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 AI answers "that falls outside my knowledge" to everything

If this website's source selection is set to Selected sources without a single collection ticked, the agent finds no article at all. An empty selection means nothing, not everything, and there's no warning that your selection is empty.

The tell: on your Help Center itself the same question works fine, and it only fails on that one website. Check the source selection of that link. See Placing the chat agent on your own website.

The customer is recognised, but questions about orders don't work

If you work with a connection to your ERP or webshop, Sarrai does the lookup on the server. If that system doesn't answer or drops out for a moment, the visitor counts as unverified and the chat simply carries on. Nothing appears in the widget and you get no notification.

So the symptom is indirect: customers suddenly get the contact form again and their questions about orders go unanswered, while the chat otherwise looks normal. If a visitor does see their name but gets no access to their orders, look at the default relation in your ERP. Sarrai uses only the relation marked as default there, and deliberately grants no access when in doubt.

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