> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Native Chat Channel Configuration

> Configure the embeddable native chat widget from Settings → Channels → Native Chat: brand color, position, agent identity, business hours, GDPR consent, origin locking, and the install snippet for your site.

# 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](/sdks/web#chat-widget--orbitchat).

## 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](/sdks/web#chat-widget--orbitchat) 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

Read-only view of the two embed forms (HTML tag and dynamic JS), plus your widget identifiers: the widget ID, API base, and widget bundle URL. Copy from here for your site, then verify with the checklist below.

### Branding

| Field              | Runtime behavior                                                                                                                                                                                                                                      |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Primary color      | Accent color of the widget: launcher button, header bar, and message bubbles. Accepts a CSS hex value.                                                                                                                                                |
| Position           | Where the launcher sits on the visitor's viewport: bottom-right or bottom-left. Keep it away from cookie-consent banners.                                                                                                                             |
| Theme              | Light or dark widget chrome.                                                                                                                                                                                                                          |
| Agent display name | The name visitors see in the chat header.                                                                                                                                                                                                             |
| Agent avatar URL   | The avatar shown beside the agent name. Serve it over HTTPS.                                                                                                                                                                                          |
| AI agent           | When a tenant's AI agent is selected, new web-chat conversations are answered by it first and hand off to a human on escalation. Leave unset to route straight to the team. Conversations carrying an AI agent show the same display name and avatar. |
| Greeting           | The first message a visitor sees when they open the widget.                                                                                                                                                                                           |
| Away message       | The message shown outside business hours (see below) when hours are enforced. You localize both texts yourself — visitor localization is not automatic.                                                                                               |

### 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

| Field                | Runtime behavior                                                                                                                                                                                                                  |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GDPR consent toggle  | When on, the widget shows a one-time consent prompt before the first message. A declined visitor never opens the widget.                                                                                                          |
| Consent text         | The copy shown in that prompt. Tenant-authored plaintext; keep it accurate about what you collect and how long you retain it.                                                                                                     |
| Origin allowlist     | Only the listed origins may mount the widget. With no origins listed and "Allow any origin" off, the widget refuses to start sessions — a leaked widget ID cannot mint visitor tokens from a site you do not control.             |
| Allow any origin     | An explicit opt-in that unlocks cross-origin embedding. The toggle is confirmation-gated because enabling it lets any website embedding your widget ID mint visitor sessions, including a leaked ID on a site you do not control. |
| Visitor data erasure | Every visitor's widget carries a "Delete my data" action that scrubs the visitor-side record (name, email, phone, user agent). The visitor's messages stay in your inbox; only the visitor-side personal data is purged.          |

## 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](/guides/inbox-setup).

## 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

| Symptom                                 | Likely cause                                                                              | Fix                                                                                                                                                                                                          |
| --------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Widget does not render at all           | Channel disabled, wrong/missing public key, or snippet placed on a page it never loads on | Check the **Enable widget** toggle in the page header, confirm the snippet widget ID/public key matches the Install tab, and place the snippet in `<head>` or just before `</body>` of the page you test on. |
| Widget renders but sessions are refused | Origin not on the privacy allowlist and "Allow any origin" is off                         | Add the page's origin to the **Privacy & GDPR** allowlist, or intentionally enable the open-surface toggle.                                                                                                  |
| Branding changes do not show up         | The widget caches config until the next bootstrap                                         | Hard-refresh the embedded page (or wait for the visitor's next page load) after saving in the console.                                                                                                       |
| GDPR consent copy not shown             | Consent toggle off, or saved before the text field was filled                             | Re-check **Privacy & GDPR → GDPR consent** is on and the consent text field is non-empty, then hard-refresh the page.                                                                                        |
| Consent text shows but is wrong         | Console edits override constructor defaults                                               | Remove the stale `greeting`/GDPR-relevant option from your embedded `OrbitChat` constructor, or accept that the console value wins by design.                                                                |
| Away message never shows                | Business hours disabled or the schedule left empty                                        | Enable **Business hours** and save a schedule; the greeting never falls back to the away message while hours are disabled.                                                                                   |
