Troubleshooting

"This agent doesn't take chat." The agent you picked has Chat switched off in its Channels. Switch Chat on and publish that agent, or point the widget at a different one. An agent with nothing published yet is accepted, so this only comes up for an agent that is already answering.

Nothing appears on my site

The widget renders nothing at all — not even a launcher — when it is not authorized, because a launcher that opens onto an error is worse for your visitors than no launcher. Open your browser's developer console on the page and look for a line starting [spark-chat], which names the reason.

Work through these in order:

The origin is not on the list. The most common cause by far. The Origin your browser sends must match an entry exactly — https://www.example.com and https://example.com are different origins, and so are http:// and https:// versions of the same host. Check the address bar against your Allowed Origins list.
The Allowed Origins list is empty. A widget with no origins is authorized nowhere, which is also how you take a widget off a site: remove the origin.
The key does not match. Copy the snippet again from the Install section rather than editing an old one by hand.
The script did not load. Look for the request to chat.tandemcx.ai (or chat.spark.sharpencx.com, if that is the host your snippet names) in the Network tab. If it is blocked, check your Content Security Policy — see Installing.
You are on a staging environment with a production snippet, or the reverse. The widget derives which Tandem environment to talk to from where the script itself was served, so a snippet copied out of the wrong dashboard asks the wrong environment about a key it has never heard of. Copy the snippet from the dashboard for the environment you are testing.

The editor's preview chat cannot tell you which of these it is, and a working one does not rule any of them out. It runs from Tandem rather than from your site, so it never uses the key, the origin list, or the script — everything on this list. What it does rule out is the agent itself: if the preview answers, the problem is the installation, and the origin list is where to look first.

The launcher appears but says the assistant is unavailable

The widget loaded, so the key and origin are fine — something behind it is not. The visitor-facing message is deliberately the same for every cause; the specific reason is in your Tandem logs. The usual ones:

The agent was deleted or re-pointed. Open the widget in Tandem: the Agent field will be empty or naming something unexpected.
The agent's model credential is missing. An agent on a keyed vendor (OpenAI, Gemini) needs that vendor's API key configured for your organization.
The agent has PII redaction on with a non-Bedrock model. That combination is refused rather than run without protection. Either switch the agent to a Bedrock model or turn PII redaction off.

The editor's preview chat is worth trying here, unlike the section above: it reaches the agent the same way a visitor's message does, so a cause on this list fails there too — and it fails while you are looking at the field that causes it.

A visitor was told there were too many messages

That is the rate limit. It is per visitor, per conversation, and per widget, and it resets within a minute. It exists because each message costs a model call and possibly a call to your own integrations — the public snippet has no secret in it, so a limit is what caps the cost of abuse.

If real traffic is hitting it, that is worth telling us about rather than working around.

There is a second, much looser limit on how often one visitor may load the panel's name and avatar. A page that opens the widget once per visit will never see it; a page that re-mounts the widget in a loop will. It also resets within a minute.

The reply shows asterisks, pipes, or hash marks

The agent is writing markdown. The chat panel renders plain text, so markdown syntax appears literally. Add a line to the agent's system prompt telling it to answer in plain prose with blank lines between paragraphs and no markdown formatting.

The conversation resets when I reload

A reload should NOT reset it, and neither should a new tab or coming back the next day — the conversation lives on our servers and the browser keeps only the ids needed to ask for it. Three things do reset it, all expected:

A different browser, device, or private window. The visitor is identified by their browser, not an account, so there is nothing to carry across.
The visitor cleared their site data, which removes the ids.
A browser blocking storage for embedded content. With nowhere to keep the ids, every page load is a new visitor. The chat still works; it just does not remember.

A conversation stops accepting new messages after 24 hours of inactivity, and after a long run of messages. The visitor can still read it, but replying starts a new one.

The chat covers something important on mobile

On a phone-sized screen the chat fills the display once opened. That is intentional. If the launcher is what collides with something (a cookie banner, a back-to-top button), move it with the widget's Position setting — bottom left or bottom right, in the Launcher section of the widget's configuration — or lower it behind your own element with data-spark-chat-z-index.