Site widget
Add chat to your site, set up the greeting and verify message delivery. Installation code, allowed sites and troubleshooting.
本页内容
The widget adds a chat button and conversation window to your website. Visitors ask questions, the bot replies through reactions, and an operator can continue the conversation in the dashboard.
For your first installation, follow the Widget quickstart. This page has the detailed settings and technical installation reference. If a developer adds the code, send them the sections on allowed sites, the installation snippet and diagnostics.
Choose a preset
In Widget, choose a starting preset: Online school or Internet store. You can change its text, colors and behavior. Later updates to a preset will not change your published configuration. Applying a preset now may replace your edits, so review the changes first.
What you can customize
The widget studio has seven tabs: Behaviour, Greeting and auto replies, Working hours, Contacts and privacy, Conversations, Appearance and Install. They cover your brand, chat button, panel, greeting, short invitation, page visibility, visitor notifications, quick actions, pre-chat form and working hours. See Widget settings for every field. A quick action sends its configured text to the conversation and immediately runs the reaction selected for it. Link a reaction to each button so the visitor gets an answer.
The form can collect name, email, phone or order number. Email and phone are unverified profile enrichment only: they do not verify identity, merge people or create marketing consent. Working hours use a timezone, weekly intervals and exceptions. They describe the configured schedule, not live operator presence.
The short invitation next to the launcher can sit beside it or above it.
Outside working hours the widget can post an auto-reply of your own into the conversation. It is an ordinary dialog message rather than a caption in the header: the visitor sees it, the operator sees it in their inbox, and it stays in the conversation history. It is sent once per closed period, not on every visitor message.
Preview before publishing
Preview the widget on desktop and mobile against light and dark backgrounds. Check the chat button, the short invitation beside it (teaser), greeting, pre-chat form and conversation. Check the message outside working hours separately. On a narrow screen, the conversation opens from the bottom and fits the available space.
Allowed origins
In Allowed sites, add the addresses where the chat should appear. The technical term origin means the protocol, domain and port if it is non-standard, without a page path. For https://example.com/catalog, add https://example.com:
https://example.com
https://www.example.com
https://shop.example.com
http://localhost:3000
The address must match exactly. www and non-www, http and https, and different subdomains count as separate addresses. A published site needs HTTPS. HTTP is allowed only for development on your own computer, such as localhost. The widget will not start on an address missing from this list.
This list restricts browser embedding. It is not a replacement for server-side authorization or abuse controls.
Install the snippet
Open Widget → Install, copy the complete snippet, and add it once to the shared template of every page where the widget belongs, preferably before </body>:
<script>
window.mybot = window.mybot || {}; window.mybot.key = "eu-1a2b3c4d-...";
</script>
<script async src="https://getmybot.dev/loader.js"></script>
Keep the key assignment before the loader and keep async. Do not split the snippet. Duplicating it is unnecessary but harmless: the widget mounts once, and window.mybot = window.mybot || {} keeps an already-installed track/identify intact. A CMS footer field or tag-manager container is suitable when it is included once per page.
The install key is a public identifier, not a password. It may appear in page source and cannot sign in to the dashboard, read conversations, export people or change bot settings. If it must be replaced, ask support; the old snippet then stops working and must be updated.
Automatic diagnostics
Choose an allowed site and a page on it, then click Check installation. First, the system checks whether the page opens and whether its source contains the widget loader and key. This step does not run JavaScript. If a tag manager or single-page app (SPA) adds the code later, the first result may be inconclusive.
Diagnostics then open the page in a browser and check whether the widget loads. Only The widget is installed and running confirms a successful installation. If the check times out, the widget did not report readiness. Look at the check details and browser console for a site, network or browser restriction.
CSP, tag managers and blockers
If your site has a Content Security Policy, allow the host shown next to the snippet to load scripts and receive widget network requests. Browser-specific CSP features can make static evidence inconclusive, so use the runtime result and the browser console together.
Tag managers and SPAs may inject the snippet after the original HTML is returned. This can leave static inspection inconclusive even when the runtime probe succeeds. Also test in a private window with extensions disabled: content blockers can remove or prevent the widget.
Visitors, drafts and history
On first launch, the widget stores an anonymous visitor ID in that browser. Returning visitors recover the same bot-scoped identity, safe conversation history, local draft, form completion and dismissal state. A different browser or device, or cleared site data, starts a new anonymous visitor.
The widget is isolated from your page in a closed Shadow DOM. Its styles do not leak into the host page and your CSS does not restyle it. The container does not intercept page clicks outside the launcher and panel.
Connecting VK
If VK linking is available for your project, connect a VK community channel and enable its https://vk.me/community_name or https://vk.me/club<ID> link in the widget settings. The link must match the connected community; a single ref_source parameter is allowed. See Widget settings for channel buttons.
- The visitor selects VK in the widget, opens the community and sends it a message, then returns to the widget.
- Once the account is found, the widget shows a masked account identifier and the consequences of merging. The visitor explicitly selects Connect. After confirmation, conversation history and previously linked channels are retained.
- If confirmation does not appear or the attempt expires, the visitor can retry. Opening VK through an ordinary link does not merge profiles.
If the widget cannot confirm that the visitor controls the previous conversation, it offers to verify a previously verified email address when available, or to start a new chat. A new chat does not carry over the previous history. The visitor can also open VK without linking. If linking is unavailable or the link does not match the connected channel, the button remains an ordinary link.
Connecting Instagram
Linking is available only after Meta confirms that the connected Page is subscribed to referral and postback events. For an account connected earlier, you may need to select it again or reconnect it to check the subscription.
If linking is available for your project, add the connected Instagram account's https://instagram.com/username link in widget settings. The visitor opens Instagram from the widget and returns to it. If the account is found, the widget shows a masked identifier and the consequences of merging; linking happens only after the visitor explicitly selects Connect.
For a new conversation, Meta requires configured icebreakers and a tap on one of them. Delivery of linking data is not guaranteed, including in existing conversations. If linking is unavailable or the attempt fails, the visitor can open the ordinary link without linking. Opening it alone does not merge profiles.
Connecting Facebook Messenger
When linking is available, add the connected Page's https://facebook.com/school.page link in widget settings. For new conversations, configure the Get Started button in Messenger. The visitor opens Messenger from the widget, taps Get Started in a new conversation, and returns to the widget. If an account is found, the widget shows a masked identifier and the consequences of merging. Linking happens only after explicit confirmation.
Meta warns that referral data may not be delivered to some Messenger for Android users or geographically restricted Pages. When linking is unavailable or an attempt fails, the ordinary link remains available and does not merge profiles by itself. See Meta's m.me documentation.
A burst of new visitors
The appearance of a new visitor is rate-limited, separately for each account: roughly two new visitors per second on average, with a burst allowance of about 500 in a row. For an ordinary site that is generous: it is on the order of 170,000 new visitors a day.
When the allowance is spent, widget initialisation for a new visitor answers 429 with a Retry-After: 60 header, and the widget tries again later. Visitors already known are unaffected: their dialogs, history and operator replies keep working as usual. The limit is deliberately shaped to slow the arrival of new conversations rather than to switch off the ones already in progress.
The limit applies to your account, not each IP address. Creating a visitor is the anonymous browser action that creates work for your account and consumes your monthly allowance of unique visitors. Someone trying to inflate that count can change IP addresses easily. See Plans for how visitors are counted.
If new visitors get a 429 response during normal site use, check whether their visitor ID survives navigation. For example, a site that clears browser storage on every load can make one person look like many new visitors. If the cause is unclear, contact support: the threshold is configurable on the platform side.
Linking a visitor to your own user
When a visitor is signed in to your site, wait for mybot.identify() before calling it. The loader and widget bundle are asynchronous, and there is no pre-load command queue. Start this after your own signed-in user is known:
async function identifySignedInVisitor() {
const deadline = Date.now() + 3_000;
while (Date.now() < deadline) {
const identify = window.mybot?.identify;
if (typeof identify === "function") {
identify(async (visitorId) => {
const response = await fetch("/mybot-sign", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ userId: currentUser.id, visitorId }),
});
return response.json(); // { userId, signature, expiresAt }
});
return;
}
await new Promise((resolve) => window.setTimeout(resolve, 50));
}
console.warn("GetMyBot identify() was not ready; visitor remains anonymous.");
}
void identifySignedInVisitor();
This polls for at most three seconds, then stops rather than calling a missing API or retrying forever. In the timeout, callback or signature-failure case, the visitor continues anonymously. The callback receives the asynchronously created visitorId. Send it only to your authenticated backend; do not log it, forward it or put it in client-side analytics. Your backend returns { userId, signature, expiresAt } and computes the signature, never the browser:
signature = hex(HMAC-SHA256(key: secret, message: userId + "\n" + visitorId + "\n" + expiresAt)).slice(0, 32)
The separators are real newline characters. expiresAt is a Unix timestamp in seconds, must not be in the past and must be no more than 24 hours ahead. Bind the signature to the specific visitor and create it immediately before returning it.
Secret reveal and rotation
The identify() secret is in Widget settings after the web channel is connected. Revealing it does not invalidate it; show it only when your backend needs it, clear it from the screen afterwards, and clear your clipboard yourself. The platform cannot reliably clear a browser clipboard.
Rotate the secret only when ready to update your backend: rotation immediately invalidates the old secret and has no overlap period. It affects only identity linking; existing chats, the install snippet and allowed origins continue to work.
Popups and lead forms
Use Popups to set up windows that appear on your site. Five layouts are available: small block, large block, inline block, fullscreen window and bar. The site widget and the customer SDK in an app can show the same content. Display rules determine who sees a popup. For example, a popup that excludes mobile devices will not appear in the app. A variant with an unsupported display method cannot be activated.
The template gallery starts you from a ready layout: one per layout, plus Lead capture (a large block with an email field, a consent checkbox and a submit button) and Chat invitation (a small block with an "open chat" button).
Content. A popup variant can use its own blocks or reference a published Popup document from Content studio. The reference points to a specific version, so publishing a new document version does not change a popup that is already live. Existing popups keep their current blocks unless you change them.
Targeting, or display rules, determines when a popup appears. The visitor must satisfy the page, behavior, audience and device rules at the same time:
- Pages. Up to 20 include and 20 exclude patterns. A pattern is an absolute
http(s)URL, either exact or ending in a single*for a prefix match; the query string is ignored. An empty include list means any page, and an exclude match always wins over an include match. - Behaviour. A delay in seconds, a scroll depth of 0-100 %, exit intent, and a minimum visit number.
- Audience. Up to 20 segments; the visitor must belong to at least one of them, not all. Segments are resolved on the server, so the browser never learns the segment definition: a visitor who does not qualify simply never receives the rule.
- Device. Desktop, mobile, tablet; nothing selected means every device.
Page and behaviour rules are evaluated in the browser, on the rule the server already decided to send.
Frequency limits how often one visitor sees a popup: set the maximum number of displays, a pause in hours and whether to stop after a target action (conversion). A new popup defaults to 3 displays, a 24-hour pause and stopping after conversion. Zero in “show at most” removes the display-count limit. To stop the popup entirely, turn it off. The browser keeps a local marker to avoid briefly showing a popup the server would reject; the server makes the final frequency decision.
When several popups qualify on one page, the lower priority number wins.
With two to five variants, you can compare them in an A/B test. Visitors are assigned by the configured weights and see the same variant on later visits. Before activation, the check warns that the test uses the default conversion goal and counts results for 30 days after display (attribution window).
For a standard popup, a target action is recorded when a visitor clicks a link or the open-chat button, or successfully submits a form. Opening chat does not mean a message was sent or a payment made. A custom script can separately report a target action using mybotPopup.track.
Buttons
A popup can have up to five buttons. Each performs one action: close the popup, open chat, follow an https:// link, submit a form or record an analytics event. Arbitrary callbacks or JavaScript and HTTP links are unsupported. Every button needs a unique lowercase technical key and a label of at most 80 characters. A “submit form” button requires a form. If the button list is invalid, the server and widget reject it in full rather than applying part of it.
Lead forms
A form collects up to 12 fields. Field types are short text, email, phone, choice list, checkbox and hidden. Every field has a unique lowercase technical key, and keys that look sensitive are refused: anything containing password, passwd, pwd, token, secret, card, cvv, cvc, government, passport, ssn, authorization or cookie, underscores ignored, so pass_word is refused too. Do not ask for passwords or payment data in a popup.
Values are bounded: a maximum length of at most 400 characters (an email field is 64-254), at most 50 unique options of at most 120 characters each in a choice list, a phone in the form + followed by 7-15 digits, and true/false for a checkbox. A hidden field always takes its value from the saved definition on the server, never from the browser, even when the browser sends the same constant. A value for a field the form does not declare is rejected outright. You can require an explicit consent checkbox before the form can be submitted.
A field can write to a profile property (property.<name>). Email and phone remain ordinary profile values. They do not create or verify a contact in a channel. Two visitors are not merged just because they entered the same address, and an ordinary form submission alone does not grant consent to marketing emails.
To accept an email subscription, add a required email field and a separate checkbox clearly stating that the visitor agrees to receive updates. Enable Subscribe to email updates and select both fields. Data-processing consent is separate from subscription consent. If the address has not yet been verified, the visitor can request and enter a code directly in the popup. Verification of address ownership alone is not consent to receive email updates.
For a new or renewed subscription, a separate confirmation email is sent after the form is submitted. The visitor must follow its link and confirm on the resulting page. Only then does the subscription become active and $email_subscribed fire. If the confirmation could not be prepared, the form shows a message and offers a retry. Queuing the email does not guarantee delivery. An unchecked box does not subscribe; an already active subscription does not emit another event. A complaint or hard suppression is not cleared by subscribing.
A double click or retry creates one lead, not two. Each submission has a unique idempotency key to prevent duplicates.
Before a popup can be activated
Activation runs a server-side check and refuses while any of these is true:
- the website widget is not connected, is disabled, or has no allowed origin;
- a page targeting rule uses an origin that is not in the widget's allowed origins;
- a selected segment no longer exists or is not ready;
- the referenced content version is missing, unpublished or archived;
- the content uses blocks the site popup cannot show;
- the form or button configuration is invalid;
- the variant weights of an A/B test cannot be allocated.
The check runs whenever you save a popup with "show to visitors" on. A blocked activation comes back as 400 with the full report; unacknowledged warnings come back as 409 until you tick the acknowledgement box. A popup you keep switched off can be saved with any of the above still unresolved.
The most common warning tells you a variant still uses legacy blocks and should move to published popup content before the next major edit.
Browser notifications
The widget can also ask a visitor for permission to send browser notifications, and Web Push is configured on this same screen. It needs one step you cannot do from the dashboard alone: the service worker file has to be served from your own domain. The setup, the payload limits and what browser push cannot do yet are on Browser push.
Available settings
There are ready-made presets for online schools and internet stores. You can adapt either one to your site; there is no separate universal preset. Quick actions send text and run the selected reaction. Visitors can attach files and images when attachments are enabled under Conversations in the message-input settings. The pre-chat form has a fixed set of fields; arbitrary custom fields cannot be added yet.
Troubleshooting
- Confirm that the snippet appears once, in the correct order, with a non-empty key.
- Check that the page origin exactly matches a saved allowed origin.
- Run automatic diagnostics and distinguish static evidence from runtime confirmation.
- Review browser-console CSP messages and test without content blockers.
- If the widget opens but gives no useful answer, link a working reaction to each quick-action button.
- Contact support with the diagnostic result if the issue remains.
Tracking rules
Create a rule in Tracking to turn a page view, click, element visibility or form interaction into a named event. Set a stable event name, select the trigger, and restrict pages where needed. Element triggers use a CSS selector, for example #checkout-button; a page view does not need one.
Extractions add event properties from the URL, an element attribute or property, a query parameter, a form field, or a constant. Test the rule with the inspector and event debugger before enabling it. Do not collect passwords, tokens or other secrets in event properties.
Custom JavaScript popup
The Custom script layout runs the JavaScript you supply instead of the standard popup card. The standard block, form and appearance controls do not apply. Targeting and frequency still determine when it may run.
The script builds and removes its own interface. Use mybotPopup.track('converted') to report a conversion and mybotPopup.close() when finished; remove your own DOM elements as part of closing. Test the script on your site before enabling it for visitors.
To count viewable impressions in the report, call mybotPopup.observe(element) after adding the popup to the page, passing the DOM element containing the popup. An event is recorded when at least half the element stays within the viewport for two consecutive seconds in a visible tab. This does not prove the content was read. Historical impressions are not backfilled.
Won deals after an impression
The popup report shows the amount and number of first recorded won CRM deals in the selected period, grouped by UTC day of the first win and by currency. A deal is included when the associated known person saw this popup within the 30 days before the win. Duplicate events for the same deal are not added again. The CRM must provide the person association, amount and currency.
This is an association with an impression, not evidence of payment or causation. One deal can appear in reports for several popups. Historical CRM events without a connection ID are excluded; later updates are also excluded if an older deal cannot be associated unambiguously with a connection. Viewing financial amounts requires analytics.revenue; a PAT also needs analytics:read.
Confirmed payments after an impression
The report separately shows confirmed payments in the selected period when the payment is linked to a known visitor who saw the popup no more than 30 days before payment. Only payments accepted through MyBot are included, for visitors unambiguously linked on the website or in Telegram, VK or WhatsApp. Anonymous payments and those without such a link are excluded.
Payments taken on your website or through an external payment system without MyBot are not included, even if the visitor is known. Won CRM deals are shown in their own section and are not treated as confirmed payments.
The daily breakdown groups by payment day in UTC and currency, showing the number of payments, gross amount, current refunded amount and amount after refunds. A refund is attributed to the original payment day, not the refund day, so historical daily figures may change. Currencies are separate. Do not add deal and payment amounts together: the same purchase can appear in both.
Financial data requires analytics.revenue; a PAT also needs analytics:read. An association with an impression does not prove the popup caused the purchase. A viewable impression does not prove the content was read.