Website chat widget #
The website widget puts a chat button on your site. Visitors talk to your AI agent, and a human operator can take over in the workspace inbox. Conversations, knowledge, hand-off, attachments and analytics are the same as in the other channels; see Messaging channels architecture for the shared runtime.
Add it to your site #
- In the workspace create a site: choose the project and a published agent, and list the pages that may show the chat (the allowed origins).
- Copy the public key of the site (it looks like
sw_pub_...). - Paste the snippet on every page that needs the chat, before the closing
</body>:
<script src="https://app.heysora.ai/widget/v1/loader.js" data-sora-key="PUBLIC_KEY" async></script>The same widget can be started from JavaScript with SoraWidget.init({ key: 'PUBLIC_KEY' }). Step-by-step instructions for administrators and the full developer documentation are in the Help centre (sign-in required).
Allowed origins #
A site lists the origins of the pages that may show its chat, for example https://www.example.com: scheme and host, plus a port if it is not the default. No wildcards, no paths, and https only (a TEST site may also list local test addresses with a port). The comparison is exact, so www and a sub-domain are separate entries. The browser enforces the list through the panel's frame-ancestors policy. Details: allowed origins.
Content-Security-Policy of your site #
If your site sets a Content-Security-Policy, allow the HeySora application address in script-src and frame-src. CORS configuration is not needed because your page makes no requests to HeySora; the chat panel runs in its own frame. Details: CSP requirements.
JavaScript API #
| Call | Purpose |
|---|---|
SoraWidget.init({ key, locale, position, autoOpen }) | start the widget; returns true if start-up began |
SoraWidget.open(), close(), destroy() | open or close the panel, or remove the widget |
SoraWidget.setUser(user) | pass name, e-mail, phone, your own user id and a few attributes |
SoraWidget.setContext(context) | pass page address, title, referrer, time zone, device class |
SoraWidget.on(event, handler), off(event, handler) | subscribe to ready, open, close, message, unread, conversationStarted, escalated, operatorJoined, conversationClosed, error |
setUser personalises the profile but does not verify identity: values come from the visitor's browser and can be forged, so never use them to grant access to an account or to decide anything about money or security. Page addresses are stored without their query string. Full reference: JavaScript API.
Operating modes, attachments and hand-off #
A site works in one of three modes: AI and operator (the agent answers and a person can join), operator only (every conversation goes straight to the queue) or AI only (no hand-off; when no confirmed answer exists the visitor gets a fallback text you configure). Visitors can attach files of the allowed types up to 10 MB each. The "Call an operator" button starts the normal hand-off and the visitor sees the status: waiting, specialist joined, closed. Details: modes, attachments and hand-off.
Test before you go live #
A site in the TEST environment accepts local development addresses, marks its conversations as test conversations, and can be previewed from the workspace. Use it for staging and keep local addresses out of production sites.
Security in short #
- The public key is not a secret; by itself it never opens a chat.
- The conversation token is never exposed to your page.
- Messages are shown as plain text only.
- The origin list is enforced by browsers; abuse by other clients is bounded by rate limits.
Read Security basics and widget security.
Versions and limits #
The widget is versioned under /widget/v1; changes within v1 only add capabilities. The first version does not include signed host identity, cross-tab or cross-device continuity, streaming answers, rich cards, quick replies, Markdown, WebSocket or wildcard origins. Rate limiting and the long-poll signals work inside a single application process, and automated browser tests cover Chromium only. See versioning.