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

# Voice Agent channel toggles walkthrough

> Walk the Settings → Channels → AI Voice Agent page end to end: bind an agent, set the disclosure and consent a visitor sees before a call, brand the button, set business hours, verify over the API, and fix the common misconfigurations

# Voice Agent channel toggles walkthrough

The AI Voice Agent (Web Call) channel puts a voice widget on your site: a visitor presses the button, sees your disclosure, consents, and talks to one of your AI agents in the browser. The channel settings page is where you decide which agent answers, what the visitor sees before the call connects, when the widget is live, and what the button looks like. This guide walks every control on the page, the equivalent API calls, and the misconfigurations that show up most often.

## 1. Where the surface lives

Open **Settings → Channels → AI Voice Agent (Web Call)**. The page has three tabs:

| Tab | Controls |
| - | - |
| Configure | Widget on/off, which agent answers, button branding, AI disclosure and consent copy |
| Business hours | Per-day open/close windows and the timezone they are evaluated in |
| Install | The `<script>` snippet to paste into your site, plus a preview |

The header shows the channel status (**Connected** once the widget is enabled with an agent bound, **Not Configured** otherwise) and the id of the bound agent.

How this page relates to the rest of the product:

* **Agents are built in the AI Agents hub.** You create, prompt, and activate agents under **AI Agents**. This channel page never edits an agent; it binds one agent to the web-call channel and sets the channel-scoped behavior around it. The picker lists active agents only, because a call can only be answered by an active agent.
* **The binding is channel-scoped.** The same agent can serve other channels, each with its own settings. Everything you set here applies to the web-call widget only.

## 2. The toggles, explained

### Agent and status

* **Enable the voice agent widget** is the master switch. While it is off, an installed snippet places no calls.
* **AI voice agent** is the active agent a visitor talks to. If you have no active agents yet, the page says so and points you to AI Agents; create and activate one there first.

### Appearance

* **Brand color** and **launcher position** set where the floating button sits and which of your brand colors it uses. These are the same two controls as the web chat widget's branding, stored against this widget's own config.
* **Theme** styles the button light or dark to match your site.
* **Button label** is the text on the floating button, up to 60 characters. The default is "Talk to AI".

### AI disclosure and consent

* **AI disclosure text** (up to 500 characters) is the notice shown to the visitor before a call connects, so they know they are speaking with an AI.
* **Require explicit consent before the call starts** is on by default. While it is on, the visitor must accept your **consent copy** (up to 1000 characters) before the call connects.

This page stores the notice and consent your visitors see on this channel. Which disclosure regimes apply to your traffic (EU AI Act, California SB 243, Utah, Korea) is the workspace-level posture you set under **Settings → Compliance → AI Disclosure**. Set that posture first, then write this channel's copy to match it; [AI disclosure pre-publish setup & evidence](/guides/ai-disclosure-setup) walks choosing regimes and verifying the notice actually renders on chat and voice.

Deeper conversation behavior (how the agent speaks, responds, and recovers) is configured on the agent itself in the AI Agents hub, not on this page.

### Business hours

Each day of the week has an enabled flag plus an open and close window, evaluated in your workspace timezone. The schedule ships as part of the widget config your site receives, so your embed knows the windows you declared. Set the hours you actually staff; a visitor outside them should not be offered a call.

## 3. Who can change what

Saving changes on this page requires the **owner** or **admin** role on the workspace.

Every control on the page is tenant-owned. You decide whether to disclose, what the notice and consent say, and when the widget is live; the platform stores your choices and applies them to the widget. Whether a disclosure regime legally applies to your traffic is a legal question for qualified counsel, not a platform default. The compliance posture page records your decision, and this page carries the channel-level copy for it.

## 4. Verify via the API

The page is a client of three endpoints:

| Method | Path | Returns |
| - | - | - |
| GET | `/api/v1/settings/voice-agent-widget` | The current config: enablement, bound agent, branding, disclosure, consent, business hours |
| PUT | `/api/v1/settings/voice-agent-widget` | The updated config |
| GET | `/api/v1/settings/voice-agent-widget/install` | The install snippet and whether the widget is ready |

Read the current state:

```bash theme={null}
curl -s https://orbit.devotel.io/api/v1/settings/voice-agent-widget \
  -H "Authorization: Bearer $ORBIT_API_KEY"
```

Flip the toggles you care about and write them back:

```bash theme={null}
curl -s -X PUT https://orbit.devotel.io/api/v1/settings/voice-agent-widget \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "agent_id": "agt_your_active_agent",
    "primary_color": "#6366f1",
    "position": "bottom-right",
    "theme": "light",
    "button_label": "Talk to AI",
    "ai_disclosure_text": "You are about to speak with an AI assistant.",
    "consent_required": true,
    "consent_text": "By continuing you agree to talk with an AI. A human can join at any time."
  }'
```

Then confirm the result the way the dashboard does: `GET` the config and check `enabled`, `agent_id`, and the disclosure fields read back as written, and `GET /install` to fetch the snippet. Once the widget is enabled with an agent bound, the page header flips from **Not Configured** to **Connected**.

## 5. Common failure paths

* **No agent answers.** The picker was left on "Select an agent…", or the bound agent was archived after binding. Only active agents are listed and can answer; rebind under Configure and save.
* **The widget does nothing on the site.** The enable switch is off, or the snippet from the Install tab was never pasted (or was pasted on a different domain than the one you test). Re-copy the snippet from the Install tab and confirm the enable switch is on.
* **Missing or stale disclosure.** The channel copy was never written, or the workspace posture changed and the channel copy no longer matches it. Update the posture under **Settings → Compliance → AI Disclosure**, then rewrite this channel's disclosure and consent copy, and re-run the verification steps in [AI disclosure pre-publish setup & evidence](/guides/ai-disclosure-setup).
* **Consent required but no consent copy.** If you keep **Require explicit consent** on (recommended wherever you need an affirmative record), write the consent copy visitors accept; an empty consent line gives visitors nothing to agree to.
* **Hours behave oddly.** The windows are evaluated in the workspace timezone, not the visitor's. A "9 to 5" schedule means 9 to 5 in your workspace timezone.
* **The Save button stays disabled.** The page tracks edits against the saved config and enables Save only when something actually differs. It is not stuck; change a field and Save becomes enabled.

## 6. Where it fits

* [AI disclosure pre-publish setup & evidence](/guides/ai-disclosure-setup): the workspace-level disclosure posture this channel's copy implements, plus the evidence trail for audits.
* [Channel settings consoles](/guides/channel-settings-consoles): the organization-level settings consoles this page sits alongside.
* **AI Agents** in the dashboard: where the agent you bind here is built, prompted, and activated.


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