The chat widget puts your agent in the corner of your website, where visitors can type to it. It answers from its chat prompt and any knowledge bases attached to it, and each conversation shows up in the portal under Conversations, on the Chat tab.
Web chat is turned on per workspace. If your agent's page in the portal has no Chat tab, email support@telvana.com and we'll turn it on.
1. Write the chat prompt
On the agent's Chat tab, edit Chat Prompt. It's separate from the agent's voice prompts, so you can write for a reader rather than a listener. Attach knowledge bases on the same tab if the agent should answer from your documents.
You can also read and replace the chat prompt through the API with GET and PUT /agents/{agentId}/chat-prompt; see the Agents reference.
2. Allow your sites
Under Allowed Origins, add each site where the widget will run. An origin is the scheme and host, plus the port if there is one, with no path and no trailing slash:
https://www.example.com
https://example.com
https://help.example.com
https://example.com and https://www.example.com are different origins, so add both if your site answers on both. The widget only works on the origins listed here. It loads nowhere until you add the first one, and removing every origin turns chat off for the agent.
3. Generate a widget key and copy the snippet
Under Widget Key, choose Generate widget key. The portal then shows the snippet for this agent, with the key filled in. It looks like this:
<script
src="https://telvana-chat-widget.s3.us-west-1.amazonaws.com/widget.js"
data-widget-key="YOUR_WIDGET_KEY"
data-color="#0F172A"
data-position="br"
data-agent-name="Ava"
async
></script>
Paste it into your site's HTML just before </body>, on every page where the chat should appear. If your site uses a tag manager or a site builder, add it as a custom HTML or script tag.
The attributes you can change:
| Attribute | What it sets |
|---|---|
| data-widget-key | The agent's widget key. Required: without it the widget doesn't appear |
| data-color | The widget's accent color, as a hex value |
| data-position | br for the bottom right corner, the default, or bl for bottom left |
| data-agent-name | The name the widget shows for your agent |
The widget key isn't a secret. It sits in your page's HTML where anyone can read it, which is why the allowed origins matter: they stop other sites from using your key.
Changing the key
Regenerate under Widget Key replaces the key and the old one stops working immediately. Every page still using the old key loses its chat until you update the snippet, so regenerate only when you can update your site straight away.
Reading chats
Chats appear on the Chat tab under Conversations in the portal. A conversation stays open while the visitor keeps writing and ends 30 minutes after their last message. Its summary and outcome appear in the portal shortly after that.
If the widget doesn't appear
- Check that the page's origin exactly matches an allowed origin, including www and https.
- Check that the snippet has the agent's current widget key, especially after a regenerate.
- Check that the script tag made it into the published page, not only a draft or a staging copy.
If the widget appears but the agent stops replying, email support@telvana.com with the page address and the time it happened.