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

# Settings: Native Chat channel toggles

> Walk through every toggle on the native-chat channel settings page at /settings/channels/native-chat — the pick-up rules, session expiry, identity policy, bot-or-human first-pick-up, and downstream inbox routing controls that govern how web_chat conversations enter your workspace.

# Settings: Native Chat channel toggles

The **Native Chat** channel page in Orbit (`/settings/channels/native-chat`) is the tenant-owned configuration surface for the embeddable widget listed under **Settings → Channels → Native Chat**. This guide covers the channel-level toggles that control how `web_chat` conversations enter your workspace — separate from the widget branding, install snippet, and pre-chat form covered in the [Native Chat channel configuration guide](/guides/native-chat-widget-channel-config).

## What native chat is on Orbit

Native chat (`web_chat` in the API) is a first-party widget that visitors open on your website and that lands conversations in the same omnichannel inbox as your SMS, WhatsApp, and voice interactions. It is distinct from social chat channels (Messenger, Instagram, Telegram) and from email — it is a loopback channel where Orbit owns both the widget runtime and the delivery surface.

Two configuration pages govern the widget:

* **Settings → Channels → Native Chat** (this page) — channel-level toggles: pick-up rules, session expiry, identity policy, bot-or-human first-pick-up, and downstream inbox routing.
* **The inline channel detail tabs** (Branding, Business hours, Pre-chat form, etc.) — widget-level configuration. Those are covered in the [Native Chat channel configuration guide](/guides/native-chat-widget-channel-config).

## Toggle matrix

The page groups channel-level controls into a compact two-column form. Each toggle is a tenant-owned setting persisted at `GET/PUT /api/v1/channels/native-chat`.

### Pick-up rules

| Toggle | What it controls |
| - | - |
| **Auto-accept new conversations** | When on, incoming `web_chat` conversations are automatically accepted into the inbox without waiting for an agent to manually pick them up. When off, conversations queue as unassigned until an agent claims them. |
| **Auto-assign to least-busy agent** | When on (requires Auto-accept), new conversations are routed to the agent with the fewest open conversations. When off, conversations stay in the unassigned queue after auto-accept. |
| **Require pre-chat form before routing** | When on, the visitor must complete the pre-chat form (name, email, reason) before the conversation enters the inbox routing pipeline. When off, the conversation enters routing immediately on first message — even if the visitor has not identified themselves. |

### Session and expiry

| Toggle | What it controls |
| - | - |
| **Session expiry window** | The number of minutes of visitor inactivity after which the widget session closes and the conversation is marked resolved. Range: 5–480 minutes (8 hours). Default: 120. The expiry fires on the widget side: if the visitor returns within the window, they resume the same conversation. |
| **Persist session across page navigations** | When on, the widget keeps the same session id as the visitor navigates pages on your site. When off, each new page load starts a fresh session — useful for authenticated single-page apps where you manage session identity yourself. |

### Identity and join policy

| Toggle | What it controls |
| - | - |
| **Require visitor identity** | When on, the widget refuses to open until the visitor provides a name and email (via the pre-chat form or your own SDK call). When off, anonymous visitors can start a chat immediately. Anonymous conversations are attributed to a visitor token; they become identified when the visitor later provides their details. |
| **Allow unauthenticated join** | When on, visitors who are not logged into your site can still open the widget. When off, the widget requires an authenticated user token set via `OrbitChat.setUser(...)` — unauthenticated visitors see a sign-in prompt instead of the chat surface. |
| **Single conversation per visitor** | When on, a returning visitor re-opens their most recent unresolved conversation rather than starting a new one. When off, every widget open creates a fresh conversation — useful for topic-specific chat embedded on different pages. |

### Bot-or-human first pick-up

| Toggle | What it controls |
| - | - |
| **AI agent first response** | When on, the AI agent selected in the Branding tab picks up every new `web_chat` conversation first. When off (and no AI agent is selected), conversations route straight to the human team. See [Creating AI agents](/agents/creating-agents) for agent setup. |
| **Handoff to human on escalation** | When on (requires AI agent first response), a conversation that the AI agent escalates is routed to a human agent in the inbox. When off, escalated conversations remain in the AI agent's lane until a human manually claims them. |

### Downstream to inbox

