Site widget

The widget puts your bot's conversation on your website. It uses the same reactions and operator dialogs as other channels.

Choose a preset

In Widget, start with the Online School or Internet Store preset. A preset copies editable defaults into the current configuration; later preset changes do not overwrite what you publish. Applying a preset can replace existing edits, so review the change before confirming.

What you can customize

The widget studio is split into seven tabs: Behaviour, Greeting and auto replies, Working hours, Contacts and privacy, Conversations, Appearance and Install. Between them you customize your brand, launcher, panel, welcome text, teaser, address-based visibility, visitor notifications, quick actions, pre-chat form, working hours and behavior. See Widget settings for every field on every tab. Quick actions are safe text actions: they send their configured text to the conversation and need matching reactions for useful automated replies.

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

The live preview shows the actual widget on desktop and mobile, against light and dark simulated pages. Check the closed, teaser, welcome, pre-chat, chat and offline states before you save. On narrow screens the widget uses a safe bottom sheet rather than unsafe fixed panel dimensions.

Allowed origins

Add the exact website origins where the widget may run. An origin is scheme, host and non-standard port, with no path:

https://example.com
https://www.example.com
https://shop.example.com
http://localhost:3000

Matching is exact. There are no wildcards; www and non-www, http and https, and each subdomain are different origins. Production origins must use HTTPS. HTTP loopback origins are available only for local development. If the current origin is not saved, initialization is rejected.

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 a saved allowed origin and a page URL on that origin, then run Check installation. Diagnostics first inspect static evidence: reachability, returned HTML, canonical loader presence, key setup and possible CSP evidence. Static inspection does not execute JavaScript, so a tag manager or SPA can make those results inconclusive.

Diagnostics then open the real page and wait for loader, bundle, initialization and mounted-widget signals. Only runtime ready confirms a successful installation. A timeout means no runtime signal was received; it can have several causes and is not a definite CSP, network or loader diagnosis.

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.

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.

Why per account and not per IP address: creating a visitor is the only anonymous browser action that generates real work for you and consumes your unique-visitor allowance. Anyone inflating it rotates IP addresses easily, and the bill lands on you. See Plans on how unique visitors are counted.

What to do if you see 429 on real traffic: it is almost always either inflation or a loop that creates a new visitor on every visit (a page clearing browser storage on load, say). Check that the visitor identifier survives navigation, and contact support: the threshold is configurable on the deployment 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

The Popups screen builds the overlays the widget shows on your site. Five layouts are available: small block, large block, inline, fullscreen and bar. The website widget and the customer SDK are two renderers of the same content: targeting decides who sees a given popup, and a popup whose device targeting excludes mobile is never served to the SDK. A variant that asks for some other renderer in its appearance settings still 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 either keeps its current blocks or references a published popup document from Content studio. A reference is captured as an exact version, so republishing the document never changes a popup that is already live. Existing popups keep working on their current blocks; nothing is rewritten for you.

Targeting narrows when a popup appears. The groups combine with AND: a visitor has to satisfy pages, behaviour, audience and device at once:

• 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 it: a maximum number of shows, a cooldown in hours, and "stop after conversion". A brand-new popup gets a deliberately conservative default of 3 shows, a 24-hour cooldown and stop-after-conversion on. Zero in "show at most" means "no limit on count", not "never": the only way to stop a popup completely is to disable it. The browser keeps a local record only to avoid a flash of a popup the server would refuse anyway; the server's own frequency state is the actual guarantee.

When several popups qualify on one page, the lower priority number wins.

Two or more variants make an A/B test, up to five, split by weight and stable per visitor. The activation check warns that a popup experiment uses the default conversion goal and a 30-day attribution window.

Buttons

A popup can carry up to five buttons, and a button can do exactly one of five things: close the popup, open the chat, open an https:// link, submit the form, or record an analytics event. There is no arbitrary callback, no JavaScript and no free-form HTTP target. Each button needs a unique lowercase technical key and a label of at most 80 characters, and a "submit the form" button is rejected on a popup that has no form. A malformed action list is dropped whole rather than partly applied, both on the server and in the widget.

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 may write into a profile property (property.<name>). Email and phone stay plain profile values. They never create or verify a channel identity, so two visitors are never merged just because they typed the same address: and a form submission alone never creates marketing consent for email.

Every submission carries an idempotency key, so a double click or a retry records one lead, not two.

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 referenced content uses blocks the website popup renderer 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.

First-release limitations

This release provides the Online School and Internet Store presets and safe text quick actions. Visitor file and image uploads, arbitrary custom pre-chat fields and broader universal widget customization are not part of this release.

Troubleshooting

1. Confirm that the snippet appears once, in the correct order, with a non-empty key.
2. Check that the page origin exactly matches a saved allowed origin.
3. Run automatic diagnostics and distinguish static evidence from runtime confirmation.
4. Review browser-console CSP messages and test without content blockers.
5. If the widget opens but gives no useful answer, configure matching reactions.
6. Contact support with the diagnostic result if the issue remains.