Skip to main content

​
Native Chat Channel Configuration

Native chat is a first-class channel in the dashboard: an embeddable widget that visitors open on your site and that lands in the same omnichannel inbox as every other channel. This guide covers the operator side of the widget — the per-tenant configuration you manage under Settings → Channels → Native Chat. For the code side (embedding via the Web SDK), see the OrbitChat constructor in the Web SDK reference.

​
The install → configure loop

Two pieces have to agree for the widget to work: the snippet on your site, and the saved configuration for your tenant.
  1. Embed the snippet. The Install snippet tab shows two forms of the embed — a single <script> tag you paste into <head> (or just before </body>) on every page where the widget should appear, and a dynamic JS loader for sites whose content-security policy forbids third-party script tags but permits inline scripts. Both carry your widget ID so the widget runtime knows which tenant it belongs to. The Web SDK OrbitChat module does the same mount programmatically.
  2. Configure in the console. Open Settings → Channels → Native Chat and work the tabs: Branding, Business hours, Pre-chat form, Sign-up forms, Agent trust, and Privacy & GDPR. Every change is saved against your tenant and applies to the widget on the next page load of your site.
  3. Enable the channel. The header of the page exposes an Enable widget / Disable widget toggle. A disabled widget does not render for visitors regardless of what is configured.
Constructor options passed to OrbitChat in code (for example a position or a greeting) are fallback defaults. When you configure the same fields in the console, the console values win — so your webmaster’s embedded defaults are overridden by whatever your operators set in the dashboard.

​
What each console field controls

The page is organized into tabs. This is what each one actually changes at widget runtime.

​
Install snippet

Open Install snippet and copy the generated embed for the tenant. The tab provides a <script> tag for a normal site and a dynamic JavaScript loader for sites that need to load the widget from their own script. Keep the generated widget ID, bundle URL, and API base together; do not substitute a different tenant’s values or hand-edit the runtime URL. Add the snippet to the shared site layout so it loads on each page where chat should be available, either in <head> or immediately before </body>. For a single-page application, mount the Web SDK’s OrbitChat instead; see the Web SDK reference. After publishing, open the page in a private browser window and verify the widget loads from the configured site origin. If the launcher is missing, check the browser console for a blocked script or connection before changing the snippet.

​
Branding

​
Business hours

A per-day open/close schedule plus a timezone in IANA form (for example America/Los_Angeles). A day toggled off is treated as closed. When the schedule is left disabled or empty, the widget is always-on and never shows the away message. When enabled, visitors who open the widget outside the schedule see the away message configured in Branding.

​
Pre-chat form

The routing and qualification fields a visitor fills before a conversation can start — such as name, email, and reason. Use them to route to the right queue or to pre-qualify before a human or AI agent picks up.

​
Sign-up forms

No-code list-growth popups, flyouts, inline embeds, and exit-intent teasers, with A/B variants and a per-field mapping of collected answers onto contact properties, plus a consent block.

​
Agent trust

Tenant-owned trust policy for third-party AI agents (Web Bot Auth / RFC 9421): which Signature-Agent / JWKS directories you trust, and whether a verified request from one is allowed, denied, or rate-capped. Only enable directories you deliberately operate with.

​
Privacy & GDPR

​
Role gates

  • Owners and admins can read and write every field on this page. The page refuses to render for other roles.
  • Everyone in the tenant can view the install snippet so a webmaster who is not an admin can still copy the embedded tags; the mutate-only controls stay gated to owner/admin.
Changes are tenant-scoped: they apply to your tenant’s widget configuration only, and every save is recorded in the audit trail so a branded-color or consent-copy change is attributable.

​
Where widget traffic lands

Every conversation the widget opens is routed into the Inbox as a web_chat conversation, alongside your SMS, email, and voice interactions. Operators work it from the same views they already use. The settings page links directly to the web-chat inbox filter from its Open native-chat inbox action. For inbox setup, assignment, and routing rules, see the Inbox setup guide. To send chats to a particular team, first create a digital queue under Inbox → Digital Queues, then select that queue in Settings → Channels → Native Chat → Route to inbox queue. If you leave the queue unset, the conversation uses the default inbox route. Routing rules can then assign matching conversations to an agent, team, or round-robin pool; test a rule before enabling it. See Digital queues, Routing rules, and Native Chat channel settings.

​
Style and collect visitor details

Under Branding, set the primary hex color, light or dark theme, launcher position, agent display name, avatar URL, greeting, and away message. The launcher sits at the bottom-right or bottom-left; choose the side that does not cover your site’s consent controls or other fixed actions. The documented branding controls do not include an uploaded custom launcher icon, so use the built-in launcher rather than relying on an icon override. Branding and copy changes appear on the next widget bootstrap. Use Pre-chat form to collect the fields your team needs before routing, such as name, email, and reason. Keep the form short: require identity only when the team needs it to handle the request, and enable Require pre-chat form before routing in Native Chat channel settings when the form must be completed before assignment. The same settings page controls whether anonymous visitors may join and whether a returning visitor resumes an open conversation.

​
Proactive engagement and opening behavior

A visitor can always open the widget from its launcher. If you want to invite visitors before they click, configure a tenant-owned conversation flow and its proactive engagement triggers; use the page context and eligibility conditions relevant to your site, and test the published flow on staging. Keep the launcher available so a visitor can dismiss an invitation and return later. Do not assume a trigger opens a chat for every visitor: the flow and its conditions determine whether the widget prompts, asks pre-chat questions, or proceeds to routing. See Conversation flows.

​
Abuse controls and site security

Treat the widget ID as public: it identifies the widget but is not a secret or an access control. In Privacy & GDPR, add each exact site origin that should host the widget, including scheme and port where applicable. Leave Allow any origin off unless you intentionally need unrestricted embedding. An empty allowlist with that option off prevents sessions from starting. The Native Chat page does not expose a numeric per-visitor message-rate setting. For a public widget, require only the identity fields your workflow needs, route chats to a monitored digital queue, and watch for unusual volume. If traffic is abusive, tighten the tenant’s origin allowlist or disable the widget while you investigate; do not rely on a hidden widget ID to block use. If your site uses a Content Security Policy, allow the generated widget bundle host in script-src and the API host shown in the Install snippet in connect-src; allow any avatar host you use in img-src. Add only the exact hosts required by the generated snippet and your branding assets. Do not relax CSP with a wildcard or unsafe-inline just to make the embed work. If the browser reports a CSP violation, use the blocked URL in the console to identify which directive needs that host.

​
Widget language

Greeting, away message, consent copy, and pre-chat labels are tenant-authored; the widget does not automatically translate these strings for each visitor. Write and review the text in the languages your site supports. If you serve localized pages, use the matching tenant-owned widget copy for that audience and test the consent and form text as well as the conversation greeting. Keep consent wording aligned with the visitor data your tenant collects and retains.

​
Verify the wiring

Use this checklist on a staging site before you let the widget onto production traffic:
  1. Embed the snippet from Install snippet on a staging page.
  2. Open the page and confirm the launcher renders in the position you configured (bottom-right by default).
  3. Open the widget and check the header shows your agent display name, avatar, and greeting.
  4. If you enabled business hours, open the page outside the schedule and confirm the away message appears.
  5. If you enabled GDPR consent, confirm the consent prompt appears before the first message and that declining it leaves the widget closed.
  6. Send a test message from the widget and confirm it appears in Inbox filtered to the web_chat channel.
  7. Confirm the origin you embedded on is in the privacy allowlist (or that “Allow any origin” is intentionally on).

​
Troubleshooting