| Toggle | What it controls |
| - | - |
| **Route to inbox queue** | Select which digital inbox queue new `web_chat` conversations land in. The picker lists every queue configured under **Inbox → Digital Queues**. An unset queue falls through to the default inbox route. See [Digital queues](/inbox/digital-queues) for queue setup. |
| **Auto-close on session end** | When on, the conversation is automatically marked `closed` when the visitor's session expires. When off, the conversation stays `open` in the inbox even after the visitor leaves — an agent must close it manually or via an auto-close rule. |
| **Send transcript to visitor** | When on, a transcript of the chat is emailed to the visitor when the session ends (requires the visitor to have provided an email address). When off, no transcript is sent. |

## How this page overlaps with the widget config guide

The three surfaces together form the full native-chat configuration:

| Surface | What it governs | Guide |
| - | - | - |
| **Settings → Channels → Native Chat** | Channel-level toggles: pick-up, session, identity, routing | This guide |
| **Branding / Business hours / Pre-chat / Privacy tabs** (same page) | Widget appearance, schedule, consent, and install snippet | [Native Chat channel configuration](/guides/native-chat-widget-channel-config) |
| **Agents → A2A** | External agent bridge for custom reply logic | [Bridge native-chat to an A2A agent](/guides/native-chat-a2a-agent-bridge) |

Changes on all three surfaces take effect immediately — the widget picks up the new configuration on the visitor's next page load. Channel-level toggles (session expiry, identity policy, routing) are evaluated at conversation-open time, not at widget-mount time, so a change mid-session applies to the next conversation the visitor opens.

## API

Read and write the channel-level configuration through the channels endpoint:

| Method | Endpoint | Purpose |
| - | - | - |
| `GET` | `/api/v1/channels/native-chat` | Read the current channel-level toggles |
| `PUT` | `/api/v1/channels/native-chat` | Persist changes to any toggle |

```bash theme={null}
# Read current toggles
curl "https://api.orbit.devotel.io/api/v1/channels/native-chat" \
  -H "X-API-Key: dv_live_sk_..."

# Update session expiry and auto-accept
curl -X PUT "https://api.orbit.devotel.io/api/v1/channels/native-chat" \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "auto_accept": true,
    "session_expiry_minutes": 180,
    "require_visitor_identity": true
  }'
```

The `PUT` endpoint accepts a partial payload — only the fields you include are updated. All fields listed in the toggle matrix above are writable. The endpoint returns the full configuration object on both `GET` and `PUT`.

## Role gating

* **Owners and admins** can read and write every toggle on this page.
* **Developer, supervisor, and agent** seats can view the page content but cannot mutate any toggle. The save bar is gated server-side.
* Every change is recorded in the audit log, so a routing rule or session-expiry change is attributable.

## Troubleshooting

| Symptom | Likely cause | Fix |
| - | - | - |
| Conversations never appear in the inbox | Auto-accept is off and no agent has manually claimed them, or the inbox queue picker points to a deleted queue | Turn on **Auto-accept new conversations** or assign an agent; verify the selected queue still exists under **Inbox → Digital Queues**. |
| Visitors keep getting new conversations instead of resuming | Single conversation per visitor is off | Turn on **Single conversation per visitor**. |
| Anonymous visitors cannot open the widget | Require visitor identity is on | Turn off **Require visitor identity** if you want anonymous chat, or prompt visitors to identify first. |
| AI agent never picks up | AI agent first response is off, or no AI agent is selected in the Branding tab | Turn on **AI agent first response** and select an agent under the Branding tab of the same page. |
| Sessions end too quickly or linger too long | Session expiry window is too short or too long | Adjust **Session expiry window** (5–480 minutes). |
| Transcripts are not emailed | Send transcript to visitor is off, or the visitor never provided an email | Turn on **Send transcript to visitor** and ensure the visitor identifies with an email address. |
| Configuration changes do not take effect immediately | Channel-level toggles are evaluated at conversation-open time | Start a new widget session (hard-refresh the page or wait for the next visitor arrival). |

## Related guides

* [Native Chat channel configuration](/guides/native-chat-widget-channel-config) — widget branding, business hours, pre-chat form, GDPR consent, and the install snippet
* [Bridge native-chat to an A2A agent](/guides/native-chat-a2a-agent-bridge) — external agent reply loop over the `web_chat` channel
* [Inbox setup](/guides/inbox-setup) — inbox routing, assignment, and auto-close rules
* [Digital queues](/inbox/digital-queues) — configure the queues the route-to-inbox picker lists
* [Creating AI agents](/agents/creating-agents) — set up the AI agent the first-response toggle invokes


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.