Embedding the chat agent: troubleshooting

Short answer: if the chat button doesn't appear, the exact address of your website is usually missing from the list of allowed sites. The scheme (https://), the (sub)domain, and the port all have to match precisely. The widget only shows your visitor a generic message; the real reason is in the browser's network tab.

The chat button doesn't appear at all

This is by far the most common complaint, and almost always a matter of the allowlist:

• The website address isn't (exactly) in the list Websites where chat may appear. Scheme, (sub)domain, and port must match exactly.
• The website runs on http:// (only https:// is allowed, except localhost for testing).
• The link or the site key is disabled.
• Your plan doesn't include the website chat (it's a paid feature).

"Chat failed to start"

The startup request failed. Usually:

• Too many requests in quick succession, for example a page that reloads the chat in a loop.
• The subscription is no longer active, or your plan doesn't include the chat.

"Sending failed. Try again."

Sending a message failed:

• Too many messages in quick succession.
• The subscription is paused, the cap has been reached, or it has been cancelled. Then Sarrai goes fully silent and the visitor only sees this generic message, not "subscription expired".

The visitor stays "anonymous" while you expected them to be recognised

Did you place the chat behind a login and expect Sarrai to recognise the signed-in visitor automatically? Then the trusted identity didn't come through: the token is expired or invalid, or you renewed the identity secret without updating the other side. The chat keeps working, but without a recognised identity.

The fastest way to find the real reason

Because your visitor always gets a generic message, the best thing is to open the network tab of your browser yourself on the page with the chat. The rejected request names the real cause in an X-Sarrai-Embed-Reason header (for example that the origin isn't allowed or that the feature isn't in your plan).

Also searched as

"why don't I see my chatbot", "chat doesn't load on my website", "the widget does nothing", "chat button missing"

See also

• Placing the chat agent on your own website