# ThunderPhone Documentation — full content

<!-- en: index -->
---
title: "Introduction"
description: "Documentation for running production voice agents over real phone calls and embeddable web widgets: quickstarts, guides, and the full ThunderPhone API reference."
---

ThunderPhone lets you build AI voice agents that place and answer
real phone calls and power mic-driven conversations on your website.
The documentation is split into four tabs:

<CardGroup cols={2}>
  <Card title="Guides" icon="book" href="/quickstart-dashboard">
    Quickstarts, concepts, and how-tos for the dashboard and the API.
    **Start here** if you're new.
  </Card>
  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Every endpoint, request field, and response shape.
  </Card>
  <Card title="Widget" icon="window-maximize" href="/widget/overview">
    The embeddable web widget — React component, headless hook, and
    CDN script tag.
  </Card>
  <Card title="Webhooks" icon="bolt" href="/webhooks/overview">
    Real-time events, signing, and delivery semantics.
  </Card>
</CardGroup>

## What you can build

<CardGroup cols={2}>
  <Card title="Inbound phone support" icon="phone">
    Answer calls to a number you own with an AI agent that follows your
    prompt, uses your tools, and hands off to humans when needed.
  </Card>
  <Card title="Outbound campaigns" icon="arrow-up-right">
    Place programmatic calls from your code — survey, follow-up, or
    confirmation flows.
  </Card>
  <Card title="In-browser voice" icon="microphone">
    Drop our embeddable [web widget](/guides/embed-web-widget) onto your
    site for customers to click-to-talk. No phone number required.
  </Card>
  <Card title="Test-driven agents" icon="flask">
    Run canned scenarios through your agent in [batches](/api-reference/test-calls)
    so regressions get caught before customers hear them.
  </Card>
</CardGroup>

## Two ways to start

**In the dashboard** (recommended for your first agent) — sign up and
the dashboard walks you through a five-step setup wizard: create an
agent, set up billing, add a phone number, run a simulation, and review
the call. The [dashboard quickstart](/quickstart-dashboard) mirrors
that wizard step by step.

**From your terminal** — the [API quickstart](/quickstart) takes the
same first call in four REST calls.

<Steps>
  <Step title="Skim the concepts">
    [Concepts](/guides/concepts) — a map of every object you'll touch,
    and where each one lives in the dashboard.
  </Step>
  <Step title="Run a quickstart">
    [Dashboard quickstart](/quickstart-dashboard) or
    [API quickstart](/quickstart) — take your first call with an AI
    agent.
  </Step>
  <Step title="Pick a guide">
    Follow a [how-to guide](/guides/build-an-agent) for
    your scenario, or dive into the
    [API reference](/api-reference/introduction).
  </Step>
</Steps>

## Browse the guides

<CardGroup cols={2}>
  <Card title="Using the dashboard" icon="table-columns" href="/guides/build-an-agent">
    Build an agent, fund it, get a number, simulate, and review calls.
  </Card>
  <Card title="Connect tools & data" icon="plug" href="/guides/connect-apps">
    OAuth apps, custom APIs, MCP servers, and VoIP providers.
  </Card>
  <Card title="Analyze & improve" icon="chart-line" href="/guides/reports">
    Reports, observability, experiments, issues, and alerts.
  </Card>
  <Card title="Team & account" icon="users" href="/guides/invite-your-team">
    Invites and roles, API keys, security, and SSO.
  </Card>
</CardGroup>

## Base URL

```
https://api.thunderphone.com/v1
```

Authentication uses the standard OAuth 2.0 Bearer scheme with an
`sk_live_` organization API key. Your key identifies the target
organization automatically — there is no org id in URL paths. See
[Authentication](/api-reference/introduction) for details.

<Note>
  Need help? Email [support@thunderphone.com](mailto:support@thunderphone.com).
</Note>

<!-- en: quickstart-dashboard -->
---
title: "Quickstart (dashboard)"
description: "From signup to your first reviewed call in five guided steps: create an agent, talk to it, get a phone number, place a real call, and review the graded result."
---

New accounts land in a five-step setup wizard, with a coach that
tracks your progress and guided tours on every page. This quickstart
mirrors that wizard, so you can follow along here or just click
**Next** in the app.

<Info>
  You'll need a [ThunderPhone account](https://app.thunderphone.com).
  Sign up is free and takes under a minute. Prefer the terminal? The
  [API quickstart](/quickstart) reaches the same first call in four
  REST calls.
</Info>

<Steps>
  <Step title="Create your agent">
    The wizard opens the agent builder with a draft agent already
    created. Three things to do here:

    1. **Write your prompt.** The prompt is the script for your voice
       agent — describe, in any language, who the agent is and how it
       should handle the call. Call actions like transfers, keypad
       presses, and hang-ups are plain prompt lines too; no separate
       configuration.
    2. **Talk to your agent.** Click **Talk** and say hello — the
       agent answers right in the browser (it'll ask for mic access).
    3. **Deploy your changes.** Every edit autosaves to your draft,
       but drafts aren't live until you click **Deploy**. Each deploy
       is snapshotted in the **History** tab, so you can restore any
       version later.

    On the **Config** tab you can also pick an engine tier (cost vs.
    speed vs. intelligence), set the primary and additional languages,
    and attach [connected apps and API connections](/guides/concepts#connections).
    Zeus shows what a minute of your agent costs before you go live.
    Full detail:
    [Build your first voice agent](/guides/build-an-agent).
  </Step>

  <Step title="Set up billing">
    ThunderPhone is pay-as-you-go: each call draws from your org's balance
    what its parts cost at our providers' list prices, plus an
    infrastructure charge and a markup. No subscriptions, no seats. Under
    **Organization → Billing Settings**:

    1. **Add a payment method.** A card unlocks top-ups and phone
       numbers. It's only charged when you add funds — never
       automatically.
    2. **Load at least $3.00** to start making real calls. Funds never
       expire.

    Optionally flip on **auto top-up** (threshold, refill amount, and
    an optional monthly spending limit) so a call never dies
    mid-sentence. Full detail:
    [Add funds and turn on auto top-up](/guides/billing-and-topups).
  </Step>

  <Step title="Add a phone number">
    On **Phone Numbers**, click **Add number**. Two paths:

    - **ThunderPhone number** — a real U.S. number, live in seconds.
      It costs {/* rate:phone */}$1/month{/* /rate */}, its call minutes are billed as the phone
      line, and it starts inbound-only.
      An organization admin can request outbound calling from the Phone Numbers
      page; ThunderPhone reviews each request manually.
    - **Connect VoIP provider** — import numbers you already own.
      Customer VoIP numbers continue to support outbound calls and campaigns.

    Provisioning auto-routes the number to your agent; the **Inbound**
    select on the number row shows (and changes) who answers. Full
    detail: [Get a phone number](/guides/get-a-phone-number).
  </Step>

  <Step title="Run a simulation">
    Back in the agent builder, click **Simulation**. An AI caller
    rings your number and has a real conversation with your agent —
    generate a caller scenario with AI or write your own, approve the
    charge, and place the call. A floating activity pill shows the
    call happening live. (Or just dial your number from your own
    phone — that counts too.) Full detail:
    [Simulate a call](/guides/simulate-a-call).
  </Step>

  <Step title="View your call">
    Every call lands in **Call History**, newest first. Open the top
    row — your simulation. If it's still in progress you can **listen
    in** live and even **whisper** instructions only your agent hears.
    Once it ends, read the transcript turn by turn and scrub the
    recording waveform. Full detail:
    [Review, listen to, and coach your calls](/guides/review-calls).
  </Step>
</Steps>

<Tip>
  Lost the wizard? Every tour is replayable from the sidebar's
  **Guided tours** menu, and the in-app copilot can walk you through
  any of these flows on demand — just ask it "how do I add a phone
  number."
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Invite your team" icon="user-plus" href="/guides/invite-your-team">
    Bring in teammates with Member or Admin roles.
  </Card>
  <Card title="Create an API key" icon="key" href="/guides/api-keys">
    Ready to automate? Mint an `sk_live_` key and switch to the API.
  </Card>
  <Card title="Core concepts" icon="map" href="/guides/concepts">
    The map of everything else — campaigns, knowledge, experiments,
    alerts, and more.
  </Card>
  <Card title="Quickstart (API)" icon="terminal" href="/quickstart">
    The same first call in four REST calls.
  </Card>
</CardGroup>

<!-- en: quickstart -->
---
title: "Quickstart (API)"
description: "Answer your first phone call with an AI agent: get an API key, create an agent, provision a phone number, and place a live test call — all through the REST API."
---

This guide walks you through the four REST calls it takes to answer
your first phone call with an AI agent.

<Info>
  You'll need a [ThunderPhone account](https://app.thunderphone.com).
  Sign up is free and takes under a minute. Prefer clicking to curling?
  The [dashboard quickstart](/quickstart-dashboard) reaches the same
  first call without writing any code.
</Info>

## Step 1: Get an API key

<Steps>
  <Step title="Log in">
    Open [app.thunderphone.com](https://app.thunderphone.com).
  </Step>
  <Step title="Navigate to Keys">
    Go to **Organization → Keys** in the dashboard.
  </Step>
  <Step title="Create a key">
    Click **Create key**, give it a name, and copy the
    `sk_live_...` value. The raw key is shown **only once** — store it
    in your secret manager immediately.
  </Step>
</Steps>

<Tip>
  Stuck? [Create a server API key](/guides/api-keys) walks
  this flow in step-by-step detail, and the in-app copilot can
  spotlight each control for you live.
</Tip>

Throughout this guide, swap `sk_live_YOUR_API_KEY` with the value you
just copied. The key identifies your organization automatically, so
you never need to put an org id in URLs.

## Step 2: Create an agent

An agent defines how the AI handles conversations — prompt, voice,
product tier, tools, and widget eligibility.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/agents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":   "Customer Support",
    "prompt": "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
    "voice":  "john",
    "product": "spark"
  }'
```

```python Python
import os, requests

agent = requests.post(
    "https://api.thunderphone.com/v1/agents",
    headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
    json={
        "name":   "Customer Support",
        "prompt": "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
        "voice":  "john",
        "product": "spark",
    },
).json()
print("Agent id:", agent["id"])
```

```javascript Node.js
const agent = await fetch("https://api.thunderphone.com/v1/agents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.THUNDERPHONE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name:    "Customer Support",
    prompt:  "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
    voice:   "john",
    product: "spark",
  }),
}).then((r) => r.json());
console.log("Agent id:", agent.id);
```
</CodeGroup>

<Tip>
  Product tiers: `spark` is optimized for cost, `bolt` for speed, and
  `storm-base` / `storm-extra` for intelligence on complex prompts. See
  [Agents](/api-reference/agents#product-tiers-at-a-glance) for the full
  comparison.
</Tip>

## Step 3: Provision a phone number

This call asks ThunderPhone for a number and assigns your
new agent as the inbound handler. (To bring your own number from a VoIP
provider, see [VoIP connections](/api-reference/voip-connections)
instead.)

<CodeGroup>
```bash cURL
# First provision
curl -X POST https://api.thunderphone.com/v1/phone-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"area_code": "415"}'

# Then assign the agent you created in Step 2
curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/<id-from-previous> \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbound_agent_id": 12}'
```

```python Python
number = requests.post(
    "https://api.thunderphone.com/v1/phone-numbers",
    headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
    json={"area_code": "415"},
).json()
requests.patch(
    f"https://api.thunderphone.com/v1/phone-numbers/{number['id']}",
    headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
    json={"inbound_agent_id": agent["id"]},
)
print("Your ThunderPhone number:", number["number"])
```
</CodeGroup>

Your new number starts in `status="provisioning"` and transitions to
`active` within a few seconds; by the time you hang up your browser the
number is ready to take calls.

## Step 4 (optional): Set up a webhook

For real-time events (dynamic call routing, post-call processing) add
a webhook endpoint. Subscribe only to the events you need.

```bash
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Prod webhook",
    "url":    "https://your-server.com/thunderphone-webhook",
    "events": ["telephony.incoming", "telephony.complete"]
  }'
```

The response contains a one-shot `secret` — copy it to your secret
manager. Use that secret to verify the `X-ThunderPhone-Signature-V2`
header on incoming requests (see
[Webhooks overview](/webhooks/overview#signature-verification)).

## Step 5: Test your agent

Call the number you just provisioned. The agent picks up, introduces
itself, and follows your prompt.

Inspect the call after it ends:

```bash
curl https://api.thunderphone.com/v1/calls \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

Drill into a specific call to fetch the transcript and recording URL:

```bash
curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

---

## Next steps

<CardGroup cols={2}>
  <Card title="Add function tools" icon="screwdriver-wrench" href="/tools/overview">
    Let your agent call your APIs during a conversation.
  </Card>
  <Card title="Place outbound calls" icon="arrow-up-right" href="/api-reference/outbound-calls">
    Trigger calls from your own code.
  </Card>
  <Card title="Handle webhooks" icon="bolt" href="/webhooks/overview">
    React to call events in real time.
  </Card>
  <Card title="Full API reference" icon="book" href="/api-reference/introduction">
    Every public endpoint, documented.
  </Card>
</CardGroup>

<!-- en: guides/coding-agents -->
---
title: "Build with Claude Code, Codex or Cursor"
description: "Install ThunderPhone Agent Skills, connect the ThunderPhone MCP server, and give a coding agent current product documentation."
---

ThunderPhone provides three layers for coding agents:

| Layer | What it gives the agent |
| --- | --- |
| [Agent Skills](https://github.com/thunderphone/skills) | Focused procedures for agents, prompts, numbers, calls, tools, webhooks, knowledge, testing, improving an agent in a closed loop, campaigns, widgets, realtime frameworks and migrations. |
| MCP | Authenticated tools cover agents, numbers, calls, testing, knowledge, tools/webhooks, campaigns, voices, imports and docs as they roll out; call `tools/list` for the live catalog. |
| [Raw documentation](https://thunderphone.com/docs/llms.txt) | Current Markdown sources for product behavior and API details. |

Skills explain how to do the work. MCP lets the coding agent inspect and act on
your organization. Raw docs provide the source material for questions outside a
loaded skill.

## Install in a project

This block installs the skills, makes the key available to the current shell,
and adds the project-scoped MCP server to Claude Code. Replace the placeholder
by reading the real value from your secret manager; do not paste a key into a
repository or chat.

```bash
npx skills add thunderphone/skills
export THUNDERPHONE_API_KEY='replace-with-value-from-your-secret-manager'
claude mcp add --transport http --scope project \
  --header 'Authorization: Bearer ${THUNDERPHONE_API_KEY}' \
  thunderphone https://api.thunderphone.com/v1/mcp
```

For Codex, replace the final command with:

```bash
codex mcp add thunderphone \
  --url https://api.thunderphone.com/v1/mcp \
  --bearer-token-env-var THUNDERPHONE_API_KEY
```

Cursor reads a project configuration from `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "thunderphone": {
      "type": "http",
      "url": "https://api.thunderphone.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:THUNDERPHONE_API_KEY}"
      }
    }
  }
}
```

VS Code uses the same server under a `servers` key in `.vscode/mcp.json`:

```json
{
  "servers": {
    "thunderphone": {
      "type": "http",
      "url": "https://api.thunderphone.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:THUNDERPHONE_API_KEY}"
      }
    }
  }
}
```

<Warning>
  An organization API key can read organization data and perform enabled
  actions. Keep it in a secret manager, scope access to the intended project,
  and review mutating tool calls before approval.
</Warning>

## Example session: bilingual dental receptionist

1. Ask the coding agent to load `create-agent`,
   `thunderphone-prompt-builder`, `build-tool-integration`, `add-knowledge`, and
   `test-agent`. Tell it to plan first and not create resources yet.
2. Give it verified practice facts, supported tasks, escalation rules and the
   two required locales. Have it check the live voice catalog and supported
   languages instead of inventing a voice or locale.
3. Ask for one production prompt built from general principles and facts. The
   agent should switch to the caller's supported language, keep speech concise,
   ask one question at a time, and avoid caller-response scripts.
4. Have it define a narrow scheduling tool and attach only the knowledge the
   receptionist needs. Test tool success, no availability, invalid input,
   timeout and human handoff before deployment.
5. Generate scenarios for both languages, interruptions, corrections, missing
   information, knowledge questions, scheduling failures and escalation. Run
   them, inspect transcripts and tool evidence, fix the smallest general rule,
   and rerun the same set.
6. Review the exact draft and test evidence, then explicitly authorize deploy
   and number attachment. Place a controlled audio call in each language before
   moving real traffic.

## Improve an agent in a closed loop

Once an agent takes calls, ask the coding agent to load `iterate-on-agent`.
The skill runs the same loop ThunderPhone uses on its own agents, so each
change is measured before it ships:

1. **Read** the agent, its [prompt revisions](/api-reference/prompt-revisions) and the [prompt style guide](/guides/prompt-style). Prompt revisions are available over REST and MCP, so a coding agent can inspect recent prompt changes directly.
2. **Build test sets.** `import_conversations` turns recent calls into
   [test conversations](/api-reference/conversations) and their hardest
   moments into examples with answer keys; `generate_conversations` writes
   them for a new agent, including difficult callers aimed at the prompt's
   weak spots (those always go to the dev split). Each conversation sits in
   a dev split, for tuning, or a test split, for measuring once. A call
   whose caller is in a test split is held out: to an API key or OAuth
   token, over REST and MCP alike, it comes back as its id, start time and
   `held_out: true` only, writes on it are refused (`held_out_call`), and
   so are test scenarios promoted from it; leave it out when tuning.
3. **Take a baseline** with `run_replays` on the dev split. With Bolt v2, a
   turn with recorded audio is [replayed](/api-reference/replay-runs) as a
   live call would run it.
4. **Edit the draft.** `review_prompt` checks the prompt against the style
   guide and offers find and replace edits; `update_agent` applies them to
   the draft with `prompt_edits`; a second review with `previous_prompt`
   checks what changed. `refactor_prompt` rewrites a prompt that has
   collected too many patches, and reports any behavior it changed. When an
   edit adds or removes a behavior, `refresh_conversations` brings the test
   conversations up to the new prompt, restoring earlier versions where a
   rule came back.
5. **Verify** with `run_replays` against the baseline, reading the
   failures the way a caller would hear them. `compare_configs` tries a
   different audio tier, voice, endpointing or intelligence tier on the same
   dev examples;
   comparisons are dev-only.
6. **Measure once** on the test split. A test run replays one whole test
   cohort and its first result spends it, so each later test run, for any
   prompt, needs fresh test data from imported calls or generated
   conversations. Each example's engine is set before the run from its
   data (recorded audio replays exactly, text-only examples as text),
   totals come per engine, and nothing falls back to text: a cohort with
   recorded audio under a configuration other than Bolt v2 is refused
   (`test_needs_exact_replay`) and stays unused, so measure that
   configuration on dev. Coding agents get its totals only, so they cannot
   tune on it.
7. **Listen** to a `run_simulation` recording, or open a
   [talk link](/api-reference/talk-links) and talk to the draft yourself.
8. **Deploy** when you say so.

Everything that spends credits quotes first: send `dry_run: true` for an
estimate, then run with its `quote_id` and `max_cost_cents`, a hard cap. A
quote pays for one run: conversation jobs, replay runs, and prompt reviews
and refactors that call the model all use it up, durably, when they start,
and a start that is refused or fails first leaves it usable; after it is
used, repeat a failed run with a new dry run. Each request
sets aside its most possible cost before it is sent, and the run is charged
what it really cost, so leave the estimate's headroom. An exact replay sets
aside about 85 cents to $1.25 per replay in flight for a typical turn
(a normal turn plus one production re-run), against a real cost of a few
cents: give replay runs a cap with room. A turn that still runs out of
budget is counted apart and spends no test cohort. An agent
runs one conversation job or replay run at a time. With OAuth, the prompt
tools need the `agents:write` scope. When a call's recording is turned off
or the call is deleted, the test conversations and examples taken from it
are removed too. The test conversation,
replay, prompt review and talk link tools are part of the agent iteration
toolkit, which is enabled per organization while it is in beta; ask
[support](mailto:support@thunderphone.com) to turn it on.

Use the [Python or TypeScript SDK](/api-reference/sdks) for typed REST requests.

Use REST instead of MCP when a build needs deterministic payloads, versioned
fixtures, bulk orchestration, or an operation not present in the current MCP
tool list. The API starts at `https://api.thunderphone.com/v1`; see the
[API introduction](/api-reference/introduction) and
[MCP guide](/guides/thunderphone-mcp-server).

<!-- en: guides/cli -->
---
title: "ThunderPhone CLI"
description: "Log in, manage voice agents and calls, configure MCP clients, and scaffold projects from the terminal."
---

The CLI requires Node.js 18.18 or later. Run it with `npx`, or install it globally:

```bash
npm install -g thunderphone
thunderphone --help
```

## Log in

```bash
npx thunderphone login
thunderphone whoami --json
```

Login prints a verification code, opens the browser, and waits for authorization.
Use `--no-browser` on a headless machine and open the printed URL elsewhere.
Device login requires the API's OAuth device-flow rollout. An organization API
key in `THUNDERPHONE_API_KEY` can also authenticate commands and takes precedence
over stored login credentials.

Credentials are stored by profile in `~/.config/thunderphone/credentials.json`
with file mode `0600`. `XDG_CONFIG_HOME` and `THUNDERPHONE_CONFIG_DIR` override the
directory. Access tokens refresh automatically and rotating refresh tokens are
saved atomically. Tokens are never printed by login.

```bash
thunderphone login --profile work
thunderphone agents list --profile work --json
thunderphone logout --profile work
```

`THUNDERPHONE_PROFILE` sets the default profile. Logout removes local credentials;
it does not revoke the server grant. Changing or resetting your password, or
changing your account email, does revoke it; run `thunderphone login` again. The default API is `https://api.thunderphone.com`.
Use `--api-base-url` or `THUNDERPHONE_API_BASE_URL` for another API. A profile's token
cannot be sent to a different configured API URL; log into that URL with a separate profile.

## Commands

Every command accepts `--json`. Successful data goes to stdout; errors go to stderr
with a nonzero exit code. Without `--json`, output is a compact table or field list.
JSON retains the API response structure, with credential fields redacted. MCP serving
reserves stdout for the MCP protocol.

| Command | Purpose |
| --- | --- |
| `login [--no-browser] [--scope "scopes"]` | Authorize through a device code |
| `logout`, `whoami` | Remove local credentials; list accessible organizations |
| `agents list`, `agents get ID` | Read agents |
| `agents create --file agent.json` | Create an agent |
| `agents update ID --file agent.json` | Save an agent draft |
| `agents deploy ID`, `agents delete ID` | Deploy the draft; delete an agent |
| `numbers list` | Read phone numbers |
| `numbers provision --country US --area-code 415` | Provision a US inbound number |
| `numbers assign NUMBER_ID --agent ID` | Assign an inbound agent |
| `sms send TO --from FROM --body TEXT --idempotency-key KEY` | Send SMS through a customer-connected carrier number with safe replay |
| `sms list [--limit N]`, `sms get UUID` | List or inspect SMS records |
| `call TO --agent ID --from FROM [--wait]` | Place an outbound call; optionally wait for its transcript |
| `calls list [--limit N] [--agent ID]` | List calls (limit 1–200) |
| `calls get ID`, `calls transcript ID` | Read one call or its transcript |
| `test run AGENT_ID [--scenario ID] --consent-to-charge` | Run billable saved scenarios using the web channel |
| `test status RUN_ID [--agent ID]` | Inspect a batch, with scenario details when an agent is supplied |
| `import VENDOR export.json` | Prepare a vendor JSON import for review |
| `imports get UUID`, `imports commit UUID` | Inspect an import; commit selected agents after review |
| `mcp setup`, `mcp serve` | Configure a client; start the stdio bridge |
| `init [directory]` | Scaffold a project |

Outbound calls require an outbound-enabled number. `THUNDERPHONE_FROM_NUMBER` can
supply `--from`. Customer VoIP numbers continue to support outbound calls.
ThunderPhone-provisioned numbers start inbound-only; an organization admin can
request outbound calling from the Phone Numbers page, where each request is
reviewed manually. `--wait` defaults to a one-hour timeout; set
`--timeout SECONDS` to change it. A timeout stops waiting without ending the call.

SMS also requires an SMS-capable number on your connected Twilio or Telnyx
account. It never sends from a ThunderPhone-owned number. Reuse an idempotency
key only when retrying the exact same sender, recipient, and body.

Imports support `vapi`, `retell`, `elevenlabs`, and `bland`. The second argument is a
path to a vendor JSON export, not a remote vendor ID. The API prepares a mapping
asynchronously; inspect it with `imports get UUID` and commit only after it is ready
and you have reviewed the mapped fields and warnings. See [agent imports](/guides/import-agents).

## MCP setup

```bash
thunderphone mcp setup --client cursor --api-key-env THUNDERPHONE_API_KEY
thunderphone mcp setup --client codex --scope user --api-key-env THUNDERPHONE_API_KEY
thunderphone mcp setup --client claude-desktop --scope user
```

Clients: `claude-code`, `codex`, `cursor`, `vscode`, `gemini`, `claude-desktop`, and
`windsurf`. Project scope is the default. Desktop and Windsurf require user scope.
Omit `--client` to detect a single client from the project; ambiguous detection
prompts interactively or fails with instructions in a non-interactive session.
Setup prints the file it wrote and preserves unrelated servers. Existing JSON
must be valid strict JSON; Codex TOML values are preserved but comments may be reformatted.

Setup prefers direct remote HTTP. With `--api-key-env`, it writes a variable
reference, never the key. Without that option, direct HTTP relies on the client's
OAuth support; it does not use the CLI credential file. To reuse `thunderphone login`
credentials in any stdio-capable client, use:

```json
{
  "mcpServers": {
    "thunderphone": {
      "command": "npx",
      "args": ["-y", "@thunderphone/mcp"]
    }
  }
}
```

The wrapper checks `THUNDERPHONE_API_KEY`, then the current CLI profile (refreshing
when needed), then delegates OAuth to `mcp-remote`. `THUNDERPHONE_MCP_URL` overrides
the endpoint. It emits no telemetry. Standalone setup is also available through
`npx -y @thunderphone/mcp setup --client cursor` or `thunderphone-mcp setup` after
installing `@thunderphone/mcp` globally.

## Create a project

```bash
npx create-thunderphone-agent my-receptionist
npx create-thunderphone-agent my-outbound --template python --agent-type outbound
# Equivalent:
thunderphone init my-receptionist --template node --agent-type receptionist
```

Templates are `node` and `python`; agent types are `receptionist`, `outbound`, and
`custom`. The default agent is an English/Spanish dental receptionist with explicit
demo facts. Projects include `agent.json`, deploy scripts, MCP configurations for
Claude Code, Cursor and VS Code, agent instructions, `.env.example`, and a README.
Scaffolding is offline and refuses to overwrite a nonempty directory.

Edit the business facts before deployment. Export the API key, connected caller
number, and your test recipient as documented in the generated README. `npm run deploy`
or `python deploy.py` creates or updates the agent, deploys its draft, and places a
billable test call. The scripts use API-key authentication; the CLI and stdio MCP
wrapper also support device login. Python scripts require Python 3.9 or later.

<!-- en: guides/concepts -->
---
title: "Core concepts"
description: "A map of everything in the platform — what each object does, where it lives in the dashboard, and which API touches it."
---

ThunderPhone is a full platform for building, running, and improving
AI voice agents. This page is the map: every concept you'll meet, one
short section each, with the dashboard surface and the API that backs
it. Skim it once, then come back whenever a term needs unpacking.

The dashboard sidebar mirrors this structure:

<CardGroup cols={2}>
  <Card title="Core" icon="cube">
    [Agents](#agents), [voices](#voices), [phone numbers](#phone-numbers),
    [web widgets](#web-widgets), [calls](#calls),
    [client portals](#client-portals), [knowledge](#knowledge-bases).
  </Card>
  <Card title="Engagement" icon="megaphone">
    [Live monitoring](#live-monitoring) and outbound
    [campaigns](#campaigns).
  </Card>
  <Card title="Connections" icon="plug">
    [Apps, APIs, MCP servers, and VoIP providers](#connections) your
    agents can use.
  </Card>
  <Card title="Quality & Testing" icon="flask">
    [Simulations](#simulations), [validation sets](#validation-sets),
    [experiments](#experiments),
    [issues](#issues), [reports](#reports),
    [observability](#observability).
  </Card>
  <Card title="Organization" icon="building">
    [Team & roles](#team-and-roles), [API keys](#organizations),
    [alerts](#alerts), [billing](#billing).
  </Card>
  <Card title="Eventing" icon="bolt">
    [Webhooks](#webhooks) and [function tools](#function-tools) for
    your own code.
  </Card>
</CardGroup>

---

## Organizations

An **organization** is the unit of tenancy. Every other resource —
agents, phone numbers, calls, keys — belongs to exactly one org. Your
account can belong to many orgs; each has its own balance, its own
keys, and its own members list.

The `sk_live_` API key you create under **Organization → Keys** is
bound to one organization. That binding is what makes the REST API so
flat: you never put an org id in URL paths, because your key already
identifies it.

**In the dashboard:** the organization switcher (sidebar footer) and
**Organization** settings — tabs for My account, General, Keys, Alerts,
Billing Settings, and Billing History. See the
[Organization settings reference](/guides/organization-settings).

**In the API:** [`/v1/orgs`](/api-reference/organizations),
[`/v1/developer/api-keys`](/api-reference/developer-api-keys).

---

## Agents

An **agent** is the AI configuration that runs a call. It bundles:

- A **prompt** that governs what the agent says and how it behaves —
  including call actions like transfers, keypad presses, and hang-ups,
  which are plain prompt lines rather than separate configuration.
- An **engine tier** (`spark`, `bolt`, `storm-*`): Spark is optimized
  for cost, Bolt for speed, Storm for intelligence on complex prompts.
- A **voice** plus a **primary language** and optional **additional
  languages** — the agent switches automatically when a caller changes
  language. See [Supported languages](/guides/supported-languages).
- Attached capabilities: [connected apps](#connections),
  [API connections](#connections), [knowledge bases](#knowledge-bases),
  [MCP servers](#connections), and inline
  [function tools](#function-tools).
- Behavior knobs: speak order, acknowledgement mode, background track,
  hold timeout.

Edits in the builder **autosave to a draft**; nothing goes live until
you click **Deploy**. Every deploy is snapshotted in the builder's
**History** tab, so you can inspect and restore any previous version.

**In the dashboard:** **Voice Agents** → the agent builder
(`/dashboard/agents`). See
[Build your first voice agent](/guides/build-an-agent).

**In the API:** [`/v1/agents`](/api-reference/agents) — CRUD,
duplicate, transfer, version history, and prompt helpers.

---

## Voices

The **voice library** contains the voices an agent can use, their playable
samples, compatible languages, gender and accent groupings, and which voices
are premium. A paid sampler can synthesize your own 1–500
character phrase before you choose.

Eligible organizations can also create **custom voices** from a short WAV or
MP3 sample. Custom voices have a quota and asynchronous creation status; once
ready, they appear in the same agent picker as library voices.

**In the dashboard:** **Voices** (`/dashboard/voices`). See
[Voice library and custom voices](/guides/voice-library).

**In the API:** [`/v1/voices`](/api-reference/voices),
[voice samples](/api-reference/voice-samples), and
[custom voices](/api-reference/custom-voices).

---

## Phone numbers

A **phone number** belongs to an org and routes inbound calls to an
agent (and can carry outbound calls). Two sources:

- **ThunderPhone numbers** — real U.S. numbers provisioned from
  ThunderPhone's pool, live in seconds, {/* rate:phone */}$1/month{/* /rate */}; their call
  minutes are billed as the phone line. They start inbound-only. An organization admin can request
  outbound calling from the Phone Numbers page; ThunderPhone reviews each
  request manually, and approved numbers can place calls and run campaigns.
  An org can hold 25 by default.
- **VoIP numbers** — brought from your own provider through a
  [VoIP connection](#connections). Twilio and Telnyx connect directly
  with an API key (Telnyx also has a guided new-account setup);
  SignalWire, Vonage, Plivo and any other SIP trunk connect through SIP
  setup, a manual SIP configuration. Once imported and verified, VoIP
  numbers support inbound and outbound.

Each number row lets you set a routing mode, pick the inbound agent,
and label the number.

**In the dashboard:** **Phone Numbers** (`/dashboard/phone-numbers`).
See [Get a phone number](/guides/get-a-phone-number).

**In the API:** [`/v1/phone-numbers`](/api-reference/phone-numbers),
[`/v1/voip-connections`](/api-reference/voip-connections),
[`/v1/phone-number-labels`](/api-reference/phone-number-labels).

---

## Calls

Every inbound call, outbound call, simulation, and widget session
becomes a **call log**. A call carries the full role-tagged transcript,
the structured turn history (including tool calls), a recording, the
billing total, and optional AI grading and issue reports.

While a call is **live**, you can open it and **listen in** — you join
silently, and nobody on the call hears you. Once listening, you can
**whisper**: type an instruction that goes straight to your agent
mid-call; the caller never hears it, and the agent follows it live.

**In the dashboard:** **Call History** (`/dashboard/call-history`) for
the archive and per-call detail; **Live** for calls in progress. See
[Review, listen to, and coach your calls](/guides/review-calls).

**In the API:** [`/v1/calls`](/api-reference/calls) — list, transcript,
history, audio, grading, export;
[`/v1/issue-reports`](/api-reference/issue-reports).

---

## Client portals

A **client portal** is a branded, read-only call-history view for an external
client. Organization admins choose the agents whose calls appear, add approved
viewer emails, upload a logo and accent color, and optionally verify a custom
domain. Portal viewers can inspect call details, transcripts, and available
recordings without receiving dashboard access.

**In the dashboard:** **Client portals** (`/dashboard/client-portals`). See
[Client portals](/guides/client-portals).

**In the API:** [`/v1/client-portals`](/api-reference/client-portals) for the
admin management surface.

---

## Web widgets

The **web widget** gives your site visitors a mic-based conversation
with an agent — no phone number needed. It authenticates with a
**publishable key** (`pk_live_...`) that browsers can only use from
your allowed domains, so it's safe in client-side code. The domain list
is not authentication, and the session settings a page may send are
off until you allow them on the key.

Keys run in one of two modes: `agent` (statically bound to one agent)
or `webhook` (your server picks the configuration per visitor — see
[Dynamic per-call configuration](/guides/dynamic-call-config)). Widget
sessions flow through the same call infrastructure as phone calls.

**In the dashboard:** **Web Widgets** (`/dashboard/web-widgets`) —
create widgets, set the mode and agent, manage allowed domains, and
copy the embed snippet. See
[Create a web widget](/guides/embed-a-web-widget-dashboard).

**In the API:** [`/v1/publishable-key`](/api-reference/publishable-keys),
[`/v1/mic-session`](/api-reference/mic-sessions), and the
[Widget SDK docs](/widget/overview).

---

## Knowledge bases

A **knowledge base** is a set of documents your agent can search
mid-call to ground its answers — upload files, paste text, or import
web pages by URL, then attach the knowledge base to an agent in the
builder. The agent queries it with a built-in search tool whenever the
conversation calls for it.

**In the dashboard:** **Knowledge** (`/dashboard/knowledge`) for the
document library; the builder's **Knowledge** section to attach one to
an agent. See
[Give your agent a knowledge base](/guides/knowledge-base).

---

## Connections

Connections are how agents reach the outside world. Four kinds, one
sidebar group:

- **Apps** (`/dashboard/app-connections`) — OAuth connections to
  Slack, HubSpot, Salesforce, Google Calendar, Google Sheets, and
  Cal.com. Connect once, then toggle per-operation tools (post a
  Slack message, upsert a HubSpot contact, book a Cal.com slot…) onto
  any agent. See [Connect apps](/guides/connect-apps).
- **APIs** (`/dashboard/api-connections`) — turn any HTTP API into an
  agent action. Paste a cURL command and the AI wizard drafts the tool
  definition, or build it manually; a **Test Request** button fires a
  sandbox call before you ship. See
  [API connections](/guides/api-connections) — the dashboard face of
  [`/v1/integrations`](/api-reference/integrations).
- **MCP** (`/dashboard/mcp-connections`) — add a Model Context
  Protocol server by URL and let the agent use the tools it exposes.
  See [Add an MCP server](/guides/mcp-servers).
- **VoIP** (`/dashboard/voip-connections`) — provider credentials for
  [bringing your own phone numbers](#phone-numbers). See
  [Connect a VoIP provider](/guides/voip-providers).

ThunderPhone also exposes its own MCP endpoint so an external MCP client can
list agents, inspect calls and transcripts, and place calls. See
[Use ThunderPhone as an MCP server](/guides/thunderphone-mcp-server).

**In the API:** [`/v1/integrations`](/api-reference/integrations),
[`/v1/mcp-servers`](/api-reference/mcp-servers), and
[`/v1/voip-connections`](/api-reference/voip-connections); see also
[Build a tool integration](/guides/build-tool-integration).

---

## Campaigns

A **campaign** places outbound calls at scale: upload a CSV of
contacts, pick the agent and from-number, and set the calling window
(days and hours, timezone-aware), concurrency, and retry policy
(max attempts and which outcomes — no answer, voicemail, failed — get
retried). The campaign works through the list and records every call
in Call History.

**In the dashboard:** **Campaigns** (`/dashboard/campaigns`). See
[Run an outbound calling campaign](/guides/outbound-campaigns).

**For one-off programmatic calls:** the
[outbound calls API](/guides/place-outbound-calls).

---

## Live monitoring

**Live** shows every call in progress across the org, and lets you
open any of them to [listen in and whisper](#calls) in real time. It's
the supervision surface: watch a new prompt take its first real
traffic, or keep an eye on a running campaign.

**In the dashboard:** **Live** (`/dashboard/live`). See
[Watch and supervise live calls](/guides/monitor-live-calls).

---

## Simulations

A **simulation** is an AI caller having a real conversation with your
agent — same telephony path, real transcript, real grading — so you
can test before (and after) you ship. Point it at an agent or a phone
number, write the caller scenario yourself or **generate scenarios
with AI** from the agent's prompt (edge cases included, if you ask),
and watch the call live.

Scenarios group into **suites** that pin a minimum pass rate and can
gate releases in CI; regressions against the accepted baseline are
reported per scenario.

**In the dashboard:** **Simulations** (`/dashboard/simulations`), plus
the **Simulation** button inside the agent builder. See
[Simulate a call](/guides/simulate-a-call).

**In the API:** [`/v1/test-calls`](/api-reference/test-calls) and the
suite runner — see [Test an agent end-to-end](/guides/test-agents).

---

## Validation sets

A **validation set** turns real call moments into repeatable, single-turn
regression checks. Each example freezes conversation context, relevant caller
audio, the original response, and the expected behavior. Replays run against
the current agent draft without placing another call, and the deploy dialog can
show whether the latest run still matches that draft.

**In the dashboard:** **Validation sets** (`/dashboard/validation`) for the
organization dataset and the agent builder's **Validation** tab for runs. See
[Validation sets](/guides/validation-sets).

**In the API:** [`/v1/validation-sets`](/api-reference/validation-sets) and
the agent/example replay endpoints on the same reference page.

---

## Experiments

An **experiment** A/B tests agent configurations on live traffic:
define variants (different prompts, engines, or settings), split
traffic between them, and compare outcomes per variant. Use it instead
of hand-rolling bucket logic in a webhook.

**In the dashboard:** **Experiments** (`/dashboard/experiments`) and
the **A/B** tab in the agent builder. See
[Experiments (A/B testing)](/guides/experiments-ab-testing).

---

## Issues

An **issue** is a flagged problem on a specific call — filed by a
human reviewer or detected by AI grading. Issues carry severity,
source, and status, and the Issues page is the triage queue: filter,
inspect the offending call, and track fixes.

**In the dashboard:** **Issues** (`/dashboard/issues`), plus per-call
flagging in Call History. See [Issues triage](/guides/issues).

**In the API:** [`/v1/issue-reports`](/api-reference/issue-reports).

---

## Reports

A **report** answers a natural-language question about your call data
("What were the top three reasons callers asked for a human last
week?") with an AI-written analysis, scoped to the agents and date
range you choose.

**In the dashboard:** **Reports** (`/dashboard/reports`). See
[Reports](/guides/reports).

---

## Observability

**Observability** is the metrics surface: call volume, outcomes, and
quality over time, filterable by agent and time window, with export
for downstream analysis.

**In the dashboard:** **Observability** (`/dashboard/observability`).
See [Observability](/guides/observability).

---

## Alerts

An **alert rule** watches a metric (success rate, failure rate,
average score, call volume, suite regressions) over a time window and
fires when it crosses your threshold. Notifications go to email and
Slack, and fire an `alert.triggered` event to your
[webhook endpoints](/webhooks/endpoints).

**In the dashboard:** **Organization → Alerts**. See
[Alerts](/guides/alerts).

---

## Webhooks

ThunderPhone sends **HTTP POST webhooks** to your server when things
happen during and after a call. Two delivery models:

- **Webhook endpoints** (recommended): manage many URLs at
  [`/v1/developer/webhook-endpoints`](/webhooks/endpoints) with
  per-endpoint secrets and per-endpoint event subscriptions.
- **Legacy single-URL webhook**: one URL per org. Managed at
  [`/v1/webhook`](/api-reference/organizations#legacy-single-url-webhook)
  or under **Organization → General**. Kept for backward compatibility.

Events split into two classes:

- **Blocking events** expect your server to respond with configuration
  that shapes the in-flight call — the
  [incoming-call events](/webhooks/call-incoming)
  (`telephony.incoming` / `web.incoming`). A phone call waits up to
  13 seconds, one retry included, and a widget session 10 seconds.
  There is no fallback agent: without a usable configuration the phone
  call is ended and the widget session fails.
- **Non-blocking events** are fire-and-forget notifications, retried
  with exponential backoff — see
  [delivery semantics](/webhooks/overview).

Every request carries a timestamped HMAC-SHA256 signature in
`X-ThunderPhone-Signature-V2`, plus the legacy body-only
`X-ThunderPhone-Signature`. See
[Signature verification](/webhooks/overview#signature-verification).

---

## Function tools

A **function tool** is an HTTP endpoint your agent can call
mid-conversation. You give ThunderPhone an OpenAI-style function
schema plus an endpoint URL; the agent decides when to call it, and
ThunderPhone makes the signed HTTP request from its servers and hands
the result back to the agent.

Agents also ship **built-in call abilities** — transferring the call,
sending keypad (DTMF) input, ending the call, waiting on hold — that
you enable with plain prompt lines rather than tool definitions.

**In the dashboard:** the builder's **API connections** section (see
[Connections](#connections)).

**In the API:** [`/v1/integrations`](/api-reference/integrations) and
the [Function Tools spec](/tools/overview).

---

## Team and roles

Each organization has a members list with two roles: **Members** build
and operate agents; **Admins** also manage the team and billing.
Invite by email — invitations expire after 7 days and can be revoked;
the ⋯ menu on a member row changes roles or removes someone. Single
sign-on can be configured org-wide — see [SSO](/guides/sso).

**In the dashboard:** **Organization → General**. See
[Invite your team](/guides/invite-your-team).

**In the API:** [`/v1/members`](/api-reference/members),
[`/v1/invites`](/api-reference/invites).

---

## Billing

ThunderPhone is **prepaid**. Each org carries a USD balance; each call
debits what its parts cost at our providers' list prices, plus an
infrastructure charge and a markup (see [pricing](/guides/pricing)). When the
balance hits zero, inbound calls are rejected and outbound calls
return `402 Payment Required`.

Top up manually, or enable **auto top-up** with a balance threshold, a
refill amount, and an optional monthly spending limit — so a call
never dies mid-sentence.

**In the dashboard:** **Organization → Billing Settings** and
**Billing History**. See
[Add funds and turn on auto top-up](/guides/billing-and-topups), plus the
[complete pricing reference](/guides/pricing).

**In the API:** [`/v1/billing`](/api-reference/billing).

---

## The in-app copilot

The dashboard ships with a built-in **copilot** — ask it "how do I X"
and it answers from these docs, offers click-by-click walkthroughs
that spotlight the real controls, and can replay any of the guided
tours. It's the fastest way to find a control this page mentions.
See [Ask the in-app copilot](/guides/ask-the-copilot).

---

## Putting it together

<CardGroup cols={2}>
  <Card title="Dashboard quickstart" icon="wand-magic-sparkles" href="/quickstart-dashboard">
    The five-step wizard: agent → billing → number → simulation → review.
  </Card>
  <Card title="API quickstart" icon="terminal" href="/quickstart">
    The same first call in four REST calls.
  </Card>
  <Card title="Using the dashboard" icon="table-columns" href="/guides/build-an-agent">
    Build an agent, fund it, get a number, simulate, and review calls.
  </Card>
  <Card title="Connect tools & data" icon="plug" href="/guides/connect-apps">
    OAuth apps, custom APIs, MCP servers, and VoIP providers.
  </Card>
  <Card title="Analyze & improve" icon="chart-line" href="/guides/reports">
    Reports, observability, experiments, issues, and alerts.
  </Card>
  <Card title="Team & account" icon="users" href="/guides/invite-your-team">
    Invites and roles, API keys, security, and SSO.
  </Card>
  <Card title="Developer cookbook" icon="phone-arrow-down-left" href="/guides/handle-inbound-calls">
    The API recipes: inbound, outbound, dynamic config, tools, testing.
  </Card>
  <Card title="Verify webhook signatures" icon="shield-check" href="/guides/verify-webhook-signatures">
    Get the HMAC check right once and reuse everywhere.
  </Card>
</CardGroup>

<!-- en: guides/ask-the-copilot -->
---
title: "Ask the copilot"
description: "The in-app assistant answers product questions, shows you where things are, and can drive the dashboard for you — by text or voice."
---

Every dashboard page has an **Ask Copilot** button in the corner. It
opens a chat panel that knows ThunderPhone and your workspace — the
fastest way to answer "how do I…?" without leaving what you're doing.

## What it can do

**Answer questions.** Ask about anything — features, pricing tiers,
"why did this call fail", "where do I add a teammate". The input
placeholder says it plainly: *Ask Copilot about your workspace…*

**Show you, not just tell you.** When the answer is a place in the app,
the copilot can take you there and point: it navigates to the right
page, highlights the exact control, and offers step-by-step
walkthroughs — look for the **Show me** style offers after an answer.
It can also start any of the guided tours you see in the sidebar's
**Guided tours** menu.

**Make requested changes.** Ask for a specific change — "switch the support
agent to Spanish", "enable silence check-ins", or "point this number at the
sales agent" — and the copilot reads the current state, makes the change, and
reports exactly what it changed. For admins, simple edits go live right away
and can be undone; a fix that changes how the agent behaves is saved as a
draft, checked there, and published once you say yes. A member's edit is
saved as a draft for an admin to publish. If the agent
already has someone else's dashboard draft or the request would rewrite most
of a prompt, the copilot pauses for confirmation instead of overwriting it.

**Propose its own recommendations.** When the copilot discovers an improvement
you did not explicitly request, it uses a **proposal card** with the exact
before-and-after change. Nothing in a proposal is applied until you select
**Apply**; you can also dismiss it.

**Talk instead of type.** Two voice options sit next to the message
box when voice is available:

- **Dictate** — speak once; your words land in the message box for
  review before sending.
- **Voice conversation** — hands-free back-and-forth: it listens,
  answers out loud, and keeps listening. End it with the hang-up
  button. A speaker toggle at the top of the panel also lets you have
  any reply read aloud.

**Hand you to a human.** Flip the panel's toggle to **Talk to a human**
to reach the ThunderPhone team in the same window. When the copilot
loops the team in for you, a banner appears above the message box and
the **Human** tab lights up to show where the support chat lives; your
messages keep going to the copilot until you open it. Support chat
supports image attachments and can escalate to a **live voice call**
inside the panel; if the support engineer needs to see your screen,
you'll get a one-click prompt to share the current tab (with
fullscreen viewing) — sharing is always your choice.

## Workspace analysis and actions

The copilot can work with the current organization rather than answering only
from generic documentation.

| Capability | What you can ask for |
| --- | --- |
| **Organization summary** | List agents and phone numbers, inspect onboarding state, or report the current prepaid balance. |
| **Call analysis** | Filter recent calls, read transcripts and detected insights, calculate call and agent metrics, and cite concrete call IDs in its findings. |
| **Agent creation and configuration** | Create an agent or change its name, prompt, tier, voice, languages, call behavior, and attached API, app, MCP, or knowledge resources. |
| **Phone-number setup** | Get a ThunderPhone number or assign an existing number to an inbound or outbound agent. |
| **Testing** | Create saved scenarios, run selected scenarios or a suite, and retrieve results. Charged test runs require an explicit request and show their cost estimate. |
| **Dashboard guidance** | Open the relevant page, spotlight a control, or offer a verified guided walkthrough. |

The copilot verifies a write before saying it succeeded. It never enters
payment-card details, releases resources, or deletes data. It initiates a
billable test run only when you explicitly request the run and provide the
required charge consent.

## Good things to ask

- "How do I connect HubSpot?"
- "Walk me through creating an API key."
- "Why is my agent's success rate down this week?"
- "Set up an alert for failure rate above 10%."
- "What does whisper do on a live call?"

<Note>
  The copilot works on real organizations — it's not available while
  browsing in demo mode. Guided tours remain available anytime from the
  sidebar's **Guided tours** button.
</Note>

<!-- en: guides/supported-languages -->
---
title: "Supported languages"
description: "Every language ThunderPhone agents can speak, which voices support each one, and which languages are served by premium voices."
---

{/*
  GENERATED FILE — do not edit by hand.
  Source: api/thunderphone_api/data/voice_catalog.json
  Regenerate: python3 scripts/docs-freshness/generate_supported_languages.py
  CI regenerates this page and fails on drift
  (scripts/docs-freshness/generators.d/10-supported-languages.sh).
*/}

ThunderPhone agents speak **47 languages** with **127
voices**. A call starts in the agent's primary language and switches
automatically when a caller uses one of the agent's additional
languages. Set both in the agent builder's **Config** tab, or via the
`primary_language` and `additional_languages` fields on the
[Agent](/api-reference/agents).

## Keep one voice or switch to native voices

By default, the agent keeps its configured voice when it switches languages.
Open **Voice Agents**, select the agent, and in **Config** add at least one
language under **Additional languages**. Turn on **Switch to native voices**, test the
draft in **Talk**, and select **Deploy**.

The switch uses a catalog voice native to the detected additional language,
matched to the configured voice's gender. The agent returns to its configured
voice for the primary language and keeps the current voice if no match is
available. Custom voices do not switch automatically. The switch itself has no
charge. API clients can set
`native_voice_switching: true` through the [Agents API](/api-reference/agents).

There is no language surcharge. The voice is one part of a call's
[price](/guides/pricing), billed at its provider's list price plus the markup:

- **Standard** languages (15) are served by our default voices.
- **Premium** languages (32) are served by premium voices, whose
  list prices are higher, so a minute costs a little more.

Accounts still on their earlier pricing (until December 1, 2026) pay
+5¢/min for a premium language.

<Note>
  Voice availability differs by language — the table shows how many
  voices speak each one. Filter live via
  [`GET /v1/voices?languages=<codes>`](/api-reference/agents#voices);
  the dashboard's voice picker applies the same filter as you select
  languages.
</Note>

| Language | Code | Voices | Voice tier |
|----------|------|--------|---------|
| Arabic | `ar` | 8 | Standard |
| Bengali | `bn` | 8 | Premium |
| Bulgarian | `bg` | 8 | Premium |
| Cantonese | `yue` | 6 | Premium |
| Chinese | `zh` | 8 | Standard |
| Croatian | `hr` | 8 | Premium |
| Czech | `cs` | 8 | Premium |
| Danish | `da` | 8 | Premium |
| Dutch | `nl` | 8 | Standard |
| English | `en` | 50 | Standard |
| Estonian | `et` | 6 | Premium |
| Finnish | `fi` | 8 | Premium |
| French | `fr` | 8 | Standard |
| German | `de` | 8 | Standard |
| Greek | `el` | 8 | Premium |
| Gujarati | `gu` | 8 | Premium |
| Hebrew | `he` | 8 | Standard |
| Hindi | `hi` | 8 | Standard |
| Hungarian | `hu` | 8 | Premium |
| Indonesian | `id` | 8 | Premium |
| Italian | `it` | 8 | Standard |
| Japanese | `ja` | 8 | Standard |
| Kannada | `kn` | 8 | Premium |
| Korean | `ko` | 8 | Standard |
| Latvian | `lv` | 6 | Premium |
| Lithuanian | `lt` | 6 | Premium |
| Malayalam | `ml` | 8 | Premium |
| Marathi | `mr` | 8 | Premium |
| Norwegian | `nb` | 8 | Premium |
| Polish | `pl` | 8 | Standard |
| Portuguese | `pt` | 8 | Standard |
| Punjabi | `pa` | 8 | Premium |
| Romanian | `ro` | 8 | Premium |
| Russian | `ru` | 8 | Standard |
| Serbian | `sr` | 6 | Premium |
| Slovak | `sk` | 8 | Premium |
| Slovenian | `sl` | 6 | Premium |
| Spanish | `es` | 12 | Standard |
| Swahili | `sw` | 6 | Premium |
| Swedish | `sv` | 8 | Premium |
| Tamil | `ta` | 8 | Premium |
| Telugu | `te` | 8 | Premium |
| Thai | `th` | 8 | Premium |
| Turkish | `tr` | 8 | Premium |
| Ukrainian | `uk` | 7 | Premium |
| Urdu | `ur` | 8 | Premium |
| Vietnamese | `vi` | 8 | Premium |

<!-- en: guides/pricing -->
---
title: "ThunderPhone pricing and usage charges"
description: "How ThunderPhone prices calls: each call's parts at our providers' list prices, an infrastructure charge and a markup. Typical prices, price targets and caps, tests, phone numbers and balances."
---

Every new account includes **$10 of free call credit** in its first
organization, with no credit card required. Organizations you add later start
without it. The credit pays for any call: browser tests, phone calls, SIP
calls, web and widget calls, and simulations. Calls use the credit first, then
your cash balance. It cannot pay for phone numbers or voice samples, so add
funds with a card when you want a number.

ThunderPhone is prepaid and pay-as-you-go: no subscription and no seat fee.
Calls draw from the selected organization's balance.

## How a call is priced

Each call costs what its parts cost at our providers' list prices, plus
infrastructure (**15% of the other costs, at least 0.5¢ and at most 2¢ a
minute**), plus a markup. The parts:

| Part | What it covers | Priced at |
| --- | --- | --- |
| **Understanding** | The AI models that decide what your agent says and does, including tool calls and the context they read. | Provider list price |
| **Hearing the caller** | Speech-to-text. | Provider list price |
| **The voice** | Text-to-speech. Premium voices from Cartesia and ElevenLabs cost more per minute than the default Inworld voices. | Provider list price |
| **The phone line** | Carrier minutes on our lines, including transfers and hold. | Carrier list rate |
| **Call review** | Grading, the summary and data extraction after the call. Optional per agent and on by default; turning it off removes its cost, along with call summaries, outcomes, flags and automatic improvement from real calls. | Provider list price |
| **Infrastructure** | Call servers, LiveKit, phone gateways and recording. | 15% of the other costs, 0.5¢ to 2¢ a minute |

### How the price is calculated

1. **Add up the parts.** Each part is priced at our provider's list price.
2. **Add infrastructure.** 15% of those costs, at least 0.5¢ and at most 2¢ a
   minute.
3. **Add the markup.** The markup is **20%** when a call costs 1¢ a minute or
   less, **33%** when it costs 15¢ a minute or more, and rises in a straight
   line in between: 26.5% at 8¢ a minute.

The total is rounded up to the cent. Receipts and Zeus show each call's price
by part, with the markup spread across the parts.

Prices follow our providers' list rates. When a model or voice's list price
drops, your calls cost less, with no action from you. Bigger prompts and large
tool results cost more because the models read more on every reply.

There is no language surcharge. Languages served by premium voices cost a
little more per minute, because those voices' list prices are higher. If you use
your own Cartesia key, Cartesia bills you for the voice and ThunderPhone
charges nothing for it.

On your own carrier, VoIP provider or SIP trunk, your carrier bills its own
minutes and there is no phone-line part.

## Typical prices

What a minute typically costs for three common setups at today's list prices,
markup included, worked out from measured calls.

| Setup | Typical price |
| --- | ---: |
| **Leanest.** Lite intelligence, Lean hearing and Patient reply speed with a standard voice, on your own carrier, with call review off. For simple, structured calls. | **about 2¢/min** |
| **Receptionist.** An inbound front desk on our default settings: Standard intelligence, Standard hearing, an Inworld voice and a ThunderPhone number. | **about 9¢/min** |
| **Premium voice.** The same receptionist with a Cartesia or ElevenLabs voice. | **about 11¢/min** |

Your price depends on your setup. Zeus shows yours before you go live.

## Price targets, hard caps and estimates

Zeus, ThunderPhone's agent builder, sets these for each agent:

- **An estimate before you go live.** Zeus runs simulated calls and shows what
  a minute of your agent costs, then updates it after the first real calls.
- **A price target.** Zeus keeps the agent's settings under it and tells you
  when a change would price above it.
- **A hard cap per call.** A call that reaches the cap ends with a goodbye.
- **Any call's cost by part.** Ask Zeus why a call cost what it did and it
  breaks the price down by part and names the cause, like a large tool result
  or a long call.

## Calls that don't connect or fail

A call that fails to connect because of ThunderPhone is never charged. A call
that uses paid services but connects for no billable minutes, like an
unanswered outbound attempt, is charged what it cost plus the markup.

## Hold time, phone menus and transfers

Hold time, automated phone menus and call screeners are billed like any other
minute, at what their parts cost plus the markup.

When your agent hands a call off with a cold transfer, your carrier takes the
call over and ThunderPhone's charges stop when the agent leaves. When
ThunderPhone keeps the transferred call connected itself, that connected time
bills what it costs, the phone legs plus infrastructure, plus the markup: about
{/* rate:cost-plus-bridge-number */}1.6¢/min{/* /rate */} on a ThunderPhone number ({/* rate:cost-plus-bridge-number-outbound */}1.8¢/min{/* /rate */} on an outbound
call) and {/* rate:cost-plus-bridge-own-carrier */}0.6¢/min{/* /rate */} on your own carrier. This covers a warm transfer after
the agent drops off, and a cold transfer your carrier refused. Accounts still
on their earlier pricing pay {/* rate:transfer-bridge */}1¢/min{/* /rate */} plus the phone line until
December 1, 2026. See [Call transfers](/guides/call-transfers).

## Simulations and testing

Test and simulated calls are billed the same way as real calls. An AI
simulation also runs a simulated caller, counted in the call's cost at
{/* rate:cost-plus-simulated-caller */}3¢/min{/* /rate */}, so infrastructure and the markup apply to it as to
any other part. There is no separate caller fee or multiplier. Accounts still
on their earlier pricing pay a flat {/* rate:simulated-caller */}5¢/min{/* /rate */} for the simulated
caller until December 1, 2026. The launch dialog shows an estimate and requires
explicit approval. Saved scenario suites and validation runs display their
own estimate before or during execution.

## Phone numbers

{/* rate:phone-numbers */}

| Number type | ThunderPhone charge |
| --- | --- |
| **ThunderPhone number** | **$1/month**. Its call minutes are part of the phone line. An organization can hold 25 by default; request a higher limit from the Phone numbers page. |
| **Imported VoIP number** | No ThunderPhone import or monthly-number charge. Your VoIP provider continues to bill its own number and telephony usage. |

{/* /rate */}

Provisioning or releasing a ThunderPhone number starts or stops its monthly billing.
Deleting an imported number disconnects it from ThunderPhone but does not
cancel it with the provider.

## Existing customers

Accounts created before this pricing launched keep their current prices until
**December 1, 2026**. Then the new pricing applies automatically. You can switch
earlier from **Billing**; the switch is one way.

## Contracts and enterprise

Customers on a contract keep the terms of their contract. For a contract or
volume pricing, [talk to us](mailto:sales@thunderphone.com).

## One-time charges

- **Generated voice sample:** **3¢** for a new voice/text/language sample;
  identical cached samples are free.
- Other billed operations present an estimate or confirmation before charging
  the organization balance.

## Balance, top-ups, and spending controls

Add a payment method and at least **$3.00** to begin making real calls. Funds do
not expire. Manual top-ups add a chosen amount immediately.

Optional auto top-up has three controls:

- Balance threshold that triggers the refill.
- Refill amount, at least $1.
- Optional monthly spending limit. When reached, new calls and usage pause
  until the next month or a higher limit; alerts are sent at 80% and 100%.

The monthly limit remains effective even if auto top-up is later disabled.
See [Billing and top-ups](/guides/billing-and-topups) and the
[Billing API](/api-reference/billing) for account and transaction operations.

<!-- en: guides/dashboard-overview -->
---
title: "Dashboard home: calls, success, issues, and live activity"
description: "Use the ThunderPhone dashboard home to track call volume, success rate, duration, issues, and live or queued calls by agent or phone number."
---

The dashboard home (`/dashboard`) is the operational summary for the
organization you currently have selected. It combines recent call volume,
quality, open issues, and calls happening now, with links into the detailed
workspaces behind each number.

<Note>
  New organizations see the five-step setup checklist first. Complete or skip
  it to reach the operational dashboard. You can replay its walkthroughs from
  **Guided tours** in the sidebar; see the
  [dashboard quickstart](/quickstart-dashboard).
</Note>

## Choose the time window

The call-volume chart supports **7**, **14**, and **30 day** windows. Changing
the window updates the chart and the summary table below it.

Use **Group by** to switch between:

- **Agents** — one series and one summary row per voice agent.
- **Numbers** — one series and one summary row per phone number. Number labels
  appear in place of raw numbers when you have added them.

The chart shows calls over time. Hover a point to inspect the date and the
series contributing calls on that day.

## Read the summary table

Each agent or phone-number row reports:

| Column | Meaning |
| --- | --- |
| **Calls** | Calls in the selected time window. |
| **Success** | Percentage of calls with a gradeable successful outcome. Calls without a final outcome do not inflate the percentage. |
| **Duration** | Average completed-call duration in minutes. |
| **Issues** | Open issue reports associated with the agent or number. |

Select a row to open **Call History** with the corresponding agent, number,
and date window already applied. For a number that handles both directions,
the link uses its predominant call direction for the filter.

## Needs attention

**Needs attention** groups unresolved issue reports by title and shows the
number of affected calls. Select a row to open that issue pattern on the
[Issues page](/guides/issues), or choose **All issues** for the complete triage
queue.

When there are no open issues, the panel reports that operational checks are
clear.

## Live and queued calls

**Live & queued calls** shows up to four calls that are in progress or waiting
to start, including:

- Inbound, outbound, or web-call direction.
- The caller or callee, using your saved phone-number label when available.
- The assigned agent.
- A **Live** or **Queued** status.

If more than four calls are active, the final row reports the additional
count. Open **Call history** to see the complete list, or use
[Live monitoring](/guides/monitor-live-calls) to listen and coach an in-progress
call.

## Organization switching

Every number on this page belongs to the organization selected in the sidebar.
Switching organizations changes the agents, numbers, calls, issues, and billing
context together. See [Organization settings](/guides/organization-settings)
for the settings that apply at that boundary.

<!-- en: guides/build-an-agent -->
---
title: "Build your first voice agent"
description: "The agent builder end-to-end: write the prompt, pick an engine, voice, and languages, attach tools and knowledge, talk to your draft, and deploy it to production."
---

Everything about an agent lives in the builder at **Voice Agents**
(`/dashboard/agents`) — create one and you land in it. This guide
walks the same path as the in-app "Build an agent" tour.

<Tip>
  First time here? The [dashboard quickstart](/quickstart-dashboard)
  wraps this page plus billing, numbers, and simulations into the
  five-step setup wizard. Already have agents on Vapi, Retell, ElevenLabs
  Agents, or Bland? [Import them](/guides/import-agents) instead of
  rebuilding.
</Tip>

## Start from a template

**Create agent → Start from a template** opens a picker of ready-made
agents. Everything is editable afterwards.

- **Interpreter** — a real-time two-way phone interpreter between two
  languages. Pick your language and the caller's language, a voice that
  speaks both, and confirm the intro the interpreter says at the start
  of every call (spoken in the non-English language; in both when
  neither is English). The agent opens fully configured on Storm at the
  standard rate; give the number to your team and add the other party
  with 3-way calling.
- **Receptionist** — the sample front-desk prompt from the onboarding
  tour: greets callers, books appointments, answers questions, transfers
  the rest.
- **Appointment scheduler** — takes booking, rescheduling and
  cancellation requests: collects the caller's name, number, and
  preferred day and time, reads the request back, and tells the caller
  the office will confirm. There is no calendar integration, so it never
  claims a booking is confirmed; give it a transfer number for anything
  it can't handle.
- **After-hours message taker** — greets, takes the caller's name,
  callback number and reason, reads them back, and ends the call. Give
  it an urgent-calls number and it transfers callers who say it's
  urgent; give it an email and it sends you a summary after each call.
- **Call router** — a phone-menu replacement. Asks in one sentence what
  the caller needs, transfers to the matching department (up to three,
  each with a name and number), and takes a message when nothing fits.
- **Lead qualifier** — screens calls from your ads: confirms what the
  caller wants, asks three qualifying questions (what, when, and a rough
  budget or size), reads the answers back, then transfers to your sales
  number or promises a callback.
- **Info line** — answers hours, location, directions, pricing and
  policy questions from the [knowledge](/guides/knowledge-base) you
  attach, says so when it doesn't know, and never invents facts. After
  creating it, add your website or documents under **Knowledge**.
- **Phone intake form** — walks the caller through a fixed list of
  fields (name, phone, email, address, reason), confirms each, reads
  the whole form back, and emails it to you.

The six business templates share one setup step — your business name,
a one-line "what you do", and optionally a transfer number and an email
for messages — and write a prompt in the
[prompting guide's](/guides/prompting) shape. Transfers are plain prompt
lines ("transfer the call to …"), the email goes through the agent's
send-email setting, and the agent is named after your business. **Start from scratch** in the same menu opens an
empty editor instead.

## 1. Write the prompt

The prompt is the script for your voice agent. Describe — in any
language — who the agent is and how it should handle the call: its
persona, what it knows, what it should and shouldn't do.

Transfers, keypad presses, hold, email, sounds, and hang-ups are prompted
actions. See [Built-in tools](/guides/built-in-tools), and use [Transfer
calls](/guides/call-transfers) for cold and screened warm handoffs.

If the call has phases that must happen in order, such as verifying a caller
before booking, split the agent into [steps](/guides/agent-steps) instead.

<Tip>
  Specific beats general. "Confirm the order number back to the caller
  before making changes" outperforms "be careful with orders."
</Tip>

## 2. Pick an engine

On the **Config** tab, the engine picker trades off cost and
performance across three tiers — **Spark** is optimized for cost,
**Bolt** for speed, **Storm** for intelligence on complex prompts.
Each card shows its per-minute price. Switch anytime; see the
[full pricing reference](/guides/pricing) and
[agent setting reference](/guides/agent-settings).

## 3. Choose a voice and languages

Pick a voice and play its sample right in the builder. Set the
**primary language** the call starts in, plus any **additional
languages** — the agent switches automatically when a caller uses one.
The voice list filters to voices that support every language you've
selected. See [Supported languages](/guides/supported-languages) for
the full catalog.

## 4. Attach tools and knowledge

Four sections on the Config tab give the agent capabilities:

- **Connected apps** — the easiest path:
  [connect Slack, HubSpot, Google & more](/guides/connect-apps) in a
  few clicks, then let your agent use them during calls.
- **API connections** — for any other API,
  [create an API connection](/guides/api-connections) for the actions
  your agent needs (paste a cURL command and the AI wizard drafts the
  tool).
- **Knowledge** — attach a
  [knowledge base](/guides/knowledge-base) the agent can search
  mid-call.
- **MCP servers** — [add an MCP server](/guides/mcp-servers) by URL.

See [Connections](/guides/concepts#connections) for how the four kinds
differ.

Advanced options below the endpoint sections control supervision, connection
tone, tool sounds, who speaks first, voicemail, the call-start consent
announcement, and silence check-ins. See
[Every agent setting](/guides/agent-settings#advanced-call-behavior).

## 5. Check your price

Each call costs what its parts cost at our providers' list prices, plus a
infrastructure charge and a markup. Zeus shows what a minute of your
agent costs before you go live, and you can set a price target and a hard
cap per call. See [pricing](/guides/pricing).

## 6. Talk to it

Click **Talk** and say hello — your agent answers right in the browser
(it'll ask for mic access). This is the fastest iteration loop:
tweak the prompt, talk, repeat. When you want a caller on the other
end instead of yourself, [run a simulation](/guides/simulate-a-call).

## 7. Deploy

Every edit **autosaves to your draft** — watch for "Saved" in the top
bar. Draft changes aren't live until you click **Deploy**.

Every deploy is snapshotted in the **History** tab: inspect what
changed between versions and restore any previous one. That makes
deploys safe to do often — you can always roll back.

## 8. Connect it to the world

The Config tab's **Phone numbers** and **Web widgets** sections attach
endpoints without leaving the builder — attach an existing number,
get a new ThunderPhone number, import via VoIP, or link a web widget.

---

## Next steps

<CardGroup cols={2}>
  <Card title="Get a phone number" icon="phone" href="/guides/get-a-phone-number">
    ThunderPhone number in seconds, or bring your own via VoIP.
  </Card>
  <Card title="Simulate a call" icon="flask" href="/guides/simulate-a-call">
    An AI caller has a real conversation with your agent.
  </Card>
  <Card title="Review the calls" icon="headset" href="/guides/review-calls">
    Transcripts, recordings, live listen-in, and whisper.
  </Card>
  <Card title="Agents API reference" icon="code" href="/api-reference/agents">
    Create and manage agents programmatically.
  </Card>
  <Card title="Every agent setting" icon="sliders" href="/guides/agent-settings">
    Complete options, ranges, behavior, and pricing.
  </Card>
</CardGroup>

<!-- en: guides/import-agents -->
---
title: "Import agents from another platform"
description: "Bring agents, tools, and knowledge bases over from Vapi, Retell, ElevenLabs Agents, or Bland with an API key or a JSON export, review the mapping, and import."
---

If your agents live on Vapi, Retell, ElevenLabs Agents, or Bland, the
importer fetches them, maps every field onto ThunderPhone, and shows you the
result before anything is created.

<Note>
  Your API key is used only for the import. It is encrypted while the
  inventory is fetched and deleted as soon as the fetch completes — and on
  any failure or discard. Admin role is required to start or commit an
  import.
</Note>

## Start an import

1. Open **Agents** and choose **Import** (or **Import from Vapi, Retell,
   ElevenLabs, or Bland** on an empty agents page).
2. Pick the platform.
3. Follow the numbered steps in the dialog to create a key on that platform
   (they open the right settings page for you), paste it, or switch to
   **Paste exported JSON** and paste one or more agent objects from that
   platform's dashboard or API.
4. Choose **Fetch my agents**. Fetching and mapping usually takes under a
   minute; you can leave the page and come back through the task tray.

## Review the plan

Each agent shows the name, matched voice (with how confident the match is),
intelligence tier, the tools and knowledge bases it brings, and notes about
anything that changed in translation. Expand a row to read the prompt:

- **Rewritten** — one coherent prompt in the style of the
  [prompting guide](/guides/prompting), with every phone number, URL, tool
  name, and placeholder from the source preserved.
- **Structured** — the source config laid out under headings, exactly as
  extracted. Used automatically when the rewrite cannot be verified, or when
  the rewrite came out much shorter than the source.

An agent imported from a flow shows **Shared instructions** instead of the
prompt, followed by its steps: each step's name, what it tells the agent to
do, and where it goes next. **Show as one prompt** shows the same agent as a
single prompt, which is what it runs wherever steps are not available.
Agents with handoffs list the agents they hand the caller to; if you untick
one of those, the review says that handoff will not be set up.

Every agent starts selected except empty ones and default starter agents
the platform created for you. Untick agents you do not want, edit names,
voices, tiers, or the prompt choice, then **Import**. Created agents open in
the builder with their API connections and knowledge attached.

## Flows, Squads and agent transfers

Multi-step agents keep their structure. See [Agent steps](/guides/agent-steps)
for how steps and handoffs run on a call.

- **Flows become steps.** Retell multi-prompt states and conversation flows,
  Bland pathways and ElevenLabs workflows import as the agent's steps. The
  source's global prompt becomes the shared instructions.
  - Each node's instructions, fixed line, values to collect and tools carry
    over.
  - Edge conditions written in words become transitions the agent decides.
    A single comparison on a collected value or a webhook response
    (`age >= 18`) becomes a transition that is checked exactly.
  - Webhook and function nodes run their tool as the step starts. Global
    nodes can be reached from any step; one with no ways forward of its own
    hands the call back to the step it interrupted.
  - Transfer and end nodes become last steps that transfer or end the call.
    A Retell transfer node keeps its way out for when the transfer does not
    go through.
  - A branch node that only picks the next step is merged into the step
    before it when it can be. Otherwise it stays a step of its own, with a
    note.
  - A flow that is too large for steps, or that ThunderPhone cannot represent
    as steps, is imported as one prompt that lists every step, with a note.
- **Squads, agent transfers and agent swaps become handoffs.** Each member
  of a Vapi Squad is imported as its own agent, named after the member and the
  Squad. The first member answers the Squad's calls and the others are reached
  by handoff. ElevenLabs transfers to another agent and Retell agent swaps
  become handoffs too. The caller stays on the line and the conversation so far
  carries over.
  - A call reached by handoff keeps the call settings of the agent that
    answered it: voicemail, call limits, languages and recording. The agent
    it hands off to brings its own prompt, steps, tools and voice.
  - A handoff can only point at an agent imported in the same run. If the
    other agent is not in the import, or you untick it, the note says so and
    you can add the handoff later in the agent's settings.

## What is imported

<Tabs>
  <Tab title="Vapi">
    **Getting a key**

    1. Open [dashboard.vapi.ai/org/api-keys](https://dashboard.vapi.ai/org/api-keys)
       (Organization settings → API Keys).
    2. Create a key and choose **Private** — public keys cannot list
       assistants.
    3. Copy it into the dialog. Vapi keys are not scoped; delete the key in
       Vapi after the import if you created it only for this.

    | Vapi field | ThunderPhone |
    |---|---|
    | `model.messages[system]` | Prompt |
    | `firstMessage`, `firstMessageMode` | Opening line in the prompt; who speaks first |
    | `voice.provider` + `voiceId` | Closest catalog voice, with best-effort Vapi library lookup (match confidence shown) |
    | `transcriber.language`, `languages`, keywords/keyterms | Languages and speech-recognition vocabulary |
    | `model.model` | Intelligence tier |
    | `model.tools`, `toolIds`, `toolRefs` (function, apiRequest) | API connections; Vapi request envelopes and assistant-level server fallbacks are preserved |
    | `transferCall` destinations | Phone transfers in the prompt; SIP, assistant, and dynamic destinations are reported for review |
    | `handoff` tools | Handoffs to the named assistants imported in the same run |
    | `endCall`, `dtmf` | Built-ins |
    | Google Calendar, Google Sheets, Slack, `sms` | Reported with the ThunderPhone integration or SMS setup needed |
    | `query` and `knowledgeBase` tools, plus legacy `knowledgeBaseId` | Knowledge base with accessible uploaded files as documents |
    | `endCallMessage`, `endCallPhrases`, `voicemailMessage`, idle-message plans and timeout hooks | Prompt sections; voicemail and silence settings |
    | `maxDurationSeconds`, recording opt-outs | Maximum call length (Vapi's 600-second default is kept); a recording opt-out is reported on the review page |
    | Squads | One agent per member, with its own prompt, overrides, voice, tools, and knowledge. `assistantDestinations` become handoffs between them; the first member keeps the Squad's numbers |
    | Custom knowledge/model servers, compliance plans, other hooks, workflows and unsupported hosted tools | Reported with a specific review or rebuild action; raw plans and credentials are not stored |
  </Tab>
  <Tab title="Retell">
    **Getting a key**

    1. Open [dashboard.retellai.com/apiKeys](https://dashboard.retellai.com/apiKeys)
       (System settings → API Keys) and choose **Create key**.
    2. Turn on **Restrict permissions** and set **Agent**, **Knowledge base**,
       and **Phone** to **Read**. Leave every other group unchecked; the
       importer never writes to Retell.
    3. Copy the key into the dialog.

    | Retell field | ThunderPhone |
    |---|---|
    | Latest published agent + its exact Retell LLM / flow version | Published prompt and behavior; newer drafts are reported for review |
    | Retell LLM `general_prompt`, `begin_message`, `start_speaker`, states | Shared instructions; opening behavior; one step per state, with its tools and transitions and the values each transition collected |
    | Conversation flow `global_prompt`, nodes, components, global nodes, and edges | Shared instructions and steps; equation conditions on collected values are checked exactly; exact opening text and transfer steps |
    | `agent_swap` tools and nodes | Handoffs to the Retell agents imported in the same run |
    | Custom tools | API connections with query parameters, timeout, and Retell/args-only request shape; a signature change and any non-default speech, retry, response-variable, or form-encoding setting are reported |
    | `transfer_call`, `end_call`, `press_digit` | Conditional transfers (including extensions) + built-ins; inferred and warm-transfer differences are reported |
    | `check_availability_cal`, `book_appointment_cal` | Reported as Cal.com tools to reconnect under Integrations; Retell credentials never carry over |
    | `send_sms`, MCP | Reported with SMS or MCP setup instructions |
    | `voice_id` (`11labs-`, `openai-`, `cartesia-`, …) | Closest catalog voice |
    | `language` (one locale, multilingual mode, or a locale list) | Primary and additional languages |
    | `model` / `s2s_model` | Intelligence tier |
    | `knowledge_base_ids` (url, document, text sources) | Knowledge base with documents |
    | `default_dynamic_variables`, supported system variables | ThunderPhone variable defaults and plain call-context instructions |
    | `voicemail_option`, `end_call_after_silence_ms`, `max_call_duration_ms`, `ring_duration_ms`, recording disabled, `boosted_keywords` | Voicemail behavior; call limits; recording setting; prompt terms |
    | `webhook_url`, custom-LLM engines, unsupported flow nodes and vendor-only settings | Reported for manual review, not silently dropped |
  </Tab>
  <Tab title="ElevenLabs Agents">
    **Getting a key**

    1. Open [elevenlabs.io/app/settings/api-keys](https://elevenlabs.io/app/settings/api-keys)
       and choose **Create API key**.
    2. Under permissions, give it **Agents Platform: Read**
       (and **Knowledge base: Read** if shown); the importer needs nothing
       else.
    3. Copy the key into the dialog.

    | ElevenLabs field | ThunderPhone |
    |---|---|
    | `conversation_config.agent.prompt.prompt`, Agent Workflow nodes and ordered branch conditions | Shared instructions and one step per workflow node; tool nodes run their tool as the step starts; expression branches are labelled for review |
    | `first_message`, `language`, `language_presets` | Opening line; primary and additional languages; translated openings |
    | `prompt.llm` | Intelligence tier |
    | `tts.voice_id` | Closest catalog voice |
    | webhook `tool_ids`, including tools attached to workflow steps | API connections with portable body/query parameters; fixed vendor parameters and credentials are removed and reported |
    | `built_in_tools` for end call, phone transfer, keypad, and voicemail | Built-ins, transfer rules, and voicemail behavior; SIP and dynamic destinations are reported for rebuilding |
    | Transfers to another agent (`transfer_to_agent`, agent workflow nodes) | Handoffs to the ElevenLabs agents imported in the same run |
    | `knowledge_base` url/text/file/folder entries, including workflow-step knowledge | Knowledge base documents; folders are expanded and text/file content is fetched by id |
    | `turn.silence_end_call_timeout`, `conversation.max_duration_seconds`, `asr.keywords`, `privacy.record_voice` | Silence and maximum-duration limits; pronunciation terms; recording turned off is reported on the review page |
    | custom LLMs, MCP servers, procedures, workspace webhooks, per-step model/voice/language overrides, ElevenLabs booking tools | Reported with the action needed after import |
  </Tab>
  <Tab title="Bland">
    **Getting a key**

    1. Open [app.bland.ai/dashboard/settings](https://app.bland.ai/dashboard/settings).
    2. Copy the **API key** shown there (Bland has one key per account; it is
       not scoped, so rotate it afterwards if you prefer).
    3. Paste it into the dialog.

    Bland display labels are not treated as the agent's identity. The importer
    derives who the agent says it is from the greeting and prompt; for a
    pathway it uses the global prompt and start node. If that check is
    unavailable or finds no name, the imported prompt stays neutral.

    | Bland field | ThunderPhone |
    |---|---|
    | Web agent `prompt`, `first_sentence`, `language`, `model`, `voice`, `pathway_id` | Prompt; opening line; language; tier; closest voice; attached published pathway flow |
    | Persona production version | Personality and orchestration prompts; voice; language; caller-first setting; recording; maximum duration; default tools and knowledge. A single attached pathway is included; multiple-pathway routing is reported for manual setup |
    | Custom and pathway tools (url, method, schema, headers, body variables) | API connections. Bland Secret references are reported and must be added again |
    | Cal.com, Slack, HubSpot, Salesforce, Google Calendar, and Google Sheets tools | Matching ThunderPhone integration is named for you to connect and enable |
    | Inbound number detail (`prompt`, `pathway_id` / version, tools, transfers, keywords, request data) | One agent per inbound number, with call-variable defaults and transfer rules |
    | Every pathway, attached to a number or not | Published version when available; an unpublished draft is clearly flagged |
    | Global prompt; Default, Knowledge Base, Transfer Call, End Call, Webhook, and Wait for Response nodes; edges, loop conditions, global nodes, extracted variables, static speech | Shared instructions and one step per node, including any-time steps, values to collect, exact speech, webhook steps, transfers, and hang-ups. Webhook response pathways on a response field or extracted variable are checked exactly |
    | Inline knowledge text and resolvable knowledge ids | Knowledge documents. Items whose text or file cannot be read are reported for manual upload |
    | `max_duration`, `wait_for_greeting`, recording setting | Call limit, speaking order, recording setting |
    | `webhook`, dynamic-data lookups, multi-path persona routing, unsupported node settings, v2 agents | Reported with the manual follow-up needed |
    | Inbound numbers | Listed with both options, since Bland does not say whether it or your Twilio account owns them |
  </Tab>
</Tabs>

## What needs a step on ThunderPhone

The report at the bottom of the review page lists numbers, webhooks, and
tools that did not move; each agent's notes cover the rest. Together they
show everything that did not move and why:

- **Phone numbers.** After the import, each source number shows where it
  lives and what you can do with it:
  - **In your own Twilio or Telnyx account** (for example a Twilio number you
    connected to Vapi or ElevenLabs): an admin can move it to an imported
    agent. If no [VoIP connection](/guides/bring-your-own-numbers) holds that
    account yet, connect it first. Before anything changes, a confirm step
    says that calls to the number will stop going to the old platform.
    ThunderPhone then points the number at itself in your carrier account (a
    Twilio number joins ThunderPhone's SIP trunk; a Telnyx number moves to
    ThunderPhone's SIP connection) and places a short test call to switch it
    on. To undo it, delete the number on **Phone numbers**, keeping it in your
    carrier account, then re-import it on the old platform.
  - **On your SIP trunk**: connect the trunk as a
    [SIP connection](/guides/voip-providers#manual-sip-configuration) and
    import the number on **Phone numbers**.
  - **Sold by the platform** (Vapi, Retell and Bland numbers bought there):
    ThunderPhone cannot move it. Port it to a carrier and import it, or get a
    ThunderPhone number and attach it to the imported agent.
  - Bland does not say whether a number is its own or from your Twilio
    account, so Bland numbers show both options.
- **Per-agent webhooks.** ThunderPhone delivers signed webhooks per
  organization; set one up under [Webhooks](/webhooks/overview).
- **Vendor-stored credentials.** Tool headers that were visible are copied.
  Credentials the old platform stored by id are flagged; add them to the API
  connection's headers.
- **Built-in integrations.** Calendar, CRM, and messaging tools the old
  platform hosted (for example Cal.com booking) are named with the
  ThunderPhone integration to connect instead; their credentials do not
  carry over. The review also flags a prompt that still tells the agent to
  use a tool that was not imported.
- **Text messages.** ThunderPhone agents text through your own carrier
  connection; set up SMS in the agent's settings.
- **Tools without an equivalent** (platform-specific automations) are listed
  so nothing is dropped silently.
- **Call variables.** `{{name}}` placeholders are kept, with the defaults
  your platform had. ThunderPhone fills them from the
  [variables passed when a call starts](/guides/call-variables) and leaves
  them blank otherwise; the review lists the ones you need to pass.
- **Call limits and recording.** The maximum call length is imported. When
  the source agent never changed it, the platform's own default is set: 10
  minutes for Vapi and ElevenLabs, 1 hour for Retell, 30 minutes for Bland. A
  source value that is not a positive number imports with no maximum, and the
  review says so. Silence and maximum-duration limits outside ThunderPhone's
  ranges are adjusted, and the review note names the source value and the
  imported one. When the source agent had call recording turned off, the
  agent's review note says whether it is imported with recording off or,
  where turning recording off is not yet available, with recording on.

## What changes when you import

A few settings your old platform left at its own default take ThunderPhone's
default instead. The review lists them in one note per agent, under
**Show details**, only where the two platforms differ. The ThunderPhone
figures below are its defaults, which you can change per agent:

| Setting | Old platform default | ThunderPhone default |
|---|---|---|
| Ring time on outbound calls | Retell: 30 seconds | 60 seconds |
| Ending a silent call | Retell: hang up after 10 minutes; ElevenLabs: never | Check in every 15 seconds (after about 6 seconds if nobody has spoken yet, after at least a minute if the caller asked the agent to wait), hang up after 1 minute of silence |
| Call recording | Bland inbound numbers and personas: off | On. Contact support, or change it in the agent's settings where available |
| At a voicemail | Bland personas: hang up | The agent decides from its prompt |

A setting you changed on the old platform is imported as you set it, not
listed here. The one exception is a silent-call setting of "never hang up":
it is listed like a default, and the agent keeps ThunderPhone's check-ins.
Change any of these in the agent's settings after import.

## Importing without a key

Choose **Paste exported JSON** and paste the object(s) your platform's API
or dashboard exports, as one object or a JSON list:

- **Vapi** — an assistant object (`GET /assistant/{id}`), a Squad object
  (`GET /squad/{id}`), or a list of either. Tools attached only by id and
  knowledge files need a key to resolve. Vapi retired Workflows, so convert a
  Workflow to a Squad before pasting it.
- **Retell** — the agent object (`GET /get-agent/{id}?version=...`) **together
  with** its same-version Retell LLM (`GET /get-retell-llm/{id}?version=...`)
  or conversation flow object in the same list. The importer links by id and
  version, prefers a pasted published agent when publication status is present,
  and imports a standalone LLM or flow under a generated name.
- **ElevenLabs** — the agent object (`GET /v1/convai/agents/{id}`). Current
  exports usually reference webhook tools and knowledge documents only by id.
  A paste reports those items as unresolved; use an API key for a complete import.
- **Bland** — a web agent, the `/v1/agents` response, or a pathway object.
  Each pasted object imports as its own agent, even when two share an id;
  tool and knowledge ids that need API access are listed for manual setup
  instead of being dropped.

Anything referenced only by id and not present in the paste is listed in the
notes.

## After the import

1. Open each agent and read its notes.
2. Place a test call from the builder.
3. Move your numbers over, or attach a new one (see **Phone numbers** above).
4. Test each API connection with the request tester.
5. Check that knowledge documents finished indexing.
6. Set an organization webhook if the old agents used one.

The importer is also available over the [REST API](/api-reference/agent-imports).

<!-- en: guides/prompting -->
---
title: "Prompting guide"
description: "How to write a voice agent's prompt that sounds natural on the phone and holds up under real callers, with three templates to start from."
---

Write the prompt the way you would brief a new receptionist: who they are
and who they work for, how a call goes from the first line to the last, and
the facts they may give out, in plain language and in any language. A
caller hears the agent once, at speaking pace, and the agent reads the
prompt on every turn and copies its wording closely. This page shows how
to write for both, and gives three complete templates to start from.

The [prompt style guide](/guides/prompt-style) has every guideline in one
place, with the ids (P1, W2 and so on) that
[prompt review](/api-reference/agents#review-a-prompt) cites when it checks
a prompt.

<Tip>
  Migrating from another platform? The [importer](/guides/import-agents)
  brings your agents over and rewrites each prompt to this guide's
  structure. For a one-off prompt, you can also paste it — or the whole
  exported agent JSON — into the [copilot](/guides/ask-the-copilot).
</Tip>

## Write the call in the order it happens

A short opening says who the agent is and how it talks. The call then
follows in the order it happens: how it opens, what to find out, what to
confirm, how it ends. Each rule sits in the step where it applies, not in a
list of rules at the end. Plain headings help:

```text
# Who you are
Your name, the business you represent, and in a few words how you talk:
short turns, warm, plain words.

# The call
How you open, what you find out and in what order, what you confirm, and
how the call ends. Each rule goes in the step where it comes up.

# Facts
What you may tell callers: hours, location, services, prices, policies.

# Handing off
When a person should take over, which transfer number to use, and what to
offer when nobody can.
```

Lists are fine for facts the agent looks things up in, such as hours or
prices. For behavior, write prose: a numbered list of rules, code-like
headings or "see section 4" make the prompt harder to follow and to edit.

The builder's prompt editor shows estimated tokens as you type and flags
common problems — an empty prompt, placeholders that won't be filled in,
or no way to hand a caller off. Longer prompts cost more per minute, because
the models read the prompt on every reply; see [pricing](/guides/pricing).

## Tactics that matter on a phone call

### Specific beats general

Vague instructions produce vague agents. Name the behavior you want:

| Instead of | Write |
| --- | --- |
| "Be careful with orders." | "Read the order number back and ask the caller to confirm it before you change anything." |
| "Be professional." | "Use the caller's name once you have it, and keep each turn to a sentence or two." |
| "Help with scheduling." | "Offer the two earliest open times, then ask which works." |

### Write for the ear, not the eye

Callers hear the agent and can't skim or re-read. Ask for short turns and
one question at a time, with the question as the last thing the agent says:
anything after it talks over the caller's answer.

```text
Keep each turn to one or two short sentences unless the caller asks for
more. Ask one question at a time, and make it the last thing you say.
```

Keep symbols out of anything the agent will say: slashes, ampersands, "@",
".com" and phone numbers written without spaces come out oddly in speech. Spell out how an
unusual name or acronym is said, and listen to new terms in the agent's
voice with **Talk** before you keep them.

### Confirm what would be costly to get wrong

Speech recognition mishears names, digits and addresses. Say in the flow
what to confirm, at the step where the agent collects it:

```text
Once you have the callback number, read it back and ask the caller to
confirm it before you book the appointment.
```

Ask for the read-back in the form the value was given — an email address
letter by letter, a phone number digit by digit. A summary read-back ("so
that's your Gmail") confirms nothing. How fast the agent reads it back is
the platform's job, so the prompt only says what to confirm.

### Pick Storm when the call turns on a spelled-out string

Phone audio is 8 kHz. Emails, surnames, confirmation codes, and
policy numbers are where that bandwidth runs out: "M" and "N" are
close, the caller's "dot" survives as a word, and the domain comes
back one letter off.

Bolt transcribes the audio to text first and reasons over the
transcript, so whatever the transcript lost is already gone. Storm
hears the audio itself and is markedly better on spelled-out strings.
If a call is only useful when the email or the reference number is
exactly right, that difference is worth more than the price gap — see
[model tiers](/guides/agent-settings#model-tier).

Then put the check somewhere the prompt can't skip: declare
`"format": "email"` on the tool parameter that receives the address.
ThunderPhone repairs the usual transcript artifacts, and rejects what
it can't repair before your endpoint runs, so the agent re-asks
instead of writing a bad address into your system. See
[Build a tool integration](/guides/build-tool-integration).

### Describe the hard moments, not the words

The happy path writes itself; calls are won and lost everywhere else. For
each situation you can foresee — a question the prompt doesn't cover, an
upset caller, a wrong number — say what the agent should achieve and what
it may offer, in the step where it comes up. Leave out "if the caller says
X, say Y" lines: the agent repeats a scripted line word for word, so it
sounds canned, and a list of branches leaves out the cases between them.

```text
When a caller asks something these instructions don't cover, offer to have
a teammate call them back, and take their name and number.
When a caller is upset, acknowledge it once and keep to what you can do
for them. If they would rather talk to a person, transfer them to Front
desk.
```

The opening greeting is the one line to write out word for word. When an
example of wording helps elsewhere, give a few varied, full sentences and
introduce them as examples ("For example, you might say ..."); clipped
tags like "Still accurate?" sound terse once spoken.

### Give every call somewhere to go

Every agent needs a way to hand off — a transfer number, a callback
promise, or both. The prompt editor warns when it can't find one.

### Describe call actions in the flow

Transfers, keypad presses, hold, and hang-ups need no separate tool —
describe them in the step where they happen. Transfers go to the
[transfer numbers](/guides/call-transfers) saved on the agent, by name; the
agent sees only the names.

```text
When the caller asks for a person, transfer them to Front desk.
When the phone menu asks for a department, press 2.
If you reach the billing menu, wait on hold until a person answers.
Once the caller has nothing else, say goodbye and end the call.
```

For routing rules, screened handoffs, and failure fallbacks, see [Transfer
calls](/guides/call-transfers). For all other platform actions, see [Built-in
tools](/guides/built-in-tools).

### Leave settings to the settings

Some things are agent settings, and prompt text about them is ignored or
conflicts with them: what the agent says while a tool runs, filler
phrases, silence check-ins and what happens after a long silence, how a
read-back is paced, the language-switching style, the recording notice,
and whether the agent or the caller speaks first. Set those in
[agent settings](/guides/agent-settings#settings-win-over-the-prompt), and
keep the prompt on the outcome ("confirm the email address before you save
it"). The opening greeting itself is written in the prompt.

### Facts belong in knowledge, behavior in the prompt

Don't paste your website into the prompt. Attach a
[knowledge base](/guides/knowledge-base) and the agent searches it
mid-call — the prompt stays short, and updating a policy doesn't mean
re-editing the prompt. Keep the prompt for who the agent is, how the call
runs and the few facts every call needs; put catalogs, FAQs, and long
policy text in knowledge. The agent may say only facts it was given.

### Personalize per call with variables or dynamic config

A placeholder such as `{{customer_name}}` in the prompt is filled from the
`variables` you send when a call starts; see
[per-call variables](/guides/call-variables). A placeholder with no value
on a call becomes empty text. The builder lists the prompt's placeholders
as a reminder that nothing fills them unless the call sends `variables`,
test calls included. To change more of the prompt per caller (VIP routing,
logged-in user context), rewrite it at call time with
[dynamic call config](/guides/dynamic-call-config).

### Write in the language you want to hear

The prompt can be written in any language, and the agent follows it.
Which language the agent *speaks* is set separately — the primary
language starts the call, and any
[additional languages](/guides/supported-languages) switch
automatically when the caller uses one.

## When a call goes wrong

Fix the cause with the smallest general change:

- **Check the configuration first.** Mishearing spelled letters is an
  audio limit (try a higher audio tier or Storm); a slow reply may be the
  tier or the endpointing setting.
- **Add the principle, not a patch.** State the general rule or the
  missing fact the agent needed. The failing call's names, numbers and
  exact words stay out of the prompt.
- **Take away before you add.** When an existing rule is too specific,
  too broad or in the wrong place, change or remove it rather than adding
  a counter-rule next to it.
- **Make an ignored instruction clearer, not louder.** Capitals,
  "IMPORTANT" and stacked "never"s draw the model to one rule and make it
  worse at the rest of the call. Make the instruction more specific, or
  move it to the step where it applies.

Prompts that have collected many small fixes drift: rules repeat, conflict,
or sit far from the step they govern. Prompt review reports
`refactor_suggested` when that happens, and a refactor rewrites the prompt
into this shape while keeping every behavior it asks for.

## Templates

Three complete prompts to copy, then make yours: swap in your business
facts, transfer numbers, and policies.

### Front-desk receptionist (inbound)

Save **Emergency line** and **Office manager** as
[transfer numbers](/guides/call-transfers) on the agent.

```text
# Who you are
You are June, the receptionist for Lakeview Dental in Portland. You sound
warm and unhurried, keep each turn to a sentence or two, and ask one
question at a time.

# The call
Open with: "Thanks for calling Lakeview Dental, this is June. How can I
help?"

Find out what the caller needs. If they are in pain or say it's an
emergency, transfer them to Emergency line right away.

For an appointment, ask what it's for, then offer the two earliest open
times and ask which works. Once they pick one, take their full name and a
callback number. Read the number back and ask them to confirm it before
you book.

When they ask about a price, give it if it's listed under Facts; for any
other procedure, tell them the dentist confirms the price at the visit.

For anything you can't do on this call, take a message: their name, their
number, and what it's about.

Before you finish, ask whether there's anything else. Once there isn't,
say goodbye and end the call.

# Facts
We're open Monday to Friday, 8 am to 5 pm, at 1420 Alder Street.
We offer cleanings, fillings, crowns, and emergency visits.
New-patient cleanings are $95. We don't do orthodontics.

# Handing off
When a caller asks for the office manager, transfer them to Office
manager. For anything else that needs a person, offer a callback.
```

### Order support with a lookup tool (inbound)

Attach an [API connection](/guides/api-connections) or
[connected app](/guides/connect-apps) for the order lookup, a knowledge
base holding the returns policy, and a **Support team** transfer number.

```text
# Who you are
You are the support agent for Brightbox, an online electronics store.
You're friendly and direct, and honest about what you can and can't do.
Keep turns short and ask one question at a time.

# The call
Open with: "Thanks for calling Brightbox support. What's your order
number?"

Read the order number back digit by digit and ask the caller to confirm
it before you look anything up. Then use the Get order tool, and tell the
caller the order's status and delivery estimate in plain words.

For return questions, search the knowledge base and follow the policy it
gives. Offer only what your tools can do: you can start a return, and
refunds and replacements are decided by the support team.

If a tool fails twice, stop retrying and offer a callback.

# Handing off
Refund requests over $200, damaged items, and anything the caller says is
urgent go to Support team. When a caller asks for a person at any point,
transfer them to Support team.
```

### Appointment reminder (outbound)

For outbound calls, also set **who speaks first** and **voicemail
handling** in
[advanced call behavior](/guides/agent-settings#advanced-call-behavior) —
the prompt covers the conversation, the settings cover the pickup. Send
`patient_name` and `appointment_time` as
[call variables](/guides/call-variables) when you place each call.

```text
# Who you are
You call on behalf of Lakeview Dental to confirm upcoming appointments.
You're brief and courteous; the whole call takes under two minutes.

# The call
Open with: "Hi, this is June from Lakeview Dental. Am I speaking with
{{patient_name}}?"

Once you know you have the right person, tell them their appointment is
{{appointment_time}} and ask whether it still works. If you reach someone
else, ask when is a good time to reach the patient, and say nothing about
the appointment.

If the time works, thank them and end the call. If it doesn't, offer the
two earliest open times and rebook, or take a note for the front desk.

If they seem unsure who is calling, give the clinic's name again and offer
to end the call. If they ask not to be called again, apologize, tell them
you'll note it, and end the call.

# Handing off
For billing or treatment questions, tell them the front desk will call
them back, and note the question.
```

<Warning>
  Outbound calling has legal requirements — consent, calling hours, and
  identification rules vary by region. Review the
  [outbound calling laws guide](/guides/outbound-calling-laws) before
  running campaigns.
</Warning>

## Iterate until it survives real callers

No prompt is right on the first draft. The loop that works:

1. **Talk to it.** Click **Talk** in the builder and probe the edges
   yourself — interrupt it, go off script, mumble a phone number. This
   is the fastest tweak-and-retry loop.
2. **[Simulate calls.](/guides/simulate-a-call)** An AI caller runs
   whole conversations against your agent, scenario by scenario.
3. **[Build a validation set.](/guides/validation-sets)** Turn the
   scenarios you care about into a repeatable suite you rerun after
   every prompt change.
4. **[Split-test in production.](/guides/experiments-ab-testing)** When
   two phrasings both seem fine, let real calls decide.

A coding agent can run this loop for you, from reviewing the prompt to
replaying real calls against each edit; see
[Build with Claude Code, Codex or Cursor](/guides/coding-agents).

Every deploy is snapshotted in the **History** tab, so prompt changes
are safe to ship often — you can inspect the diff and roll back at any
time.

## Next steps

<CardGroup cols={2}>
  <Card title="Prompt style guide" icon="pen" href="/guides/prompt-style">
    Every guideline prompt review checks, with its id.
  </Card>
  <Card title="Build your first agent" icon="wand-magic-sparkles" href="/guides/build-an-agent">
    The builder end-to-end: prompt, engine, voice, tools, deploy.
  </Card>
  <Card title="Knowledge bases" icon="book" href="/guides/knowledge-base">
    Give the agent facts to search instead of a longer prompt.
  </Card>
  <Card title="Every agent setting" icon="sliders" href="/guides/agent-settings">
    Supervision, who speaks first, voicemail, silence check-ins, and more.
  </Card>
</CardGroup>

<!-- en: guides/prompt-style -->
---
title: "Prompt style guide"
description: "How to write and edit a ThunderPhone voice agent's prompt: the guidelines prompt review checks, with the ids its findings cite."
---

{/*
  GENERATED FILE: do not edit by hand.
  Source: api/agents/prompt_style_guide.md
  Regenerate: python3 scripts/docs-freshness/generate_prompt_style_guide.py
  CI regenerates this page and fails on drift
  (scripts/docs-freshness/generators.d/50-prompt-style-guide.sh).
*/}

<Note>
  This is the guide [prompt review](/api-reference/agents#review-a-prompt) checks a prompt against, and
  its findings cite the ids below. Coding agents connected to the
  [MCP server](/guides/thunderphone-mcp-server) read the same text as the resource
  `thunderphone://guides/prompt-style`. For templates and examples, see the
  [prompting guide](/guides/prompting).
</Note>

This guide is for anyone who writes or edits a voice agent's prompt: a person in the builder, Copilot, or a coding
agent working through the API. The prompt review tool uses it as its rubric and cites its guideline ids (P1, W2,
and so on).

A caller hears the agent once, at speaking pace, and cannot scroll back. The agent reads the prompt on every
turn and copies its wording closely. Both facts shape everything below.

## Shape

**P1. Write it the way a person would brief a new receptionist.** A short opening says who the agent is and who
it works for. The call then follows in the order it happens: how it opens, what to find out, what to confirm,
how it ends. Each rule sits in the part of the call where it applies. A reader should be able to ask of every
paragraph, "could a person running this business have typed this?"

**P2. Plain headings, prose underneath.** Headings such as "Who you are", "The call", "Facts" and "Handing off"
help. Machine-style structure does not: numbered rule manuals, camelCase or code-like headings, long dash-bullet
lists of rules, a tools reference up front, and cross-references like "see section 4 below". Lists are fine for
data the agent looks things up in (hours, prices, an address).

**P3. Manner of speaking once, briefly.** How the agent talks across the whole call (short turns, warm, plain
words) fits in one short paragraph near the top. Everything specific to one step lives in that step.

**P4. Facts apart from behavior.** Hours, prices, locations, policies and other facts go in a facts part of the
prompt or in a knowledge base, not scattered through the call flow. Long catalogs and FAQs belong in a knowledge
base. The agent may say only facts it was given.

## Content

**C1. Principles and facts, not scripts.** Describe what the agent is trying to achieve and what it needs to
know. Leave out "if the caller says X, say Y" branches, scripted answers to anticipated questions and canned
lines. The configured opening greeting is the one scripted element.

**C2. A fix states the general principle.** When a prompt change responds to an observed failure, the change adds
a general principle or a missing fact, not a patch for that one case. The failing call's specifics (its names,
its numbers, its exact words) stay out of the prompt.

**C3. Prefer taking away to adding.** When a failure traces to an existing rule that is too specific, too broad
or badly placed, change or remove that rule rather than adding a counter-rule next to it.

**C4. Settings decide some things, not the prompt.** These are agent settings, and prompt text about them is
ignored or conflicts with them: what is said while a tool runs (tool start line, filler phrases), silence
check-ins and the final action after silence, how a read-back is paced, the language-switching style, the
recording notice, and whether the agent or the caller speaks first. Point the prompt at the outcome instead
("confirm the email address before you save it"), and set the setting. The opening greeting itself is written in
the prompt.

**C5. Examples are lines the agent will say.** The agent copies example wording almost word for word, so every
example is a full, natural spoken sentence, and a few varied examples beat one. Introduce them as examples ("For
example, you might say ..."), not as the required line. Clipped tags like "Still accurate?" sound terse once
spoken.

**C6. No examples from our own customers' calls.** Examples describe the kind of situation in general terms or
use an invented business.

## Wording

**W1. Say what to do, plainly, once.** State the wanted behavior as an instruction in ordinary words: "Read the
order number back digit by digit and ask the caller to confirm it." Say it once, where it applies.

**W2. No emphasis.** No IMPORTANT, NOTE or CRITICAL labels, no words in capitals for force, no exclamation
marks, no "Bad:" and "Good:" pairs, no blocks of what not to do. Words like "never", "always" and "must" used
for force belong here too. Emphasis pulls the model's attention to one rule and makes it worse at the rest of the
call. When the agent ignores an instruction, make the instruction clearer, more specific or better placed, not
louder.

**W3. Fix the structure that causes a behavior.** Before adding a rule against something the agent does, find
the wording or structure that leads it there: a template the model fills in literally, a term that means two
things, an if-else branch that a fast model reads loosely. Change that.

**W4. Specific beats general.** "Offer the two earliest open times, then ask which works" beats "help with
scheduling". Vague instructions give vague behavior.

## Speech

**S1. One question per turn, and the question ends the turn.** Anything said after a question talks over the
caller's answer. Put any explanation before the question.

**S2. Short turns.** One or two short sentences unless the caller asks for detail. Spoken options are limited to
a few.

**S3. Write for the ear.** In what the agent says, avoid markdown, symbols and notation the voice will read oddly
(slashes, ampersands, "@", ".com", thousands separators, unspaced phone numbers). Facts and values the agent passes
to a tool, such as an email address or an account number, stay in their exact written form; when one also has to be
said aloud, add how it is said next to it rather than rewriting it. Spell out how unusual names or acronyms are
said, and listen to new terms in the agent's voice before keeping them.

**S4. Confirm what would be costly to get wrong.** Names, numbers, emails, addresses and codes are confirmed back
in the form they were given. The prompt says what to confirm; the platform paces the read-back.

## Iterating

**I1. Test before you keep a change.** Replay the agent's dev set on the edited draft and compare it with the
current version: which examples a change fixed, which it broke. Read the replies the way a caller would hear them.
Anything a caller would notice is a problem, not a detail.

**I2. The hold-out set is checked once.** Tune on the dev set only. Run the test set when a change is ready, and
report its result as it is. A change made after seeing test results needs fresh test examples.

**I3. Refactor when patches pile up.** A prompt that has collected many small fixes drifts from P1: rules
repeat, conflict, or sit far from the step they govern. Then rewrite it into this shape, keeping every behavior
it asks for. List each behavior as kept, merged, reworded or dropped, and drop nothing silently. Replay the dev
set before and after; a refactor should change wording, not behavior.

**I4. Check the configuration before the prompt.** Some failures are not the prompt's: mishearing spelled
letters is an audio-understanding limit (try a higher audio tier or Storm), a slow reply may be the tier or the
endpointing setting. Rule out configuration before rewriting text.

<!-- en: guides/agent-steps -->
---
title: "Agent steps and handoffs"
description: "Split an agent into steps with their own instructions, tools and collected values, and hand calls between agents mid-call."
---

A single prompt gives the model the whole job at once. **Steps** give it one
phase of the call at a time: each step has its own instructions, its own tools,
an optional line spoken word for word, and values it must collect before moving
on. **Handoffs** let another agent in your organization take over mid-call,
with the transcript intact, so the caller never repeats themselves.

Every agent starts as a single prompt. Nothing about it changes until you add
steps or handoffs.

## Steps or a single prompt?

| Use steps when | Keep a single prompt when |
| --- | --- |
| The call has phases that must happen in order: verify, then book. | The conversation is open-ended: FAQ, reception, general support. |
| A value must be captured before the agent moves on. | Nothing has to be collected in a fixed order. |
| A rule must never bend, such as "callers under 18 go to a guardian". | The model's judgment is good enough for every branch. |
| A lookup has to run at a fixed point in the call. | Tools can be called whenever the caller asks. |
| Part of the call belongs to a different agent, with its own prompt and voice. | One persona handles everything. |

Steps are not a scripted phone tree. Inside a step the model runs the
conversation as it does with a single prompt. The step decides what it is
working on, which tools it can use and what it needs before it can leave.

## How a stepped agent is built

When an agent has steps, its `prompt` holds the **shared instructions**: the
persona and rules that apply in every step. Each step adds its own
instructions on top. On every turn the model sees the shared instructions, the
current step's name and instructions, and the values collected so far.

In the builder, switch the agent from **Single prompt** to **Steps**. You get a
card per step with its name, instructions, say line, tools, collected values
and transitions, a handoffs picker, and a read-only flow graph of the steps.
Switching back to a single prompt offers a flattened prompt that merges the
shared instructions and every step.

Over the API, `steps` and `handoffs` are fields on the
[agent](/api-reference/agents). Like every agent field, a `PATCH` stages them
in the draft; `POST /v1/agents/{agent_id}/deploy` makes them live. Sending
`"steps": null` switches the agent back to a single prompt. Test calls and
**Talk** run the draft.

<Tip>
  The [copilot](/guides/ask-the-copilot) can build steps from a description
  ("add a step that verifies date of birth before booking") and edit one step
  without touching the others.
</Tip>

### Step fields

| Field | Meaning |
| --- | --- |
| `id` | Required. Lowercase letters, digits and underscores, starting with a letter, up to 40 characters. Unique within the agent. |
| `name` | Required display name, 1 to 80 characters. |
| `instructions` | Required, up to 20,000 characters. Supports `{{var}}` [call variables](/guides/call-variables), like `prompt`. |
| `say` | Optional line spoken word for word when the step is entered, up to 1,000 characters. Supports `{{var}}`. |
| `tools` | `null` gives the step every tool attached to the agent. A list limits the step to those tools, by name. Built-in actions such as `end_call` and `transfer_call` follow the agent's settings in every step. |
| `collect` | Up to 20 values the step gathers. Each has a `name`, a `type`, a `description` and `required` (default `true`). |
| `on_enter_tool` | Optional tool name, called automatically when the step is entered. See [Webhook steps](#webhook-steps). |
| `transitions` | Ordered list of where the step can go next. See [Transitions](#transitions). |
| `global_when` | Optional. Makes the step reachable from any step. See [Global steps](#global-steps). |
| `voice` | Optional voice id for this step. Ignored when the agent uses a custom voice configuration. |

The graph itself is `{"start_step": "<step id>", "steps": [...]}`. The call
begins in `start_step`.

## Transitions

Each transition has `to`, a step id, and exactly one of:

- **`when`**: plain language, and the **model decides**. The agent gets a
  built-in `go_to_step` tool listing the steps it may move to, with each
  `when` as the reason to pick it.
- **`condition`**: a rule on collected values, and **code decides**. The model
  cannot skip it or talk its way around it.
- **`"always": true`**: move on without a check. Code decides first: as soon
  as a step is entered, or once its required values are collected, the first
  matching `condition` or `always` transition wins, before the model can pick
  a `when`. So put `always` after the conditions as their fallback, or alone
  to chain a step straight into the next one. A step with `always` never
  waits for a `when` choice.

A `condition` is `{"value": <collected name or dotted path>, "op": <op>, "target": <literal>}`:

| `op` | True when the value |
| --- | --- |
| `eq`, `ne` | equals, or does not equal, `target` |
| `lt`, `lte`, `gt`, `gte` | is less than, at most, greater than, or at least `target` |
| `in`, `not_in` | is, or is not, one of the values in the `target` list |
| `exists`, `missing` | has, or has not, been collected (no `target`) |

`eq`, `ne`, `in` and `not_in` compare text case-insensitively after trimming
spaces. Numbers compare as numbers and dates as `YYYY-MM-DD` strings. A value
that was never collected makes every op false except `missing`.

Write `when` and `global_when` as a condition, such as "The caller wants to
book an appointment", not as something to say. The agent sees them as internal
routing notes and is told never to read them out or mention that it is
changing steps.

When the model calls `go_to_step`:

1. Every `required` value in the step must be present. If one is missing, the
   model is told which one, and asks the caller for it.
2. The values are stored.
3. `condition` and `always` transitions are checked in order. The first match
   wins.
4. Otherwise the agent moves to the step the model chose.
5. If nothing matches and the model named no step, the agent stays where it is.

A jump to a [global step](#global-steps) is the exception: the caller changed
topic, so it goes ahead even when the current step still has required values
missing, and before that step's conditions are checked.

`condition` and `always` transitions are also checked every time a step is
entered, so a run of code-decided steps plays out in one go. The chain stops:

- at a step it has already visited on this run;
- after 8 hops;
- at a step that still has required values to collect, unless the step has an
  `on_enter_tool` (a webhook step always routes on its result).

Only the `say` line of the step where the chain stops is spoken.

A step with no transitions is **terminal**. The agent finishes there and ends
or transfers the call with its normal built-in actions.

## Collecting values

List what a step needs in `collect`. The model passes the values when it calls
`go_to_step`, and they stay available for the rest of the call.

| `type` | Holds |
| --- | --- |
| `string` | Any text |
| `number` | A number |
| `boolean` | `true` or `false` |
| `date` | A date as `YYYY-MM-DD` |

Collected values are call content. They appear on the call next to the
transcript and follow the same retention, deletion and redaction rules. When
the agent's call recording is turned off, collected values are neither stored
nor sent in webhooks; the step timeline still is. See
[Where to see it on a call](#where-to-see-it-on-a-call).

## Say lines

`say` is spoken exactly as written when the agent enters the step. The model
then carries on in the new step in the same reply, knowing the line was just
said, so it does not repeat it. Use `say` for greetings, required disclosures
and fixed wording, and leave the rest of the reply to the model.

The start step's `say` is the agent's opening line when it speaks first, after
any consent announcement. When the caller speaks first, it opens the agent's
first reply to a person, never to an IVR or a voicemail greeting.

A step's `say` is not spoken again when the call returns to it through
`__previous__` or a hand-back. Write it the way it should sound: spell out
anything the voice could misread. Say lines support `{{var}}` call variables
but not collected values.

## Webhook steps

Set `on_enter_tool` to one of the agent's tools and it runs as soon as the step
is entered, without waiting for the model. Its arguments are the collected
values whose names match the tool's parameter names. The result is stored as a
collected value named `<tool>_result`, truncated to 4 KB, and the step's
`condition` and `always` transitions are checked straight away, so the lookup
can route the call on its own result.

The stored value has two fields:

| Field | Holds |
| --- | --- |
| `status` | The HTTP status code your endpoint returned. |
| `response` | The response body. |

Route on a body field with `lookup_account_result.response.<field>`, and on
the status code with `lookup_account_result.status`.

The lookup runs for up to 8 seconds, or the tool's own timeout if that is
shorter. If it takes longer than 3 seconds, the agent says a short line so the
caller is not left in silence. If your endpoint returns a status of 400 or
above, or does not answer in time, the agent tells the caller it could not
check that just now and carries on with what it can do.

## Global steps

A step with `global_when` can be reached from any step whenever that
description holds. The model decides, as with `when`. Use it for topics a
caller can raise at any point: billing questions, a request for a human, a
complaint.

A transition with `"to": "__previous__"` on a global step returns the call to
the step that was active before it, so the caller picks up where they left
off. The step resumes: its `on_enter_tool` does not run again, its `say` is
not repeated, and the agent continues it without starting over.

## Handoffs

`handoffs` lists other agents in your organization that can take over the call:

```json
[{"agent_id": 413, "when": "The caller asks about billing or a refund"}]
```

The agent gets a built-in `hand_off` tool with those agents and reasons. As
with transitions, each `when` is an internal routing note, never read out.

When it hands off, the agent says one short line telling the caller where they
are going, such as "Sure, I'll send you over to our billing team", in its own
voice. Then the target agent's prompt, steps, tools and voice take over and
the call continues with the same transcript. The new agent introduces itself
briefly and answers the caller's last request; it does not announce a
transfer. The target's knowledge base is available from then on.

The first time a call reaches an agent, it starts in that agent's
`start_step`: the step's `on_enter_tool` runs and its `say` is spoken. When
the call is handed back to an agent it already visited, that agent resumes the
step it was on, without running `on_enter_tool`, repeating its `say` or
introducing itself again. Collected values are shared by every agent on the
call.

- A target must be an agent in the same organization, and an agent cannot hand
  off to itself.
- Everything call-level stays with the agent that answered: product,
  languages, who speaks first, voicemail, consent announcement and every other
  call setting.
- Targets can hand off further, and back. One call can reach up to 8 agents.
- A test call runs the draft of the agent you test. The agents it hands off to
  run their deployed versions.
- If two agents have a tool with the same name and different definitions, only
  one is kept for the call, and the answering agent's always wins. The builder
  warns you when you save.
- An agent can have handoffs without steps. Its whole prompt is used as-is.

`go_to_step` and `hand_off` are reserved on agents with steps or handoffs, so
your own tools cannot use those names.

## Where to see it on a call

Open the call in **Call History**. A step timeline next to the transcript shows
each step the call entered and why, and the collected values are listed with
it.

The [call object](/api-reference/calls#retrieve-a-call) and the call-complete
webhook ([`telephony.complete` / `web.complete`](/webhooks/call-complete)) carry
the same data as `steps_trace` and `collected_values`. Both are absent on calls
without steps.

```json
"steps_trace": [
  {"t_ms": 0, "agent": "a412", "step": "greet", "via": "start"},
  {"t_ms": 51230, "agent": "a412", "step": "verify", "via": "model"},
  {"t_ms": 98410, "agent": "a412", "step": "minor", "via": "condition"}
],
"collected_values": {"full_name": "Dana Reyes", "dob": "2010-04-02", "age": 15}
```

`agent` is `a` followed by the agent id. `via` says what moved the call:

| `via` | Meaning |
| --- | --- |
| `start` | The call began in this step. |
| `model` | The model chose the step through `go_to_step`, a `when` or a `global_when`. |
| `condition` | A `condition` or `always` transition matched. |
| `on_enter` | A transition matched on a webhook step's result. |
| `handoff` | Another agent took over. |

## Where steps run

Steps run natively on **Spark**, **Bolt** and every **Storm** product, on
inbound, outbound and campaign calls, test calls, and web and widget calls.

Everywhere else the agent still works, just without the structure: it runs a
flattened prompt that merges the shared instructions and every step, in order.
That covers:

- [Realtime](/guides/use-with-openai-realtime) sessions, including sessions
  for a saved agent;
- inline configurations returned by a [dynamic call config](/guides/dynamic-call-config)
  webhook. A webhook that returns an `agent_id` uses that agent's steps.

## Limits

| Limit | Value |
| --- | --- |
| Steps per agent | 100 |
| Collected values per step | 20 |
| Handoff targets per agent | 8 |
| Agents reachable in one call | 8 |
| Size of the `steps` JSON | 200 KB |
| Step `instructions` | 20,000 characters |
| `say` line | 1,000 characters |
| Stored `on_enter_tool` result | 4 KB |

A save that breaks a rule returns `400` with the path of the bad field, such
as `steps.steps[2].transitions[0].to`. Tool names in `tools` and
`on_enter_tool` must be tools attached to the agent.

Per-step languages, scripted steps that skip the model, and collected values
inside say lines are not supported.

## Imported agents

[Importing](/guides/import-agents) from Retell, Bland, Vapi or ElevenLabs
brings multi-prompt agents, flows, pathways and workflows over as steps, and
squads and agent transfers over as handoffs between the imported agents. The
review page shows both before you import.

## Example: dental intake

Three steps in order: greet, collect the patient's details, book.

```json
{
  "prompt": "You are Ava, the front desk assistant at Acme Dental. Be warm and brief. Ask one question at a time.",
  "steps": {
    "start_step": "greet",
    "steps": [
      {
        "id": "greet",
        "name": "Greeting",
        "instructions": "Greet the caller and ask how you can help.",
        "say": "Thanks for calling Acme Dental, this is Ava. How can I help you today?",
        "tools": null,
        "collect": [],
        "transitions": [
          {"to": "details", "when": "The caller wants to book an appointment"}
        ]
      },
      {
        "id": "details",
        "name": "Patient details",
        "instructions": "Ask for the caller's full name, date of birth and the reason for the visit. Read the date of birth back and ask the caller to confirm it.",
        "tools": null,
        "collect": [
          {"name": "full_name", "type": "string", "description": "Caller's full name", "required": true},
          {"name": "dob", "type": "date", "description": "Date of birth", "required": true},
          {"name": "reason", "type": "string", "description": "Reason for the visit", "required": true},
          {"name": "new_patient", "type": "boolean", "description": "First visit to the practice", "required": false}
        ],
        "transitions": [
          {"to": "book", "when": "The caller has confirmed their details"}
        ]
      },
      {
        "id": "book",
        "name": "Book",
        "instructions": "Offer the two earliest open slots from book_slot and book the one the caller picks. Confirm the date and time, then say goodbye and end the call.",
        "tools": ["book_slot"],
        "collect": [],
        "transitions": []
      }
    ]
  }
}
```

Stage it with `PATCH /v1/agents/{agent_id}`, try it with **Talk**, then deploy.
The `details` step cannot hand over to booking until the name, date of birth
and reason are collected; `new_patient` is optional.

## Example: an age-gated branch

The model can talk to anyone, but code decides who gets booked. Collect the
age, then route on it before the model's own choice is considered.

```json
{
  "id": "verify",
  "name": "Verify age",
  "instructions": "Ask for the caller's age.",
  "tools": null,
  "collect": [
    {"name": "age", "type": "number", "description": "Caller's age in years", "required": true}
  ],
  "transitions": [
    {"to": "guardian", "condition": {"value": "age", "op": "lt", "target": 18}},
    {"to": "book", "when": "The caller has given their age"}
  ]
}
```

A caller who says fifteen goes to `guardian`, whatever the model decides.
Everyone else goes to `book`. Both are ordinary steps elsewhere in the graph.

## Example: account lookup webhook step

The caller gives an account number, the lookup runs on entering the next step,
and its result picks the route. The `not_found`, `collections` and `support`
steps are left out for brevity.

```json
[
  {
    "id": "identify",
    "name": "Identify",
    "instructions": "Ask for the caller's account number and read it back digit by digit.",
    "tools": null,
    "collect": [
      {"name": "account_number", "type": "string", "description": "Account number", "required": true}
    ],
    "transitions": [
      {"to": "lookup", "when": "The caller has confirmed their account number"}
    ]
  },
  {
    "id": "lookup",
    "name": "Look up account",
    "instructions": "Tell the caller what you found on their account and ask how you can help.",
    "tools": ["lookup_account"],
    "collect": [],
    "on_enter_tool": "lookup_account",
    "transitions": [
      {"to": "not_found", "condition": {"value": "lookup_account_result.response.found", "op": "eq", "target": false}},
      {"to": "collections", "condition": {"value": "lookup_account_result.response.account_status", "op": "in", "target": ["past_due", "suspended"]}},
      {"to": "support", "when": "The caller needs help with an active account"}
    ]
  }
]
```

`lookup_account` receives `account_number` because its parameter has that
name. If the response body has `"found": false`, the call goes to
`not_found`. If its `account_status` is `past_due` or `suspended`, it goes to
`collections`. An active account stays in `lookup`, where the model helps and
moves on to `support`. To send a failed lookup to its own step, add
conditions on the status first: an error response stores its status code, so
`{"value": "lookup_account_result.status", "op": "gte", "target": 400}`
catches it, and a timeout or no answer stores `"error"`, so
`{"value": "lookup_account_result.status", "op": "eq", "target": "error"}`
catches that.

## Example: front desk to billing

Two agents. The front desk (agent `412`) answers every call and hands billing
questions to a billing agent (agent `413`) with its own prompt, tools and voice.

On the front desk:

```json
{
  "handoffs": [
    {"agent_id": 413, "when": "The caller asks about a bill, a payment or a refund"}
  ]
}
```

On the billing agent, so it can hand the caller back:

```json
{
  "handoffs": [
    {"agent_id": 412, "when": "The billing question is resolved and the caller needs something else"}
  ]
}
```

The front desk says a short line such as "Let me get you to our billing
team", and the billing agent introduces itself and picks up the conversation
where the front desk left it. When billing hands back, the front desk resumes
where it was, without greeting the caller again. The call's product,
languages, consent announcement and other call settings stay with the front
desk, because it answered.

If billing only needs its own instructions and not its own agent, use a global
step on the front desk instead. When the question is answered, the call goes
back to whatever step the caller was in:

```json
{
  "id": "billing",
  "name": "Billing questions",
  "instructions": "Answer questions about bills and payments. Offer to send a payment link by email.",
  "tools": null,
  "collect": [],
  "transitions": [
    {"to": "__previous__", "when": "The billing question is answered"}
  ],
  "global_when": "The caller asks about a bill or payment at any point"
}
```

## Next steps

<CardGroup cols={2}>
  <Card title="Prompting guide" icon="pen" href="/guides/prompting">
    Write shared instructions and step instructions that hold up on the phone.
  </Card>
  <Card title="Build a tool integration" icon="code" href="/guides/build-tool-integration">
    Create the tools your steps and webhook steps call.
  </Card>
  <Card title="Test your agents" icon="flask" href="/guides/test-agents">
    Run the same scenarios against every branch before you deploy.
  </Card>
  <Card title="Agents API" icon="robot" href="/api-reference/agents">
    Every agent field, draft and deploy.
  </Card>
</CardGroup>

<!-- en: guides/agent-settings -->
---
title: "Voice agent settings reference"
description: "Every ThunderPhone voice agent setting explained: tiers, voices, languages, acknowledgements, tools, speak order, voicemail, consent announcements, silence handling, testing, and deployment."
---

Open **Voice Agents**, select an agent, and use its **Config** tab to control
how it sounds, reasons, starts calls, uses tools, handles silence and voicemail,
and reaches callers. Changes autosave to a draft; production traffic does not
change until you select **Deploy**.

This page is the complete dashboard reference. For field names and request
examples, use the [Agents API reference](/api-reference/agents).

## Prompt and identity

The agent name identifies it throughout the dashboard, reports, call history,
and client portals. The prompt is the agent's operating script: persona,
business facts, required questions, escalation policy, and call actions.

The prompt editor reports estimated tokens and flags common problems such as an
empty prompt, unresolved template placeholders, a missing escalation path, or
a very long prompt. Longer prompts cost more per minute, because the models
read the prompt on every reply; see [pricing](/guides/pricing).

<Tip>
  Transfers, keypad presses, hold behavior, and hang-up decisions can be written
  directly into the prompt. Attach API, app, MCP, or knowledge tools when the
  agent needs external data or actions.
</Tip>

For routing rules, cold transfers, and screened warm transfers, see
[Transfer calls](/guides/call-transfers).

## Model tier

| Tier | Best fit |
| --- | --- |
| **Spark** | Cost-sensitive, straightforward calls. |
| **Bolt** | Fast responses and balanced everyday workflows. |
| **Storm** | Complex instructions, audio understanding, and reasoning. |

Storm exposes two optional controls:

- **Acknowledgement** — **None** stays silent while preparing the full reply;
  **Tick** plays a soft waiting sound; **Verbal** speaks a brief acknowledgement.
  Verbal text can be generated from the main prompt or
  supplied manually. **Custom acknowledgement prompt** appears only when the
  selected Storm mode supports verbal acknowledgements; otherwise that field is
  unavailable.
- **Extra intelligence** — adds deeper reasoning for complex calls.

Bolt exposes **Audio understanding**, which sets how the agent hears the
caller. Every Bolt agent starts on **Standard**; you can downgrade it to
**Lean** or upgrade it to **Hearing**:

- **Standard** (default) — three transcribers. Calls that process PHI use
  only BAA-covered transcribers.
- **Lean** — one transcriber. Cheapest; it mishears more often.
- **Hearing** — Standard, plus on some turns a powerful ensemble of audio
  models listens to the caller's audio to work out exactly what they said. Best
  for languages and names; those turns take 1–2 seconds longer. **While the
  audio models listen** sets what the caller hears meanwhile:
  **Spoken acknowledgement**, **Ticking sound**, or **Silence**.

In the API these are `audio_tier` (`standard`, the default, `lean`, or
`hearing`), `acknowledgement_feedback_mode` (`acknowledgement`, `tick`, or
`none` for silence), `endpointing` (`faster`, `fast`, `normal`, or `patient`),
and `intelligence` (`lite` or `standard`). Older API clients may
still use `eagerness` for `endpointing`. Other tiers ignore `audio_tier`,
`endpointing`, and `intelligence`.

Each call is billed at what its parts cost at our providers' list prices, plus
an infrastructure charge and a markup, so every setting that uses more
model, transcription or voice work costs more per minute. Zeus shows what a
minute of the agent costs before you go live; see [pricing](/guides/pricing).

#### Bolt endpointing and intelligence

**Endpointing** controls how long the caller must stay quiet before the agent
starts preparing a reply:

- **Faster**
- **Fast**
- **Normal** (default)
- **Patient**

**Intelligence** controls the Bolt reply tier:

- **Lite**
- **Standard** (default)

Existing Bolt agents stay on **Normal** endpointing and **Standard**
intelligence unless you change them.

## Voice, background, and languages

Select a voice and play its sample before deploying. The picker only requires
your chosen voice to support the **primary language**. If you turn on **Switch to native voices**,
additional languages can be covered by same-gender native catalog voices instead.
Premium voices cost more per minute than the default voices. Your custom voices appear in
the same picker once ready. See [Voice library and custom voices](/guides/voice-library).

**Background track** can be:

- **None** — no ambient audio.
- **Call center** — a call-center ambience, with an in-dashboard preview.

Set one **primary language**, then any number of **additional languages**. The
agent automatically detects when a caller switches to a selected language and
responds in it. There is no language surcharge; languages served by premium
voices cost a little more per minute. See the generated [Supported languages](/guides/supported-languages) catalog.

When an agent has **Additional languages**, enable **Switch to native voices**
to use a catalog voice native to the detected language, matched by gender. It
switches back to the configured voice for the primary language. If no matching
native voice is available, the current voice stays in use. Custom voices do not
switch. Test each language with **Talk**, then select **Deploy**.

Native switching has no separate charge. The voice that speaks is billed at its
provider's list price.

**Pronunciation dictionary** (API field `pronunciation_dicts`, off by default)
reads the agent's Cartesia speech through ThunderPhone's pronunciation
dictionary, for example car model numbers and brand names. It applies to
ThunderPhone's own Cartesia voices on phone, widget and test calls, not to a
customer's own Cartesia key or Realtime sessions. For your own words, use the
agent's [words list](/api-reference/agents#words).

## Connected capabilities

The Config tab has four independently attachable capability sections:

| Section | Use it for |
| --- | --- |
| **Connected apps** | Approved operations in Google Calendar, Google Sheets, Slack, HubSpot, Salesforce, or Cal.com. |
| **API connections** | Your own HTTP endpoints, described as callable functions. |
| **Knowledge** | Files or web content the agent can search during a call. |
| **MCP servers** | Cached tools discovered from remote Model Context Protocol servers. |

An attachment is part of the draft and becomes available to production calls
after deployment. Configure the resources first under **Connections** or
**Knowledge**, then attach them to the agent.

## Phone and web endpoints

Under **Phone numbers**, attach an existing number, get a ThunderPhone number, or
import a number through a VoIP connection. A number can use different agents
for inbound and outbound directions. Each number answers with the agent's
latest published version, or with one version you pick, so you can try changes
on a test number while the main line stays on the version it has.

### Call setup webhook

**Call setup webhook** is a URL your server answers before each inbound phone
call this agent takes, to fill in the agent's `{{variables}}` and the call's
context: the caller's account, their last order, why you expect them to call.
It receives the caller, the number and the agent's version, and answers with
`variables` and `context`
([request and answer](/webhooks/call-incoming#agent-call-setup-webhook)).

When the prompt uses a variable with no default, the agent needs this webhook
to answer a phone number: the builder lists those variables, the agent can't be
put on a number or published to one without a webhook, and a call whose
webhook doesn't answer doesn't start. A variable with a default, like
`{{first_name|there}}`, lets the agent answer even when the webhook fails.

Under **Web widgets**, attach a widget so visitors can speak to the agent from a
site. Widget availability can also be enabled or disabled as part of agent
configuration.

## Time zone

**Time zone**, under the phone numbers, is what the agent treats as "now": it
states the date and time, offers appointment times and works out "today" and
"tomorrow" in this zone. This agent's business hours in reports use it too.

A new agent starts with your organization's time zone, or your computer's if
the organization has none. Change it if your callers are somewhere else. When
the agent's phone number is in a different zone from the one you picked, the
builder says so and offers to switch.

An agent without a time zone (an older one, or one created through the API
without `timezone`) uses the zone of the number the call is on, then the zone
of the agent's numbers, then the organization's, then US Pacific. The builder shows which zone that is
and asks you to confirm it, or to pick one when the numbers don't settle it
(a toll-free number, or numbers in different zones).

When one agent serves contacts in several time zones, pass the zone with each
call instead: `timezone` on [`POST /v1/call`](/api-reference/outbound-calls) or
in your [configuration webhook's response](/guides/dynamic-call-config#set-the-time-zone-per-call).

### If your agent has no time zone yet

New agents require a time zone. Older agents can still have none.

If an older agent has no time zone, ThunderPhone first uses the agent's own
setting if there is one, then your organization's, then the time zone inferred
from the agent's phone numbers. If that still does not settle it, it falls
back to Los Angeles. The builder shows the resolved zone and asks you to
confirm it, or to pick one when the numbers do not settle it.

## Advanced call behavior

Expand **Advanced** at the bottom of Config for the following controls.

### Supervision

When enabled, a second AI monitor checks each agent turn against the
instructions and can intervene silently. Its model use is billed like any other
part of the call. Supervision is not available on Bolt.

### Connection tone

Play a short tone immediately after the call connects and before either party
speaks.

### Intro clip

Play a prerecorded clip at the start of inbound calls, followed by ringing,
so the line sounds like a company phone line before the agent answers. It plays
on inbound phone calls and on **Talk** (browser) test calls in the builder. It
does not play on outbound calls, AI test calls, web widget calls, or Realtime
API calls.

- **Off** (default) — the agent answers right away.
- **Recording notice** — a recorded voice says "This call may be monitored or
  recorded, for quality assurance purposes." Preview it in the builder.
- **Your own recording** — upload an audio file (MP3, WAV, M4A, and other
  formats your browser can play) or record one in the browser. Clips can be
  0.5 to 15 seconds long. The builder converts the clip before uploading it,
  and you can play it back or remove it.

**Ring after intro** sets how many US rings play after the clip: **Off**,
**1 ring** (default), or **2 rings**.

The order at the start of a call is: connection tone (if on), intro clip,
rings, then the [consent announcement](#consent-announcement) or
[AI-processing disclosure](#ai-processing-disclosure) if they apply, then the
greeting. The intro clip never replaces the consent announcement or the
AI-processing disclosure, even when your clip says the call is recorded.
Caller audio is not processed while the clip and rings play. A custom clip is
fetched when the call starts; if it cannot be loaded within a few seconds, the
call goes ahead without it, so a failed load can delay the greeting by up to
about 3 seconds.

The intro clip is a draft setting like the others: it reaches live calls when
you deploy.

<Note>
Stock recording notice voice: Allison Smith,
[CC BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/), adapted
(trimmed, joined, resampled) by ThunderPhone.
</Note>

### Tool sound

Choose the sound made by the prompt-callable sound tool:

- **None** — the tool is not offered.
- **Chime**, **Ding**, or **Beep** — each can be previewed in the builder.

### Typing sounds

Enable **Typing sounds** to play a soft keyboard sound while the agent runs a
custom tool. Platform-managed tools do not trigger it.

Once it is on, pick the sound. Each one can be previewed in the builder:

- **Keyboard and mouse** (default): typing with mouse clicks, like someone looking it up.
- **Mechanical keyboard**: bright, clicky mechanical keys.
- **Desktop keyboard**: steady typing on a standard keyboard.
- **Laptop**: soft, flat laptop keys.
- **Office keyboard**: quiet, muted office keyboard.
- **Quiet room**: soft room tone with one person typing.

### Tool-start line

Choose whether something is said when the agent calls a tool:

- **Always** (default for new agents): something is said at every tool call,
  however fast the tool returns. If the agent spoke with the call, its own words
  are that line. Otherwise a short line written for the call plays as soon as
  it is ready, or a standard one such as "One moment, please" if it takes more
  than about a second. Tools that play their own audio or act on the call
  itself (keypad input, sounds, hold, transfers, ending the call, step
  handoffs) still get a line only if they are slow, and so does any tool
  while the agent is in a phone menu or talking to voicemail.
- **Only if the tool is slow**: a short line plays only if the tool is still
  running about 3 seconds after the agent last spoke. Agents created before
  this setting existed keep this choice.
- **Never**: ThunderPhone says nothing when a tool starts, and the agent is
  told not to speak when it calls a tool. Anything the agent still says with
  the call plays.

The agent's own words always play, whichever option you pick. The caller hears
at most one tool-start line per turn: a line already spoken in that turn, such
as the agent's words or a filler on a slow reply, counts as it.

### Long-wait updates

On by default. When a tool is still running after about 12 seconds of
silence, the agent says it is still working on it, then adds a short patience
line about every 15 seconds until the result arrives. These lines are worded
for the call: they follow the agent's prompt and persona, the conversation so
far and the call language, so they do not repeat one fixed sentence. If a line
cannot be written in time, the agent uses a standard one such as "Sorry, this
is taking a little longer than expected". Slow replies without a tool get
short standard lines such as "Just a sec".

Turn **Long-wait updates** off to stay quiet after the tool-start line until
the result arrives. Slow replies without a tool then get no filler either.
Typing sounds still play if they are on. Storm's acknowledgement setting is
separate and is not affected.

### Settings win over the prompt

Tool-start line and Long-wait updates decide what ThunderPhone says while a
tool runs. Prompt text cannot stop or add these lines. For an agent that stays
silent while tools run, set **Tool-start line** to **Never** and turn
**Long-wait updates** off rather than asking for silence in the prompt. The
builder's prompt check warns when the prompt asks for silence, or for a line
at every tool call, and these settings say otherwise.

### Send email

Enable **Send email** and enter one recipient address to give the agent the
`send_email` tool. The address is fixed in the agent settings. The model writes
the subject and plain-text body, but it cannot choose or change the recipient.
Prompt the agent with the exact situations that should produce an email, such
as sending a caller's message after collecting their name and callback number.

See [Built-in tools](/guides/built-in-tools) for the full tool behavior.

### Calculator

Enable **Calculator** to give the agent the `calculate` tool. The agent uses it
to add up order totals, fees and change exactly instead of doing the math
itself. It is off by default; turn it on for agents that quote prices. No
prompt change is needed.

See [Built-in tools](/guides/built-in-tools) for the full tool behavior.

### Send SMS

Enable **Send SMS** to give the agent a `send_sms` tool.

Choose which connected VoIP number (Twilio or Telnyx, SMS-capable and verified) to
send from; ThunderPhone-provisioned numbers cannot send SMS. You can limit
sending to the caller only, or allow other recipients and keep an allowlist of
approved numbers. You can also enable an SMS follow-up template for messages
sent after the call.

See [Built-in tools](/guides/built-in-tools) for the full tool behavior.

### Extra audio context

**Extra audio context** controls how much recent caller audio is carried
between turns:

- **Automatic (recommended)** uses more recent audio for inbound, browser, and
  WebSocket calls, and only the latest turn for outbound phone calls.
- **On** includes the last few caller turns to help with corrections, spelling,
  and number-heavy data collection.
- **Off** includes only the latest caller turn for lower latency.

The Agents API also exposes the Storm-only `audio_context_mode` compatibility
field: `full` or `reduced`. It is separate from the dashboard's
`additional_audio_context` tri-state above.

### Who speaks first

Configure inbound and outbound calls separately:

- **Inbound:** agent speaks first, or caller speaks first.
- **Outbound:** agent speaks first, or callee speaks first.

To remove the agent's initial greeting, choose **Caller speaks first** for
inbound calls or **Callee speaks first** for outbound calls.

This setting is useful for outbound dialers that must wait for a person or
phone menu before beginning the script.

### Voicemail handling

Choose what happens when an outbound call reaches voicemail:

| Option | Behavior |
| --- | --- |
| **Let the agent decide** | The prompt and conversation context determine whether to speak or hang up. |
| **Hang up silently** | End without leaving a message. |
| **Leave a message, then hang up** | Speak the configured message and end the call. |

Hanging up on voicemail can cost you pickups. A short message usually works
better: people call back numbers that leave one, and callbacks help the
number's standing with carriers. The builder says so when you pick **Hang up
silently**.

Voicemail messages can contain up to **2,000 characters** and support
`{agent_name}` and `{org_name}`. See
[Pricing](/guides/pricing#hold-time-phone-menus-and-transfers) for how
voicemail and hold time are billed.

### Consent announcement

By default, a short announcement at the start of every call tells the caller
that they are speaking with an AI assistant and that the call is recorded. You
can edit the announcement text, up to **2,000 characters**; it plays verbatim
in the agent's language.

Disabling the announcement on an eligible agent requires an organization admin
to affirm that the organization will provide any legally required notice and
obtain any legally required consent. Re-enabling and later disabling it
requires a new affirmation. Review the
[recording consent laws guide](/guides/recording-consent-laws) before changing
this setting.

### Record calls

**Record calls** controls whether this agent stores call audio, transcripts,
and other call content. The organization-wide recording setting must also be
enabled for recording to occur. When recording is off, those artifacts are not
stored. A recording covers at most the first 3 hours of a call; a longer call
continues, but the audio after 3 hours is not recorded. See [Call recording consent laws](/guides/recording-consent-laws#turning-recording-off-and-the-ai-processing-disclosure).

### AI-processing disclosure

When recording is off, **AI-processing disclosure** controls the shorter notice
that audio is processed live but not recorded. Choose **Use organization
setting**, **Always play**, or **Don't play**. Disabling the disclosure requires
an organization-admin attestation.

### Uninterruptible disclosures

**Uninterruptible disclosures** remains visible for compatibility, but enabling
it has no effect. Leave it off. For required opening language, use **Consent
announcement**, which plays before conversation and cannot be interrupted.

### Silence check-ins

When enabled, the agent checks whether the caller is still present after a
period of silence, repeats up to your limit, then hangs up or transfers the
call:

- **Seconds before check-in:** 10–120 seconds.
- **Check-ins before hanging up or transferring:** 1–10.
- **After the last check-in:** **Hang up** (the default) or **Transfer to**
  one of the agent's [transfer numbers](/guides/call-transfers). The
  transfer is skipped when the caller never said anything on the call: the
  agent hangs up instead, so a dead line never rings a person. If the
  transfer can't be placed, the agent hangs up.
- **What the agent says:** the line spoken at that moment, up to 300
  characters, read exactly as written. Leave it blank for the default:
  "I'm not hearing anything, so I'll let you go. Feel free to call back."
  before hanging up, or "Please hold while I transfer you." before a
  transfer, in the call's language.

The defaults are 15 seconds and 3 check-ins. The check-ins follow the
conversation:

- If nobody has said anything since the call started, the agent asks
  "Hello? Are you there?" after about 6 seconds, then waits your interval
  between check-ins.
- If the caller asked the agent to wait ("give me a minute", "let me grab
  my card"), the agent gives them the time they asked for, at least a
  minute, and then only lets them know it's still there. It hangs up
  after about a minute without a reply following its last check-in.
- Otherwise the check-ins change the longer the line stays quiet. First the
  agent nudges on what it just said: "Did you catch all that?" after reading
  details back, or its question again, short but whole. Later it asks "Hello?
  Are you still there?", then "Hmm, I think I might've lost you. Can you
  hear me?" With 25 seconds or more before a check-in, the first check-in
  skips the nudge and asks whether the caller is still there.

Through the API, `"silence_interval_seconds": null` leaves the pace to
ThunderPhone, as for an inline call configuration that doesn't set it. The
pace then follows the conversation:

- Before the caller has said anything, check-ins come after 6, 10 and 15
  seconds of silence.
- Ordinary quiet during the call gets check-ins after 10, 15 and 15 seconds.
- After the caller asks the agent to wait, the first check-in comes after at
  least 60 seconds, or the time they asked for, up to 10 minutes.

### Call length and timeouts

Use these controls to keep stalled or unusually long calls from accumulating
call time and telephony charges:

- **Minutes of silence before hanging up:** 1–60 minutes. The default is 10
  minutes and applies when silence check-ins are disabled. The call then
  ends with nothing said; the after-the-last-check-in settings don't apply.
- **Max call duration:** 1–360 minutes. New agents start at 60 minutes,
  except agents made from the Interpreter template, which start with no
  agent-level cap; raise it, lower it, or switch it off for no agent-level
  cap. Agents created before this default keep their existing setting. 45 seconds before the
  limit (a quarter of the limit when it is under 3 minutes) the agent is told
  to wrap up and say goodbye.
- **Platform limit:** every call ends after 6 hours, whatever the agent's
  setting. The agent gets the same wrap-up warning first.
- **Ring duration:** let outbound and transferred calls ring for 5–120 seconds. Outbound calls ring for at least 14 seconds whatever you set: a call that rings briefly and drops looks like a one-ring scam call, and carriers are quicker to label the number as spam. A shorter setting still applies to transfers.
  Leave it unset for platform defaults: 60 seconds for outbound calls, 45
  seconds for warm transfers, and the carrier default for cold transfers.
  This setting does not affect inbound ringing.

## Builder tabs and lifecycle

| Tab or action | Purpose |
| --- | --- |
| **Live / Talk** | Speak with the current draft in your browser and inspect transcript and tool activity. |
| **Calls** | Review calls handled by this agent. |
| **A/B** | Create prompt or configuration variants and compare live outcomes. |
| **Simulate** | Run saved or ad-hoc AI-caller scenarios against the draft. |
| **Validation** | Replay frozen real-call turns against the draft before deployment. |
| **History** | Compare deployed revisions and restore one into the draft. |
| **Discard** | Revert every pending draft setting to the deployed version. |
| **Deploy** | Atomically promote the complete draft and create a revision. |

If another editor saves the same agent after you loaded it, ThunderPhone stops
the conflicting save or deploy and asks you to refresh rather than overwriting
their changes.

## Manage agents from the list

The **Voice Agents** page also supports organization-level lifecycle actions:

- **Duplicate** an agent as a new starting point in the same organization.
- **Transfer** an agent to another organization you belong to. **Copy** keeps
  the source; **Move** removes it from the current organization and requires
  administrator access.
- Delete one agent, or bulk-delete selected agents, after confirmation.

### Export the agent list

Select one or more agents and export their summary fields as **CSV** or
**JSON**. The export does not include full prompts and is not a configuration
backup.

Copying or moving an agent across organizations does not silently grant the
destination organization access to source-only connections. Review the copied
agent's app, API, knowledge, MCP, phone-number, and widget attachments before
deploying it there.

## Related pages

<CardGroup cols={2}>
  <Card title="Build your first agent" icon="robot" href="/guides/build-an-agent">
    A concise end-to-end builder walkthrough.
  </Card>
  <Card title="Pricing" icon="coins" href="/guides/pricing">
    Base tiers, add-ons, call metering, numbers, and one-time charges.
  </Card>
  <Card title="Validation sets" icon="list-check" href="/guides/validation-sets">
    Freeze real-call turns and replay them before deploying.
  </Card>
  <Card title="Agents API" icon="code" href="/api-reference/agents">
    Request fields, drafts, deploys, versions, and examples.
  </Card>
</CardGroup>

<!-- en: guides/built-in-tools -->
---
title: "Built-in tools"
description: "Prompt ThunderPhone agents to end calls, transfer callers, navigate keypads, wait on hold, search knowledge, play sounds, send email, and calculate totals."
---

Built-in tools let an agent perform common call actions without connecting your
own API. Most are available automatically; email, sounds, the calculator, and
knowledge search appear only after you configure the related setting or source. Tell the agent
when to use each action in its prompt.

| Tool | Use it for | How to enable it | Supported calls |
| --- | --- | --- | --- |
| `end_call` | Finish a completed conversation | On by default; `system_tool_settings` can turn it off | Phone, browser Talk, widget, simulation, and Realtime |
| `transfer_call` | Route a phone caller | Configure routing in the prompt | Ordinary phone calls; inline Realtime with `call_events` can use cold transfer. Saved-agent Realtime omits it. |
| `send_keypad_input` | Press keys in a phone menu | On by default for outbound calls; `system_tool_settings` can turn it on or off | Phone calls; inline outbound Realtime with `call_events`. Saved-agent Realtime omits it. |
| `no_response` | Keep listening while an automated menu speaks or a caller thinks aloud; a caller who asks the agent to wait gets just "Sure." | Always available | All call types |
| `wait_on_hold` | Wait silently for a person to return | On by default for outbound calls; `system_tool_settings` can turn it on or off | Phone calls and outbound inline Realtime sessions |
| `search_knowledge_base` | Answer from attached sources | Attach knowledge to the agent | Saved-agent calls with attached knowledge |
| `play_sound` | Play a configured notification sound | **Advanced → Tool sound** | Saved-agent calls |
| `send_email` | Email one fixed recipient | **Advanced → Send email** | Saved-agent calls |
| `calculate` | Add up totals, fees, and change exactly | **Advanced → Calculator** | Saved-agent calls |

## `end_call`

Ends the current call when the prompt tells the model to do so. It is on by
default. An agent that should never hang up on its own, such as an interpreter
relaying between two people who end the call themselves, can turn it off with
the agent's `system_tool_settings` field (`{"end_call": false}`). The call then
ends when a person hangs up, or through the silence and time limits.

Write the condition and any required farewell into the prompt:

```text
When the caller confirms they need nothing else, say goodbye and end the call.
```

A model-ended call has `end_reason: "ai_hangup"`, including one that ends
after the call time limit warning. The call ends with `max_duration` only if
the time limit is reached first, with `balance_exhausted` when the prepaid
balance runs out, and with `price_cap_reached` when the call reaches the agent's
hard price cap (the agent says a short goodbye first).

## `transfer_call`

Transfers a phone caller to a fixed number supplied by the model. Cold transfer
is immediate. A screened warm transfer privately calls the destination before
connecting the parties. Warm transfer requires a verified imported VoIP number
that can place outbound calls.

Put the destination number and exact routing condition in the prompt:

```text
If the caller asks for billing, transfer them to +15551234567.
```

A successful cold transfer has `end_reason: "ai_transfer"`; a completed warm
handoff has `end_reason: "ai_warm_transfer"`. A failed warm attempt returns
control to the agent, so the call's later ending determines its end reason. On
non-phone sessions, a transfer request ends the session instead.

See [Transfer calls](/guides/call-transfers) for dashboard and API setup,
routing, screening, failure handling, limits, and testing.

## `send_keypad_input`

Sends DTMF (phone keypad) digits `0`–`9`, `*`, and `#` to a phone line. The
model uses it to navigate an IVR, the automated menu that asks callers to press
keys. It is on by default for outbound calls and off for inbound calls; set
`"send_keypad_input": true` or `false` in the agent's `system_tool_settings`
to change that for every call.

Tell the model which menus it may navigate and where requested values come
from. Do not ask it to guess menu options:

```text
Follow the phone menu for account status. Press a key only after the menu
states what that key does. Enter the account number supplied by the caller.
```

The platform removes unsupported characters and sends valid digits in order.
If no valid digits remain or the call cannot send keypad input, the failure is
returned to the agent so it can recover.

## `no_response`

Keeps the agent silent while an automated system is still speaking or asks it
to keep listening, and while a caller thinks aloud ("um, let me see") or turns
to talk to someone else. When a caller asks the agent to wait while they do
something ("one sec", "let me check", "can you hold on a second?") and gives it
nothing else to answer, the agent says just "Sure." (not "Take your time") and
waits for the caller to speak again. The agent's silence check-ins still run,
and are always spoken, if the line stays quiet. It is not for a live
person's greeting, a question, or a true hold queue. It is available by default
and has no agent setting.

If your prompt tells the agent what to say when a caller asks for a moment, the
prompt wins.

Usually the built-in description is enough. For IVR-heavy calls, reinforce the
boundary in the prompt:

```text
Stay silent while a phone menu is still speaking. Answer a live person as soon
as they address you.
```

This action does not end the call.

## `wait_on_hold`

Places an outbound agent into a silent hold state until a live person returns.
The model uses it only after the other party explicitly says the agent is being
put on hold. It is on by default for outbound calls; set `"wait_on_hold"` in the
agent's `system_tool_settings` to turn it on or off for every call.

```text
If a person explicitly puts you on hold, wait silently. When they return,
continue from the question you were discussing.
```

Do not prompt the agent to use it for an IVR's "please wait" message. Hold lasts
up to 15 minutes by default. For ordinary outbound calls, `POST /v1/call`
accepts a positive-integer `max_hold_seconds`; inline Realtime restricts
`max_hold_seconds` to 10–900 seconds. If the person
returns, the agent resumes without changing the call's end reason. If the limit
expires, the platform ends the call with `end_reason: "ai_hangup"`.

## `search_knowledge_base`

Searches documents attached to the agent and returns relevant passages. Attach
a knowledge base or individual knowledge documents to enable it, then tell the
model which answers must come from those sources:

```text
Search the knowledge base before answering policy questions. If the first
search is inconclusive, try once more with different key terms.
```

If a search fails, the result is returned to the agent. See [Knowledge
base](/guides/knowledge-base) for dashboard and API setup.

## `play_sound`

Plays the agent's configured notification sound after any speech in the same
turn. In the dashboard, set **Advanced → Tool sound** to **Chime**, **Ding**,
or **Beep**, then deploy the agent. **None** removes the tool.

With the [Agents API](/api-reference/agents), stage `play_sound_asset` as
`"chime"`, `"ding"`, or `"beep"`, then deploy. Set it to `""` to disable
the tool.

```text
After confirming that an appointment was saved, say "You're all set" and play
the notification sound.
```

A playback failure is returned to the agent and does not end the call.

## `send_email`

Sends a plain-text email to the one recipient configured by the agent owner.
The model supplies the subject and body. It never sees a recipient parameter
and cannot choose or change the address.

In the dashboard, enable **Advanced → Send email**, save a recipient address,
then deploy the agent. With the [Agents API](/api-reference/agents), stage both
`send_email_enabled: true` and a non-empty `send_email_recipient`, then deploy.
Define the trigger and required contents in the prompt:

```text
When the caller asks to leave a message, collect their name, callback number,
and message. Read the details back for confirmation, then email them.
```

A call can attempt at most three emails. Each subject is limited to 300
characters and each body to 20,000 characters. Missing configuration, invalid
content, the per-call limit, and delivery failures are returned to the agent.
A failed delivery still uses one of the three attempts.

Test with a controlled recipient before deploying broadly. Browser Talk and
simulations send real email; there is no dry-run mode.

## `calculate`

Evaluates an arithmetic expression exactly and returns the result, so the agent
does not add up prices in its head. It is off by default. In the dashboard,
enable **Advanced → Calculator**, then deploy the agent. With the [Agents
API](/api-reference/agents), stage `calculator_enabled: true`, then deploy.

The model writes the expression, such as `2*23.5 + 16.5 + 4`, and reads the
result back to the caller. Expressions may use numbers, `+`, `-`, `*`, `/`, and
parentheses. One call can carry up to 10 expressions separated by `;`, such as
a subtotal and the total with a delivery fee, up to 500 characters in all.
Results are rounded to 10 decimal places. The math is exact decimal arithmetic, so
`0.1 + 0.2` returns `0.3`. Division by zero and anything else in the expression
come back to the agent as an error to correct. It runs on ThunderPhone and
answers instantly, with no filler line or typing sound.

Turn it on for agents that quote order totals, fees, or change. No prompt change
is needed.

## Compatibility note

The **Advanced → Uninterruptible disclosures** setting and the legacy
`speak_uninterruptible_enabled` field remain for compatibility, but enabling
them has no effect. Leave the setting off; no prompt can activate this tool.

For a required call-opening disclosure, use **Consent announcement**. It plays
verbatim before ordinary conversation and cannot be interrupted. See [Call
recording consent laws](/guides/recording-consent-laws).

## Test and monitor built-in tools

Use browser Talk or a simulation to check prompting, knowledge search, sounds,
and email. Those environments cannot reproduce phone-network behavior. Test
keypad navigation and hold on an outbound phone call, and test a complete warm
handoff on a real call using an eligible imported VoIP number. Realtime support
is limited as shown in the table above.

## Calls, pricing, and webhooks

Built-in actions have no per-use tool fee. Normal call and provider charges
still apply; see [Pricing](/guides/pricing). Their calls and results can appear
in the completed transcript, but they do not emit `telephony.tool` or `web.tool`.
Those events are for [user-defined functions](/tools/overview). Only a completed
hangup or transfer changes the call's `end_reason`; other failures are returned
to the agent. See [Completion webhooks](/webhooks/call-complete) for the call
record.

<!-- en: guides/call-transfers -->
---
title: "Transfer calls"
description: "Save the numbers an agent may transfer to, then route callers with a cold transfer, or stay on the line and introduce them with a warm transfer."
---

An agent transfers calls only to its **transfer numbers**: a list of names and
phone numbers you save on the agent. The prompt refers to each number by name
and says when to transfer and whether the handoff should be cold or warm. The
agent sees only the names, never the numbers. An agent with no transfer numbers
can't transfer calls.

| Mode | What happens | Use it when |
| --- | --- | --- |
| **Cold** | The caller is sent directly to the destination. The agent does not introduce the caller or confirm that anyone will answer. | Fast routing matters more than an introduction, or the call's number can't place outbound calls. |
| **Warm** | As soon as someone answers, the caller is connected, the agent introduces the caller on the line, and drops. You can instead have the agent [ask first or whisper](#before-connecting). | The destination should hear who is calling and why, or the caller should return to the agent when nobody answers. |

If the agent omits the mode, the transfer is cold.

## Configure transfers

In the dashboard:

1. Open **Voice Agents**, select the agent, and open **Config**.
2. Under **Transfer numbers**, add each destination with a name and a phone
   number, such as **Billing** and `+1 415 555 2671`. An agent can have up to
   50 transfer numbers.
3. In the prompt, refer to each destination by its name and say when to use
   it and whether to use `cold` or `warm` mode, for example "transfer billing
   questions to Billing". You do not create a custom tool.
4. For warm transfers, choose what happens **Before connecting** and,
   optionally, what the **Briefing** should say. See
   [Before connecting](#before-connecting).
5. If needed, set **Advanced → Ring duration** from 5 to 120 seconds.
6. Select **Deploy**.

With the API, `PATCH /v1/agents/{agent_id}` to stage `transfer_destinations`,
the prompt, and the optional `warm_transfer_style`, `warm_transfer_briefing`
and `ring_duration_seconds`, then `POST /v1/agents/{agent_id}/deploy`:

```json
{
  "transfer_destinations": [
    {"name": "Billing", "number": "+14155552671"},
    {"name": "Front desk", "number": "+19375551234"}
  ],
  "warm_transfer_style": "introduce",
  "warm_transfer_briefing": "The caller's name and what they need."
}
```

A write replaces the whole list, and `[]` removes every transfer number. See
the [Agents API](/api-reference/agents#transfer-numbers) for the field rules and
validation errors.

### Names and numbers

- **Name:** 1 to 60 characters, unique on the agent ignoring case. This is the
  word the prompt uses.
- **Number:** a full phone number. Numbers without a country code are read as
  US numbers, and every number is stored in E.164 format. Extensions and the
  fictional range 555-0100 through 555-0199 are refused.
- **Variable number:** instead of a phone number, one
  [call variable](/guides/call-variables) on its own, such as `{{rep_phone}}`.
  It is filled from the call's variables when the call starts. If the variable
  is missing or isn't a valid number on that call, a transfer to that name is
  refused.
- **SIP address:** a `sip:` or `sips:` address instead of a phone number, such
  as a contact center queue. See [Transfer to a SIP address](#transfer-to-a-sip-address).
- **Return:** no number at all. The agent hands the call back to the contact
  center it came from. See [Return the call to your contact center](#return-the-call-to-your-contact-center).

### Transfer to a SIP address

A transfer number can be a SIP address, such as
`sip:support@pbx.example.com`, so the agent can hand callers back to your
contact center or PBX. The transfer is a cold transfer: ThunderPhone sends a
SIP `REFER` with that address, and your system takes the call from there.

A SIP address works only when the call came from your own SIP system:

- calls to a [SIP address](/guides/sip-addresses) (per-call URI or SIP
  endpoint), and
- calls on a number you connected through a manual SIP connection
  ([your own SIP trunk](/guides/voip-providers)).

On any other call, including calls on ThunderPhone numbers and on numbers
connected through Twilio or Telnyx, a transfer to a SIP address is refused:
the agent is told it can't transfer there and keeps talking to the caller. A
warm transfer to a SIP address runs as a cold transfer.

The address must be written out in full; it can't be a `{{variable}}`. It is at
most 255 characters, needs a host, and can't contain spaces, quotes, commas or
angle brackets. Parameters such as `;transport=tls` are fine. The one header
the address itself can carry is `?User-to-User=`, for platforms that read
user-to-user information from the transfer address:
`sip:queue@sbc.example.com?User-to-User=00a1b2;encoding=hex`.

#### SIP headers on the transfer

Any transfer number can also list `headers` to send with the `REFER` of a cold
transfer, for example the caller's account ID for your contact center to look
up:

```json
{
  "name": "Support queue",
  "number": "sip:support@pbx.example.com",
  "headers": {
    "X-Account-Id": "{{account_id}}",
    "User-to-User": "{{uui}}"
  }
}
```

- Up to 10 headers. Names start with `X-` or are `User-to-User`. `X-TP-` names
  are reserved for ThunderPhone.
- Values are at most 256 bytes and can use
  [call variables](/guides/call-variables), filled when the call starts. A
  missing variable is left empty, line breaks are removed, and a header whose
  filled-in value is over 256 bytes is not sent.
- Headers go only on a cold transfer's `REFER`, and only reach your system
  when the carrier passes them on. They are not sent on a warm transfer's new
  call or when ThunderPhone has to connect a refused transfer itself.

#### Headers inside the transfer address

Some contact centers read context only from the transfer address (the
`Refer-To` of the `REFER`), not from separate headers. Twilio, Genesys Cloud
and Talkdesk work this way, and most of them expect `User-to-User` in hex. Set
two options on the SIP address entry:

```json
{
  "name": "Escalation",
  "number": "sip:escalation@talkdesk.example.com",
  "headers": {
    "User-to-User": "autopilot_result={{handoff_summary}}",
    "X-Call-ID": "{{handoff_id}}"
  },
  "headers_in_uri": true,
  "uui_encoding": "hex"
}
```

- `headers_in_uri: true` sends the headers inside the address instead of on
  the `REFER`:
  `sip:escalation@talkdesk.example.com?User-to-User=…&X-Call-ID=…`. Values are
  escaped for a SIP address, so `;` becomes `%3B` and a space `%20`.
- The whole address is kept to 254 characters, inside Twilio's limit of 256
  with the angle brackets. `User-to-User` goes first, then the other headers in
  alphabetical order. A long `User-to-User` is cut to fit rather than left out,
  so put the part your platform needs most at its start. Another header that
  doesn't fit beside it is left out whole, and the transfer still goes ahead.
- `uui_encoding: "hex"` sends `User-to-User` as hex with `;encoding=hex`.
  Write the value as plain text: it is encoded at the transfer, after
  variables and placeholders are filled. Text that would make the encoded
  value longer than 256 bytes is cut first. It also works on a
  [return](#return-the-call-to-your-contact-center).
- `headers_in_uri` can't be used with a `?User-to-User=` written into the
  address itself; move that value into `headers` instead.

Add SIP addresses and headers with the
[Agents API](/api-reference/agents#transfer-numbers) (`transfer_destinations`),
or in an inline call config.

### Return the call to your contact center

When your contact center sent the call, the agent can hand it back instead of
transferring it: it says goodbye, ThunderPhone hangs up, and the SIP `BYE` it
sends carries routing data your platform reads to decide where the caller goes
next. Add a transfer number with `"action": "return"` and no number:

```json
{
  "name": "Contact center",
  "action": "return",
  "headers": {
    "X-RouteType": "queue",
    "X-RouteValue": "{{queue_id}}",
    "User-to-User": "{{uui}}"
  }
}
```

- The prompt names it like any other transfer number, for example "when the
  caller asks for a person, transfer to Contact center".
- The `BYE` can carry `X-RouteType`, `X-RouteValue`, `X-RouteReason`,
  `X-CustomMetaData` (the four Five9 reads) and `User-to-User`, each
  optional. Values follow the rules for
  [SIP headers on the transfer](#sip-headers-on-the-transfer): at most 256
  bytes, call variables allowed, line breaks removed. The `BYE` also carries
  `X-TP-Handoff-Id` (see
  [Pass context to your contact center](#pass-context-to-your-contact-center)).
  A return without headers otherwise just hangs up, and your platform handles
  the call as after any hangup.
- It works on the same calls as a transfer to a SIP address: calls to a
  [SIP address](/guides/sip-addresses) and calls on a number on a manual SIP
  connection. Other calls don't offer it to the agent, and Browser Talk and
  simulations refuse it. A warm transfer to it runs as a plain return.
- Nothing is dialed and no `REFER` is sent. The call ends with the end reason
  `returned_to_platform`.
- The headers ride on your SIP trunk's settings. SIP addresses and manual SIP
  connections set up before this option existed need a one-time update from
  ThunderPhone; ask support before you rely on the headers.

Add a return with the [Agents API](/api-reference/agents#transfer-numbers)
(`transfer_destinations`), or in an inline call config. The dashboard keeps one
you added, and its headers, when you edit the other transfer numbers.

### Pass context to your contact center

On a call that can reach your contact center (a transfer to a SIP address, or a
return), the agent can say what the caller needs, so the person or flow that
takes the call doesn't start from scratch. Use three placeholders in that
entry's `headers`:

| Placeholder | What it holds |
|---|---|
| `{{handoff_summary}}` | What the caller needs and what the agent already did, written by the agent at the transfer. At most 300 characters. |
| `{{handoff_intent}}` | A short label the agent picks, like `billing_dispute`. At most 60 characters. |
| `{{handoff_id}}` | An id for this transfer, for the lookup below. |

```json
{
  "name": "Support queue",
  "number": "sip:support@pbx.example.com",
  "headers": {
    "X-Summary": "{{handoff_summary}}",
    "X-Intent": "{{handoff_intent|general}}",
    "X-Handoff-Id": "{{handoff_id}}"
  }
}
```

- They are filled at the moment of the transfer, not when the call starts. A
  value the agent left out is empty, or the `|default` you wrote.
- Line breaks are removed, and a header whose filled-in value is over 256 bytes
  is cut to 256 bytes. The transfer goes ahead either way.
- A return always sends the id as `X-TP-Handoff-Id` on the `BYE`, whatever its
  headers say.
- On a phone number entry, or on a call that can't reach your contact center,
  they are ordinary call variables: empty unless the call has variables of
  those names. Other calls never see the extra fields, so their agents behave
  as before.

To get the full context, call
[`GET /v1/calls/handoff`](/api-reference/calls#look-up-a-handed-off-call) with
your organization's API key and either the id or your platform's own id for the
call (`external_call_id`, from the call-id header it
[sent with the call](/guides/sip-addresses#where-they-show-up)). It returns the call's id
and status, the summary and intent, the SIP headers and variables the call
started with, and once the call has ended, its summary and extracted data.

### Which numbers a call can reach

What a transfer can reach depends on which line carries it. A transfer carried
on ThunderPhone's line can reach US numbers only, excluding premium-rate and
other special-service numbers. A transfer carried by
[your own carrier](/guides/voip-providers) can reach any number you saved.

| Transfer | Carried by |
| --- | --- |
| Cold transfer on an inbound call | The carrier the call arrived on: ThunderPhone's line for a ThunderPhone number, your carrier for a number on your own carrier. |
| Cold transfer on an outbound call | The line the call was placed on. |
| Warm transfer (the new leg to the target) | The line the new leg is dialed on. |

A number on your own carrier places outbound calls and warm legs only through
its connection's own outbound trunk: manual SIP connections with an outbound
trunk, Twilio connections with outbound calling set up, and Telnyx
connections. Without that trunk the number can't dial out at all, so it
supports cold transfer only. Those calls never fall back to
ThunderPhone's line.

If your organization has no numbers on its own carrier, saving a number that
ThunderPhone's line can't reach fails with an error. Once you connect your own
carrier, those numbers save and are marked as working only on transfers your
carrier carries (`platform_ok: false` in the API). One agent can answer on
both kinds of number, so the check runs on each call.

## Before connecting

Each agent chooses what happens when the person at the destination answers a
warm transfer. The setting applies to every warm transfer the agent makes.

| Setting | API value | What happens | Caller's wait |
| --- | --- | --- | --- |
| **Introduce on the line** (default) | `introduce` | The caller is connected as soon as the destination answers and hears its greeting. When the person who answered has finished, the agent introduces the caller in one or two sentences that both of them hear, then drops. Nobody is asked anything. | Ringing only. |
| **Ask first** | `ask_first` | The agent privately briefs the person who answers and asks whether they can take the call. They can ask questions, accept, or decline. If they accept, the caller is connected, the agent introduces the caller on the line, and drops. | Ringing plus the private conversation, often 15 seconds or more. |
| **Whisper** | `whisper` | The agent privately tells the person who answers who is calling and why, in one short sentence. Nothing is asked. Then the caller is connected and the agent drops without saying anything on the line. | Ringing plus one private sentence. |

Use **Introduce on the line** unless the person answering needs to be able to
turn calls away or should hear about the caller before the caller is on the
line. **Ask first** lets them decline, but keeps the caller on hold longer, and
voicemail, silence or a decline all send the caller back to the agent.
**Whisper** gives them the context privately without asking; voicemail sends
the caller back to the agent.

### The briefing

The **Briefing** setting shapes what the agent tells the person who answers
about the caller. With **Introduce on the line**, that is the introduction
both of them hear once they are connected. By default it is very short: who is
calling and why, such as "Hi, I have Alex on the line about an order. Alex, go
ahead." With **Ask first**, it is the one private sentence before the caller
is connected, ending with whether they can take the call; the introduction
after they accept follows the same idea. With **Whisper**, it is the one
private sentence before the caller is connected, such as "I have Alex calling
about a late order, putting them through now." It is a statement, not a
question.

To change what it says, write a **Briefing** instruction on the agent
(`warm_transfer_briefing`, up to 300 characters), for example "The caller's
name, their account number, and what they need." The agent follows it when it
writes each introduction or briefing. Keep it to the few facts that matter: an
introduction or **Whisper** sentence over about 40 words, or an **Ask first**
briefing over about 25 words, is replaced by a short standard line. Leave it blank for the default.

## What happens during a warm transfer

With **Introduce on the line** (the default):

1. The agent tells the caller it is starting the transfer. The call recording
   stops, and ThunderPhone starts calling the destination from the number
   handling the call right away, while the agent is still speaking.
2. While the destination rings, the caller waits briefly in silence. There is
   no hold music in this style.
3. As soon as the destination answers, the caller is already on the line, so the caller hears the greeting from its first word.
4. When the person who answered has finished and is waiting for a reply, the
   agent introduces the caller in one or two sentences that both of them
   hear, such as "Hi, I have Alex on the line about an order. Alex, go
   ahead." The agent judges this from what they said, not from a pause: a
   recording notice or "please hold" is not the end of their turn, "How can I
   help you?" is. If they say nothing, the agent starts after about 3
   seconds. If they start talking over the introduction, the agent stops,
   lets them finish and says it again. After about 15 seconds, for example a
   long phone menu, the agent introduces the caller anyway. A missing or
   overly long introduction is replaced by a short standard line, spoken in
   the call's language.
5. The agent drops automatically; nothing more is said.

Whoever answers is connected. If it is a voicemail greeting, the agent says
nothing into it and drops, so the caller can leave a message. If the
destination does not answer, is busy,
the call cannot be placed, or the person who answered hangs up before the
introduction ends, ThunderPhone ends that call and the caller returns to the
agent. The agent receives the outcome and continues the original conversation.
It can take a message, suggest another route, or make a cold transfer if the
caller still wants one.

<Note>
  With **Introduce on the line**, the recording ends when a warm transfer
  starts, as it does for a cold transfer. Nothing the destination says is
  recorded or transcribed (ThunderPhone only listens, until the introduction,
  to tell when it is speaking and when it has finished), so it does not hear
  the agent's consent announcement. If the transfer fails and the caller returns to the agent, the
  rest of the call is not recorded either; its transcript continues. The
  [call object](/api-reference/calls#call-object) and the
  [completion webhook](/webhooks/call-complete) say when this happened:
  `recording_stopped_at` is the moment the recording stopped and
  `recording_stopped_reason` is `warm_transfer`.
</Note>

### With Ask first

1. The agent tells the caller it is starting the transfer, then the caller
   hears hold music while the destination rings.
2. When the destination answers, the agent lets the person who answers finish
   their greeting first, judged the same way as above. If the agent's consent
   announcement is on, the person who answers hears it first. Then the agent
   speaks its briefing and asks whether they can take the call. The caller, on hold,
   hears none of it.
3. The person can ask questions, which the agent answers from the
   conversation so far. If they accept, the caller is connected, the agent
   introduces the caller in one or two sentences that both of them hear, and
   drops.
4. If they decline, don't reply, or the call reaches voicemail, ThunderPhone
   ends that call and takes the caller off hold. The agent gets the outcome,
   including any message the person asked it to pass on, and continues with
   the caller.

In this style the transfer does not stop the call recording. If the agent
records calls, the private conversation with the person who answers and the
connected call are both recorded. If call recording is off for the agent,
neither is.

### With Whisper

1. The agent tells the caller it is starting the transfer, then the caller
   hears hold music while the destination rings.
2. When the destination answers, the agent waits for the person who answers
   to finish their greeting. If the agent's consent announcement is on, the
   person who answers hears it first. Then the agent tells them, in one short
   sentence, who is calling and why. It does not ask whether they can take
   the call. The caller, on hold, hears none of it.
3. The caller is connected and the agent drops. Nothing is said on the line.
4. If the call reaches voicemail, the agent hangs up on it and takes the
   caller off hold. If the destination does not answer, is busy, or the call
   cannot be placed, the caller also returns to the agent. The agent gets the
   outcome and continues with the caller.

Recording works as it does for **Ask first**: if the agent records calls, the
private sentence and the connected call are both recorded.

## Prompt the agent to transfer well

Put the routing rules in the agent prompt and name each destination exactly as
it appears under **Transfer numbers**. Do not write phone numbers in the
prompt; the agent transfers by name. Specify the transfer mode for each route
and give the agent a fallback for failed warm transfers.

```text
Transfer policy

Confirm the caller's name and reason for calling before any transfer.

| Caller needs | Destination | Transfer mode |
| --- | --- | --- |
| A new purchase or plan change | Sales | warm |
| Help with an existing order | Order support | warm |
| The main office | Front desk | cold |

For a warm transfer:
- Keep the introduction to one or two short sentences: who is calling and
  why.
- Do not plan to speak after the introduction because you will be dropped.
- If the target does not answer or is busy, tell the caller what happened,
  then offer to take a message or try another route. Do not cold-transfer
  unless the caller asks.
```

The agent supplies these fields when it calls the built-in action:

| Field | When used | Purpose |
| --- | --- | --- |
| `destination` | Always | The name of one of the agent's transfer numbers. |
| `mode` | Optional | `cold` or `warm`; defaults to `cold`. |
| `screen_message` | Required for warm | With **Introduce on the line**, the [introduction](#the-briefing) the caller and the person who answers both hear once connected. With **Ask first**, the private briefing the person who answers hears before deciding. With **Whisper**, the private sentence the person who answers hears before the caller is connected. The caller does not hear either private line. |
| `introduction` | Optional for warm | With **Ask first**, the introduction both hear once the person accepts. With **Introduce on the line**, used only when `screen_message` is empty. Not offered with **Whisper**, since nothing is said on the line. |

You do not need to define or attach a custom tool named `transfer_call`. The
action's description follows the agent's **Before connecting** and
**Briefing** settings, so the prompt does not need to repeat them.

## When a transfer is refused

ThunderPhone checks every transfer before placing it. It refuses a transfer
when the name isn't one of the agent's transfer numbers, when a variable number
has no valid value on this call, when a transfer carried on ThunderPhone's
line would reach a number outside the US or a premium-rate number, or when the
destination is a SIP address or a return and the call didn't come from your own
SIP system (see [Transfer to a SIP address](#transfer-to-a-sip-address)).

A refused transfer does not end the call. The agent does not announce the
transfer, receives the reason (including the list of valid names when the name
didn't match), and keeps talking to the caller. Tell it in the prompt what to
do instead, such as taking a message. The refusal appears as a tool error in
the call's history.

## Whisper transfers

“Whisper transfer” is a common industry name for a warm transfer where the
destination hears private context before the caller is connected, without
being asked whether to take the call. That is the **Whisper** setting under
[Before connecting](#before-connecting).

This is different from
[`POST /v1/calls/{id}/whisper`](/guides/monitor-live-calls#whisper-to-the-agent).
That endpoint lets a staff member or owner send private text guidance to the AI
agent during a live call. It does not call or brief a transfer destination.

## Requirements, limits, and testing

| Question | Answer |
| --- | --- |
| Which destinations can a transfer reach? | On a ThunderPhone-provisioned number, only US numbers are supported, toll-free included; Canada, other +1 countries, and premium-rate numbers are not. ThunderPhone refuses any other destination before dialing: the caller stays on the line and the agent gets the reason and keeps talking (see [When a transfer is refused](#when-a-transfer-is-refused)). To transfer to other countries, [connect your own carrier](/guides/voip-providers) and take the call on a number imported through it. The transfer then goes out through your carrier, so the carrier must accept call transfers and allow calls to that country. On a Twilio SIP trunk, turn on **Call Transfers** and **Enable call transfers to the PSTN**. |
| Which numbers support warm transfer? | A number that can place outbound calls: a verified number imported through a VoIP connection with outbound calling, or a ThunderPhone-provisioned number once your organization's [outbound calling request](/guides/get-a-phone-number) is approved. Other ThunderPhone numbers support cold transfer only. If warm mode is unavailable, the action falls back to cold transfer. [Connect a VoIP provider](/guides/voip-providers). |
| Which call types support it? | Cold transfer is available on ordinary phone calls. Browser Talk, widgets, simulations, and test calls cannot test a warm handoff. Saved-agent Realtime omits `transfer_call`; inline Realtime with `call_events` can request cold transfer. |
| What about calls without a saved agent? | An [outbound call](/api-reference/outbound-calls) or [`call.incoming`](/webhooks/call-incoming#response-schema) response with an inline `config`, and an inline [Realtime](/api-reference/realtime#call-events) session, accept the same `transfer_destinations` list. With a list, the call transfers only to those names. Without one, the agent keeps a transfer action that takes a phone number, and calls on ThunderPhone numbers can still reach only US numbers. |
| How do I test it? | Check routing language in Browser Talk or a simulation: you see which name the agent picks, or the refusal. Both always refuse a transfer to a SIP address or a return, since they don't come from your SIP system; that refusal doesn't mean the entry is misconfigured. Then test the complete handoff with a real phone call to the agent's number. Any ThunderPhone or imported number works for a cold transfer; a warm transfer needs a ThunderPhone number whose outbound calling request is approved, or an imported number with outbound calling. |
| How long does the destination ring? | `ring_duration_seconds` accepts 5–120 seconds. `null` uses 45 seconds for warm transfer and the carrier's default for cold transfer. Ordinary outbound calls default to 60 seconds and never ring for less than 14 seconds. The setting does not change inbound ringing. |
| What if my carrier refuses a cold transfer? | Normally your carrier hands the call over to the destination. Some carrier connections refuse transfers, for example a Twilio trunk without call transfer (SIP REFER) enabled. When the call's number can place outbound calls, ThunderPhone then connects the call itself: it dials the destination, the caller hears ringing until it answers, and the agent leaves without an introduction. Recording stops at the transfer. If nobody answers, or the number cannot place outbound calls, the call ends. A refused transfer to a SIP address always ends the call. Your organization's admins get an email the first time a connection refuses a transfer. When you connect a Twilio account in the dashboard, **Allow call transfers** (on by default) turns transfers on for its SIP trunk. For a Twilio connection you already have, use **Turn on call transfers** on the VoIP connections page. Other carriers have the setting in their own portal. |
| How long can the human bridge last? | Up to 4 hours after the agent connects the two people. With **Introduce on the line** the bridge is not recorded: the recording stops when the transfer starts. With **Ask first** and **Whisper** it is recorded when the agent records calls. |
| What happens on failure? | In a warm transfer, if the target does not answer, is busy, or the outbound leg fails, the caller returns to the agent with the result. The prompt should define the next step. A cold transfer has already ended the agent's part of the call, so a failed cold transfer ends the call. |
| What does it cost? | There is no transfer-tool fee. Normal call charges include the warm-transfer flow until the agent leaves. After the AI leaves a warm transfer, ThunderPhone keeps the two people connected and bills that time at a per-minute bridge rate; see [Pricing](/guides/pricing). A cold transfer stops metering at the handoff. When ThunderPhone connects a refused cold transfer itself, the connected time is billed at the same bridge rate. On imported VoIP numbers, your carrier can continue billing the transfer leg while the two people remain connected. |

## Webhooks and end reasons

The completion payload records the destination in `transfer_number` and uses
one of these end reasons:

| `end_reason` | Meaning |
| --- | --- |
| `ai_transfer` | The agent initiated a cold transfer. |
| `ai_warm_transfer` | The destination answered a warm transfer, the parties were connected, and the agent dropped. |
| `returned_to_platform` | The agent [returned the call to your contact center](#return-the-call-to-your-contact-center). `transfer_number` is not set. |

An unanswered, busy, or failed warm attempt is not a completed transfer. The caller returns to the agent, so the eventual end reason reflects
what ends the original call.

For a successful warm transfer, the completion event and the AI call's end
reason are recorded when the AI leaves, right after the parties are connected.
With **Introduce on the line**, the recording covers the call up to the
transfer and ends there (`recording_stopped_at`); the conversation between the
two people is neither recorded nor transcribed. With **Ask first** and
**Whisper**, the recording (when the agent records calls) continues until the
connected call ends.

<Accordion title="Legacy completion webhook">
  A legacy single-URL webhook can delay a cold transfer for up to five minutes
  by returning `{"transfer_ready": false}` and later updating the call's
  transfer-ready state. Webhook endpoint deliveries and warm transfers do not
  use this coordination.
</Accordion>

See [Completion webhooks](/webhooks/call-complete) for the complete payload and
legacy behavior.

## Troubleshooting

### The call drops when the agent transfers

Check the destination's country. Calls on ThunderPhone numbers support
transfers to US numbers only. The carrier can reject a transfer to another
country, which disconnects the caller, and the call still ends with
`ai_transfer`. To reach other countries,
[connect your own carrier](/guides/voip-providers) and route the call through a
number imported from it. The carrier must accept call transfers and allow calls
to that country. On a Twilio SIP trunk, turn on **Call Transfers** and **Enable
call transfers to the PSTN**.

### The agent makes a cold transfer instead of a warm one

Check that the call is using a number that can place outbound calls: a
verified, imported VoIP number with working outbound routing, or a
ThunderPhone number with approved outbound calling. Warm mode is removed from
the tool options for other numbers and for non-phone sessions. Also make the mode explicit in the prompt's
routing table.

### The target never answers

Confirm that your VoIP trunk can place outbound calls to the destination and
that its authentication and routing rules are current. Check the number saved
under **Transfer numbers**. Increase `ring_duration_seconds` if 45 seconds is too short
for a warm transfer.

### The target reaches voicemail

With **Introduce on the line**, the caller is connected to whatever answers,
including a voicemail greeting. The agent recognizes the greeting, says
nothing into the mailbox and drops, and the caller can leave a message. With
**Ask first** and **Whisper**, the agent hangs up on the voicemail and the
caller returns to the agent. If a destination often goes to voicemail, give the agent another route
for it in the prompt.

### A cold transfer waits before connecting

If you use the legacy single-URL webhook, check whether it returned
`{"transfer_ready": false}`. The caller hears hold music while ThunderPhone
waits. Update the call's transfer-ready state when the destination is prepared.

### The agent says it can't transfer

Check that the agent has transfer numbers and that the prompt uses the same
names. An agent with no transfer numbers has no transfer action at all. If the
transfer rides ThunderPhone's line (see
[Which numbers a call can reach](#which-numbers-a-call-can-reach)), the
destination must be a US number that is not premium-rate. For a variable
number, check that the call's variables include a valid phone number for it.

### Deploy fails with a transfer number error

Every deploy re-checks the saved transfer numbers. A non-US number saved while
your organization had a number on its own carrier fails the check once that
organization no longer has one. Remove the number, or connect your own carrier
again.

### Staff whispering does not start a transfer

Live-call whispering only coaches the AI. Add transfer instructions to the
agent prompt and let it call `transfer_call`. See
[Monitor live calls](/guides/monitor-live-calls).

<!-- en: guides/voice-library -->
---
title: "Voice library, previews, and custom voices"
description: "Search and preview ThunderPhone voices, generate spoken samples, request custom voice access, create a voice from audio, and manage voice pricing and status."
---

Open **Voices** (`/dashboard/voices`) to explore voices for your agents and,
when enabled for your organization, create custom voices from a short audio
sample.

## Browse the voice library

Use search plus the **Language** and **Gender** filters to narrow the catalog.
Each row shows the voice name, supported language information, a built-in audio
sample, and whether it is a premium voice.

The agent builder filters this same catalog to voices compatible with the
agent's primary and additional languages. Selecting a voice in the library does
not change an agent; open the agent's **Config** tab to assign it.

## ElevenLabs voices

The library also lists voices from ElevenLabs under ElevenLabs' own names. They
run on ElevenLabs' **Eleven v4 Turbo** model and speak every language in the
[language catalog](/guides/supported-languages), so an agent's languages never
rule one out. Each one plays ElevenLabs' own sample; generating a sample of
your own text (below) isn't available for them yet.

- An ElevenLabs voice is billed at ElevenLabs' list price, plus the markup,
  in every language. That costs more per minute than a default Inworld voice.
- ElevenLabs voices are **not HIPAA eligible yet**. An agent that processes PHI
  can't select one, and an agent that uses one can't be switched to processing
  PHI. If you need them on PHI calls, ask us to enable HIPAA for them.
- If an agent's calls become PHI calls some other way (for example, a BAA is
  recorded for your organization), those calls use a standard voice for the
  call language instead and carry no ElevenLabs charge.
- In the API an ElevenLabs voice is `elevenlabs:<voice_id>`. `GET /v1/voices`
  lists them in its `elevenlabs` block; see the [Voices API](/api-reference/voices).

## Hear a voice say your text

Choose **Hear _voice_ say your words**, enter **1–500 characters**, select a
supported language, and generate a sample.

- Each new sample costs **3¢** from the organization balance.
- The confirmation dialog shows the charge before generation.
- An identical cached sample is served free and marked **Served from cache**.
- Each organization can create up to **30 samples per hour**.
- A voice can be previewed only in languages available for that voice.

The [Voice samples API](/api-reference/voice-samples) exposes the same workflow
programmatically.

## Request custom voice access

Custom voices are enabled per organization. If access is not enabled, choose
**Request access**, enter the number of voice slots you need, and optionally
describe the use case in up to **2,000 characters**.

Only one request can be pending at a time. After access is enabled, the page
shows the number of used and available custom-voice slots. Use **Request more
slots** when you need a higher quota.

## Create a custom voice

<Steps>
  <Step title="Confirm your rights">
    Confirm that you have the rights to use and clone the voice. A custom voice
    cannot be created without this confirmation.
  </Step>
  <Step title="Record or upload a clean sample">
    Record up to 15 seconds in the browser, or upload a **WAV** or **MP3** file
    up to **4 MB**. Use one speaker, a steady pace, and as little background
    noise as possible.
  </Step>
  <Step title="Name and classify it">
    Enter a name of 1–100 characters, choose its language, and optionally mark
    the voice as female or male. Select **Create voice**.
  </Step>
</Steps>

Creation is asynchronous. A voice moves through **Creating**, **Ready**, or
**Failed**. Ready voices can be played and assigned to agents; a failed voice
can be retried with a new sample.

<Note>
  The custom-voice language picker contains the languages supported for custom
  voice creation. It may be narrower than the complete
  [voice-agent language catalog](/guides/supported-languages).
</Note>

## Rename, retry, and delete

- **Rename** changes the label shown throughout the dashboard without changing
  the voice id.
- **Try again** starts a new creation attempt after a failure.
- **Delete** removes the voice from your organization's picker and frees its
  quota slot. Agents already using it keep their saved configuration until you
  re-save them with another voice.

For the complete object, status, quota-request, preview, rename, and deletion
contracts, see the [Custom voices API](/api-reference/custom-voices).

## Pricing

The voice is one part of a call's price: its characters are billed at the voice
provider's list price, plus the markup. There is no flat voice or language
surcharge. Premium voices from Cartesia and ElevenLabs cost more per minute than
the default Inworld voices, because their list prices are higher. With your own
Cartesia key, Cartesia bills you for the voice and ThunderPhone charges nothing
for it. Organization-specific custom-voice pricing, when applicable, is
returned by the custom voice policy. See [pricing](/guides/pricing).

<!-- en: guides/billing-and-topups -->
---
title: "Add funds and turn on auto top-up"
description: "Pay-as-you-go billing: add a card, load your balance, and set auto top-up so a call never dies mid-sentence."
---

Every new account includes **$10 of free call credit** in its first
organization, with no credit card required. Organizations you add later start
without it. The credit pays for any call: browser tests, phone calls, SIP
calls, web and widget calls, and simulations. Calls use the credit first, then
your cash balance. It cannot pay for phone numbers or voice samples, so add
funds with a card when you want a number.


ThunderPhone billing is pay-as-you-go: each call draws from your
organization's balance what its parts cost at our providers' list
prices, plus an infrastructure charge and a markup. No
subscriptions, no seats. Everything on this page lives under
**Organization → Billing Settings**.

## 1. Add a card

A card unlocks top-ups and phone numbers. It's only charged when you
add funds — **never automatically** (unless you later opt into auto
top-up).

## 2. Load your balance

Click one of the preset amounts ($25–$1000) or enter your own, then
**Add to balance** — a confirmation dialog shows exactly what you're
about to charge before you click **Confirm and charge**. Add at least
**$3.00** to start making real calls. Funds never expire.

<Note>
  What a minute costs depends on the agent's setup: its intelligence,
  hearing, voice, prompt size and phone line. Zeus shows what a minute
  of each agent costs before you go live; see
  [pricing](/guides/pricing). Running
  [outbound campaigns](/guides/outbound-campaigns)? Every campaign
  call draws from this same balance, so size your top-ups (or auto
  top-up) to the list you're dialing.
</Note>

## 3. Turn on auto top-up (optional, recommended)

When the balance is about to run out mid-call, the agent is told to
apologize, wrap up, and say goodbye, and the call ends once it is spent.
Auto top-up prevents that from ever happening:

<Steps>
  <Step title="Enable the switch">
    Flip **Enable auto top-up**.
  </Step>
  <Step title="Set the trigger and refill">
    Choose **When balance falls below** (the threshold) and **Add
    amount** (the refill). When the balance dips under the threshold,
    ThunderPhone charges your card for the refill amount.
  </Step>
  <Step title="Optionally cap the month">
    Check **Monthly spending limit** to bound how much auto top-up can
    spend per calendar month.
  </Step>
  <Step title="Save">
    Click **Save changes**.
  </Step>
</Steps>

## Prompt size

Longer prompts cost more per minute, because the models read the prompt
on every reply. That includes page `context` supplied by an embedded
[web widget](/guides/embed-web-widget), which is capped at 12,000
characters (roughly 3,400 tokens of typical English text), and large tool
results. The prompt editor in the dashboard shows a live token estimate
while you edit.

The complete pricing reference, with the parts of a call, typical prices,
price targets and hard caps, simulations and phone numbers, is at
[ThunderPhone pricing](/guides/pricing).

## Watch the money

The **Billing History** tab lists every transaction — top-ups
(manual and automatic), per-call usage, and monthly phone-number
charges. The same data is available programmatically via the
[Billing API](/api-reference/billing).

---

## Next steps

<CardGroup cols={2}>
  <Card title="Get a phone number" icon="phone" href="/guides/get-a-phone-number">
    With funds loaded, numbers are a click away.
  </Card>
  <Card title="Billing API reference" icon="code" href="/api-reference/billing">
    Balance, top-ups, auto-reload, and transactions over REST.
  </Card>
  <Card title="Pricing reference" icon="coins" href="/guides/pricing">
    How calls are priced, typical prices, and one-time charges.
  </Card>
</CardGroup>

<!-- en: guides/get-a-phone-number -->
---
title: "Get a phone number (from ThunderPhone or your own)"
description: "Get a ThunderPhone number in seconds, or connect your VoIP provider to use numbers you already own."
---

Numbers are how callers reach your agent. On **Phone Numbers**
(`/dashboard/phone-numbers`), click **Add number** to see your two
options:

- **ThunderPhone number** — a real U.S. number from ThunderPhone's
  pool, live in seconds. It costs **{/* rate:phone */}$1/month{/* /rate */}**, its call
  minutes are billed as the phone line, and it starts as **inbound-only**. You can request permission
  to use it for outbound calls.
- **Connect VoIP provider** — import numbers you already own, or
  provision new ones, through your own provider. These numbers support
  outbound calls and campaigns without requesting ThunderPhone-number access.

## The ThunderPhone path

<Steps>
  <Step title="Choose ThunderPhone number">
    In the Add-number chooser, pick **ThunderPhone number**.
  </Step>
  <Step title="Pick who answers">
    Select the **agent that answers this number** and (optionally) a
    preferred area code.
  </Step>
  <Step title="Get the number">
    Click **Get number**. The number appears in your table and is
    ready to take calls within seconds.
  </Step>
</Steps>

Provisioning auto-routes the number to your agent — the **Inbound**
select on the number's row shows who answers, and you can change it
anytime.

<Note>
  ThunderPhone numbers start as inbound only. To request outbound access,
  select **Request outbound calling** on the Phone Numbers page and tell us
  how many outbound calls per day you need, your use case, how you obtain
  consent, and your website. Once approved, you can request a higher daily
  limit from the same page. Numbers from your own VoIP provider have no daily
  limit. We review each request by hand and show the result on the page.
  You can still connect your own carrier for outbound calling without this
  permission. An organization can hold 25 ThunderPhone numbers by default;
  request a higher limit from the same page if you need more.
</Note>

## The VoIP path

**Connect VoIP provider** takes you to **Connections → VoIP** — the
full flow is covered in
[Connect a VoIP provider](/guides/voip-providers). In short, two
routes:

- **Connect a provider you already use**: paste an API key for
  **Twilio** or **Telnyx**, or pick **SignalWire**, **Vonage**,
  **Plivo** or **Other provider** to fill in SIP trunk details, with
  provider-specific steps for the named ones and a **Generate AI Setup
  Guide** button for any trunk. Both end with a connection test.
- **Set up a new Telnyx account**: a step-by-step flow that walks you
  through creating a Telnyx account, generating an API key, and
  connecting, with a **Connect & Test** check at the end.

Once connected, import the numbers you want; imported numbers support
inbound **and outbound**. The programmatic version of this flow is
[Bring your own numbers (API)](/guides/bring-your-own-numbers).

## Manage your numbers

Each row in the numbers table gives you:

- **Copy** the number, and a **label** field to name it.
- **Routing mode** and the **Inbound** agent select.
- An **actions** menu (⋯) for everything else, including release.

### Label phone numbers

In **Phone Numbers**, select **Add label** beside a number, enter 1–100
characters, and save. Use **Edit label** or **Remove label** to change it later.
Labels are shared across your organization and can also identify external
caller or destination numbers from call history. They appear in call details
and under **Exclude numbers from analysis** in AI reports.
Developers can manage the same E.164-based labels with the [Phone Number Labels
API](/api-reference/phone-number-labels).

### Caller name and spam registration

Your ThunderPhone numbers show your organization's caller name automatically.
Numbers in your own Twilio or Telnyx account can be registered for a caller
name, verified caller ID and the carriers' spam filters from the **Caller ID and
spam registration** section. See
[Caller ID and spam registration](/guides/caller-id-and-spam-registration).

## Hear it for real

Dial the number from your own phone and talk to your agent. Or run a
[simulation](/guides/simulate-a-call) and let an AI caller do it.

---

## Next steps

<CardGroup cols={2}>
  <Card title="Simulate a call" icon="flask" href="/guides/simulate-a-call">
    An AI caller rings your new number.
  </Card>
  <Card title="Bring your own numbers (API)" icon="phone-volume" href="/guides/bring-your-own-numbers">
    The VoIP connect-import-verify flow over REST.
  </Card>
  <Card title="Phone numbers API" icon="code" href="/api-reference/phone-numbers">
    Provision and assign programmatically.
  </Card>
  <Card title="Run outbound campaigns" icon="megaphone" href="/guides/outbound-campaigns">
    Use an outbound-enabled customer VoIP or ThunderPhone number at scale.
  </Card>
  <Card title="Caller ID and spam registration" icon="shield-check" href="/guides/caller-id-and-spam-registration">
    Show your business name and register numbers so more people answer.
  </Card>
</CardGroup>

<!-- en: guides/caller-id-and-spam-registration -->
---
title: "Caller ID and spam registration"
description: "Show your business name on calls and register your numbers with the carriers' spam filters, so more people pick up."
---

Phone carriers decide whether your call shows as your business, as a plain
number, or as "Spam Likely". Registering your numbers with the carriers' spam
filters and showing your business name makes people more likely to answer.
Everything on this page is free.

Find it on **Phone Numbers** (`/dashboard/phone-numbers`), in the
**Caller ID and spam registration** section under your numbers. Each number
shows three things:

| Column | What it means |
|---|---|
| **Caller name** | The business name people see when you call (CNAM). |
| **Verified caller ID** | Carriers check that the call really comes from your number (SHAKEN/STIR). Unverified calls are more often labeled spam. |
| **Spam-filter registration** | The number is registered with the spam filters the major US carriers use, so they know who is calling. |

## ThunderPhone numbers: done for you

- **Caller name.** A new ThunderPhone number gets your organization's caller
  name when you buy it. Saving the caller name applies it to every ThunderPhone
  number you have.
- **Verified caller ID.** Calls from ThunderPhone numbers are verified by our
  carrier automatically.
- **Spam-filter registration** is not offered for ThunderPhone numbers yet; the
  page shows **Not offered yet**.

### Set your caller name

The caller name starts as your organization's name, cut to fit. If your
organization still has the name it was created with ("Jane's Team"), there is
no caller name until you set one. Only organization admins can change it, on
**Phone Numbers** or in **Organization Settings**.

<Steps>
  <Step title="Open the caller name">
    On **Phone Numbers**, click **Edit caller name**, or use **Edit** in the
    **Caller name** card in **Organization Settings**.
  </Step>
  <Step title="Type the name">
    Up to 15 characters: letters, numbers and spaces, starting with a letter.
    Leave it blank to use your organization's name. The dialog shows what calls
    will display.
  </Step>
  <Step title="Save">
    ThunderPhone sends the name to the carriers for every ThunderPhone number.
    Turn off **Show a caller name** to stop showing one.
  </Step>
</Steps>

<Note>
  Carriers take 1 to 3 days to show a new name. Landlines show caller names
  reliably; many mobile phones show them only sometimes, or show their own
  label instead.
</Note>

## Numbers in your own Twilio or Telnyx account

Registering a number in your own carrier account changes that account, so
ThunderPhone only does it when an organization admin asks, one number or a few
at a time. Click **Register** in the column you want, choose the numbers, and
confirm. ThunderPhone uses the credentials saved on your
[VoIP connection](/guides/voip-providers).

| | Telnyx | Twilio |
|---|---|---|
| Caller name | Yes, set with your API key. **Turn off** removes it again. | Yes, a CNAM registration in Twilio's Trust Hub. |
| Verified caller ID | Managed in your Telnyx account. | Yes: the number joins a SHAKEN/STIR registration, so Twilio verifies your calls at the highest level (A instead of B). |
| Spam-filter registration | Managed in your Telnyx account. | Yes, through Twilio Voice Integrity. You tell us what the calls are for, your employee count and your daily call volume. |

Caller names are for US local numbers only: carriers don't list them on
toll-free or non-US numbers, so those numbers show no **Register** button for a
caller name. For SignalWire, Vonage and other SIP carriers, register in your
carrier's own console.

### Before you register Twilio numbers

Twilio needs an approved **Primary Business Profile** in its Trust Hub first.
If your account has none, ThunderPhone says so and links to the
[Twilio Trust Hub](https://console.twilio.com/us1/account/trust-hub/overview).
Create the profile there; Twilio usually reviews it within 1 to 3 days. Then
click **Register** again.

When you register, ThunderPhone adds each number to your Business Profile,
reuses your account's existing registration of that kind or creates one, adds
the numbers to it and submits it for review. Registering again never creates a
duplicate. When your account already has a spam-filter registration, new
numbers join it, and the answers you give now (what the calls are for, employee
count, daily calls) are not used; change them in Twilio's Trust Hub.

### Statuses

| Status | Meaning |
|---|---|
| **Sending** | ThunderPhone is sending it to your carrier. |
| **Submitted** | The carrier has it and is about to review it. |
| **In review** | The carrier is reviewing it. Reviews usually take 1 to 3 days. |
| **Approved** | Done. A caller name can take up to 3 more days to reach every carrier. |
| **Rejected** | The carrier said no; the reason shows under the status. Fix it in Twilio's Trust Hub, then click **Try again**. |
| **Needs attention** | Something stopped the registration, such as missing details or credentials that no longer work. The reason shows under the status. |
| **Off** | No caller name is set: it was turned off, or the number left your account. |

Telnyx caller names have no review step: they stay **Submitted** for about 3
days, then turn **Approved** once ThunderPhone reads the listing back from
Telnyx. They never show **In review**. If the name is changed or removed in
your Telnyx account, the status becomes **Needs attention**.

ThunderPhone checks registrations under review about once an hour. Click
**Refresh status** to check now.

## API

The same controls are available over REST at
[`/v1/caller-registration`](/api-reference/caller-registration).

---

## Next steps

<CardGroup cols={2}>
  <Card title="Get a phone number" icon="phone" href="/guides/get-a-phone-number">
    ThunderPhone numbers and your own carrier's numbers.
  </Card>
  <Card title="Run outbound campaigns" icon="megaphone" href="/guides/outbound-campaigns">
    Call your contact list at scale.
  </Card>
</CardGroup>

<!-- en: guides/simulate-a-call -->
---
title: "Simulate a call before you ship"
description: "An AI caller has a real conversation with your agent — same telephony path, real transcript, real grading."
---

A **simulation** is an AI caller talking to your agent for real: it
rings your number (or connects directly to the agent), improvises
within a scenario you set, and produces a normal call log — transcript,
recording, grading — in Call History. It's how you test a prompt
before real callers hear it, and how you catch regressions after every
change.

## Run one from the agent builder

<Steps>
  <Step title="Click Simulation">
    In the agent builder's top bar, click **Simulation**.
  </Step>
  <Step title="Set the scene">
    Generate a caller scenario with AI or write your own — who the
    caller is, what they want, how difficult they're being. Then
    approve the charge and place the call. A simulation bills both sides —
    your configured agent plus the simulated caller — and the dialog shows an
    estimate capped at 10 minutes before you commit. Shorter calls cost less.
  </Step>
  <Step title="Watch it happen">
    A floating activity pill appears as soon as the run is placed —
    your agent is on a call right now. Open the call to follow along;
    you can even [listen in live](/guides/review-calls).
  </Step>
</Steps>

## Build a scenario library

The **Simulations** page (`/dashboard/simulations`) manages scenarios
per agent. Pick an agent and click **Generate scenarios with AI** —
it drafts scenarios from the agent's own prompt, with an optional
**Include edge case scenarios** pass for the hard stuff (angry
callers, wrong numbers, half-answers). Edit and keep the ones you
like.

Scenarios group into **suites** with a minimum pass rate, which can
gate releases in CI — see
[Test an agent end-to-end (API)](/guides/test-agents) for the suite
runner and the programmatic version of everything on this page.

## What to do with the result

Every simulation lands in **Call History** like any other call. Read
the transcript to spot where the prompt needs tightening, check the
grade, and fix-then-rerun. When a real call exposes a gap, promote it:
the call detail page's **Create test case** button turns a real
conversation into a reusable scenario.

Simulation pricing is itemized from both bots and any telephony leg; it is not
a blanket 2× multiplier. See [Pricing](/guides/pricing#simulations-and-testing).

---

## Next steps

<CardGroup cols={2}>
  <Card title="Review the call" icon="headset" href="/guides/review-calls">
    Transcript, recording, listen-in, whisper.
  </Card>
  <Card title="Test-calls API" icon="code" href="/api-reference/test-calls">
    Run simulations and batches programmatically.
  </Card>
  <Card title="Suites in CI" icon="flask" href="/guides/test-agents">
    Release gates with pass rates and regression tracking.
  </Card>
  <Card title="Experiments (A/B)" icon="scale-balanced" href="/guides/experiments-ab-testing">
    Compare variants on live traffic once simulations pass.
  </Card>
</CardGroup>

<!-- en: guides/validation-sets -->
---
title: "Validation sets: replay real call turns before deployment"
description: "Turn real ThunderPhone call moments into reusable validation examples, review expected behavior, replay them against an agent draft, and catch regressions before deploy."
---

A **validation example** freezes one agent turn from a real call: the
conversation leading up to it, the relevant caller audio, what the agent
actually did, and the ground truth for what it should do. Replaying a set
against the current draft catches regressions without placing another call.

Use the organization-wide **Validation sets** page
(`/dashboard/validation`) to build and review the dataset. Use an individual
agent's **Validation** tab to run the set and inspect run history.

## Add examples from call history

<Steps>
  <Step title="Choose Add examples">
    Pick the agent whose behavior the example should validate. The workspace
    shows up to 25 recent non-simulation calls for that agent.
  </Step>
  <Step title="Select a call and agent turn">
    Read the transcript, hover the agent turn you want to preserve, and select
    the checklist action. The conversation through that turn and its caller
    audio spans are copied into the validation dataset.
  </Step>
  <Step title="Review the expectation">
    ThunderPhone drafts a description of correct behavior. Edit it so it is
    specific and testable, and optionally edit the accepted example response
    and expected tool calls.
  </Step>
  <Step title="Save or activate">
    **Save draft** leaves the example in **Needs review**.
    **Save & activate** includes it in future validation runs.
  </Step>
</Steps>

Promoting the same turn twice reuses the existing example rather than creating
two copies. An example is a copy of its call, so
[deleting the call](/guides/review-calls#delete-a-call) deletes the example
too.

## Example kinds and statuses

Kinds describe why an example exists:

| Kind | Use |
| --- | --- |
| **Failure** | A real response that exposed behavior you want to prevent. |
| **Golden** | A known-good response worth preserving. |
| **Manual** | A manually curated case that is neither category. |

Statuses control the lifecycle:

| Status | Meaning |
| --- | --- |
| **Needs review** | Ground truth is still being reviewed; excluded from runs. |
| **Active** | Included in validation runs. |
| **Stale** | The prompt changed since the example was frozen; review its expectation. |
| **Incompatible** | The example cannot be replayed with the current configuration. |
| **Archived** | Preserved for history but excluded from runs. |

## Browse and refine the dataset

Filter the organization dataset by **agent**, **status**, or **kind**. Selecting
an example shows:

- Frozen conversation context and playable caller audio spans.
- The source call and original response.
- Ground-truth expectation, accepted spoken response, and tool calls.
- The latest replay beside the original and expected behavior.
- The latest verdict and judge explanations, when available.

Choose **Edit ground truth** to revise the expectation or accepted response.
Choose **Replay against draft** to test only that example without starting a
full run. Replays use the agent's current draft, not necessarily its deployed
configuration.

## Run a validation set

From the agent's **Validation** tab, start a run over every active example. Each
example receives one of these verdicts:

- **Pass** — the response satisfies the expectation and caller audio.
- **Warn** — the response is usable but one check found uncertainty.
- **Fail** — it contradicts the audio or misses required behavior.
- **Skipped** — required caller audio could not be loaded; it is excluded from
  the pass-rate denominator.
- **Error** — replay or grading could not complete.

The run summary reports pass, warning, failure, and skipped counts, the pass
rate, estimated cost, and any regression from pass to fail since the preceding
completed run. Only one validation run per agent can be active at a time.

## Deploy with validation evidence

When an agent has validation examples, the deploy dialog reports whether the
latest completed run matches the current draft. You can:

- Deploy with the displayed pass rate and regression count.
- Run validation first if no matching run exists.
- Deliberately deploy anyway when the result has been reviewed.

Validation is evidence and a deployment check, not an automatic production
traffic split. For live comparisons, use
[Experiments (A/B testing)](/guides/experiments-ab-testing).

## API automation

The [Validation Sets API](/api-reference/validation-sets) covers promoting
turns, managing examples, streaming pinned audio, individual replays, batch
runs, run results, deploy-time status, and the organization overview.

<!-- en: guides/review-calls -->
---
title: "Review, listen to, and coach your calls"
description: "Call History end-to-end: transcripts, recordings, live listen-in, and whispering instructions to your agent mid-call."
---

Every call — inbound, outbound, simulation, or widget session — lands
in **Call History** (`/dashboard/call-history`), newest first. This is
where you find out what your agent actually said, and where you can
step into a live call and steer it.

## Find the call

The list filters by **Date**, **Type**, **From**, **To**, **Agent**,
**Outcome**, **Needs attention** (calls flagged for a follow-up) and
**Business hours**, and the **Columns** button controls what each row
shows. The
**Outcome** column carries the label the call report chose (the agent's
own list, or Success / Failure), **Summary** the one-line summary, and
**Needs attention** the follow-up reason. Phone numbers take labels (e.g.
"Acme Corp") so recurring callers are recognizable at a glance. Click any
row to open the call.

## Set up call reports

Open the agent builder and expand **Reporting**. Next to **Outcome
labels**, choose **Edit**. Use **Suggest from prompt** or write your own
labels, and give each one a description under **When to use it**. Keep
2–12 labels, or choose **Replace all → Success / Failure** to restore the
defaults.

Under **Summary rules**, choose **Edit** to add instructions for the
report's wording, then **Done**. Test the draft with a browser call that
includes a conversation. After grading finishes, open the call in Call
History and check its outcome, summary and follow-up flag. Choose
**Deploy** to apply the changes to production calls. For API setup, see
[agent reporting fields](/api-reference/agents#deployed-fields).

## Label a phone number

Any number in the **From** or **To** column takes a label ("Aetna", "Main
line", "Jack Morrison"): hover the number and choose the pencil. Labels are
shared by everyone in the organization. They appear in Call History, on
Home, in the Client Portal Calls table and in portal CSV exports. The
**From** and **To** filters search labels too: type a label to pick every
call from that party.

## Read the conversation

The transcript shows every turn, word for word — including the
agent's tool calls and their results. It's the fastest way to spot
where the prompt needs tightening. Alongside it:

- **View** the exact prompt snapshot the call ran with (and download
  it) — what the agent was told, not what the agent is told today.
- **Create test case** — turn this conversation into a reusable
  [simulation scenario](/guides/simulate-a-call).

## Hear it back

Ended calls have a recording — scrub the waveform to replay any
moment, or download the audio.

## Listen in — live

While a call is **in progress**, the recording spot offers **Listen
in** instead. Click it and you join the call silently: you hear
everything, and nobody on the call hears you. Use it to watch a new
prompt take its first real traffic, or to supervise a
[campaign](/guides/outbound-campaigns) as it runs. The
[**Live** page](/guides/monitor-live-calls) shows every in-progress
call across the org, one click from the same experience.

## Whisper — coach your agent mid-call

Once you're listening, a whisper bar appears. Whatever you type goes
**straight to your agent**: the caller never hears it, and the agent
follows the instruction live, mid-conversation.

Try one on your next simulation: `wrap up the call politely`. Or in
production: `the caller is a VIP — offer the expedited option`,
`stop offering refunds`, `ask for their order number`.

Whispers are first-class steering — private operator guidance of up
to 500 characters per message. They show up in the call's internal
history but never in the customer-facing transcript, and the agent
treats them as instructions, not conversation.

<Tip>
  Listen-in and whisper are also available over the API — see the
  [calls reference](/api-reference/calls) — so you can build your own
  supervision console.
</Tip>

## Close the loop

Spotted a problem? File an issue on the call — issues carry severity
and status and queue up for triage on the
[Issues](/guides/issues) page. Recurring themes across many
calls are what [Reports](/guides/reports) and
[Observability](/guides/observability) are for.

## Delete a call

Owners and admins can permanently delete calls. Open a call and choose
**Delete call**, or tick several calls in the list and choose **Delete** in
the selection bar. Deleting removes the recording, transcript, summary,
extracted data, grades and issue reports, and cannot be undone. It also
deletes any [validation examples](/guides/validation-sets) made from the
call; the confirmation says how many. A call that
is still in progress, or whose billing is still being settled right after
it ends, can't be deleted yet; try again in a few minutes.

Your billing history keeps the charge for each deleted call, without any of
its content. To delete calls from your own systems, use the
[calls API](/api-reference/calls#delete-a-call).

---

## Next steps

<CardGroup cols={2}>
  <Card title="Simulate a call" icon="flask" href="/guides/simulate-a-call">
    Practice listening in and whispering on an AI caller first.
  </Card>
  <Card title="Calls API reference" icon="code" href="/api-reference/calls">
    Transcripts, history, audio, grading, and export over REST.
  </Card>
  <Card title="Issue reports API" icon="triangle-exclamation" href="/api-reference/issue-reports">
    File and query issues programmatically.
  </Card>
  <Card title="Fix the prompt, redeploy" icon="robot" href="/guides/build-an-agent">
    Every deploy is versioned — iterate fearlessly.
  </Card>
</CardGroup>

<!-- en: guides/knowledge-base -->
---
title: "Knowledge base"
description: "Upload your docs once — FAQs, policies, product sheets — and let agents search them mid-call."
---

The **Knowledge** page (`/dashboard/knowledge`) is your organization's
document store. Upload files once, then select the exact documents each
agent can search; during calls the agent looks up answers in its attached
documents instead of guessing.

It is also the right home for large reference content such as menus,
catalogs, and policies. The agent searches for the part it needs, instead
of carrying a tool result that returns everything on every turn.

## Supported files and limits

| Type | Extensions | Size limit |
| --- | --- | --- |
| Text | `.txt`, `.md`, `.csv` | 5 MB per file (UTF-8) |
| Binary | `.pdf`, `.docx` | 50 MB per file |

## Upload documents

Click **Upload files** or drag files anywhere onto the page — you can
drop several at once. Each document is processed for search after upload;
its status badge tracks the progress, and a **Retry** action appears on
anything that fails (plus a **Retry all** banner when several fail).

If a file's content is identical to a document already in the
organization, it still uploads but you'll see a duplicate warning so you
can tidy up.

<Note>
  Adding, editing, replacing, and deleting documents requires an
  **admin** or **owner** role. Any member can browse and search.
</Note>

## Find and maintain documents

- **Search** — the search box matches document names *and* contents.
- **Open a document** — click its row to view the extracted content,
  download the original file, **replace** it with a new upload
  (re-processed automatically), retry processing, or delete it.
- **Bulk actions** — select multiple rows to retry or delete together.

<Warning>
  Deleting a document removes it from every agent that uses it.
</Warning>

## Give an agent access

Documents don't apply to agents automatically. In the agent builder's
knowledge section ([Build an agent](/guides/build-an-agent)), pick the
exact documents that agent may search. Scoping per agent keeps a support
agent out of your sales playbook and vice versa.

## Next steps

<CardGroup cols={2}>
  <Card title="Build an agent" icon="robot" href="/guides/build-an-agent">
    Attach documents in the builder's knowledge section.
  </Card>
  <Card title="Simulate a call" icon="flask" href="/guides/test-agents">
    Verify the agent actually uses its knowledge before you ship.
  </Card>
</CardGroup>

<!-- en: guides/outbound-campaigns -->
---
title: "Outbound campaigns"
description: "Upload a contact list and let an agent work through it — with calling windows, retries, and live progress."
---

Campaigns dial a list of contacts on your behalf: pick an agent, upload a
CSV, set when calling is allowed, and ThunderPhone works through the list
— retrying no-answers and voicemails on the schedule you choose. Find
them under **Engagement → Campaigns** (`/dashboard/campaigns`).

For one-off programmatic calls, use the
[outbound calls API](/guides/place-outbound-calls) instead.

## Prerequisites

- A deployed voice agent.
- An outbound-enabled phone number. Customer VoIP numbers continue to support
  campaigns. ThunderPhone numbers start inbound-only; an organization admin can
  request outbound calling from the Phone Numbers page. ThunderPhone reviews
  each request manually, and approved numbers can run campaigns. See
  [Connect a VoIP provider](/guides/voip-providers).
- Contacts as a CSV file (or pasted JSON) with a `phone` or
  `phone_number` column. **Up to 5,000 rows per upload**, UTF-8 encoded.
  New JSON uploads must be flat: extra values may be strings, numbers,
  booleans, or `null`. Rows containing arrays or nested objects are rejected
  individually with a validation message; valid rows still import. CSV cells
  are strings. Accepted extra columns are kept as per-contact variables on the campaign's
  contact records and automatically supplied to each dial. ThunderPhone also
  classifies the saved agent prompt before each outbound call to decide whether
  the agent should navigate a phone menu. Headers such as `name` and `account_id`
  match `{{name}}` and `{{account_id}}` in the saved agent's prompt. Name mapping can also combine columns into `name`. See
  [per-call variables](/guides/call-variables) for defaults, naming rules,
  the 32 KB object limit, and values returned in completion webhooks.

Older contact records may contain nested metadata from earlier JSON uploads.
That metadata stays on the stored contact. Each dial omits non-scalar values from
its variables payload and logs the ignored key names for that attempt, without
logging values. Retries use the same filtering.

## Create a campaign

<Steps>
  <Step title="Click New campaign">
    Name it, pick the **voice agent**, and choose the **from numbers**:
    one or more of your outbound-enabled numbers. Spreading calls across
    several local numbers keeps each number under carrier spam thresholds
    and shows people a local area code. See
    [number pools](#number-pools-and-daily-limits).
  </Step>
  <Step title="Upload the contacts CSV">
    Rows with an invalid phone number or invalid variables are rejected individually and
    reported back with their row numbers — the rest import fine.
  </Step>
  <Step title="Set the calling window">
    Choose a **timezone** and a **daily start/end** window; the campaign
    only dials inside it. The timezone starts on your first from number's zone
    (its area code in the US and Canada, its country elsewhere) or, for
    numbers that span several zones such as toll-free ones, your
    browser's. The hint under the field says which. The window defaults
    to 9am–5pm. A window that starts before 8am or ends after 9pm shows a
    warning: calls outside those hours may break calling-hours rules such
    as the TCPA's. An end earlier than the start crosses midnight: 22:00 →
    02:00 dials from 10pm until 2am the next day, with a warning.
    **Call in each contact's local time** (on by default) runs the window
    where each contact is, by their area code: 9am means 9am in New York
    for a New York contact and 9am in Los Angeles for a Los Angeles one.
    Contacts without a US or Canadian area code use the timezone above,
    and an area code that spans two zones is called only while both are
    inside the window.
    Turn it off to run the window in the campaign's timezone for everyone.
    Optionally set a **start at** to schedule the launch and an
    **end at** after which the campaign completes automatically.
  </Step>
  <Step title="Tune pacing and retries">
    - **Concurrent calls** — how many calls this campaign runs at once
      (1–10, default 3). Campaigns start no new call while your
      organization has 10 outbound calls in progress, so parallel
      campaigns share that budget. Every call also counts toward your
      organization's [concurrent-call limit](/api-reference/introduction#call-limits)
      (20 by default, across inbound, outbound, web and test calls).
      When that limit is reached, or the same number was called in the
      last 10 seconds, the contact simply waits for a later pass; its
      attempts are not used up.
    - **Calls per number per day** — the most outbound calls each from
      number places in any 24 hours (1–500, default 75). Clear it for no
      limit.
    - **Maximum attempts** — how many times each contact may be dialed
      (1–10, default 2).
    - **Retry backoff (minutes)** — the shortest wait before a retry (at
      least 30, default 60).
    - **Retry timing** — **Spread across days and times of day** (the
      default) moves each retry to a later day and a different part of
      the contact's day: morning, then midday, then late afternoon.
      **After the backoff** retries exactly the backoff later.
    - **Call twice when there's no answer** — if a call rings out, call
      once more from the same number 30–60 seconds later. It doesn't use
      an attempt. On iPhone, a second call within three minutes can ring
      through Do Not Disturb when Allow Repeated Calls is on. Redials take
      dialing time, so a campaign where most calls ring out reaches new
      contacts more slowly with this on.
    - **Retry on** — which outcomes trigger a retry: **no answer**,
      **voicemail**, **failed** (all on by default).

    Need more attempts or shorter spacing? Contact support: staff can
    raise both limits for your organization.
  </Step>
  <Step title="Create draft, then start">
    Campaigns are created as drafts — contacts can only be added while a
    campaign is a draft. Starting a campaign requires an explicit consent
    to the call charges. With a future **start at** it becomes
    *scheduled*; otherwise it starts *running* immediately.
  </Step>
</Steps>

<Note>
  Campaigns saved before these limits keep running exactly as configured.
  Their attempts and spacing stay as saved through other edits.
</Note>

## Number pools and daily limits

Phone carriers label numbers as spam when they place many calls a day or
call in bursts, and people pick up more often when they see a local area
code. A campaign with several from numbers (its pool) spreads its calls
across them:

- Each contact is called from the number it was last called from, so
  retries come from the same caller ID. A new contact gets a pool number
  with its area code, else one in its timezone, else the number used
  least in the last 24 hours. The contacts table shows which number
  called each contact. With **Text before calling** on, a number keeps
  room for the contacts it texted, so when that room is all spoken for
  a retry may come from another pool number.
- **Calls per number per day** counts every outbound call from that
  number in your organization over the last 24 hours, including other
  campaigns and API calls.
- A ThunderPhone number with less than a week of outbound calls warms
  up: it places at most 20 calls on its first day, rising evenly to the
  full limit by day 7. Numbers on your own carrier skip the warm-up.
- When every number has reached its limit, contacts wait. Nothing fails
  and no attempts are used; the campaign page says why it is waiting, and
  calling resumes on its own as the last day's calls age out. To go
  faster, pause the campaign and add numbers or raise the limit.
- If a number stops working mid-campaign, the campaign keeps calling from
  the others, and pauses only when none is left.

As a rule of thumb, size the pool so the list's daily volume divided by
the number of numbers stays under the limit. A pool is for pacing and
local presence: retire a number that gets labeled as spam rather than
adding fresh ones to hide it.

## Text before you call

People are more likely to pick up a number they were told to expect. A
campaign can text each contact a few minutes before their first call,
saying who is calling and from which number.

Turn it on in the campaign's create or edit form, under **Text before
calling**: switch it on, pick a number under **Send texts from**, edit
the **Message**, and set **Minutes before the call** (1–60, default 2).
Through the API, set the `pre_call_sms_*` fields on the
[campaign](/api-reference/campaigns#text-before-calling).

- Texts go out through your own Twilio or Telnyx number. ThunderPhone
  numbers cannot text.
- The message can use the contact's variables plus `{{org_name}}`,
  `{{agent_name}}` and `{{call_from_number}}` (the pool number that will
  call this contact; the call comes from it). A missing variable is
  left out, so a contact with no first name gets "Hi, this is …". The
  default message:

  ```text
  Hi {{first_name}}, this is {{org_name}}. We'll call you in a few minutes from {{call_from_number}}. Reply STOP to opt out of texts.
  ```
- Only the first call gets a text; retries never do. Campaigns place
  calls in passes every 5 minutes, so with the default 2 minutes the
  call comes about 5 minutes after the text.
- Keep the minutes before the call short. A texted contact holds its
  call slot until it is called, so a long lead slows the campaign: with
  3 calls at a time and 30 minutes, it texts 3 people and then waits
  half an hour to call them. A texted contact is called ahead of due
  retries.
- A text goes out only when the calling window is open and will still
  be open for the call, with 5 minutes to spare. With **Call in each
  contact's local time** on, that is the contact's own window. Otherwise the contact
  waits for the next window. The window must be at least the minutes
  before the call plus 12 minutes.
- A text that fails or is skipped never holds up the call: the contact
  is dialed right away. Landlines are skipped. Failed texts are not
  resent.

<Warning>
  Texting needs the same consent as calling; texts fall under the TCPA
  and carrier rules too. A US local number must be registered for A2P
  10DLC on your Twilio account (until it is approved, contacts are
  called without a text and the campaign shows a warning), a toll-free
  number needs toll-free verification, and a Telnyx number needs a
  messaging profile. Carrier fees are billed by your carrier.
  ThunderPhone does not receive replies yet, so STOP is handled by your
  carrier's opt-out handling. See [SMS](/api-reference/sms).
</Warning>

Open the campaign to see each contact's text result in the **Text**
column: delivered or sent, not sent (with the reason), skipped or unknown. Through the API it is the contact's
[`pre_call_sms`](/api-reference/campaigns#contact-object), and each
text also appears in `GET /v1/sms` with `source: "pre_call"`.

## How outcomes and retries work

After each call, the contact gets an outcome — successful calls are
marked completed; a call graded as no-answer, detected as voicemail, or
failed is retried if that outcome is in your **retry on** list and the
contact has attempts left. Contacts that run out of attempts are marked
*exhausted*; non-retryable failures are marked *failed*.

<Note>
  Dialing pauses automatically while your account balance isn't in good
  standing, and resumes once it is. Keep
  [auto top-up](/guides/billing-and-topups) on for long campaigns.
</Note>

## Monitor and control

Each campaign card shows its status and progress (e.g. "173 of 248
finished"). Open a campaign for the status breakdown, per-contact
results, and recent calls — each links to the full transcript and
recording in call history.

- **Pause / resume** — pausing stops new dials; calls already in
  progress finish naturally. Paused campaigns can be edited and resumed.
- **Cancel** — permanently stops the campaign.
- A campaign completes on its own when every contact reaches a final
  state or the **end at** time passes.

Campaign statuses: `draft`, `scheduled`, `running`, `paused`,
`completed`, `cancelled`. Contact statuses: `pending`, `scheduled`,
`calling`, `completed`, `failed`, `exhausted`.

## Next steps

<CardGroup cols={2}>
  <Card title="Watch calls live" icon="tower-broadcast" href="/guides/monitor-live-calls">
    Listen in on campaign calls as they happen.
  </Card>
  <Card title="Outbound calls API" icon="phone-arrow-up-right" href="/guides/place-outbound-calls">
    Place individual calls programmatically.
  </Card>
</CardGroup>

<!-- en: guides/outbound-deliverability -->
---
title: "Get outbound calls answered"
description: "Keep your numbers from being labeled spam and get more people to pick up, for calls placed through the API and through campaigns."
---

Carriers decide whether your call shows your business name, a plain number
or "Spam Likely". People decide whether to pick up. The label depends
mostly on how each number calls, so most of what helps is in your hands.

## How carriers judge a number

Three analytics companies score US calls for the big carriers: Hiya for
AT&T, TNS for Verizon and First Orion for T-Mobile. They don't publish
their scores, but they weigh the same signals:

- How many calls a number places a day, and whether they come in bursts.
- How many calls end within seconds, and how often a person answers.
- Complaints from the people you call.
- The STIR/SHAKEN attestation on each call, and whether the number is
  registered with them.
- Whether the number takes calls back.

Whether someone picks up also depends on a local area code, a name they
recognize, knowing you'll call, the time of day, and getting past iPhone
Call Screening and Pixel Call Screen.

## Which levers apply to your calls

Some protections apply to every outbound call, whether you place it with
[`POST /v1/call`](/guides/place-outbound-calls) or run a
[campaign](/guides/outbound-campaigns). Others are campaign settings, and
with the API you do the same thing in your own code.

| Lever | Calls through `POST /v1/call` | Campaigns |
|---|---|---|
| 14-second minimum ring | Automatic | Automatic |
| Who answered (`answered_by`) and number health | Yes | Yes |
| Callbacks reach an agent with context | Yes | Yes |
| Caller name and carrier registration | Yes, per number | Yes, per number |
| Voicemail handling | Agent setting | Agent setting |
| Call screener handling | Automatic | Automatic |
| Local area code | You choose the `from_number` | The pool picks one per contact |
| Calls per number per day | You pace your own volume | **Calls per number per day**, with warm-up |
| Contact's local calling hours | You schedule | **Call in each contact's local time** |
| Retries on other days and times | You schedule | **Spread across days and times of day** |
| One quick redial after a ring-out | You redial | **Call twice when there's no answer** |
| A heads-up text | Send with [`POST /v1/sms`](/api-reference/sms) | **Text before calling** |

## Keep each number's daily volume low

Volume per number is the signal you control most directly. Spread your
calls across several numbers instead of pushing them all through one, and
make each of them a number people can trust: caller name set, registered,
and taking callbacks. A large pool of bare numbers reads as evasion.

- [Number health](#watch-each-numbers-health) marks a number **Watch** at
  over 50 calls on its busiest day and **At risk** at over 100, so a
  number used near the campaign default of 75 shows **Watch**.
- Campaigns cap each number at 75 calls in any 24 hours by default
  (**Calls per number per day**, 1–500). The count includes every
  outbound call from that number in your organization, API calls too.
  When every number is at its limit, contacts wait; nothing fails.
- A ThunderPhone number new to outbound calling warms up in campaigns: 20
  calls on its first day, rising to the full limit by day 7.
- No per-number cap applies to API calls. Count calls per
  `from_number` over the last 24 hours and stop well before 100. Don't
  send a whole list from one number in a few minutes.

Size the pool to the list so each number stays under the limit. See
[number pools](/guides/outbound-campaigns#number-pools-and-daily-limits).

## Call from a local number

People answer a familiar area code more often than a distant one.

- **Campaigns** call a new contact from a pool number with the contact's
  area code, else one in the same time zone, else the least used number.
  Retries come from the number that called before.
- **With the API**, keep numbers in the area codes you call most, choose
  the `from_number` that matches the contact, and use the same number
  for every call to that person.

## Show who's calling

Find these on **Phone Numbers**, in the **Caller ID and spam registration**
section. They are free. See
[Caller ID and spam registration](/guides/caller-id-and-spam-registration)
for the steps.

- **Caller name (CNAM).** ThunderPhone numbers show your organization's
  caller name automatically, up to 15 letters, numbers and spaces, once
  your organization has a real name (not the generated "…'s Team"). Numbers
  in your own Twilio or Telnyx account get one when an admin registers
  them. Carriers take 1 to 3 days, and landlines show it more reliably
  than mobile phones. Caller names work on US local numbers only, not
  toll-free.
- **Verified caller ID (STIR/SHAKEN).** Carriers sign each call **A** when
  they know you own the number. Lower attestation gets labeled spam more
  often. Calls from ThunderPhone numbers are signed A. On Twilio,
  registering a number for verified caller ID gets its calls signed A.
  On a manual SIP trunk, ask your carrier for A attestation. Each number's
  health panel shows the attestation to expect.
- **Spam-filter registration.** On Twilio, an admin can have ThunderPhone
  register numbers with the carriers' spam analytics through Twilio Voice
  Integrity; it needs an approved Primary Business Profile. For
  any other number, register it yourself at
  [freecallerregistry.com](https://www.freecallerregistry.com), the free
  registry Hiya, TNS and First Orion share.

## Tell people you're going to call

A person who expects your call is more likely to pick up. A short text a few minutes before
the call, from a number they can see is yours, does that. Only text people
who agreed to it: texts fall under the same consent rules as calls.

- **Campaigns** can text each contact before the first call. Turn on
  **Text before calling**, pick one of your Twilio or Telnyx numbers, and
  set the minutes before the call (1–60, default 2). Retries are never
  texted, and a text that fails never holds up the call. See
  [Text before you call](/guides/outbound-campaigns#text-before-you-call).
- **With the API**, send the text with [`POST /v1/sms`](/api-reference/sms)
  from your Twilio or Telnyx number, then place the call.

ThunderPhone numbers cannot send texts. A US local number needs A2P 10DLC
registration before it can text.

Ask people to save your number. iPhone Call Screening and Silence Unknown
Callers skip numbers in the contact list.

## Call when people pick up

- **Call in the contact's local hours.** Campaigns do it by default: **Call
  in each contact's local time** runs the window by each contact's area
  code. With the API, work out the contact's time zone and schedule the
  call yourself. US marketing calls must fall between 8am and 9pm local
  time; see [outbound calling compliance](/guides/outbound-calling-laws).
- **Retry on another day at another time.** Someone who missed a 10am call
  may be free mid-afternoon. Campaigns spread retries this way by default
  (**Retry timing** → **Spread across days and times of day**). With the
  API, don't redial an unanswered number on a fixed short loop.
- **Redial once, quickly, after a ring-out.** On iPhone, a second call
  from the same number within three minutes rings through Do Not Disturb
  when Allow Repeated Calls is on. Campaigns do this with **Call twice when
  there's no answer**. Never redial more than once, and never after a
  declined call or voicemail.

## Make every call look like a real call

Carriers read short rings and very short calls as robocalls.

- **Let it ring.** Outbound calls ring for at least 14 seconds, whatever
  the agent's **Ring duration**. A call that rings once and drops is what
  one-ring scams do. A shorter setting applies to transfers only, and the
  builder says so.
- **Avoid very short calls.** Number health counts answered calls under
  10 seconds. Have the agent speak first (the default) and open with who
  is calling and why, so the person stays on the line.
- **Leave a voicemail.** People call back numbers that leave a message,
  and callbacks help the number's standing. Under **When voicemail
  answers**, **Let the agent decide** (the default) leaves a short message
  written from your prompt unless the prompt says not to, and **Leave a
  message, then hang up** plays the message you set. **Hang up silently** leaves nothing, and the builder
  warns about it. See [voicemail handling](/guides/agent-settings#voicemail-handling).
- **Get past call screeners.** When iPhone Call Screening or Pixel Call
  Screen answers, the agent states its name and the reason for the call
  in a sentence, then waits for the person. Put your business name and
  the purpose of the call near the top of the prompt so the agent has
  both.

## Take calls back

A number that takes calls back looks like a real business, and a returning
caller is your warmest lead.

When someone calls back a number that called them in the last 30 days,
the answering agent gets a short note on the earlier call: when, which
agent and what happened. If the number has no inbound agent and no
webhook answers, the call goes to the agent that placed the earlier call
instead of ending. This works for API and campaign calls alike.

Give every outbound number an inbound agent or a route you choose.
Caller ID can be faked, so the earlier call's summary and variables are
shared only if an admin turns on **Share the earlier call's details**
under **Organization → General → Callbacks**. See
[callbacks to your outbound calls](/guides/handle-inbound-calls#callbacks-to-your-outbound-calls).

## Watch each number's health

On **Phone Numbers**, each number that placed outbound calls in the
last 30 days shows
**Healthy**, **Watch** or **At risk**. Open **Outbound health** for calls
per day, how often a person answered, voicemail rate, short calls and
short rings over the last day, week and month, with the reasons in plain
English. The status covers the last 7 days, and needs at least 20 calls
before it judges the answer rate and 10 before it judges short calls or
short rings. The same data is at
[`GET /v1/phone-numbers/health`](/api-reference/phone-numbers#outbound-number-health).

| Reason | Watch | At risk |
|---|---|---|
| Calls a day from one number | Over 50 | Over 100 |
| Calls that reach a person | Fewer than 1 in 5 | Fewer than 1 in 10 |
| Answered calls under 10 seconds | Over 30% | Over half |
| Unanswered calls that ring under 12 seconds | Over half | — |

Each outbound call also records who answered as `answered_by`: `human`,
`voicemail`, `screener`, `ivr` or `unknown`. It is on the
[call](/api-reference/calls#call-object), in the completion webhook and
under **Answered by** in call history.

Health reads the same signals carriers use from your own calls. It is a
guide, not any carrier's actual label.

## When a number gets labeled spam

You'll usually see it first as a falling answer rate, a number marked
**At risk**, or people telling you their phone showed "Spam Likely".

1. **Slow down or stop calling from it.** Lower its daily volume, or take
   it out of the campaign pool.
2. **Fix the cause.** Check its health reasons: too many calls a day, too
   many short calls, or too few people answering.
3. **Register it.** Set a caller name and register the number with the
   spam filters as above, or at
   [freecallerregistry.com](https://www.freecallerregistry.com). If the
   label stays, ask the analytics company behind that carrier (Hiya, TNS
   or First Orion) to review the number.
4. **Retire it if the label stays.** Once you've fixed the cause, release
   the number and replace it, and call from the new one at a pace that
   keeps it healthy.

Don't rotate fresh numbers in to hide a labeled one. A pool is for pacing
and local area codes, not for dodging labels. New numbers that call the
same way get labeled the same way.

## Stay within the law

Consent, calling hours and do-not-call rules apply to every outbound call
and text. Read [outbound calling compliance](/guides/outbound-calling-laws)
and talk to your counsel about your calling program.

---

## Next steps

<CardGroup cols={2}>
  <Card title="Outbound campaigns" icon="megaphone" href="/guides/outbound-campaigns">
    Number pools, local calling hours, spread retries and texts.
  </Card>
  <Card title="Place outbound calls (API)" icon="phone-arrow-up-right" href="/guides/place-outbound-calls">
    Call one person at a time from your own code.
  </Card>
  <Card title="Caller ID and spam registration" icon="shield-check" href="/guides/caller-id-and-spam-registration">
    Show your business name and register your numbers.
  </Card>
  <Card title="Outbound calling compliance" icon="scale-balanced" href="/guides/outbound-calling-laws">
    Consent, calling hours and do-not-call rules.
  </Card>
</CardGroup>

<!-- en: guides/monitor-live-calls -->
---
title: "Monitor live calls"
description: "See every call in progress, listen in silently, and whisper guidance the caller never hears."
---

The **Live** page (`/dashboard/live`) under **Engagement** lists every
call currently in progress — who's talking to which agent, in which
direction, and for how long. From there you can join any call as a
silent listener and coach the agent mid-call.

## The live board

Each row shows the **agent**, **direction** (inbound/outbound),
**caller**, **callee**, a ticking **live duration**, and when the call
started. The page refreshes itself every few seconds, and a "live"
counter in the header tracks the total. Calls placed directly through
the API without an agent show as *API / Webhook*.

Click **Listen** on a row to open that call's detail page, where the
live controls appear.

<Note>
  Live supervision works on real calls only — in demo mode the board
  shows simulated calls and the listen/whisper controls are disabled.
</Note>

## Listen in

**Listen in** joins the call as a hidden, listen-only participant:

- Neither the caller nor the agent is affected — nothing on the call
  changes and nobody is notified.
- The recording is unaffected; your listening never appears in it.
- A **LIVE** indicator shows while connected. Click **Leave** to drop
  out; if your connection blips, the session reconnects automatically.
- When the call ends, the session ends with it.

## Whisper to the agent

While listening, a **Whisper to agent…** box appears next to the live
controls. Type a short instruction (up to 500 characters) and press
**Send**:

- The agent receives your text as **private mid-call guidance** and
  incorporates it into the conversation.
- **The caller never hears or sees the whisper** — it changes what the
  agent does next, not the audio on the line.
- You'll see *Whisper sent* on delivery, or *Call ended* if the call
  finished before the whisper arrived.

Whispers are ideal for live corrections — "the discount code is
SPRING24", "offer to escalate", "wrap up, this is a spam call" — without
taking the call over.

<Tip>
  Listen and whisper are also available programmatically via
  `POST /v1/calls/{id}/listen` and `POST /v1/calls/{id}/whisper` — see
  the [calls API reference](/api-reference/calls).
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Review finished calls" icon="waveform-lines" href="/guides/review-calls">
    Transcripts, recordings, and grading in call history.
  </Card>
  <Card title="Set up alerts" icon="bell" href="/guides/alerts">
    Get notified when success rates dip — before you need to listen in.
  </Card>
</CardGroup>

<!-- en: guides/embed-a-web-widget-dashboard -->
---
title: "Create a web widget in the dashboard"
description: "Set up a click-to-talk widget for your site from the Web Widgets page — no API calls required."
---

The **Web Widgets** page (`/dashboard/web-widgets`) creates and manages
the publishable keys that power ThunderPhone's embeddable voice widget.
Everything the [API version of this guide](/guides/embed-web-widget)
does with cURL, this page does with a form — plus it generates the embed
code for you.

## Create a widget

<Steps>
  <Step title="Click New widget and pick a mode">
    - **Agent mode** — the widget always runs one agent you pick from
      the dropdown. The simplest setup.
    - **Webhook mode** — on every widget session, ThunderPhone calls
      your webhook URL and your server returns the agent configuration
      for that visitor (per-page routing, logged-in users, rollouts).
      Leave the URL blank to use your organization's default webhook;
      when you enter a new URL you can also set it as the org default.
  </Step>
  <Step title="List the allowed domains">
    At least one domain is required, and browsers can only start
    sessions from the hostnames you list. Subdomain wildcards like
    `*.example.com` are allowed (they match subdomains, not the bare
    domain); bare wildcards like `*` are rejected. The list stops casual
    reuse of your key on other sites but is not authentication: a script
    outside a browser can send any `Origin` header. `localhost` is not
    allowed automatically in production; add it to the list to test
    locally against the production API.
  </Step>
  <Step title="Choose the browser overrides">
    Tick each session setting your page sends: **Page context**,
    **Variables**, **Voice**, **Language**. New widgets accept none, and
    a session request carrying a setting that is off fails with `400`.
    Your key is public, so allow only what you use. See
    [Browser overrides](/guides/embed-web-widget#browser-overrides).
  </Step>
  <Step title="Name it, enable it, create it">
    The **Enable widget** toggle controls whether the key accepts
    sessions — you can create a widget disabled and flip it on at launch.
  </Step>
</Steps>

## Grab the embed code

Right after creation (or via each row's **Embed** button), an embed
dialog generates ready-to-paste code with your publishable key filled
in:

- **React** — a `<ThunderPhoneWidget />` snippet for bundler apps.
- **Script tag** — a CDN `<script>` + stylesheet pair for any site.

The dialog also previews basic appearance options — title, primary
color, corner position, and light/dark theme — and bakes your choices
into the snippet. For the full prop reference, styling hooks, and the
headless option, see the [widget SDK docs](/widget/overview).

<Note>
  Publishable keys (`pk_live_…`) are public by design — safe to ship in
  front-end code. Copy one anytime with the copy button on its row.
</Note>

## Manage widgets from the list

Each row edits in place:

- **Mode / Agent** — switch between agent and webhook mode, or repoint
  the agent, with inline selects.
- **Domains** — add or remove allowed domains as chips.
- **Enable/disable** — a switch per widget; disabled widgets stop
  accepting sessions immediately.
- **Transfer to org** — copy or move the widget to another organization
  you belong to (moving removes it here).
- **Delete** — revokes the publishable key; the widget stops working
  immediately on all domains. This can't be undone.

Widget sessions appear in [call history](/guides/review-calls) with the
same transcript, recording, and grading as phone calls.

## Next steps

<CardGroup cols={2}>
  <Card title="Widget SDK reference" icon="window-maximize" href="/widget/overview">
    React component, headless hook, and CDN script details.
  </Card>
  <Card title="Webhook-mode routing" icon="bolt" href="/guides/dynamic-call-config">
    Return per-visitor agent config from your server.
  </Card>
</CardGroup>

<!-- en: guides/client-portals -->
---
title: "Client portals: branded read-only call reporting"
description: "Create a ThunderPhone client portal, choose visible agents, add viewers, brand the experience, connect a custom domain, and share read-only call history."
---

**Client portals** give each client a branded, read-only view of calls handled
for them. A portal can include selected agents, its own viewers, a logo and
accent color, and an optional custom domain.

Organization admins manage portals at **Client portals**
(`/dashboard/client-portals`). Viewers use the hosted portal URL and never gain
access to the ThunderPhone dashboard.

## Create a portal

<Steps>
  <Step title="Choose New portal">
    Enter the client-facing name. ThunderPhone creates a unique URL slug from
    it; you can edit the slug later.
  </Step>
  <Step title="Assign agents">
    Add the agents whose calls the client should see. A portal with no assigned
    agents has no visible calls.
  </Step>
  <Step title="Add viewers">
    Add each approved viewer's email address. Viewers request their own login
    code from the portal sign-in page.
  </Step>
  <Step title="Share the URL">
    Copy the portal URL or choose **Open** to test it. The list page also shows
    each portal's active status, agent count, and viewer count.
  </Step>
</Steps>

## Portal details and availability

The **Portal details** card controls:

- **Name** — displayed on the portal login and header; maximum 255 characters.
- **Slug** — the hosted URL segment; maximum 100 characters. Use lowercase
  letters, numbers, and single hyphens. Slugs must be unique and cannot use a
  reserved platform route.
- **Agents** — the exact set of agent call histories visible in the portal.
- **Portal active** — turn this off to prevent every viewer from opening it
  without deleting configuration.

Only calls belonging to an assigned agent are in scope. Viewers cannot edit
agents, place calls, manage billing, or see other organization data.

## Branding

Upload a **PNG**, **JPEG**, or **WebP** logo up to **2 MB**. Choose a full
six-digit hexadecimal accent color such as `#2e8fff`; it controls the primary
buttons and highlights. Reset either value to return to the default branding.

Branding appears on both the sign-in page and authenticated portal header.

## Viewer access

Add viewers by email. On the portal login page, an active viewer can:

- Request a six-digit code by email. A code is valid for 10 minutes.
- Sign in with a password if they have created one.
- Create a password of at least 8 characters after signing in.

You can deactivate a viewer without removing their row, or delete them to
remove access. Portal sessions are separate from dashboard sessions.

## What viewers can see

The portal has two sections: **Overview** and **Calls**.

**Overview** shows five numbers for the last 7, 14 or 30 days. Comparison
indicators show changes from the previous period of the same length. An
indicator is omitted when the previous value was zero and the current value
is positive. Colour shows whether a change is good or bad, not which way it
points:

1. **Calls answered**: inbound and web calls that reached the agent, plus
   outbound calls the other side answered, and how many started after
   hours.
2. **Start to finish**: calls that left nothing for the client to do.
3. **Didn't go well**: calls where the caller hung up mid-conversation or
   after the agent asked for information, the agent struggled to capture
   details, a booking failed, or a transfer did not connect. The most
   common cause is shown. Hanging up at the greeting alone does not count.
4. **Frustrated callers**: callers who showed frustration, with the most
   common cause. Fewer is better.
5. **Appointments set**, and how many were with new clients.

Below the numbers, Overview lists up to eight calls that need a follow-up;
**View all flagged calls** opens the filtered Calls list. When more than
one agent has answered calls in the selected period, a table shows calls,
after-hours calls,
start-to-finish calls, calls that did not go well, appointments and flagged
calls for each agent. The five headline numbers also appear on the dashboard
Home page and in each agent's **Calls** tab.

**Calls** lists inbound, outbound and widget calls for the assigned
agents; browser tests and simulations are left out. Each row shows the
date, the **From** number with any
[label](/guides/review-calls#label-a-phone-number) your organization gave
it, the one-line summary, the outcome label (the agent's own list, or
Success / Failure), any **Needs attention** flag and reason, the agent and
the duration. Flagged calls sort to the top; the **Sort** filter
switches to newest first. Filters also cover date range, call type, needs
attention and business hours. **Export CSV** downloads up to 5,000
matching calls with the report columns, flagged calls first. If more than
5,000 calls match, the file is truncated.

Opening a call shows the flag, outcome, summary and caller experience
above the recording. For a frustrated caller, caller experience shows the
frustration cause; otherwise the caller-experience note appears when
available. When the flag has a recorded time and the call has a
recording, **Jump to …** starts playback at that moment. The transcript
follows.

Calls from or to the organization's excluded test numbers are left out of
portal lists, Overview numbers and CSV exports, and cannot be opened in the
portal. After-hours counts use the organization's time zone and business
hours ([Organization settings](/guides/organization-settings#reporting)),
or an agent's own when set under **Reporting** in the agent builder.

The interface is read-only. It does not expose agent prompts, organization
settings, keys, billing, tools, or internal issue workflows.

## Connect a custom domain

<Steps>
  <Step title="Add the hostname">
    Under **Custom domains**, enter a full hostname such as
    `calls.client.com`. A hostname can belong to only one portal.
  </Step>
  <Step title="Point traffic to the portal">
    Add the displayed **CNAME** record at the DNS provider.
  </Step>
  <Step title="Prove domain ownership">
    Add the displayed **TXT** record at
    `_tp-portal-verify.<hostname>` with the generated verification value.
  </Step>
  <Step title="Allow Azure hostname validation">
    Add the displayed **TXT** record at `asuid.<hostname>` with the Azure
    verification value. Keep it in place while the hostname is connected.
  </Step>
  <Step title="Verify">
    Choose **Verify now**. DNS can take time to propagate; the setup screen can
    check again every 20 seconds. After verification succeeds, the TXT record
    can be removed while the CNAME must remain.
  </Step>
</Steps>

Remove a domain from the portal before reusing that hostname elsewhere.

## Delete a portal

Deleting a portal permanently removes its viewer access and custom-domain
configuration. It does not delete the organization's agents or calls, but the
portal cannot be recovered. Use the **Portal active** switch for a reversible
pause.

For admin automation, see the
[Client Portals API](/api-reference/client-portals).

<!-- en: guides/connect-apps -->
---
title: "Connect apps (Google, Slack, HubSpot & more)"
description: "Give your agents real abilities in a few clicks and no code — check calendars, update your CRM, post to Slack — through prebuilt connections to the apps you use."
---

App connections let a voice agent act inside the tools your team already
uses, mid-conversation: check availability on a calendar, look up a caller
in your CRM, append a lead to a spreadsheet, post a summary to Slack. You
connect an account once under **Connections → Apps**
(`/dashboard/app-connections`), choose what the agent is allowed to do, and
attach the connection to any agent in its builder.

Six applications are available today:

| Application | What your agent can do with it |
| --- | --- |
| **Google Calendar** | View availability and manage calendar events. |
| **Google Sheets** | Append lead details and call outcomes to a sheet. |
| **Slack** | Find channels, search messages, and post with permission. |
| **HubSpot** | Find contacts, update records, and add notes. |
| **Salesforce** | Search records, update leads, and log activity. |
| **Cal.com** | Check availability and manage bookings. |

For anything not on this list, build a custom
[API connection](/guides/api-connections) or add an
[MCP server](/guides/mcp-servers).

## Connect an account

<Steps>
  <Step title="Open Connections → Apps and click Add application">
    A picker shows the six applications. You can connect multiple accounts
    of the same app — each shows a "connected" count once you have one.
  </Step>
  <Step title="Authorize the account">
    Most apps use OAuth: a popup opens, you sign in to the provider and
    approve access, and the connection appears on the page. **Cal.com is
    the exception** — it connects with an API key instead. Paste the key
    and click **Validate and connect**; the key is checked against Cal.com
    before it is encrypted and saved.
  </Step>
  <Step title="Google Sheets only: pick the spreadsheet">
    A Sheets connection needs to know which spreadsheet and tab to write
    to. Right after connecting, a configuration panel opens — paste the
    spreadsheet's URL (or its ID), click **Inspect spreadsheet**, and
    choose the tab. The panel confirms the columns it found. Until this is
    done the connection tile shows **Needs configuration**.
  </Step>
</Steps>

Connecting and managing app connections requires an **admin** or **owner**
role in the organization.

## Control what the agent may do

Every connection has per-operation permission toggles — open a connection
tile to manage them. Read-style operations start enabled; operations that
write to or change your data start **off** until you enable them:

| Application | Enabled by default | Off by default |
| --- | --- | --- |
| Google Calendar | View events & availability, Create events | Update events, Cancel events |
| Google Sheets | Add rows | — |
| Slack | View channels & recent messages, Search messages | Post messages |
| HubSpot | Search & read contacts and companies | Create or update contacts and add notes |
| Salesforce | Search & read leads, contacts, and opportunities | Create or update records and log activity |
| Cal.com | List event types & check availability, Create bookings | Reschedule or cancel bookings |

An operation you disable is simply not available to the agent — the
corresponding tools are never offered to it on calls.

Google Calendar connections also carry an **Email invitations to guests**
switch, on by default. When the agent collects the caller's email address
and passes it as a guest on the event, Google emails them the invitation,
and any later update or cancellation the agent makes. Turn it off to keep
guests on the event without email. The invitation includes the event
description, so have the agent keep internal notes out of it and read the
address back to the caller before booking.

## The tools your agent gets

Once a connection is attached to an agent, the enabled operations surface
as callable tools during conversations:

- **Google Calendar** — `calendar_list_events`, `calendar_check_availability`,
  `calendar_create_event`, `calendar_update_event`, `calendar_cancel_event`
- **Google Sheets** — `sheets_append_row` (writes to the spreadsheet and tab
  you configured)
- **Slack** — `slack_list_channels`, `slack_search_messages`,
  `slack_post_message`
- **HubSpot** — `hubspot_search_contacts`, `hubspot_get_contact`,
  `hubspot_upsert_contact`, `hubspot_add_note`
- **Salesforce** — `salesforce_search_records`, `salesforce_get_record`,
  `salesforce_upsert_lead`, `salesforce_log_activity`
- **Cal.com** — `calcom_list_event_types`, `calcom_check_availability`,
  `calcom_create_booking`, `calcom_find_bookings`,
  `calcom_reschedule_booking`, `calcom_cancel_booking`. To reschedule or
  cancel, the agent first finds the caller's upcoming booking by the email
  address and full name it was made under. With **Reschedule or cancel
  bookings** on, a caller who gives both can move or cancel that booking, the
  way a front desk would on the phone. A booking with other guests can't be
  changed on a call, since the change would apply to everyone on it.

You don't write schemas for any of these — ThunderPhone defines the tools
and routes the calls through the connected account.

## Attach the connection to an agent

Connections do nothing until an agent uses them. Open the agent in the
builder ([Build an agent](/guides/build-an-agent)) and add the connection
in its **Connected apps** section. A connection's tile on the Apps page
shows how many operations are enabled and how many agents use it.

## Disconnect

Open a connection tile and disconnect it from there. Agents that were
using it lose those tools on their next call.

## Next steps

<CardGroup cols={2}>
  <Card title="Turn any API into an agent action" icon="plug" href="/guides/api-connections">
    The paste-a-cURL wizard for services without a native connection.
  </Card>
  <Card title="Add an MCP server" icon="server" href="/guides/mcp-servers">
    Bring your own tool server over Streamable HTTP.
  </Card>
</CardGroup>

<!-- en: guides/api-connections -->
---
title: "API connections"
description: "Turn any HTTP API into a function your agent can call mid-conversation: paste a cURL command and the wizard builds the tool definition, parameters, and auth."
---

API connections are custom HTTP functions your agents can call during a
conversation — look up an order, create a ticket, fetch account status
from your own backend. You define the endpoint once under
**Connections → APIs** (`/dashboard/api-connections`); agents that have
the connection attached can then invoke it whenever the conversation
calls for it.

There are two ways to build one: paste something the wizard can analyze,
or set the connection up manually.

## The fast path: paste and analyze

<Steps>
  <Step title="Click New API connection">
    The dialog opens on the wizard. Paste a sample **cURL command**,
    **OpenAPI/Swagger spec**, **Postman export**, **TypeScript
    interface**, or **Zod schema** into the box.
  </Step>
  <Step title="Click Analyze">
    ThunderPhone infers the whole connection from your paste — URL,
    method, headers, and a parameter schema derived from the query
    parameters and request body it found. Headers you pasted (including
    auth headers) are carried into the endpoint configuration.
  </Step>
  <Step title="Confirm the highlighted fields">
    The inferred configuration opens with the guessed fields highlighted
    for review. Adjust names, descriptions, and parameter types so the
    agent understands when and how to call the function — the description
    is what the model reads.
  </Step>
  <Step title="Validate & Save">
    Saving runs a live test request against your endpoint first. If the
    request fails, the connection isn't saved — fix the URL, auth
    headers, or body and try again. On success the connection is stored
    with a **Validated** badge.
  </Step>
</Steps>

If the wizard can't find a request URL in your paste, it will say so —
include a full `http(s)` endpoint and try again.

## Manual setup

Click **Set up manually →** in the wizard (or **Want AI to infer this?
Try the Wizard →** to go back). The manual builder has two editors:

- **Visual** — form fields for the display name, function name, request
  **URL**, **method** (`POST`, `GET`, `PUT`, `PATCH`, `DELETE`), custom
  **headers**, and the parameter schema (**Add property** for each
  argument the agent can supply).
- **JSON** — the same definition as raw JSON, for pasting or fine-tuning
  a tool spec directly.

A **Test Request** panel (optional) lets you fire the configured request
before saving and shows the status, latency, and a response preview.
**Validate & Save** always runs this test and only saves on success.

The panel also shows how big the response is, in characters and
approximate tokens. Your agent re-reads a tool result on every turn of the
call, so a response over 20,000 characters gets a warning with ways to
slim it down, and one over 100,000 characters is flagged because the agent
only sees its start. See
[Tool returns too much data](/guides/build-tool-integration#common-gotchas).

Header values are write-only. Once saved they are encrypted and never shown
again, in the dashboard or the API. When you edit a connection, a saved
header shows its name with dots in place of the value and a **Saved** note:
leave it as is to keep the saved value, or type a new one to replace it. Test
requests and live calls use the saved value. **Clone** copies saved values
to the new connection.

<Tip>
  Give parameters plain-language descriptions ("Customer email address,
  e.g. jane@example.com"). The agent chooses arguments from these
  descriptions in real time, mid-call.
</Tip>

## Manage your connections

Each connection row shows its validation status — **Validated**,
**Untested**, or **Error** — its function name, and which agents use it.
From the row's action menu you can:

- **Edit** — reopen the configuration.
- **Clone** — duplicate it as a starting point (the copy starts
  Untested).
- **Revision history** — view earlier versions and restore one into the
  editor.
- **Transfer** — copy or move the connection to another organization you
  belong to. Moving removes it here; agents that used it may need
  reconfiguration.
- **Delete** — permanent; agents using the connection will need to be
  reconfigured.

## Attach it to an agent

Add the connection to an agent in the builder's API connections section
([Build an agent](/guides/build-an-agent)). The list shows which agents
use each connection, so you can tell at a glance what a change affects.

Function names only need to be unique on an agent. Two connections may
share one, such as a `save_information` for each of two agents that save to
different places, but one agent can't have both: saving the agent with
two tools of the same name is refused, and so is renaming a connection to
a name another tool on one of its agents already uses.

## Next steps

<CardGroup cols={2}>
  <Card title="Tool integrations via API" icon="code" href="/guides/build-tool-integration">
    Create and manage the same connections programmatically.
  </Card>
  <Card title="Connect apps" icon="cable" href="/guides/connect-apps">
    Prebuilt Google, Slack, HubSpot, Salesforce, and Cal.com connections.
  </Card>
  <Card title="Add an MCP server" icon="server" href="/guides/mcp-servers">
    Expose a whole tool server to your agents.
  </Card>
  <Card title="Integrations API reference" icon="book" href="/api-reference/integrations">
    Every field on the integration resource.
  </Card>
</CardGroup>

<!-- en: guides/mcp-servers -->
---
title: "MCP servers"
description: "Connect a remote MCP server and every tool it exposes becomes available to your agents mid-conversation, without defining each tool by hand."
---

If you already run a tool server that speaks the
[Model Context Protocol](https://modelcontextprotocol.io), you can plug it
into ThunderPhone directly. Add the server once under
**Connections → MCP** (`/dashboard/mcp-connections`); its tools are
discovered automatically and can be attached to any agent.

ThunderPhone connects to MCP servers over **Streamable HTTP** — that is
the only supported transport, so the server must be reachable at an HTTP
URL (stdio-only local servers won't work).

## Add a server

<Steps>
  <Step title="Click Add server">
    Give the server a **name** and its **URL** (for example
    `https://example.com/mcp`).
  </Step>
  <Step title="Add headers if the server needs them">
    Add any static HTTP headers the server requires — typically an
    `Authorization` header. Header values are write-only and encrypted at
    rest: when you edit the server later, leave a value blank to keep the
    existing one.
  </Step>
  <Step title="Save and sync">
    Saving immediately synchronizes the server's tool list. The server
    card shows every discovered tool by name; if none appear, the server
    responded but advertised no tools.
  </Step>
</Steps>

## Manage servers

Each server card shows its URL and cached tool list, with controls to:

- **Enable/disable** the server without deleting it.
- **Sync tools** — re-fetch the tool list after the server changes.
- **Edit** the name, URL, or headers.
- **Delete** the server.

<Note>
  Tool lists are cached from the last sync. If you add or change tools on
  your server, click **Sync tools** so agents see the new set.
</Note>

## Attach it to an agent

A connected server does nothing until an agent uses it. Open the agent in
the builder ([Build an agent](/guides/build-an-agent)) and attach the
server in its MCP section — the server's tools then become callable
during that agent's conversations.

## Next steps

<CardGroup cols={2}>
  <Card title="Use ThunderPhone as an MCP server" icon="server" href="/guides/thunderphone-mcp-server">
    Let an external AI client list agents, place calls, and inspect call results.
  </Card>
  <Card title="API connections" icon="plug" href="/guides/api-connections">
    A single HTTP endpoint as an agent function — no MCP server needed.
  </Card>
  <Card title="Connect apps" icon="cable" href="/guides/connect-apps">
    Prebuilt Google, Slack, HubSpot, Salesforce, and Cal.com tools.
  </Card>
</CardGroup>

<!-- en: guides/docs-mcp -->
---
title: "Connect your coding agent to ThunderPhone docs"
description: "Add ThunderPhone's read-only documentation MCP server to Claude Code, Codex, Cursor, or another Streamable HTTP MCP client."
---

ThunderPhone exposes a public, read-only documentation MCP server at:

```text
https://thunderphone.com/docs/mcp
```

It needs no API key. Use it when a coding agent needs current ThunderPhone
product and API context without loading the entire documentation set into its
prompt.

## Add it to Claude Code

```bash
claude mcp add --transport http thunderphone-docs https://thunderphone.com/docs/mcp
```

## Add it to Codex

Add this to `~/.codex/config.toml`, or to `.codex/config.toml` in a trusted
project when the server should only be available there:

```toml
[mcp_servers.thunderphone-docs]
url = "https://thunderphone.com/docs/mcp"
```

## Add it to Cursor

Add this server to `.cursor/mcp.json` in a project, or use the equivalent
global MCP settings:

```json
{
  "mcpServers": {
    "thunderphone-docs": {
      "url": "https://thunderphone.com/docs/mcp"
    }
  }
}
```

## Available tools

| Tool | Arguments | What it returns |
| --- | --- | --- |
| `list_pages` | none | Every English documentation page with its title, Markdown URL, and description. |
| `search_docs` | `query` | Up to 10 ranked matches with descriptions and text snippets. |
| `get_page` | `path` | The raw Markdown/MDX source for one English documentation page. |

All three tools are marked read-only. The server is stateless and contains no
customer or organization data.

<Note>
  This server reads the documentation. To let an MCP client inspect your
  organization's agents and calls, read transcripts, or place outbound calls,
  use the authenticated [ThunderPhone API MCP server](/guides/thunderphone-mcp-server).
</Note>

## Test the connection

Ask your client:

```text
Search the ThunderPhone docs for webhook signature verification, then show me
the relevant page and a minimal implementation checklist.
```

You can also inspect the tool list over JSON-RPC:

```bash
curl -X POST https://thunderphone.com/docs/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

<!-- en: guides/thunderphone-mcp-server -->
---
title: "Use ThunderPhone as an MCP server"
description: "Build, test, validate, and operate ThunderPhone voice agents from Claude, ChatGPT, Claude Code, Codex, Cursor, VS Code, or another Streamable HTTP MCP client."
---

ThunderPhone exposes a Streamable HTTP Model Context Protocol server at:

```text
https://api.thunderphone.com/v1/mcp
```

This is the opposite direction from [connecting a remote MCP server to a voice agent](/guides/mcp-servers):

| Direction | Result |
| --- | --- |
| Remote MCP server → ThunderPhone agent | A voice agent can call the remote server's tools. |
| ThunderPhone → your MCP client | Your coding agent can build, test, and operate ThunderPhone. |

## Authenticate

Use [OAuth](/guides/oauth) by default for directory clients: sign in, choose an organization, and approve the requested permissions. Revoke access under **Organization → API keys → Authorized apps**. Changing or resetting your password, or changing your account email, also revokes the connection, so reconnect the client afterwards.

For clients configured with an API key, create an `sk_live_` key under **Organization → Keys** and expose it to your MCP client as `THUNDERPHONE_API_KEY`. The key is bound to one organization; an id owned by another organization behaves as not found.

<Warning>
  An `sk_live_` key can read organization data and perform production actions such as deploying agents, placing calls, buying numbers, starting campaigns, and deleting resources. Keep it out of browser code, repositories, screenshots, and chat logs. Use your client's secret store or environment support and revoke an exposed key immediately.
</Warning>

## Organizations that handle PHI

If your organization's calls may contain protected health information (PHI),
because you have a BAA with ThunderPhone or your agents are designated as
processing PHI, the URL above never returns call content: transcripts,
recordings, grades, call lists, exports, campaign outcomes, call analytics and
insights, conversations built from real calls and replay results. Those tools return an error with
`code: "phi_content_unavailable"`. Building, testing and configuring agents
works as usual.

That URL is the one listed in public assistant directories, which may not
carry PHI. If your organization has its own BAA with an assistant's provider
covering the workspace you use:

1. An organization admin opens **Organization → General → AI assistant access**
   in ThunderPhone and confirms that coverage.
2. Connect the assistant as a custom connector with this URL instead:

```text
https://api.thunderphone.com/v1/mcp/baa
```

Call content is then available there, including calls that may contain PHI.
Withdrawing the confirmation stops it on the assistant's next request. A call
your organization handled as not containing PHI is available at either URL.

## CLI and stdio alternatives

The [ThunderPhone CLI](/guides/cli) can write client configuration while preserving
unrelated servers:

```bash
npx -y @thunderphone/mcp setup --client cursor --api-key-env THUNDERPHONE_API_KEY
npx thunderphone mcp setup --client claude-desktop --scope user
```

After a global install of `@thunderphone/mcp`, use `thunderphone-mcp setup` with the
same options. Setup supports Claude Code, Codex, Cursor, VS Code, Gemini, Claude
Desktop and Windsurf. Direct HTTP is preferred; Desktop uses stdio.

For any stdio-capable client, configure `command: "npx"` with
`args: ["-y", "@thunderphone/mcp"]`. The wrapper uses `THUNDERPHONE_API_KEY` first,
then credentials from `thunderphone login`, refreshing expired tokens, then
OAuth through `mcp-remote`. Device login and OAuth require the corresponding API
OAuth rollout. The API-key path does not. Direct HTTP configurations do not read
the CLI credential store; use the stdio wrapper to reuse device login.

These are alternatives to the manual client configurations below.

## Client configuration

Claude and ChatGPT sign in with [OAuth](/guides/oauth); no API key is involved. If you do not have a ThunderPhone account yet, choose **Create account** on the sign-in page and you return to the approval screen after verifying your email.

### Claude (web, desktop, and mobile)

1. Open **Customize → Connectors** (**Settings → Connectors** in older versions). If ThunderPhone appears in the connector directory, select it. Otherwise choose **Add custom connector**, name it `ThunderPhone`, and enter `https://api.thunderphone.com/v1/mcp`.
2. Select **Connect**, sign in to ThunderPhone, pick the organization, and approve the permissions.
3. In a chat, enable ThunderPhone from the tools menu and ask for what you need, for example "List my agents".

Claude asks before it uses each tool for the first time. To skip most of those prompts, open **Customize → Connectors → ThunderPhone** and set **Read-only tools** to always allow. Those tools only look things up: agents, calls, transcripts, balances, docs. Leave **Write/delete tools** on approval if you want to see each change before it happens.

Custom connectors need a paid Claude plan. On Team and Enterprise plans an owner adds the connector under the organization's connector settings first, then each member connects their own ThunderPhone account.

### ChatGPT

1. If ThunderPhone appears in the ChatGPT app directory, select it and connect.
2. Otherwise open **Settings → Apps & Connectors → Advanced settings**, turn on **Developer mode**, and create a connector with the URL `https://api.thunderphone.com/v1/mcp` and OAuth authentication.
3. Sign in to ThunderPhone, pick the organization, and approve the permissions. Add ThunderPhone to a chat from the tools menu.

Deleting an agent or phone number, discarding a draft, launching a campaign, and sending a test request that can write to an external system ask for a second confirmation in either app; see [Confirming destructive actions](#confirming-destructive-actions).

### Claude Code

```bash
claude mcp add --transport http thunderphone https://api.thunderphone.com/v1/mcp \
  --header "Authorization: Bearer $THUNDERPHONE_API_KEY"
```

### Codex

Add this to `~/.codex/config.toml`:

```toml
[mcp_servers.thunderphone]
url = "https://api.thunderphone.com/v1/mcp"
bearer_token_env_var = "THUNDERPHONE_API_KEY"
```

### Cursor

Create `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "thunderphone": {
      "url": "https://api.thunderphone.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:THUNDERPHONE_API_KEY}"
      }
    }
  }
}
```

### Claude Desktop

Add an `mcp-remote` bridge to the Claude Desktop configuration:

```json
{
  "mcpServers": {
    "thunderphone": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.thunderphone.com/v1/mcp",
        "--header",
        "Authorization: Bearer ${THUNDERPHONE_API_KEY}"
      ],
      "env": {
        "THUNDERPHONE_API_KEY": "sk_live_YOUR_API_KEY"
      }
    }
  }
}
```

### VS Code

Create `.vscode/mcp.json` and enter the key through VS Code's input prompt:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "thunderphone-api-key",
      "description": "ThunderPhone organization API key",
      "password": true
    }
  ],
  "servers": {
    "thunderphone": {
      "type": "http",
      "url": "https://api.thunderphone.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${input:thunderphone-api-key}"
      }
    }
  }
}
```

## Tools

Every tool carries MCP annotations. In the tables, **R** means read-only, **D** destructive, **I** idempotent, and **O** open-world/network interaction. A dash means no hint is set.

### Connection

| Tool | Main arguments | Annotations | What it does |
| --- | --- | --- | --- |
| `get_connection_identity` | — | R, I | Validates the credential and returns its organization and safe credential metadata. |

### Agents

| Tool | Main arguments | Annotations | What it does |
| --- | --- | --- | --- |
| `list_agents` | — | R, I | Lists agents. |
| `get_agent` | `agent_id` | R, I | Gets one agent. |
| `create_agent` | agent configuration | — | Creates an agent. Takes the same settings as `update_agent`, including `steps`, `handoffs`, `intro_clip` and `intro_ring_count`. |
| `update_agent` | `agent_id`, changed fields, optional `prompt_edits`, `expected_prompt_sha256` | D | Stages fields in the agent draft, replacing what the draft had. Runs without a confirmation step: the deployed agent is unchanged until `deploy_agent`, and `discard_agent_draft` reverts the draft. You can also set `max_hold_seconds`, `system_tool_settings`, and `words`. To change part of the prompt, send `prompt_edits` (see [Editing a prompt in place](#editing-a-prompt-in-place)). |
| `deploy_agent` | `agent_id`, optional `if_updated_at` | D, I | Promotes the draft to production. |
| `discard_agent_draft` | `agent_id`, optional `if_updated_at`, `confirmation_token` on the second request | D, I | Discards staged changes. Two-step, see [Confirming destructive actions](#confirming-destructive-actions). |
| `duplicate_agent` | `agent_id`, optional `name` | — | Copies an agent inside the organization. |
| `delete_agent` | `agent_id`, `confirmation_token` on the second request | D, I | Permanently deletes an agent. Two-step. |
| `list_agent_versions` | `agent_id` | R, I | Lists deployed configuration versions. |
| `list_prompt_revisions` | `agent_id`, optional `source`, `limit`, `offset` | R, I | Lists every change to the agent's prompt text, drafts included, each with a diff against the revision it replaced. Needs the agent iteration toolkit (see below). |
| `review_prompt` | `agent_id`, optional `prompt`, `previous_prompt`, `quote_id`, `max_cost_cents` | — | Reviews the draft prompt (or the text you send) against the [prompt style guide](#resources). Each finding quotes the passage, names the guideline and offers a find and replace edit; the result also lists the behaviors the prompt asks for, with stable ids, whether a refactor is due and, for the agent's own prompt, whether its test conversations need a refresh. Changes nothing on the agent; the inventory is saved with its prompt revision. Paid, so it is not marked read-only: quote it with `dry_run`, then run it once with the `quote_id` it returns and `max_cost_cents`. Needs the agent iteration toolkit (see below). |
| `refactor_prompt` | `agent_id`, optional `prompt`, `inventory`, `instructions`, `quote_id`, `max_cost_cents` | — | Rewrites the prompt into the style guide's shape and maps every behavior as kept, merged, reworded or dropped. Returns the new text and a diff, and by default re-reads it to report `behavior_changes` (added, removed or changed) and `behavior_preserved`; apply it with `update_agent`. Paid: quote it with `dry_run`, then run it once with the `quote_id` it returns and `max_cost_cents`. Needs the agent iteration toolkit (see below). |
| `list_reusable_instructions` | — | R, I | Lists reusable instructions: shared prompt rules attached to many agents with `update_agent`'s `reusable_instruction_ids`. |
| `create_reusable_instruction` | `name`, `content` | — | Creates an unattached reusable instruction. Admins only. |

### Phone numbers and carriers

| Tool | Main arguments | Annotations | What it does |
| --- | --- | --- | --- |
| `list_phone_numbers` | — | R, I | Lists organization numbers and routing. |
| `get_phone_number_limits` | — | R, I | Gets managed-number usage and limits. |
| `provision_phone_number` | optional `area_code`, `city`, `state`, `idempotency_key` | D, O | Buys a ThunderPhone-managed inbound number. |
| `list_voip_connections` | — | R, I | Lists connected customer carriers. |
| `search_voip_numbers` | `connection_id`, `country`, `type`, optional `area_code` | R, I, O | Searches carrier inventory. |
| `import_voip_numbers` | `connection_id`, `numbers` | D, O | Imports numbers already owned at the carrier. |
| `update_phone_number` | `phone_number_id`, routing/label/webhook fields | D | Updates number routing, including agent assignment. |
| `delete_phone_number` | `phone_number_id`, `confirm`, optional `release_at_provider`, `confirmation_token` on the second request | D, I, O | Releases a number. Two-step. |
| `get_voip_setup_session` | optional `session_id` | R, I | Reads a guided carrier setup (status, checklist, the question it is waiting on), or lists open setups. A setup starts in the dashboard because it needs the carrier password. Admins only. |
| `answer_voip_setup_question` | `session_id`, `question_id`, `answer` | O | Passes the user's answer to the setup. Passwords, test-call consent, the server address, the username and letting ThunderPhone sign in to the provider account are answered in the setup wizard only; for those it returns the wizard link and sends nothing. |
| `save_voip_setup` | `session_id`, optional `name`, `confirmation_token` on the second request | D, I, O | Saves a connected draft connection so it can be used. Two-step. |
| `check_phone_number` | `phone_number` or `phone_number_id` | R, I, O | Diagnoses one of the organization's own numbers from evidence: routing, connection, verification, recent carrier and test calls, and where the carrier sends it. |

### SMS

| Tool | Main arguments | Annotations | What it does |
| --- | --- | --- | --- |
| `send_sms` | `from_number`, `to`, `body`, `idempotency_key` | D, I, O | Sends one plain-text SMS through a connected Twilio or Telnyx number. |

### Calls

| Tool | Main arguments | Annotations | What it does |
| --- | --- | --- | --- |
| `list_calls` | optional filters, `limit`, `offset` | R, I | Lists calls with the REST call-history filters, including `exclude_test_calls`. |
| `get_call` | `call_id` | R, I | Gets call status and metadata. |
| `get_call_transcript` | `call_id`, optional `live` | R, I | Gets the call transcript. |
| `get_call_audio_url` | `call_id`, optional `download` | R, I, O | Returns a signed audio URL; it never streams audio through MCP. |
| `get_call_grade` | `call_id` | R, I | Gets the latest call grade. |
| `place_call` | `agent_id`, `from_number`, `to_number` | D, O | Places one non-idempotent outbound call. |
| `export_calls` | call filters, `export_format` | R, I | Exports up to the REST endpoint's cap as JSON or CSV. |
| `get_call_analytics` | optional `since_days`, `agent_id` | R, I | Aggregates real calls by status, direction, outcome, grade and issue, with test calls counted apart. |
| `get_call_insights` | `call_ids` (up to 10) | R, I | Gets the grade, outcome, summary and detected issues of several calls at once. |

### Testing and validation

| Tool | Main arguments | Annotations | What it does |
| --- | --- | --- | --- |
| `list_test_scenarios` | `agent_id` | R, I | Lists test scenarios. |
| `create_test_scenario` | `agent_id`, `title`, `scenario_prompt`, optional conditions | — | Creates a scenario. |
| `generate_test_scenarios` | `agent_id`, optional `count`, `include_edge_cases`, `locale` | O | Generates scenarios from the agent prompt. |
| `run_agent_tests` | `agent_id`, `channel`, `consent_to_charge`, optional selection/matrix | D, O | Executes scenarios through web or telephony. |
| `get_test_run` | `agent_id`, `batch_id` | R, I | Gets batch status and per-scenario results. |
| `test_my_agent` | `agent_id`, `consent_to_charge`, optional `scenario_ids`, `count`, `wait_seconds` | D, O | Tests an agent in one call: runs its saved scenarios (generating some when it has none) and waits up to a minute for the verdicts, or returns the `batch_id` for `get_test_run`. Billed like `run_agent_tests`. |
| `test_in_text` | `agent_id`, `callers` (1 to 3 descriptions), optional `version`, `direction` | O | Free text test: simulated callers talk to the agent's draft (or live version) in text through the real pipeline, and the transcripts come back in about a minute. Tool results are simulated. |
| `run_simulation` | `agent_id`, `consent_to_charge`, optional `scenario_prompt`, `direction`, `language` | D, O | Starts one simulated phone call between an AI caller and the agent's draft, so a person can listen to a change. Returns the run at `in_progress`. It is recorded when the agent records calls, and graded after it ends. Billed like a test call, from the free test budget first. |
| `get_simulation` | `simulation_id` | R, I | Gets a simulated call's status and, once it ends, what it produced: a short-lived recording URL and the transcript when the agent records calls, and the grade once grading finishes (`null` before). |
| `list_validation_runs` | `agent_id` | R, I | Lists recent draft validation runs. |
| `get_validation_status` | `agent_id` | R, I | Gets the latest validation state and draft match. |
| `list_conversations` | `agent_id`, optional `split`, `source` | R, I | Lists the conversations the agent is tested against. Needs the agent iteration toolkit. |
| `get_conversation` | `conversation_id` | R, I | Gets one test conversation with its current turns. Needs the agent iteration toolkit. |
| `get_conversation_revisions` | `conversation_id`, optional `limit`, `offset` | R, I | Lists every revision of a test conversation: how and why it changed (refreshed for a prompt change, restored from an earlier revision), the behaviors added, removed and changed, the examples moved or retired, and the row diff. Needs the agent iteration toolkit. |
| `generate_conversations` | `agent_id`, optional `count`, `style` | O | Writes simulated test conversations against the agent's draft and turns their hardest moments into validation examples with answer keys. Quote with `dry_run` first; a real run needs its `quote_id` and `max_cost_cents`. Needs the agent iteration toolkit. |
| `import_conversations` | `agent_id`, optional `since_days`, `max_calls` | O | Turns the agent's recent calls into test conversations (at most two per caller, recording-off calls skipped) and their hardest moments into examples. Quote with `dry_run` first; a real run needs its `quote_id` and `max_cost_cents`. Needs the agent iteration toolkit. |
| `refresh_conversations` | `agent_id`, optional `conversation_ids`, `from_prompt_revision_id` | O | Brings the agent's test conversations up to its current prompt after behaviors were added, removed or changed: re-points, restores an earlier revision (real audio included) or rewrites the out-of-date turns, and retires examples whose caller turn is gone. Quote with `dry_run` first; a real run needs its `quote_id` and `max_cost_cents`. Needs the agent iteration toolkit. |
| `get_conversation_job` | `job_id` | R, I | Gets a generate, import or refresh job: status, cost so far against its cap, and what it wrote or refreshed. Needs the agent iteration toolkit. |
| `run_replays` | `agent_id`, optional `overrides`, `split`, `engine`, `sample_size`, `sample_seed`, `max_cost_cents`, `quote_id`, `dry_run` | D, O | Replays a sample of the agent's examples under its draft, or under overrides such as a candidate prompt, voice or tier, and judges each reply against the example's answer key. Exact replays run the turn's recorded audio as a live call would; pass rates are reported per engine. Replays of PHI calls run as PHI, and a configuration they cannot run (an ElevenLabs voice, an experimental product) is refused. `dry_run` returns an estimate, the `sample_seed` it drew and a `quote_id`; a real run sends the same request with that `quote_id` and `sample_seed`, and `max_cost_cents`, a hard cap: each request sets aside its upper bound before it is sent, and the run stops instead of sending one that does not fit, so leave the estimate's `largest_reservation_cents` of headroom per worker. An exact replay sets aside its worst case, about 85 cents to $1.25 per replay in flight for a typical turn (two run at once), against a real cost of a few cents; the run is charged what the replays really cost, so set `max_cost_cents` with room. An exact replay runs under a budget sized for a normal turn plus one re-run of the kind production takes (the reply race again and a watchdog retry); a turn that needs more is recorded as an error, `replay_budget_exhausted`, counted apart as `budget_exhausted`, left out of the pass rate and, on the test split, spends no cohort. On the test split, a cohort with recorded caller audio under a configuration other than Bolt v2 is refused (`test_needs_exact_replay`) and stays unused: measure that configuration on the dev split. Needs the agent iteration toolkit. |
| `compare_configs` | `agent_id`, `configs` (2 to 4, the first is the baseline), optional `sample_size`, `sample_seed`, `max_cost_cents`, `quote_id`, `dry_run` | O | Replays the same examples under each configuration and reports pass rate, examples fixed and broken against the baseline, latency to first audio, how often the caller waited on an acknowledgement, ticks or silence, and cost per turn, per engine. Quote it with `dry_run` like `run_replays`. Dev split only: on the test split it is refused (`comparison_dev_only`); compare on dev, then measure the pick with `run_replays`. Needs the agent iteration toolkit. |
| `get_replay_run` | `run_id`, optional `include_trace` | R, I | Gets a replay run's totals, flips and per-example results, and its comparison group. Exact replays that needed more than their budget are counted apart (`budget_exhausted`), outside the pass rate. Needs the agent iteration toolkit. |
| `create_talk_link` | `agent_id`, optional `variant_id`, `language`, `expires_in_minutes` | O | Creates a single-use link a person opens in a browser to talk to the agent's current draft, like the dashboard's Talk button. The link expires after 30 minutes by default (at most 120); the conversation bills like a Talk test call. See [Talk links](/api-reference/talk-links). Needs the agent iteration toolkit (see below). |

The tools marked as needing the agent iteration toolkit are part of it; the toolkit is enabled per organization while it is in beta, and without it they return `feature_not_enabled` with what to do next. Each of an agent's conversations is in its dev split or its test split. The test split is for measuring a change, not for tuning it, so the conversation tools return a test-split conversation as its id, split, source, status and counts only. A replay run on the test split replays one whole test cohort (`sample_size` and `sample_seed` are ignored), each example on the engine its data allows, set before the run from the example (exact for recorded caller audio, text for a text-only example; a configuration other than Bolt v2 has no exact path, so a cohort with recorded audio is refused for it with `test_needs_exact_replay` and stays unused; `engine` is omitted or `auto`, since `exact` or `text` is refused with `test_engine_per_example`, and nothing falls back to text), and returns totals only, per engine: pass rate, failures by severity and kind, latency and cost. Its first result that stores a replay spends the cohort, so the next test run, for any prompt, takes another, and with none left it is refused with `no_test_cohort` (importing calls or generating conversations fills new cohorts); a run that ends before storing one (Core cannot replay its audio examples exactly, `exact_replay_unavailable`, its replay capacity stays busy, `core_busy`, or every turn ran out of its budget, `replay_budget_exhausted`) leaves the cohort unused. On the dev split, an exact replay Core cannot run falls back to text and the run is marked `degraded`. Comparisons run on the dev split only. Every paid tool takes its dry run's `quote_id`, good for one run: it is used up once, durably, as the run starts, and a start that is refused or fails before then leaves it usable; a run that fails after it says so, and is repeated with a new dry run for a new `quote_id`. With OAuth, `review_prompt` and `refactor_prompt` need the `agents:write` scope, dry runs included, and the conversation and replay tools need `testing:write` to run. People see the whole test split in the dashboard. A call whose caller is in an agent's test split is held out, because it is part of the test set. In an organization with the toolkit, `list_calls`, `get_call`, `get_call_transcript`, `get_call_audio_url`, `get_call_grade` and `export_calls` return it as exactly `{"call_id", "start_time", "held_out": true}` (`started_at` in place of `start_time` in an export's rows), without its transcript, recording, history, grade or report; every other field of the call is absent, so read a withheld row by its `held_out` before anything else. The REST API does the same for API keys and OAuth tokens, and its views across many calls (report summaries, issue clusters, investigations, pipeline reports) leave held-out calls out of their counts, clusters and samples, and withhold any text a model wrote from them. A write on a held-out call (grading, promoting it to a test scenario, regenerating a turn) is refused with `held_out_call`. A test scenario someone promoted from a held-out call comes back from `list_test_scenarios` and in test runs as exactly `{"id", "held_out": true}`, and a simulation run from it, from `get_test_run` and the simulation tools, as exactly `{"id", "scenario_id", "held_out": true}`; its simulated calls are held out too, and test runs still run it. A dev conversation, example or replay result copied from a held-out caller's call (splits are per agent, so that caller may be in another agent's test split) reads like a test-split one. People see held-out calls in full in the dashboard, and an admin can let one API key see them in full (`include_held_out_calls`, off by default, set only in the dashboard), for an integration that needs every call; MCP never uses it. Webhooks are unchanged. Organizations without the toolkit see no `held_out` field and no change.

`generate_conversations`, `import_conversations` and `refresh_conversations` spend model credits. Call them with `dry_run: true` first: the answer is a cost quote, step by step, with a `quote_id`, and nothing runs. The quote counts every request the run can make at a typical size. A real run needs that `quote_id` (it expires after 15 minutes, and only works with the same arguments) and `max_cost_cents`, a hard cap: before each request the job sets aside the most that request can cost, and stops instead of sending one that does not fit, keeping what it wrote. Because of that set-aside, a run can stop with some of its cap unspent; the quote's `largest_reservation_cents` says how much headroom to leave. Simulated callers are invented from the agent's prompt; `style: "adversarial"` writes difficult callers who push on the prompt's weak spots, and those conversations always go to the dev split. `target: "changed_behaviors"` aims the callers at what changed in the last prompt edit. Each agent runs one of these jobs or one replay run at a time, so a refresh never changes the examples a replay is running on; a start while the other is running returns `job_active`, `replay_run_active` or `conversation_job_active` with what to wait for.

After a prompt edit that adds, removes or changes a behavior, `review_prompt` on the agent's draft reports how many test conversations were written for a prompt with other behaviors (`conversations.refresh_suggested`). `refresh_conversations` then brings them up to the draft, so the dev and test sets measure the new prompt on histories it could have produced. A refresh never loses anything: each conversation keeps every earlier revision, and when a removed rule comes back, the revision from when it existed is restored with its real caller audio. A refresh a coding agent starts leaves test-split conversations, and conversations copied from held-out calls, out of its selection, quote, progress and cost; naming one in `conversation_ids` returns 403 `test_conversation`. A person refreshes those from the dashboard, and to coding agents that job's results show them as ids and counts only. An `active` example whose history, reply or answer key a refresh rewrites goes back to `pending_review`, labeled `refreshed_needs_review`. A refresh's quote prices every conversation it reads as if it were rewritten, every model call at its output cap, and holds for the prompt and the conversations it was quoted on: when either changes before the run, quote again; when the prompt changes while it runs, the job stops as `failed`, keeping what it refreshed.

### Knowledge

| Tool | Main arguments | Annotations | What it does |
| --- | --- | --- | --- |
| `list_knowledge_bases` | — | R, I | Lists knowledge bases. |
| `create_knowledge_base` | `name`, optional `description` | — | Creates a knowledge base. |
| `add_knowledge_document` | `knowledge_base_id`, `name`, `content` | — | Adds text or Markdown. |
| `import_knowledge_url` | `url`, optional `name` | O | Queues a public page for safe ingestion. |
| `search_knowledge` | `knowledge_base_id`, `query` | R, I | Searches through production retrieval. |

### Integrations, webhooks, and remote MCP servers

| Tool | Main arguments | Annotations | What it does |
| --- | --- | --- | --- |
| `list_integrations` | — | R, I | Lists HTTP function integrations. |
| `create_integration` | `display_name`, function `spec`, optional endpoint fields | — | Creates an HTTP tool. Add authentication headers in the dashboard. |
| `test_integration` | `url`, optional method/body/timeout, `integration_id` with `header_names`, `confirmation_token` on the second request | D, O | Sends a bounded, SSRF-protected test request. Saved header values are filled in from the integration and only sent to its own host. `POST` (the default), `PUT`, `PATCH` and `DELETE` are two-step; `GET` runs immediately. |
| `list_webhook_endpoints` | — | R, I | Lists signed webhook endpoints. |
| `list_webhook_deliveries` | optional `agent_id`, optional `endpoint_id` | R, I | Lists recent payload-free webhook delivery outcomes. |
| `create_webhook_endpoint` | `label`, `url`, optional events/status | O | Creates a signed webhook endpoint. |
| `copy_webhook_endpoint` | `endpoint_id`, `target_agent_id` | I | Copies an agent's webhook, signing secret included, onto another agent on the server. Admins only. |
| `test_webhook_endpoint` | `endpoint_id` | O | Sends a synthetic event through normal delivery. |
| `list_mcp_servers` | — | R, I | Lists remote servers callable by voice agents. |
| `create_mcp_server` | `display_name`, `url` | O | Registers and syncs a remote server. Servers that need authentication headers are added in the dashboard. |
| `sync_mcp_server_tools` | `server_id` | D, O | Refreshes a remote server's tool catalog. |

### Campaigns

| Tool | Main arguments | Annotations | What it does |
| --- | --- | --- | --- |
| `list_campaigns` | — | R, I | Lists outbound campaigns. |
| `create_campaign` | campaign fields | — | Creates a draft campaign. |
| `add_campaign_contacts` | `campaign_id`, `contacts` | — | Adds up to 5,000 JSON contacts. |
| `campaign_action` | `campaign_id`, `action`, optional `consent_to_charge`, `confirmation_token` on the second request | D, O | Runs `start`, `pause`, `resume`, or `stop`. `start` and `resume` are two-step; `pause` and `stop` run immediately. |
| `get_campaign_stats` | `campaign_id` | R, I | Gets counters and recent outcomes. |
| `check_campaign` | optional `campaign_id`, `contact_phone_number`, `contact_status` | R, I | Explains why a campaign is not calling: its calling window in its own time zone, contacts due now and what stops dialing. |

### Organization settings and blocked callers

| Tool | Main arguments | Annotations | What it does |
| --- | --- | --- | --- |
| `get_org_settings` | — | R, I | Reads the time zone, business hours, test numbers, call outcome labels, status names and which alerts are off, with `updated_at`. |
| `update_org_settings` | changed settings, `if_updated_at`, `confirmation_token` when asked | D, I | Changes them (admins only). Lists and objects replace the stored value. Turning an alert off or adding a test number is two-step. The result has the old values for undo. |
| `get_account_limits` | — | R, I | Gets platform limits with this organization's own values. |
| `list_blocked_callers` | optional `number`, `search` | R, I | Lists blocked caller numbers. |
| `block_callers` | `numbers`, optional `note`, `confirmation_token` on the second request | D, I | Refuses calls from these numbers before any agent answers. Two-step, admins only. |
| `unblock_callers` | `numbers`, `confirmation_token` on the second request | D, I | Removes numbers from the blocklist. Two-step, admins only. |

`get_org_settings`, `update_org_settings` and `get_account_limits` need the `org:read` or `org:write` [OAuth scope](/guides/oauth); a connection made before they existed is asked to approve it on first use.

### Capabilities, help, and imports

| Tool | Main arguments | Annotations | What it does |
| --- | --- | --- | --- |
| `get_supported_languages` | — | R, I | Lists the languages agents speak, with codes. |
| `get_agent_capabilities` | — | R, I | Says what an agent can do on a call and which settings and integrations exist. |
| `escalate_to_human` | `summary` | O | Asks the ThunderPhone team for help. They reply in ThunderPhone. For organizations that may handle PHI only a neutral note leaves ThunderPhone. |
| `request_feature` | `title`, `request`, `details` | O | Files a feature request with the ThunderPhone team. At most three per organization a day. |
| `start_agent_import` | `platform` | R, I | Returns the dashboard link where you enter your Vapi, Retell, ElevenLabs or Bland key and pick agents. No tool takes the key. |
| `get_agent_import` | optional `import_id` | R, I | Lists recent imports, or one import's status and mapped agents. |
| `commit_agent_import` | `import_id`, optional `item_ids` | O | Creates the agents from a ready import, in the background. Admins only. |

### Voices, billing, and docs

| Tool | Main arguments | Annotations | What it does |
| --- | --- | --- | --- |
| `list_voices` | — | R, I | Lists voices and supported languages. |
| `preview_voice` | `voice`, `language`, `text` | O | Generates a sample and returns a signed URL. |
| `list_voice_clones` | — | R, I | Lists custom voice clones. |
| `get_billing_summary` | — | R, I | Gets balance and authoritative tier prices; no payment mutations are exposed. |
| `search_docs` | `query`, optional `limit` | R, I, O | Searches the public docs index. |
| `get_doc_page` | `path` | R, I, O | Fetches one public Markdown docs page. |

Results about an agent, call, number, campaign or setting carry `web_url`, the matching dashboard page, so you can open it in ThunderPhone or keep going with Zeus there.

All product tools use the same REST code paths as the public API. REST validation, organization scoping, roles, billing admission, quotas, TCPA confirmation, provider safety, and audit behavior therefore apply unchanged.

## Editing a prompt in place

`update_agent` can change part of the draft prompt without sending the whole text back. `prompt_edits` is an ordered list of find and replace pairs, the same format `review_prompt` and `refactor_prompt` return:

```json
{
  "agent_id": 123,
  "expected_prompt_sha256": "9c1f…",
  "prompt_edits": [
    {
      "find": "Ask for their name and their phone number, then tell them we will call back.",
      "replace": "Tell them we will call back, then ask for their name. Once they answer, ask for their phone number."
    }
  ]
}
```

The server applies the edits in order to the agent's current draft prompt (the deployed prompt when there is no draft) and writes the result to the draft through the same path as a whole-prompt `update_agent`. Each `find` must appear exactly once in the prompt as it stands when that edit's turn comes. If one does not, nothing is written and the error names the edit:

| Code | Meaning | What to do |
| --- | --- | --- |
| `prompt_edit_not_found` | The `find` text is not in the current draft prompt. `edit_index` says which edit. | Read the agent again and copy the passage exactly. |
| `prompt_edit_ambiguous` | The `find` text appears more than once. `occurrences` says how often. | Include more of the surrounding text. |
| `stale_prompt` | `expected_prompt_sha256` is not the SHA-256 of the current draft prompt: it changed after you read it. | Read the agent again, rewrite the change against the current text, and send its SHA-256. |
| `conflict` | Another write landed between the server reading the draft and writing it. | Retry; the draft was not changed by this call. |

`expected_prompt_sha256` is optional and also guards a whole-prompt write. Use the `prompt_sha256` from `review_prompt`, or `source_prompt_sha256` from `refactor_prompt`. Any call that changes the prompt returns `prompt_sha256` for the new text, `previous_prompt_sha256` when the server read the draft first, and a `next_step` suggesting `review_prompt` with `previous_prompt` set to the text before the change. The REST API takes only the whole prompt: `PATCH /v1/agents/{agent_id}` with `prompt` and `if_updated_at`.

## Confirming destructive actions

Tools marked D change or remove something, or begin dialing real people. Those that cannot be undone take two requests. The first request changes nothing and returns:

```json
{
  "status": "confirmation_required",
  "action": "Delete agent",
  "target": { "id": 195, "name": "Front Desk Receptionist" },
  "confirmation_token": "…",
  "expires_in_seconds": 600,
  "next_step": "…"
}
```

The assistant shows the user what is affected and asks for a yes. It then repeats the request with the same arguments plus `confirmation_token`. A token is valid for 10 minutes, works once (even if that call fails), and covers one organization, one person, one tool and one exact set of arguments, so deleting three agents takes three confirmations. `campaign_action` with `pause` or `stop` skips this step so a running campaign can always be halted at once, and so does `test_integration` with `GET`. Some D tools run in one request because the D marks their effect, not a server-side confirmation: `update_agent` replaces what the draft had (`discard_agent_draft` reverts it), `deploy_agent` replaces the live configuration, `update_phone_number` reroutes live calls, `sync_mcp_server_tools` replaces a remote server's tool catalog, `import_voip_numbers` re-points numbers at your carrier, `run_agent_tests` and `run_simulation` can spend credit, `send_sms` and `place_call` reach a real person (`place_call` keeps its own consent confirmation), and `provision_phone_number` buys a number. `test_my_agent` spends test credit and needs `consent_to_charge`. `run_replays` spends money too; its `dry_run` quote and `max_cost_cents` cap stand in for the confirmation. Your MCP client may still ask you to approve them.

Some changes that can be undone still wait for a yes: `block_callers`, `unblock_callers` and `save_voip_setup` always, `update_org_settings` when it turns an alert off or adds a test number, and `update_agent` when its `attention_reasons` turn one of the agent's alerts off. Their `next_step` asks you to confirm the exact change rather than warning that it cannot be undone.

## Starter prompts

`prompts/list` advertises twelve reusable workflows:

- `create_inbound_receptionist`
- `run_agent_tests`
- `buy_and_attach_number`
- `review_low_grade_calls`
- `add_url_to_agent_knowledge`
- `improve_agent_from_calls`
- `check_change_before_deploy`
- `test_my_agent`
- `diagnose_phone_number`
- `why_campaign_not_calling`
- `call_report`
- `import_agents`

Use `prompts/get` with the listed prompt name and its declared arguments to receive a ready-to-run user message.

## Resources

`resources/list` exposes public, cached references:

| URI | Content |
| --- | --- |
| `thunderphone://docs/llms.txt` | Public documentation index. |
| `thunderphone://docs/quickstart` | Quickstart Markdown. |
| `thunderphone://pricing` | Current public pricing Markdown. |
| `thunderphone://guides/prompt-style` | The voice-agent prompt style guide that `review_prompt` checks against. Its guideline ids (P1, W2 and so on) are the ones findings cite. |
| `thunderphone://guides/working-with-thunderphone` | How an assistant should work with these tools: small rounds on the draft, a check before every deploy, the user's yes for anything live or billed, and never asking for secrets. |

Read one with `resources/read`. Public fetches use a short timeout, a 2 MiB limit, and a ten-minute in-process cache.

## Protocol and errors

The server supports protocol versions `2025-06-18` and `2025-03-26`; it echoes a supported client version and otherwise selects `2025-06-18`. It implements `initialize`, `ping`, tools, prompts, resources, and notifications. Notifications return `202 Accepted`. This stateless server does not expose an SSE listener or session deletion, so `GET` and `DELETE` return `405 Method Not Allowed` with `Allow: POST`.

Tool failures remain successful JSON-RPC responses with `isError: true`. Their text contains a short sentence followed by a JSON block:

```json
{
  "code": "insufficient_balance",
  "detail": "There is not enough prepaid balance.",
  "next_step": "Call get_billing_summary, add funds in Organization > Billing, then retry."
}
```

The distinct `outbound_tcpa_confirmation_required:` prefix is retained for `place_call`. Unknown JSON-RPC methods return `-32601` in an HTTP `200` response. JSON-RPC batches are not supported by MCP `2025-06-18` and return a clean `-32600` invalid-request error.

<!-- en: guides/oauth -->
---
title: "Connect with OAuth"
description: "Authorize MCP clients and the ThunderPhone CLI without sharing an API key."
---

OAuth lets an app connect to one ThunderPhone organization with the permissions you approve. Directory clients should use OAuth by default. Organization API keys remain available for clients that require a manually configured Bearer token.

## Approve a connection

Start the connection in your MCP client. Sign in to ThunderPhone, check the app name and requested permissions, choose an organization, and select **Approve**. Select **Deny** if you did not start the connection or do not trust the app. App names are supplied by their developers and are not a verification badge.

Read permissions expose the named data, including recordings and transcripts when `calls:read` is requested. Write permissions can change or delete resources; calls, campaigns, phone purchases, and deployments can incur costs or affect production. Your organization role still applies.

For a CLI connection, open the verification link shown in your terminal, compare the eight-character code, select your organization, and approve. Merely opening the link does not grant access. Codes expire after 15 minutes.

## Disconnect an app

Open **Organization → API keys → Authorized apps** in the dashboard and choose **Revoke**. This revokes your selected authorization for the current organization, including its access and refresh tokens. Reconnect from the app if you want to authorize it again.

Changing or resetting your password, or changing your account email, signs you out everywhere: it also revokes every app you authorized, in every organization, including MCP connectors, Zapier and the CLI. Reconnect each app afterwards.

Webhook endpoints an app created keep delivering events after its access is revoked, until you delete them. After a suspected account theft, list them with [`GET /v1/developer/webhook-endpoints`](/webhooks/endpoints) using an admin API key and delete any you don't recognize; endpoints scoped to an agent also appear in that agent's **Webhooks** section.

## Discovery for MCP clients

Use the server URL `https://api.thunderphone.com/v1/mcp`. A request without valid authentication receives `401` with:

```http
WWW-Authenticate: Bearer resource_metadata="https://api.thunderphone.com/.well-known/oauth-protected-resource"
```

Fetch that document, then fetch the authorization server's metadata at `https://api.thunderphone.com/.well-known/oauth-authorization-server`. Resource metadata is also available at `/.well-known/oauth-protected-resource/v1/mcp`. Use the returned endpoints instead of constructing them. The resource identifier is `https://api.thunderphone.com/v1/mcp`.

The server supports authorization code with **S256 PKCE**, rotating refresh tokens, public dynamic client registration, revocation, and the device authorization grant. There are no client secrets or implicit grants. OpenID discovery is also available at `/.well-known/openid-configuration`; it includes the same authorization-server fields plus `subject_types_supported: ["public"]` and the userinfo endpoint. ID tokens and Client ID Metadata Documents (CIMD) are not supported.

### Register a public client

Send JSON to `POST /v1/oauth/register`:

```json
{
  "client_name": "My MCP client",
  "redirect_uris": ["http://127.0.0.1:8765/callback"],
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"]
}
```

Save the returned `client_id`. Redirects must use HTTPS, or HTTP on `127.0.0.1` or `localhost`. Register the exact callback URI, including its port and path. Fragments and embedded credentials are rejected. Optional `client_uri` and `logo_uri` must use HTTPS; ThunderPhone does not fetch them during registration. Registration is rate-limited. Registered clients do not expire and remain registered when a connection is revoked. HTTPS callbacks include `https://chatgpt.com/connector/oauth/<id>` and `https://chatgpt.com/connector_platform_oauth_redirect`. Each connection may register its own client.

### Authorization code

Open the discovered authorization endpoint with `client_id`, the exact registered `redirect_uri`, `response_type=code`, a random `state`, `scope`, `code_challenge`, `code_challenge_method=S256`, and `resource=https://api.thunderphone.com/v1/mcp`. Compute the challenge as the unpadded base64url SHA-256 digest of a fresh high-entropy PKCE verifier. Check the returned `state` and `iss` before exchanging the code. Every authorization response, including denial and protocol errors, identifies the issuer with `iss`, exactly matching the discovered `issuer`. Errors for an invalid client or callback are returned locally without redirecting to that callback.

Exchange at `POST /v1/oauth/token` using form encoding (JSON is also accepted):

```text
grant_type=authorization_code
client_id=<your client id>
code=<single-use authorization code>
redirect_uri=<exact registered redirect URI>
code_verifier=<original PKCE verifier>
resource=https://api.thunderphone.com/v1/mcp
```

The optional `resource` parameter is accepted on both authorization and token requests (including refresh and device exchanges). When omitted, it defaults to the discovered MCP resource. When present, it must exactly match that resource; other values return `invalid_target`. Access tokens carry that audience, and MCP rejects tokens with a missing or different audience with `401` and a discovery challenge.

Authorization requests and codes expire after 10 minutes. Every token response contains `access_token`, `token_type` (`Bearer`), `expires_in` (3600 seconds by default), `refresh_token`, `scope`, `organization_id`, and `organization_name`. Send access tokens only through the `Authorization: Bearer` header. Never put tokens in URLs, logs, source control, or chat.

### Refresh and revoke

Refresh with `grant_type=refresh_token`, `client_id`, `refresh_token`, and `resource` at the token endpoint. Save the new refresh token atomically and stop using the old one. Refresh tokens expire after 30 days without a successful refresh. An optional `scope` may narrow the granted permissions. `offline_access` is always included and refresh tokens are always issued. An initial request without `scope` grants only `offline_access`, so clients should request the permissions they need.

Code reuse and rotated refresh-token reuse revoke the entire authorization. Serialize refreshes within a client; replaying a successfully exchanged credential is not a safe retry strategy.

To disconnect, send `token` and `client_id` to `POST /v1/oauth/revoke`. Revoking either token revokes its authorization, including all tokens issued from it. An unknown token returns success without disclosing whether it exists. Dashboard sessions can list their own authorizations at `GET /v1/oauth/grants` and revoke one at `DELETE /v1/oauth/grants/<id>`, with `X-ThunderPhone-Org` selecting the organization.

### Device authorization

Device authorization is restricted to pre-registered clients; dynamically registered clients receive `unauthorized_client`. The pre-registered public client `thunderphone-cli` supports device authorization and refresh. Send `client_id=thunderphone-cli` and `scope` to `POST /v1/oauth/device/code`. Display `user_code` and `verification_uri` to the user, or open `verification_uri_complete`.

Poll the token endpoint with `grant_type=urn:ietf:params:oauth:grant-type:device_code`, `client_id`, and `device_code`, waiting at least the returned `interval` (5 seconds). Continue on `authorization_pending`. On `slow_down`, use the new `interval` returned in the response (increased by 5 seconds) for every subsequent request. Stop on `access_denied`, `expired_token`, or any other error. Never approve a device code automatically.

The pre-registered `thunderphone-mcp` client accepts `http://127.0.0.1/callback` and `http://localhost/callback` on any port. Scheme, host, path and query must match; the token exchange must use the exact redirect URI (including port) from authorization. Dynamically registered clients require exact redirect-URI matching, including the port. Register a different callback dynamically if you need another path.

### Account identity and workspace domain checks

Request both `openid email` alongside the operation scopes your client needs. Call the discovered `userinfo_endpoint` (`GET /v1/oauth/userinfo`) with the access token in the Bearer header. A successful response contains:

```json
{
  "sub": "123",
  "email": "person@example.com",
  "email_verified": true,
  "name": "Example User",
  "org_id": 456
}
```

`sub` is the stable user identifier; `org_id` is the organization selected during consent. The endpoint requires both identity scopes and returns `403` if either is missing. It returns `403` with `error=access_denied` if the account has no verified email profile, rather than asserting that an unverified email is trusted. Invalid, expired, revoked, or wrong-audience tokens return `401`. Human session tokens and organization API keys cannot call userinfo. No ID token is issued.

## Available permissions

| Family | Scopes |
| --- | --- |
| Agents and agent imports | `agents:read`, `agents:write` |
| Calls | `calls:read`, `calls:write` |
| Phone numbers, blocked callers and VoIP | `numbers:read`, `numbers:write` |
| Knowledge | `knowledge:read`, `knowledge:write` |
| Campaigns | `campaigns:read`, `campaigns:write` |
| Integrations, webhook endpoints, MCP servers | `integrations:read`, `integrations:write` |
| Voices | `voices:read` |
| Test scenarios, test runs, validation | `testing:read`, `testing:write` |
| Billing | `billing:read` |
| Organization settings (MCP tools only) | `org:read`, `org:write` |
| Account identity and verified email | `openid`, `email` (both required for userinfo) |
| Persistent connection | `offline_access` (always included) |

GET, HEAD, and OPTIONS use read scopes; other methods use write scopes. Voice and billing mutations are unavailable through OAuth; `POST /v1/voices/preview` uses `voices:read` because it previews a voice without changing its configuration. MCP tools enforce the scope of their underlying REST operation; MCP tools with no single REST operation name their own (for example `org:read` for `get_org_settings`, `numbers:write` for `unblock_callers`). `org:read` and `org:write` open no REST route. Cross-organization transfers are denied even when the authorizing user belongs to both organizations. Other API families, including API-key management and human account settings, are unavailable through OAuth. A missing permission on a REST operation returns `403` with `WWW-Authenticate: Bearer error="insufficient_scope", scope="..."`. Invalid or expired access tokens return `401`.


### MCP tool authentication signals

Every tool in `tools/list` includes `securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}]`, with the scope of that tool's REST operation. Public documentation tools, `get_supported_languages`, `get_agent_capabilities`, `escalate_to_human` and `request_feature` use an empty scope list and still require an authenticated connection.

A valid token missing a tool's scope receives HTTP `200` with a JSON-RPC `result` containing `isError: true`, explanatory text in `content`, and `_meta["mcp/www_authenticate"]`. The latter is an array containing a Bearer challenge with `resource_metadata`, `error="insufficient_scope"`, `error_description`, and the required `scope`. The tool is not executed. Use this challenge to request expanded consent. Missing or invalid authentication continues to return HTTP `401` with `WWW-Authenticate`; REST scope failures continue to return HTTP `403`.

## Credential retention

The API runs `python manage.py oauth_cleanup` hourly in staging and production. It removes expired authorization requests and device codes. Expired access tokens, authorization codes and refresh-token hashes are pruned only after their grant is revoked or the entire family is dead. Spent hashes are retained while the family has a usable refresh token, authorization code, approved device code or access token, so cleanup cannot disable replay detection.

<!-- en: guides/use-with-openai-realtime -->
---
title: "Use ThunderPhone with OpenAI Realtime clients"
description: "Point an OpenAI Realtime-compatible server client at ThunderPhone, using either a saved agent or inline session configuration."
---

ThunderPhone implements a focused subset of the OpenAI Realtime event model.
An existing server-side client can keep its WebSocket, audio, session, and
response event flow while using a ThunderPhone voice agent.

## Before you connect

You need a ThunderPhone organization secret API key and a server runtime that
can open WebSockets. Do not connect from browser code or expose the key to a
browser. To use a saved agent, deploy it first and copy its numeric agent ID.

Connect to:

```text
wss://api.thunderphone.com/v1/realtime
```

Authenticate the WebSocket upgrade from your server:

```http
Authorization: Bearer sk_live_YOUR_API_KEY
```

Query-string authentication exists for clients that cannot set handshake
headers, but URLs are easier to leak into logs.

## Choose who owns the configuration

| Mode | Select it with | Configuration source |
| --- | --- | --- |
| Saved agent | `session.prompt.id` in the first `session.update`, or `?agent_id=12` | Deployed prompt, voice, product, languages, knowledge, and compatible server-run tools, plus this session's instructions and variables |
| Inline | Neither | The first accepted `session.update` from your client |

### Saved agent

Keep what every call shares in a saved agent, where it has versions and test
sets, and send what changes per session in the first `session.update`:
`session.prompt.id` picks the deployed agent, `session.instructions` carries
this session's brief, and `session.prompt.variables` fills the agent prompt's
`{{name}}` placeholders.

```json
{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "prompt": {
      "id": "12",
      "variables": { "user_name": "Ada Park" }
    },
    "instructions": "Ada is a Costco member in Mountain View. Call the store and ask for today's opening hours.",
    "audio": {
      "input": { "format": { "type": "audio/pcm", "rate": 24000 } },
      "output": { "format": { "type": "audio/pcm", "rate": 24000 } }
    }
  }
}
```

The instructions become the call's [context](/guides/call-variables#context),
added after the agent's prompt for this call only. The session's own options
(`telephony`, `outbound`, `ivr_mode`, `call_events`, `placeholders`) and the
language it starts in (`primary_language`) go in `session.config`, as for an
inline session. The agent's voice, product, and tools come from its deployed
configuration: a voice, another agent setting, or an OpenAI-only field such as
a non-default `tool_choice` in the update produces an `error` event and is
ignored, and tools your client runs are refused (client-executed tools need
an inline session). `prompt.version` is accepted and ignored. See [Use a saved
agent](/api-reference/realtime#use-a-saved-agent) for every rule.

Connecting with `?agent_id=12` instead starts the agent while the socket
connects, so a `session.update` is not required, but its session config is
then fixed: instructions, variables and session options (`outbound`,
`ivr_mode`, `telephony`, `placeholders`, `call_events`) sent after that are
refused with an `error` event. Add
`&wait_for_session_update=1` to the URL to start it at your first
`session.update` instead, which then carries instructions, variables and
session options the same way; an outbound session needs this. Until that update arrives, caller audio is held, other events are
refused, and the socket closes if none arrives within 10 seconds.

The greeting remains available, but Realtime disables the agent's spoken
silence check-ins and offers `transfer_call` and `send_keypad_input` only with
`call_events`. Other compatible tools run on ThunderPhone; client-executed
tools need an inline session. Audio formats and the session's instructions and variables cannot
change after the call starts.

### Inline session

Without a saved agent, wait for `session.created`, then send `session.update`:

```json
{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "instructions": "Answer questions clearly and keep responses brief.",
    "audio": {
      "input": {
        "format": { "type": "audio/pcm", "rate": 24000 }
      },
      "output": {
        "format": { "type": "audio/pcm", "rate": 24000 },
        "voice": "olivia"
      }
    },
    "config": {
      "product": "bolt"
    }
  }
}
```

The first accepted update provisions the call. `session.updated` means the
session is live. Instructions, voice, product, tools, and audio formats cannot
change after that point. To keep the instructions fixed and vary only named
values, write `{{name}}` placeholders into them and send the values in
`session.config.variables`.

Inline sessions have no automatic greeting or spoken silence check-ins. To
make the agent speak first, append a system or user message and send
`response.create`. A completely idle session still ends at the platform's
silent-call limit, 600 seconds by default.

## Use the official OpenAI SDK

Pass a WebSocket base URL ending at `/v1`; the SDK appends `/realtime`. The
`model` value is a compatibility name and does not select the ThunderPhone
product. Choose the product in the session configuration or the saved agent.

This connection check creates an inline Bolt session, prints events until the
first `session.updated`, and closes. Use the [minimal Python
client](/api-reference/realtime#minimal-python-client) to stream audio.

```python
import asyncio
import os

from openai import AsyncOpenAI


async def main():
    client = AsyncOpenAI(
        api_key=os.environ["THUNDERPHONE_API_KEY"],
        websocket_base_url="wss://api.thunderphone.com/v1",
    )

    async with client.realtime.connect(
        model="thunderphone-realtime"
    ) as connection:
        await connection.session.update(session={
            "type": "realtime",
            "instructions": "Listen to the caller and help them complete the call.",
            "config": {"product": "bolt"},
        })
        async for event in connection:
            print(event.type)
            if event.type == "session.updated":
                break


if __name__ == "__main__":
    asyncio.run(main())
```

Keep your existing handling for input-audio append, response audio deltas,
interruptions, function calls, errors, and clean socket closure. Inline custom
functions execute in your client; return their results through the Realtime
protocol. Saved-agent tools execute on ThunderPhone.

## Session lifecycle and failures

One WebSocket represents one call. An invalid agent ID or rejected inline
configuration produces an `error` event. Wait for `session.updated` before
treating the session as live. Declare the actual input and output formats and
sample rates: a PCM rate mismatch plays audio too fast or too slowly instead of
producing a validation error.

After the session starts, close the socket cleanly when your application is
done. Inline sessions can use client-executed functions. Saved-agent sessions
use compatible ThunderPhone-run tools, and offer `transfer_call` (plus
`send_keypad_input` on outbound sessions) only with `call_events`; your client
carries out those `call.*` events.

## Test the integration

Start with the [minimal Python WAV client](/api-reference/realtime#minimal-python-client)
and a mono PCM16 WAV at its declared rate. Verify:

1. The server accepts the configuration and sends `session.updated`.
2. Input produces transcript and response-audio events at the expected speed.
3. Interruption and response cancellation stop remaining output audio.
4. Inline function results or saved-agent tool results return to the model.
5. Invalid input produces an `error` event your client handles.
6. Your client closes the socket and the call appears in [Call
   history](/guides/review-calls).

The [Realtime WebSocket reference](/api-reference/realtime) lists the accepted
events, audio formats, session fields, and complete examples.

## Cost

Realtime calls are priced like any other call: what their parts cost at our
providers' list prices, plus an infrastructure charge and a markup. Enabling
live transcript deltas adds transcription work for the whole session; see [Live
transcripts](/api-reference/realtime#live-transcripts) and
[Pricing](/guides/pricing).

`POST /v1/realtime/sessions` is a separate managed LiveKit path. It creates a
room and scoped participant token; it is not required for a direct WebSocket
connection.

For framework integrations, see [Use ThunderPhone from Pipecat](/guides/use-with-pipecat)
and [Use ThunderPhone from LiveKit Agents](/guides/use-with-livekit).

<!-- en: guides/use-with-pipecat -->
---
title: "Use ThunderPhone from Pipecat"
description: "Run a ThunderPhone voice agent as the speech-to-speech service inside a Pipecat pipeline, with your own transport and telephony."
---

[Pipecat](https://github.com/pipecat-ai/pipecat) is an open-source framework
for building voice agents out of composable services. ThunderPhone plugs in as
a **speech-to-speech LLM service**: Pipecat sends caller audio, ThunderPhone
returns the agent's voice, transcripts and function calls, and Pipecat's
transport (Daily, LiveKit, Twilio, WebRTC, a local microphone) carries the
audio. Speech recognition, the language model, the voice, turn-taking, 47
languages and tools all run on ThunderPhone.

Calls made this way appear in [call history](/api-reference/calls) and are
billed like any other realtime call ([pricing](/guides/pricing)). There
is no subscription and no ThunderPhone phone number involved.

## Install

```bash
pip install pipecat-thunderphone
export THUNDERPHONE_API_KEY=sk_live_...   # a secret API key
```

The package wraps Pipecat's OpenAI Realtime service, because ThunderPhone's
[Realtime WebSocket](/api-reference/realtime) speaks the same protocol. It
needs `pipecat-ai` 1.8 or newer.

## Run a saved agent

Everything the agent does (prompt, voice, engine, languages, tools, greeting,
silence check-ins) is configured on ThunderPhone. The pipeline only moves audio.

```python
from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.worker import PipelineParams, PipelineWorker
from pipecat.processors.aggregators.llm_context import LLMContext
from pipecat.processors.aggregators.llm_response_universal import LLMContextAggregatorPair
from pipecat_thunderphone import ThunderPhoneRealtimeLLMService

llm = ThunderPhoneRealtimeLLMService(agent_id=12)

context = LLMContext()
aggregators = LLMContextAggregatorPair(context)
pipeline = Pipeline([
    transport.input(),
    aggregators.user(),
    llm,
    aggregators.assistant(),
    transport.output(),
])
worker = PipelineWorker(pipeline, params=PipelineParams(allow_interruptions=True))
```

A saved agent opens the call on its own schedule, so the service does not
request an opening response from Pipecat. Pass `greet_on_connect=True` if you
want one anyway.

## Configure the session inline

Without `agent_id`, instructions and tools come from the Pipecat context, the
same way they do for OpenAI. `product` picks the engine and `voice` picks the
ThunderPhone voice.

```python
from pipecat.adapters.schemas.function_schema import FunctionSchema
from pipecat.adapters.schemas.tools_schema import ToolsSchema
from pipecat.services.llm_service import FunctionCallParams

llm = ThunderPhoneRealtimeLLMService(product="bolt", voice="olivia", language="es")

async def check_availability(params: FunctionCallParams):
    slots = await calendar.free_slots(params.arguments["date"])
    await params.result_callback({"slots": slots})

llm.register_function("check_availability", check_availability)

context = LLMContext(
    messages=[{"role": "system", "content": "You are Acme Dental's receptionist."}],
    tools=ToolsSchema(standard_tools=[
        FunctionSchema(
            name="check_availability",
            description="Free appointment slots on a date",
            properties={"date": {"type": "string"}},
            required=["date"],
        )
    ]),
)
```

Inline sessions are client-steered: the agent speaks first because Pipecat
requests a response when the context arrives, and stays quiet during silence
unless you append a message or request another response.

## Options

| Argument | Meaning |
|---|---|
| `api_key` | Secret key (`sk_live_...`). Defaults to `THUNDERPHONE_API_KEY`. |
| `agent_id` | Run a saved agent. Mutually exclusive with `product` and `voice`. |
| `product` | Engine for inline sessions: `spark`, `bolt` or `storm`. |
| `voice` | ThunderPhone voice name for inline sessions. |
| `language` | Primary language hint for inline sessions, e.g. `es`. |
| `from_number`, `to_number` | Numbers to record on the call when the pipeline fronts a phone line. |
| `live_transcripts` | Stream caller transcript fragments mid-utterance (billed extra). |
| `greet_on_connect` | Request a first response as soon as the session is ready. |
| `end_task_on_call_ended` | Push `EndWorkerFrame` when ThunderPhone ends the call (default on). |

## Events

ThunderPhone adds platform events on top of the realtime protocol. The service
delivers them to handlers:

```python
@llm.event_handler("on_call_ended")
async def on_call_ended(service, event):
    print("call ended:", event["reason"], "call id:", service.call_id)
```

`service.call_id` is set once the session is live. Use it with
[`GET /v1/calls/{call_id}`](/api-reference/calls) to fetch the recording,
transcript and grade after the call.

## Limits

- Turn detection is server-side and always on; Pipecat-driven turns
  (`turn_detection=False`) are not supported.
- Functions registered on the service run for inline sessions only. A saved
  agent executes its own tools on ThunderPhone.
- Audio is 16-bit mono PCM at 24 kHz in both directions.
- Video frames are ignored.

<Note>
Building on LiveKit Agents instead? See
[Use ThunderPhone from LiveKit Agents](/guides/use-with-livekit).
</Note>

<!-- en: guides/use-with-livekit -->
---
title: "Use ThunderPhone from LiveKit Agents"
description: "Run a ThunderPhone voice agent as the realtime (speech-to-speech) model of a LiveKit Agents session, with LiveKit rooms, SIP and telephony around it."
---

[LiveKit Agents](https://github.com/livekit/agents) is an open-source framework
for realtime voice agents on top of LiveKit rooms. ThunderPhone plugs in as the
**realtime model**: the framework sends the participant's audio, ThunderPhone
returns the agent's voice, transcripts and function calls, and LiveKit's room,
SIP trunks and telephony carry the audio. Speech recognition, the language
model, the voice, turn-taking, 47 languages and tools all run on ThunderPhone.

Calls made this way appear in [call history](/api-reference/calls) and are
billed like any other realtime call ([pricing](/guides/pricing)). There
is no subscription and no ThunderPhone phone number involved.

## Install

```bash
pip install livekit-plugins-thunderphone
export THUNDERPHONE_API_KEY=sk_live_...   # a secret API key
```

The plugin wraps LiveKit's OpenAI Realtime model, because ThunderPhone's
[Realtime WebSocket](/api-reference/realtime) speaks the same protocol. It
needs `livekit-agents` 1.8 or newer.

<Note>
The plugin is under review in the
[livekit/agents](https://github.com/livekit/agents) repository. Until LiveKit
publishes it, install it from the branch:

```bash
pip install "git+https://github.com/kolchinski/agents@add-thunderphone-plugin#subdirectory=livekit-plugins/livekit-plugins-thunderphone"
```
</Note>

## Run a saved agent

Everything the agent does (prompt, voice, engine, languages, tools, greeting,
silence check-ins) is configured on ThunderPhone. The session only moves audio.

```python
from livekit.agents import Agent, AgentSession, JobContext, WorkerOptions, cli
from livekit.plugins import thunderphone


async def entrypoint(ctx: JobContext):
    session = AgentSession(llm=thunderphone.RealtimeModel(agent_id=12))
    await session.start(agent=Agent(instructions=""), room=ctx.room)


if __name__ == "__main__":
    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))
```

A saved agent greets and runs its own tools on ThunderPhone; the LiveKit
`Agent`'s instructions and tools are not sent. The call ends when the
ThunderPhone agent hangs up, and the session closes with it.

## Configure the session inline

Without `agent_id`, instructions and tools come from the LiveKit `Agent`, the
same way they do for OpenAI. `model` picks the engine and `voice` picks the
ThunderPhone voice.

```python
from livekit.agents import Agent, AgentSession, RunContext, function_tool
from livekit.plugins import thunderphone


class Receptionist(Agent):
    def __init__(self):
        super().__init__(instructions="You are Acme Dental's receptionist. Be brief.")

    @function_tool
    async def check_availability(self, context: RunContext, date: str) -> dict:
        """Free appointment slots on a date."""
        return {"slots": await calendar.free_slots(date)}


async def entrypoint(ctx: JobContext):
    session = AgentSession(
        llm=thunderphone.RealtimeModel(model="bolt", voice="olivia", language="es"),
    )
    await session.start(agent=Receptionist(), room=ctx.room)
    await session.generate_reply()   # the agent speaks first
```

ThunderPhone freezes instructions and tools when the call starts, so
`update_instructions`, `update_tools` and agent hand-offs that change them are
not supported mid-call. Inline sessions are client-steered: the agent speaks
when you call `generate_reply()` or when the participant finishes a turn.

## Options

| Argument | Meaning |
|---|---|
| `api_key` | Secret key (`sk_live_...`). Defaults to `THUNDERPHONE_API_KEY`. |
| `agent_id` | Run a saved agent. Mutually exclusive with `model` and `voice`. |
| `model` | Engine for inline sessions: `spark`, `bolt` or `storm`. |
| `voice` | ThunderPhone voice name for inline sessions. |
| `language` | Primary language hint for inline sessions, e.g. `es`. |
| `caller_number`, `callee_number` | Phone numbers of the call when the room fronts a phone line. They appear as the from and to numbers in call history. |
| `live_transcripts` | Stream caller transcript fragments mid-utterance (billed extra). |
| `base_url` | Endpoint override, default `wss://api.thunderphone.com/v1/realtime`. |

## Events

ThunderPhone adds platform events on top of the realtime protocol. The session
emits them:

```python
@session.llm.session.on("thunderphone_call_ended")  # or on the RealtimeSession you hold
def on_call_ended(event):
    print("call ended:", event["reason"])
```

The `RealtimeSession` exposes `call_id` once the session is live. Use it with
[`GET /v1/calls/{call_id}`](/api-reference/calls) to fetch the recording,
transcript and grade after the call. Every other `call.*` event (transfer,
keypad, speech ignored) arrives as `thunderphone_call_event`.

## Limits

- Turn detection is server-side and always on; framework-side turn detection
  (`turn_detection` on the `AgentSession`) is ignored.
- Instructions and tools cannot change once the call starts.
- Audio is 16-bit mono PCM at 24 kHz in both directions.
- Video frames are ignored.

<Note>
Building on Pipecat instead? See [Use ThunderPhone from Pipecat](/guides/use-with-pipecat).
</Note>

<!-- en: guides/use-with-n8n -->
---
title: "Use ThunderPhone with n8n"
description: "Install the ThunderPhone node for n8n, connect a server API key, and build a workflow that runs every time a call ends."
---

[n8n](https://n8n.io) is a workflow automation tool. The ThunderPhone package
for n8n adds two nodes:

- **ThunderPhone Trigger** starts a workflow when a call ends (**Call
  Completed**) or a call grading run finishes (**Call Graded**).
- **ThunderPhone** places outbound calls, adds contacts to campaigns and
  starts them, gets calls with their transcript and recording, and lists your
  agents and phone numbers.

It is a verified community node, listed at
[ThunderPhone on n8n](https://n8n.io/integrations/thunderphone/).

## Install the node

In the n8n editor, click **+** to open the nodes panel and search for
**ThunderPhone**. An instance owner may need to set up verified nodes before
other users can add them.

On self-hosted n8n, you can also install by package name: open
**Settings > Community Nodes** and install `n8n-nodes-thunderphone`. Check community-node risks and your instance policy
before you install.

## Create a server API key

<Steps>
  <Step title="Open the Keys tab">
    In ThunderPhone, go to **Organization → Keys** and click **Create key**.
  </Step>
  <Step title="Name it">
    Use a name that says where the key lives, such as "n8n".
  </Step>
  <Step title="Copy it now">
    The full `sk_live_...` secret is shown once. Copy it before you close the
    dialog.
  </Step>
</Steps>

Only an admin or owner can create the key, and ThunderPhone treats requests
made with it as coming from that person. The trigger and the campaign
operations need that person to keep the admin or owner role.
[Create a server API key](/guides/api-keys) covers rotation and revocation.

## Add the credential in n8n

1. In n8n, create a credential of type **ThunderPhone API**.
2. Paste the key into **API Key**.
3. Save it and run the credential test. The test reads one call from your
   organization with `GET /v1/calls?limit=1`.

## Build a first workflow

This workflow adds a row to a Google Sheet every time a call ends.

<Steps>
  <Step title="Add the trigger">
    Add **ThunderPhone Trigger**, select your ThunderPhone API credential, and
    set **Event** to **Call Completed**.
  </Step>
  <Step title="Get the call">
    Add a **ThunderPhone** node. Set **Resource** to **Call**, **Operation**
    to **Get**, and **Call ID** to the expression `{{ $json.data.call_id }}`.
    The output is the [call record](/api-reference/calls) plus `transcripts`
    and `recording_url`, a short-lived link that is `null` when the call has
    no recording.
  </Step>
  <Step title="Append a row">
    Add a Google Sheets node that appends a row, and map the columns you want
    from the Get Call output (see the table below).
  </Step>
  <Step title="Activate the workflow">
    Save and activate. The trigger registers its Production URL as a webhook
    endpoint in your ThunderPhone organization. Deactivating the workflow
    deletes that endpoint.
  </Step>
  <Step title="Test it">
    Open an agent in the builder, click **Talk**, and end the call. Builder
    test calls are delivered as `web.complete`, one of the two events behind
    Call Completed, so the workflow runs and a row appears.
  </Step>
</Steps>

Useful columns:

| Column | Expression |
|---|---|
| Call ID | `{{ $json.call_id }}` |
| Direction | `{{ $json.direction }}` |
| From | `{{ $json.from_number }}` |
| To | `{{ $json.to_number }}` |
| Started | `{{ $json.start_time }}` |
| Duration (s) | `{{ $json.duration_seconds }}` |
| Status | `{{ $json.status }}` |
| End reason | `{{ $json.end_reason }}` |
| Call link | `https://app.thunderphone.com/dashboard/call-history/{{ $json.call_id }}` |

The call link opens the call in the ThunderPhone dashboard for members of
your organization, with its transcript and recording, so the sheet does not
need to hold either.

To add the transcript anyway, map
`{{ $json.transcripts.filter(t => typeof t.content === 'string').map(t => t.role + ': ' + t.content).join('\n') }}`.
The recording URL expires, so store the call ID and run Get Call again when
you need a fresh link. Call transcripts, summaries and recordings can contain
personal or health information. Send them only to apps your organization is
allowed to use for that data, under a BAA where health information is
involved, and keep only the fields you need.

<Note>
  ThunderPhone delivers events with `POST` to the trigger's **Production
  URL**, so your n8n instance must be reachable over HTTPS from the internet,
  and the workflow must be active. The trigger verifies the
  `X-ThunderPhone-Signature` HMAC on every request and answers `401` to
  anything unsigned or invalid.
</Note>

The trigger outputs the complete event: `type`, `event_id` and `data`. See
[`telephony.complete` / `web.complete`](/webhooks/call-complete) and
[`call.graded`](/webhooks/events) for every field. Delivery is at least once,
and `event_id` stays the same across retries of one event, so check it before
a step that must not repeat.

## Place outbound calls safely

**Place Outbound Call** (Resource **Outbound Call**, Operation **Place**)
takes:

| Field | Meaning |
|---|---|
| Agent Name or ID | A saved agent. The dropdown lists your agents. |
| Phone Number Name or ID | The from number. The dropdown lists only numbers enabled for outbound calls. |
| To Number | Destination in E.164 format, e.g. `+14155552671`. |
| Variables | JSON object of values for placeholders in the agent prompt. |
| Idempotency Key | A stable ID from the upstream record or event. Required. |

Map the **Idempotency Key** to an ID from whatever caused the run, such as a
CRM record ID or the trigger's `event_id`. The node sends
`n8n:<node ID>:<your value>`, so:

- An automatic retry or **Retry execution** sends the same key, and
  ThunderPhone returns the original call with `idempotent_replay: true`
  instead of dialing again.
- Two ThunderPhone nodes fed the same record send different keys.
- A blank value fails before any request is sent.

Avoid timestamps, random values, and n8n execution or workflow IDs. A new
value on retry places a second real call. The whole key can be at most 128
characters. Reusing a key with a different agent, number or variables fails
with a conflict.

**Campaigns.** **Add Contacts** (Resource **Campaign**) adds contacts to a
draft campaign. It takes a Campaign ID and a JSON array of contacts. Each contact needs `phone_number`; other keys
become call variables. The node fails when every contact is rejected and sets
`partial_success: true` when only some are. **Start** requires the checkbox
confirming that the campaign places real calls and spends ThunderPhone
credits. See [Outbound campaigns](/guides/outbound-campaigns).

Before a workflow starts calls:

- If ThunderPhone asks your organization to confirm that its outbound calls
  follow the TCPA and other calling laws, an admin must record that
  confirmation in the dashboard first.
- The from number must be enabled for outbound calls. Numbers you bring from
  your own carrier qualify once verified. ThunderPhone numbers start
  inbound-only and can be approved for outbound use: an admin requests it
  from the Phone Numbers page. See
  [Get a phone number](/guides/get-a-phone-number).
- Your organization is responsible for having consent to call each number
  and for following the calling laws that apply. See
  [Outbound calling laws](/guides/outbound-calling-laws).

## Example workflows

- **CRM contacts to a campaign.** Add CRM contacts to a draft ThunderPhone
  campaign, then start the campaign once someone approves the list.
- **Completed call to the customer record.** On Call Completed, run Get Call
  and save the transcript and recording link to the matching customer record.
- **Low grades to review.** On Call Graded, filter on
  `{{ $json.data.grade.score }}` and route low-scoring calls to a review queue
  with the call ID and grade details. A call can be graded more than once,
  and each finished grading run fires the trigger, so keep only the latest
  `graded_at` for each call ID.

Call transcripts, summaries and recordings can contain personal or health
information. Send them only to apps your organization is allowed to use for
that data, under a BAA where health information is involved, and keep only
the fields you need.

<Note>
  Sending the same call events to your own server instead? See
  [Webhook endpoints](/webhooks/endpoints).
  [Place outbound calls](/guides/place-outbound-calls) covers the API behind
  Place Outbound Call.
</Note>

<!-- en: guides/use-with-zapier -->
---
title: "Use ThunderPhone with Zapier"
description: "Connect the ThunderPhone app on Zapier to your organization and build a Zap that runs every time a call ends."
---

[Zapier](https://zapier.com) connects apps with automated workflows called
Zaps. The ThunderPhone app on Zapier adds:

- **Triggers:** **Call Completed** fires when a phone, web, or test call ends.
  **Call Graded** fires when a completed call's grade is available.
- **Actions:** **Place Outbound Call**, **Add Contacts to Campaign**, and
  **Start Campaign**.
- **Search:** **Find Call** looks up a call by ID and returns it with its
  transcript and a signed recording URL when one is available.

Find it at [ThunderPhone on Zapier](https://zapier.com/apps/thunderphone/integrations).
For an overview of both ways to use Zapier with ThunderPhone, see the
[Zapier integration page](https://thunderphone.com/integrations/zapier).

## Connect your organization

The app connects through OAuth. You sign in to ThunderPhone and approve
access for one organization, and no API key is copied into Zapier.

<Steps>
  <Step title="Add a ThunderPhone step">
    In the Zap editor, search for **ThunderPhone** (shown with a Beta label)
    and pick a trigger or action. When Zapier asks for an account, connect a new one. Zapier opens
    a ThunderPhone sign-in window.
  </Step>
  <Step title="Sign in and choose the organization">
    Sign in, check the requested permissions, choose the organization, and
    select **Approve**. The app asks to read your agents and phone numbers,
    read and write calls and campaigns, manage integrations such as webhook
    endpoints, and see your account email.
  </Step>
  <Step title="Check the connection name">
    Zapier names the connection after the organization you approved, so you
    can tell connections apart when you belong to more than one.
  </Step>
</Steps>

Connect with an account that has the admin or owner role in that
organization. Turning a trigger Zap on or off, and every action, needs that
role. A trigger Zap that is already on keeps receiving call events after the
role changes or the connection is revoked. Turn it off to stop them. Find
Call works for any member.

The app has no ThunderPhone charge of its own. Calls it places or starts
bill at your normal ThunderPhone rates, and Zapier counts tasks on your
Zapier plan.

## Build a first Zap

This Zap adds a row to a Google Sheet every time a call ends.

<Steps>
  <Step title="Make a call to use as sample data">
    Open an agent in the builder, click **Talk**, and end the call. Builder
    test calls fire Call Completed, so this gives the trigger a recent call to
    load.
  </Step>
  <Step title="Add the trigger">
    Choose **ThunderPhone** as the trigger app, set the event to **Call
    Completed**, and select your ThunderPhone connection. Test the trigger.
    Zapier loads your most recent completed calls as samples, in the same
    shape as a live event.
  </Step>
  <Step title="Add Google Sheets">
    Add a Google Sheets action that creates a spreadsheet row. Pick a sheet
    with a header row, then map each column to a field from the trigger (see
    the table below).
  </Step>
  <Step title="Publish the Zap">
    Publish and turn the Zap on. Turning it on creates a webhook endpoint in
    your ThunderPhone organization named **Zapier: Call Completed**. Turning
    the Zap off deletes that endpoint.
  </Step>
  <Step title="Test it">
    Make another builder test call. When it ends, the Zap runs and a row
    appears.
  </Step>
</Steps>

Useful columns:

| Column | Call Completed field |
|---|---|
| Call ID | Call ID |
| Agent | Agent Name |
| Direction | Direction |
| From | From Number |
| To | To Number |
| Started | Started At |
| Ended | Ended At |
| Duration (s) | Duration in Seconds |
| Status | Status |
| End reason | End Reason |
| Call link | Type `https://app.thunderphone.com/dashboard/call-history/`, then insert Call ID |

The call link opens the call in the ThunderPhone dashboard for members of
your organization, with its transcript and recording, so the sheet does not
need to hold either.

The event can also carry the transcript, as a list of turns, and a Recording
URL, a signed link that expires. Add them only if the sheet needs them. Call
transcripts, summaries and recordings can contain personal or health
information. Send them only to apps your organization is allowed to use for
that data, under a BAA where health information is involved, and keep only
the fields you need. See
[`telephony.complete` / `web.complete`](/webhooks/call-complete) for every
field.

<Note>
  Every delivery is signed. The app checks the `X-ThunderPhone-Signature`
  HMAC against the endpoint's secret before the Zap runs and stops on anything
  unsigned or invalid. If Zapier does not accept a delivery, ThunderPhone
  retries it for up to 24 hours. See [Webhooks overview](/webhooks/overview).
</Note>

## Triggers, actions, and search

**Call Graded** gives the Call ID, Agent ID, Agent Name, and the grade: Grade
ID, Score, Call Outcome, Summary, Grader Model, and Graded At. Turning a Zap
on creates an endpoint named **Zapier: Call Graded**. A call can be graded
more than once, and each finished grading run fires the trigger. See
[`call.graded`](/webhooks/events).

**Find Call** takes a Call ID, with a dropdown of recent calls. It returns
the call's agent, direction, numbers, start and end times, status, end
reason, grade score and call outcome, the transcript, and a signed recording
URL when one is available. An unknown Call ID returns no result instead of an
error.

**Place Outbound Call** takes:

| Field | Meaning |
|---|---|
| Agent | A saved agent. The dropdown lists your agents. |
| To Number | Destination in E.164 format, such as `+14155552671`. |
| From Number | The dropdown lists only numbers enabled for outbound calls. |
| Variables | Optional JSON object of values for placeholders in the agent prompt. |
| Idempotency Key | A stable ID from the trigger or source record. Required. |

It returns the Call ID, Status, and Idempotent Replay.

**Add Contacts to Campaign** adds contacts to a draft campaign. For one
contact, fill **Phone Number** in E.164 format and optionally **Contact
Variables**, a JSON object whose properties become campaign variables. For a
batch, fill **Contacts JSON** with an array of up to 5,000 objects. Each needs
`phone_number`, and its other properties become variables. The step fails
when every contact is rejected, and sets **Partial Success** when only some
are.

**Start Campaign** starts or resumes a campaign that has at least one
contact. It requires **Consent to Charge**. See
[Outbound campaigns](/guides/outbound-campaigns).

## Before a Zap places calls

Place Outbound Call and Start Campaign dial real phone numbers and start
billable calls.

- If ThunderPhone asks your organization to confirm that its outbound calls
  follow the TCPA and other calling laws, an admin must record that
  confirmation in the dashboard before a Zap can start calls.
- The From Number must be enabled for outbound calls. Numbers you bring from
  your own carrier qualify once verified. ThunderPhone-provided numbers start
  inbound-only, and you can request outbound access for them in the
  dashboard. See [Get a phone number](/guides/get-a-phone-number).
- Place Outbound Call requires an **Idempotency Key**. Map a stable ID from
  the trigger or source record, such as the ThunderPhone event ID or a CRM
  record ID. If Zapier retries the step, ThunderPhone recognizes the key and
  returns the original call instead of placing a second one. Avoid
  timestamps, random values, or the Zap ID alone.
- Start Campaign requires **Consent to Charge**, which confirms the Zap may
  start billable outbound calls on your account.
- Your organization is responsible for having consent to call each number
  and for following the calling laws that apply. See
  [outbound calling laws](/guides/outbound-calling-laws).

An idempotency key is unique across your organization and can be at most 128
characters. Reusing a key with a different agent, number, or variables fails
with a conflict, so if two Zaps can call about the same record, give each Zap
its own fixed prefix before the record ID.
[Place outbound calls](/guides/place-outbound-calls) covers the API behind
this action.

## Example Zaps

- **Call Completed to a CRM.** Log an activity for each finished call with
  its status, end reason, and transcript.
- **Call Graded to follow-up.** Filter on the call outcome or score and route
  the call into the right follow-up workflow.
- **New lead to a campaign.** Add the lead to a draft campaign with Add
  Contacts to Campaign, then run Start Campaign once someone approves the
  list.

Call transcripts, summaries and recordings can contain personal or health
information. Send them only to apps your organization is allowed to use for
that data, under a BAA where health information is involved, and keep only
the fields you need.

## Troubleshooting

**A step fails with an authorization error.** Reconnect the ThunderPhone
connection in Zapier and approve again. A connection stops working when the
person who connected revokes it in ThunderPhone under **Organization → Keys →
Authorized apps**, when that person changes or resets their password or
changes their account email, when that person leaves the organization, or
when it goes 30 days without a successful token refresh. See
[Connect with OAuth](/guides/oauth).

**Turning a Zap on or off fails, or an action is refused.** The person who
connected needs the admin or owner role in the organization. Reconnect with
an account that has it. A trigger Zap that is already on keeps receiving call
events after the role changes or the connection is revoked. Turn it off to
stop them.

**You want to disconnect the app.** Turn off your ThunderPhone Zaps before
you revoke the connection, since turning a Zap off deletes its endpoint and
needs a working connection. If you revoked first, delete the leftover
**Zapier: …** endpoint with `DELETE /v1/developer/webhook-endpoints/{id}`
using an admin API key. See [Webhook endpoints](/webhooks/endpoints).

**The Zap should use a different organization.** Each connection covers one
organization. Turn the Zap off first, so its webhook endpoint is deleted from
the current organization. Then connect a new ThunderPhone account in Zapier,
choose the other organization when you approve, and select that connection
on each ThunderPhone step. Agents, numbers and campaigns differ between
organizations, so pick **Agent**, **From Number** and **Campaign** again on
each step that has them. Then turn the Zap back on.

**The trigger stopped firing.** Each Zap with a ThunderPhone trigger owns one
webhook endpoint in your organization, named **Zapier: Call Completed** or
**Zapier: Call Graded**. It is created when the Zap turns on and deleted when
it turns off. Leave it as it is. If it was edited or deleted in ThunderPhone,
turn the Zap off and on again to create a fresh one.
With an admin API key,
[`GET /v1/developer/webhook-deliveries`](/api-reference/webhook-deliveries)
shows recent delivery attempts.

<Note>
  Want the agent to use Zapier actions during a call instead of after it?
  Connect a Zapier MCP endpoint under **Connections → MCP**. See
  [MCP servers](/guides/mcp-servers). To send the same call events to your
  own server, see [Webhook endpoints](/webhooks/endpoints).
</Note>

<!-- en: guides/voip-providers -->
---
title: "Connect a VoIP provider"
description: "Connect a provider you already use (Twilio or Telnyx by API key; SignalWire, Vonage, Plivo or any SIP trunk over SIP), or open a new Telnyx account with guided setup."
---

Production traffic should run on numbers you own through your own
VoIP provider. The dashboard's **Connections → VoIP** page
(`/dashboard/voip-connections`) connects your provider account; once
connected, you import numbers that support inbound **and outbound**
calling.

Click **New connection** and pick one of two routes: **Connect a
provider you already use**, or **Set up a new Telnyx account**.

## Connect a provider you already use

Pick the provider your numbers are with:

| Provider | How it connects |
|----------|-----------------|
| Twilio | API key: paste your Account SID and Auth Token |
| Telnyx | API key: paste your v2 API key |
| SignalWire | SIP setup |
| Vonage | SIP setup |
| Plivo | SIP setup |
| Other provider | SIP setup with ThunderPhone's setup assistant, for any other carrier or a PBX you run |

For Twilio and Telnyx, paste the credentials and click **Connect &
Test**. ThunderPhone verifies them and configures the provider side
for you.
For Telnyx, ThunderPhone adds one SIP connection of its own to your
Telnyx account (named `thunderphone-production-<org>-outbound-<id>`) and places
outbound calls through it, so Telnyx bills those calls to you. It uses
the outbound voice profile of the Telnyx connection your numbers are
on, so that profile's allowed countries and spend limits apply. If that
connection has no outbound voice profile and your account has exactly
one enabled profile, ThunderPhone uses that one. To use a different one,
assign it to the connection in the Telnyx portal and save the ThunderPhone
connection again. If the account has no enabled profile,
or several, assign one to the connection in the Telnyx portal and save
the ThunderPhone connection again. Until then, outbound calls fail with
`outbound_trunk_unavailable`; inbound calls keep working.

When Telnyx refuses an outbound call (for example SIP 403 Forbidden),
the refusal comes from your own Telnyx account. The usual causes are no
available credit, a caller number that is not on that Telnyx account,
or an outbound voice profile that does not allow the destination
country.

### SIP setup for SignalWire, Vonage and Plivo

These three open the [manual SIP form](#manual-sip-configuration) with
the steps for that provider at the top, a link to the provider's own
setup guide, and an example SIP domain:

- **SignalWire:** create SIP credentials for outbound calls, enter the
  SIP domain, username and password, and give each number a SWML script
  that connects incoming calls to the ThunderPhone SIP endpoint.
- **Vonage:** in the SIP Trunking dashboard, create a trunk with
  outbound credentials, enter its domain (for example
  `your-trunk.sip-us.vonage.com`) and the credentials, add the
  ThunderPhone SIP endpoint as the trunk's inbound SIP URI, and link
  your numbers to the trunk.
- **Plivo:** create an outbound trunk with a credential and enter its
  Termination SIP Domain (`<trunk-id>.zt.plivo.com`), username and
  password; create an inbound trunk whose Primary URI is the
  ThunderPhone SIP endpoint followed by `;transport=tcp`; then set each
  number's Application Type to that trunk.

The result is a manual SIP connection (`provider: "manual"` in the
API), tested and verified exactly like one entered by hand. The
connection card shows the provider's name, for example
**SignalWire · SIP**.

## Set up a new Telnyx account

No provider yet? The guided flow walks you through opening a Telnyx
account and connecting it:

<Steps>
  <Step title="Create the account">
    Click **Open Telnyx Signup**, create your account, and check
    "I've created my account."
  </Step>
  <Step title="Get an API key">
    Click **Open API Keys Page**, generate a key, and paste it into
    **API Key (v2)**. Optionally name the connection.
  </Step>
  <Step title="Connect & Test">
    Click **Connect & Test** — ThunderPhone verifies the credentials
    and provisions what it needs on the Telnyx side before saving.
  </Step>
</Steps>

### What ThunderPhone sets up in Telnyx

Unless you enter your own Connection ID, both Telnyx routes (guided
setup and pasting an API key) leave the same thing in your Telnyx
account: one SIP connection named
`thunderphone-<your organization id>`. It is an **FQDN connection**
whose FQDN record points at ThunderPhone's SIP endpoint, and every
number you import is assigned to it. Telnyx sends calls for those
numbers straight to ThunderPhone over SIP.

- Its webhook fields are empty on purpose. No webhook, Call Control
  application, TeXML application or registered SIP phone is involved.
- Don't move imported numbers to another connection or application,
  and don't register a device against it.
- If you entered your own Connection ID when connecting, ThunderPhone
  uses that connection instead and never changes it; it must be an FQDN
  connection pointing at the ThunderPhone SIP endpoint.

Before August 30, 2026, the `thunderphone-…` connection ThunderPhone
created was a **Credential connection**, which cannot receive calls.
If yours still shows as a Credential connection, contact support and
we will convert it.

## Manual SIP configuration

The SignalWire, Vonage and Plivo tiles open this form, and so does
**I'll enter every setting myself** under **Other provider**. Any SIP trunk works, including DIDWW or a PBX you run
yourself. Enter the connection name, **SIP domain / URI**,
optional username and password, port, and transport; **Advanced
Settings** adds media encryption (SRTP). The form also shows the SIP
address your trunk must send inbound calls to: `sip.thunderphone.com`,
on port 5060 for UDP or TCP, or 5061 for TLS. Over TLS, the SIP
signaling stays encrypted all the way to LiveKit Cloud, where
ThunderPhone handles the call; audio never passes through
`sip.thunderphone.com`, so SRTP works as before. Address each call to
the dialed number in E.164 form, with the same number, including the
`+`, in both the request line and the `To` header: for example
`sip:+14155550142@sip.thunderphone.com`. The `+` is what lets
ThunderPhone handle the call in the right region (see the note under
[IP allowlisting](#ip-allowlisting-and-trunk-authentication)).
Trunks set up earlier with a `<your-project>.sip.livekit.cloud`
address keep working while **Allowed Source IPs** is empty; you don't
need to change them. ThunderPhone
turns those settings into a dedicated pair of SIP trunks on LiveKit
Cloud: outbound calls
from the connection's numbers are placed to your SIP domain with your
credentials, and inbound calls to those numbers are accepted from any
address unless you fill in the optional **Allowed Source IPs** field.
Only fill it in if your carrier publishes fixed signaling IPs: a wrong
or incomplete list makes ThunderPhone reject your carrier's incoming
calls. Two buttons do the heavy lifting:

- **Generate AI Setup Guide** — writes provider-specific instructions
  for the trunk-side configuration you need.
- **Test & Save Connection** — checks that the SIP endpoint resolves
  to a public address and, for TCP/TLS, accepts a connection on the
  chosen port (UDP hosts get the DNS check only), then saves. It cannot
  place a call yet because the connection has no numbers; the real
  proof comes at import time (below).

Editing a connection later re-runs the same check on your changed
settings before anything is saved, then rebuilds the trunk and
re-verifies every number on the connection with a short test call in
the background — the numbers show as *Provisioning* until their test
call succeeds. Changing only **Allowed Source IPs** on a *Connected*
connection is different: it never affects outgoing calls, so
ThunderPhone updates the list on the inbound trunk right away and the
numbers stay *Active*. Their incoming call test resets to *not tested*;
run it again, or place a real call through your carrier, to confirm the
new list lets calls in. The test fails when its call would be refused
under the list. Stored passwords are never shown back; leave the
password blank to keep it, or tick "Remove the stored password" for an
IP-authenticated trunk.

### IP allowlisting and trunk authentication

Some carriers (DIDWW, Telnyx IP-auth connections, most PBXs behind a
firewall) only accept SIP traffic from addresses you allowlist, or
authenticate outbound calls by source IP. ThunderPhone uses two sets of
addresses.

**SIP edge.** Inbound calls you send to `sip.thunderphone.com` go
through ThunderPhone's SIP edge, which carries SIP signaling only. The
first INVITE goes to `sip.thunderphone.com`; the rest of the call's
signaling (ACK, hang-up, transfers) runs between your carrier and the
edge server that took the call, `sip-1` or `sip-2`. If your firewall
filters SIP signaling, allow all three, on UDP and TCP port 5060 and
TLS port 5061:

| Host | IP address |
|------|------------|
| `sip.thunderphone.com` | `172.170.39.202` |
| `sip-1.thunderphone.com` | `13.86.104.121` |
| `sip-2.thunderphone.com` | `20.80.98.90` |

**LiveKit Cloud.** The audio (RTP) of every call, and the SIP signaling
of outbound calls, run between your carrier and LiveKit Cloud, never
through the SIP edge. Allow **every** range below, for both SIP
signaling and media:

{/* generated:livekit-static-ips:start */}
{/*
  GENERATED BLOCK — do not edit by hand.
  Source: scripts/docs-freshness/data/livekit-static-ips.json
  Regenerate: python3 scripts/docs-freshness/generate_livekit_static_ips.py
  CI regenerates this block and fails on drift
  (scripts/docs-freshness/generators.d/30-livekit-static-ips.sh).
*/}

| IP range |
|----------|
| `143.223.88.0/21` |
| `161.115.160.0/19` |
| `153.57.128.0/18` |

LiveKit applies these ranges to Realtime, SIP signaling and media and Webhooks, and they cover calls handled in its Canada, EU, India, Japan and US regions. Region names for a pinned endpoint: `canada`, `eu`, `india`, `japan`, `us`.
{/* generated:livekit-static-ips:end */}

<Note>
  Calls sent to `sip.thunderphone.com` are handled in a covered region.
  A number with a leading `+` in the `To` header and a Japanese, Indian,
  EU/EEA, UK or Swiss country code goes to that region. Every other call
  is handled in the LiveKit region nearest ThunderPhone's SIP edge,
  currently the US. A trunk that still points at a `<your-project>.sip.livekit.cloud`
  address is routed through the LiveKit region nearest the caller, which
  can be outside the covered regions if your carrier is. Move it to
  `sip.thunderphone.com`, or pin it by inserting a region name just
  before `.sip.livekit.cloud`: for example
  `<your-project>.japan.sip.livekit.cloud`. Inbound number matching is
  unaffected.
</Note>

A few rules of thumb for the trunk itself:

- **ThunderPhone does not register.** It never sends SIP `REGISTER` to
  your carrier, so configure the trunk for IP-based and/or credential
  (username + password) authentication, not registration.
- **Outbound calls should use credentials.** Enable username/password
  authentication on the carrier side and enter the same values in the
  manual SIP form. Treat the IP allowlist as a second layer, not the
  only one — outbound calls to destinations outside the covered regions
  may originate from other addresses.
- **Inbound is the reverse direction.** The optional **Allowed Source
  IPs** field in the form is where you enter *your carrier's* signaling
  addresses so ThunderPhone only accepts calls from them. Enter IP
  addresses or CIDR ranges; hostnames never match. Leave it blank
  unless your carrier publishes a fixed list. ThunderPhone checks the
  list on every inbound call against the address its SIP edge sees, so
  once the list is set, send your calls to `sip.thunderphone.com`. A
  call from an address not on the list, or one sent straight to a
  `<your-project>.sip.livekit.cloud` address, is refused: it fails or
  connects and ends straight away.

The ranges are published by LiveKit at
[Regions, regional endpoints, and static IPs](https://docs.livekit.io/deploy/admin/regions/endpoints/);
ThunderPhone checks that page weekly and updates this guide when it
changes.

## After connecting

Import numbers from **Phone Numbers → Add number → Connect VoIP
provider** (or straight from the connection). Each imported number is
verified before it goes active. For a manual SIP connection that
verification places a short (a few seconds) test call **from your
number, through your SIP trunk, to a ThunderPhone number** — so the
username, password, transport and your carrier's outbound routing are
all exercised for real. Your carrier bills that call like any other.
If the carrier rejects it, the number stays in *Provisioning* and the
phone-numbers page shows the carrier's answer (for example "rejected
ThunderPhone's credentials (SIP 401)"); fix the connection and verify
again. If your carrier accepts the trunk but its routing plan does not
cover ThunderPhone's test number (DIDWW answers "Destination number
blacklisted by routing plan"), the number shows as *Verified · carrier
accepted*: it is usable, but calls to other destinations were not
tested. That call proves your trunk can *place* calls as the number; it
is not proof that you own the number, and it does not test calls *to*
the number; the optional incoming test below does.

Manual SIP numbers **outside the US and Canada** verify differently: the
number calls *itself* through your SIP trunk. That is a domestic call, so
a trunk barred from international calls can still verify. If your
inbound routing points at ThunderPhone, the call comes straight back and
ThunderPhone hangs it up before anything answers it; that one call proves
calls work both ways, and the number's incoming test is recorded as
passed too. If the number's calls go somewhere else, that phone may ring
for up to 25 seconds; if something answers it, outgoing calls still count
as verified. If your carrier refuses the self-call in a way that says
nothing about your account (busy, no route to the number, no answer),
ThunderPhone calls its own test number instead. A refusal that comes
after a long pause usually means your provider played a recorded message
first, such as no credit or a blocked destination; the reason says so.
Verified numbers
support inbound and outbound — which unlocks
[outbound campaigns](/guides/outbound-campaigns) and programmatic
[outbound calls](/guides/place-outbound-calls).

### Incoming call test

**Verify number** opens a dialog that can also test incoming calls. The
test places a call to your number, checks that the call reaches
ThunderPhone, then hangs up without starting your agent:

- **Numbers with their own outbound SIP trunk** (manual SIP numbers, and
  Twilio numbers once ThunderPhone has set up outbound calling in your
  Twilio account) first call themselves: ThunderPhone dials the number
  from the number, through that trunk. The dialog tells you before it
  places the call. The call goes out through your carrier and, if your
  inbound routing is right, comes straight back to ThunderPhone. When it
  comes back under the number's own caller ID, that one call proves both
  that your carrier accepts ThunderPhone's calls as the number and that
  calls to the number reach ThunderPhone, in any country. Some carriers
  refuse or don't connect a call from a number to itself; that says
  nothing about your routing, so ThunderPhone then calls from one of its
  own numbers instead. If your number forwards somewhere else, that phone
  may ring twice: first showing the number's own caller ID, then
  ThunderPhone's test number. Outside the US and Canada nothing can follow
  the self-call, so it rings once, for up to 25 seconds.
- **Other numbers** (and the fallback above) are called from one of
  ThunderPhone's own numbers. ThunderPhone can only place these calls to
  US and Canadian numbers for now; for other numbers the test reports
  that it couldn't run, with your carrier's answer if the self-call was
  refused.

If your carrier changes the caller ID on the way, ThunderPhone can't
recognise the call, so your agent may answer it for a moment. The
incoming test is optional. Skip it and the number still works; the
phone-numbers page then shows *Incoming not tested*, and you can run it
later with **Test** or the number's **Test incoming calls** menu item.
Right after an import, the phone-numbers page also asks you to test
incoming calls on the new numbers. Nothing is dialed until you confirm in
the dialog.

If your provider sends the number somewhere else, whatever it points at
may ring for up to 8 seconds per call before ThunderPhone hangs up. If
something answers first (a Twilio app that answers and then forwards, a
phone menu), the test waits for the forwarded call to reach ThunderPhone:
up to 8 seconds on the self-call and 15 seconds on a call from a
ThunderPhone number. The result stays on the number (*Incoming* passed or
failed) until you change the connection or re-import the number, which
resets it to *not tested*. Changing a connection re-verifies outgoing
calls in the background but never calls your number unasked.

## Troubleshooting inbound calls

The connection's **Test** button checks credentials, and verification
checks outbound dialing. To check inbound, run the incoming call test
above, or call the number from a phone and look for the call in
**Call History**.
Browser **Talk** tests and bot-to-bot simulations don't go through
your carrier, so they don't show whether inbound works. A simulation
that targets the phone number (SIP loopback) does dial it through your
carrier, so an answered one does exercise inbound routing.

- **You hear your own mobile carrier's message** (for example "Welcome
  to Verizon" or "the number you have dialed is not in service"): the
  call failed before it reached ThunderPhone. Check that the number is
  active in your provider account and assigned to the ThunderPhone
  connection or trunk.
- **Busy signal or the call rings out:** the provider accepted the call
  but could not deliver it. With Telnyx, check the number's
  **Connection** in the Telnyx portal: it should be the
  `thunderphone-…` FQDN connection described above, or your own FQDN
  connection pointing at the ThunderPhone SIP endpoint. With Twilio, the
  number should be attached to the ThunderPhone SIP trunk rather than a
  Voice webhook or TwiML app.
- **Your carrier's logs show `404 No trunk found`** (manual SIP): the
  call reached ThunderPhone but matched no trunk. Check that the number
  is imported on this connection and that the trunk points at
  `sip.thunderphone.com`. If it points at a
  `<your-project>.sip.livekit.cloud` address, **Allowed Source IPs**
  must be empty: with a list set, only calls sent to
  `sip.thunderphone.com` are accepted.
- **`404 Not Found` from `sip.thunderphone.com`** (manual SIP): the
  call was not addressed to a phone number, or the request line and the
  `To` header name different numbers. Send the dialed number in both,
  as above.
- **`403 Forbidden` from `sip.thunderphone.com`:** the request line
  names another host. Address the call to `sip.thunderphone.com`, for
  example `sip:+14155550142@sip.thunderphone.com`.
- **The call reaches ThunderPhone but the wrong agent answers, or
  nobody does:** check the number's inbound agent on **Phone Numbers**.

The in-app copilot can check a number for you: ask it why calls to
the number fail. For Telnyx connections it also looks up, read-only and for
organization admins, which connection Telnyx assigns the number to.

---

## Next steps

<CardGroup cols={2}>
  <Card title="Get a phone number" icon="phone" href="/guides/get-a-phone-number">
    The full add-a-number flow, ThunderPhone numbers and VoIP.
  </Card>
  <Card title="Bring your own numbers (API)" icon="code" href="/guides/bring-your-own-numbers">
    The same connect-import-verify flow over REST.
  </Card>
  <Card title="Run outbound campaigns" icon="megaphone" href="/guides/outbound-campaigns">
    CSV lists, calling windows, and retry policy.
  </Card>
  <Card title="VoIP connections reference" icon="phone-volume" href="/api-reference/voip-connections">
    Every field on connections, evidence, and imports.
  </Card>
</CardGroup>

<!-- en: guides/reports -->
---
title: "AI reports"
description: "Ask questions in plain English and get a report built from your actual call transcripts — funnels, drop-offs, and answers."
---

The **Reports** page (`/dashboard/reports`) under **Quality & Testing**
turns call transcripts into analysis. Pick the agents and date range,
optionally ask specific questions, and the AI reads the calls in scope
and reports back — call funnel, where callers drop off, recurring
patterns, and direct answers to whatever you asked.

## Generate a report

<Steps>
  <Step title="Scope it">
    Choose one or more **agents** and a **date range** — last 7/30/90
    days, all time, or custom dates. Selecting several agents produces a
    comparison report.
  </Step>
  <Step title="Ask your questions (optional)">
    Add anything specific you want answered, up to 2,000 characters —
    e.g. *"How often do callers ask about pricing? Did the July script
    change help?"* Suggestion chips cover common asks like "Where do
    callers drop off, and why?" and "Compare my agents against each
    other."
  </Step>
  <Step title="Exclude noise (optional)">
    Under **Exclude numbers from analysis**, toggle off labeled numbers
    (your own team's test lines, for instance) or paste numbers to
    exclude.
  </Step>
  <Step title="Click Generate report">
    Generation takes a few minutes for large call volumes. The report
    analyzes up to the **200 most recent calls** in scope.
  </Step>
</Steps>

## Quota

Reports are limited to **3 per organization per calendar month**. The
composer shows how many you have left and when the quota resets (the
1st of the next month). Spend them on well-scoped questions — a report
with a specific ask beats a generic one.

## Reading and reusing reports

Generated reports are saved on the page. Open one to see the call
funnel, metrics, distributions, and the answers to your questions. From
a report you can:

- **Re-run** it on a new date range with the same agents, questions,
  and exclusions — the quickest way to track a change over time.
- **Chat in your AI instead** — export the underlying data and continue
  the analysis in ChatGPT, Claude, or Gemini. Exports don't count
  against your report quota.

## Next steps

<CardGroup cols={2}>
  <Card title="Observability" icon="chart-line" href="/guides/observability">
    Live operational metrics — the numbers behind the narrative.
  </Card>
  <Card title="Issues" icon="triangle-exclamation" href="/guides/issues">
    Triage the recurring problems reports surface.
  </Card>
</CardGroup>

<!-- en: guides/observability -->
---
title: "Observability"
description: "Runtime metrics for your agents — volume, success rate, failures, and the calls behind every number."
---

**Observability** (`/dashboard/observability`, under Quality & Testing)
is the operational view of your calls: how many, how successful, what's
failing, and which agent is responsible. Where [Reports](/guides/reports)
answers questions in prose, Observability gives you the live numbers.

## Scope the view

Two filters at the top drive the whole page:

- **Time window** — last hour, 6, 24, or 72 hours, 7 days, or 30 days.
  Charts bucket hourly for short windows and daily from 48 hours up.
- **Agent** — all agents or a single one.

For very busy windows, detailed metrics are sampled from the most
recent calls; a notice tells you when that happens and how many calls
the sample covers.

## What you get

**Summary cards** — Calls, Success Rate (based on AI grading, with
infrastructure errors excluded from the denominator), Unsuccessful, No
Conversation (caller disconnected early), Errors (infrastructure
failures), In Progress, and Average Duration.

**Charts** — call volume over time and the success-rate trend, bucket
by bucket.

**Call status breakdown** — successful / unsuccessful / no conversation
/ error as proportions of the window.

**Agent performance** — a per-agent table of calls, failed calls,
issues raised, and average grade. Sort out which agent is dragging the
success rate before you start editing prompts.

**Recent failed calls** — each with its end reason ("Caller hung up",
"No answer", "Call failed", …) and an **Open call** button straight into
the transcript and recording.

**Bucket details** — the raw per-bucket table: calls, successes,
errors, success rate.

## Export

The **Export** button downloads the current window's full observability
payload as JSON — handy for piping into your own dashboards or handing
to an analysis tool.

<Tip>
  Don't watch this page for regressions by hand — create an
  [alert rule](/guides/alerts) on success rate, failure rate, or call
  volume and get emailed/Slacked when a threshold breaks.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Alerts" icon="bell" href="/guides/alerts">
    Threshold alerts on the same metrics.
  </Card>
  <Card title="Review calls" icon="waveform-lines" href="/guides/review-calls">
    Drill from a number into the actual conversations.
  </Card>
</CardGroup>

<!-- en: guides/experiments-ab-testing -->
---
title: "Experiments (A/B testing)"
description: "Run two agent configurations side by side on real calls and let the success rates pick the winner."
---

A/B testing answers "is the new prompt actually better?" with data
instead of vibes: incoming calls are split between agent **variants**,
each call is graded as usual, and you compare success rates per variant.

There are two surfaces:

- **Per agent** — tests are configured and tuned in each agent's
  builder, on its **A/B** tab (`/dashboard/agents/<id>?tab=variants`).
  That's where variants are created and the test is switched on.
- **Cross-agent overview** — the **Experiments** page
  (`/dashboard/experiments`, under Quality & Testing) aggregates every
  agent's test into one table.

## Set up a test

From the Experiments page, click **Set up an A/B test** and pick an
agent — you land on that agent's A/B tab, where you create the variant
configurations (one is marked **control**) and enable split testing.
See [Build an agent](/guides/build-an-agent) for the builder itself.

## Read the overview

For each agent with a test, the Experiments table shows:

- **Status** — Active (split testing on) or Paused.
- **Variants** — every variant as a chip, with the control labeled.
- **Leading** — the variant with the best success rate so far, with its
  percentage. Until variants have graded calls, this reads *Not enough
  data yet* — don't crown a winner off a handful of calls.
- **Calls** — total calls across the test's variants.

Agents without a test are listed underneath as one-click nudges to
start one. Clicking any row jumps to that agent's A/B tab to tune or
conclude the test.

<Tip>
  Which variant handled a call is recorded on the call itself, so you
  can filter and spot-check each side's transcripts in
  [call history](/guides/review-calls).
</Tip>

<Note>
  Prefer this built-in feature over hand-rolling A/B assignment in a
  [dynamic config webhook](/guides/dynamic-call-config) — you get
  assignment, per-variant stats, and grading for free.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Build an agent" icon="robot" href="/guides/build-an-agent">
    Create variants on the agent's A/B tab.
  </Card>
  <Card title="Simulations" icon="flask" href="/guides/test-agents">
    Pre-ship testing with AI callers, before real traffic votes.
  </Card>
</CardGroup>

<!-- en: guides/issues -->
---
title: "Issues"
description: "Recurring call problems, grouped into patterns you can triage — and fix with AI help."
---

The **Issues** page (`/dashboard/issues`, under Quality & Testing)
collects problems detected across your calls and groups repeat
occurrences into **patterns**, so fifty instances of "agent quoted the
wrong hours" show up as one row with a trend line — not fifty separate
reports.

## Where issues come from

- **System** — raised automatically by ThunderPhone's call analysis
  when it detects something going wrong on a call.
- **User** — raised by people: reported from a call's detail page or
  filed via the [issue reports API](/api-reference/issue-reports).

Each issue has a **severity** — Critical, Warning, or Info.

## Triage

Every pattern row shows its severity, an occurrence **trend**
sparkline, the number of affected **calls**, its **status**, and when
it was last seen. Statuses:

| Status | Meaning |
| --- | --- |
| **Open** | Needs attention — the default view shows only these. |
| **Dismissed** | Acknowledged; not being acted on. |
| **Resolved** | Fixed. New occurrences push a pattern back to the top. |

Change a pattern's status inline from its status control, or select
several rows (including "all matching") and update them in bulk.

Filter pills mirror the columns: **Status** (defaults to Open),
**Severity**, **Source**, free-text **Search** (title, trace, or call
ID), and a **Date** range — plus **Reset filters**.

## Dig into a pattern

Click a row to open the detail panel: the pattern's description, its
occurrence history, and the affected calls, each linking to the full
transcript in call history so you can see the failure in context.

### Fix with AI

Fix with AI needs recorded audio from at least one affected call. Calls made
while recording was disabled cannot be replayed. The investigation replays
stored turns; it does not place live calls or create billable simulation calls.

From the detail panel, **Fix with AI** checks whether the problem still
reproduces, then tests focused prompt changes against the affected turns and
clean comparison calls. The result shows the before-and-after replay rate,
detected side effects, and whether the issue was **Fixed** or **Improved**. You
review the winning redline before applying it. Leave the page at any time;
**Resume fix** returns to the saved investigation.

Nothing is applied automatically:

- **Apply fix** stages the prompt change in the agent's draft.
- **Apply & deploy** stages the change and deploys it immediately.

Both actions preserve unrelated draft edits. Until you deploy, the current
deployed prompt remains live.

If the audio cannot be reconstructed, the investigation ends as **Not
replayable**. If the issue no longer appears, it ends as **Not reproducible**.
It also stops without changing the agent when its replay budget ends before
confirmation.

ThunderPhone applies the change only when it can still find exactly one
unchanged match for the prompt section that was tested. Unrelated draft edits
are preserved. If that section changed or matches more than one place, apply
reports a conflict. Rerun the investigation against the current prompt before
applying it. See the [Investigations API
reference](/api-reference/investigations) for the complete status and replay
objects.

### Report to ThunderPhone

When the investigation finds no safe prompt fix, select **Report to
ThunderPhone**. ThunderPhone also routes some unresolved investigations
automatically. If you use organization-wide webhooks, the `issue.escalated`
event tells you that an issue pattern was reported and whether the report was
automatic. [Configure issue webhooks](/webhooks/events#issue-escalated).

## Next steps

<CardGroup cols={2}>
  <Card title="Alerts" icon="bell" href="/guides/alerts">
    Get notified when quality metrics slip, before issues pile up.
  </Card>
  <Card title="Simulations" icon="flask" href="/guides/test-agents">
    Turn a fixed issue into a regression test scenario.
  </Card>
</CardGroup>

<!-- en: guides/alerts -->
---
title: "Alerts"
description: "Threshold rules on your call metrics — delivered to email, Slack, or your webhooks the moment something slips."
---

Alert rules watch your organization's call metrics and notify you when
a threshold is crossed — success rate below 80% over the last day,
more than 500 calls in an hour, a test suite regression. Manage them
under **Settings → Organization → Alerts**
(`/dashboard/organization?tab=alerts`). Managing alert rules requires
an **admin** or **owner** role.

## Create a rule

Click **Create rule** and fill in:

| Field | Options |
| --- | --- |
| **Metric** | Success rate · Failure rate · Average score · Call volume · Suite regressions |
| **Condition** | is less than · is at most · is greater than · is at least |
| **Threshold** | The number to compare against |
| **Window (hours)** | How far back the metric is computed — 1 to 720 hours |
| **Email recipients** | Comma-separated, up to 10 addresses |
| **Slack incoming webhook URL** | Optional — posts the alert message to a channel |
| **Cooldown (minutes)** | Minimum quiet time between firings (default 60) |
| **Deliver to developer webhooks** | Also send an `alert.triggered` event to your webhook endpoints |
| **Enable alert rule** | Rules can be saved disabled and switched on later |

Example: *"Success rate **is less than** 80 over the last 24 hours"*
fires when graded calls in the trailing 24-hour window dip below an 80%
success rate.

<Note>
**Failure rate counts more than "Unsuccessful" calls.** The alert metric
treats every call that didn't reach a successful outcome — including calls
with no conversation at all (immediate hang-ups, failed connections) — as a
failure. The dashboard's **Unsuccessful** tile counts only calls graded
`unsuccessful`. A failure-rate alert can therefore fire even when the
dashboard tile shows a low number; that's expected, not a discrepancy.
</Note>

## How firing works

Rules are evaluated against the trailing window you configured. When
the condition is met, the rule fires **once** and then stays quiet for
its cooldown period, even if the metric remains in breach — so a bad
hour produces one page, not a page per evaluation. Each firing records
the metric value, threshold, and time.

## Delivery channels

A single rule can notify on all three channels at once:

- **Email** — a message to every listed recipient naming the rule,
  metric, value, threshold, and window.
- **Slack** — the same message posted via your Slack incoming webhook
  URL.
- **Developer webhooks** — an `alert.triggered` event delivered to your
  organization's [webhook endpoints](/webhooks/overview), for wiring
  alerts into PagerDuty, on-call tooling, or your own systems.

One channel failing never blocks the others.

## Manage rules

The Alerts tab lists every rule with its enabled/disabled state and
when it last triggered. Toggle rules on and off in place, **Edit** to
change any field, or delete rules you no longer need. Recent alert
activity is shown alongside so you can confirm a rule actually fires
the way you expect.

## Next steps

<CardGroup cols={2}>
  <Card title="Observability" icon="chart-line" href="/guides/observability">
    The dashboards behind the same metrics.
  </Card>
  <Card title="Webhooks" icon="webhook" href="/webhooks/overview">
    Receive alert.triggered (and every other event) in your own systems.
  </Card>
</CardGroup>

<!-- en: guides/organization-settings -->
---
title: "Organization settings reference"
description: "Manage a ThunderPhone organization: profile, dashboard language, members, outbound confirmation, blocked callers, webhooks, SSO, API keys, alerts, billing, spending limits, and history."
---

Open **Organization Settings** (`/dashboard/organization`) to manage the active
organization and your own account. Settings are split into six tabs; your role
determines which controls you can change.

## My account

The **My account** tab contains settings for the signed-in user, not the whole
organization:

- First name, last name, email, and an avatar URL.
- Dashboard display language.
- macOS desktop app download.
- Add, verify, list, and remove passkeys.
- Cookie preferences.
- Sign out on the current device.

When you sign in through organization SSO, the identity provider manages your
email and it is read-only here. See [Account & security](/guides/account-and-security)
for the detailed passkey and profile workflow.

## General

### Outbound calling compliance

For organizations where the requirement applies, an owner or admin must review
and record the one-time outbound-calling confirmation before agents can place
outbound calls. Members can see that action is required but cannot submit it.
See [Outbound calling laws](/guides/outbound-calling-laws).

### Reporting

Time zone, weekly business hours and the organization's own test numbers.
Business hours decide which calls count as after hours in the call
report numbers on Home, in each agent's **Calls** tab and in Client
Portals, and the **Business hours** filter in Call History. With no days
checked, after-hours calls are not tracked and every call counts as
business hours. Calls from or to a test number are left out of every report
count, and out of portal lists, Overview numbers and CSV exports; they
cannot be opened in a portal. An agent can carry its own time zone and
hours under **Reporting** in the agent builder, which then apply to that
agent's calls only.

Owners and admins change these settings under **General → Reporting**.
Choose the time zone and check each open day, then enter its opening and
closing times. Under **Test numbers**, enter each number and choose
**Add**. Then choose **Save reporting settings**. Until a time zone is
saved, reports use UTC; the page suggests your browser's zone as an unsaved
change. Once any business hours are set, unchecked days count as after
hours for calls using that schedule.

#### Configure reporting through the API

Owners and admins can `PATCH /v1/orgs/{id}/` with `timezone`,
`business_hours` and `excluded_numbers`:

- `timezone`: an IANA time zone name such as `America/Los_Angeles`, up to
  64 characters.
- `business_hours`: weekday keys `mon` through `sun`, each a list of at
  most four `{start, end}` windows in 24-hour `HH:MM`, with each end later
  than its start. `{}` means no after-hours split.
- `excluded_numbers`: up to 50 phone numbers, stored in E.164 form. A bare
  10-digit North American number gets the `+1` country code.

```bash
curl -X PATCH https://api.thunderphone.com/v1/orgs/42/ \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timezone": "America/Los_Angeles",
    "business_hours": {
      "mon": [{"start": "09:00", "end": "17:00"}],
      "sat": [{"start": "10:00", "end": "14:00"}]
    },
    "excluded_numbers": ["+14155550199"]
  }'
```

### Blocked callers

Numbers on this list cannot reach your agents. When a blocked number calls
any of your organization's phone numbers, ThunderPhone hangs up before an
agent answers and does not bill the call. It still appears in Call History,
as a failed inbound call with end reason **Blocked caller**. Calls with a
withheld or anonymous caller ID are never matched, and outbound calls to a
blocked number are not affected. A caller you block during a call is not cut
off; the block applies from their next call.

Every member can see the list; owners and admins change it under
**General → Blocked callers**:

- To block one number, enter it with an optional note and choose **Block
  number**. Use `+` and the country code; a national format such as
  `(415) 555-0123` also works when all of your organization's phone numbers
  are in one country.
- To block many at once, choose **Paste a list**, paste up to 500 numbers
  (one per line or separated by commas) and submit. The result shows how many
  were added, already blocked or invalid, and lists the invalid entries.
- To unblock a number, choose **Remove** on its row and confirm.

You can also open an inbound call in **Call History** and choose **Block this
caller**. An organization can block up to 10,000 numbers. To manage the list
through the API, see [Blocked Callers](/api-reference/blocked-callers).

### Organization identity and membership

The organization card shows the organization id, your membership role, and the
editable organization name. The team card combines active members and pending
invites.

| Role | Typical access |
| --- | --- |
| **Member** | Build and operate agents and review calls. |
| **Admin** | Member access plus team, keys, portals, connections, alerts, billing, and security administration. |
| **Owner** | Admin access plus ownership-level organization actions. |

Owners and admins can invite a **Member** or **Admin**, revoke a pending invite,
change eligible member roles, and remove members. Invites are email-specific
and expire after seven days. See [Invite your team](/guides/invite-your-team).

The danger zone lets an eligible user leave an organization or permanently
delete it. Deletion removes the organization's agents, numbers, call history,
and billing data and cannot be undone.

To delete your own account, open the **Account** tab and choose **Delete
account**. The dialog lists the organizations that will be deleted (those where
you are the only member) and the ones you will leave. API keys you created in an
organization you leave are revoked. Deletion is blocked while you are the only
owner of an organization that has other members (make someone else an owner
first), while you created custom voices in an organization that stays, while
a call is in progress, or while a legal hold applies; the dialog lists whatever
is blocking it. It cannot be undone.

### Default webhook

Set one legacy webhook URL to receive events from all web widgets and phone
numbers in the organization. For per-endpoint secrets, subscriptions, delivery
history, and retries, use the recommended
[webhook endpoints](/webhooks/endpoints) instead.

### Enterprise SSO

Configure one or more SSO connections, allowed email domains, just-in-time
provisioning, the default role, and optional group-to-role mappings. The
security policy can require SSO, allow emergency password access for admins,
and require passkeys for organization access. See [SSO](/guides/sso).

## Keys

The **Keys** tab manages secret `sk_live_` server API keys. Each row shows the
name, prefix, active/revoked state, creation time, last use, and revocation
time.

The complete secret is displayed only once, immediately after creation. Copy
it then and store it in a secret manager. Revocation is permanent and stops
every integration using the key. See [API keys](/guides/api-keys).

Publishable `pk_live_` keys belong to **Web Widgets**, because they are
origin-restricted browser credentials rather than server keys.

## Alerts

Create metric rules for success rate, failure rate, average score, call volume,
or suite regressions. A rule includes:

- Comparator and numeric threshold.
- Evaluation window from 1 to 720 hours.
- Up to 10 email recipients.
- Optional Slack incoming-webhook URL.
- Optional developer-webhook delivery.
- Cooldown in whole minutes and enabled state.

The same tab lists recent firings. See [Alerts](/guides/alerts).

## Billing Settings

Manage the organization balance and payment behavior:

- Add or replace the default payment card.
- Add funds manually.
- Enable auto top-up and set its threshold and refill amount.
- Set or remove a monthly spending limit.

The monthly limit pauses new calls and usage at 100% and remains active even
when auto top-up is off. See [Pricing](/guides/pricing) and
[Billing and top-ups](/guides/billing-and-topups).

## Billing History

Use **Billing History** to inspect balance and spend for Today, 7 days, 30 days,
90 days, or all time. It includes:

- Balance trend.
- Billing mix across call charges, reports, phone-number fees, and top-ups.
- Top agent spend.
- Transaction table with date, category, description, type, amount, and
  resulting balance.
- Category filtering and CSV or JSON export of the displayed history.

The dashboard reports when only the most recent transactions are displayed;
older rows beyond that limit are also absent from the export. The
[Billing API](/api-reference/billing) supports programmatic pagination.

<!-- en: guides/invite-your-team -->
---
title: "Invite your team"
description: "Add teammates to your ThunderPhone organization, choose the role that controls what each member can see and do, and manage invitations and existing members."
---

Organizations are multi-player. The team lives under
**Organization → General**, right below the org settings.

<Steps>
  <Step title="Enter their email">
    Type the email address of the person you want on this
    organization. They'll get an invitation link there.
  </Step>
  <Step title="Choose a role">
    Two roles:

    - **Member** — can build and operate agents.
    - **Admin** — can also manage the team and billing.

    You can change this later.
  </Step>
  <Step title="Send the invitation">
    Click **Invite**. They receive an email link to join; the
    invitation **expires after 7 days**, and you can revoke it from
    the list anytime.
  </Step>
  <Step title="Track it">
    Pending invites and current members share the same list. Use the
    ⋯ menu on a row to change a role, revoke an invite, or remove
    someone.
  </Step>
</Steps>

<Tip>
  Ask the in-app copilot to "invite a teammate" and it will offer to
  walk you through this flow, spotlighting each control live.
</Tip>

---

## Next steps

<CardGroup cols={2}>
  <Card title="Members API" icon="code" href="/api-reference/members">
    List members and manage roles programmatically.
  </Card>
  <Card title="Invites API" icon="envelope" href="/api-reference/invites">
    Create and revoke invitations over REST.
  </Card>
</CardGroup>

<!-- en: guides/api-keys -->
---
title: "Create a server API key"
description: "Mint an sk_live_ secret key from the dashboard for server-to-server calls to the ThunderPhone API, keep it safe, and rotate or revoke it when needed."
---

Server API keys (`sk_live_...`) authenticate server-to-server calls to
the ThunderPhone API. Keys live under **Organization → Keys**.

<Warning>
  Server keys are secrets. Never ship one in client-side code — for
  browsers, use domain-restricted
  [publishable keys](/api-reference/publishable-keys) (`pk_live_...`)
  instead.
</Warning>

<Steps>
  <Step title="Open the Keys tab">
    Go to **Organization → Keys** and click **Create key**.
  </Step>
  <Step title="Name it">
    Pick a name that says where the key will live — like "Production
    backend". Names are labels only; they don't affect access.
  </Step>
  <Step title="Create the key">
    Click **Create key** in the dialog. This generates the secret.
  </Step>
  <Step title="Copy it now">
    The full secret is shown **exactly once**. Copy it into your
    secret manager — after you leave, only the prefix remains visible.
  </Step>
</Steps>

## Use it

The key is bound to this organization, so requests need no org id —
just the Bearer header:

```bash
curl https://api.thunderphone.com/v1/agents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

From here, the [API quickstart](/quickstart) takes you to your first
call in three more requests.

## Rotate and revoke

Create a new key, move your services over, then delete the old one
from the same tab — the list shows each key's prefix and name so you
can tell them apart. To script rotation, call the
[developer API keys endpoints](/api-reference/developer-api-keys) with a
signed-in session token. An `sk_live_` key can't create, list, or revoke
keys, so a leaked key can't mint its own replacement. The same goes for
members, invites, payment settings, and other
[account controls](/api-reference/introduction#what-api-keys-cant-do).

<Note>
  Server API keys are machine credentials and are exempt from your
  organization's [**Require passkeys**](/guides/sso#security-policy)
  policy — that setting checks human sign-ins, not `sk_live_...` keys.
  Because of that, rotating and revoking keys promptly here is your
  main control over standing API access; if passkeys are required,
  the security policy panel shows how many active keys are currently
  exempt.
</Note>

<Tip>
  Ask the in-app copilot to "create an API key" and it will walk you
  through this flow, spotlighting each control live.
</Tip>

---

## Next steps

<CardGroup cols={2}>
  <Card title="API quickstart" icon="terminal" href="/quickstart">
    Agent, number, webhook, first call — four REST calls.
  </Card>
  <Card title="Authentication reference" icon="lock" href="/api-reference/introduction">
    How Bearer auth and org binding work.
  </Card>
</CardGroup>

<!-- en: guides/account-and-security -->
---
title: "Account & security"
description: "Your profile, profile picture, passkeys, and the macOS desktop app — everything on the My account page."
---

**Organization Settings → My account**
(`/dashboard/organization?tab=account`) holds your personal settings —
distinct from the organization-wide tabs beside it. Old
`/dashboard/account` links redirect here.

## Profile

Edit your **first name**, **last name**, and **email**, then click
**Save changes**.

### Profile picture (avatar)

Your profile picture — the avatar shown next to your name — is set by
URL, not by uploading a file:

1. Host the photo somewhere publicly reachable (any image URL works,
   e.g. `https://example.com/avatar.png`).
2. Paste that link into the **Avatar URL** field.
3. Click **Save changes** — the preview at the top of the card updates.

There is currently no file-upload option for profile photos; the URL
field is the whole mechanism. Clear the field and save to go back to
the default avatar (your initials).

<Note>
  If you sign in through your company's identity provider
  ([SSO](/guides/sso)), your email is managed there and shown
  read-only — you can still update your name and profile picture here.
</Note>

## Passkeys

Passkeys give you passwordless sign-in backed by your device (Touch ID,
Windows Hello, or a hardware security key):

- **Add passkey** registers a new one through your browser. Registered
  passkeys are listed with the date added, and you can remove any of
  them.
- **Verify now** performs a passkey check on your current session.

Organizations can **require passkeys** as part of their security
policy. If yours does, a banner on this page prompts you to add a
passkey (or verify with one after signing in) before you can keep using
organization resources — that post-login passkey check is the second
factor. Admins configure the requirement on the
[SSO & security settings](/guides/sso).

## Dashboard language

Choose the language used by the dashboard from the language selector. The
change is saved to your account and follows you across organizations. This is
separate from an agent's spoken languages; configure those in the agent builder
and see [Supported languages](/guides/supported-languages).

## Desktop app (macOS)

**Download for macOS** installs the native ThunderPhone app: the same
dashboard in its own application window, without browser tabs or an
address bar. The current beta requires macOS 12 or later.

## Sign out

**Sign out** ends your session on this device.

Resetting your password or changing your email signs you out on every
device and disconnects every app you authorized with
[OAuth](/guides/oauth), such as MCP connectors and Zapier. Sign in again
and reconnect those apps. Webhook endpoints a connected app created keep
delivering events until you delete them, so after a suspected account theft
review them as [Connect with OAuth](/guides/oauth#disconnect-an-app)
describes.

For the other settings tabs, see the complete
[Organization settings reference](/guides/organization-settings).

<!-- en: guides/sso -->
---
title: "Enterprise SSO"
description: "Let your team sign in to ThunderPhone through your company identity provider, with just-in-time provisioning and an organization-wide security policy you control."
---

Enterprise SSO lives on **Settings → Organization** (General tab), in
the **Enterprise SSO** card. Flip the **Single sign-on** switch to
reveal the configuration. Only organization **admins** and **owners**
can see or change these settings.

## Security policy

Three org-wide switches, saved together with **Save Policy**:

- **Require SSO for sign-in** — members must authenticate through your
  identity provider.
- **Allow break-glass password sign-in for admins** — an emergency
  password path for admins while SSO is enforced (only configurable
  when enforcement is on).
- **Require passkeys for organization access** — every member must
  register a [passkey](/guides/account-and-security) and pass a
  post-login passkey check. Members without one get a **3-day grace
  period** to set it up; the policy panel shows how many members still
  need one.

<Note>
  **Org [API keys](/guides/api-keys) are exempt from this requirement.**
  Passkeys are a human 2FA check tied to a login session; server API
  keys (`sk_live_...`) are machine credentials with no session to attach
  a passkey check to, so they keep authenticating even when this policy
  is on — by design, not by omission. When the requirement is enabled
  and your organization has active API keys, the policy panel shows how
  many are exempt, with a link to **Organization → Keys** so admins can
  audit or revoke any that shouldn't still be active.
</Note>

## SSO connections

ThunderPhone's SSO is backed by Stytch. **Add connection** creates one
with:

| Field | What it does |
| --- | --- |
| **Connection name** | A label, e.g. "Acme Workspace SSO". |
| **Default role for new users** | Member, Admin, or Owner for accounts created via SSO. |
| **Stytch organization slug / ID** | Identifies your Stytch organization backing the connection. |
| **Allowed email domains** | Comma-separated domains permitted to sign in through it. |
| **Group-to-role mappings** | JSON array mapping IdP groups to roles, e.g. `[{"group":"it-admins","role":"admin"}]`. |
| **Enable JIT provisioning** | Auto-create ThunderPhone accounts on first SSO sign-in. |
| **Connection active** | Deactivate without deleting. |

Deleting a connection removes it permanently — users who signed in
through it can no longer use it.

<Note>
  Setting up the identity-provider side requires a Stytch organization;
  if you don't have those identifiers, contact
  [support](mailto:support@thunderphone.com) to get your organization
  provisioned.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Invite your team" icon="user-plus" href="/guides/invite-your-team">
    Roles and invitations for members joining outside SSO.
  </Card>
  <Card title="Account & security" icon="shield" href="/guides/account-and-security">
    What the passkey requirement looks like for each member.
  </Card>
</CardGroup>

<!-- en: guides/recording-consent-laws -->
---
title: "Call recording consent laws"
description: "Why the recording announcement exists, what the law requires in different places, and what your organization takes on if you turn the announcement off."
---

<Note>
  This page is a practical orientation, not legal advice. Recording and
  wiretap laws vary by state and country and change over time — consult
  your counsel about your specific call flows.
</Note>

By default, every ThunderPhone agent opens its calls with a short spoken
announcement (for example, *"This call is with an AI assistant and will be
recorded and transcribed."*). This page explains which kinds of laws that
announcement is designed to address and what your organization becomes
responsible for if you [turn it off](#turning-the-announcement-off). It
describes the legal landscape; it does not certify that the announcement
satisfies any particular jurisdiction's requirements for your calls.

## What the announcement covers

**United States — recording consent.** Federal law and most states allow
recording when *one* party to the call consents ("one-party consent").
But a number of states — including California, Florida, Illinois,
Maryland, Massachusetts, Montana, New Hampshire, Pennsylvania, and
Washington — require *every* participant's consent ("all-party consent"),
and it is generally the strictest applicable state's rule that matters
when callers can be anywhere. A clear announcement at the start of the
call, with the caller continuing afterward, is the widely used way
businesses seek consent on recorded lines — but what counts as valid
consent is defined by each state's statute and case law, and some (such
as [California Penal Code § 632](https://leginfo.legislature.ca.gov/faces/codes_displaySection.xhtml?lawCode=PEN&sectionNum=632))
provide no blanket continued-participation safe harbor. California's
Invasion of Privacy Act (CIPA) is the most actively litigated of these
statutes, and recent cases have applied it to AI vendors that listen to
or transcribe calls in real time — not just to stored recordings.

**United States — AI disclosure.** A growing set of states (Utah,
Colorado, Maine, Texas, among others) regulate telling consumers when
they are interacting with an AI system rather than a person. Scope
varies: some require disclosure only when the consumer asks, with
proactive disclosure reserved for specific regulated interactions (see
e.g. [Utah Code § 13-77-103](https://le.utah.gov/xcode/Title13/Chapter77/13-77-S103.html)),
while others reach further. The announcement's "AI assistant" language is
a proactive disclosure aimed at this family of rules.

**European Union and UK.** GDPR requires a lawful basis and transparency
for processing call audio and transcripts; the EU AI Act (Article 50)
separately requires disclosing that a caller is interacting with an AI
system. The announcement provides the disclosure half; your organization
remains responsible for its lawful basis.

**Everywhere else.** Most jurisdictions have some combination of
recording-notice and interception rules. The announcement is designed as
a conservative default for them; whether it is sufficient for a given
jurisdiction and call flow is your organization's determination to make.

## How ThunderPhone strengthens your position

When the announcement plays, ThunderPhone also stores content-free
evidence of what happened next — that the notice finished playing and
that the caller kept talking afterward. If a recording is ever
challenged, the recording itself begins with the announcement, and the
call's consent evidence shows the caller heard it and continued.

### Uninterruptible disclosures

Use **Advanced → Consent announcement** for required call-opening text. It
plays before the conversation and cannot be interrupted. The
**Uninterruptible disclosures** setting and `speak_uninterruptible_enabled` API
field remain visible for compatibility but currently have no runtime effect;
leave them off.

## Turning the announcement off

Organization admins can turn the announcement off per agent (Agent →
Advanced → Consent announcement). Doing so removes a default compliance
control while **recording, transcription, and AI processing continue**,
so the confirmation dialog asks you to confirm that your organization
will provide any legally required notice and obtain any legally required
consent itself — for example, because your phone system already plays its
own recording notice, or your customer relationships establish consent
another way. ThunderPhone can restore the announcement at any time.

## Turning recording off, and the AI-processing disclosure

Organizations can also turn **call recording itself** off — organization-wide
(Organization → General → Call recording & AI disclosure) or per agent
(Agent → Advanced). Calls without recording keep no recordings, transcripts,
or stored call content.

Turning recording off does not end your notice obligations: interception and
AI-disclosure rules (including CIPA-style statutes and the EU AI Act) can
apply to *live* AI processing of a call even when nothing is stored. So on
calls that are not recorded, agents play a different, shorter notice by
default:

> "This call is with an AI assistant; audio is processed live but not
> recorded."

This AI-processing disclosure has its own controls: an organization-wide
default plus a per-agent override (inherit / always play / don't play).
Turning it off is a separate attested decision — an organization admin
confirms in a dialog that the organization will provide any legally required
notices and disclosures, and obtain any legally required consents, for its
calls while the disclosure is off. Without an active attestation, the
disclosure plays regardless of the saved setting, and ThunderPhone can
restore it at any time.

<!-- en: guides/outbound-calling-laws -->
---
title: "Outbound calling compliance"
description: "What the TCPA and similar laws require before your agents place outbound calls, and what the one-time confirmation in the dashboard means."
---

<Note>
  This page is a practical orientation, not legal advice. Telemarketing
  and robocall laws vary by jurisdiction and change over time — consult
  your counsel about your specific calling program.
</Note>

Before an organization first places outbound calls through ThunderPhone
(starting a campaign, or calling `POST /v1/call`), an organization admin
confirms once that the organization's outbound calling complies with
applicable law. This page explains what that actually involves.

## Calls to U.S. numbers: the TCPA

The Telephone Consumer Protection Act (TCPA) and the FCC's implementing
rules ([47 CFR § 64.1200](https://www.ecfr.gov/current/title-47/chapter-I/subchapter-B/part-64/subpart-L/section-64.1200))
govern automated outbound calling. The rules that most commonly matter
for AI voice agents:

- **Consent.** Calls that use an artificial, prerecorded, or AI-generated
  voice generally require the called party's *prior express consent* —
  and for marketing calls, *prior express written consent*. Consent must
  be obtained before the call and can be revoked at any time.
- **Identification.** The call must identify who is calling, and provide
  a contact number.
- **Do-not-call.** Marketing calls must honor the National Do-Not-Call
  Registry and your own internal do-not-call list; opt-out requests must
  be honored promptly. When someone asks your agent on an outbound call
  not to be called again, the agent ends the call and ThunderPhone adds the
  number to your [opt-out list](/api-reference/opt-outs), which refuses
  later calls to it. If the person hangs up first, ThunderPhone checks the
  transcript after the call, on calls that keep a transcript, and adds the
  number then. This depends on
  recognizing the request, so keep honoring your own do-not-call list as
  well. You can turn this detection off for an agent only after your
  organization attests that it takes responsibility for do-not-call
  compliance on its calls
  ([details](/api-reference/opt-outs#turning-detection-off)).
- **Calling windows.** Marketing calls are restricted to 8 a.m.–9 p.m. in
  the called party's local time (ThunderPhone campaigns let you set
  calling windows).
- **State laws.** Several states layer their own "mini-TCPA" statutes on
  top (Florida and Oklahoma are frequently cited), sometimes with
  stricter consent or timing rules.

Statutory damages run $500–$1,500 *per call*, which is why consent
hygiene on your contact lists matters more than any other single thing.

## Calls to other countries

Outside the U.S., the destination country's rules apply — for example
PECR/Ofcom rules in the UK, CRTC telemarketing rules and CASL in Canada,
and ACMA rules in Australia. Requirements typically cover consent or
opt-out registries, calling hours, and caller identification.

## What the confirmation is

The dashboard asks an organization admin to confirm, once, that the
organization takes responsibility for its outbound calls complying with
these laws. It applies only to calls your agents *originate* — inbound
calls and call transfers are never affected — and running campaigns are
never interrupted by it. Organizations that existed before August 3,
2026 are not asked at all.

<!-- en: guides/handle-inbound-calls -->
---
title: "Handle inbound calls (API)"
description: "End-to-end: configure an agent, assign it to a phone number, take a call, and inspect the transcript."
---

<Note>
  Building your first agent by hand? The dashboard walks this exact
  flow — build the agent, add a number, simulate, review — with a
  guided wizard. Start at the
  [dashboard quickstart](/quickstart-dashboard).
</Note>

The canonical "answer a phone with an AI" flow, from your terminal.
You'll:

1. Create an agent with a prompt and voice.
2. Provision (or bring) a phone number and assign the agent as its
   inbound handler.
3. Call the number. Observe the call log, transcript, and recording.

Total API calls: four. Total time: under five minutes.

## 1. Create an agent

An agent bundles the prompt, voice, and product tier that will drive
the call. You can also set call limits such as `max_call_duration_seconds`
and `ring_duration_seconds` on the agent. For outbound calls, you can also set
`max_hold_seconds` to limit how long the agent waits on hold before ending the
call. Bolt agents also support `audio_tier`, `endpointing`, and `intelligence`
to control how they listen and reply. `intelligence` supports `lite` and
`standard`. Agents also support an `intro_clip` and
`intro_ring_count` to play a prerecorded intro and up to two rings before the
agent speaks. New agents also need a time zone. If your agent is multilingual,
you can set `language_switching` to control whether it asks before switching
languages or follows the caller's language. You can also set `words` on the
agent to control how it says specific terms and which terms it listens for.
See [Agents](/api-reference/agents) for every configuration field; the
minimum is:

```bash
curl -X POST https://api.thunderphone.com/v1/agents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":    "Acme Support",
    "prompt":  "You are a friendly support agent for Acme. Help callers with orders and returns. Keep answers short.",
    "voice":   "john",
    "product": "spark"
  }'
```

Save the returned `id` — you'll need it in step 2.

<Tip>
  Pick `spark` for simple Q&A at the lowest cost, `bolt` when speed
  matters most. Upgrade to `storm-base-with-ack` when your prompt
  needs deeper reasoning and can tolerate a half-second filler while
  the model thinks. See
  [product tiers](/api-reference/agents#product-tiers-at-a-glance).
</Tip>

## 2. Get a phone number

If you just need something to dial against, get a ThunderPhone number
from ThunderPhone's pool:

```bash
curl -X POST https://api.thunderphone.com/v1/phone-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"area_code": "415"}'
```

The response includes an `id` and a `number` in E.164. ThunderPhone
numbers start in `status="provisioning"` and become `active` within a few
seconds — poll
[`GET /v1/phone-numbers/{id}`](/api-reference/phone-numbers#retrieve-a-phone-number)
to watch the transition if you care.

<Note>
  ThunderPhone numbers start inbound-only. An organization admin can request
  outbound calling from the Phone Numbers page. ThunderPhone reviews each
  request manually; once approved, the numbers can place calls and run
  campaigns. Customer VoIP numbers are unchanged.
</Note>

## 3. Assign the agent

Associate the agent from step 1 with the number's inbound direction:

```bash
curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/{phone_id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbound_agent_id": 12}'
```

That's it — the number is live. After outbound calling is approved for your
organization, you can also set `outbound_agent_id` in the same PATCH. Until
then, the API rejects that assignment with `400`.

If you route inbound calls through a config webhook instead of a fixed
`inbound_agent_id`, that webhook can now return a per-call `timezone` along
with `agent_id` and `variables`. For Bolt agents, you can also set
`audio_tier`, `endpointing`, and `intelligence` on the agent in API writes.
The API still accepts the older `eagerness` name as an alias for
`endpointing`. If your agent uses API connections with `trigger="call_start"`,
ThunderPhone can run those tools once at the start of each phone call, before
the greeting, using their saved `call_start_arguments`.

### Callbacks to your outbound calls

When someone calls back a number that called them in the last 30
days, the answering agent gets a short background note on that call:
when it was made, by which agent and what happened (no answer,
voicemail or a conversation). A number with no inbound agent sends
the same details to your config webhook as `returning_call`. If that
number has no webhook, or the webhook times out or cannot be reached,
the call goes to the agent that placed the earlier call instead of
ending. Caller ID can be faked, so the earlier call's summary and
variables are shared only if an admin turns on **Share the earlier
call's details** under Organization → General → Callbacks. See
[Callbacks](/webhooks/call-incoming#callbacks).

## 4. Take a call

Dial the number from your phone. The agent picks up, introduces itself
per your prompt, and the conversation begins.

While the call is in flight, it appears in
[`GET /v1/calls`](/api-reference/calls#list-calls) with
`status="in_progress"`. When it ends, the record updates with
`end_reason`, `duration_seconds`, `billable_minutes`, and (eventually)
a recording URL and AI grade.

Inbound calls count toward your organization's
[concurrent-call limit](/api-reference/introduction#call-limits) (20
calls in progress by default, shared with outbound, web and test
calls). A call that arrives at the limit is refused before the agent
answers and hung up, is not billed, and is recorded as a failed call
with end reason `concurrent_call_limit_reached`. Email support@thunderphone.com if you
need a higher limit.

## 5. Inspect the results

Fetch the list of recent calls:

```bash
curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

Grab the transcript:

```bash
curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

And the recording URL (short-lived, signed):

```bash
curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

If you subscribed to the
[`telephony.complete` webhook](/webhooks/events#telephony-complete)
you'll receive the same data as a POST to your server — see
[call.complete](/webhooks/call-complete).

If your agent has extraction fields configured, the completed call payload can
also include structured extracted data.

---

## Next steps

<CardGroup cols={2}>
  <Card title="Dynamic per-call config" icon="bolt" href="/guides/dynamic-call-config">
    Pick a different agent per caller based on the phone number or
    custom logic in a webhook.
  </Card>
  <Card title="Add tool integrations" icon="screwdriver-wrench" href="/guides/build-tool-integration">
    Let the agent call your APIs mid-conversation.
  </Card>
  <Card title="Transfer calls" icon="phone-arrow-right" href="/guides/call-transfers">
    Route callers directly or screen the destination before connecting them.
  </Card>
  <Card title="Receive call.complete webhooks" icon="bolt" href="/webhooks/call-complete">
    Stream each finished call to your CRM / analytics pipeline.
  </Card>
  <Card title="AI grading and issue reports" icon="chart-line" href="/api-reference/calls#ai-call-grading">
    Score every call automatically and route flagged ones for review.
  </Card>
</CardGroup>

<!-- en: guides/place-outbound-calls -->
---
title: "Place outbound calls (API)"
description: "Trigger an AI-driven outbound call from your own code — survey, follow-up, or confirmation flows."
---

Outbound calling lets you hand a destination number and an agent
configuration to ThunderPhone and have the AI place the call on your
behalf. Typical use cases:

- Appointment confirmations
- Survey callbacks
- "Second-try" follow-ups after a missed call
- Dispatch-style notifications

<Note>
  Calling a whole list? The dashboard's
  [**Campaigns**](/guides/outbound-campaigns) feature
  (`/dashboard/campaigns`) takes a CSV of contacts and handles
  timezone-aware calling windows, concurrency, and retry policy for
  you. This guide covers single programmatic calls.
</Note>

## Prerequisites

<Steps>
  <Step title="Choose an outbound-enabled number">
    Use a number you own through a
    [VoIP connection](/api-reference/voip-connections), or request permission
    to use your ThunderPhone numbers for outbound calls from the Phone Numbers
    page. ThunderPhone numbers start inbound-only. ThunderPhone reviews each
    request manually; once approved, those numbers can place calls up to the
    approved daily limit (resetting at 00:00 UTC) and run campaigns, and you
    can ask for a higher limit. Customer VoIP numbers have no daily limit, so we recommend
    them for outbound calling. See
    [Bring your own numbers](/guides/bring-your-own-numbers).
  </Step>
  <Step title="Create an agent">
    An outbound-flavoured prompt tends to start with the agent
    identifying itself and its purpose — "Hi, this is Acme calling to
    confirm your appointment for tomorrow at 3pm…" Set
    `outbound_speak_order` to `agent_first` (the default).
  </Step>
  <Step title="Keep a positive balance">
    Outbound calls return `402 Payment Required` if balance is ≤
    `$0.00`. Top up or enable auto-reload under
    **Organization → Billing Settings** in the dashboard. Your `sk_live_`
    key can check the balance with
    [`GET /v1/billing`](/api-reference/billing#get-billing-account) but
    can't top up or change auto-reload.
  </Step>
</Steps>

## Place a call with a saved agent

The simplest path — reference an agent by id:

```bash
curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155552671",
    "agent_id":    12
  }'
```

Response:

```json
{ "call_id": 987654321, "status": "initiated" }
```

<Warning>
  `status: "initiated"` just means the request was accepted — the call
  is **not yet connected**. Poll
  [`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)
  for the live status (`in_progress` → `completed` / `failed`).
</Warning>

## Place a call with inline config

If you want a one-off prompt that isn't worth saving as an agent,
pass `config` instead. The shape matches the response schema of the
[`call.incoming` webhook](/webhooks/call-incoming#response-schema):

```bash
curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155552671",
    "config": {
      "prompt":  "You are confirming Jane Doe appointment for 3pm tomorrow…",
      "voice":   "john",
      "product": "spark"
    }
  }'
```

### Control what happens after the last silence check-in

You can also pass the same silence final-action settings in inline `config` that saved agents use:

```json
{
  "from_number": "+[REDACTED_PHONE]",
  "to_number": "+[REDACTED_PHONE]",
  "config": {
    "silence_final_action": "hang_up"
  }
}
```

Use `silence_final_action` to choose what happens after the last silence check-in. You can also pass `silence_final_message`, and when the final action is transfer, `silence_transfer_destination`.

### Add a words list to inline `config`

Inline outbound calls can include the same `words` list as saved agents.
Use this when you want the call to follow custom pronunciation or hearing
rules without saving an agent first.

```json
{
  "from_number": "+[REDACTED_PHONE]",
  "to_number": "+[REDACTED_PHONE]",
  "config": {
    "prompt": "[REDACTED_LITERAL]",
    "voice": "john",
    "product": "spark",
    "words": []
  }
}
```

## Follow the call

A response with a `queued_at` time means ThunderPhone's outbound capacity is
in use: the call dials when there is room, within 10 minutes, and ends with
`end_reason` `outbound_queue_timeout` if there is none. You don't need to
retry. See [queued calls](/api-reference/outbound-calls#queued-calls).

In parallel, subscribe to the
[`telephony.complete` webhook](/webhooks/events#telephony-complete) —
the fastest way to know a call finished. If you can't accept inbound
webhooks, poll `GET /v1/calls/{call_id}` every couple of seconds; the
record includes `end_reason`, `duration_seconds`, and the recording
URL once the call ends.

If your agent is set up to extract structured data after the call,
that data is delivered separately after finalization completes.

### Pass per-call variables to a saved agent

Saved agents can use placeholders like `{{name}}` or `{{name|there}}` in
prompt text. When you place an outbound call with `agent_id`, pass
`variables` with the values for that call:

```json
{
  "from_number": "+[REDACTED_PHONE]",
  "to_number": "+[REDACTED_PHONE]",
  "agent_id": 12,
  "variables": {
    "name": "Jordan"
  }
}
```

Use string values keyed by placeholder name. These variables apply to
saved agents; this guide's inline `config` example does not use them.

## Failure modes worth handling

| Error | Fix |
|-------|-----|
| `402 Payment Required` | Top up the balance or enable auto-reload |
| `400` with `code: destination_not_allowed` | ThunderPhone does not call that number: invalid numbers, emergency numbers, premium-rate numbers, short codes, or sanctioned countries. From ThunderPhone numbers, only ordinary US and Canadian numbers (no premium-rate). `reason` says which; see [blocked destinations](/api-reference/outbound-calls#blocked-destinations) |
| `409` with `retryable: false` for a ThunderPhone number | Follow the `code`: request outbound calling on the Phone Numbers page, wait for a pending review, or use another eligible number |
| `429` with `code: platform_outbound_daily_limit_reached` | The organization used today's outbound calls from ThunderPhone numbers. Wait for `resets_at` (00:00 UTC), request a higher limit on the Phone Numbers page, or call from a number on your own VoIP connection |
| `429` with `code: concurrent_call_limit_reached` | The organization has as many calls in progress as its [concurrent-call limit](/api-reference/introduction#call-limits) (20 by default, counting inbound, outbound, web and test calls). Retry after the `Retry-After` header's seconds or when a call ends; email support@thunderphone.com to raise the limit |
| `429` with `code: outbound_queue_full` | The organization has 50 [queued calls](/api-reference/outbound-calls#queued-calls) waiting. Retry after the `Retry-After` header's seconds |
| `429` with `code: same_number_too_soon` | You called the same `to_number` less than 10 seconds ago. Retry after the `Retry-After` header's seconds |
| `409` with `retryable: false` for a customer VoIP number | Correct the state named by `code`; for verification failures, run [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) |
| `409` idempotency conflict | Reuse the key only with the original normalized request, or send a new key |
| `404 from_number is not registered to this organization` | Confirm the `from_number` matches an active phone number in your organization. A number that is already provisioning, failed, releasing, or released also returns this response |
| `500` with only a `detail` field | No outbound trunk is configured. Contact support; this is not a number-state problem you can correct |
| `502 Bad Gateway` | Transient SIP / LiveKit failure; safe to retry |

See the [outbound calls reference](/api-reference/outbound-calls#error-responses)
for the complete stable eligibility-code list and both `409` response shapes.
If an active number becomes ineligible after the request is accepted but before
the call is placed, the final check returns the non-retryable `409` payload.

## Controlling hold time

Outbound calls that run long because the callee is slow to respond
(IVR trees, queues) can be capped with `max_hold_seconds` on the call, or by setting it on the saved agent:

```json
{
  "from_number": "+15551234567",
  "to_number":   "+14155552671",
  "agent_id":    12,
  "max_hold_seconds": 120
}
```

The agent hangs up if no human audio has been received in the last
N seconds. Default is 900 seconds (15 minutes).

If you set `max_hold_seconds` on both the saved agent and the outbound call request, the per-call value is used for that call.

---

## Next steps

<CardGroup cols={2}>
  <Card title="Outbound calls reference" icon="phone-arrow-up-right" href="/api-reference/outbound-calls">
    Every request field and error code.
  </Card>
  <Card title="Receive call.complete" icon="bolt" href="/webhooks/call-complete">
    Stream finished outbound calls to your system.
  </Card>
  <Card title="Billing" icon="credit-card" href="/api-reference/billing">
    Auto-reload so outbound never fails on balance.
  </Card>
  <Card title="Test outbound agents" icon="flask" href="/guides/test-agents">
    Dry-run your outbound agent before production.
  </Card>
</CardGroup>

<!-- en: guides/embed-web-widget -->
---
title: "Embed the web widget"
description: "Drop a voice agent onto your marketing or support site with a single script tag — visitors talk to it straight from the browser, no phone number required."
---

The web widget gives your site visitors a click-to-talk conversation
with an AI agent, using the browser's microphone. It's a separate
JavaScript / React SDK with its own [SDK reference](/widget/overview)
— this guide focuses on the ThunderPhone-side setup the widget needs.

<Note>
  You can do all of this without cURL: the **Web Widgets** dashboard
  page (`/dashboard/web-widgets`) creates the widget, sets its mode
  and agent, manages allowed domains, and hands you the embed snippet.
</Note>

## Prerequisites

<Steps>
  <Step title="Create an agent">
    The agent whose prompt and voice will run the widget session. Set
    `widget_enabled: true` (the default).
  </Step>
  <Step title="Decide the routing mode">
    - `mode="agent"` — one static agent per key. Simplest.
    - `mode="webhook"` — your server picks the agent per visitor via a
      [`web.incoming` webhook](/webhooks/call-incoming). Use this for
      logged-in users, A/B tests, or per-page routing.
  </Step>
  <Step title="List the allowed domains">
    Name every hostname that will embed the widget. Browsers send the
    page's origin with each session request, so the list stops your key
    from working when someone copies it onto another site. It is not
    authentication: a script outside a browser can send any `Origin`
    header. `localhost` is not allowed automatically in production; to
    test locally against the production API, add `localhost` to the
    list.
  </Step>
  <Step title="Choose the browser overrides">
    Decide which session settings your page may send. New keys accept
    none; see [Browser overrides](#browser-overrides).
  </Step>
</Steps>

## Create a publishable key

<CodeGroup>
```bash Static agent
curl -X POST https://api.thunderphone.com/v1/publishable-key \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":            "Marketing site (prod)",
    "mode":            "agent",
    "agent_id":        12,
    "allowed_domains": ["example.com", "*.example.com"],
    "allowed_overrides": ["context"]
  }'
```

```bash Dynamic via webhook
curl -X POST https://api.thunderphone.com/v1/publishable-key \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":            "Support (dynamic)",
    "mode":            "webhook",
    "webhook_url":     "https://example.com/thunderphone/widget-hook",
    "allowed_domains": ["support.example.com"]
  }'
```
</CodeGroup>

The response includes a `key` starting with `pk_live_...`. **Publishable
keys are public by design** — safe to ship in your front-end bundle.
See [Publishable keys reference](/api-reference/publishable-keys) for
all fields.

<Warning>
  `allowed_domains` must contain at least one entry. `*.example.com`
  matches subdomains (e.g. `api.example.com`) but **not** the bare
  domain. Bare wildcards like `*` or `*.*` are rejected.
</Warning>

## Drop the widget on your site

Three integration options are covered in the
[widget SDK docs](/widget/overview):

<CardGroup cols={3}>
  <Card title="React component" icon="react" href="/widget/react">
    `<ThunderPhoneWidget publishableKey="pk_live_..." />`.
  </Card>
  <Card title="Headless hook" icon="circle-nodes" href="/widget/headless-hook">
    `useThunderPhone()` for custom UIs.
  </Card>
  <Card title="CDN script tag" icon="code" href="/widget/cdn-script-tag">
    `ThunderPhone.mount({...})` for non-bundler sites.
  </Card>
</CardGroup>

All three accept the same `publishableKey` and render the mic button
plus the in-call audio element.

## Browser overrides

The widget can send four per-session settings from the page:

| Setting | Widget prop | What it changes |
|---------|-------------|-----------------|
| `context` | `context` | Text from the page, appended to the agent prompt as reference |
| `variables` | none (raw `POST /v1/widget/session` only) | Values for `{{variable}}` placeholders in the prompt |
| `voice` | `voice` | The agent's voice for this session |
| `language` | `language` | The language the session starts in |

Your publishable key is public, so anyone who has it can send these
settings, including from a script that fakes your domain. Each one is
therefore off until you allow it on the key: tick it under **Browser
overrides** when you create or edit the widget in the dashboard, or set
`allowed_overrides` through the
[Publishable keys API](/api-reference/publishable-keys). Allow only what
your page actually sends.

A session request that carries a setting the key does not allow fails
with `400` and names it:

```json
{
  "error": "override_not_allowed",
  "fields": ["voice"],
  "message": "This publishable key does not allow the browser to set `voice`. ..."
}
```

The check applies in both modes. In webhook mode an allowed setting is
also forwarded to your `web.incoming` webhook (`context` arrives as
`website_context`). Keys created before this setting existed allow all
four, so existing embeds keep working; turn off what you don't use.

Widget `context` is truncated at 12,000 characters (roughly 3,400
tokens of typical English text) and is part of the prompt the models read, so
a longer context [costs more per minute](/guides/billing-and-topups#prompt-size).
The agent is told to treat it as page content, not as instructions.

## Widget-mode webhooks

When `mode="webhook"`, ThunderPhone calls your `webhook_url` on every
session start with a `web.incoming` payload. Return the agent
configuration you want to run for that visitor — it follows the same
[response schema](/webhooks/call-incoming#response-schema) as phone
calls:

```json
{
  "prompt":  "You are a VIP concierge for Jane Doe.",
  "voice":   "john",
  "product": "storm-base",
  "tools":   [ /* per-customer tools */ ]
}
```

You can mix context from your own session (which customer is browsing,
which page they're on) into the prompt, and swap agents per rollout.

## Observe the sessions

Widget sessions show up in
[`GET /v1/calls`](/api-reference/calls#list-calls) with
`direction="widget"` — same transcript, recording, grading, and
billing as phone calls. Filter by `direction` to build a widget-only
dashboard.

---

## Next steps

<CardGroup cols={2}>
  <Card title="Widget SDK reference" icon="window-maximize" href="/widget/overview">
    React / hook / CDN integration details.
  </Card>
  <Card title="Dynamic per-call config" icon="bolt" href="/guides/dynamic-call-config">
    Implement the `mode="webhook"` flow end-to-end.
  </Card>
  <Card title="Publishable keys reference" icon="key" href="/api-reference/publishable-keys">
    Every field on the key resource.
  </Card>
  <Card title="Mic sessions API" icon="microphone" href="/api-reference/mic-sessions">
    Skip the widget; drive LiveKit directly for custom UIs.
  </Card>
</CardGroup>

<!-- en: guides/bring-your-own-numbers -->
---
title: "Bring your own numbers (VoIP, API)"
description: "Connect Twilio or Telnyx, or SignalWire, Vonage, Plivo and any other SIP trunk over SIP, import the phone numbers you already own, and let ThunderPhone agents answer and place calls on them."
---

Approved ThunderPhone numbers can place outbound calls and run campaigns. If
you prefer to use numbers you own through your own VoIP provider, this guide
walks you through the connection flow: **test credentials → create connection
→ import numbers → verify**.

<Note>
  The dashboard has a guided version of this whole flow under
  **Connections → VoIP** (`/dashboard/voip-connections`): a
  connect-existing path first (Twilio and Telnyx by API key; SignalWire,
  Vonage, Plivo and any other trunk through the manual SIP form with
  provider-specific steps and an AI setup-guide generator), and a
  guided setup second that opens a new Telnyx account.
</Note>

## Supported providers

| Provider | `provider` id | Notes |
|----------|---------------|-------|
| Twilio | `twilio` | Account SID + Auth Token; one connection per Twilio account or subaccount (see [Twilio subaccounts](#twilio-subaccounts)) |
| Telnyx | `telnyx` | API key; guided onboarding available (`setup_method: guided_telnyx`) |
| SignalWire | `signalwire` | No native provider connection; connect it as `manual` with the SignalWire SIP preset |
| Vonage | `vonage` | No native provider connection; connect it as `manual` with the Vonage SIP preset |
| Manual SIP | `manual` | Any SIP trunk, including SignalWire, Vonage and Plivo. If you start from one of those provider tiles in the dashboard, the connection is still `manual` and stores the choice in `sip_config.preset` (`signalwire`, `vonage` or `plivo`) |

## 1. Test credentials

Before you create a persisted VoIP connection, probe the provider
credentials to confirm they work. This returns a
`verification_evidence_id` that you pass to the create step so the
credentials aren't double-charged for testing.

```bash
curl -X POST https://api.thunderphone.com/v1/voip-connections/test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider":    "telnyx",
    "credentials": { "apiKey": "KEY...", "connectionId": "123456" },
    "sip_config":  { "domain": "acme.sip.telnyx.com" }
  }'
```

```json Response
{
  "status": "pass",
  "verification_evidence_id": "b9a2...",
  "suggested_connection_name": "Telnyx: Acme Main (+15550001234)",
  "checks": {
    "credentials_valid": true,
    "inbound_reachable": true,
    "outbound_authorized": true
  }
}
```

If any check fails, response `status` will be `fail` and `checks` will
show which step blew up. Fix the provider-side config (trunk
assignment, IP allowlist, outbound authorization) and retry.

## 2. Create the connection

Pass the `verification_evidence_id` you just got:

```bash
curl -X POST https://api.thunderphone.com/v1/voip-connections \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":         "Acme Telnyx Main",
    "provider":     "telnyx",
    "setup_method": "api_key",
    "credentials":  { "apiKey": "KEY...", "connectionId": "123456" },
    "sip_config":   { "domain": "acme.sip.telnyx.com" },
    "verification_evidence_id": "b9a2..."
  }'
```

The response is a [VoipConnection object](/api-reference/voip-connections#connection-object)
in `status="connected"`. Credentials and other secret connection values are stored server-side and never
returned in plain text by subsequent GETs — to rotate, run a fresh
`test` and PATCH with the new evidence.

### Twilio subaccounts

A Twilio connection is bound to the single Twilio account whose
Account SID and Auth Token it holds. Twilio keeps phone numbers and SIP
trunks inside each subaccount, so a connection made with the parent
account only ever sees the parent's own numbers, and an existing
connection cannot be switched to a different subaccount later.

To reach numbers held in subaccounts, create one connection per
subaccount. The dashboard does this for you: when you connect a parent
account that has active subaccounts, the setup dialog lists them, you
tick the ones you want, and ThunderPhone creates a connection (and a
SIP trunk) in each one. The same flow is available over the API:

```bash
# Discover active subaccounts visible to the parent credentials
curl -X POST https://api.thunderphone.com/v1/voip-connections/twilio/subaccounts \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"credentials": {"accountSid": "ACparent...", "authToken": "..."}}'
```

```json Response
{
  "discovery_id": "7c1e...",
  "parent": { "sid": "ACparent...", "friendly_name": "Acme" },
  "subaccounts": [
    { "sid": "ACsupport...", "friendly_name": "Acme Support", "already_connected": false, "connection_id": null },
    { "sid": "ACsales...",   "friendly_name": "Acme Sales",   "already_connected": true,  "connection_id": 5 }
  ]
}
```

```bash
# Create a connection for each selected subaccount
curl -X POST https://api.thunderphone.com/v1/voip-connections/twilio/subaccounts/connect \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"discovery_id": "7c1e...", "subaccount_sids": ["ACsupport..."]}'
```

The response carries one row per subaccount with `status` of
`created`, `skipped` (already connected) or `failed` plus an `error`
you can act on. Rows are independent, so a failure in one subaccount
never blocks the others, and a `discovery_id` stays valid for 30
minutes so a failed row can simply be retried. Subaccount tokens are
read from Twilio at discovery time and stored on the new connection;
they are never returned by the API. Each new connection then imports
and verifies numbers exactly like a connection you created by hand.
Add `"enable_transfers": true` to also turn call transfers on for each
new connection's SIP trunk; a failure there is reported in that
connection's `test_result.transfer_enable_error` and does not fail the
row.

## 3. List and import numbers

Inspect the numbers visible to your credentials that aren't already
in a ThunderPhone org:

```bash
curl https://api.thunderphone.com/v1/voip-connections/5/available-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

Then import the ones you want:

```bash
curl -X POST https://api.thunderphone.com/v1/voip-connections/5/import-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"numbers": ["+15550001234", "+15550009999"]}'
```

Each import becomes a [phone number resource](/api-reference/phone-numbers)
in your org with `number_type="voip"` and `status="provisioning"`.

### Keep your own call routing

On Twilio, importing puts the number on ThunderPhone's SIP trunk in your
account; on Telnyx, it assigns the number to ThunderPhone's SIP connection.
Either way, every call then goes straight to your agent.

To route calls yourself instead (for example, ring a person first and send
the call to the agent only if they don't answer), change the number's voice
settings at your provider after importing, or import through the API with
`"call_routing": "customer"` so ThunderPhone doesn't change them at all.
ThunderPhone never changes them back. To have the agent answer, send the
call to the number's SIP address:

```xml
<Response>
  <Dial>
    <Sip>sip:+15550001234@sip.thunderphone.com</Sip>
  </Dial>
</Response>
```

Texting through the number works the same either way. The incoming-call
test calls the number, so it reaches whoever your routing sends calls to
first.

### Moving a number between connections

Importing a number that is already on another of your connections moves
it to the new one, with its agents and history. A number that a Twilio or
Telnyx connection sends to ThunderPhone has to be removed from that
connection first, since its provider would keep sending calls there.

## 4. Verify each imported number

Importing registers the number as *available*; actually routing calls
through it needs verification. For provider connections (Twilio,
Telnyx) that re-checks the provider credentials and SIP reachability.
For a **manual SIP** connection it first tries a loopback self-call:
ThunderPhone places a short probe call *from* the number, *through* your SIP
trunk, *back to the same number*. If that does not verify the inbound path, it
falls back to a short probe call *from* the number, *through* your SIP trunk,
*to* a ThunderPhone number. These tests check the trunk's username,
password, transport, outbound routing, and inbound delivery. Your carrier
bills these calls like any other.

```bash
curl -X POST https://api.thunderphone.com/v1/phone-numbers/{id}/verify-voip \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

On success, `voip_verification_status` flips to `verified` and the
number enters `status="active"`. A number in your own Telnyx account
keeps taking inbound calls when its test call fails or outbound is not
set up yet: it becomes `status="active"` with `voip_verification_status`
set to `unverified`, and the response says why. On failure, the
response spells out
what failed — for a manual trunk that is the carrier's SIP answer, for
example *"rejected ThunderPhone's credentials (SIP 401)"* or *"could
not route a call (SIP 404)"* — fix it (credentials, allowed source
IPs, a missing trunk assignment in the provider dashboard) and call
again.

For an allowlisted manual SIP connection, the incoming-call test also fails if
those Allowed Source IPs would block a real inbound call.

## 5. Assign agents and take a call

With the number verified, you assign inbound / outbound agents the
same way as a ThunderPhone number. See
[Handle inbound calls](/guides/handle-inbound-calls) and
[Place outbound calls](/guides/place-outbound-calls).

## Rotating credentials

When a provider key rotates, re-run the test-then-update flow:

```bash
# 1. Test the new credentials
curl -X POST https://api.thunderphone.com/v1/voip-connections/test ...

# 2. PATCH the connection with the new evidence
curl -X PATCH https://api.thunderphone.com/v1/voip-connections/{id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": { "apiKey": "NEW_KEY..." },
    "verification_evidence_id": "fresh-evidence-id"
  }'
```

The connection stays in place — no need to re-import numbers.

---

## Next steps

<CardGroup cols={2}>
  <Card title="VoIP connections reference" icon="phone-volume" href="/api-reference/voip-connections">
    Every field on the connection, evidence, and import responses.
  </Card>
  <Card title="Phone numbers reference" icon="phone" href="/api-reference/phone-numbers">
    Assign agents, transfer between orgs, release numbers.
  </Card>
  <Card title="Place outbound calls" icon="arrow-up-right" href="/guides/place-outbound-calls">
    Now that you own the number, start placing outbound.
  </Card>
</CardGroup>

<!-- en: guides/sip-addresses -->
---
title: "Connect over SIP (no phone number)"
description: "Send calls to a ThunderPhone agent straight from your PBX, carrier or SIP application, with a one-time SIP URI per call or a permanent SIP address."
---

If your own system already handles phone numbers (a PBX, a contact-center
platform, or a carrier account where you rotate numbers), you can send calls to
a ThunderPhone agent over plain SIP. You don't import or buy a number on
ThunderPhone. Your system dials a SIP address and the agent answers.

There are two kinds of SIP address:

| | **Per-call SIP URI** | **SIP endpoint** |
|---|---|---|
| Looks like | `sip:c-<token>@sip.thunderphone.com` | `sip:agent-<id>-<letters>@sip.thunderphone.com` |
| Created with | `POST /v1/calls/register-sip`, once per call | `POST /v1/sip-endpoints`, once |
| Authentication | The one-time token in the address | SIP digest username + password (and optionally a source-IP allowlist), or a source-IP allowlist alone for platforms that authenticate by IP |
| Good for | Apps that already call an API before transferring a call; per-call variables | PBXs and carriers that should just "point a trunk" at ThunderPhone |
| Valid for | 5 minutes, one call | Until you delete it |

Both kinds route to one agent in your organization, and both show up in call
history like any other inbound call.

## Per-call SIP URI

### 1. Register the call

```bash
curl -X POST https://api.thunderphone.com/v1/calls/register-sip \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 12,
    "to_number": "+14155550142",
    "variables": {"customer_name": "Ada"}
  }'
```

```json
{
  "call_id": 862197007562,
  "sip_uri": "sip:c-1790372992.Qm3xT8vLk2PzR7nYw4HbJa.uF6sD1gK9eW2cX5vB8nM0q@sip.thunderphone.com",
  "expires_at": "2026-09-25T21:49:52Z",
  "agent_id": 12,
  "to_number": "+14155550142"
}
```

- `to_number` (optional) is the number the caller dialed on your side. It is
  stored as the call's destination in call history, and the agent sees it as
  its own number.
- `variables` (optional) fill `{{placeholders}}` in the agent's prompt, the
  same way as for [outbound calls](/guides/call-variables).
- `call_id` is the id the call will have in call history
  (`GET /v1/calls/{call_id}`) once it connects.

### 2. Dial the URI

Send the call to `sip_uri` within 5 minutes. The URI works for one call only:
once a call has used it, it is spent, even if that call ends quickly.

With Twilio, for example, return this TwiML for the call you want to hand over:

```xml
<Response>
  <Dial>
    <Sip>sip:c-1790372992.Qm3xT8vLk2PzR7nYw4HbJa.uF6sD1gK9eW2cX5vB8nM0q@sip.thunderphone.com;transport=tcp</Sip>
  </Dial>
</Response>
```

From a PBX, dial the URI as a SIP destination. No username or password is
needed; the token is the credential, so treat the URI like a password until it
has been used.

## SIP endpoint (permanent address)

### 1. Create the endpoint

```bash
curl -X POST https://api.thunderphone.com/v1/sip-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": 12, "name": "Main PBX"}'
```

```json
{
  "id": 7,
  "name": "Main PBX",
  "agent_id": 12,
  "sip_uri": "sip:agent-12-jhxmginwjx@sip.thunderphone.com",
  "auth": "digest",
  "username": "tp409667538f83",
  "password": "8mJ0…",
  "allowed_source_cidrs": [],
  "status": "active",
  "created_at": "2026-09-25T21:46:18Z"
}
```

<Warning>
  The `password` is returned only once, when the endpoint is created. Store it
  in your PBX or carrier configuration straight away. If you lose it, rotate it
  with `POST /v1/sip-endpoints/{id}/rotate-password`.
</Warning>

### 2. Point your system at it

Configure a SIP trunk or destination with:

| Setting | Value |
|---|---|
| SIP URI | the endpoint's `sip_uri` |
| Username / password | `username` / `password` (digest authentication; ThunderPhone challenges each call). None for an `ip_allowlist` endpoint (below) |
| Transport | TCP on port 5060 or TLS on port 5061 (recommended), or UDP on port 5060 |
| Codecs | G.711 (PCMU/PCMA) or G.722 |

<Note>
  Prefer TCP or TLS. UDP works from public addresses and from most NATs, but
  behind a "symmetric" NAT (one that uses a new port for every destination) the
  agent's hang-ups and transfers may not reach your system. A source-IP
  allowlist (below) also needs TCP or TLS. Over TLS, SIP signaling stays
  encrypted past `sip.thunderphone.com` too, all the way to the servers that
  handle the call.
</Note>

These transport and codec settings apply to per-call URIs too. Two network
details matter for both kinds of address:

- **Follow Record-Route.** After the first INVITE, the rest of the call's
  signalling (ACK, hang-up, transfers) goes to the specific ThunderPhone server
  that answered, which is named in the `Record-Route` header
  (`sip-1.thunderphone.com` or `sip-2.thunderphone.com`, or its IP address).
  If you restrict outbound SIP, allow those hosts as well as
  `sip.thunderphone.com`: `172.170.39.202` (`sip`), `13.86.104.121`
  (`sip-1`) and `20.80.98.90` (`sip-2`).
- **Audio goes elsewhere.** `sip.thunderphone.com` carries signalling only.
  Allow media (RTP) to the addresses and ports in the SDP answer.

Every call to the address reaches the endpoint's agent, whatever number your
caller dialed on your side. You never import numbers, so rotating them on your
side needs no change on ThunderPhone.

### Pass the dialed number (optional)

To record which of your numbers the caller dialed, send it on the INVITE in an
`X-Original-To` header (for example `X-Original-To: +14155550142`) or in a
standard `Diversion` header. ThunderPhone stores it as the call's destination.

The destination is chosen in this order: the `to_number` given when a per-call
URI was registered, then a number in `X-Original-To`, then one in `Diversion`.
If none of these gives a number, it is shown as `sip:agent-12-jhxmginwjx` (the
endpoint's address) for an endpoint, or `sip:call` for a per-call URI.

With Twilio you can add the header to the SIP URI:
`sip:agent-12-jhxmginwjx@sip.thunderphone.com;transport=tcp?X-Original-To=%2B14155550142`.

### Restrict source IPs (optional)

Set `allowed_source_cidrs` to only accept calls from your own signalling
addresses, on top of the username and password:

```bash
curl -X PATCH https://api.thunderphone.com/v1/sip-endpoints/7 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allowed_source_cidrs": ["203.0.113.0/28"]}'
```

Calls from any other address are refused before they reach the agent. Use the
addresses your system sends SIP signalling from (for a carrier such as Twilio,
its published signalling IP ranges), not your media addresses.

<Warning>
  The allowlist is checked for calls over TCP or TLS only. A UDP source address
  can be forged, so an endpoint with an allowlist refuses every call that
  arrives over UDP. Send calls to it with `;transport=tcp` (port 5060) or over
  TLS (port 5061).
</Warning>

### Platforms that authenticate by source IP

Some contact-center platforms, such as Talkdesk, Amazon Connect and Amazon
Chime Voice Connector, identify themselves only by the addresses
they send SIP from and document no password authentication. For these, create
the endpoint with `auth` set to `ip_allowlist` and list the platform's SIP
signalling ranges:

```bash
curl -X POST https://api.thunderphone.com/v1/sip-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 12,
    "name": "Amazon Chime",
    "auth": "ip_allowlist",
    "allowed_source_cidrs": ["3.80.16.0/23", "99.77.253.0/24"]
  }'
```

The response has `"username": null` and no `password`. Point the platform at
the `sip_uri` over TLS (port 5061) or TCP (port 5060): an `ip_allowlist`
endpoint refuses every call over UDP, because a UDP source address can be
forged.

The list must have at least one entry. Each must be a public IPv4 range of
`/16` or narrower or an IPv6 range of `/48` or narrower. Use the signalling
ranges the platform publishes for the regions you use, not its media ranges
and not a whole cloud provider's.

To switch an existing endpoint, `PATCH` it with `auth` (and
`allowed_source_cidrs` if its list doesn't meet these rules). Switching back
to `digest` returns a new password once.

<Warning>
  Without a password, the SIP address and the allowlist together are the
  credential. A platform's addresses are shared by all its customers, so
  anyone on the same platform who learns the address can call your agent, and
  those calls are billed to you. Keep the `sip_uri` private, list only the
  ranges you need, and check call history for calls you don't expect. To
  change the address, create a new endpoint and delete the old one.
</Warning>

### Platforms that dial a phone number

Five9, NICE CXone and Zoom Contact Center send a call to a phone number and
can't dial the endpoint's `agent-…` address. Give an `ip_allowlist` endpoint
up to 5 `dial_in_numbers`: the platform then sends its INVITE to
`sip:<number>@sip.thunderphone.com` and reaches the endpoint's agent. Zoom
Contact Center also needs TLS with SRTP, so set `srtp` to `required` (SRTP,
like dial-in numbers, is available on `ip_allowlist` endpoints only):

```bash
curl -X POST https://api.thunderphone.com/v1/sip-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 12,
    "name": "Zoom Contact Center",
    "auth": "ip_allowlist",
    "allowed_source_cidrs": ["203.0.113.0/24", "198.51.100.0/24"],
    "dial_in_numbers": ["999123456789012"],
    "srtp": "required"
  }'
```

Replace the example ranges (documentation addresses, which the API refuses)
with your platform's SIP signalling ranges. Enter each number exactly as the
platform dials it, with or without the `+`
(Zoom's 15-digit `999…` numbers have none); spaces, dashes and parentheses are
removed. A number counts as an address, not a password: calls to it are
checked against `allowed_source_cidrs` and must arrive over TCP or TLS, the
same as calls to the `sip_uri`. A number can't already be in use on
ThunderPhone, as a phone number or on another SIP endpoint; creating or
updating with one returns `409`. To change the list, `PATCH` the endpoint with
the full new `dial_in_numbers`.

<Warning>
  A number is easier to guess than an `agent-…` address, and the platform's
  ranges are shared by all its customers: anyone else on the same platform who
  dials the number reaches your agent, and they control the call's SIP headers
  (`From`, `X-…`, `User-to-User`). Use a number nobody would guess where you
  choose it, don't publish it, and don't let the agent treat SIP context as
  proof of who is calling.
</Warning>

Calls to a dial-in number are SIP-address calls: no ThunderPhone number
carries them, so they don't appear under phone numbers and have no
phone-number charge. The call's destination is the number in `X-Original-To`
or `Diversion` when the platform sends one, otherwise the dial-in number.

## Pass call context in SIP headers

A contact-center platform or PBX usually knows things about the call before
it reaches the agent: its own call or contact id, what the caller chose in
the IVR, the account number they entered. Send them as SIP headers on the
INVITE and the agent can use them.

ThunderPhone reads two kinds of header:

- every header whose name starts with `X-` (for example
  `X-Amzn-ConnectContactId` or `X-Intent`), except `X-TP-*` and `X-LK-*`,
  which ThunderPhone's own SIP servers use and are always dropped;
- `User-to-User` (UUI). A value marked `;encoding=hex` is decoded to text
  when it decodes to UTF-8; the value as sent is kept as well.

This works on both kinds of SIP address, and on numbers imported through a
[manual SIP connection](/guides/bring-your-own-numbers). It does not apply to
ThunderPhone numbers or to numbers on a Twilio or Telnyx connection.

### Use them in the prompt

Each header becomes a [call variable](/guides/call-variables) named `sip_`
plus the header name in lower case, with every run of characters other than
letters and digits turned into one `_`:

| Header | Variable |
|---|---|
| `X-Amzn-ConnectContactId` | `{{sip_x_amzn_connectcontactid}}` |
| `X-Intent` | `{{sip_x_intent}}` |
| `User-to-User` | `{{sip_uui}}` (decoded) and `{{sip_uui_raw}}` (as sent, only when it was hex-encoded) |

A header only reaches the agent where its prompt names it; nothing is added
to the conversation otherwise. A variable of the same name from
`register-sip` or from your [call setup webhook](/webhooks/call-incoming)
wins over the header. Give each placeholder a default
(`{{sip_x_intent|unknown}}`) so calls without the header still read well.

<Warning>
  Header values come from whoever sends the call, and on some routes a
  caller can set them. Treat them like anything a caller says: use them as
  context, not to decide who the caller is or what they may do.
</Warning>

### Limits

At most 32 headers per call, 1,024 characters per value and 8 KB in total;
headers past these limits are dropped. Control characters are removed.

### Where they show up

- **Call history:** `GET /v1/calls/{call_id}` returns `sip_headers` (header
  name in lower case → value), or `null` for a call without any.
- **Your platform's call id:** the first of these headers the call carried is
  stored as the call's `external_call_id`: `X-Amzn-ConnectContactId` (Amazon
  Connect), `x-inin-cnv` (Genesys Cloud, with the trunk's Conversation Headers
  setting on), `X-Talkdesk-Interaction-Id` (Talkdesk), `X-ZOOM-Call-Sid` (Zoom
  Contact Center), `X-CallID` (Five9), `X-Call-ID` (set it yourself on any
  other platform) and `X-Genesys-Conversation-Id`. When the agent hands the call back to your
  platform, [`GET /v1/calls/handoff`](/api-reference/calls#look-up-a-handed-off-call)
  finds the call by it.
- **Webhooks:** the [`telephony.incoming`](/webhooks/events#telephonyincoming)
  event includes `sip_headers` when the call carried some. For numbers on a
  manual SIP connection, so does the blocking
  [call configuration request](/webhooks/call-incoming#request-payload) and
  the agent's call setup webhook.

## What callers and your system see

- **Caller ID:** the user part of the `From` header is stored as the caller.
  A phone number (digits, optionally with `+`, spaces, dashes, dots or
  brackets) is normalized to E.164; anything else, such as a SIP username, is
  kept as sent. At most 32 characters are kept, and a missing caller is stored
  as `anonymous`.
- **Refused calls:** an unknown or expired per-call URI gets SIP
  `404 Not Found`. An already-used per-call URI, a disabled endpoint, or a
  source outside the allowlist (including any UDP call to an endpoint with an
  allowlist) is disconnected before the agent starts: your system may see the
  call fail, or connect and then end straight away. These refusals do not
  create a call-history entry. If your organization is out of credit or has
  reached its spending limit, the call is refused and shows in call history as
  a failed call with no charge. To retry a per-call attempt, register a new URI.
- **Transfers:** the agent's cold transfers work (ThunderPhone sends a SIP
  `REFER`, which your system must accept). A transfer number can also be a SIP
  address in your system, such as a queue, with SIP headers for it to read; see
  [Transfer to a SIP address](/guides/call-transfers#transfer-to-a-sip-address).
  The agent can also hand the call back by hanging up with routing headers on
  the `BYE`; see
  [Return the call to your contact center](/guides/call-transfers#return-the-call-to-your-contact-center).
  Warm transfers are not available on
  SIP-address calls, because there is no ThunderPhone number to show as caller
  ID for the second leg. With Twilio, the TwiML above connects the agent but
  does not handle transfers: add `referUrl="https://YOUR_SERVER/sip-transfer"`
  to the `<Dial>`, and have that webhook read `ReferTransferTarget` and return
  TwiML that dials the transfer destination (see Twilio's
  [SIP REFER guide](https://www.twilio.com/docs/voice/api/refer-to-twilio)).
- **Text messages:** the SIP address and the dialed number can't send texts.
  The agent can text during a SIP-address call only if it has a separate
  SMS-capable number set up for texting; otherwise its SMS tool is
  unavailable.
- **Registration:** ThunderPhone does not accept SIP `REGISTER`. Send calls to
  the address; don't register to it.

## Pricing

SIP-address calls are billed like any other call. There is no phone-line
part, because no ThunderPhone number carries the call. Your
own carrier bills its side of the call as usual. See
[Pricing](/guides/pricing).

## Test it

1. Create a per-call URI or an endpoint as above.
2. Dial it from your system, or from any SIP softphone (for a `digest`
   endpoint, enter the username and password; an `ip_allowlist` endpoint only
   answers calls from its allowed ranges).
3. After hanging up, open the call in **Calls** in the dashboard, or fetch it
   with `GET /v1/calls/{call_id}`. It shows the caller, the destination
   (see the order under "Pass the dialed number") and the transcript.

API details: [SIP addresses API reference](/api-reference/sip-addresses).

<!-- en: guides/dynamic-call-config -->
---
title: "Dynamic per-call configuration"
description: "Pick the answering agent — or rewrite its prompt and settings — separately for every incoming call, driven by custom logic in a webhook you control."
---

By default every phone number and publishable key has a static agent
assigned. When you need **per-caller** or **per-visitor** customization
— VIP routing, logged-in user context, A/B prompt tests — switch to
webhook-mode and let your server decide.

<Tip>
  Want the number to keep its agent and only fill in that agent's
  variables and context per call? Give the agent a
  [call setup webhook](/webhooks/call-incoming#agent-call-setup-webhook)
  instead: the number stays assigned to the agent (and can be pinned to
  one of its versions), and your webhook answers with just the call's
  `variables` and `context`.
</Tip>

## How it works

1. You subscribe to the [`telephony.incoming`](/webhooks/events#telephony-incoming)
   (phone) or [`web.incoming`](/webhooks/events#web-incoming) (widget)
   event. Both are **blocking** webhooks: ThunderPhone waits for your
   response before continuing the call, up to 13 seconds for a phone
   call (one retry included) and 10 seconds for a widget session.
2. ThunderPhone sends you `{call_id, from_number, to_number}` (widget
   sessions carry widget-specific fields instead of numbers — see the
   [request schema](/webhooks/call-incoming)).
3. Your server responds with an agent configuration (prompt, voice,
   product, tools, words). ThunderPhone uses that configuration for the call.
4. There is no fallback agent. If you return `{}` or an invalid
   configuration, or the request still fails after its
   [retry](/webhooks/call-incoming#timeouts-and-retries), the phone
   call is ended right away and recorded with `end_reason`
   `inbound_config_webhook_failed`; a widget session request fails.

<Note>
  Works identically for phone calls (`telephony.incoming`) and widget
  sessions (`web.incoming`), whether delivered to a webhook endpoint
  or to the legacy single-URL webhook.
</Note>

<Warning>
  **No ThunderPhone consent announcement plays on inline webhook-configured
  calls.** This path bypasses the agent-level call-start announcement
  and is expressly excluded from ThunderPhone's consent-announcement
  framework (Terms of Service, "Recording and consent" section). Your
  organization owns all recording, monitoring, AI-participation, and
  caller-identification notices and consents on these calls. Provide
  them in your own flow — for example in the prompt's opening script —
  before enabling inline webhook mode. A webhook response that references a
  saved `agent_id` uses that agent's normal recording and disclosure policy.
</Warning>

## 1. Configure the webhook destination

<Tabs>
<Tab title="Phone calls">
For phone numbers, subscribe your endpoint to `telephony.incoming`:

```bash
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Prod call-incoming",
    "url":    "https://example.com/thunderphone/incoming",
    "events": ["telephony.incoming"]
  }'
```

The response includes a one-shot `secret` — save it; you'll use it
for signature verification.
</Tab>
<Tab title="Web widget">
For widget sessions, create a publishable key in `mode="webhook"`
with your endpoint URL baked in:

```bash
curl -X POST https://api.thunderphone.com/v1/publishable-key \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":            "Dynamic widget",
    "mode":            "webhook",
    "webhook_url":     "https://example.com/thunderphone/widget-incoming",
    "allowed_domains": ["example.com"]
  }'
```

The widget will POST to this URL on every session start.
</Tab>
</Tabs>

## 2. Implement the handler

Three rules of thumb:

- **Verify the signature** on every request (see
  [Verify webhook signatures](/guides/verify-webhook-signatures)).
  Don't skip this in dev — get it right once and reuse.
- **Respond fast**. A phone call's first attempt is cut off at 10
  seconds and the whole exchange at 13, and every second is dead air
  for the caller. Do database lookups if you need to, but don't call
  downstream LLMs synchronously — if you want dynamic prompt
  generation, pre-compute and cache.
- **Fall back cleanly**. For any unexpected state, answer with a
  default `prompt` and `voice` (or a saved `agent_id`). Returning `{}`
  or an error status ends the call.

<CodeGroup>
```python FastAPI
import hashlib
import hmac
import json
import os

from fastapi import FastAPI, HTTPException, Request

app = FastAPI()
SECRET = os.environ["THUNDERPHONE_WEBHOOK_SECRET"]

def verify(body: bytes, sig: str) -> bool:
    expected = hmac.new(SECRET.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig or "")

@app.post("/thunderphone/incoming")
async def incoming(request: Request):
    body = await request.body()
    if not verify(body, request.headers.get("X-ThunderPhone-Signature", "")):
        raise HTTPException(401)

    event = json.loads(body)
    if event["type"] not in ("telephony.incoming", "web.incoming"):
        return {}  # fall back to default

    caller = event["data"]["from_number"]
    # Cheap DB lookup: is this a known VIP?
    customer = lookup_customer(caller)
    if customer and customer.tier == "vip":
        return {
            "prompt":  f"You are a VIP concierge for {customer.name}. Be proactive…",
            "voice":   "john",
            "product": "storm-base",
        }
    return {}  # default agent handles non-VIPs

def lookup_customer(phone: str):
    # ... your CRM integration ...
    pass
```

```javascript Express
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.THUNDERPHONE_WEBHOOK_SECRET;

function verify(body, sig) {
  const expected = crypto.createHmac("sha256", SECRET).update(body).digest("hex");
  return sig &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
}

app.post(
  "/thunderphone/incoming",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    if (!verify(req.body, req.header("X-ThunderPhone-Signature"))) {
      return res.sendStatus(401);
    }
    const event = JSON.parse(req.body.toString("utf8"));

    const IMPORTANT_TYPES = new Set([
      "telephony.incoming",
      "web.incoming",
    ]);
    if (!IMPORTANT_TYPES.has(event.type)) return res.json({});

    const customer = await lookupCustomer(event.data.from_number);
    if (customer?.tier === "vip") {
      return res.json({
        prompt:  `You are a VIP concierge for ${customer.name}. Be proactive…`,
        voice:   "john",
        product: "storm-base",
      });
    }
    res.json({}); // fall back to default agent
  },
);
```
</CodeGroup>

## 3. Response schema

The response body matches the
[incoming-call response schema](/webhooks/call-incoming#response-schema)
exactly. The commonly-used fields:

| Field | Type | Description |
|-------|------|-------------|
| `prompt` | string (required) | System prompt for the agent |
| `voice` | string (required) | Voice id from [`GET /v1/voices`](/api-reference/agents#voices) |
| `product` | string | Defaults to `spark`. |
| `background_track` | string \| null | Ambient audio id |
| `acknowledgement_prompt_mode` | string | `auto` or `manual` (Storm-with-ack only) |
| `acknowledgement_prompt` | string | Required when mode is `manual` |
| `language_switching` | string | For multilingual agents, `ask_first` or `follow_caller` |
| `tools` | array | Inline function-tool schemas — see [Function Tools](/tools/overview) |

<Note>
  Per-call speak-order and `max_hold_seconds` aren't available on the
  webhook response. Set them on the
  [Agent](/api-reference/agents) you reference.
</Note>

### Keep a saved agent and supply variables or context

Return `{"agent_id": 12, "variables": {"name": "Ada"}}` to use that organization's
saved agent with per-call data. Its prompt can contain `{{name}}` or
`{{name|Friend}}`. Webhook variables merge over request-level variables; null
uses the placeholder default, or empty text if none is provided. The final
values and unresolved names appear in call details and completion webhooks.
Add `context`, a free-form string of up to 20,000 characters, to give the agent
a brief for this call (notes from your CRM, the reason you expect the call);
it is added after the prompt in a delimited block.
Saved-agent responses accept only `agent_id`, `variables`, `context`, `timezone` and `language`. If `prompt` is
present, the response uses inline configuration and ignores `agent_id` (including
null or non-integer metadata); the inline prompt must still be valid. Inline
configuration responses may also include `variables` and `context`. Saved-agent responses use
the agent's deployed A/B split on both phone and widget calls, then render variables. See [call variables](/guides/call-variables)
for limits and session API support. Blocking configuration comes from the legacy
phone-number/organization URL or a webhook-mode widget key; endpoint-system
incoming events are notifications only.

### Set the time zone per call

One agent can answer for contacts in different time zones. Add `timezone`, an
IANA name, to a saved-agent or inline response and the agent states the date
and time and offers times in that zone for this call, ahead of the agent's own
time zone:

```json
{"agent_id": 12, "timezone": "America/Chicago", "variables": {"name": "Ada"}}
```

Send the zone rather than a timestamp in `variables`: the agent's clock keeps
running during the call, and a time you pass in goes stale. A value that is not
an IANA zone is ignored and the call connects in the agent's zone.

### Set the language per call

One agent can answer in each of its languages. Add `language`, a supported
language code such as `es` (`es-MX` is read as `es`), next to `agent_id` and the
call starts in that language:

```json
{"agent_id": 12, "language": "es", "variables": {"name": "Ada"}}
```

The agent speaks it with its voice for that language: its
[`language_voices`](/api-reference/agents#deployed-fields) entry; else, with
`native_voice_switching` on, the native voice the agent would switch to for
that language; else its own voice, when that voice speaks the language. Then
the agent's other languages and its primary language stay available for
switching. If none of these can speak it, the call still starts in that
language, with the language's default voice (an agent with a custom voice keeps
it) and no other languages. Only a code that is not a supported language is
rejected. Widget and realtime sessions take the same `language` field.

## Patterns

### Logged-in user context

In webhook-mode widgets, the visitor's page already knows who they
are. Call your webhook with a query string parameter the widget SDK
forwards (`?customer_id=123`) and look up the customer server-side.

### A/B prompt rollout

Before you hand-roll this, note that ThunderPhone has a native
[Experiments](/guides/concepts#experiments) feature
(`/dashboard/experiments` and the agent builder's **A/B** tab) that
defines variants, splits traffic, and compares outcomes per variant —
no webhook required.

If you need webhook-side control anyway: hash `call_id` → bucket;
serve prompt A for `0..49` and prompt B for `50..99`. Record which
bucket you chose in your own DB and later correlate against the
completed call's grade.

### Time-based routing

Business hours → "live support" agent; after-hours → "take a message"
agent. Pure switch on `new Date().getUTCHours()` in your handler.

---

## Next steps

<CardGroup cols={2}>
  <Card title="Incoming-call webhook reference" icon="phone" href="/webhooks/call-incoming">
    Exact request + response schemas, including every configuration key.
  </Card>
  <Card title="Verify webhook signatures" icon="shield-check" href="/guides/verify-webhook-signatures">
    Get the HMAC right once; reuse everywhere.
  </Card>
  <Card title="Build a tool integration" icon="screwdriver-wrench" href="/guides/build-tool-integration">
    Combine dynamic routing with per-agent tools.
  </Card>
  <Card title="Delivery semantics" icon="bolt" href="/webhooks/overview">
    Retries, ordering, timeouts.
  </Card>
</CardGroup>

<!-- en: guides/call-variables -->
---
title: "Per-call variables and context"
description: "Give each call its own details, as named variables for the prompt or a free-form brief, without changing the agent."
---

Each call can carry two kinds of per-call input. Use either one, or both
together:

- **`variables`**: named values that fill `{{placeholders}}` in the prompt. Use
  them for fields the prompt refers to by name, such as the caller's name, an
  account number or an appointment slot.
- **`context`**: free-form text added after the prompt. Use it for a brief that
  does not fit a template, such as a description of the task for this call or
  notes collected earlier.

Both work with a saved agent and with an inline configuration, on every way of
starting a call described below. Neither changes the saved agent, its version
history or its other settings.

```json
{
  "agent_id": 12,
  "variables": {"name": "Ada", "appointment_slot": "Tuesday at 10 AM"},
  "context": "Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number."
}
```

## Variables

Put placeholders in your saved agent's prompt, then supply a `variables`
object when starting a call. ThunderPhone renders the text before sending the
call configuration to the voice runtime.

When no values are needed, omit `variables`, do not send `null` (rejected with `400`).

### Placeholders and defaults

```text
You are calling {{name|Friend}} about account {{account_id}}.
The available appointment is {{ appointment_slot }}.
```

Names are case-sensitive and follow `[A-Za-z_][A-Za-z0-9_]*`. Whitespace around
the name is allowed; whitespace after `|` is part of the default and is
preserved. `{{name|Friend}}` uses `Friend` when `name` is missing or
`null`; an empty string is an explicitly supplied value. Missing values without
a default become empty strings and their names appear in `unresolved_variables`.
Text between double braces that is not a valid placeholder is removed. Double-braced
text inside each supplied value is removed independently; a value cannot remove
surrounding prompt text or another value. Unmatched double-brace delimiters are
removed too. JSON examples in prompts must not use `{{`.
Values are plain text, never evaluated
as code or recursively expanded as templates.

Variables can also appear in acknowledgement prompts, outbound voicemail
messages, and the consent announcement text when that field is sent for a
phone call. The agent has no separate `first_message` field: put its opening
instructions in the prompt. Existing voicemail `{agent_name}` and `{org_name}`
placeholders continue to work.

### Values and limits

Values may be strings, numbers, booleans, or `null`; booleans render as `true`
and `false`. Unicode control (`Cc`) characters except newline (`\n`), tab (`\t`),
and carriage return (`\r`), format (`Cf`) characters except the zero-width
non-joiner and joiner (U+200C, U+200D, which spell words in Indic and
Arabic-script languages), and surrogate (`Cs`) code points are removed; `\r\n`
is normalized to `\n`. Each value
is limited to 2,000 characters when rendered. Supplied strings are cleaned and
truncated before storage as well. The original object must fit in **32 KB of
UTF-8 JSON**; larger objects receive `400` on call/session requests, while
campaign imports report invalid rows individually. Arrays and nested objects are not
accepted as values. Nonmatching metadata keys (for example a CSV header with a
space) are retained and echoed but cannot be referenced by a placeholder.

## Context

`context` is a string of up to **20,000 characters**. ThunderPhone adds it after
the prompt, once the prompt's variables are filled in, as a delimited block:

```text
<your prompt, with its variables filled in>

Details for this call:
<call_context>
Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number.
</call_context>
```

The agent reads it together with its instructions, so write it the way you
would brief a colleague before the call. Context is not a template:
`{{name}}` inside it stays as written. If the text needs a value, put the value
in yourself before sending.

- `null`, an empty string, or only whitespace means no context.
- A value that is not a string, or is longer than 20,000 characters, is
  rejected with `400` on call and session requests; from a configuration
  webhook it fails the exchange like invalid `variables` (see below).
- Leading and trailing whitespace is trimmed, and the same control and format
  characters as in variable values are removed.
- Context is part of the call's prompt, so it counts toward the call's
  [prompt size](/guides/pricing#how-a-call-is-priced).

On a [steps](/guides/agent-steps) agent, the context follows the prompt of
every agent in the call, not each step's instructions.

## Where values come from

### Outbound API

Send `variables` and `context` on `POST /v1/call`:

```json
{
  "from_number": "+15551234567",
  "to_number": "+14155552671",
  "agent_id": 12,
  "variables": {
    "name": "Ada",
    "account_id": "A-17",
    "appointment_slot": "Tuesday at 10 AM"
  },
  "context": "Ada asked to be called back about the late fee on her March invoice."
}
```

Both also work with the phone number's default outbound agent, or with an inline
`config.prompt`. With an inline config, `context` can also go inside `config`,
the same field a configuration webhook returns; if you send both, they must be
the same text. An idempotency key cannot be reused with different variables or
a different context.

### Campaign CSV

Non-phone CSV columns are already stored as contact variables. Each dial now
uses them automatically. Use headers such as `name`, `account_id`, and
`appointment_slot` to match your placeholders. The existing name mapping can
combine first and last name columns into the variable `name`. Campaign
contacts have no per-contact context.

### Dynamic configuration webhook

On the blocking configuration webhook path, return a saved agent in your
organization plus any per-call values:

```json
{
  "agent_id": 12,
  "variables": {"name": "Ada", "account_id": "A-17"},
  "context": "Ada called yesterday about a leak in unit 4B; a plumber is booked for Friday."
}
```

The response's variables overwrite request-level variables, while other request
keys remain. A response value of `null` selects the placeholder's default.
The merged object must also fit in 32 KB. Saved-agent responses accept only
`agent_id`, `variables`, `context` and a per-call
[`timezone`](/guides/dynamic-call-config#set-the-time-zone-per-call); return an inline configuration when you need to
replace the prompt or other settings. A response containing `prompt` always uses inline
configuration: any `agent_id` in that response is ignored, including null or
non-integer metadata. The inline prompt still must pass normal validation.
Inline webhook responses can include `variables` and `context` too. A `context`
that is not a string or is too long fails the exchange: a phone call is
rejected, and a widget session request fails with `400`. Saved-agent webhook
responses use the agent's deployed A/B split on both phone and widget calls;
variables render after variant selection. On inbound phone calls, use a number with no assigned inbound
agent and configure its phone-number or organization webhook; widget keys use
`mode="webhook"`. Endpoint-system incoming notifications do not supply blocking
configuration responses.

### Agent call setup webhook

To keep a number assigned to its agent and fill in only the call's values,
give the agent a [call setup webhook](/webhooks/call-incoming#agent-call-setup-webhook).
Before each inbound call the agent answers on a number, the webhook gets the
call and the agent's id, name and version, and answers with the same
`variables` and `context` as above, without needing an `agent_id`. An agent
whose settings use a placeholder with no default needs this webhook to answer
a phone number: the call does not start when the webhook fails. Placeholders
with a default, like `{{name|there}}`, let the agent answer without it.

### SIP headers

Calls that reach an agent over SIP (a [SIP address](/guides/sip-addresses), or
a number on a manual SIP connection) can carry context in `X-*` and
`User-to-User` headers. Each one becomes a `sip_` variable, such as
`{{sip_x_amzn_connectcontactid}}` or `{{sip_uui}}`, with the lowest
precedence: a value of the same name from the API or a webhook wins. See
[Pass call context in SIP headers](/guides/sip-addresses#pass-call-context-in-sip-headers).
Header values are set by the sender, so treat them as untrusted, like any
browser-supplied value.

### Widget session API

`POST /v1/widget/session` accepts a top-level `variables` object. Its publishable
key selects the saved agent. Webhook-mode keys forward these values to the
configuration webhook and merge the response as described above.
Browser-supplied widget `variables` are client-controlled, forwarded
verbatim in `web.incoming` after the validation and string cleanup described
above, and echoed into completion webhooks and call history. Do not treat them
as trusted identity or authorization data.

The widget's own browser `context` field is different: it carries text from the
page the visitor is on, which the agent treats as website content (see
[Embed the web widget](/guides/embed-web-widget)). A widget call's per-call
context comes from a webhook-mode key's configuration webhook, as above. When a
call has both, the per-call context comes first, then the page content.

### Realtime session API

`POST /v1/realtime/sessions` accepts top-level `variables` and `context`
alongside `agent_id` or an inline `config`:

```json
{
  "agent_id": 12,
  "variables": {"name": "Ada"},
  "context": "Ada is calling from the front desk about a guest's lost key card."
}
```

`context` goes at the top level only; an inline `config` rejects it as an
unknown field.

### Realtime WebSocket

With a saved agent, the saved agent's deployed prompt stays its prompt.
`session.instructions` becomes the call's context, and `session.prompt.variables`
(or `session.config.variables`) become its variables. Choose the agent with
`session.prompt.id` in the first `session.update`, which starts the session once
that update arrives:

```json
{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "prompt": {"id": "12", "variables": {"name": "Ada"}},
    "instructions": "Ada asked for a callback about her delivery window."
  }
}
```

`?agent_id=12` on the connection URL starts the agent as soon as the socket
connects, before any `session.update`, so it carries no per-call input. Add
`&wait_for_session_update=1` to wait for the first `session.update` and use its
instructions and variables.

In an inline session (no saved agent), `session.instructions` is the prompt
itself, as before. Builder mic and simulated test calls resolve defaults and
missing placeholders but have no per-call variables or context input.

## After the call

`GET /v1/calls`, `GET /v1/calls/{call_id}`, `telephony.complete`, and `web.complete` include the
final merged `variables` and `unresolved_variables`. Legacy completion payloads
that include `data.history` include them too:

```json
{
  "variables": {"name": "Ada", "account_id": "A-17"},
  "unresolved_variables": ["appointment_slot"]
}
```

The call's `prompt_snapshot` (`GET /v1/calls/{call_id}`) shows the agent's
prompt with its variables filled in and the context block added.

Store your CRM or task identifier in the variables object to join the completed
call back to its source record. Variables and context are retained with the call
record; only send information appropriate to retain in call history and
webhooks.

Replays of a call, in [validation sets](/api-reference/validation-sets),
[replay runs](/api-reference/replay-runs) and
[investigations](/api-reference/investigations), use that call's variables and
context with the prompt under test, so a replay tests what the agent on that
call would have been told.

## Existing prompt compatibility

Rendering also applies to existing saved-agent and A/B variant prompts, inline
outbound and realtime configurations, and prompts returned by configuration
webhooks. Unknown `{{name}}` placeholders become blank text, even when no
`variables` are supplied. Check existing prompts before rollout, including
externally supplied inline/webhook prompts that ThunderPhone cannot inventory.
Builder mic and simulation calls apply the same default/blank behavior.

<!-- en: guides/build-tool-integration -->
---
title: "Build a tool integration (API)"
description: "Let your agent call your APIs mid-conversation — search a database, create a ticket, look up an order."
---

A **tool integration** is a reusable HTTP endpoint that an agent can
invoke during a call. You give ThunderPhone a JSON-schema description
of the tool plus an endpoint URL; the agent decides when to call it
based on the conversation, and ThunderPhone makes the outbound HTTP
request from its servers and returns the response to the agent.

<Note>
  The dashboard covers most tool needs without this API: **Connections
  → Apps** connects Slack, HubSpot, Salesforce, Google Calendar,
  Google Sheets, and Cal.com in a few OAuth clicks; **Connections →
  APIs** turns any HTTP API into an agent action (paste a cURL command
  and an AI wizard drafts the tool, with a built-in Test Request); and
  **Connections → MCP** adds MCP servers. See
  [Connections](/guides/concepts#connections). This guide is the raw
  API underneath the APIs surface.
</Note>

This guide walks through building a weather-lookup tool end-to-end.

## Anatomy of a tool

Two pieces:

1. **The schema** — an OpenAI-style function definition
   (`{type: "function", function: {name, description, parameters}}`)
   that tells the LLM what the tool does and what arguments it takes.
2. **The endpoint** — the URL ThunderPhone's servers call when the
   integration runs. For agent-triggered tools, the request is JSON
   POST with the LLM's chosen arguments as the body.

## 1. Choose an editor

<CardGroup cols={2}>
  <Card title="Dashboard" icon="window-maximize">
    Open **Connections → APIs**, create or edit the API connection,
    switch the parameter editor to **JSON**, and add the format there.
  </Card>
  <Card title="Integrations API" icon="plug">
    Create the spec with `POST /v1/integrations`, or update it with
    `PATCH /v1/integrations/{id}`.
  </Card>
</CardGroup>

Both paths create a saved integration. Attach that integration to the
agent after saving it. The Agents API has no writable inline `tools`
field. This guide uses the integrations API path.

## 2. Create the integration

```bash
curl -X POST https://api.thunderphone.com/v1/integrations \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Weather API",
    "spec": {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Return the current weather for a zip code.",
        "parameters": {
          "type": "object",
          "properties": {
            "zip": { "type": "string", "description": "5-digit US ZIP code" }
          },
          "required": ["zip"]
        }
      }
    },
    "endpoint_url":    "https://api.example.com/weather",
    "endpoint_method": "GET",
    "headers": [
      { "key": "X-Api-Key", "value": "your-provider-key" }
    ]
  }'
```

Save the returned `id` (a UUID). Header values are write-only: responses
list header names only, and a later `PATCH` can send a header without a
`value` to keep the stored one.

<Tip>
  Spend real effort on the `description` of the tool and of each
  parameter. The LLM uses these strings at runtime to decide whether
  and how to call the tool. Vague descriptions → vague tool calls.
</Tip>

### Declare `format: "email"` on address parameters

A parameter that receives an email address should say so in its
schema:

```json
"email": { "type": "string", "format": "email", "description": "The caller's email address" }
```

`format` is more than a hint. For a resolved email schema, before your
endpoint is called ThunderPhone trims the value, lower-cases the
domain, turns the standalone English words `at`, `dot`, `underscore`,
`dash`, and `hyphen` into their characters, and removes whitespace
directly around `@`, `.`, `_`, and `-`. The words have the same meaning
whether or not the transcript already contains a literal `@`:
`"john dot smith at gmail dot com"` becomes
`john.smith@gmail.com`.

Any other internal whitespace is rejected rather than silently joined.
Spoken separator words are English-only; non-English or unrecognized
spaced forms fail closed. Valid internationalized domains and SMTPUTF8
local parts are accepted. Punycode input remains punycode and Unicode
domain input remains Unicode after parser normalization, so your API
receives the caller-supplied conventional representation. If the final
value is invalid, the tool is **not called**. The agent receives
`invalid_email_argument` telling it
to confirm the spelling with the caller and resend the literal address.

An omitted optional email is untouched. `null`, an empty string, or a
whitespace-only string is also untouched when the property is optional
or nullable; the same values are rejected for a required, non-nullable
email.

Local schema references such as `#/$defs/email` and
`#/definitions/email`, plus `anyOf`, `oneOf`, and `allOf`, are inspected
with cycle and depth limits. A non-local or unresolvable `$ref` is a
known enforcement limit and is passed through unchanged, as is a call
whose tool snapshot has no usable schema. Keep email schemas local when
you need the gate to apply.

Parameters without an enforced email format are passed through exactly
as the model produced them.

Supported formats are `date-time`, `time`, `date`, `duration`,
`email`, `hostname`, `ipv4`, `ipv6`, and `uuid`; only `email` is
normalized and enforced today.

## 3. Sandbox-test the endpoint

Before you link the integration to an agent, fire a signed request
from ThunderPhone's servers to confirm connectivity:

```bash
curl -X POST https://api.thunderphone.com/v1/integrations/test-request \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url":    "https://api.example.com/weather?zip=94110",
    "method": "GET",
    "headers": { "X-Api-Key": "your-provider-key" }
  }'
```

```json Response
{
  "ok": true,
  "status": 200,
  "elapsed_ms": 187,
  "response_headers": { "content-type": "application/json" },
  "response_preview": "{\"temperature_f\": 64, ...}"
}
```

This test also hardens ThunderPhone's SSRF guards — requests to
localhost or private IP ranges return `400 code=url_not_allowed`.

## 4. Link the integration to an agent

Attach via `integration_ids` when you create or update an agent:

```bash
curl -X PATCH https://api.thunderphone.com/v1/agents/12 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_ids": ["f9b5a1a4-..."]
  }'
```

You can link many integrations to one agent. The agent's prompt can
reference them by name — "use `get_weather` when the caller asks
about conditions" — or it can discover them implicitly from the
schema descriptions.

## 5. Implement the endpoint

When the agent invokes the tool, ThunderPhone sends a signed POST to
your `endpoint_url`:

```
POST /weather HTTP/1.1
Host: api.example.com
X-Api-Key: your-provider-key
X-ThunderPhone-Signature-V2: t=<unix seconds>,v1=<HMAC-SHA256 hex>
X-ThunderPhone-Signature: <HMAC-SHA256 hex>
X-ThunderPhone-Call-ID: 987654321
Content-Type: application/json

{"zip": "94110"}
```

Your server responds with JSON that gets handed back to the LLM:

```json
{"temperature_f": 64, "condition": "Partly cloudy", "wind_mph": 8}
```

The LLM ingests that response and speaks a human summary to the
caller.

<Warning>
  The signature is computed over the raw request body using the same
  `secret` as your webhook endpoint. **Verify it** — tool endpoints
  are internet-facing and subject to the same spoofing concerns as
  webhooks. See
  [Verify webhook signatures](/guides/verify-webhook-signatures).
</Warning>

## 6. Test the loop

Run a [mic session](/api-reference/mic-sessions) against the agent
and ask the question your tool handles ("What's the weather in
94110?"). The call's transcript shows the full round trip:

```json
{
  "call_id": 987654321,
  "transcripts": [
    { "role": "user",
      "content": "What's the weather in 94110?" },
    { "role": "tool_call",
      "content": "{\"tool_call\": \"get_weather\", \"arguments\": {\"zip\": \"94110\"}}" },
    { "role": "tool_response",
      "content": "{\"tool_name\": \"get_weather\", \"response\": {\"temperature_f\": 64, \"condition\": \"Partly cloudy\"}}" },
    { "role": "agent",
      "content": "It's 64 degrees and partly cloudy." }
  ]
}
```

You can pull this via
[`GET /v1/calls/{call_id}/transcript`](/api-reference/calls#get-transcript);
the raw event stream (with per-entry timing and audio offsets) is at
[`GET /v1/calls/{call_id}/history`](/api-reference/calls#get-history).

In call-listing and analytics surfaces, ThunderPhone now reports test calls separately from real traffic. Browser Talk tests and simulations can reuse a real phone number and may look inbound, but they do not count toward production call totals, grades, or issue metrics.

## Common gotchas

<AccordionGroup>
  <Accordion title="Agent never calls the tool">
    The LLM decides based on the tool's description. If the caller's
    question doesn't match the description, the model won't invoke
    the tool. Tighten the description (add common synonyms and
    phrasing) or mention it explicitly in the agent prompt ("When the
    caller asks about weather, use `get_weather`.").
  </Accordion>

  <Accordion title="Tool returns too much data">
    A tool result stays in the conversation, and the agent re-reads it on
    every later turn, so a large result adds cost and delay to the rest of
    the call. A result over 100,000 characters is cut down to a preview, and
    the agent is told it is incomplete. On a very long call, older tool
    results may be dropped from the agent's memory; it can call the tool
    again if it needs them.

    To keep results small:

    - Return only the fields the agent needs, not your whole row.
    - Add a parameter so the agent can look up one item or category at a
      time instead of fetching everything.
    - Put large reference content (menus, catalogs, policies) in a
      [knowledge base](/guides/knowledge-base) instead.

    **Send Test Request** in the dashboard shows how big a result is and
    warns when it is large.
  </Accordion>

  <Accordion title="Timeouts">
    Tool endpoints have a 20-second default timeout. Set the tool's
    `timeout` to allow up to 180 seconds (see
    [Tools](/tools/overview)). For work that takes longer, handle it
    asynchronously: return `{"status": "pending", "request_id": "..."}`
    and surface the result via a separate tool call.
  </Accordion>

  <Accordion title="Versioning">
    Every integration `PATCH` creates a new revision. Inspect
    [`GET /v1/integrations/{id}/versions`](/api-reference/integrations#version-history)
    to see who changed what. If you break a tool's schema, you can
    roll back manually by PATCH-ing an older snapshot back in.
  </Accordion>
</AccordionGroup>

---

## Next steps

<CardGroup cols={2}>
  <Card title="Integrations reference" icon="plug" href="/api-reference/integrations">
    CRUD, transfer, version history.
  </Card>
  <Card title="Function Tools spec" icon="screwdriver-wrench" href="/tools/overview">
    Full JSON schema grammar and the signed-endpoint contract.
  </Card>
  <Card title="Verify signatures" icon="shield-check" href="/guides/verify-webhook-signatures">
    Apply the webhook-signature pattern to tool endpoints.
  </Card>
  <Card title="Transcript + history API" icon="phone" href="/api-reference/calls">
    Inspect the full round-trip of a tool call.
  </Card>
</CardGroup>

<!-- en: guides/test-agents -->
---
title: "Test an agent end-to-end (API)"
description: "Run one-shot simulations, parallel scenario batches, and release-gate suites through the ThunderPhone API so agent regressions are caught before customers hear them."
---

<Note>
  Prefer the dashboard? The same capability lives in **Simulations**
  (`/dashboard/simulations`), including AI scenario generation — see
  [Simulate a call](/guides/simulate-a-call). This page covers the
  programmatic path.
</Note>

Iterating on an AI agent means iterating on its prompt, its tools,
and the way it handles edge cases. The **simulations API** runs real
calls against an agent using a scenario prompt you supply. Targeting
an agent creates a bot-to-bot run; targeting a phone number creates a
SIP loopback run. Every run produces a real call log with
transcript, grading, and billing, so you see exactly how the agent
behaves and what it costs.

Use it for:

- Pre-deploy smoke tests after every prompt edit
- Regression suites wired into CI (hook `test-call.completed` webhook
  → fail the build if score drops)
- Stress-testing concurrency limits

## One-shot: single run

```bash
curl -X POST https://api.thunderphone.com/v1/simulations \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_type":     "agent",
    "target_id":       12,
    "direction":       "outbound",
    "scenario_prompt": "You are a polite caller asking about refund policy for order 12345.",
    "consent_to_charge": true
  }'
```

Fields:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `target_type` | string | yes | `agent` or `phone_number` |
| `target_id` | integer | yes | The agent id (or phone number id) |
| `direction` | string | no | `outbound` (default; test caller places) or `inbound` (test caller answers) |
| `scenario_prompt` | string | no | Drives what the test bot says |
| `language` / `primary_language` | string | no | Language for the test caller; unsupported codes are rejected |
| `simulator_product` | string | no | `testing` (default) or `spark` for a more human-like simulated caller, such as warm-transfer consult tests |
| `consent_to_charge` | boolean | **yes** | Must be `true`. The selected agent's side bills like a real call. The simulated caller is counted in the call's cost at a per-minute rate and marked up like any other part, with no separate fee (accounts on their earlier pricing pay a flat per-minute rate for it until December 1, 2026), plus any telephony leg ([pricing](/guides/pricing#simulations-and-testing)) |
| `target_number` | string | no | E.164 override for the remote side; otherwise the platform test number is used |

`mode` is read-only and derived from `target_type`: `agent` produces
`mode="bot"`, while `phone_number` produces `mode="sip"`.

The response is a [simulation run object](/api-reference/test-calls#test-call-run-object)
in `status="queued"`. Poll until `status` becomes `completed` or
`failed`; once `call_id` is set, load the transcript via
[`GET /v1/calls/{call_id}/transcript`](/api-reference/calls#get-transcript).

## Batches: parallel scenarios

Run N scenarios concurrently — useful for regression suites that
hit every known edge case in parallel:

```bash
curl -X POST https://api.thunderphone.com/v1/simulations/batches \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_type":     "agent",
    "target_id":       12,
    "direction":       "outbound",
    "run_count":       5,
    "stagger_seconds": 2,
    "scenario_prompts": [
      "Ask about refund policy.",
      "Ask for hours of operation.",
      "Complain about a delayed shipment.",
      "Ask to speak with a human.",
      "Ask an unrelated trivia question."
    ],
    "consent_to_charge": true
  }'
```

Response carries a `run_ids` list of child run ids. Fetch batch
status:

```bash
curl https://api.thunderphone.com/v1/simulations/batches/{batch_id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

`run_count` is capped at 20; `stagger_seconds` spaces out the spawn
to avoid hammering the agent (0–60 s).

## Hook it into CI

Create a release gate suite on the **Simulations** page
(`/dashboard/simulations`) — pick the agent, add scenarios by hand or
click **Generate scenarios with AI** to draft them from the agent's
prompt (with an optional edge-case pass), and group them into a suite.
A suite pins its scenarios and agent, plus a minimum pass rate and an
optional zero-critical-failures rule. Passing runs become the accepted
baseline; later pass→fail transitions are returned as regressions.

Use an [organization API key](/api-reference/developer-api-keys) in CI.
This script triggers the suite, polls until grading and comparison are
complete, and exits nonzero unless the verdict is `pass`:

```bash
#!/usr/bin/env bash
set -euo pipefail

: "${THUNDERPHONE_API_KEY:?Set THUNDERPHONE_API_KEY}"
: "${THUNDERPHONE_ORG_ID:?Set THUNDERPHONE_ORG_ID}"
: "${THUNDERPHONE_SUITE_ID:?Set THUNDERPHONE_SUITE_ID}"

base="https://api.thunderphone.com/v1/orgs/${THUNDERPHONE_ORG_ID}/suites/${THUNDERPHONE_SUITE_ID}"
auth="Authorization: Bearer ${THUNDERPHONE_API_KEY}"

run_id="$(curl --fail --silent --show-error -X POST "${base}/run" \
  -H "$auth" -H "Content-Type: application/json" -d '{}' | jq -r '.id')"

deadline=$((SECONDS + 1800))
while (( SECONDS < deadline )); do
  result="$(curl --fail --silent --show-error \
    "${base}/runs/${run_id}" -H "$auth")"
  status="$(jq -r '.status' <<<"$result")"
  if [[ "$status" == "completed" ]]; then
    jq . <<<"$result"
    [[ "$(jq -r '.verdict' <<<"$result")" == "pass" ]]
    exit
  fi
  sleep 10
done

echo "ThunderPhone suite timed out" >&2
exit 1
```

`POST /v1/orgs/{org_id}/suites/{suite_id}/run` returns `202` with the
run id. `GET /v1/orgs/{org_id}/suites/{suite_id}/runs/{run_id}` returns
`status`, `verdict`, `pass_rate`, `critical_failure_count`, and the
baseline `regressions` list. Both endpoints bind the URL organization
to the API key's organization.

## Run a suite on a schedule

Open the agent's **Simulate** tab, select **Release gate suites**, and create or
edit a suite. Turn on **Run on a schedule**, choose **Frequency** and
**Timezone**, then set **Minute past the hour**, **Local time**, or **Day** as
shown. Select **Save suite**. Unchecking **Run on a schedule** removes the
dashboard schedule.

### Via API

PATCH the suite to add or replace its schedule. See [Suites (release
gates)](/api-reference/test-scenarios#suites-release-gates) for the complete
suite object and endpoints.

```bash
curl -X PATCH https://api.thunderphone.com/v1/suites/{suite_id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": {
      "enabled": true,
      "frequency": "daily",
      "timezone": "America/Chicago",
      "hour": 6,
      "minute": 30
    }
  }'
```

`frequency` can be `hourly`, `daily`, or `weekly`. Use an IANA timezone.
Hourly schedules use `minute`; daily schedules use `hour` and `minute`;
weekly schedules also use `weekday`, where Monday is `0` and Sunday is `6`.
The suite response includes `next_run_at` and `last_run_at`.

Times follow the selected timezone's daylight-saving changes. Scheduled runs
appear in the suite's run history and use its current agent, scenarios,
criteria, and accepted baseline. Each generated test call emits
`test-call.completed`; there is no suite-level completion webhook. Scheduled
calls are billed at the same simulation rate as manual suite runs and record
`trigger: "schedule"` on the suite run.

To pause a schedule without changing its timing, PATCH the complete existing
schedule object with `"enabled": false`. `frequency` is required; omitted
timezone and time fields reset to their defaults, so include the existing
values. Send `"schedule": null` to remove the schedule.

## Patterns

### Per-prompt regression corpus

Maintain a JSON file of `{name, scenario_prompt, expected_outcome}`
tuples. On every prompt change, run the full set as a batch; diff the
transcripts and grades against the previous run.

### Per-release smoke test

A single batch of five happy-path scenarios you run after every
deploy. Latency-sensitive, so keep `stagger_seconds: 0`.

### Latency benchmarking

Run identical scenarios against different product tiers (`spark`,
`bolt`, `storm-base`) or Bolt intelligence tiers (`lite`, `standard`).
Compare the `call.graded` scores and the
`duration_seconds` from each resulting call log.

---

## Next steps

<CardGroup cols={2}>
  <Card title="Test calls reference" icon="flask" href="/api-reference/test-calls">
    Every query parameter, status code, and batch shape.
  </Card>
  <Card title="AI grading" icon="chart-line" href="/api-reference/calls#ai-call-grading">
    Auto-score every test run to track quality over time.
  </Card>
  <Card title="Issue reports" icon="triangle-exclamation" href="/api-reference/issue-reports">
    Flag specific tests for human review.
  </Card>
  <Card title="test-call.completed webhook" icon="bolt" href="/webhooks/events#test-call-completed">
    Stream results into your CI / Slack / PagerDuty.
  </Card>
</CardGroup>

<!-- en: guides/contact-centers/overview -->
---
title: "Contact centers"
description: "Send calls from Amazon Connect, Five9, Genesys Cloud, Talkdesk, Twilio, Microsoft Dynamics 365, NICE CXone or Zoom Contact Center to a ThunderPhone agent over SIP, and get them back with the agent's hand-off."
---

A ThunderPhone agent can answer calls inside your contact center's call flow.
Your platform sends the call to the agent's [SIP address](/guides/sip-addresses)
with SIP headers that carry its own call id and anything else it knows about
the caller. When the caller needs a person, the agent hands the call back with
a hand-off: a summary of what the caller needs, a short intent label and an id
your flow can look up.

## Platforms

| Platform | How the call arrives | Call-id header | How it comes back | How the context gets back |
|---|---|---|---|---|
| [Amazon Connect](/guides/contact-centers/amazon-connect) | External voice transfer connector; IP allowlist | `X-Amzn-ConnectContactId` | Return: the agent hangs up and the flow resumes | A Lambda calls the hand-off lookup |
| [Five9](/guides/contact-centers/five9) | AI Agent Connect, set up by Five9, to a dial-in number; IP allowlist | `X-CallID` | Return: the agent hangs up with routing headers on the `BYE` | `X-Route*` and `X-CustomMetaData` headers into IVR call variables |
| [Genesys Cloud](/guides/contact-centers/genesys-cloud) | BYOC Cloud trunk; digest | `x-inin-cnv` | `REFER`, accepted by Take Back and Transfer | Hex UUI inside the transfer address, then a data action |
| [Talkdesk](/guides/contact-centers/talkdesk) | Connect to Autopilot Voice; IP allowlist | `X-Talkdesk-Interaction-Id` | `REFER` to Talkdesk's escalation address | Hex UUI inside the transfer address, then Execute Action |
| [Twilio](/guides/contact-centers/twilio) | `<Dial><Sip>`; digest | `X-Call-ID`, which you add | `REFER` to your `referUrl` handler | Headers inside the transfer address (`ReferTransferTarget`) |
| [Microsoft Dynamics 365](/guides/contact-centers/microsoft-dynamics-365) | Transfer to a phone number, through your SBC; digest | `X-Call-ID`, which you add | Return, then your SBC routes the caller back | HTTP Request node calls the hand-off lookup |
| [NICE CXone](/guides/contact-centers/nice-cxone) | Studio `Placecall` with `Sipputheader`, to a dial-in number; IP allowlist | `X-Call-ID`, which you add | Return: the agent hangs up (confirm with NICE how the script takes the caller back) | REST API action calls the hand-off lookup |
| [Zoom Contact Center](/guides/contact-centers/zoom-contact-center) | Bot widget on a trunk Zoom builds, to a dial-in number; IP allowlist with SRTP | `X-ZOOM-Call-Sid` | `REFER` to Zoom's human-agent address | HTTP Call widget calls the hand-off lookup |

## How it works

1. **Create a SIP endpoint** for the agent. Platforms that can answer a
   password challenge use the endpoint's username and password. Platforms that
   identify themselves only by their source addresses use an endpoint with
   `auth` set to `ip_allowlist`; see
   [Platforms that authenticate by source IP](/guides/sip-addresses#platforms-that-authenticate-by-source-ip).
   Platforms that dial a phone number rather than a SIP address reach the
   endpoint through its
   [dial-in numbers](/guides/sip-addresses#platforms-that-dial-a-phone-number).
2. **Send calls with context.** The platform dials the endpoint's `sip_uri` or
   a dial-in number.
   Every `X-` header and `User-to-User` it sends becomes a `{{sip_…}}` call
   variable the prompt can use, and its call-id header is stored as the
   call's `external_call_id`. See
   [Pass call context in SIP headers](/guides/sip-addresses#pass-call-context-in-sip-headers).
3. **Add one transfer number that hands the call back**, either a SIP address
   on your platform (the agent sends a `REFER`) or a
   [return](/guides/call-transfers#return-the-call-to-your-contact-center)
   (the agent hangs up and your flow carries on). Its headers can carry
   `{{handoff_summary}}`, `{{handoff_intent}}` and `{{handoff_id}}`; see
   [Pass context to your contact center](/guides/call-transfers#pass-context-to-your-contact-center).
4. **Read the hand-off** where your platform puts it, or look it up by your
   platform's call id.

### Add the transfer number

SIP addresses, returns and their headers are set with the
[Agents API](/api-reference/agents#transfer-numbers). A write replaces the
whole list, so include the agent's other transfer numbers, then deploy:

```bash
curl -X PATCH https://api.thunderphone.com/v1/agents/12 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transfer_destinations": [{"name": "Contact center", "action": "return"}]}'

curl -X POST https://api.thunderphone.com/v1/agents/12/deploy \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

Then tell the agent when to use it, by name, in its prompt: "When the caller
asks for a person, or you can't resolve the request, transfer to Contact
center."

### Look up the hand-off

Your flow can fetch the hand-off with your organization's API key and your
platform's call id:

```bash
curl "https://api.thunderphone.com/v1/calls/handoff?external_call_id=YOUR_PLATFORM_CALL_ID" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

The response has `handoff.summary`, `handoff.intent` and `handoff.handoff_id`,
the SIP headers and variables the call started with and, once the call has
ended, its summary and extracted data. You can also look a call up by
`handoff_id`. See
[Look up a handed-off call](/api-reference/calls#look-up-a-handed-off-call).

Keep the API key in your platform's credential store, not in the flow itself.

<Warning>
  Header values come from whoever sends the call. Use them as context in the
  prompt, not to decide who the caller is or what they may do.
</Warning>

## Guides

<CardGroup cols={2}>
  <Card title="Amazon Connect" icon="phone" href="/guides/contact-centers/amazon-connect">
    External voice transfer in, return and a Lambda lookup back.
  </Card>
  <Card title="Five9" icon="phone" href="/guides/contact-centers/five9">
    AI Agent Connect in, routing headers on the hang-up back.
  </Card>
  <Card title="Genesys Cloud" icon="phone" href="/guides/contact-centers/genesys-cloud">
    BYOC Cloud trunk in, Take Back and Transfer with UUI back.
  </Card>
  <Card title="Talkdesk" icon="phone" href="/guides/contact-centers/talkdesk">
    Connect to Autopilot Voice in, escalation with UUI back.
  </Card>
  <Card title="Twilio" icon="phone" href="/guides/contact-centers/twilio">
    TwiML Dial in, a REFER to your referUrl handler back.
  </Card>
  <Card title="Microsoft Dynamics 365" icon="phone" href="/guides/contact-centers/microsoft-dynamics-365">
    Transfer through your SBC in, return and an HTTP lookup back.
  </Card>
  <Card title="NICE CXone" icon="phone" href="/guides/contact-centers/nice-cxone">
    Studio Placecall in, return and a REST lookup back.
  </Card>
  <Card title="Zoom Contact Center" icon="phone" href="/guides/contact-centers/zoom-contact-center">
    Bot widget in, a REFER to a human agent back.
  </Card>
</CardGroup>

<!-- en: guides/contact-centers/amazon-connect -->
---
title: "Connect from Amazon Connect"
description: "Send Amazon Connect calls to a ThunderPhone agent over SIP with the contact id and UUI, and resume your flow with the agent's hand-off."
---

Your Amazon Connect flow sends the caller to the agent with the contact id and
any UUI you set. When the agent is done, it hangs up, your flow carries on, and
a Lambda fetches the hand-off by contact id.

## Before you start

- A ThunderPhone agent and an organization [API key](/guides/api-keys).
- Amazon Connect's **External voice transfer** connector. Request the
  "External voice transfer connectors per account" quota increase first: the
  menu stays hidden until AWS approves it. AWS bills each connector per day
  ([$100 a day since July 21, 2025](https://aws.amazon.com/about-aws/whats-new/2025/07/amazon-connect-announces-per-day/))
  plus per-minute usage.

<Warning>
  AWS's current admin guide no longer has pages for external voice transfer.
  Before you build on it, confirm with AWS that the connector is available for
  your instance and Region.
</Warning>

## 1. Create the SIP endpoint

The connector doesn't document SIP digest authentication, so create an
endpoint that accepts calls by source address:

```bash
curl -X POST https://api.thunderphone.com/v1/sip-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 12,
    "name": "Amazon Connect",
    "auth": "ip_allowlist",
    "allowed_source_cidrs": ["CONNECT_SIGNALLING_RANGE_1", "CONNECT_SIGNALLING_RANGE_2"]
  }'
```

Get the connector's SIP signalling ranges for your Region from AWS. Each must be
a public IPv4 range of `/16` or narrower (IPv6 `/48` or narrower). See
[Platforms that authenticate by source IP](/guides/sip-addresses#platforms-that-authenticate-by-source-ip)
for the rules and the risk of an address shared by every customer of the
platform. Keep the response's `sip_uri`, for example
`sip:agent-12-jhxmginwjx@sip.thunderphone.com`.

## 2. Send calls with context

1. In the Amazon Connect console, open **External Voice Systems → Voice
   Transfer Integrations** and choose **Create**.
2. Pick the destination type (an SBC) and add an outbound route with host
   `sip.thunderphone.com`, port `5061` and protocol TLS. The endpoint needs
   TLS or TCP (port `5060`) and refuses UDP. AWS doesn't document which
   protocols the connector offers, so confirm with AWS that it can use one of
   them.
3. In your flow, add a **Transfer to phone number** block with **Transfer to**
   set to **External voice system**, and set:
   - **Destination ARN:** the connector.
   - **To User:** the user part of the endpoint's `sip_uri`, such as
     `agent-12-jhxmginwjx`.
   - **UUI** (optional): context for the agent. Connect sends it hex-encoded.
   - **Resume flow after disconnect:** Yes, so the flow continues when the
     agent hangs up.

Connect sends the contact id in `X-Amzn-ConnectContactId`. ThunderPhone stores
it as the call's `external_call_id`, which is how your flow finds the call
later. The UUI reaches the prompt as `{{sip_uui}}`. Third-party integrations
document the contact-id header; AWS's own docs don't, so check it on your first
test call.

## 3. Get the call back

AWS documents no way for Connect to read headers on the `BYE` or to accept a
`REFER` from the agent. So the agent returns the call: it says goodbye and
hangs up, and your flow resumes after the transfer block. Add this transfer
number (see [Add the transfer number](/guides/contact-centers/overview#add-the-transfer-number)):

```json
{"name": "Amazon Connect", "action": "return"}
```

Then fetch the hand-off with an **Invoke AWS Lambda function** block after the
transfer. The Lambda looks the call up by contact id:

```python
import json
import os
import urllib.error
import urllib.parse
import urllib.request


def lambda_handler(event, context):
    contact_id = event["Details"]["ContactData"]["ContactId"]
    url = "https://api.thunderphone.com/v1/calls/handoff?" + urllib.parse.urlencode(
        {"external_call_id": contact_id}
    )
    request = urllib.request.Request(
        url, headers={"Authorization": "Bearer " + os.environ["THUNDERPHONE_API_KEY"]}
    )
    try:
        with urllib.request.urlopen(request, timeout=5) as response:
            call = json.load(response)
    except (urllib.error.URLError, TimeoutError):
        return {"found": "false"}
    handoff = call.get("handoff") or {}
    return {
        "found": "true",
        "intent": handoff.get("intent") or "",
        "summary": handoff.get("summary") or "",
    }
```

The block returns a flat map, so the flow can branch on `intent` or set
`summary` as a contact attribute for the person who takes the call. Run the
block synchronously (up to 8 seconds) and store the API key encrypted, for
example in AWS Secrets Manager. The response fields are in
[Look up a handed-off call](/api-reference/calls#look-up-a-handed-off-call).

## Test it

Call a number on your Connect instance that reaches the transfer block, ask the
agent for a person, and check that the flow resumes. Then open the call with
`GET /v1/calls/{call_id}`: `sip_headers` should list
`x-amzn-connectcontactid`, and `external_call_id` should equal the `ContactId`
your Lambda receives. If the transfer fails with SIP `404`, ThunderPhone didn't
find the endpoint's user part: it must be in both the request URI and the `To`
header.

## Limits

- AWS documents no way to read headers on the `BYE`, including
  `X-TP-Handoff-Id`, so the contact id is the only link back to the call.
- AWS doesn't document a maximum UUI length for the connector.
- A synchronous Lambda block times out after 8 seconds.

<!-- en: guides/contact-centers/five9 -->
---
title: "Connect from Five9"
description: "Send Five9 calls to a ThunderPhone agent over SIP with AI Agent Connect, and get them back with routing headers your IVR script reads."
---

Your Five9 IVR script sends the caller to the agent with Five9's call
details. When the agent is done, it hangs up with routing headers on the SIP
`BYE`, which the script reads into call variables to route the caller.

## Before you start

- A ThunderPhone agent and an organization [API key](/guides/api-keys).
- Five9's **AI Agent Connect** add-on. Five9 limits it to AI providers it has
  accredited, and Five9's implementation team sets it up: it imports the
  provider's IVR script template, creates the call variables and points the
  script's **Third Party Transfer** module at the provider. ThunderPhone isn't
  on Five9's accredited list yet: ask your Five9 account team or ThunderPhone
  support before you plan around it.

## 1. Create the SIP endpoint

Five9's Third Party Transfer module dials a phone number, not a SIP address,
and other providers' Five9 integrations authenticate Five9 by source address
rather than a password. So create an `ip_allowlist` endpoint with the number
Five9 will dial as a dial-in number (see
[Platforms that dial a phone number](/guides/sip-addresses#platforms-that-dial-a-phone-number)):

```bash
curl -X POST https://api.thunderphone.com/v1/sip-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 12,
    "name": "Five9",
    "auth": "ip_allowlist",
    "allowed_source_cidrs": ["FIVE9_SIGNALLING_RANGE_1", "FIVE9_SIGNALLING_RANGE_2"],
    "dial_in_numbers": ["+14155550188"]
  }'
```

- `allowed_source_cidrs`: the SIP signalling ranges of your Five9 data
  centers, from Five9. Each must be a public IPv4 range of `/16` or narrower
  (IPv6 `/48` or narrower).
- `dial_in_numbers`: the number Five9's script will dial, written the way
  Five9 sends it. It doesn't have to be a real phone number. It can't already
  be in use on ThunderPhone, as a phone number or on another endpoint: that
  returns `409`.

Five9's addresses are shared by all its customers, so any other Five9
customer who dials the number reaches your agent. Where you choose the
number, pick a long one nobody would guess (up to 15 digits), make sure
Five9 sends it to ThunderPhone rather than out to the phone network, and
don't publish it.

## 2. Send calls with context

Ask Five9's implementation team to:

- Send the call from the **Third Party Transfer** module to
  `sip:+14155550188@sip.thunderphone.com`, with the number in both the request
  URI and the `To` header. The module takes the number, with the provider's
  SIP domain in a header.
- Send it over TLS (port 5061) or TCP (port 5060). The endpoint refuses UDP,
  and Five9 doesn't publish which transport it uses, so make sure it isn't
  UDP.
- Turn on **Return After 3rd Party Call**, so the script continues when the
  agent hangs up (Five9 allows up to 3,600 seconds on the third-party call).

Five9's guide lists the values it sends (`call.ANI`, `call.DNIS`,
`call.call_id`, `call.session_id`, `call.campaign_name` and others), not their
header names. Other AI providers' Five9 integrations document them on the wire
as `X-CallANI`, `X-CallDNIS`, `X-CallID`, `X-CallSessionID`, `X-CallCampaign`
and `X-AgentID`; check them on your first test call. Each reaches the prompt as a variable, such as
`{{sip_x_callcampaign}}`. `X-CallID` is stored as the call's
`external_call_id`.

## 3. Get the call back

The agent returns the call: it says goodbye and hangs up, and the `BYE` carries
the four headers Five9's script reads. Add this transfer number (see
[Add the transfer number](/guides/contact-centers/overview#add-the-transfer-number)):

```json
{
  "name": "Five9 agent",
  "action": "return",
  "headers": {
    "X-RouteType": "SkillTransfer",
    "X-RouteValue": "Support",
    "X-RouteReason": "{{handoff_intent}}",
    "X-CustomMetaData": "handoff_id={{handoff_id}}"
  }
}
```

- `X-RouteType` and `X-RouteValue` tell the script where to send the caller,
  here the Support skill. Values other providers document for `X-RouteType` include
  `SkillTransfer`, `PhoneTransfer`, `Hangup` and `DispositionOnly`; agree the
  values with whoever maintains the script. For several destinations, add one
  return per destination with a different name and `X-RouteValue`.
- `X-RouteReason` carries the agent's intent label, such as `billing_dispute`.
- `X-CustomMetaData` carries the hand-off id. The `BYE` also carries it as
  `X-TP-Handoff-Id`, which Five9 doesn't read.

Five9's script maps the four headers into call variables. For the agent's
summary, have the script call the hand-off lookup with an IVR **Query** module:
`GET https://api.thunderphone.com/v1/calls/handoff?external_call_id=` followed by
`call.call_id`, with an Authorization Profile that sends
`Authorization: Bearer` and your API key. See
[Look up a handed-off call](/api-reference/calls#look-up-a-handed-off-call).

## Test it

Call into the IVR script, ask the agent for a person, and check that the script
routes the caller with the call variables filled. If the call never reaches the
agent, check that the number in the request URI and `To` header matches the
dial-in number, that Five9's source address is in `allowed_source_cidrs`, and
that the call came over TCP or TLS. Then open the call with
`GET /v1/calls/{call_id}`: `sip_headers` should list `x-callid`, and
`external_call_id` should match `call.call_id` in Five9.

## Limits

- Five9's guide documents routing data on the `BYE` and doesn't mention
  accepting a `REFER`, so the hand-back is a cold transfer by the script.
- Five9 reads `X-RouteType`, `X-RouteValue`, `X-RouteReason` and
  `X-CustomMetaData`, not `User-to-User`. ThunderPhone sends each header value
  at most 256 bytes long.
- Five9 recommends keeping custom headers to about ten to avoid packet
  fragmentation.

<!-- en: guides/contact-centers/genesys-cloud -->
---
title: "Connect from Genesys Cloud"
description: "Send Genesys Cloud calls to a ThunderPhone agent over a BYOC Cloud trunk with the conversation id and UUI, and take them back with the hand-off in UUI."
---

Your Architect flow sends the caller to the agent over a BYOC Cloud trunk, with
the conversation id and any UUI you set. When the caller needs a person, the
agent sends a SIP `REFER`, Genesys takes the call back, and the hand-off id
arrives in the call's UUI.

## Before you start

- A ThunderPhone agent and an organization [API key](/guides/api-keys).
- Genesys Cloud with BYOC Cloud, and an external trunk (type BYOC Carrier or
  PBX) with these settings turned on
  ([external trunk settings](https://help.genesys.cloud/articles/external-trunk-settings/)):
  - **Conversation Headers**, so Genesys sends its conversation id in
    `x-inin-cnv`. It is off by default.
  - **UUI Passthrough**, with header type `User-To-User` and encoding Hex.
  - **Take Back and Transfer**, so Genesys accepts the agent's `REFER`.

## 1. Create the SIP endpoint

Genesys answers a digest challenge, so use a standard endpoint:

```bash
curl -X POST https://api.thunderphone.com/v1/sip-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": 12, "name": "Genesys Cloud"}'
```

Store the `password` from the response straight away; it is shown once. On the
trunk:

| Setting | Value |
|---|---|
| SIP server | `sip.thunderphone.com`, port `5061` |
| Protocol | TLS |
| Digest authentication | the endpoint's `username` and `password` |
| Codecs | PCMU, PCMA or G.722 |

Put the trunk on an outbound route of your site whose number plan covers the
address the flow dials.

## 2. Send calls with context

In your Architect flow:

1. Optionally, add a **Set UUI Data** action with context for the agent, such
   as `account=12345`. Genesys recommends 128 characters or fewer.
2. Add a **Transfer to Number** action with the endpoint's `sip_uri`, for
   example `sip:agent-12-jhxmginwjx@sip.thunderphone.com`.

Genesys sends the conversation id in `x-inin-cnv`. ThunderPhone stores it as
the call's `external_call_id`. The UUI reaches the prompt decoded, as
`{{sip_uui}}`.

Trunk custom headers are static in Genesys, so put per-call values in the UUI.
Genesys reserves the `x-inin`, `x-genesys`, `x-pcv` and `x-gcv` header prefixes
for itself.

## 3. Get the call back

The agent transfers with a `REFER` to an address on Genesys, with the hand-off
id as hex UUI inside that address. Add this transfer number (see
[Add the transfer number](/guides/contact-centers/overview#add-the-transfer-number)
and [Headers inside the transfer address](/guides/call-transfers#headers-inside-the-transfer-address)):

```json
{
  "name": "Genesys support",
  "number": "sip:support@acme.byoc.mypurecloud.com",
  "headers": {"User-to-User": "{{handoff_id}}"},
  "headers_in_uri": true,
  "uui_encoding": "hex"
}
```

Replace the address with one that routes back to the queue or flow that should
take the caller; confirm its form with Genesys. The `REFER` looks like this:

```
Refer-To: <sip:support@acme.byoc.mypurecloud.com?User-to-User=5A72336D59...%3Bencoding%3Dhex>
```

With **Take Back and Transfer** on, Genesys takes the call back from the trunk
and routes it to that address. Genesys documents that incoming UUI lands in
`Call.UUIData`; it doesn't document this for a take-back, so confirm with
Genesys, or on a test call, that the flow receiving the caller finds the
hand-off id there. To get the summary and intent, call the hand-off lookup with
a **Call Data Action** on a Web Services Data Actions integration:

- Request: `GET https://api.thunderphone.com/v1/calls/handoff?handoff_id=`
  followed by the id from `Call.UUIData`.
- Credentials: your API key, sent as `Authorization: Bearer sk_live_…`.
- Output: map `handoff.summary` and `handoff.intent` to flow variables.

See [Look up a handed-off call](/api-reference/calls#look-up-a-handed-off-call).

## Test it

Call a number that reaches the flow, ask the agent for a person, and check that
Genesys takes the call to the address you set. In that flow, check that
`Call.UUIData` holds the hand-off id as text (if it shows hex digits, check the
trunk's UUI encoding is Hex). Then open the call with `GET /v1/calls/{call_id}`:
`external_call_id` should be the conversation id.

## Limits

- The **Get SIP Headers** action reads only the initial `INVITE`, so it can't
  read anything from the agent's `REFER`. The hand-off reaches Genesys only
  through UUI.
- Genesys drops all UUI when a call carries more than one UUI header.
- The transfer address is kept to 254 characters, so a long UUI is cut to fit.
  A hand-off id always fits.

<!-- en: guides/contact-centers/talkdesk -->
---
title: "Connect from Talkdesk"
description: "Send Talkdesk calls to a ThunderPhone agent with Connect to Autopilot Voice, and escalate them back with the hand-off id in UUI."
---

Your Talkdesk Studio flow sends the caller to the agent with the interaction
id and UUI. When the caller needs a person, the agent escalates with a SIP
`REFER` to Talkdesk, and the hand-off id lands in a Studio variable.

## Before you start

- A ThunderPhone agent and an organization [API key](/guides/api-keys).
- A Talkdesk **Conversation Orchestrator** license, which covers the Studio
  **Connect to Autopilot Voice** component in **External Voice Stream** mode
  ([Talkdesk's article](https://support.talkdesk.com/hc/en-us/articles/48921776047259)).
  Talkdesk bills it per minute while the agent holds the call.

## 1. Create the SIP endpoint

Talkdesk documents only an IP allowlist, so create an endpoint that accepts
calls by source address:

```bash
curl -X POST https://api.thunderphone.com/v1/sip-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 12,
    "name": "Talkdesk",
    "auth": "ip_allowlist",
    "allowed_source_cidrs": ["TALKDESK_SIGNALLING_RANGE_1", "TALKDESK_SIGNALLING_RANGE_2"],
    "srtp": "optional"
  }'
```

Talkdesk's article says it sends audio over SRTP, and `"srtp": "optional"`
answers SRTP when Talkdesk offers it. The article doesn't say whether Talkdesk
requires SRTP; if Talkdesk tells you it does, set `srtp` to `required`, which
refuses calls without it.

Get Talkdesk's SIP signalling ranges from Talkdesk. Each must be a public IPv4
range of `/16` or narrower (IPv6 `/48` or narrower). See
[Platforms that authenticate by source IP](/guides/sip-addresses#platforms-that-authenticate-by-source-ip).
Talkdesk sends SIP from Twilio's network, whose addresses every Twilio customer
shares, so the endpoint's address is what keeps other callers out: don't
publish it.
Keep the response's `sip_uri`, for example
`sip:agent-12-jhxmginwjx@sip.thunderphone.com`.

## 2. Send calls with context

In your Studio flow, add **Connect to Autopilot Voice** in **External Voice
Stream** mode and set its target to the endpoint's `sip_uri` with `;transport=tls` added, for
example `sip:agent-12-jhxmginwjx@sip.thunderphone.com;transport=tls`. The
endpoint refuses calls over UDP, which Twilio's SIP uses unless told otherwise.

Talkdesk sends:

- `X-Talkdesk-Interaction-Id`, stored as the call's `external_call_id`;
- `User-to-User`, hex-encoded, such as `business_hours=open`. It reaches the
  prompt decoded, as `{{sip_uui}}`.

Version 2.1 of the component can also send **Defined headers**. Talkdesk's
preferences page describes them as JSON sent over a WebSocket, so confirm with
Talkdesk whether they arrive as SIP headers before you rely on them.

## 3. Get the call back

The agent escalates with a `REFER` to Talkdesk's escalation address, with the
hand-off id as hex UUI inside that address, the only place Talkdesk reads it.
Add this transfer number (see
[Add the transfer number](/guides/contact-centers/overview#add-the-transfer-number)
and [Headers inside the transfer address](/guides/call-transfers#headers-inside-the-transfer-address)):

```json
{
  "name": "Talkdesk escalation",
  "number": "sip:escalation@talkdesk.com",
  "headers": {"User-to-User": "autopilot_result={{handoff_id}}"},
  "headers_in_uri": true,
  "uui_encoding": "hex"
}
```

The address is the one in Talkdesk's article. Version 2.1 of the component
reads `autopilot_result=`; version 1.7 reads `escalate_to=`, so use that key on
1.7. The `REFER` looks like this:

```
Refer-To: <sip:escalation@talkdesk.com?User-to-User=6175746F70696C6F745F726573756C743D...%3Bencoding%3Dhex>
```

Talkdesk puts the value in a Studio variable. To get the summary and intent,
add an **Execute Action** step on a custom integration built with
Connections:

- Auth type **API key**, header name `Authorization`, value
  `Bearer sk_live_…`.
- Request: `GET https://api.thunderphone.com/v1/calls/handoff?handoff_id=`
  followed by the id from the variable. You can also look the call up by
  `external_call_id` with the interaction id.
- Route on `handoff.intent`, and show `handoff.summary` to the person who takes
  the call.

See [Look up a handed-off call](/api-reference/calls#look-up-a-handed-off-call).

## Test it

Start a call through the Studio flow, ask the agent for a person, and check
that the flow continues past the component with the hand-off id in its
variable. Then open the call with `GET /v1/calls/{call_id}`:
`external_call_id` should be the Talkdesk interaction id.

## Limits

- Talkdesk reads at most 256 bytes of UUI and doesn't allow values separated by
  `|` or `;`, so send a single value. The hand-off id fits.
- Talkdesk's APIs can't read the agent's transcript. Use the hand-off lookup or
  `GET /v1/calls/{call_id}` instead.

<!-- en: guides/contact-centers/twilio -->
---
title: "Connect from Twilio"
description: "Send Twilio calls to a ThunderPhone agent over SIP with the CallSid, and take them back through your referUrl with the hand-off in the transfer address."
---

Your TwiML dials the agent's SIP address with the call's `CallSid` in a header.
When the caller needs a person, the agent sends a SIP `REFER`, Twilio passes the
transfer address with the hand-off inside it to your `referUrl` handler, and the
TwiML your handler returns decides where the caller goes, such as a Flex queue.

## Before you start

- A ThunderPhone agent and an organization [API key](/guides/api-keys).
- Twilio Programmable Voice, and somewhere to serve TwiML and a `referUrl`
  handler: your own server, or a TwiML Bin and a Twilio Function. Flex is
  optional.

## 1. Create the SIP endpoint

Twilio's `<Sip>` takes a username and password, so use a standard endpoint:

```bash
curl -X POST https://api.thunderphone.com/v1/sip-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": 12, "name": "Twilio"}'
```

Store the `password` from the response straight away; it is shown once. To
accept calls only from Twilio as well, see
[Restrict source IPs](/guides/sip-addresses#restrict-source-ips-optional).

## 2. Send calls with context

Return this TwiML for the call you want to hand to the agent:

```xml
<Response>
  <Dial answerOnBridge="true" referUrl="https://YOUR_SERVER/thunderphone-refer">
    <Sip username="tp409667538f83" password="YOUR_ENDPOINT_PASSWORD">sip:agent-12-jhxmginwjx@sip.thunderphone.com;transport=tls?X-Call-ID={{CallSid}}</Sip>
  </Dial>
</Response>
```

- `;transport=tls` matters: Twilio uses UDP unless told otherwise.
- `X-Call-ID` carries the `CallSid`. Twilio doesn't document a call-id header of
  its own, so add this one: ThunderPhone stores it as the call's
  `external_call_id`. `{{CallSid}}` works in a TwiML Bin; from your own server,
  write the `CallSid` of the incoming request.
- Add more context the same way, such as `&amp;X-Account-Id=12345`. Inside
  TwiML, write `&` as `&amp;`, since a bare `&` is invalid XML. Each reaches the
  prompt as a variable, here `{{sip_x_account_id}}`. Twilio allows `x-` headers
  and `User-to-User`, percent-encoded, with the whole URI under 255 characters
  and the headers under 1,024.
- `referUrl` lets Twilio accept the agent's `REFER`; without it the transfer
  fails with [error 13802](https://www.twilio.com/docs/api/errors/13802).
  `answerOnBridge="true"` keeps the caller connected until the new destination
  answers, so a failed transfer can fall back.

Studio's **Connect Call To** widget doesn't document custom headers or
`referUrl`, so from Studio hand the call to this TwiML, for example with a
**TwiML Redirect** widget.

## 3. Get the call back

The agent transfers with a `REFER` whose transfer address carries the hand-off
id and intent. Add this transfer number (see
[Add the transfer number](/guides/contact-centers/overview#add-the-transfer-number)
and [Headers inside the transfer address](/guides/call-transfers#headers-inside-the-transfer-address)):

```json
{
  "name": "Twilio support",
  "number": "sip:support@acme.sip.twilio.com",
  "headers": {"X-Handoff-Id": "{{handoff_id}}", "X-Handoff-Intent": "{{handoff_intent}}"},
  "headers_in_uri": true
}
```

Twilio sends the whole address to your `referUrl` as `ReferTransferTarget`, for
example `<sip:support@acme.sip.twilio.com?X-Handoff-Id=Zr3mY0b1Q9xWw2kPq4s7Tg&X-Handoff-Intent=billing_dispute>`.
Your handler reads the headers out of it and returns TwiML for where the caller
goes next. The address's user part (`support`) is yours to choose, so you can
add one transfer number per destination and route on it.

This Twilio Function enqueues the caller to Flex with the hand-off as task
attributes and looks the summary up by hand-off id. The lookup runs in a
Function because Studio's HTTP Request widget can't send the `Authorization`
header:

```js
exports.handler = async (context, event, callback) => {
  const target = (event.ReferTransferTarget || "").replace(/^<|>$/g, "");
  const params = new URLSearchParams(target.split("?")[1] || "");
  const handoffId = params.get("X-Handoff-Id") || "";
  const attributes = { handoff_id: handoffId, intent: params.get("X-Handoff-Intent") || "" };

  if (handoffId) {
    const response = await fetch(
      "https://api.thunderphone.com/v1/calls/handoff?handoff_id=" + encodeURIComponent(handoffId),
      { headers: { Authorization: "Bearer " + context.THUNDERPHONE_API_KEY } }
    );
    if (response.ok) {
      const call = await response.json();
      attributes.summary = (call.handoff && call.handoff.summary) || "";
    }
  }

  const twiml = new Twilio.twiml.VoiceResponse();
  twiml.enqueue({ workflowSid: context.FLEX_WORKFLOW_SID }).task({}, JSON.stringify(attributes));
  callback(null, twiml);
};
```

Keep the API key in the Function's environment variables. See
[Look up a handed-off call](/api-reference/calls#look-up-a-handed-off-call)
for the other fields.

## Test it

Call a Twilio number that returns the TwiML above, ask the agent for a person,
and check that your `referUrl` handler receives `ReferTransferTarget` with both
headers and that the caller reaches the queue. Then open the call with
`GET /v1/calls/{call_id}`: `external_call_id` should be the `CallSid`.

## Limits

- Twilio limits `Refer-To` to 256 characters. ThunderPhone keeps the address to
  254 and leaves out a header that doesn't fit, so keep header names and values
  short.
- Twilio doesn't document reading headers on a `BYE`, so a return can't carry
  the hand-off back to Twilio. Use a `REFER` as above.
- Twilio doesn't accept a `REFER` on a call connected through `<Conference>` or
  `<Queue>`, so dial the agent with `<Dial><Sip>` as above.

<!-- en: guides/contact-centers/microsoft-dynamics-365 -->
---
title: "Connect from Microsoft Dynamics 365"
description: "Send Dynamics 365 Contact Center and Copilot Studio calls to a ThunderPhone agent through your SBC with X-headers, and look up the agent's hand-off over HTTP."
---

Dynamics 365 Contact Center sends the caller to the agent through your session
border controller (SBC), with up to five X-headers including the conversation
id. When the agent is done, it hangs up, your SBC brings the caller back into
Dynamics 365, and an HTTP Request node fetches the hand-off.

## Before you start

- A ThunderPhone agent and an organization [API key](/guides/api-keys).
- The Dynamics 365 Contact Center voice channel, connected through Azure
  Communication Services **Direct Routing** to an SBC you run
  ([SBC requirements](https://learn.microsoft.com/en-us/azure/communication-services/concepts/telephony/direct-routing-infrastructure)):
  a supported SBC with a public certificate, TLS 1.2 on port 5061 and SRTP
  toward Microsoft.
- **SIP X-header support** on the **Transfer conversation** node
  ([Copilot Studio](https://learn.microsoft.com/en-us/microsoft-copilot-studio/voice-sip-x-header)).
  Confirm it is available in your environment.

Dynamics 365 transfers only to a phone number, and Microsoft authenticates
Direct Routing by certificate, not by password. Your SBC sits between
Microsoft and ThunderPhone and turns that number into the agent's SIP address.

## 1. Create the SIP endpoint

The call reaches ThunderPhone from your SBC, so create a standard endpoint for
the SBC to use:

```bash
curl -X POST https://api.thunderphone.com/v1/sip-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": 12, "name": "Dynamics 365 SBC"}'
```

Store the `password` from the response straight away; it is shown once, and
your SBC answers ThunderPhone's challenge with it. If your SBC can't do digest
authentication, create the endpoint with `auth` set to `ip_allowlist` and your
SBC's public address instead; see
[Platforms that authenticate by source IP](/guides/sip-addresses#platforms-that-authenticate-by-source-ip).

## 2. Send calls with context

1. Pick a phone number for the agent on your SBC, such as `+14155550188`.
2. On the SBC, route calls to that number to the endpoint's `sip_uri`, for
   example `sip:agent-12-jhxmginwjx@sip.thunderphone.com`, over TLS on port
   `5061`. ThunderPhone finds the endpoint by the user part
   (`agent-12-jhxmginwjx`), which must be in both the request URI and the
   `To` header. Pass the X-headers through unchanged.
3. In Copilot Studio, add a **Transfer conversation** node with
   **External phone number transfer** to that number, and add the X-headers:
   - `X-Call-ID`: the Dynamics 365 conversation id. No Microsoft header carries
     it, so add it here; ThunderPhone stores it as the call's
     `external_call_id`. Confirm in Copilot Studio which variable holds the
     conversation id.
   - Up to four more, such as `X-Customer-Tier`.

Microsoft sends at most five X-headers, with names up to 64 characters and
values up to 256, using letters, digits and `= ; . ! % * _ + ~ -`. It writes
the prefix as lowercase `x-`; ThunderPhone matches header names ignoring case,
so `x-customer-tier` reaches the prompt as `{{sip_x_customer_tier}}`.

If you build the call with Azure Communication Services Call Automation
instead, `AddSipX` writes `X-MS-Custom-` names by default. Pass
`SipHeaderPrefix.X` so `X-Call-ID` keeps its name
([custom context](https://learn.microsoft.com/en-us/azure/communication-services/how-tos/call-automation/custom-context)).

## 3. Get the call back

The agent returns the call: it says goodbye and hangs up. Add this transfer
number (see
[Add the transfer number](/guides/contact-centers/overview#add-the-transfer-number)):

```json
{"name": "Dynamics 365", "action": "return"}
```

Bringing the caller back into Dynamics 365 is your SBC's job. Microsoft
documents one way in for a call with context: a new call through the SBC to a
number registered in Dynamics 365, with UUI whose keys match context variables
you set up under **Workstreams → Advanced settings**
([third-party IVR transfer](https://learn.microsoft.com/en-us/dynamics365/customer-service/administer/voice-channel-contextual-transfer-external-ivr)).
Work out with your SBC vendor how the caller reaches that number when
ThunderPhone hangs up, and carry the conversation id you sent in `X-Call-ID`
so the flow can find the call.

Then fetch the hand-off with a Copilot Studio **HTTP Request** node:

- `GET https://api.thunderphone.com/v1/calls/handoff?external_call_id=`
  followed by the conversation id.
- Header `Authorization: Bearer sk_live_…`.
- Parse the response into a variable and use `handoff.summary` and
  `handoff.intent`.

See [Look up a handed-off call](/api-reference/calls#look-up-a-handed-off-call).

## Test it

Call a Dynamics 365 number that reaches the transfer node, ask the agent for a
person, and check that the caller comes back into Dynamics 365. Then open the
call with `GET /v1/calls/{call_id}`: `sip_headers` should list `x-call-id`, and
`external_call_id` should be the conversation id. If the call never reaches the
agent and your SBC logs SIP `404`, its request URI or `To` header doesn't carry
the endpoint's user part.

## Limits

- An SBC is required. Microsoft can't dial a SIP address or answer a digest
  challenge.
- Microsoft sends at most five X-headers, and keeps only the first five on a
  call coming in. Dynamics 365 takes at most 128 characters of UUI.
- Microsoft doesn't document reading headers on a `BYE`, so the hand-off comes
  back only through the lookup.

<!-- en: guides/contact-centers/nice-cxone -->
---
title: "Connect from NICE CXone"
description: "Send NICE CXone calls to a ThunderPhone agent from a Studio script with the ContactID in a SIP header, and look up the agent's hand-off when the script continues."
---

Your CXone Studio script places a call to the agent with SIP headers that carry
the contact id and any other context. When the agent is done, it hangs up, and
a REST API action in the script fetches the hand-off.

## Before you start

- A ThunderPhone agent and an organization [API key](/guides/api-keys).
- A CXone SIP trunk group that accepts custom headers. Your NICE account
  representative has to turn this setting on before CXone sends them.

## 1. Create the SIP endpoint

Placecall dials a phone number over a CXone trunk group, not a SIP address.
NICE doesn't document SIP credentials for it, and another AI provider's CXone
integration uses TLS with an IP allowlist. So create an `ip_allowlist`
endpoint with the number the script will dial as a dial-in number (see
[Platforms that dial a phone number](/guides/sip-addresses#platforms-that-dial-a-phone-number)):

```bash
curl -X POST https://api.thunderphone.com/v1/sip-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 12,
    "name": "NICE CXone",
    "auth": "ip_allowlist",
    "allowed_source_cidrs": ["CXONE_SIGNALLING_RANGE_1", "CXONE_SIGNALLING_RANGE_2"],
    "dial_in_numbers": ["+14155550188"]
  }'
```

- `allowed_source_cidrs`: the SIP signalling ranges of your CXone cluster,
  from NICE. Each must be a public IPv4 range of `/16` or narrower (IPv6 `/48`
  or narrower).
- `dial_in_numbers`: the number Placecall will dial, written the way
  CXone sends it. It doesn't have to be a real phone number. It can't already
  be in use on ThunderPhone, as a phone number or on another endpoint: that
  returns `409`.

CXone's addresses are shared by all its customers, so any other CXone
customer who dials the number reaches your agent. Where you choose the
number, pick a long one nobody would guess (up to 15 digits), make sure
CXone sends it to ThunderPhone rather than out to the phone network, and
don't publish it.

## 2. Send calls with context

In your Studio script, before **Placecall**:

1. Add a **Sipputheader** action with header `X-Call-ID` and the value of
   `ContactID`. CXone sends no call-id header of its own; ThunderPhone stores
   this one as the call's `external_call_id`.
2. Add a **Sipputheader** action for each other value the agent should know,
   such as `X-Skill` set to `support`. It reaches the prompt as
   `{{sip_x_skill}}`. Sipputheader takes `User-to-User`, any `X-` header, and
   most `P-` headers; NICE recommends values of 256 characters or less.

Then **Placecall** to that number, over a trunk group that sends it to
`sip.thunderphone.com` with the number in both the request URI and the `To`
header. The endpoint takes TLS (port 5061) or TCP (port 5060) and refuses
UDP, and NICE doesn't document the trunk's transport, so make sure it isn't
UDP.

## 3. Get the call back

CXone reads SIP headers only on the `INVITE` and its final response, so the
agent returns the call: it says goodbye and hangs up, and your script picks the
caller up again. Add this transfer number (see
[Add the transfer number](/guides/contact-centers/overview#add-the-transfer-number)):

```json
{"name": "NICE CXone", "action": "return"}
```

NICE doesn't document that a script continues after Placecall when the placed
call ends. Other AI providers' CXone integrations instead signal the script
through CXone's Signal API (`POST /interactions/{contactId}/signal`) before
they hang up; ThunderPhone doesn't call it. Confirm with NICE how your script
takes the caller back, then fetch the hand-off with a **REST API** action:

- `GET https://api.thunderphone.com/v1/calls/handoff?external_call_id=`
  followed by `ContactID`.
- Header `Authorization: Bearer sk_live_…`.
- Read `handoff.summary` and `handoff.intent` from the response to route the
  contact.

See [Look up a handed-off call](/api-reference/calls#look-up-a-handed-off-call).

## Test it

Call a number that runs the script, ask the agent for a person, and check that
the script continues and the REST API action returns the hand-off. If the call
never reaches the agent, check the number CXone sends, that its source address
is in `allowed_source_cidrs`, and that the call came over TCP or TLS. Then open the
call with `GET /v1/calls/{call_id}`: `sip_headers` should list `x-call-id`, and
`external_call_id` should equal the `ContactID`.

## Limits

- CXone sends and reads headers only on the `INVITE` and its final `2xx`, so
  nothing on the agent's `BYE` reaches the script.
- NICE doesn't document accepting a `REFER` from the agent.
- The REST API action times out after 10 seconds by default (under 90 at most)
  and reads responses up to 32 KB.

<!-- en: guides/contact-centers/zoom-contact-center -->
---
title: "Connect from Zoom Contact Center"
description: "Send Zoom Contact Center calls to a ThunderPhone agent with a third-party voicebot connector, and take them back to a human agent with a SIP REFER."
---

A Bot widget in your Zoom Contact Center flow sends the caller to the agent with
Zoom's call sid. When the caller needs a person, the agent sends a SIP `REFER`
to Zoom's human-agent address, and your flow fetches the hand-off by call sid.

## Before you start

- A ThunderPhone agent and an organization [API key](/guides/api-keys).
- A Zoom Marketplace **General App**, managed by your admin and made available
  to Contact Center, with a connector for the Bot widget
  ([Zoom's third-party voicebot guide](https://developers.zoom.us/docs/contact-center/library/guides/3p-voicebot/)).
- A SIP trunk from Zoom to the bot provider. Zoom's ISV team builds it in
  stages (discovery, a staging trunk, then production), and the app's Company
  Name must match the trunk record exactly. This setup starts with ThunderPhone
  support and Zoom, not in your Zoom account alone.

## 1. Create the SIP endpoint

Zoom's connector dials a 15-digit number starting with `999`, not a SIP
address. Saving the connector generates that number. Zoom's trunk uses TLS 1.2
on port 5061 with SRTP for audio, and is allowlisted by Zoom's subnets rather
than a password. So create an `ip_allowlist` endpoint with the connector's
number as a dial-in number and SRTP required (see
[Platforms that dial a phone number](/guides/sip-addresses#platforms-that-dial-a-phone-number)):

```bash
curl -X POST https://api.thunderphone.com/v1/sip-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 12,
    "name": "Zoom Contact Center",
    "auth": "ip_allowlist",
    "allowed_source_cidrs": ["ZOOM_SIGNALLING_RANGE_1", "ZOOM_SIGNALLING_RANGE_2"],
    "dial_in_numbers": ["999123456789012"],
    "srtp": "required"
  }'
```

- `allowed_source_cidrs`: Zoom's SIP signalling subnets, from Zoom. Each must
  be a public IPv4 range of `/16` or narrower (IPv6 `/48` or narrower).
- `dial_in_numbers`: the connector's number exactly as Zoom sends it, without a
  `+`.
- `srtp`: `required`, since Zoom's trunk always uses SRTP.

Zoom's addresses are shared by all its customers, so any other Zoom customer
who dials the number reaches your agent. Zoom assigns the number; don't
publish it.

## 2. Send calls with context

Add a **Bot** widget to your flow and bind it to the connector. Ask Zoom's ISV
team to point the trunk at `sip.thunderphone.com`, TLS on port 5061, with the
connector's number in both the request URI and the `To` header. The endpoint
refuses UDP, so make sure the trunk doesn't fall back to it.

Zoom sends:

- `X-ZOOM-Call-Sid`, stored as the call's `external_call_id`. Zoom's own data
  mapping page doesn't list it; another AI provider's Zoom integration documents
  it, so check it on your first test call.
- `X-ZOOM-DNIS`, the number the caller dialed, as `{{sip_x_zoom_dnis}}`.
- `X-ZOOM-WEBHOOK`, the connector's Static URL.

## 3. Get the call back

The agent sends a `REFER` to the human-agent address on Zoom's SBC. Add this
transfer number (see
[Add the transfer number](/guides/contact-centers/overview#add-the-transfer-number)),
with the SBC address Zoom gives you:

```json
{"name": "Zoom human agent", "number": "sip:HumanAgent@203.0.113.10:5061"}
```

Zoom's guide describes two ways a bot passes context: a `POST` to the
connector's Static URL before the `REFER` (`voicebot_metadata` and similar
events), and SIP headers mapped under **Inbound from Bot**. ThunderPhone
doesn't post to the Static URL. Zoom's guide doesn't say whether it reads
mapped headers from a `REFER`; if you want to try, add `headers` such as
`"X-Handoff-Id": "{{handoff_id}}"` to the entry and check on a test call. Also
confirm with Zoom that it accepts a `REFER` with no metadata `POST` before it.

To get the hand-off without relying on either, have your flow look it up after
the Bot widget, with an **HTTP Call** or **Script** widget:

- `GET https://api.thunderphone.com/v1/calls/handoff?external_call_id=`
  followed by the call sid.
- Header `Authorization: Bearer sk_live_…`.
- Use `handoff.summary` and `handoff.intent` to route the caller and brief the
  person who takes the call.

Zoom doesn't publish field-level docs for these widgets, so confirm in your
account that the widget can send an `Authorization` header. See
[Look up a handed-off call](/api-reference/calls#look-up-a-handed-off-call).

## Test it

Call a number that reaches the Bot widget, ask the agent for a person, and check
that the caller reaches a human agent and the widget returns the hand-off. Then
open the call with `GET /v1/calls/{call_id}`: `sip_headers` should list
`x-zoom-call-sid`, and `external_call_id` should match the call sid your flow
uses.

## Limits

- ThunderPhone doesn't post to the connector's Static URL, so Zoom gets the
  hand-off through the lookup, or through mapped headers if your test shows
  Zoom reads them from the `REFER`.
- The trunk is built by Zoom's ISV team, so you can't set it up or test it on
  your own.

<!-- en: guides/verify-webhook-signatures -->
---
title: "Verify webhook signatures"
description: "Every webhook and tool request ThunderPhone sends is signed with a timestamp. Verify it with the recipe or SDK helper here and reject replayed requests older than five minutes."
---

Every request we send to your server (webhook deliveries, the legacy
single-URL webhook and tool-endpoint calls) carries two signature
headers. Both are HMAC-SHA256 with the same secret.

| Header | Signs | Replay protection |
|--------|-------|-------------------|
| `X-ThunderPhone-Signature-V2` (recommended) | Timestamp, method, path, query and body | Reject requests more than 5 minutes old |
| `X-ThunderPhone-Signature` | Body only | None: a captured request verifies forever |

Verify `X-ThunderPhone-Signature-V2` in new integrations and move
existing ones to it. `X-ThunderPhone-Signature` is still sent on every
request, unchanged, so verifiers built on it keep working. We will
announce a date before we stop sending it.

## Signature V2

```http
X-ThunderPhone-Signature-V2: t=1767225600,v1=03a89bec521f78d55727237ca4713bb0b8dcdf2e09e450865b5b5637b80c1c4e
```

- `t` is the Unix time, in seconds, when we sent the request. A retried
  delivery is signed again when it is sent, with its own `t`.
- `v1` is the hex HMAC-SHA256 of the signed string below, keyed with your
  secret.

The value is a comma-separated list of `key=value` pairs. Ignore keys you
do not recognize, and accept the request if any `v1` matches: we may add
a second signature during a future change.

### The signed string

Four fields, each followed by one newline (`\n`, byte `0x0A`) except the
last:

```text
<t>\n<METHOD>\n<path and query>\n<body>
```

| Field | Value |
|-------|-------|
| `t` | The `t` value from the header |
| `METHOD` | The HTTP method in upper case: `POST`, `GET`, `PUT`, `PATCH` or `DELETE` |
| path and query | The request target from the HTTP request line: the path, then `?` and the query string when there is one. No scheme, host or fragment. Use it exactly as it arrived, without decoding it or re-ordering parameters |
| `body` | The raw request body. `GET` and `DELETE` tool calls have no body, so their signed string ends with the newline after the path |

To verify:

1. Before any parsing, read the header, the method, the raw path and
   query, and the raw body.
2. Take `t` and every `v1` from the header.
3. Reject the request if `t` is more than **300 seconds** before or after
   your clock.
4. Compute the hex HMAC-SHA256 of the signed string with your secret.
5. Compare it with `v1` in constant time. Respond `401` if nothing matches.

### Worked example

Secret `whsec_example_4c1f2a9b`. We send this request at
`t = 1767225600` (2026-01-01 00:00:00 UTC):

```http
POST /tools/lookup?region=us HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-ThunderPhone-Signature-V2: t=1767225600,v1=03a89bec521f78d55727237ca4713bb0b8dcdf2e09e450865b5b5637b80c1c4e

{"customer_id":"cust_123"}
```

The signed string is these four lines, with no newline after the body:

```text
1767225600
POST
/tools/lookup?region=us
{"customer_id":"cust_123"}
```

Its HMAC-SHA256 is
`03a89bec521f78d55727237ca4713bb0b8dcdf2e09e450865b5b5637b80c1c4e`.
Check your implementation against it, or reproduce it with `openssl`:

```bash
printf '1767225600\nPOST\n/tools/lookup?region=us\n{"customer_id":"cust_123"}' \
  | openssl dgst -sha256 -hmac 'whsec_example_4c1f2a9b'
```

A `GET` tool call to `/tools/lookup?customer_id=cust_123` at the same
second has an empty body. Its signed string is
`1767225600\nGET\n/tools/lookup?customer_id=cust_123\n` and its signature
is `3ce214cb0b8f2bf39b1d19d4e7265df9dbaff5a5f838d3cc6c753a8f7a4ad280`.

### With the SDKs

The [Python and TypeScript SDKs](/api-reference/sdks) include a helper
(`thunderphone` 0.2.0 or later, `@thunderphone/sdk` 0.2.0 or later). It
checks the 5-minute window, compares in constant time, and accepts a list
of secrets so you can rotate without downtime.

<CodeGroup>
```python Python
from thunderphone import verify_signature

ok = verify_signature(
    header,            # the X-ThunderPhone-Signature-V2 value
    secret=SECRET,     # or [NEW_SECRET, OLD_SECRET] while rotating
    method=method,     # "POST"
    path=path,         # "/tools/lookup?region=us", exactly as received
    body=raw_body,     # bytes, before any JSON parsing
    tolerance=300,     # optional; seconds
)
```

```javascript Node.js
import { verifySignature } from "@thunderphone/sdk";

const ok = verifySignature({
  header,               // the X-ThunderPhone-Signature-V2 value
  secret: SECRET,       // or [NEW_SECRET, OLD_SECRET] while rotating
  method,               // "POST"
  path,                 // "/tools/lookup?region=us", exactly as received
  body: rawBody,        // Buffer or string, before any JSON parsing
  toleranceSeconds: 300, // optional
});
```
</CodeGroup>

### Without an SDK

<CodeGroup>
```python Python
import hashlib
import hmac
import time

TOLERANCE_SECONDS = 300


def verify_v2(header: str, secret: str, method: str, path: str, body: bytes) -> bool:
    """path is the path plus ?query exactly as received; body is the raw body."""
    timestamp, signatures = None, []
    for item in (header or "").split(","):
        key, _, value = item.strip().partition("=")
        if key == "t" and value.isdigit() and len(value) <= 15:
            timestamp = int(value)
        elif key == "v1":
            signatures.append(value)
    if timestamp is None or abs(time.time() - timestamp) > TOLERANCE_SECONDS:
        return False
    signed = f"{timestamp}\n{method.upper()}\n{path}\n".encode() + body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected.encode(), s.encode()) for s in signatures)
```

```javascript Node.js
import crypto from "node:crypto";

const TOLERANCE_SECONDS = 300;

// path is the path plus ?query exactly as received; body is the raw Buffer.
export function verifyV2(header, secret, method, path, body) {
  let timestamp;
  const signatures = [];
  for (const item of (header || "").split(",")) {
    const [key, value = ""] = item.trim().split("=", 2);
    if (key === "t" && /^\d+$/.test(value)) timestamp = Number(value);
    else if (key === "v1") signatures.push(value);
  }
  if (timestamp === undefined) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > TOLERANCE_SECONDS) return false;
  const expected = Buffer.from(
    crypto
      .createHmac("sha256", secret)
      .update(`${timestamp}\n${method.toUpperCase()}\n${path}\n`)
      .update(body)
      .digest("hex"),
  );
  return signatures.some((sig) => {
    const candidate = Buffer.from(sig);
    return (
      candidate.length === expected.length &&
      crypto.timingSafeEqual(candidate, expected)
    );
  });
}
```
</CodeGroup>

### Framework wiring

Each example reads the raw path and query and the raw body, then calls
the SDK helper.

<CodeGroup>
```python FastAPI
import json

from fastapi import FastAPI, HTTPException, Request
from thunderphone import verify_signature

app = FastAPI()


def raw_path_and_query(request: Request) -> str:
    path = (request.scope.get("raw_path") or request.url.path.encode()).decode("latin-1")
    query = request.scope.get("query_string", b"").decode("latin-1")
    return f"{path}?{query}" if query else path


@app.post("/thunderphone-webhook")
async def hook(request: Request):
    body = await request.body()  # raw bytes, NOT request.json()
    if not verify_signature(
        request.headers.get("X-ThunderPhone-Signature-V2"),
        secret=SECRET,
        method=request.method,
        path=raw_path_and_query(request),
        body=body,
    ):
        raise HTTPException(status_code=401)
    event = json.loads(body)
    # … dispatch on event["type"] …
    return {"ok": True}
```

```javascript Express
import express from "express";
import { verifySignature } from "@thunderphone/sdk";

const app = express();

app.post(
  "/thunderphone-webhook",
  // IMPORTANT: parse as raw; do NOT use express.json() here.
  express.raw({ type: "application/json" }),
  (req, res) => {
    const ok = verifySignature({
      header: req.header("X-ThunderPhone-Signature-V2"),
      secret: process.env.WEBHOOK_SECRET,
      method: req.method,
      path: req.originalUrl, // path and query as received
      body: req.body,
    });
    if (!ok) return res.sendStatus(401);
    const event = JSON.parse(req.body.toString("utf8"));
    // … dispatch on event.type …
    res.sendStatus(204);
  },
);
```

```python Django
import json

from django.http import HttpResponseForbidden, JsonResponse
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_POST
from thunderphone import verify_signature


@csrf_exempt
@require_POST
def hook(request):
    if not verify_signature(
        request.headers.get("X-ThunderPhone-Signature-V2"),
        secret=SECRET,
        method=request.method,
        path=request.get_full_path(),
        body=request.body,  # raw bytes
    ):
        return HttpResponseForbidden("invalid signature")
    event = json.loads(request.body)
    # … dispatch on event["type"] …
    return JsonResponse({"ok": True})
```
</CodeGroup>

`req.originalUrl` (Express) and the ASGI `raw_path` and `query_string`
(FastAPI) are the target exactly as received. Django's
`get_full_path()` and Flask's `request.path` decode the path first, which
gives the same string for ordinary paths. If your endpoint path contains
percent-encoded or reserved characters such as `%2F`, `;` or `=`, read the
raw target your server provides instead (for example `request.META["RAW_URI"]` on
Gunicorn).

## Which secret?

The same secret signs both headers.

| Source | Secret |
|--------|--------|
| [Webhook endpoint](/webhooks/endpoints) (`/v1/developer/webhook-endpoints`) | Per-endpoint `secret` (48 hex chars) returned once at create |
| [Legacy single-URL webhook](/api-reference/organizations#legacy-single-url-webhook) | Per-org `secret` returned on `GET /v1/webhook` |
| [Tool-endpoint invocation](/tools/overview) (direct call to your `endpoint.url`) | The **org-level webhook secret** (the same one as the legacy single-URL webhook) — not a per-endpoint secret |

Store the secret in your secret manager or env var — never commit it.

## Verifying tool calls

When the agent invokes one of your
[function tools](/tools/overview) directly (the tool has an
`endpoint`), the request carries these ThunderPhone headers alongside
your configured `endpoint.headers`:

- `X-ThunderPhone-Call-ID` — the numeric id of the live call.
- `X-ThunderPhone-Signature-V2` — the timestamped signature above, keyed
  with your **org-level webhook secret**.
- `X-ThunderPhone-Signature` — the legacy body-only signature, same key.

Phone calls also carry `X-ThunderPhone-From-Number`,
`X-ThunderPhone-To-Number` and `X-ThunderPhone-Call-Direction`
([details](/tools/overview#request-headers)). Like every header, they
are not covered by either signature.

Every tool request is signed, even if your org never configured the
legacy webhook: ThunderPhone creates the org secret automatically. Read
it from `GET /v1/webhook`.

One thing differs from webhooks: **`GET` / `DELETE` tools have no
body.** Arguments travel as query parameters. The V2 signature covers
them through the path and query, and the body field is empty. Verify
with the raw query string: parsing the parameters and building a new
query string can change their order or encoding. The legacy header signs
the empty byte string.

```python
@app.api_route("/tools/search-appointments", methods=["GET", "POST"])
async def tool(request: Request):
    body = await request.body()  # b"" for GET/DELETE tools
    if not verify_signature(
        request.headers.get("X-ThunderPhone-Signature-V2"),
        secret=ORG_WEBHOOK_SECRET,
        method=request.method,
        path=raw_path_and_query(request),
        body=body,
    ):
        raise HTTPException(status_code=401)
    call_id = request.headers.get("X-ThunderPhone-Call-ID", "")
    args = json.loads(body) if body else dict(request.query_params)
    ...
```

In Express, a body parser leaves `req.body` as an empty object on a `GET`,
so pass `Buffer.isBuffer(req.body) ? req.body : Buffer.alloc(0)`.

Webhook-**mode** tool dispatch (tools without an `endpoint`, delivered
to your org webhook as `telephony.tool` / `web.tool`) is an ordinary
signed webhook — the standard recipe above applies. See
[Function Tools](/tools/overview) for both request shapes.

## Legacy signature: `X-ThunderPhone-Signature`

The original header is the hex HMAC-SHA256 of the raw body alone, with
the same secret. It carries no timestamp, so anyone who captures one
signed request can replay it. It is still sent on every request while
integrations move to V2.

1. Read the **raw** request body — the exact bytes we sent you.
2. Compute `hmac_sha256(secret, body).hexdigest()`.
3. Compare in **constant time** against `X-ThunderPhone-Signature`.

We sign exactly the bytes we transmit. Those bytes are also the
**canonical JSON serialization** of the payload — keys sorted
alphabetically, compact separators (`,` and `:` with no spaces), UTF-8.
If your framework only exposes parsed JSON, re-serialize canonically and
HMAC that:

```python
# Equivalent to hashing the raw body:
import json
canonical = json.dumps(payload, separators=(",", ":"), sort_keys=True).encode("utf-8")
```

Prefer the raw body — it's one less step and immune to JSON number
round-tripping quirks in some languages. The same holds for the body
field of V2.

<CodeGroup>
```python Python
import hashlib
import hmac


def verify(body: bytes, signature: str, secret: str) -> bool:
    """Constant-time HMAC-SHA256 verification."""
    expected = hmac.new(
        secret.encode("utf-8"),
        body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature or "")
```

```javascript Node.js
import crypto from "node:crypto";

export function verify(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  if (!signature || expected.length !== signature.length) return false;
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature),
  );
}
```

```go Go
package webhook

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
)

func Verify(body []byte, signature, secret string) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(body)
    expected := hex.EncodeToString(mac.Sum(nil))
    return hmac.Equal([]byte(expected), []byte(signature))
}
```

```ruby Ruby
require "openssl"

def verify(body, signature, secret)
  expected = OpenSSL::HMAC.hexdigest("SHA256", secret, body)
  Rack::Utils.secure_compare(expected, signature.to_s)
end
```
</CodeGroup>

## Common pitfalls

<AccordionGroup>
  <Accordion title="Clock skew">
    The 5-minute window is measured against your server's clock. Keep it
    synchronized with NTP; a clock more than 5 minutes off rejects every
    request.
  </Accordion>

  <Accordion title="A proxy rewrites the path">
    The signed path is the one we requested: the path of the URL you
    configured in ThunderPhone. If a reverse proxy or API gateway strips
    or adds a prefix before your application sees the request, rebuild
    the path we sent (for example, put the prefix back) before verifying.
  </Accordion>

  <Accordion title="Re-serializing with default formatting">
    Parsing the body and re-dumping it with your JSON library's
    defaults (spaces after `,` / `:`, insertion-ordered keys) produces
    different bytes and breaks the HMAC. Verify the raw body — or if
    you must re-serialize, match our canonical form exactly: sorted
    keys, compact separators, UTF-8.
  </Accordion>

  <Accordion title="Framework auto-parses JSON">
    Express's `express.json()` middleware consumes the body stream
    and you lose the raw bytes. Use `express.raw()` on the webhook
    route specifically, or buffer the raw body in a pre-middleware.
    Same story for NestJS / Koa — check their "raw body" docs.
  </Accordion>

  <Accordion title="Timing-unsafe comparison">
    `expected === signature` in JS or `expected == signature` in
    Python are timing-variable comparisons. Use `crypto.timingSafeEqual`
    or `hmac.compare_digest` respectively. The performance difference
    is nil.
  </Accordion>

  <Accordion title="Wrong secret for tool endpoints">
    Direct tool-endpoint calls are signed with the **org-level webhook
    secret** (`GET /v1/webhook`) — not with any per-endpoint secret
    from `/v1/developer/webhook-endpoints`. Reuse the same helper,
    but make sure you feed it the org secret on tool routes.
  </Accordion>

  <Accordion title="Query strings on GET/DELETE tools">
    V2 signs the query string exactly as sent. The legacy header signs
    the empty body and never the query string, so hashing the URL for
    the legacy header will never match.
  </Accordion>

  <Accordion title="Duplicates inside the window">
    The timestamp stops replays older than 5 minutes, not a second copy
    inside that window. Endpoint deliveries are at-least-once, so a
    retry of the same event can also arrive; deduplicate on the
    envelope's `event_id`.
  </Accordion>

  <Accordion title="Not returning 401 on mismatch">
    Returning 200 on failed verification makes the handler a replay
    target. Always respond non-2xx if verification fails.
  </Accordion>
</AccordionGroup>

---

## Next steps

<CardGroup cols={2}>
  <Card title="Webhooks overview" icon="bolt" href="/webhooks/overview">
    Delivery semantics, retries, source IPs.
  </Card>
  <Card title="Webhook endpoints" icon="plug" href="/webhooks/endpoints">
    Manage multiple URLs, rotate secrets.
  </Card>
  <Card title="Function Tools" icon="screwdriver-wrench" href="/tools/overview">
    The two tool-invocation paths and their request shapes.
  </Card>
  <Card title="Tool integrations" icon="wrench" href="/guides/build-tool-integration">
    Build a complete tool-backed integration end to end.
  </Card>
</CardGroup>

<!-- en: api-reference/introduction -->
---
title: "Authentication"
description: "How to authenticate with the ThunderPhone API using sk_live_ bearer keys, pick the organization your requests act on, and read the shared error format."
---

The ThunderPhone API is a REST + JSON API. Every public endpoint accepts an
[Organization API key](#api-keys) via the standard OAuth 2.0 Bearer scheme
and returns JSON with UTF-8 encoding.

The resource families listed under
[Available permissions](/guides/oauth#available-permissions) in the OAuth guide
(agents, calls, phone numbers, knowledge, campaigns, integrations, voices,
testing, billing reads) also accept an OAuth 2.0 access token issued by
ThunderPhone's authorization server, sent the same way
(`Authorization: Bearer <access_token>`) and limited to the permissions the
user approved; a request outside them returns `403` with
`error="insufficient_scope"`. Organization, member, and API-key management
endpoints are not available through OAuth. Integration platforms (MCP clients,
Make, the ThunderPhone CLI) connect with OAuth so users never paste an
`sk_live_` key. Endpoints, PKCE, refresh, and revocation are in
[Connect with OAuth](/guides/oauth).

## Base URL

```
https://api.thunderphone.com/v1
```

All examples in this reference are rooted at that base URL. The API is
versioned via the `/v1` path prefix — we add new fields additively and
avoid breaking changes within `v1`.

OpenAPI spec: https://thunderphone.com/docs/openapi.json

## API keys

Create a key from the dashboard:

<Steps>
  <Step title="Sign in">
    Log into the [ThunderPhone Dashboard](https://app.thunderphone.com).
  </Step>
  <Step title="Open Keys">
    Navigate to **Settings → Keys**.
  </Step>
  <Step title="Create key">
    Click **Create API Key**, give it a name (e.g. `production`, `ci`), and copy the `sk_live_...` value.
    The raw key is shown **only once** — if you lose it, revoke and create a new one.
  </Step>
</Steps>

<Warning>
  **Keep API keys secret.** They carry broad access to your organization's
  resources. Never ship them in client-side code or commit them to version
  control. Publishable keys (`pk_live_...`) are **not** API keys — they are
  a separate, origin-restricted credential for the embeddable web widget
  and are not accepted by this API.
</Warning>

<Note>
  **API keys are exempt from the "Require passkeys" org policy.** Passkeys
  are a human 2FA check performed at sign-in and on session use; an
  `sk_live_...` key is a machine credential with no login session to
  attach a passkey check to, so it authenticates independently of that
  policy even when it's enabled for your organization. This is intentional
  — treat key issuance and rotation as your access control for
  server-to-server integrations, and audit or revoke keys from
  **Organization → Keys** the same way you would rotate any other
  standing credential. See [Create a server API key](/guides/api-keys)
  and [Enterprise SSO](/guides/sso#security-policy) for how the policy
  applies to human members.
</Note>

### What API keys can't do

A key acts with the role of the person who created it, so it reaches most
of what that person can, inside the key's own organization. Account
control, money movement, and anything that reaches another organization are
the exception. These endpoints return `403` to an `sk_live_` key and need a
signed-in session instead (see
[Dashboard access](#dashboard-access-x-thunderphone-org)):

| Area | Endpoints closed to API keys |
|------|------------------------------|
| [API keys](/api-reference/developer-api-keys) | List, create, and revoke keys |
| [Members](/api-reference/members) | Remove a member, change a role, transfer ownership, leave |
| [Invites](/api-reference/invites) | List, send, and revoke invites; accept, decline, or request access to one |
| [Organizations](/api-reference/organizations) | Create or delete an organization |
| [Enterprise SSO](/guides/sso) | Change SSO connections or the security policy |
| [Billing](/api-reference/billing) | Change auto-reload or the monthly limit, top up, add or remove a card, set the default card |
| [Client portals](/api-reference/client-portals) | Add, re-enable, or remove a viewer |
| Transfers ([agents](/api-reference/agents), [numbers](/api-reference/phone-numbers), [integrations](/api-reference/integrations), [publishable keys](/api-reference/publishable-keys)) | Copy or move into any organization other than the key's own |

A leaked key therefore can't lock you out, let someone else in, or change
how your organization pays, and revoking it cuts it off. After revoking a
leaked key, also check for publishable keys or SIP endpoint passwords it
may have created. A key can still
spend balance the way your integration does (placing calls, buying
numbers), and reads next to these endpoints, such as listing members,
billing state, and transactions, still work with a key.

## Making a request

Send the key as a bearer token in the `Authorization` header. The API
infers your organization from the key, so **you don't need an org id in
the URL path**.

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/agents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

```python Python
import requests

resp = requests.get(
    "https://api.thunderphone.com/v1/agents",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    timeout=10,
)
resp.raise_for_status()
agents = resp.json()
```

```javascript Node.js
const response = await fetch(
  "https://api.thunderphone.com/v1/agents",
  { headers: { Authorization: `Bearer ${process.env.THUNDERPHONE_API_KEY}` } },
);
if (!response.ok) throw new Error(await response.text());
const agents = await response.json();
```
</CodeGroup>

<Info>
  Successful JSON responses use `200 OK` for reads and `201 Created` for
  writes. Deletes return `204 No Content`. Errors use the standard HTTP
  status codes listed below.
</Info>

## Health check

Verify API connectivity without authentication:

```bash
curl https://api.thunderphone.com/v1/healthz
```

```json Response
{ "ok": true }
```

## Dashboard access (X-ThunderPhone-Org)

The dashboard at [app.thunderphone.com](https://app.thunderphone.com)
authenticates users with a personal session/token (one user can belong to
many organizations). Those requests identify the target organization via
the `X-ThunderPhone-Org` header:

```http
Authorization: Token <personal-token>
X-ThunderPhone-Org: 42
```

You will normally **not** need this header — it exists for the dashboard
code path and for the [account-control endpoints](#what-api-keys-cant-do)
that refuse API keys. API integrations built against an `sk_live_` key
should omit it; the key already carries an org binding and the header, if
present, is ignored for API-key requests.

## ID format

Most core resources use 64-bit integer ids (agents, phone numbers,
calls, members, organizations, publishable keys, VoIP connections).
Newer resources use **UUID** ids — integrations, developer API keys,
webhook endpoints, campaigns, knowledge bases and documents, MCP
servers, provider connections, investigations, and test suites — and
issue reports are addressed by a UUID `trace_id`. Each page states the
id type in its object table. Tokens (invites, API keys) are opaque
strings. Every successful write returns the persisted object including
its assigned id:

```json
{
  "id": 12,
  "name": "Customer Support Agent",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}
```

Timestamps are ISO 8601 with millisecond precision in UTC.

## Pagination

List endpoints return a plain JSON array by default. Endpoints that can
produce very large result sets (currently **calls** and
**issue reports**) accept `limit` and `offset` query parameters and
return a wrapped envelope:

```json
{
  "results": [ /* ... */ ],
  "total":   1234,
  "limit":   50,
  "offset":  0
}
```

To page forward, add `limit` to the current `offset` on each request
and stop when `offset + limit >= total`. See each endpoint's page for
the default and maximum `limit` it accepts.

<Note>
  [Billing transactions](/api-reference/billing#list-transactions) also
  accept `limit`/`offset` but return a plain array without the envelope
  — page forward until you receive fewer rows than `limit`.
</Note>

## Errors

The API uses conventional HTTP status codes:

| Status | Meaning |
|--------|---------|
| `200` | OK |
| `201` | Created |
| `204` | No Content — operation succeeded with no body |
| `400` | Bad Request — invalid parameters. Body contains `detail` or field-specific messages |
| `401` | Unauthorized — missing or invalid API key |
| `402` | Payment Required — insufficient balance |
| `403` | Forbidden — valid credentials but the resource is out of scope or policy denies the action |
| `404` | Not Found — resource doesn't exist (or isn't visible to this key) |
| `409` | Conflict — optimistic-concurrency failures, or an action that requires a live/other state |
| `410` | Gone — deprecated URL shape (see `new_path` in body), or an expired/used invite token |
| `422` | Unprocessable Entity — the request is well-formed but can't be processed (e.g. billing prerequisites not met) |
| `429` | Too Many Requests — a [call limit](#call-limits) or a scoped limit on a specific endpoint (noted on that endpoint's page). A [queued call](/api-reference/outbound-calls#queued-calls) is not one of these |
| `500` | Internal Server Error |
| `502` | Bad Gateway — an upstream provider (LiveKit, VoIP, model backend) failed |
| `503` | Service Unavailable — an upstream provider (e.g. the billing provider) is temporarily unreachable; retry shortly |

Error responses include a JSON body with a human-readable `detail`
message:

```json Error body
{
  "detail": "Call not found."
}
```

Field-specific validation errors (`400`) instead map each offending
field to a list of messages, using DRF's default format:

```json Validation error
{
  "name": ["This field is required."],
  "voice": ["Unsupported voice option."]
}
```

<Note>
  Most endpoints return **only** `detail` (or the field-error map) —
  there is no machine-readable `code` field on generic errors. The
  exception is [Billing](/api-reference/billing#errors), whose payment
  errors add `code`, `retryable`, and `next_action` fields so clients
  can drive recovery flows (3-D Secure, card update, retry).
</Note>

## Rate limiting

There is **no global request rate limit** on the API today. Endpoints
that start calls enforce the [call limits](#call-limits) below. A small
number of other endpoints carry scoped limits — for example, [invite
access requests](/api-reference/invites#request-access-to-an-invite)
are limited to 3 per hour per user. These are documented on the
relevant endpoint pages and return `429 Too Many Requests` when
exceeded. Treat write operations as non-idempotent unless the endpoint
documents otherwise.

### Call limits

Every organization has two call limits. Email
[support@thunderphone.com](mailto:support@thunderphone.com) to raise
either one for your organization.

- **Concurrent calls:** at most **20 calls in progress at once**,
  counting every kind of call together: inbound phone and SIP calls,
  outbound calls (`POST /v1/call`, the MCP `place_call` tool and
  campaigns), web widget sessions, realtime sessions, mic sessions and
  test calls. A call counts from the moment it starts until it ends.
- **Same-number spacing:** outbound calls from your organization to the
  same number must be at least **10 seconds** apart. This applies to
  `POST /v1/call`, `place_call` and campaigns.

Separately, ThunderPhone keeps some of its shared outbound capacity free
for live transfers, so calls placed from ThunderPhone numbers can wait
briefly when it is in use. This is not a limit on your organization, and
calls through your own carrier never wait. [`POST /v1/call` and
`place_call`](/api-reference/outbound-calls#queued-calls) answer as usual,
with a `queued_at` time, and dial when there is room, within 10 minutes.
An organization may have up to 50 calls waiting; past that, a new call gets
`429` with the code `outbound_queue_full` and a `Retry-After` header.
Campaign contacts stay pending without using an attempt.

Your organization's values are the read-only `max_concurrent_calls` and
`min_seconds_between_calls_to_same_number` fields on the
[organization](/api-reference/organizations#organization-object).

A call that would go over a limit is refused before anything is dialed
or billed. Call-starting endpoints return `429 Too Many Requests` with a
`Retry-After` header giving the seconds to wait:

```json Concurrent calls
{
  "code": "concurrent_call_limit_reached",
  "detail": "This organization has reached its limit of 20 concurrent calls. Try again when a call ends. To raise the limit, email support@thunderphone.com.",
  "max_concurrent_calls": 20,
  "retry_after_seconds": 30
}
```

```json Same-number spacing
{
  "code": "same_number_too_soon",
  "detail": "This organization called this number less than 10 seconds ago. Calls to the same number must be at least 10 seconds apart; try again in 7 seconds. To change this, email support@thunderphone.com.",
  "min_seconds_between_calls_to_same_number": 10,
  "retry_after_seconds": 7
}
```

The web widget's session request returns the same values as `error` and
`message`. An inbound call that arrives while your organization is at
its limit is refused and hung up before an agent answers, and is not
billed; it shows in call history as a failed call with end reason
`concurrent_call_limit_reached`. Campaigns never use up a contact's
attempts on either limit: the contact waits and is dialed on a later
pass.

Some features also have their own caps, which apply within the
concurrent-call limit: a campaign runs at most 10 calls at once and
starts no new call while your organization has 10 outbound calls in
progress, the web widget allows 25 active sessions (or your
concurrent-call limit, if that is higher), and at most 10
simulation runs can be active.

## Migration from `/v1/orgs/<id>/...` paths

The API previously nested every resource under your organization id in
the URL path — e.g. `/v1/orgs/42/agents`. Those URLs now return `410
Gone` with a body pointing to the new flat shape:

```json
{
  "detail": "This endpoint moved. Drop the /orgs/<id>/ prefix...",
  "legacy_path": "/v1/orgs/42/agents",
  "new_path": "/v1/agents"
}
```

Existing integrations only need a one-line change: remove `/orgs/<id>`
from every URL. Your `sk_live_` key is unchanged and continues to
identify your organization automatically.

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Create your first agent, provision a number, and take a test call.
  </Card>
  <Card title="Agents" icon="robot" href="/api-reference/agents">
    Configure voices, prompts, and tool integrations.
  </Card>
  <Card title="Calls" icon="phone" href="/api-reference/calls">
    List, inspect, and export call history.
  </Card>
  <Card title="Webhooks" icon="bolt" href="/webhooks/overview">
    Subscribe to real-time events.
  </Card>
</CardGroup>

<!-- en: api-reference/sdks -->
---
title: "Python and TypeScript SDKs"
description: "Typed ThunderPhone clients for agents, calls, and the public API."
---

The ThunderPhone SDKs use the [OpenAPI specification](https://thunderphone.com/openapi.json)
for request and response types. They read `THUNDERPHONE_API_KEY` from your server's
environment. Create a key in the dashboard under **Organization → Keys**, and keep
it in your secret manager. Never include it in browser code.

## TypeScript

Requires Node.js 18 or later. Both ESM and CommonJS are supported.

```bash
npm install @thunderphone/sdk
```

```typescript
import { ThunderPhone } from "@thunderphone/sdk";

const api = new ThunderPhone();
const agent = await api.agents.create({
  name: "Reception",
  prompt: "Help callers with scheduling and business information.",
  voice: process.env.THUNDERPHONE_VOICE!,
});
const call = await api.calls.place({
  agent_id: agent.id,
  from_number: process.env.FROM_NUMBER!,
  to_number: process.env.TO_NUMBER!,
  idempotency_key: "appointment-123",
});
const done = await api.calls.waitForCompletion(call.call_id, { timeoutMs: 300_000 });
if (done.status === "failed") throw new Error(done.end_reason ?? "Call failed");
console.log((await api.calls.transcript(call.call_id)).transcripts);
```

Pass `{ apiKey, baseUrl }` to configure the client explicitly. `baseUrl` defaults
to `https://api.thunderphone.com`, without `/v1`. All operations are available via
`api.client.GET`, `.POST`, `.PUT`, `.PATCH`, and `.DELETE` with typed paths and bodies.
`waitForCompletion` accepts an `AbortSignal`, `timeoutMs`, and `pollIntervalMs`.

## Python

Requires Python 3.10 or later.

```bash
pip install thunderphone
```

```python
import os
from thunderphone import ThunderPhone, AgentRequest, PlaceCallRequest

with ThunderPhone() as api:
    agent = api.agents.create(AgentRequest(
        name="Reception",
        prompt="Help callers with scheduling and business information.",
        voice=os.environ["THUNDERPHONE_VOICE"],
    ))
    call = api.calls.place(PlaceCallRequest(
        agent_id=agent.id,
        from_number=os.environ["FROM_NUMBER"],
        to_number=os.environ["TO_NUMBER"],
        idempotency_key="appointment-123",
    ))
    done = api.calls.wait_for_completion(call.call_id, timeout=300)
    if done.status == "failed":
        raise RuntimeError(done.end_reason)
    print(api.calls.transcript(call.call_id).transcripts)
```

Pass `api_key=` and `base_url=` to configure the client explicitly. Every operation
also has typed sync and async functions under `thunderphone.generated.api`, with
models under `thunderphone.generated.models`. Pass `client=api.client` to use the
same authentication and client-identification header.

## Verify webhook and tool-call signatures

Both SDKs (0.2.0 or later) verify the `X-ThunderPhone-Signature-V2` header
that every webhook and tool request carries. The helpers reject requests
signed more than 5 minutes ago and accept a list of secrets while you
rotate. Pass the raw body and the path with its query string exactly as
received.

<CodeGroup>
```python Python
from thunderphone import verify_signature

ok = verify_signature(
    header, secret=SECRET, method="POST", path="/hooks/thunderphone", body=raw_body
)
```

```typescript TypeScript
import { verifySignature } from "@thunderphone/sdk";

const ok = verifySignature({
  header, secret: SECRET, method: "POST", path: "/hooks/thunderphone", body: rawBody,
});
```
</CodeGroup>

The signed string, a worked example and framework wiring are in
[Verify webhook signatures](/guides/verify-webhook-signatures).

## Calls and errors

Choose `THUNDERPHONE_VOICE` from `GET /v1/voices`. Set `FROM_NUMBER` to an
outbound-enabled number, and `TO_NUMBER` to your test destination. Outbound
calling requires sufficient balance and the organization's outbound confirmation.
Customer VoIP numbers continue to support outbound calling. ThunderPhone-provisioned
numbers start inbound-only; an organization admin can request outbound calling
from the Phone Numbers page, where each request is reviewed manually.

Polling returns completed or failed calls; inspect the status before consuming
the transcript. Helpers raise `ThunderPhoneError` for unsuccessful HTTP responses
and expose `status` and `body`. Transport errors propagate. Requests that mutate
state are not retried automatically. Reuse an idempotency key only for the same
outbound-call request.

For direct tool use from a coding agent, connect to the
[MCP server](https://api.thunderphone.com/v1/mcp). See the
[coding-agent guide](/guides/coding-agents) for setup and the
[OpenAPI specification](https://thunderphone.com/openapi.json) for every operation.

<!-- en: api-reference/organizations -->
---
title: "Organizations"
description: "List, create, update, and delete the organizations that own your agents, phone numbers, and billing, including the legacy single-URL webhook configuration."
---

Organizations are the top-level container for every ThunderPhone
resource — agents, phone numbers, calls, billing, and keys. An API key is
bound to exactly one organization; the endpoints on this page are the
handful that let you enumerate or manage the org resource itself.

The dashboard lets a single user belong to multiple organizations and
switch between them. The API treats your key's bound org as implicit on
every other page in this reference — you do **not** need an org id in
URLs for resource operations. See [Authentication](/api-reference/introduction)
for the full story.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/orgs/` | List organizations the caller belongs to |
| `POST` | `/v1/orgs/` | Create an organization |
| `GET` | `/v1/orgs/{id}/` | Retrieve a single organization |
| `PATCH` | `/v1/orgs/{id}/` | Update the organization's name or reporting settings |
| `DELETE` | `/v1/orgs/{id}/` | Delete the organization |
| `GET` | `/v1/webhook` | Get the single-URL webhook (see note below) |
| `PUT` / `PATCH` | `/v1/webhook` | Set the single-URL webhook |

## Organization object

```json
{
  "id": 42,
  "name": "Acme Operations",
  "role": "owner",
  "timezone": "America/Los_Angeles",
  "business_hours": {
    "mon": [{"start": "09:00", "end": "17:00"}]
  },
  "excluded_numbers": ["+14155550199"],
  "callback_context_details_enabled": false,
  "gdpr_applies": false,
  "max_concurrent_calls": 20,
  "min_seconds_between_calls_to_same_number": 10,
  "new_agent_max_call_duration_seconds": 3600,
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Server-assigned organization id |
| `name` | string | Display name |
| `role` | string \| null | On list responses, the caller's role in this org (`owner`, `admin`, `member`) |
| `timezone` | string | IANA time zone (up to 64 characters) for call-report business hours. `""` means UTC |
| `business_hours` | object | Weekly schedule keyed by `mon` … `sun`; each day holds at most four `{start, end}` windows in 24-hour `HH:MM`, end later than start. `{}` means no after-hours split |
| `excluded_numbers` | array | The organization's own test numbers (up to 50, E.164). Calls from or to them are left out of report counts and Client Portals |
| `callback_context_details_enabled` | boolean | Default `false`. When someone calls back a number that called them, also give the answering agent the earlier call's summary, and that call's `variables` when the agent that placed it answers. Caller ID can be faked, so only turn this on if the earlier call's details are safe to share with anyone who calls from that number. See [Callbacks](/webhooks/call-incoming#callbacks) |
| `gdpr_applies` | boolean | Default `false`. Your record that the GDPR or UK GDPR covers your callers' personal data. It changes nothing on calls |
| `max_concurrent_calls` | integer | Read-only. Most calls this organization can have in progress at once, across inbound, outbound, web and test calls. Default 20. See [Call limits](/api-reference/introduction#call-limits) |
| `min_seconds_between_calls_to_same_number` | integer | Read-only. Minimum seconds between outbound calls from this organization to the same number. Default 10; `0` means no spacing. See [Call limits](/api-reference/introduction#call-limits) |
| `new_agent_max_call_duration_seconds` | integer \| null | Read-only. The `max_call_duration_seconds` a new agent starts with when you create it without one: 3600 (one hour) unless ThunderPhone set another value for your organization; `null` means new agents have no per-agent limit |
| `created_at` | timestamp | ISO 8601 in UTC |
| `updated_at` | timestamp | ISO 8601 in UTC |

---

## List organizations

Returns every organization the caller is a member of.

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/orgs/ \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

```python Python
resp = requests.get(
    "https://api.thunderphone.com/v1/orgs/",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
)
orgs = resp.json()
```

```javascript Node.js
const orgs = await fetch("https://api.thunderphone.com/v1/orgs/", {
  headers: { Authorization: `Bearer ${process.env.THUNDERPHONE_API_KEY}` },
}).then((r) => r.json());
```
</CodeGroup>

Response is a JSON array of [Organization objects](#organization-object).

<Note>
  An API key is bound to exactly one organization, so this list almost
  always has a single entry when authenticated with `sk_live_`. The
  dashboard flow uses personal tokens and can return multiple orgs.
</Note>

---

## Create organization

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/orgs/ \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Operations"}'
```

```python Python
resp = requests.post(
    "https://api.thunderphone.com/v1/orgs/",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={"name": "Acme Operations"},
)
org = resp.json()
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | yes | 1–120 characters |

Returns `201 Created` with the new [Organization object](#organization-object).
The creator becomes the `owner` member automatically.

---

## Get organization

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/orgs/42/ \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

```python Python
resp = requests.get(
    f"https://api.thunderphone.com/v1/orgs/{org_id}/",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
)
```
</CodeGroup>

Returns `200 OK` with an [Organization object](#organization-object), or `404` if
the caller is not a member of the requested org.

---

## Update organization

<CodeGroup>
```bash cURL
curl -X PATCH https://api.thunderphone.com/v1/orgs/42/ \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Ops"}'
```

```python Python
resp = requests.patch(
    f"https://api.thunderphone.com/v1/orgs/{org_id}/",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={"name": "Acme Ops"},
)
```
</CodeGroup>

Returns `200 OK` with the updated [Organization object](#organization-object).
Owners and admins can send `name`, `timezone`, `business_hours`,
`excluded_numbers`, `callback_context_details_enabled` and `gdpr_applies`; see [Organization settings](/guides/organization-settings#configure-reporting-through-the-api)
for an example.

---

## Delete organization

<Warning>
  Destructive and irreversible. Only allowed for the `owner`, from a
  signed-in session: an `sk_live_` API key gets `403` here (see
  [What API keys can't do](/api-reference/introduction#what-api-keys-cant-do)).
  You must remove all other members first. A user cannot delete their
  only organization.
</Warning>

<CodeGroup>
```bash cURL
curl -X DELETE https://api.thunderphone.com/v1/orgs/42/ \
  -H "Authorization: Token YOUR_SESSION_TOKEN"
```

```python Python
resp = requests.delete(
    f"https://api.thunderphone.com/v1/orgs/{org_id}/",
    headers={"Authorization": "Token YOUR_SESSION_TOKEN"},
)
```
</CodeGroup>

Returns `204 No Content`.

| Status | Condition |
|--------|-----------|
| `204` | Deleted |
| `400` | Other members still present, or this is the caller's only org |
| `403` | Caller is not the owner, or the request used an API key |

---

## Legacy single-URL webhook

<Info>
  This is the **original** webhook config: one URL receives every event
  type (`call.incoming`, `call.complete`, …). It is still supported for
  existing integrations.   New integrations should use the
  [Webhook Endpoints](/webhooks/endpoints) system (multiple URLs,
  per-endpoint secrets, event filtering) — see
  [Webhooks overview](/webhooks/overview).
</Info>

### Get webhook config

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/webhook \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

```python Python
resp = requests.get(
    "https://api.thunderphone.com/v1/webhook",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
)
```
</CodeGroup>

Returns `200 OK` with the webhook row, or `404` if the org has not
configured a webhook yet.

```json
{
  "url": "https://example.com/thunderphone-webhook",
  "secret": "whsec_abc123...",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}
```

### Set webhook URL

<CodeGroup>
```bash cURL
curl -X PUT https://api.thunderphone.com/v1/webhook \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/thunderphone-webhook"}'
```

```python Python
resp = requests.put(
    "https://api.thunderphone.com/v1/webhook",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={"url": "https://example.com/thunderphone-webhook"},
)
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | yes | HTTPS URL; `http://` is allowed only for `localhost` during local dev |

The `secret` is generated server-side and rotated only when you
explicitly call `PUT` again. Store it in your secret manager and use it
to verify the `X-ThunderPhone-Signature-V2` signature on inbound requests — see
[Webhooks overview](/webhooks/overview#signature-verification).

---

## Related

<CardGroup cols={2}>
  <Card title="Members" icon="users" href="/api-reference/members">
    Manage roles and memberships within an organization.
  </Card>
  <Card title="Invites" icon="envelope" href="/api-reference/invites">
    Invite users to join your organization.
  </Card>
  <Card title="Webhooks" icon="bolt" href="/webhooks/overview">
    Subscribe to real-time events delivered as HTTP POST requests.
  </Card>
  <Card title="API Keys" icon="key" href="/api-reference/developer-api-keys">
    Rotate the `sk_live_` keys your integrations use.
  </Card>
</CardGroup>

<!-- en: api-reference/members -->
---
title: "Members"
description: "List members, update roles, transfer ownership, and leave an organization."
---

Manage users within your organization. The endpoints on this page scope
to the org bound to your credential — you don't need to pass an org id in
the path.

## Endpoints

| Method | Path | Required role | Description |
|--------|------|---------------|-------------|
| `GET` | `/v1/members` | any member | List members |
| `DELETE` | `/v1/members/{member_id}` | `admin+` | Remove a member |
| `PATCH` | `/v1/members/{member_id}/role` | `owner` | Update a member's role |
| `POST` | `/v1/members/{member_id}/transfer-ownership` | `owner` | Transfer ownership |
| `POST` | `/v1/leave` | any member | Leave the organization |

<Warning>
  Only listing members works with an `sk_live_` API key. Removing a
  member, changing a role, transferring ownership, and leaving need a
  signed-in session (`Authorization: Token <session-token>` plus
  `X-ThunderPhone-Org`) and return `403` to an API key, so a leaked key
  can't take over the organization. See
  [What API keys can't do](/api-reference/introduction#what-api-keys-cant-do).
</Warning>

## Member object

```json
{
  "id": 1,
  "email": "jane@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "role": "admin",
  "has_passkey": true,
  "created_at": "2026-04-20T18:24:10.113Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Membership id (not user id) |
| `email` | string | Member's email |
| `first_name`, `last_name` | string | Member's display name |
| `role` | string | `owner`, `admin`, or `member` |
| `has_passkey` | boolean | Whether the member has a passkey registered on their account |
| `created_at` | timestamp | ISO 8601 UTC |

### Role hierarchy

| Role | Can invite | Can remove members | Can change roles | Can transfer ownership |
|------|-----------|--------------------|--------------------|-----------------------|
| `owner` | ✓ | ✓ (including admins) | ✓ | ✓ |
| `admin` | ✓ | ✓ (members only, not admins) | — | — |
| `member` | — | — | — | — |

Each org has exactly one `owner`.

---

## List members

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/members \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

```python Python
members = requests.get(
    "https://api.thunderphone.com/v1/members",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
).json()
```

```javascript Node.js
const members = await fetch("https://api.thunderphone.com/v1/members", {
  headers: { Authorization: `Bearer ${process.env.THUNDERPHONE_API_KEY}` },
}).then((r) => r.json());
```
</CodeGroup>

Returns a JSON array of [Member objects](#member-object), sorted by `created_at` ascending.

---

## Remove a member

<CodeGroup>
```bash cURL
curl -X DELETE https://api.thunderphone.com/v1/members/5 \
  -H "Authorization: Token YOUR_SESSION_TOKEN" \
  -H "X-ThunderPhone-Org: 42"
```

```python Python
requests.delete(
    f"https://api.thunderphone.com/v1/members/{member_id}",
    headers={"Authorization": "Token YOUR_SESSION_TOKEN", "X-ThunderPhone-Org": "42"},
)
```
</CodeGroup>

Returns `204 No Content`.

| Status | Condition |
|--------|-----------|
| `204` | Removed |
| `400` | Caller tried to remove themself — use [`POST /v1/leave`](#leave-organization) instead |
| `403` | Caller is not admin/owner; caller is admin trying to remove another admin; target is the owner; or the request used an API key |
| `404` | No such member in this org |

<Note>
  You cannot remove yourself with this endpoint — use
  [`POST /v1/leave`](#leave-organization) instead.
</Note>

---

## Update member role

Only the owner can change roles. Supported target roles are `admin` and
`member`. To promote someone to owner, use
[Transfer ownership](#transfer-ownership).

<CodeGroup>
```bash cURL
curl -X PATCH https://api.thunderphone.com/v1/members/5/role \
  -H "Authorization: Token YOUR_SESSION_TOKEN" \
  -H "X-ThunderPhone-Org: 42" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}'
```

```python Python
requests.patch(
    f"https://api.thunderphone.com/v1/members/{member_id}/role",
    headers={"Authorization": "Token YOUR_SESSION_TOKEN", "X-ThunderPhone-Org": "42"},
    json={"role": "admin"},
)
```
</CodeGroup>

| Field | Type | Required | Allowed values |
|-------|------|----------|----------------|
| `role` | string | yes | `admin`, `member` |

Returns `200 OK` with the updated [Member object](#member-object).

---

## Transfer ownership

Promotes another member to `owner` and demotes the current owner to
`admin`. Atomic — if any step fails, no change is applied.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/members/5/transfer-ownership \
  -H "Authorization: Token YOUR_SESSION_TOKEN" \
  -H "X-ThunderPhone-Org: 42"
```

```python Python
requests.post(
    f"https://api.thunderphone.com/v1/members/{member_id}/transfer-ownership",
    headers={"Authorization": "Token YOUR_SESSION_TOKEN", "X-ThunderPhone-Org": "42"},
)
```
</CodeGroup>

<Warning>
  Irreversible without the new owner's cooperation. Make sure you trust
  the recipient before calling this endpoint.
</Warning>

Returns `200 OK`:

```json
{ "detail": "Ownership transferred." }
```

Errors:

| Status | Condition |
|--------|-----------|
| `400` | Target is already the owner (e.g. you passed your own membership id) |
| `403` | Caller is not the owner, or the request used an API key |
| `404` | Target membership not found |

---

## Leave organization

Remove the caller's own membership from the org.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/leave \
  -H "Authorization: Token YOUR_SESSION_TOKEN" \
  -H "X-ThunderPhone-Org: 42"
```

```python Python
requests.post(
    "https://api.thunderphone.com/v1/leave",
    headers={"Authorization": "Token YOUR_SESSION_TOKEN", "X-ThunderPhone-Org": "42"},
)
```
</CodeGroup>

Returns `204 No Content`. Errors:

| Status | Condition |
|--------|-----------|
| `403` | Caller is the owner — transfer ownership first, **or** this is the caller's only organization, **or** the request used an API key |
| `404` | Caller is no longer a member of this org |

---

## Related

<CardGroup cols={2}>
  <Card title="Invites" icon="envelope" href="/api-reference/invites">
    Invite users to join this organization.
  </Card>
  <Card title="Organizations" icon="building" href="/api-reference/organizations">
    Manage the org resource itself.
  </Card>
</CardGroup>

<!-- en: api-reference/invites -->
---
title: "Invites"
description: "Invite users into your ThunderPhone organization by email, choose the role each invite carries, revoke pending invites, and accept or decline the ones you receive."
---

Invites are the mechanism for bringing new members into an organization.
The admin-side endpoints create/list/revoke invites scoped to your org.
The token-side endpoints let an invitee look up, accept, or decline an
invite by its secret token — those endpoints don't require you to be a
member of the target org (the token itself identifies it).

## Endpoints

| Method | Path | Required role | Description |
|--------|------|---------------|-------------|
| `GET` | `/v1/invites` | `admin+` | List pending invites |
| `POST` | `/v1/invites` | `admin+` | Send an invite |
| `DELETE` | `/v1/invites/{invite_id}` | `admin+` | Revoke a pending invite |
| `GET` | `/v1/invites/{token}` | authenticated | Look up an invite by token |
| `POST` | `/v1/invites/{token}/accept` | authenticated | Accept an invite |
| `POST` | `/v1/invites/{token}/decline` | authenticated | Decline an invite |
| `POST` | `/v1/invites/{token}/request-access` | authenticated | Ask the inviter to re-issue the invite to your email |

<Warning>
  Invites decide who joins your organization, so every endpoint on this
  page except the token lookup refuses `sk_live_` API keys with `403`.
  Admin-side calls need a signed-in session (`Authorization: Token
  <session-token>` plus `X-ThunderPhone-Org`); the token-side calls act
  for the signed-in invitee and need only their session token. See
  [What API keys can't do](/api-reference/introduction#what-api-keys-cant-do).
</Warning>

## Invite object (admin list/create)

The list and create endpoints return this object. For the by-token
lookup see [the token lookup response](#look-up-by-token).

```json
{
  "id": 18,
  "email": "new-teammate@example.com",
  "role": "member",
  "status": "pending",
  "invited_by_email": "owner@example.com",
  "created_at": "2026-04-20T18:24:10.113Z",
  "expires_at": "2026-04-27T18:24:10.113Z",
  "token": "a1b2c3d4-...",
  "send_failed": false
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Internal invite id (used by the revoke endpoint) |
| `email` | string | Invitee email |
| `role` | string | Role granted on acceptance: `admin` or `member` |
| `status` | string | `pending`, `accepted`, or `declined` |
| `invited_by_email` | string | Email of the admin/owner who sent the invite |
| `created_at` | timestamp | ISO 8601 UTC |
| `expires_at` | timestamp | 7 days after `created_at` by default |
| `token` | UUID | The invite's secret join token, so an admin can copy the invite link and hand it over directly. Treat it like the invite email itself |
| `send_failed` | boolean | `true` when the invite email could not be sent. The invite still exists; hand over the link built from `token` instead |

---

## List pending invites

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/invites \
  -H "Authorization: Token YOUR_SESSION_TOKEN" \
  -H "X-ThunderPhone-Org: 42"
```

```python Python
invites = requests.get(
    "https://api.thunderphone.com/v1/invites",
    headers={"Authorization": "Token YOUR_SESSION_TOKEN", "X-ThunderPhone-Org": "42"},
).json()
```
</CodeGroup>

Returns a JSON array of [Invite objects](#invite-object-admin-listcreate)
in `pending` state, sorted by `created_at` descending.

---

## Send an invite

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/invites \
  -H "Authorization: Token YOUR_SESSION_TOKEN" \
  -H "X-ThunderPhone-Org: 42" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "new-teammate@example.com",
    "role": "member"
  }'
```

```python Python
invite = requests.post(
    "https://api.thunderphone.com/v1/invites",
    headers={"Authorization": "Token YOUR_SESSION_TOKEN", "X-ThunderPhone-Org": "42"},
    json={"email": "new-teammate@example.com", "role": "member"},
).json()
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `email` | string | yes | Invitee email |
| `role` | string | yes | `admin` or `member` |

Returns `201 Created` with the [Invite object](#invite-object-admin-listcreate).
The invitee receives an email containing a link of the form
`https://app.thunderphone.com/invite/{token}`.
If that email could not be sent, the invite is still created and the
response has `send_failed: true`.

| Status | Condition |
|--------|-----------|
| `400` | Email already has a pending invite for this org, or is already a member |
| `403` | Caller is not an admin/owner |

---

## Revoke an invite

<CodeGroup>
```bash cURL
curl -X DELETE https://api.thunderphone.com/v1/invites/18 \
  -H "Authorization: Token YOUR_SESSION_TOKEN" \
  -H "X-ThunderPhone-Org: 42"
```

```python Python
requests.delete(
    f"https://api.thunderphone.com/v1/invites/{invite_id}",
    headers={"Authorization": "Token YOUR_SESSION_TOKEN", "X-ThunderPhone-Org": "42"},
)
```
</CodeGroup>

Returns `204 No Content`. Only invites with status `pending` can be
revoked.

---

## Look up by token

Public lookup used by the dashboard's invite-landing page. **This
endpoint is unauthenticated** — the token itself is the credential.
Used to render the "You've been invited to join *Acme Ops*" UI.

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/invites/a1b2c3d4-...
```

```python Python
invite = requests.get(
    f"https://api.thunderphone.com/v1/invites/{token}",
).json()
```
</CodeGroup>

Response:

```json
{
  "id": 18,
  "org_name": "Acme Ops",
  "email": "new-teammate@example.com",
  "role": "member",
  "status": "pending",
  "invited_by_email": "owner@example.com",
  "created_at": "2026-04-20T18:24:10.113Z",
  "expires_at": "2026-04-27T18:24:10.113Z"
}
```

| Status | Condition |
|--------|-----------|
| `200` | Pending, not expired — response includes `org_name` for UI display |
| `404` | Token not found |
| `410` | Token exists but is already accepted / declined, or has expired |

---

## Accept an invite

The caller must be authenticated; their user is added to the target org
with the role specified on the invite.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/invites/a1b2c3d4-.../accept \
  -H "Authorization: Token YOUR_SESSION_TOKEN"
```

```python Python
result = requests.post(
    f"https://api.thunderphone.com/v1/invites/{token}/accept",
    headers={"Authorization": "Token YOUR_SESSION_TOKEN"},
).json()
```
</CodeGroup>

Returns `200 OK`:

```json
{
  "detail": "Invite accepted.",
  "org_id": 42
}
```

| Status | Condition |
|--------|-----------|
| `200` | Invite accepted; caller is now a member |
| `403` | Caller is signed in as a user whose email does not match the invite, or the request used an API key |
| `404` | Token not found |
| `410` | Token exists but is already accepted / declined, or has expired |

---

## Decline an invite

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/invites/a1b2c3d4-.../decline \
  -H "Authorization: Token YOUR_SESSION_TOKEN"
```

```python Python
requests.post(
    f"https://api.thunderphone.com/v1/invites/{token}/decline",
    headers={"Authorization": "Token YOUR_SESSION_TOKEN"},
)
```
</CodeGroup>

Returns `204 No Content`.

---

## Request access to an invite

For a signed-in user who received an invite link addressed to a
**different** email (e.g. a forwarded invite): emails the original
inviter asking them to grant access to the caller's account instead.
No membership is created — the inviter decides.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/invites/a1b2c3d4-.../request-access \
  -H "Authorization: Token YOUR_SESSION_TOKEN"
```
</CodeGroup>

No request body. Returns `204 No Content` when the request email was
sent.

| Status | Condition |
|--------|-----------|
| `204` | Access request sent to the inviter |
| `400` | The invite is already addressed to your email (just accept it), or it has no sender to approve access |
| `403` | The request used an API key |
| `404` | Token not found |
| `410` | Invite already accepted / declined, or expired |
| `429` | Rate limited — max 3 access requests per hour per user |
| `503` | The request email could not be sent |

---

## Related

<CardGroup cols={2}>
  <Card title="Members" icon="users" href="/api-reference/members">
    Manage members and roles after they join.
  </Card>
  <Card title="Organizations" icon="building" href="/api-reference/organizations">
    Manage the org resource itself.
  </Card>
</CardGroup>

<!-- en: api-reference/onboarding -->
---
title: "Onboarding"
description: "Read and manage your organization's onboarding checklist state."
---

Each organization carries a server-side onboarding checklist (the
"getting started" coach in the dashboard). Steps complete
**automatically** as the org performs the underlying action — creating
and talking to an agent, adding billing, getting a phone number, and
taking a first call. The API exposes the state read-only, plus
dismiss/undismiss controls and one explicit skip.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/onboarding` | Current onboarding state |
| `POST` | `/v1/onboarding/dismiss` | Hide the checklist |
| `POST` | `/v1/onboarding/undismiss` | Show it again |
| `POST` | `/v1/onboarding/agent-talk/skip` | Complete the agent step without the mic test |

## Onboarding object

All four endpoints return the same object (the POSTs return the
updated state):

```json
{
  "steps": {
    "agent":   { "completed": true,  "completed_at": "2026-04-20T18:24:10.113Z" },
    "billing": { "completed": true,  "completed_at": "2026-04-20T18:30:02.551Z" },
    "phone":   { "completed": false, "completed_at": null },
    "call":    { "completed": false, "completed_at": null }
  },
  "all_complete": false,
  "dismissed": false,
  "dismissed_at": null
}
```

| Step | Completes when… |
|------|-----------------|
| `agent` | The org has an agent **and** someone talked to it via a mic session (or the talk step was explicitly [skipped](#skip-the-agent-talk-step)) |
| `billing` | A payment method is saved or a top-up succeeds |
| `phone` | The org gets its first phone number |
| `call` | The org's first real call completes |

`dismissed` hides the checklist in the dashboard without changing step
state; `undismiss` re-shows it. Steps never un-complete.

### Skip the agent-talk step

`POST /v1/onboarding/agent-talk/skip` marks the `agent` step complete
even though no mic call happened — used when the builder tour's
optional "Talk to your agent" step is skipped. The org must actually
have an agent for the step to complete.

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/onboarding \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

---

## Related

<CardGroup cols={2}>
  <Card title="Agents" icon="robot" href="/api-reference/agents">
    Step 1: create an agent.
  </Card>
  <Card title="Billing" icon="credit-card" href="/api-reference/billing">
    Step 2: add funds.
  </Card>
  <Card title="Phone Numbers" icon="phone" href="/api-reference/phone-numbers">
    Step 3: get a number.
  </Card>
  <Card title="Mic Sessions" icon="microphone" href="/api-reference/mic-sessions">
    Talk to your agent from the browser.
  </Card>
</CardGroup>

<!-- en: api-reference/client-portals -->
---
title: "Client Portals"
description: "Create and administer branded client portals over the ThunderPhone API, including agent scope, viewers, logos, custom domains, and DNS verification."
---

Client portals give external viewers a branded, read-only call-history
experience for a selected set of agents. The management API is organization
scoped and requires an **admin or owner** authenticated with an `sk_live_` key,
except for viewer changes: adding, re-enabling, or removing a viewer grants or
withdraws a login to your call history, so it needs a signed-in admin session
(`Authorization: Token <session-token>` plus `X-ThunderPhone-Org`) and returns
`403` to an API key. Listing viewers still works with a key. See
[What API keys can't do](/api-reference/introduction#what-api-keys-cant-do).

Viewer login, sessions, call browsing, transcripts, and audio use the hosted
portal's separate viewer authentication. They are not `sk_live_` integration
endpoints.

## Endpoints

| Method | Path | Description |
| --- | --- | --- |
| `GET` | `/v1/client-portals` | List portals. |
| `POST` | `/v1/client-portals` | Create a portal. |
| `GET` | `/v1/client-portals/{portal_id}` | Retrieve a portal. |
| `PATCH` | `/v1/client-portals/{portal_id}` | Update details, active state, branding color, or agents. |
| `DELETE` | `/v1/client-portals/{portal_id}` | Permanently delete a portal. |
| `POST` | `/v1/client-portals/{portal_id}/logo` | Upload or replace a logo. |
| `DELETE` | `/v1/client-portals/{portal_id}/logo` | Remove the logo. |
| `GET` / `POST` | `/v1/client-portals/{portal_id}/viewers` | List or add viewers. Adding needs a signed-in session. |
| `PATCH` / `DELETE` | `/v1/client-portals/{portal_id}/viewers/{viewer_id}` | Activate/deactivate or delete a viewer. Needs a signed-in session. |
| `GET` / `POST` | `/v1/client-portals/{portal_id}/domains` | List or add custom domains. |
| `DELETE` | `/v1/client-portals/{portal_id}/domains/{domain_id}` | Remove a custom domain. |
| `POST` | `/v1/client-portals/{portal_id}/domains/{domain_id}/verify` | Check the ownership TXT record. |

## Portal object

```json
{
  "id": 18,
  "name": "Acme Dental",
  "slug": "acme-dental",
  "accent_color": "#2e8fff",
  "is_active": true,
  "logo_url": "https://…",
  "agent_ids": [12, 19],
  "agent_count": 2,
  "viewer_count": 3,
  "calls_last_30d": 147,
  "created_at": "2026-07-16T18:24:10.113Z",
  "updated_at": "2026-08-05T09:40:12.551Z"
}
```

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer | Portal id used by management endpoints. |
| `name` | string | Client-facing name, maximum 255 characters. |
| `slug` | string | Globally unique hosted URL slug, maximum 100 characters. |
| `accent_color` | string | Empty for the default, or a full six-digit hex color. |
| `is_active` | boolean | Inactive portals cannot be opened by viewers. |
| `logo_url` | string \| null | Temporary or hosted URL for the current logo. |
| `agent_ids` | array of integer | Agents whose calls are in the portal scope. |
| `agent_count`, `viewer_count` | integer | Current related-resource counts. |
| `calls_last_30d` | integer | Calls from assigned agents in the preceding 30 days. |
| `created_at`, `updated_at` | timestamp | ISO 8601 timestamps. |

## List and create portals

```bash
curl https://api.thunderphone.com/v1/client-portals \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

The list is sorted by name, then id.

```bash
curl -X POST https://api.thunderphone.com/v1/client-portals \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Dental","slug":"acme-dental"}'
```

| Field | Required | Validation |
| --- | --- | --- |
| `name` | yes | Non-empty after trimming; maximum 255 characters. |
| `slug` | no | Maximum 100 characters. Lowercase letters, numbers, and single hyphens only; must be unique and not reserved. A unique slug is generated from `name` when omitted. |

Returns `201 Created` with the portal object.

## Retrieve, update, and delete

`PATCH /v1/client-portals/{portal_id}` accepts any subset of:

| Field | Type | Behavior |
| --- | --- | --- |
| `name` | string | Replaces the client-facing name. |
| `slug` | string | Replaces the hosted URL slug after uniqueness validation. |
| `is_active` | boolean | Enables or disables all viewer access. |
| `accent_color` | string | Six-digit hex such as `#2e8fff`, or `""` for the default. |
| `agent_ids` | array of integer | Replaces the complete assigned-agent set. Duplicates are removed; every id must belong to the organization. Use `[]` for no visible calls. |

```bash
curl -X PATCH https://api.thunderphone.com/v1/client-portals/18 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_ids":[12,19],"accent_color":"#2e8fff"}'
```

`DELETE` returns `204 No Content` and permanently removes the portal, its
viewers, domain records, and logo reference. It does not delete agents or calls.

## Upload or remove a logo

Upload multipart form field `file`. The accepted formats are **PNG**, **JPEG**,
and **WebP**, with a maximum size of **2 MB**. The file contents must match the
declared MIME type.

```bash
curl -X POST https://api.thunderphone.com/v1/client-portals/18/logo \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -F "file=@acme-logo.png"
```

The response is `{"logo_url":"https://…"}`. Uploading a new logo replaces
the old one. `DELETE` removes it and returns `204`.

## Viewers

The viewer object is:

```json
{
  "id": 31,
  "email": "client@example.com",
  "is_active": true,
  "has_password": false,
  "created_at": "2026-08-05T09:40:12.551Z",
  "updated_at": "2026-08-05T09:40:12.551Z"
}
```

Add a unique email address from a signed-in admin session:

```bash
curl -X POST https://api.thunderphone.com/v1/client-portals/18/viewers \
  -H "Authorization: Token YOUR_SESSION_TOKEN" \
  -H "X-ThunderPhone-Org: 42" \
  -H "Content-Type: application/json" \
  -d '{"email":"client@example.com"}'
```

Returns `201`. `PATCH` accepts only `is_active`; setting it to `false` blocks
login without deleting the viewer. `DELETE` returns `204`.

## Custom domains

Create a domain with its hostname only:

```bash
curl -X POST https://api.thunderphone.com/v1/client-portals/18/domains \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"calls.client.com"}'
```

Returns `201`:

```json
{
  "id": 7,
  "hostname": "calls.client.com",
  "verification_token": "tp_verify_…",
  "status": "pending",
  "verified_at": null,
  "cname_record": {
    "name": "calls.client.com",
    "value": "CNAME_TARGET_FROM_RESPONSE"
  }
}
```

The hostname is normalized, can be at most 253 characters, and must be unique
across portals. Add the returned CNAME, then add this TXT record:

| Type | Name | Value |
| --- | --- | --- |
| TXT | `_tp-portal-verify.calls.client.com` | The returned `verification_token`. |

Check it with:

```bash
curl -X POST https://api.thunderphone.com/v1/client-portals/18/domains/7/verify \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

On success, the domain object has `status: "active"` and `verified_at`. While
the TXT record is not visible, the response remains pending and repeats the
expected TXT and CNAME records. DNS propagation can take several minutes.

`DELETE /domains/{domain_id}` returns `204` and releases the hostname for reuse.

## Errors and authorization

| Status | Meaning |
| --- | --- |
| `400` | Invalid slug, color, agent list, upload, email, or hostname. |
| `401` | Missing or invalid API key. |
| `403` | The authenticated user or key is not authorized for admin management, or an API key tried to change a viewer. |
| `404` | Portal or nested resource is outside the current organization or absent. |
| `204` | Successful deletion. |

For the dashboard workflow and viewer experience, see
[Client portals](/guides/client-portals).

<!-- en: api-reference/agents -->
---
title: "Agents"
description: "Create and manage voice agents over REST: configure prompts, engines, voices, languages, tools, and knowledge, then deploy, duplicate, transfer, or version them."
---

An **agent** is the configuration that drives every ThunderPhone call —
the product tier, the voice, the languages, the system prompt, the
acknowledgement behavior, silence/voicemail handling, the attached
tools and knowledge, and whether the agent is reachable from the web
widget. Phone numbers assign an inbound and/or outbound agent; outbound
calls and mic sessions can target an agent directly.

Agents use a **draft / deploy** workflow: edits made via `PATCH`/`PUT`
are saved as a *draft* and do **not** affect production calls until you
`POST /deploy`. Test calls and mic sessions run against the draft (when
one exists) so you can try changes before shipping them.

For dashboard setup, see [Voice agent settings](/guides/agent-settings). For
prompt-callable actions, see [Built-in tools](/guides/built-in-tools) and
[Transfer calls](/guides/call-transfers).

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/agents` | List agents |
| `POST` | `/v1/agents` | Create an agent |
| `GET` | `/v1/agents/{agent_id}` | Retrieve a single agent |
| `PUT` / `PATCH` | `/v1/agents/{agent_id}` | Save changes to the agent's **draft** |
| `POST` | `/v1/agents/{agent_id}/deploy` | Promote the draft to the deployed config |
| `POST` | `/v1/agents/{agent_id}/discard-draft` | Throw away all pending draft changes |
| `GET` / `POST` | `/v1/agents/{agent_id}/relabel-calls` | Put past calls on the agent's current [outcome labels](#relabel-past-calls) |
| `DELETE` | `/v1/agents/{agent_id}` | Delete an agent |
| `POST` | `/v1/agents/{agent_id}/duplicate` | Duplicate an agent |
| `POST` | `/v1/agents/{agent_id}/transfer` | Copy or move an agent to another org |
| `GET` | `/v1/agents/{agent_id}/versions` | List deployed configuration revisions |
| `POST` | `/v1/agents/{agent_id}/versions/{revision}/restore` | Put the agent back to a deployed revision |
| `GET` / `POST` / `DELETE` | `/v1/agents/{agent_id}/intro-clip` | Download, upload or remove the agent's custom [intro clip](#intro-clip) |
| `GET` / `POST` | `/v1/agents/{agent_id}/consent-attestations` | List or record consent-announcement attestations |
| `GET` / `POST` | `/v1/phi-designation-attestation` | Read or record an agent's no-PHI designation attestation |
| `POST` | `/v1/agents/prompt-language-check` | Detect the language of a prompt |
| `POST` | `/v1/agents/translate-prompt` | Translate a prompt into another locale |
| `POST` | `/v1/agents/generate-acknowledgement-prompt` | Auto-generate a Storm-mode acknowledgement prompt |
| `POST` | `/v1/agents/steps/flatten` | Render shared instructions and steps as one prompt |
| `POST` | `/v1/agents/{agent_id}/prompt-analysis` | Check a prompt against the agent's configuration |
| `POST` | `/v1/agents/{agent_id}/prompt-review` | Review a prompt against the prompt style guide |
| `POST` | `/v1/agents/{agent_id}/prompt-refactor` | Rewrite a prompt into the style guide's shape |

Related agent-scoped surfaces documented on their own pages:
[test scenarios & suites](/api-reference/test-scenarios),
[split testing (A/B variants)](/api-reference/split-testing).

## Agent object

```json
{
  "id": 12,
  "name": "Customer Support Agent",
  "prompt": "You are a helpful support agent for Acme Ops…",
  "voice": "john",
  "primary_language": "en",
  "additional_languages": [],
  "native_voice_switching": false,
  "language_voices": {},
  "language_switching": "ask_first",
  "audio_tier": "standard",
  "endpointing": "normal",
  "intelligence": "standard",
  "faster_replies_enabled": true,
  "product": "spark",
  "thinking_level": "base",
  "background_track": "NONE",
  "acknowledgement_prompt_mode": "auto",
  "acknowledgement_prompt": "",
  "acknowledgement_feedback_mode": "acknowledgement",
  "inbound_speak_order": "agent_first",
  "outbound_speak_order": "caller_first",
  "voicemail_action": "prompt",
  "voicemail_message": "",
  "silence_interval_seconds": 15,
  "silence_max_checkins": 3,
  "silence_checkins_enabled": true,
  "silence_hangup_seconds": 600,
  "silence_final_action": "hang_up",
  "silence_transfer_destination": "",
  "silence_final_message": "",
  "max_call_duration_seconds": 3600,
  "ring_duration_seconds": null,
  "max_hold_seconds": null,
  "connect_tone_enabled": false,
  "typing_sounds_enabled": false,
  "typing_sound": "keys_and_mouse",
  "filler_phrases_enabled": true,
  "pronunciation_dicts": false,
  "tool_start_line": "always",
  "play_sound_asset": "",
  "intro_clip": "none",
  "intro_clip_artifact_path": "",
  "intro_clip_sha256": "",
  "intro_ring_count": 1,
  "speak_uninterruptible_enabled": false,
  "send_email_enabled": false,
  "send_email_recipient": "",
  "calculator_enabled": false,
  "do_not_call_detection_enabled": true,
  "system_tool_settings": {"end_call": false},
  "transfer_destinations": [
    {"name": "Billing", "number": "+14155552671", "platform_ok": true},
    {"name": "Assigned rep", "number": "{{rep_phone}}", "platform_ok": null}
  ],
  "warm_transfer_style": "introduce",
  "warm_transfer_briefing": "",
  "consent_announcement_enabled": true,
  "consent_announcement_text": "This call may be recorded…",
  "consent_disabled_reason": "",
  "audio_context_mode": "full",
  "watchdog_enabled": false,
  "additional_audio_context": null,
  "extraction_fields": [
    {
      "key": "insurance_type",
      "type": "enum",
      "description": "Insurance type requested by the caller",
      "options": ["term", "whole"],
      "required": false,
      "ask": true
    }
  ],
  "extraction_blocks_completion": "except_transfers",
  "call_summary_enabled": false,
  "outcome_labels": [],
  "report_instructions": "",
  "timezone": "America/New_York",
  "business_hours": null,
  "reusable_instructions": [],
  "integrations": [],
  "knowledge_bases": [],
  "knowledge_documents": [],
  "mcp_servers": [],
  "tool_collision_warnings": [],
  "widget_enabled": true,
  "split_testing_enabled": false,
  "steps": null,
  "handoffs": [],
  "words": [
    {
      "term": "Quayside",
      "say_as": "Kee side",
      "ipa": "ˈkiːsaɪd",
      "language": "en",
      "case_sensitive": false,
      "speak_with": "auto",
      "hear": false,
      "step": null,
      "hear_always": false,
      "hear_when": null,
      "checked": null,
      "support": {
        "level": "phonetic",
        "reason": "Uses phonetic spelling on this voice. Voices usually follow it, but not always. Preview to check.",
        "step_missing": false
      }
    }
  ],
  "warnings": [],
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z",
  "draft_prompt": null,
  "draft_voice": null,
  "draft_consent_announcement_enabled": null,
  "draft_updated_at": null,
  "has_draft": false
}
```

### Deployed fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Server-assigned agent id |
| `name` | string | Human-readable name. 1–255 chars |
| `prompt` | string | The system prompt that governs agent behavior |
| `voice` | string | Voice name from [`GET /v1/voices`](#voices) — e.g. `john`, `megan`. Entitled organizations can also pass [`custom:<public_id>`](/api-reference/custom-voices#use-a-custom-voice) for a ready custom voice, any agent that does not process PHI can use an [ElevenLabs voice](#elevenlabs-voices) as `elevenlabs:<voice_id>`, and any voice from [`GET /v1/voices/library`](#every-voice) works by its `name` |
| `primary_language` | string | ISO 639 code, e.g. `en`, `es`. Default `en`. Drives the default TTS locale |
| `additional_languages` | array of string | Extra language codes the agent supports (`es` or BCP-47 `es-ES`) |
| `native_voice_switching` | boolean | For multilingual agents using catalog voices, switch to a native voice for the detected additional language, matched by gender. Returns to the configured voice for the primary language and keeps the current voice if no match is available. Default `false` |
| `language_voices` | object | The voice a call uses when it starts in a given language, by language code: `{"es": "marta"}`. Used when a call names its own `language` (a config webhook's `agent_id` answer, a widget or realtime session; see [Set the language per call](/guides/dynamic-call-config#set-the-language-per-call)), ahead of native voice switching's choice and of the agent's own voice. Each voice must speak its language. Default `{}` |
| `language_switching` | string | How a multilingual agent handles the other person (the caller, or the person an outbound call reaches) speaking another of its languages. `ask_first` (default) switches at once when they ask for the language or say a full sentence in it, and asks whether to continue in it after something short, like a "sí". `follow_caller` switches to whatever configured language they speak, even a single word. Applies only when `additional_languages` is set |
| `endpointing` | string | How long a Bolt v2 agent waits after the caller stops before asking the model for a reply: `faster` (200 ms), `fast` (300 ms), `normal` (500 ms, default) or `patient` (800 ms). Shorter waits can answer sooner but send more requests that the caller's next words make stale, which raises the model cost, and can talk over callers who pause mid-sentence; how fast the reply then arrives also depends on the intelligence tier. `patient` suits callers reading out numbers, addresses or spellings. Other products ignore it |
| `eagerness` | string | Deprecated: the name of `endpointing` until October 19, 2026. Responses still include it with the same value, and writes may still send it instead of `endpointing`; sending both with different values is a `400` |
| `intelligence` | string | The intelligence tier of a Bolt agent on the Bolt v2 pipeline: which model writes its replies. Ignored while `audio_tier` is `deep_hearing`, whose calls always run `standard`. `lite`: ~700 ms to first word; cheapest and fastest, follows instructions a little less reliably than Standard (on calls treated as PHI, ~900 ms and less reliable). `standard` (default): ~900 ms to first word; our production model. A Lite reply that would only call a tool, with no spoken words, is handed to the Standard model (except staying silent, waiting on hold and pressing keypad digits), which also takes over if the tier's model is unavailable. Other products ignore it |
| `faster_replies_enabled` | boolean | Default `true`. On a Bolt agent on the Bolt v2 pipeline, on replies where it helps, sends two requests and uses whichever answers first. Those replies use twice the model tokens. `false` turns that off, and some replies may take longer. The Hearing audio tier's audio check can still send extra requests. Other products ignore it. |
| `product` | string | Product tier. One of: `spark`, `bolt`, `storm-base`, `storm-base-with-ack`, `storm-extra`, `storm-extra-with-ack` |
| `audio_tier` | string | Bolt only ("Audio understanding" in the dashboard): how the agent hears the caller. `standard` (default) runs three transcribers; calls that process PHI use only BAA-covered transcribers. `lean` downgrades to one transcriber; it is cheapest and mishears more often. `hearing` upgrades to `standard` plus a powerful ensemble of audio models that listens to the caller's audio on some turns, best for languages and names; those turns take about 1–2 seconds longer, and `acknowledgement_feedback_mode` sets what the caller hears meanwhile. `deep_hearing` ("Deep Hearing", the highest tier): for exceptionally hard cases like rare languages; replies take about 3–4 seconds, and calls run `standard` intelligence whatever `intelligence` is set to (the stored value applies again on another tier). Not generally available: only organizations it has been enabled for can set it; others get `400`. Other products ignore it |
| `thinking_level` | string | `base` or `extra`. Derived from `product` for Storm tiers |
| `background_track` | string | Ambient audio track name, or `"NONE"` for silence. **Never `null`** — a `null` write is coerced to `"NONE"` |
| `acknowledgement_prompt_mode` | string | `auto` (we generate the ack prompt) or `manual` (you supply it) |
| `acknowledgement_prompt` | string | Used when `acknowledgement_prompt_mode="manual"`. Storm-tier only |
| `acknowledgement_feedback_mode` | string | What the caller hears while a Storm agent thinks, or while the audio models work out a turn on a Bolt agent with `audio_tier` `hearing` or `deep_hearing`: `acknowledgement` (default, a short spoken acknowledgement), `tick` (ticking sound) or `none` (silence) |
| `inbound_speak_order` | string | Who talks first on inbound calls. `agent_first` or `caller_first` |
| `outbound_speak_order` | string | Who talks first on outbound calls |
| `voicemail_action` | string | What to do when a voicemail system answers: `prompt` (let the agent decide), `hangup`, or `message` (leave a message). Leaving a short message usually gets more callbacks, and callbacks help the number's standing with carriers; `hangup` lists `voicemail_hangup_on_outbound` in `warnings` |
| `voicemail_message` | string | TTS template for `voicemail_action="message"`, max 2000 chars. Supports `{agent_name}` and `{org_name}` variables |
| `silence_interval_seconds` | integer or null | Seconds between "are you still there?" check-ins. 10–120, default 15. `null` lets ThunderPhone pace them by context, the schedule an inline config without this field gets: before the caller has spoken, after 6, 10 and 15 seconds; ordinary quiet, after 10, 15 and 15 seconds; after the caller asks to wait, at least 60 seconds |
| `silence_max_checkins` | integer | Check-ins before the agent hangs up. 1–10, default 3 |
| `silence_checkins_enabled` | boolean | Whether the agent proactively checks in during caller silence. Default `true` |
| `silence_hangup_seconds` | integer | Caller-idle seconds before a silent hangup when check-ins are disabled. 60–3600, default 600 |
| `silence_final_action` | string | What the agent does after its last check-in: `hang_up` (default) or `transfer` to `silence_transfer_destination`. A transfer that can't be placed hangs up |
| `silence_transfer_destination` | string | Name of one of the agent's `transfer_destinations`, matched without regard to case. Required when `silence_final_action` is `transfer`. Default `""` |
| `silence_final_message` | string | What the agent says at that moment, read as written, up to 300 characters. `""` (default) uses the default line in the call's language |
| `max_call_duration_seconds` | integer or null | Maximum call length in seconds. 60–21600 (1 minute–6 hours); `null` means no per-agent limit. New agents start at your organization's new-agent default (3600, one hour) unless you send a value; agents created before that default keep what they had. Every call ends after 6 hours whatever this says |
| `ring_duration_seconds` | integer or null | Ringing time for outbound and transferred calls, in seconds. 5–120; null uses platform defaults (60s outbound, 45s warm transfer, provider default for cold transfer). Outbound calls ring for at least 14 seconds whatever this says, because a call that rings briefly and drops looks like a one-ring scam call; a shorter value still saves and applies to transfers. Does not affect inbound ringing. |
| `max_hold_seconds` | integer or null | How long the agent waits on hold during a call it places before it hangs up, in seconds. 10–900; `null` uses the default (900, 15 minutes). A `max_hold_seconds` sent with an outbound call overrides it for that call |
| `connect_tone_enabled` | boolean | Play a short connection tone before the agent begins. Default `false` |
| `typing_sounds_enabled` | boolean | Play a soft keyboard sound while a custom tool runs. Platform-managed tools do not trigger it. Default `false` |
| `typing_sound` | string | Which typing sound plays when `typing_sounds_enabled` is on: `keys_and_mouse`, `mechanical`, `desktop`, `laptop`, `office`, or `quiet_room`. Default `keys_and_mouse` |
| `filler_phrases_enabled` | boolean | Long-wait updates: on a slow tool or reply, lines such as "Sorry, this is taking a little longer than expected" after the tool-start line. `false` stays quiet after the tool-start line, which `tool_start_line` controls. Default `true` |
| `pronunciation_dicts` | boolean | Use ThunderPhone's pronunciation dictionary for the agent's Cartesia speech on phone, widget and test calls (not Realtime sessions). Applies only with ThunderPhone's own Cartesia voices, not a customer's own Cartesia key. Same as an inline config's `pronunciation_dicts`. Default `false` |
| `tool_start_line` | string | Tool-start line: what ThunderPhone says when the agent calls a tool. `always`: something at every tool call (the agent's own words, or a short line written for the call). `only_if_slow`: a short line only if the tool is still running after about 3 seconds. `never`: nothing from ThunderPhone, and the agent is told not to speak at tool calls. The agent's own words always play. New agents default to `always`; agents created before this field existed have `only_if_slow`. Prompt text cannot override it |
| `play_sound_asset` | string | Prompt-callable sound asset: `""` (none), `chime`, `ding`, or `beep` |
| `intro_clip` | string | Prerecorded clip played at the start of inbound phone calls (and Talk browser test calls), before the agent speaks: `none`, `stock_recording_notice` ("This call may be monitored or recorded, for quality assurance purposes."), or `custom` (the clip uploaded with [`POST /v1/agents/{agent_id}/intro-clip`](#intro-clip); plays nothing until one is uploaded). Not played on outbound calls, AI test calls, web widget calls or Realtime API calls. Default `none` |
| `intro_clip_artifact_path` | string | Read-only. Storage path of the uploaded custom clip, `""` when there is none |
| `intro_clip_sha256` | string | Read-only. SHA-256 of the uploaded custom clip, `""` when there is none |
| `intro_ring_count` | integer | US rings played after the intro clip, before the agent speaks. 0–2, default 1. Only used when `intro_clip` is not `none` |
| `speak_uninterruptible_enabled` | boolean | Legacy compatibility field. The `speak_uninterruptible` tool is currently unavailable, so this setting has no runtime effect. Default `false` |
| `send_email_enabled` | boolean | Offer the built-in email tool when `send_email_recipient` is also set. Default `false` |
| `send_email_recipient` | string | Fixed recipient for the built-in email tool. The model supplies only the subject and body and cannot choose or change this address |
| `calculator_enabled` | boolean | Offer the built-in `calculate` tool, which adds up totals and prices exactly. Default `false` |
| `do_not_call_detection_enabled` | boolean | On outbound calls, when the person asks not to be called again, the agent apologizes, ends the call and adds the number to your [opt-out list](/api-reference/opt-outs). Default `true`. Setting it to `false` needs your organization's [do-not-call detection attestation](/api-reference/opt-outs#turning-detection-off) |
| `system_tool_settings` | object | Turn the `end_call`, `send_keypad_input` and `wait_on_hold` built-in tools on (`true`) or off (`false`) for every call. A tool left out follows the call: `end_call` is on, and the other two are on for outbound calls only. Default `{}` |
| `send_sms_enabled` | boolean | Offer the `send_sms` tool when a customer-connected SMS-capable sender is available. Default `false` |
| `sms_from_number` | string | Optional E.164 fallback sender on the organization's connected Twilio or Telnyx account |
| `sms_allowed_recipients` | array of object | Up to 10 owner-configured contacts the agent may text. Each object has a unique E.164 `number` and a unique NFKC-normalized, case-insensitive `label` of 1–60 visible characters. Labels cannot look like phone numbers and are caller-visible public metadata; only labels are shown to the model |
| `sms_allow_other_recipients` | boolean | Allow the model to text any valid E.164 number, including any number a caller dictates. Default `false`. This broad permission is not required for the telephone other party or `sms_allowed_recipients` |
| `transfer_destinations` | array of object | The agent's [transfer numbers](#transfer-numbers): up to 50 `{name, number}` entries (or `{name, action: "return"}`), each with optional `headers` and a read-only `platform_ok`. The agent transfers only to these, by name; `[]` (the default for new agents) means it can't transfer calls |
| `warm_transfer_style` | string | What happens when a [warm transfer](/guides/call-transfers#before-connecting) is answered. `introduce` (default, **Introduce on the line**): the caller is connected as soon as the person answers, then the agent introduces the caller on the line, which both hear, and drops. `ask_first` (**Ask first**): the caller waits on hold while the agent privately asks the person who answers whether they can take the call; they can decline. On yes the caller is connected and introduced on the line. `whisper` (**Whisper**): the caller waits on hold while the agent privately tells the person who answers who is calling and why, without asking; then the caller is connected and the agent drops with nothing said on the line |
| `warm_transfer_briefing` | string | What the agent tells the person who answers a [warm transfer](/guides/call-transfers#the-briefing) about the caller, as an instruction to the agent, for example `"The caller's name and what they need."`. ≤300 characters; line breaks and repeated spaces are collapsed. `""` (the default) keeps a very short briefing: who is calling and why |
| `sms_followup_enabled` | boolean | Send one SMS from the customer carrier after an eligible completed telephone call. Default `false` |
| `sms_followup_template` | string | Plain-text follow-up template. Supports call variables and extracted fields when present |
| `consent_announcement_enabled` | boolean | Play the configured AI/recording announcement at call start. Default `true`; disabling requires an active [consent attestation](#consent-attestations) where applicable |
| `consent_announcement_text` | string | Announcement played verbatim at call start; must not be blank and is limited to 2000 characters in the dashboard |
| `consent_disabled_reason` | string | Read-only platform-managed status associated with an announcement exception. Clients cannot set it |
| `audio_context_mode` | string | API-only Storm compatibility control: `full` or `reduced` (lower latency, less prior audio). This is separate from `additional_audio_context` |
| `watchdog_enabled` | boolean | Enables live supervision of agent turns (Storm). Default `false` |
| `additional_audio_context` | boolean \| null | Backing field for the dashboard's **Extra audio context** choices: `true` is **On**, `false` is **Off**, and `null` is **Automatic (recommended)**. Automatic uses more context for inbound and browser/WebSocket sessions and only the latest turn for outbound phone calls |
| `extraction_fields` | array | Complete structured-data schema extracted from each retained call transcript. Up to 40 fields. Each item requires a unique lowercase `key`, a `type` (`string`, `number`, `boolean`, `enum`, `date`, or `datetime`), and a 1–500 character `description`. `enum` fields require 2–50 unique `options`; `ask` defaults to `true` and `required` defaults to `false`. Writes replace the complete list. |
| `outcome_labels` | array | How calls with a gradeable conversation are labelled in the [call report](/api-reference/calls#call-report) (dashboard: **Reporting** in the agent builder, where **Suggest from prompt** proposes a set fitted to the agent's job). `[]` (default) uses the platform pair `success` / `failure`, judged as before. Otherwise send 2–12 objects: `key` is required, unique, and matches `[a-z][a-z0-9_]{0,39}`; `label` is required, 1–60 characters after whitespace is collapsed; `description` is optional (default `""`, up to 400 characters) and tells the grader when the label applies; `color` is optional, one of `gray`, `green`, `red`, `amber`, `blue`, `purple`, `pink` or `teal` (default `gray`), and only sets the pill colour. Keeping the keys `success` / `failure` but rewriting a label or description makes them your own definitions. Calls are judged against the labels in effect when they started; to bring older calls onto a new list, [relabel past calls](#relabel-past-calls). A quick hang-up has no configured outcome and shows as `No conversation`. Writes replace the complete list. |
| `report_instructions` | string | Rules for the report's prose fields (one-line summary, call reason, caller-experience note, attention note), for example what must never be mentioned. ≤2,000 characters; `""` uses the platform default. |
| `timezone` | string | IANA time zone, up to 64 characters, such as `America/New_York` (dashboard: **Time zone**). The agent states the date and time, offers times and works out "today" in it, and this agent's business hours in reports use it. Set it for every agent. `""` means automatic: each phone call uses the zone of the number it is on when that number's area code places it, else the zone of the agent's numbers, else the [organization's](/guides/organization-settings#reporting), else US Pacific; reports then use the organization's zone. An agent with `""` lists `timezone_not_set` in `warnings`. A call can override it with its own [`timezone`](/api-reference/outbound-calls). |
| `business_hours` | object \| null | Weekly schedule keyed by `mon` through `sun`, each a list of at most four `{start, end}` windows in 24-hour `HH:MM` with the end later than the start, deciding which of this agent's calls count as after hours. `null` inherits the organization's schedule; `{}` counts every call as business hours. |
| `call_summary_enabled` | boolean | Generate a plain-language summary after each call (dashboard: **Generate a call summary** under **Data to collect**). Delivered as `summary` on [`telephony.complete` / `web.complete`](/webhooks/call-complete) and on the [Call object](/api-reference/calls#call-object). Runs in the post-call extraction step, so `extraction_blocks_completion` decides whether the completion event waits for it; when it does not wait, the summary is only available on the Call object. Requires call recording; not generated for calls too short to summarize. Default `false`. |
| `call_setup_webhook_url` | string | URL asked before each inbound phone call this agent answers on one of your numbers, to fill in its `{{variables}}` and the call's context; `""` (default) for none. See [Agent call setup webhook](/webhooks/call-incoming#agent-call-setup-webhook). Staged and published like other settings and kept in the version history. While the agent answers a number with its published settings, a deploy that would leave it using a `{{variable}}` with no default and no webhook is refused with `400` |
| `call_setup_webhook_signing_secret` | string | Write-only: never returned by any read. Signs every call setup webhook request (`X-ThunderPhone-Signature`, the hex HMAC-SHA256 of the raw body). Set one your endpoint checks (16–255 characters); it applies at once, not on deploy, and is never part of the version history. Until you set one, requests are signed with a secret ThunderPhone made, which nobody can read |
| `call_setup_webhook_signing_secret_set` | boolean | Read-only. Whether the agent has a signing secret |
| `call_setup_webhook_variables` | array of string | Read-only. The variables this agent's settings, unpublished changes included, use with no default: what its call setup webhook must fill in. It reads the prompt and attached reusable instructions, step instructions and lines, the acknowledgement prompt, the voicemail message, the consent announcement, and `{{variable}}` transfer numbers |
| `reusable_instruction_ids` | array | UUIDs of the organization's [reusable instructions](/api-reference/reusable-instructions) attached to this agent. Each attached instruction is appended to the end of the system prompt under a `## <name>` heading at call start, in creation order. Writes replace the complete list; responses embed the attached rows as `reusable_instructions` (the `prompt` field itself is unchanged). |
| `extraction_blocks_completion` | string | When extraction may hold customer completion and legacy webhook delivery: `except_transfers` (default; a return to your contact center counts as a transfer), `always`, or `never`. Billing settlement and reservation release never wait. In a blocking mode, completion normally waits at most the 75-second extraction budget. If the worker process is lost, the production finalization drain (every five minutes) releases a past-deadline completion before starting another extraction attempt; a later success emits `call.data_extracted`. |
| `integrations` | array | Linked [Integration](/api-reference/integrations) objects |
| `knowledge_bases` | array | Attached [knowledge bases](/api-reference/knowledge-bases) (full objects) |
| `knowledge_documents` | array | Individually attached [knowledge documents](/api-reference/knowledge-bases#knowledge-document-object) |
| `mcp_servers` | array | Attached [MCP servers](/api-reference/mcp-servers) (full objects) |
| `widget_enabled` | boolean | Whether the agent is reachable via the embeddable web widget |
| `split_testing_enabled` | boolean | Whether calls are split across [A/B variants](/api-reference/split-testing) |
| `warnings` | array | Read-only [configuration warnings](#configuration-warnings) for the draft the builder and test calls use: tool, handoff, time zone and outbound setting problems. Never blocks a save. Default `[]` |
| `tool_collision_warnings` | array | Deprecated: read `warnings`. The same list without `timezone_not_set` and the outbound setting codes. |
| `steps` | object \| null | Splits the agent into [steps](#steps-and-handoffs). `null` (default) is a single-prompt agent. When set, `prompt` holds the shared instructions that apply in every step |
| `handoffs` | array | Other agents in the organization this agent can [hand the call to](#steps-and-handoffs). Default `[]` |
| `words` | array of object | How the agent says specific [words](#words): up to 200 entries, each with a read-only `support`. Default `[]` |
| `created_at`, `updated_at` | timestamp | ISO 8601 UTC |

<Warning>
  Extracted values are a model's interpretation of the conversation. Each
  non-null value includes the quote, speaker role, and turn index it was based
  on, plus a run-level verification flag. Verify the result before decisions
  involving money, identity, or access.
</Warning>

### Draft fields

Every configurable field above has a `draft_*` mirror in the response
(`draft_name`, `draft_prompt`, `draft_voice`, `draft_primary_language`,
`draft_additional_languages`, `draft_native_voice_switching`, `draft_language_voices`, `draft_language_switching`, `draft_audio_tier`, `draft_endpointing`, `draft_intelligence`, `draft_product`, `draft_background_track`,
`draft_thinking_level`, `draft_acknowledgement_prompt_mode`,
`draft_acknowledgement_prompt`, `draft_acknowledgement_feedback_mode`,
`draft_inbound_speak_order`, `draft_outbound_speak_order`,
`draft_voicemail_action`, `draft_voicemail_message`,
`draft_silence_interval_seconds`, `draft_silence_max_checkins`,
`draft_silence_checkins_enabled`, `draft_silence_hangup_seconds`, `draft_silence_final_action`,
`draft_silence_transfer_destination`, `draft_silence_final_message`, `draft_max_call_duration_seconds`, `draft_ring_duration_seconds`, `draft_max_hold_seconds`, `draft_connect_tone_enabled`,
`draft_typing_sounds_enabled`, `draft_typing_sound`, `draft_filler_phrases_enabled`, `draft_pronunciation_dicts`, `draft_tool_start_line`, `draft_play_sound_asset`,
`draft_intro_clip`, `draft_intro_clip_artifact_path`, `draft_intro_clip_sha256`, `draft_intro_ring_count`,
`draft_speak_uninterruptible_enabled`, `draft_send_email_enabled`,
`draft_send_email_recipient`, `draft_calculator_enabled`, `draft_do_not_call_detection_enabled`, `draft_faster_replies_enabled`, `draft_call_setup_webhook_url`, `draft_system_tool_settings`,
`draft_send_sms_enabled`, `draft_sms_from_number`, `draft_sms_allow_other_recipients`,
`draft_sms_allowed_recipients`, `draft_transfer_destinations`,
`draft_warm_transfer_style`, `draft_warm_transfer_briefing`,
`draft_sms_followup_enabled`, `draft_sms_followup_template`,
`draft_consent_announcement_enabled`, `draft_consent_announcement_text`,
`draft_audio_context_mode`, `draft_watchdog_enabled`, `draft_additional_audio_context`,
`draft_extraction_fields`, `draft_extraction_blocks_completion`, `draft_call_summary_enabled`, `draft_outcome_labels`, `draft_report_instructions`, `draft_timezone`, `draft_business_hours`, `draft_reusable_instruction_ids`,
`draft_widget_enabled`, `draft_split_testing_enabled`, `draft_steps`, `draft_handoffs`, `draft_words`), plus draft id
lists for attachments (`draft_integration_ids`,
`draft_knowledge_base_ids`, `draft_knowledge_document_ids`,
`draft_mcp_server_ids`) and read-only markers:

| Field | Type | Description |
|-------|------|-------------|
| `draft_<field>` | same as field \| null | `null` = no pending change for that field; non-null = the value staged for the next deploy |
| `draft_updated_at` | timestamp \| null | When the draft was last edited |
| `has_draft` | boolean | True when any draft field is set |
| `deep_hearing_available` | boolean | Whether this agent's organization can use the `deep_hearing` audio tier, which is not generally available. Read-only |
| `premium_surcharge_lock_cents` | integer \| null | The per-minute premium voice and language surcharge this agent keeps from before the current price, in cents. `null` means the agent pays the current premium rate. Applies only to accounts still on their earlier pricing (until December 1, 2026); on the [new pricing](/guides/pricing) the voice is billed at its provider's list price and this is ignored. Read-only |
| `effective_phone_consent_announcement` | boolean | Whether this agent's phone calls, inbound and outbound, play the consent announcement, as decided when each call starts. It can be `true` while `consent_announcement_enabled` is `false`: the announcement comes back when the consent attestation that turned it off is suspended, revoked or for a statement version that is no longer accepted. `false` while call recording is off. Read-only |
| `billing_overrides` | object | Billing overrides ThunderPhone has set on this agent, each `true` or `false`: `discount` (a per-minute discount applies to the agent's calls as it is deployed, today or from a scheduled later date before the discount ends) and `price_lock` (the agent keeps the per-minute price it had before the current price). A discount's amount is on your call receipts. Neither applies on the [new pricing](/guides/pricing). Read-only |
| `pinned_fields` | object | Settings the dashboard assistant won't change, keyed by field name (`voice`, `prompt`, …). Each entry says who pinned it (`name`, `null` for ThunderPhone staff; `staff`; `is_you`) and when (`at`). Read-only: people pin and unpin settings in the dashboard. It only stops the assistant; your own API writes are not affected. `{}` when nothing is pinned. |

`draft_max_call_duration_seconds` is read-only: `null` means unchanged, and
`0` means a pending removal of the cap. Stage removal by sending
`"max_call_duration_seconds": null`; deployment restores the live value to `null`.

`draft_ring_duration_seconds` follows the same read-only draft convention: `null`
means unchanged and `0` stages clearing the setting. Write `"ring_duration_seconds": null`
to restore platform defaults on deployment. Public writes must be null or 5–120.
`draft_max_hold_seconds` works the same way: write `"max_hold_seconds": null` to restore
the default on deployment.
`draft_silence_interval_seconds` uses `0` the same way: write
`"silence_interval_seconds": null` to stage ThunderPhone's own check-in pacing.

To turn a stepped agent back into a single-prompt agent, send `"steps": null`.
While that change is pending the response shows `"draft_steps": {}`, which means
"no steps on deploy". Send the text from
[`steps/flatten`](#render-steps-as-one-prompt) as `prompt` in the same request
to keep the steps' instructions.

To restore the organization's business hours, send `"business_hours": null`.
When this clears an existing override, the response shows
`"draft_business_hours": {"__inherit__": true}` until deployment. That marker
means "inherit on deploy"; it is not a weekday schedule. Send
`"timezone": ""` too to go back to the automatic time zone.

Production call paths (inbound, outbound, widget) always read the
deployed fields. Mic sessions and simulations read the draft with
fallback to the deployed value.

### Transfer numbers

`transfer_destinations` lists the numbers the agent may transfer calls to.
The prompt refers to each entry by `name`; the model sees the names and never
the numbers. See [Transfer calls](/guides/call-transfers) for prompting and
runtime behavior.

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Required. 1–60 characters after NFKC normalization and trimming, unique on the agent ignoring case. No line breaks, control characters, or invisible characters |
| `number` | string | Required, except on a return. A phone number, exactly one `{{variable}}` with no default, or a `sip:` or `sips:` address. Numbers without a country code are read as US numbers and are stored in E.164. A variable is filled from the call's [variables](/guides/call-variables) when the call starts. A SIP address is stored as written (scheme in lowercase) and works only on calls to a [SIP address](/guides/sip-addresses) and on numbers on a manual SIP connection; see [Transfer to a SIP address](/guides/call-transfers#transfer-to-a-sip-address) |
| `action` | string | Optional. `"return"` hands the call back to the contact center it came from: the agent says goodbye and hangs up, and `headers` go on the SIP `BYE`. A return has no number: leave `number` out, or send `""` from a typed SDK, which requires the field (responses show it as `""`). It works only on calls to a [SIP address](/guides/sip-addresses) and on numbers on a manual SIP connection; see [Return the call to your contact center](/guides/call-transfers#return-the-call-to-your-contact-center). Omitted for every other entry |
| `headers` | object | Optional. Up to 10 SIP headers sent on the `REFER` of a cold transfer, as `{"X-Name": "value"}`. Names start with `X-` (not `X-TP-`) or are `User-to-User`. Values are at most 256 bytes, no line breaks, and can use `{{variables}}`, filled when the call starts (a missing one is left empty). On a return they go on the `BYE`, and only `X-RouteType`, `X-RouteValue`, `X-RouteReason`, `X-CustomMetaData` and `User-to-User` are allowed (matched ignoring case). On a SIP address or a return, `{{handoff_summary}}`, `{{handoff_intent}}` and `{{handoff_id}}` are filled at the transfer instead: see [Pass context to your contact center](/guides/call-transfers#pass-context-to-your-contact-center). Omitted from responses when the entry has none. On an update, an entry sent without a `headers` key keeps the headers saved on the entry with exactly the same number (a return: the return with the same name); send `{}` or `null` to remove them |
| `headers_in_uri` | boolean | Optional, SIP addresses only. `true` sends `headers` inside the transfer address (the `REFER`'s `Refer-To`, `sip:queue@host?User-to-User=…&X-Name=value`, values escaped) instead of as separate headers, for contact centers such as Twilio, Genesys Cloud and Talkdesk that read only the address. The address is kept to 254 characters: `User-to-User` goes first and is cut to fit rather than left out, then the other headers go in alphabetical order, and one that doesn't fit is left out whole. The transfer still happens. Refused with a `?User-to-User=` written into the address. See [Headers inside the transfer address](/guides/call-transfers#headers-inside-the-transfer-address). Omitted unless `true` |
| `uui_encoding` | string | Optional, SIP addresses and returns. `"hex"` sends `User-to-User` hex-encoded with `;encoding=hex`: write the value as plain text and it is encoded at the transfer, cut first so the encoded value fits 256 bytes. Omitted unless set. On an update, an entry sent without `headers_in_uri` or `uui_encoding` keeps the saved value, like `headers`; send `false` or `null` to remove it |
| `platform_ok` | boolean \| null | Read-only; ignored on write. `true` when calls on ThunderPhone numbers can transfer here (a US number that is not premium-rate or another special-service number). `false` means the number works only on transfers your own carrier carries (see [Transfer calls](/guides/call-transfers#which-numbers-a-call-can-reach)); always `false` for a SIP address and a return. `null` for a variable entry, which is checked on each call |

Writes replace the whole list. Sending `null` is rejected; send `[]` to remove
every entry. The same validation runs on create, update, deploy, and every
other write path:

- At most 50 entries.
- Only `name`, `number`, `action`, `headers`, `headers_in_uri` and
  `uui_encoding` are allowed. Other keys return `Unknown field(s): …` on that
  entry. The only `action` is `"return"`, and a return sent with a number is
  refused.
- A number must be a valid phone number without an extension. Numbers in the
  fictional range 555-0100 through 555-0199 are refused.
- If the organization has no number on its own carrier, a number that a
  ThunderPhone number can't reach (outside the US, premium-rate, shared-cost,
  personal-number, and similar types) is refused with a message that says
  why.
- A variable must be one placeholder on its own, such as `{{rep_phone}}`.
  `{{rep_phone|+14155552671}}` and text around the placeholder are refused.
- A SIP address is at most 255 characters and needs a host. Spaces, line
  breaks, quotes, commas, angle brackets, non-ASCII characters and
  `{{variables}}` are refused. The only header it can embed is
  `?User-to-User=`, and its value can't contain `@`.
- Header names and values that break the rules above are refused on the
  entry's `headers` field.
- `headers_in_uri: true` on a phone number, a variable or a return, and
  `uui_encoding` on a phone number or a variable, are refused on that field.
  `false`, `null` and `""` are accepted anywhere and mean not set.

Entry errors come back as a list with one object per submitted entry, in
order, and `{}` for entries that passed:

```json
{
  "transfer_destinations": [
    {},
    {"number": ["(415) 555-0134 is a fictional number: 555-0100 through 555-0199 are reserved for examples. Enter a real number."]},
    {"number": ["+44 20 7123 4567 is outside the US, and calls on ThunderPhone numbers can only transfer to US numbers. To transfer there, connect your own carrier under Phone Numbers."]}
  ]
}
```

Deploying re-checks the deployed list against the organization, so a non-US
entry saved while the organization had a number on its own carrier blocks the
deploy once it has none.

### Words

`words` tells the agent how to say names, places and terms it gets wrong, such
as a building called Quayside or a caller named Siobhan. Put pronunciations
here rather than respelling them in the prompt: the prompt keeps the real
spelling, and the agent's speech swaps in yours.

| Field | Type | Description |
|-------|------|-------------|
| `term` | string | Required. The word or phrase as the agent writes it, 1–80 characters. Matched as a whole word, longest first. Unique per language, ignoring case unless both entries set `case_sensitive` |
| `say_as` | string | How to say it, respelled in plain words of the language's own script, such as `"Kee side"`. Up to 80 characters. Required unless `hear` is `true` |
| `ipa` | string | Optional IPA, such as `ˈkiːsaɪd`, without slashes or brackets. Up to 80 characters. Needs `say_as` |
| `language` | string | Language code, such as `en`. Defaults to the agent's primary language when the entry is saved. The entry applies only when the agent speaks that language |
| `case_sensitive` | boolean | Match only this capitalization, for acronyms that are also words (`US`). Default `false` |
| `speak_with` | string | `auto` (default): the IPA on voices where it is proven to work, otherwise the respelling. `ipa`: the IPA wherever the voice can take it. `say_as`: always the respelling. Preview both and keep what sounds better |
| `hear` | boolean | Also listen for this word in what the caller says, so it is transcribed as written. With a `step`, it is listened for on every turn of that step; without one, on turns where the agent itself says the word. `hear_when` and `hear_always` add turns. Default `false` |
| `step` | string \| null | With `hear`: listen for the word in this [step](#steps-and-handoffs), on every turn of it, so a long list such as insurer names stays out of the rest of the call. `null` (default): no step. Speech uses the entry in every step either way. A step the agent doesn't have is kept and reported in `support`, and the word is then listened for only where `hear_when` matches |
| `hear_always` | boolean | Listen for the word on every turn, such as your company name. Needs `hear`, and no `step` or `hear_when`; at most 3 per agent. Default `false` |
| `hear_when` | array \| null | With `hear`: also listen for the word on turns where the agent's line contains one of these phrases. For an insurer list, `["insurance"]` brings every insurer in when the agent asks "Who's your insurance with?", a question that names none. 1–5 phrases of up to 40 characters, each with at least one letter or digit, matched as whole words, ignoring case. With a `step` too, the word is listened for in either case. `null` (default) or `[]`: none. On an edit, an entry sent without `hear_when` keeps the word's current phrases; send `null` or `[]` to clear them |
| `checked` | object \| null | The last time someone listened to the entry: `{voice, model, result, by, at}`, where `result` is `right`, `wrong` or `unsure`, `by` is `zeus` or `person`, and `at` is an ISO 8601 date or time. Kept for your records; never affects the call |
| `support` | object | Read-only; ignored on write. How well the agent's voice can follow this entry. See below |

On a turn, the words the agent's line says go first, then `hear_always` words, then the words `hear_when` brings in
(in list order), then the rest of the step's words. Each turn carries only the first 15 to 20 of them, so put the
most likely answers first.

On Storm agents, and on turns where a Bolt agent with `audio_tier` `hearing` or `deep_hearing` listens to the caller's audio, every
`hear` word is listed for the whole call, whatever its `step` or `hear_when`.

`support` is computed for the agent's current voice and languages.
`draft_words` uses the draft's voice, languages and steps, but it is only
present when the word list itself is staged: after staging only a new voice,
`words` still shows support for the published voice.

| `level` | Meaning |
|---------|---------|
| `phonetic` | The voice gets the IPA. Voices usually follow it, but not always |
| `respelling` | The voice says `say_as` in place of the word. Close, but stress and vowels may be off |
| `not_supported` | The agent doesn't speak the entry's language, so it never applies |
| `hear_only` | No `say_as`: the entry is only for listening, and the agent says the word as written |

`support` also has `reason` (a sentence on why) and `step_missing` (`true`
when `step` names a step the agent doesn't have). No level means exact:
preview a word before relying on it.

Writes replace the whole list, except that an entry sent without `hear_when` keeps
that word's current phrases. Sending `null` is rejected; send `[]` to remove
every entry. Unknown keys are refused by name, except `support`, which is
dropped so you can send back what you read. Errors are keyed by the entry's
position, then the field:

```json
{"words": {"1": {"ipa": ["Write the IPA without slashes or brackets."]}}}
```

To copy one agent's words to another, read `words` from the first and send
them as `words` to the second.

### Configuration warnings

`warnings` flags settings worth a second look. Every entry has a `code` and a
human-readable `message`; other keys depend on the code. Create, update and
retrieve responses all carry it. The older `tool_collision_warnings` field
carries the same entries except `timezone_not_set` and the two outbound setting codes; it is deprecated.

| `code` | Extra keys | Meaning |
|---|---|---|
| `tool_has_no_inputs` | `tool_name`, `integration_id` | An attached [integration](/api-reference/integrations) declares no inputs in `spec.function.parameters.properties`, so the agent may call it with no arguments. Add the fields your endpoint expects. Ignore this only if the endpoint really takes no data. When the last [analysis](#analyze-a-prompt) of the prompt finds the tool, this is replaced by `tool_arguments_not_declared`, or dropped when the prompt lists no arguments for it. |
| `tool_arguments_not_declared` | `tool_name`, `integration_id`, `arguments` | The prompt tells the agent to send `arguments` to this tool, but its `spec.function.parameters.properties` doesn't declare them. The agent sends only declared inputs reliably. |
| `api_mcp_tool_name_collision` | `tool_name`, `mcp_server_id`, `mcp_server_name` | An integration and an MCP tool share a name; the integration wins and the MCP tool is left out. |
| `handoff_target_missing`, `handoff_graph_truncated`, `handoff_tool_name_collision` | see [`handoffs`](#handoffs) | Handoff problems. |
| `timezone_not_set` | `suggested_timezone`, `source` | The agent has no `timezone`. `suggested_timezone` is the zone its calls use now and `source` says why (`phone_number`, `organization` or `default`). Set `timezone` to the zone its callers are in. |
| `voicemail_hangup_on_outbound` | `field` | `voicemail_action` is `hangup`. Outbound calls that reach voicemail leave nothing. A short message usually works better: people call back numbers that leave one, and callbacks help the number's standing with carriers, so more calls get picked up. |
| `ring_duration_below_outbound_floor` | `field` | `ring_duration_seconds` is under 14. Outbound calls ring for at least 14 seconds anyway, so the setting applies only to transfers. |
| `do_not_call_detection_off_without_attestation` | `field` | `do_not_call_detection_enabled` is `false`, but the organization has no active do-not-call detection attestation, so calls still detect stop-calling requests. |
| `call_setup_webhook_needed` | `field`, `variables` | The agent answers a phone number and its settings use `variables` with no default, but it has no `call_setup_webhook_url` to fill them in. Saving is allowed; deploying a new such variable is refused. Add a [call setup webhook](/webhooks/call-incoming#agent-call-setup-webhook), or give each variable a default like `{{first_name\|there}}`. |

Reading the agent never runs a prompt analysis. `tool_arguments_not_declared`
comes from the last [analysis](#analyze-a-prompt) of the current prompt, by
the dashboard builder or by `POST /v1/agents/{id}/prompt-analysis`. To get it
after changing a prompt over the API, call that endpoint with the agent's
`draft_prompt` (or `prompt` when there is no draft) exactly as the agent
response returns it, then read the agent again. A prompt that differs by so
much as a trailing newline is analyzed separately.

```json
"warnings": [
  {
    "code": "tool_has_no_inputs",
    "tool_name": "create_ticket",
    "integration_id": "6f1c2a9e-1b7d-4c55-9a0e-3f2d8b7c4e10",
    "message": "The tool 'create_ticket' declares no inputs, so the agent may call it without the data your endpoint needs. Add the fields it expects to spec.function.parameters.properties. Ignore this only if the endpoint really needs no data."
  }
]
```

### Product tiers at a glance

| Product | Optimized for | Acknowledgement |
|---------|---------------|-----------------|
| `spark` | Cost — fast and efficient for simple tasks | — |
| `bolt` | Speed — the lowest-latency tier, balanced for most use cases | — |
| `storm-base` | Intelligence — complex prompts and reasoning | — |
| `storm-base-with-ack` | Intelligence | Spoken filler (or tick) while thinking |
| `storm-extra` | Deepest reasoning | — |
| `storm-extra-with-ack` | Deepest reasoning | Spoken filler (or tick) while thinking |

## Steps and handoffs

Split an agent into **steps** when its calls move through phases, such as
greeting, identity checks and booking. Each step has its own instructions,
tools, an optional word-for-word line and values to collect. The agent moves
on by calling the built-in `go_to_step` tool, or when a code-checked condition
on the collected values holds. When `steps` is set, `prompt` holds the shared
instructions that apply in every step.

A **handoff** passes the call to another agent in the same organization. That
agent brings its own prompt, steps, tools and voice, and the transcript
carries over. Every other call setting (product, languages, speaking order,
voicemail, consent) comes from the agent the call started on.

Agents without steps or handoffs (`"steps": null`, `"handoffs": []`) work
exactly as before.

### `steps`

```json
{
  "start_step": "greet",
  "steps": [
    {
      "id": "greet",
      "name": "Greeting",
      "instructions": "Greet the caller and ask how you can help.",
      "say": "Thanks for calling Acme Dental, this is Ava.",
      "transitions": [
        {"to": "verify", "when": "The caller wants to book, move or cancel an appointment"}
      ]
    },
    {
      "id": "verify",
      "name": "Verify identity",
      "instructions": "Ask for the caller's full name and date of birth.",
      "tools": ["lookup_patient"],
      "collect": [
        {"name": "full_name", "type": "string", "description": "Caller's full name"},
        {"name": "dob", "type": "date", "description": "Date of birth"}
      ],
      "transitions": [
        {"to": "minor", "condition": {"value": "age", "op": "lt", "target": 18}},
        {"to": "book", "when": "Identity is confirmed"}
      ]
    },
    {"id": "minor", "name": "Minor", "instructions": "Ask for a parent or guardian."},
    {"id": "book", "name": "Book", "instructions": "Offer open slots and book one."},
    {
      "id": "billing",
      "name": "Billing questions",
      "instructions": "Answer questions about bills and payments.",
      "global_when": "The caller asks about a bill or payment",
      "transitions": [{"to": "__previous__", "always": true}]
    }
  ]
}
```

`start_step` names the step the call begins in. Each step takes:

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Required. Matches `[a-z][a-z0-9_]{0,39}`, unique within the agent |
| `name` | string | Required display name, 1–80 characters |
| `instructions` | string | Required, up to 20,000 characters. Supports `{{variables}}` like `prompt` |
| `say` | string \| null | Line spoken word for word when the step is entered, up to 1,000 characters. Supports `{{variables}}` |
| `tools` | array \| null | `null` (default) offers every agent tool. A list offers only the named agent tools in this step. Built-in tools such as ending or transferring the call follow the agent's settings in every step |
| `collect` | array | Up to 20 values to gather: `name` (same pattern as `id`, unique in the step), `type` (`string`, `number`, `boolean` or `date` as `YYYY-MM-DD`), optional `description` (up to 500 characters) and `required` (default `true`) |
| `on_enter_tool` | string \| null | An agent tool called automatically when the step is entered. Its result is stored as the value `<tool>_result`: `status` is the tool's HTTP status code and `response` is the response body |
| `transitions` | array | Ordered moves out of the step, up to 40. Each has `to` and exactly one trigger: `when` (the model decides, up to 1,000 characters), `condition` (code decides) or `"always": true`. `to` is a step `id`, or `"__previous__"` to return to the step that was active before a global step. A step with no transitions is the last one |
| `global_when` | string \| null | Makes the step reachable from any step when this holds (the model decides) |
| `voice` | string \| null | Voice for this step. Ignored when the call uses a custom `voice_config` |

A `condition` is `{"value", "op", "target"}`. `value` names a collected value
or a dotted path into a tool result, such as `lookup_patient_result.response.found`
(a field of the response body) or `lookup_patient_result.status` (its HTTP status code).
`op` is one of `eq`, `ne`, `lt`, `lte`, `gt`, `gte`, `in`, `not_in`, `exists`
or `missing`:

- `eq` and `ne` take a string, number or boolean; `in` and `not_in` take a
  list of 1–50 of them. Strings compare case-insensitively after trimming.
- `lt`, `lte`, `gt` and `gte` take a number or a `YYYY-MM-DD` date.
- `exists` and `missing` take no `target`.

A value that was never collected makes every op false except `missing`.
Conditions are checked in order when the agent moves on, and the first match
wins.

Limits: 100 steps and 200 KB of JSON per agent. Step `tools` and
`on_enter_tool` must name tools the agent has when you save. On an agent with
steps or handoffs, no tool may be named `go_to_step` or `hand_off`.

### `handoffs`

```json
[{"agent_id": 13, "when": "The caller asks about billing or a refund"}]
```

Up to 8 entries. `agent_id` must be another agent in the same organization;
`when` (1–1,000 characters) tells the agent when to hand off. A call includes
at most 8 agents, counted breadth-first from the agent it started on. The
agent's `warnings` lists `handoff_graph_truncated` when
handoffs further out are left out, `handoff_target_missing` when a handoff
names an agent that no longer exists (calls skip it), and
`handoff_tool_name_collision` when a handed-to agent has a different tool with
the same name as an earlier agent's (that tool is left out of the call).

### Validation errors

Invalid steps or handoffs return `400` with one key per field path:

```json
{
  "steps.steps[1].transitions[0].to": ["Unknown step id \"booking\"."],
  "handoffs[0].agent_id": ["No agent with this id in the organization."]
}
```

### Example

Stage steps and a handoff on the draft, then deploy:

<CodeGroup>
```bash cURL
curl -X PATCH https://api.thunderphone.com/v1/agents/12 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "You are Ava, the front desk for Acme Dental. Be brief and friendly.",
    "steps": {
      "start_step": "greet",
      "steps": [
        {
          "id": "greet",
          "name": "Greeting",
          "instructions": "Ask how you can help.",
          "transitions": [{"to": "book", "when": "The caller wants an appointment"}]
        },
        {"id": "book", "name": "Book", "instructions": "Offer open slots and book one."}
      ]
    },
    "handoffs": [{"agent_id": 13, "when": "The caller asks about billing"}]
  }'

curl -X POST https://api.thunderphone.com/v1/agents/12/deploy \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

---

## List agents

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/agents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

```python Python
agents = requests.get(
    "https://api.thunderphone.com/v1/agents",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
).json()
```

```javascript Node.js
const agents = await fetch("https://api.thunderphone.com/v1/agents", {
  headers: { Authorization: `Bearer ${process.env.THUNDERPHONE_API_KEY}` },
}).then((r) => r.json());
```
</CodeGroup>

Returns an array of [Agent objects](#agent-object), sorted by `created_at` descending.

---

## Create an agent

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/agents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent",
    "prompt": "You are a helpful support agent for Acme Ops…",
    "voice": "john",
    "product": "spark",
    "widget_enabled": true
  }'
```

```python Python
agent = requests.post(
    "https://api.thunderphone.com/v1/agents",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={
        "name": "Customer Support Agent",
        "prompt": "You are a helpful support agent for Acme Ops…",
        "voice": "john",
        "product": "spark",
        "widget_enabled": True,
    },
).json()
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | yes | 1–255 chars |
| `prompt` | string | yes | System prompt |
| `voice` | string | yes | Voice name from [`/v1/voices`](#voices) (e.g. `john`). Entitled organizations can also pass [`custom:<public_id>`](/api-reference/custom-voices#use-a-custom-voice) for a ready custom voice, an agent that does not process PHI can pass an [ElevenLabs voice](#elevenlabs-voices) (`elevenlabs:<voice_id>`), and any voice from [`/v1/voices/library`](#every-voice) works by its `name`; anything else is rejected with `"Unsupported voice option."` |
| `primary_language` | string | no | Defaults to `en` |
| `additional_languages` | array of string | no | ISO 639 (`es`) or BCP-47 (`es-ES`) codes |
| `native_voice_switching` | boolean | no | Use a native catalog voice, matched by gender, after switching to an additional language. Default `false` |
| `language_voices` | object | no | Language code to voice, for calls that start in that language. See [Deployed fields](#deployed-fields) |
| `language_switching` | string | no | `ask_first` (default) or `follow_caller`. See [Deployed fields](#deployed-fields) |
| `endpointing` | string | no | `faster`, `fast`, `normal` (default) or `patient`. Bolt v2 only. See [Deployed fields](#deployed-fields) |
| `intelligence` | string | no | `lite` or `standard` (default). Bolt v2 only. See [Deployed fields](#deployed-fields) |
| `faster_replies_enabled` | boolean | no | Default `true`. Bolt v2 only: on replies where it helps, sends two requests and uses whichever answers first, which uses twice the model tokens on those replies. |
| `product` | string | no | Defaults to `spark` |
| `audio_tier` | string | no | Bolt only. `standard` (default), `lean`, `hearing` or `deep_hearing` (not generally available). See [Deployed fields](#deployed-fields) |
| `thinking_level` | string | no | Ignored for Storm tiers (derived from `product`) |
| `background_track` | string | no | Track name or `"NONE"` |
| `extraction_fields` | array | no | Complete replacement list of structured fields to extract after each retained call. See [Deployed fields](#deployed-fields) for the item schema |
| `extraction_blocks_completion` | string | no | `except_transfers` (default), `always`, or `never`; controls customer completion delivery only |
| `outcome_labels` | array | no | Complete replacement list of call-report outcome labels; `[]` restores Success / Failure. See [Deployed fields](#deployed-fields) |
| `report_instructions` | string | no | Instructions for the call report's prose fields |
| `timezone` | string | no | The agent's time zone; see [Deployed fields](#deployed-fields). Optional, but an agent without one lists `timezone_not_set` in `warnings` |
| `business_hours` | object \| null | no | This agent's reporting hours; see [Deployed fields](#deployed-fields) |
| `acknowledgement_prompt_mode` | string | no | `auto` or `manual`. Only meaningful for Storm-with-ack products |
| `acknowledgement_prompt` | string | no | Required if `acknowledgement_prompt_mode="manual"` |
| `acknowledgement_feedback_mode` | string | no | `acknowledgement` (default), `tick` or `none` (silence) |
| `inbound_speak_order` | string | no | Defaults to `agent_first` |
| `outbound_speak_order` | string | no | Defaults to `caller_first` |
| `voicemail_action` | string | no | `prompt` (default), `hangup`, or `message` |
| `voicemail_message` | string | no | ≤ 2000 chars |
| `silence_interval_seconds` | integer or null | no | 10–120, default 15; `null` for ThunderPhone's context-aware pacing (6, 10, 15 s before the caller speaks; 10, 15, 15 s of ordinary quiet; at least 60 s after a request to wait) |
| `silence_max_checkins` | integer | no | 1–10, default 3 |
| `silence_checkins_enabled` | boolean | no | Default `true` |
| `silence_hangup_seconds` | integer | no | 60–3600, default 600; used when check-ins are disabled |
| `silence_final_action` | string | no | `hang_up` (default) or `transfer` |
| `silence_transfer_destination` | string | no | A `transfer_destinations` name; required with `transfer`. Create and deploy refuse a name the agent's transfer numbers don't include |
| `silence_final_message` | string | no | ≤ 300 chars; `""` uses the default line |
| `max_call_duration_seconds` | integer or null | no | 60–21600. Omit it to use the organization's new-agent default (3600, one hour); send `null` for no per-agent limit. Every call still ends after 6 hours |
| `ring_duration_seconds` | integer or null | no | Ringing time for outbound and transferred calls, in seconds. 5–120; null uses platform defaults (60s outbound, 45s warm transfer, provider default for cold transfer). Outbound calls ring for at least 14 seconds; a shorter value applies to transfers only. Does not affect inbound ringing. |
| `max_hold_seconds` | integer or null | no | Outbound hold timeout in seconds. 10–900; `null` uses the default (900) |
| `connect_tone_enabled` | boolean | no | Default `false` |
| `typing_sounds_enabled` | boolean | no | Play a soft keyboard sound while a custom tool runs. Default `false` |
| `typing_sound` | string | no | `keys_and_mouse`, `mechanical`, `desktop`, `laptop`, `office`, or `quiet_room`. Default `keys_and_mouse` |
| `filler_phrases_enabled` | boolean | no | Long-wait updates on slow tools and replies. `false` stays quiet after the tool-start line. Default `true` |
| `pronunciation_dicts` | boolean | no | ThunderPhone's pronunciation dictionary for Cartesia speech (ThunderPhone's own Cartesia voices only). Default `false` |
| `tool_start_line` | string | no | `always`, `only_if_slow`, or `never`. Default `always` |
| `play_sound_asset` | string | no | `""` (none), `chime`, `ding`, or `beep` |
| `speak_uninterruptible_enabled` | boolean | no | Legacy compatibility field with no current runtime effect. Default `false` |
| `send_email_enabled` | boolean | no | Offer the built-in email tool when a recipient is configured. Default `false` |
| `send_email_recipient` | string | no | Fixed email recipient chosen by the agent owner; the model cannot change it |
| `calculator_enabled` | boolean | no | Offer the built-in `calculate` tool for exact arithmetic. Default `false` |
| `do_not_call_detection_enabled` | boolean | no | Add the number to your opt-out list when the person on an outbound call asks not to be called again. Default `true`. `false` returns `400` (unless the agent already has it off) until your organization has recorded the [do-not-call detection attestation](/api-reference/opt-outs#turning-detection-off) |
| `send_sms_enabled` | boolean | no | Offer `send_sms` when an eligible customer-connected sender is available. Default `false` |
| `sms_from_number` | string | no | E.164 fallback sender owned by the organization and confirmed SMS-capable by Twilio or Telnyx |
| `sms_allowed_recipients` | array of object | no | Up to 10 `{number, label}` contacts. Numbers are unique E.164 values. Labels are NFKC-normalized, unique case-insensitively, 1–60 visible characters, cannot look like phone numbers, and are caller-visible public metadata. Only labels are shown to the model. A configured contact enables real sends in widget, realtime, mic, and simulation sessions without broad recipient permission |
| `sms_allow_other_recipients` | boolean | no | Permit any valid E.164 recipient beyond the current telephone party and configured contacts. Default `false`. When enabled, the agent can text any number a caller dictates |
| `transfer_destinations` | array of object | no | Up to 50 `{name, number}` [transfer numbers](#transfer-numbers) (or `{name, action: "return"}`), each with optional `headers`. Default `[]`: the agent can't transfer calls |
| `words` | array of object | no | Up to 200 [words](#words) the agent says your way. An entry without `language` takes the agent's `primary_language`. Default `[]` |
| `sms_followup_enabled` | boolean | no | Send one eligible post-call SMS. Default `false` |
| `sms_followup_template` | string | no | Plain-text post-call template, up to 1600 characters |
| `consent_announcement_enabled` | boolean | no | Defaults to `true`. New agents must be created with it enabled; disabling later requires the [attestation workflow](#consent-attestations) where applicable |
| `consent_announcement_text` | string | no | Non-blank call-start announcement text |
| `audio_context_mode` | string | no | `full` (default) or `reduced` |
| `watchdog_enabled` | boolean | no | Default `false` |
| `additional_audio_context` | boolean \| null | no | Override whether the last few caller-audio turns are included. `null` keeps the direction-based default |
| `widget_enabled` | boolean | no | Defaults to `true` |
| `split_testing_enabled` | boolean | no | Default `false` |
| `integration_ids` | array of UUID | no | Link reusable [integrations](/api-reference/integrations) by id. Tool names must be unique on the agent: two integrations with the same `spec.function.name` (or one that matches an attached MCP server's tool) return `400` naming the tool. Integrations of other agents may share a name |
| `knowledge_base_ids` | array of UUID | no | Attach [knowledge bases](/api-reference/knowledge-bases) |
| `knowledge_document_ids` | array of UUID | no | Attach individual knowledge documents |
| `mcp_server_ids` | array of UUID | no | Attach [MCP servers](/api-reference/mcp-servers) |
| `reusable_instruction_ids` | array of UUID | no | Attach [reusable instructions](/api-reference/reusable-instructions) |
| `call_summary_enabled` | boolean | no | Generate a post-call summary. Default `false` |
| `call_setup_webhook_url` | string | no | [Call setup webhook](/webhooks/call-incoming#agent-call-setup-webhook) URL. Default `""` (none) |
| `call_setup_webhook_signing_secret` | string | no | Its signing secret (write-only). Set one to verify requests |

Returns `201 Created` with the new [Agent object](#agent-object). A
create deploys immediately (there is no draft yet) and records revision
1 in the [version history](#version-history).

<Note>
  Inline `tools` exist on the underlying model but are **not writable
  through this API** — tool configuration is managed via
  [Integrations](/api-reference/integrations),
  [App connections](/api-reference/provider-connections), and
  [MCP servers](/api-reference/mcp-servers).
</Note>

---

## Retrieve an agent

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/agents/12 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

```python Python
agent = requests.get(
    f"https://api.thunderphone.com/v1/agents/{agent_id}",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
).json()
```
</CodeGroup>

Returns `200 OK` with an [Agent object](#agent-object), or `404` if not found.

---

## Update an agent (writes the draft)

`PATCH` and `PUT` do **not** modify the deployed configuration.
Every field you send is staged into the corresponding `draft_*` column;
production calls keep using the deployed values until you
[deploy](#deploy-the-draft). Sending a value identical to the deployed
value *clears* that field's draft (so manually reverting an edit
removes the pending change).

<CodeGroup>
```bash cURL
curl -X PATCH https://api.thunderphone.com/v1/agents/12 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "You are a refined support agent…"}'
```

```python Python
agent = requests.patch(
    f"https://api.thunderphone.com/v1/agents/{agent_id}",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={"prompt": "You are a refined support agent…"},
).json()
```
</CodeGroup>

Accepts the same fields as [create](#create-an-agent), including the
`integration_ids` / `knowledge_base_ids` / `knowledge_document_ids` /
`mcp_server_ids` / `reusable_instruction_ids` lists (staged as draft
attachment lists). Returns
`200 OK` with the [Agent object](#agent-object) — inspect the
`draft_*` fields and `has_draft` to see what is pending.

### Optimistic concurrency

To safely make edits from a UI, include `if_updated_at` (or
`updated_at`) with the last `updated_at` you observed:

```json
{
  "prompt": "Newer prompt",
  "if_updated_at": "2026-04-20T18:24:10.113Z"
}
```

If the server-side `updated_at` differs, the API returns `409 Conflict`
with `{"detail": "Agent was modified by another user. Please refresh and try again."}`
so you can refresh and retry.

---

## Deploy the draft

Promotes every pending `draft_*` value to the deployed configuration,
clears the draft, and records a new revision in the
[version history](#version-history).

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/agents/12/deploy \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

```python Python
agent = requests.post(
    f"https://api.thunderphone.com/v1/agents/{agent_id}/deploy",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
).json()
```
</CodeGroup>

Returns `200 OK` with the updated [Agent object](#agent-object)
(`has_draft` is now `false`). Deploying with no pending draft is a
no-op that still returns `200` with the current agent.

| Body field | Type | Description |
|---|---|---|
| `updated_at` | string | Optional. The agent's `updated_at` from your last read; the deploy is refused with `409` if the agent changed since |
| `confirm_price_change` | boolean | Optional, default `false`. Send `true` only after the person paying for the agent agreed to the higher per-minute price this deploy brings |

### Deploys that raise the price

A deploy that raises the agent's per-minute price needs an explicit
confirmation. It applies when the draft changes a pricing setting
(`intelligence`, `audio_tier`, `endpointing`, `voice`,
`acknowledgement_feedback_mode` or the setup) to one that costs more, when
a longer prompt alone raises it by more than a quarter of a cent a minute,
when the change ends the price the agent kept from before the current price
list, or when the deployed setup leaves the one the agent's discount covers
(`ends_discount`; on usage-based billing its calls then bill their full
usage). Without `confirm_price_change: true`, such a deploy deploys nothing
and returns `409`:

```json
{
  "code": "price_change_needs_confirmation",
  "detail": "Deploying changes reply speed to Fast. Front Desk goes from 8.00¢ to 10.94¢ a minute. Its price lock ends for good: switching back later does not bring the kept price back. Nothing was deployed. To deploy at the new price, send the request again with confirm_price_change: true.",
  "next_step": "Tell the user the price per minute before and after, and only after they agree send the deploy again with confirm_price_change: true.",
  "price_change": {
    "raises_price": true,
    "ends_price_lock": true,
    "ends_discount": false,
    "current_per_minute_cents": 8.0,
    "new_per_minute_cents": 10.94,
    "changes": [
      {"field": "endpointing", "name": "reply speed", "from": "normal", "to": "fast", "from_label": "Normal", "to_label": "Fast"}
    ],
    "message": "Deploying changes reply speed to Fast. Front Desk goes from 8.00¢ to 10.94¢ a minute. Its price lock ends for good: switching back later does not bring the kept price back."
  }
}
```

Show the person both prices, and only after they agree send the deploy
again with the flag:

```bash
curl -X POST https://api.thunderphone.com/v1/agents/12/deploy \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"confirm_price_change": true}'
```

Deploys that do not raise the price are unchanged and need no flag.
These include small prompt edits and other non-pricing changes, and a
cheaper setting. A [version restore](#version-history) with `deploy` takes
the same flag. The MCP `deploy_agent` tool does not take it yet: deploy a
change that raises the price through this endpoint or the dashboard.

## Discard the draft

Clears every pending draft field, reverting the editor state to the
deployed configuration.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/agents/12/discard-draft \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Returns `200 OK` with the [Agent object](#agent-object).

## Relabel past calls

A call is judged against the [outcome labels](#deployed-fields) the agent had when the call started, so a
new label list reaches only calls placed after it is deployed. This route puts the agent's older calls on
its current deployed labels: for each call it re-picks the outcome label, and a one-sentence reason, from
the [call report](/api-reference/calls#call-report) written when the call ended and the call's transcript.
Nothing else changes: the grade, the report's summary and needs-attention fields, and the call itself stay
as they are, and no webhooks are sent. A later [regrade](/api-reference/calls#run-grading) of a relabeled
call judges it against the same labels.

It covers the agent's calls with a judged outcome (not `No conversation`) whose labels differ from the
current list, started before the dry run, newest first, up to 5,000 calls a run. A call whose grade is still
being worked out is left for a later run, and so is every call once the agent's labels change while the run
is going. A run already going for the agent is returned instead of a second one, and while one agent's run
is going, starting another agent's in the same organization is refused (`409`, `organization_busy`). Any
member of the organization may start one.

A run starts in two steps. First, a dry run counts the calls, prices the run and returns a `quote_id`, good
for 30 minutes. Then you start the run with that `quote_id`. The run covers only the calls the quote
counted that still need relabeling, never others. A quote starts one run only. It's refused (`409`) once
used or expired, or after the agent's labels change. Then run a new dry run. A run stops, and ends `failed`,
once what it has spent passes 125% of `estimated_cost_usd`.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `dry_run` | boolean | no | `true` counts and prices the run and returns a quote, without changing anything |
| `quote_id` | string | to start a run | The dry run's `quote_id` |
| `since` | string | no | Dry run only: only calls from this ISO 8601 date or time on |
| `until` | string | no | Dry run only: only calls before this ISO 8601 date or time |
| `include_transcript` | boolean | no | Dry run only: `false` judges each call from its report alone. Default `true` |

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/agents/12/relabel-calls \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true}'
```
</CodeGroup>

A dry run returns `200 OK`:

```json
{
  "dry_run": true,
  "calls": 412,
  "total_calls": 412,
  "capped": false,
  "max_calls": 5000,
  "model_calls": 412,
  "estimated_cost_usd": 3.1,
  "max_cost_usd": 18.4,
  "quote_id": "5d0c7b0e-0d43-4f3e-9a51-0c6b1a7f2e90",
  "expires_at": "2026-10-30T18:32:11Z",
  "job": null
}
```

`calls` is how many calls the run covers (`total_calls` need it in all; `capped` when that is more than
`max_calls`), and `model_calls` how many of them need a model request (a change of colours only, or a
return to the default Success / Failure pair, which follows each call's grade, needs none).
`max_cost_usd` is the most the run can cost, with every request retried and at its longest answer.
`quote_id` is `null` when no call needs relabeling. Then start it:

```bash
curl -X POST https://api.thunderphone.com/v1/agents/12/relabel-calls \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"quote_id": "5d0c7b0e-0d43-4f3e-9a51-0c6b1a7f2e90"}'
```

The run is queued and the response is `202 Accepted` (`200 OK` with the run already going):

```json
{
  "created": true,
  "job": {
    "id": "9b6f0c2e-4f1a-4c55-9d43-2b7f1d0c6a11",
    "status": "queued",
    "progress": {},
    "created_at": "2026-10-30T18:02:11Z",
    "updated_at": "2026-10-30T18:02:11Z",
    "error": null
  }
}
```

`GET` returns the agent's current `labels` and its latest run (`job`, or `null`). A run's `status` is
`queued`, `running`, `succeeded` or `failed`. `progress` counts `total`, `done`, `relabeled`, `unchanged`
(the label stayed the same), `skipped_grading` (a grade was in progress), `failed` and `not_started` calls.
`stopped` is `labels_changed` when the labels changed mid-run. A run whose calls failed is retried by
itself and picks up only the calls left.

## Intro clip

`GET /v1/agents/{agent_id}/intro-clip` ·
`POST /v1/agents/{agent_id}/intro-clip` ·
`DELETE /v1/agents/{agent_id}/intro-clip`

Manage the agent's custom intro clip (`intro_clip: "custom"`). Like every
agent edit, an upload or removal changes the **draft**; it reaches live calls
when you [deploy](#deploy-the-draft).

**Upload** with a multipart `audio` field. The file must be a PCM WAV,
**48,000 Hz, mono, 16-bit**, 0.5–15 seconds long and at most 2 MB; anything
else is refused with `400` and an `audio` error. (The dashboard converts any
file or browser recording to this format for you.) The upload sets
`draft_intro_clip` to `custom` along with `draft_intro_clip_artifact_path` and
`draft_intro_clip_sha256`.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/agents/12/intro-clip \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -F "audio=@intro.wav;type=audio/wav"
```
</CodeGroup>

Returns `201 Created`:

```json
{
  "artifact_path": "agents/intro-clips/7/12/3f5a…c9.wav",
  "sha256": "3f5a…c9",
  "duration_seconds": 4.2,
  "updated_at": "2026-10-13T18:02:11.482913Z"
}
```

`updated_at` is the agent's new value, for
[optimistic concurrency](#optimistic-concurrency).

**Download** returns the clip the draft would play (the draft's clip if one is
staged, otherwise the deployed one) as `audio/wav`, or `404` when there is
none.

**Remove** stages removal of the custom clip; if `intro_clip` was `custom`,
the draft also switches it to `none`. Returns `200 OK` with the draft's
resulting `intro_clip` and `updated_at`:

```json
{ "intro_clip": "none", "updated_at": "2026-10-13T18:05:40.120004Z" }
```

---

## Consent attestations

`GET /v1/agents/{agent_id}/consent-attestations` ·
`POST /v1/agents/{agent_id}/consent-attestations`

Every agent plays a call-start consent announcement (recording and AI
disclosure) by default. Disabling it on a non-grandfathered agent requires
an **active attestation**: an admin's recorded affirmation that your
organization will provide any legally required notice and obtain any
legally required consent for its calls while the announcement stays off
(see the [call recording consent laws](/guides/recording-consent-laws)
guide for what that involves). Without one, staging or deploying
`consent_announcement_enabled: false` returns `400`.

Attestations are single-use per disable cycle: re-enabling the
announcement retires the active attestation (recorded with
`status_reason: "superseded-by-reenable"`), so the next disable needs a
fresh affirmation. ThunderPhone may also suspend or revoke attestations,
which restores the announcement at runtime. New attestations are recorded
only under the **current** `attestation_text_version`, but an active
attestation recorded under an earlier accepted version stays valid — a
statement-copy revision never re-prompts an organization that already
attested.

`GET` lists the agent's attestations (newest first) and returns the
current `attestation_text_version` **and the server-owned canonical
statement package** — `statement_text`, its `statement_sha256`, and the
`statement_locale` it resolved for your `?locale=` (English until a locale
is registered). Display `statement_text` verbatim to the admin, then
`POST` with `affirmed: true`, the exact version, your `locale`, and
**assent to the package**: echo `statement_sha256`, or send the displayed
text as `rendered_text` (it must hash to the canonical value). The server
stores its canonical hash — blank or mismatched statement evidence is
rejected.

**Step 1 — fetch the canonical statement:**

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/agents/12/consent-attestations?locale=en \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

```json Response (excerpt)
{
  "attestation_text_version": "consent-disable-v4-2026-08-03",
  "statement_locale": "en",
  "statement_text": "Turn off the call-recording announcement?\n…",
  "statement_sha256": "7a284954b61b6610d1f9fb43ec05e82e6aec4362956fa5409deb3375cfc99035",
  "results": []
}
```

**Step 2 — display the statement, collect the affirmation, and record it:**

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/agents/12/consent-attestations \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"affirmed": true, "attestation_text_version": "consent-disable-v4-2026-08-03", "statement_sha256": "7a284954b61b6610d1f9fb43ec05e82e6aec4362956fa5409deb3375cfc99035", "locale": "en"}'
```
</CodeGroup>

```json Response
{
  "id": 91,
  "organization_id": 7,
  "agent_id": 12,
  "user_id": 3,
  "attestation_text_version": "consent-disable-v4-2026-08-03",
  "status": "active",
  "attested_at": "2026-08-03T23:02:11.480Z",
  "status_updated_at": null,
  "affirmed": true,
  "attestation_text_sha256": "7a284954b61b6610d1f9fb43ec05e82e6aec4362956fa5409deb3375cfc99035",
  "locale": "en",
  "user_role": "admin",
  "status_reason": ""
}
```

| Status | Condition |
|--------|-----------|
| `201` | Attestation recorded (POST) |
| `400` | `affirmed` was not `true`, `attestation_text_version` does not match the current version, `locale` is blank, or the statement evidence (`statement_sha256`/`rendered_text`) is blank or does not match the canonical package |
| `403` | Caller is not an org admin |

## PHI designation attestation

`GET /v1/phi-designation-attestation?agent_id={agent_id}` ·
`POST /v1/phi-designation-attestation`

Only organizations whose BAA includes the PHI designation clause
(`baa_status: "executed_with_designation"`) use this endpoint. In such an
organization every agent processes PHI by default. Before an agent's
`phi_processing_override` can be set to `no_phi`, an organization admin
must record an attestation for that agent; without one, saving or deploying
the override returns `400`.

`GET` returns the current `text_version`, the canonical English statement
(`statement_en`) and its `statement_sha256`, the organization's
`baa_status` and `phi_processing`, and `designation_available`. With
`agent_id`, it also reports whether that agent has an active attestation
(`attested`, `attestation`).

`POST` takes `agent_id`, `accepted: true`, the `text_version` and the
`statement_sha256` from `GET`, and an optional display `locale` (default
`en`; the English statement governs). It returns `201` with the
attestation, or `200` with the existing one if the agent already has an
active attestation.

<Note>
  The attestation must be recorded by an organization admin as a user, not
  with an organization API key: `POST` with an `sk_live_` key returns `403`.
  `GET` works with a key.
</Note>

<CodeGroup>
```bash cURL
curl "https://api.thunderphone.com/v1/phi-designation-attestation?agent_id=12" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

```json Response (excerpt)
{
  "text_version": "phi-designation-no-phi-v1-2026-09-24",
  "statement_en": "I am authorized to designate this agent as not processing protected health information (PHI). …",
  "statement_sha256": "7776b7852f41e777eac228bfd5abdc4df5c958752b39ea032c86f14b02a892da",
  "baa_status": "executed_with_designation",
  "phi_processing": "phi",
  "designation_available": true,
  "attested": false,
  "attestation": null
}
```

| Status | Condition |
|--------|-----------|
| `201` | Attestation recorded (POST) |
| `200` | The agent already has an active attestation (POST) |
| `400` | Unknown `agent_id`, `accepted` was not `true`, `locale` is blank, `text_version` is not accepted, or `statement_sha256` does not match the canonical statement |
| `403` | API key, or caller is not an org admin (POST) |
| `409` | The organization's BAA has no designation clause, so there is nothing to attest |

---

## Delete an agent

<CodeGroup>
```bash cURL
curl -X DELETE https://api.thunderphone.com/v1/agents/12 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

```python Python
requests.delete(
    f"https://api.thunderphone.com/v1/agents/{agent_id}",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
)
```
</CodeGroup>

Returns `204 No Content`. Phone numbers that reference the deleted agent
have their inbound/outbound assignment cleared.

An agent that other agents [hand off to](#steps-and-handoffs), in their
deployed or draft `handoffs`, cannot be deleted. The request returns
`409 Conflict` with `"code": "agent_is_handoff_target"` and the referencing
agents in `agents` (`[{"id", "name"}]`). Remove those handoffs first.

---

## Duplicate an agent

Creates a new agent in the same org with everything configured for the
source agent: all settings, both deployed and pending drafts, the same
attached integrations, knowledge bases/documents, MCP servers and reusable
instructions, and new copies of its agent-scoped webhook endpoints (same URL,
events and signing secret), calendar/CRM connections, split-testing variants,
test scenarios and suites (with schedules), and client portal listings. The
name defaults to `<name> (Copy)` and can be overridden. If the source has a
pending draft, the copy has one too (`has_draft: true`), and deploying it
ships those edits.

A few settings are reset rather than copied:

- A consent announcement turned off by attestation stays off, and the copy
  gets its own attestation record carrying the original's. A copy of an agent
  exempted without an attestation starts with the announcement on.
- A live-processing disclosure set to off goes back to the org default.
- A PHI override the org doesn't allow goes back to the org default.

Phone numbers, SIP addresses, widget publishable keys, campaigns and call
history stay with the source agent. Move a number to the copy separately.
Steps and handoffs are copied as they are, so the copy hands off to the same
agents.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/agents/12/duplicate \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Customer Support Agent (clone)"}'
```

```python Python
clone = requests.post(
    f"https://api.thunderphone.com/v1/agents/{agent_id}/duplicate",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={"name": "Customer Support Agent (clone)"},
).json()
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | no | Defaults to `"<original name> (Copy)"` |

Returns `201 Created` with the new [Agent object](#agent-object).

---

## Transfer an agent to another org

Copy or move an agent to a different organization. `admin+` role is required
on **both** orgs.

An `sk_live_` API key is limited to its own organization: with a key,
`target_org_id` must be the key's organization, and any other target
returns `403`. Copy or move between organizations from a signed-in session
(`Authorization: Token <session-token>` plus `X-ThunderPhone-Org` for the
source org), as below.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/agents/12/transfer \
  -H "Authorization: Token YOUR_SESSION_TOKEN" \
  -H "X-ThunderPhone-Org: 42" \
  -H "Content-Type: application/json" \
  -d '{
    "target_org_id": 77,
    "mode": "copy"
  }'
```

```python Python
result = requests.post(
    f"https://api.thunderphone.com/v1/agents/{agent_id}/transfer",
    headers={"Authorization": "Token YOUR_SESSION_TOKEN", "X-ThunderPhone-Org": "42"},
    json={"target_org_id": 77, "mode": "copy"},
).json()
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `target_org_id` | integer | yes | For `mode="move"` it must differ from the source org id |
| `mode` | string | no | `copy` (default — keep source intact) or `move` (re-home the agent) |
| `name` | string | no | Override the new agent's name |

`copy` makes the same copy as [Duplicate](#duplicate-an-agent), with the
target org's rules applied: integrations, knowledge, MCP servers and reusable
instructions attach only if the same record belongs to the target org;
webhook endpoints, calendar/CRM connections, client portal listings, legacy
inline `tools`, and test scenarios created from real calls are not copied and
are named in `not_copied`; copied test-suite schedules start disabled; SMS
sending is off until the target org picks one of its own numbers; transfer
numbers the target org could not save (numbers a ThunderPhone number can't
reach, when the target org has no number on its own carrier) are left behind
and reported as `transfer_destinations` in `not_copied`; and the consent
announcement starts on, because another org's attestation does not
cover the target org.

Returns `201 Created` for `copy` (with `not_copied`, a list such as
`["webhook_endpoints"]`) / `200 OK` for `move`:

```json
{
  "mode": "move",
  "source_org_id": 42,
  "target_org_id": 77,
  "agent": { /* Agent object in the target org */ },
  "detached": {
    "publishable_keys": 1,
    "webhook_endpoints": 0,
    "provider_connections": 1,
    "client_portals": 0,
    "transfer_destinations": 0
  }
}
```

<Note>
  A move is rejected while the agent has campaigns, validation examples,
  or pending/running validation or simulation runs. Finish or remove that
  work before retrying. Source-owned phone assignments, publishable keys,
  agent-scoped webhooks, provider connections, client portals, integrations,
  knowledge, and MCP servers are detached or disabled and counted in the
  response. Custom voices stay in the source organization; a voice cloned
  for the agent loses that link (`detached.custom_voices`). Call logs, completed runs, pipeline reports, and import history
  remain in the source organization. Agent variants and prompt analyses move
  with the agent.
</Note>

<Note>
  Copies keep the agent's `steps`. Handoff targets are agents of the source
  organization, so cross-organization copies and moves drop `handoffs`
  (deployed and draft), and a move reports how many it dropped as
  `detached.handoffs`. A move is also rejected while other agents hand off to
  the agent.
</Note>

<Note>
  Cross-organization copies and moves clear deployed and draft SMS senders,
  enablement, broad-recipient permission, and configured contacts. Moved
  version snapshots are scrubbed too, so restoring an old version cannot
  recover the source organization's SMS authority. Configure SMS again in the
  destination organization.
</Note>

---

## Version history

Deploys (and creates/duplicates/transfers) record an
`AgentConfigVersion` snapshot of the **deployed** configuration.
Draft autosaves are *not* versioned — the history reflects what
actually shipped to production.

<CodeGroup>
```bash cURL
curl 'https://api.thunderphone.com/v1/agents/12/versions?limit=20' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

```python Python
versions = requests.get(
    f"https://api.thunderphone.com/v1/agents/{agent_id}/versions",
    params={"limit": 20},
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
).json()
```
</CodeGroup>

| Query param | Default | Description |
|-------------|---------|-------------|
| `limit` | 20 | Max results. Values outside 1–100 are clamped |

Response:

```json
{
  "count": 3,
  "results": [
    {
      "id": 501,
      "revision": 3,
      "created_by_id": 7,
      "created_by_name": "Dana Ruiz",
      "created_by_staff": false,
      "source": "api",
      "restored_from_revision": null,
      "created_at": "2026-04-20T18:24:10.113Z",
      "snapshot": { /* Deployed agent config at this revision */ },
      "changed_fields": ["prompt", "voice"]
    }
  ]
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Version row id |
| `revision` | integer | 1-based, increments per deploy |
| `created_by_id` | integer \| null | User id that deployed the revision |
| `created_by_name` | string \| null | That user's name. `null` when nobody is on record, and for ThunderPhone support staff (then `created_by_staff` is `true`) |
| `created_by_staff` | boolean | Deployed by ThunderPhone support |
| `source` | string \| null | Where the deploy came from: `dashboard`, `zeus`, `copilot` or `api`. `null` for revisions recorded before October 2026 and for imports |
| `restored_from_revision` | integer \| null | The revision this one put back, when it was a [restore](#restore-a-revision) |
| `snapshot` | object | Full deployed config at this revision |
| `changed_fields` | array of string | Fields that differ from the previous revision |

### Restore a revision

Puts the agent back to an earlier deployed revision. The revision's
configuration is saved to the draft the same way a `PATCH` is, then
deployed when you ask for it and your role allows it.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/agents/12/versions/2/restore \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deploy": true}'
```
</CodeGroup>

| Body field | Default | Description |
|------------|---------|-------------|
| `deploy` | `true` | Deploy the restored configuration. Deploying needs an admin or owner; for a member the restore is saved as a draft |
| `if_updated_at` | none | The agent's `updated_at` as you last read it. If the agent changed since, the restore is refused with `409` and nothing changes |
| `if_live_revision` | none | The latest revision as you last read it. If a newer revision was deployed since, the restore is refused with `409`, so an undo never also discards someone else's deploy |
| `discard_drafts` | `false` | Go ahead even though someone else has draft changes, not yet deployed, that the revision would overwrite. Without it, that restore is refused with `409` (below) and nothing changes |
| `confirm_price_change` | `false` | With `deploy`: the person agreed to the higher per-minute price the restored revision brings. Without it, such a restore is refused with `409` `price_change_needs_confirmation`, as a [deploy](#deploys-that-raise-the-price) is |

Response:

```json
{
  "status": "deployed",
  "restored_revision": 2,
  "revision": 4,
  "kept": [{"field": "consent_announcement_enabled", "reason": "needs_attestation"}],
  "also_published": [],
  "discarded": [],
  "agent": { /* The agent, as GET /v1/agents/{agent_id} returns it */ }
}
```

| Field | Description |
|-------|-------------|
| `status` | `deployed`, `draft_saved` (a member, or `deploy: false`) or `no_change` (the agent already matches the revision) |
| `revision` | The new revision the deploy recorded, or `null` |
| `kept` | Settings left as they are now. `needs_attestation`: the revision had the consent announcement or live-processing disclosure off, and turning it off again needs a new [attestation](#consent-attestations). `not_allowed`: your organization's BAA no longer allows the revision's PHI setting. `deleted_since`: some attachments were deleted; the rest are restored. `published_only`: the name, on a restore saved as a draft |
| `also_published` | Draft fields someone had saved that the revision does not cover. A deploy publishes them too, as the deploy endpoint would |
| `discarded` | Other people's draft fields the restore wrote over. Only ever non-empty with `discard_drafts: true` |

When the revision would overwrite draft changes that someone else saved and
has not deployed, the restore is refused with `409` and nothing changes. The
body has the same shape as the [optimistic concurrency](#optimistic-concurrency)
conflict, with `reason` set to `unpublished_drafts`:

```json
{
  "detail": "Agent was modified by another user. Please refresh and try again.",
  "conflict": {
    "reason": "unpublished_drafts",
    "updated_at": "2026-10-17T18:02:11.204Z",
    "changed_at": "2026-10-17T18:02:11.204000+00:00",
    "action": "draft",
    "editors": [{"name": "Sam Lee", "staff": false, "is_you": false}],
    "fields": ["prompt"]
  }
}
```

Ask the person, then send the same request with `discard_drafts: true` to go
ahead. Your own draft changes never block a restore.

A restore saved as a draft (a member, or `deploy: false`) leaves the agent's
name as it is, listed in `kept` with reason `published_only`: renames take
effect immediately, so the name changes when an admin deploys the revision.

The intro clip's audio file is not restored: the agent keeps the clip it has now.

---

## Prompt helpers

These endpoints are convenience wrappers that call the same
underlying models we use in the dashboard. All of them take and return
JSON; none change your agents or any other resource you manage.

### Detect prompt language

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/agents/prompt-language-check \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hola, gracias por llamar..."}'
```
</CodeGroup>

```json Response
{
  "detected_language_code": "es",
  "detected_language_name": "Spanish",
  "mismatch": true,
  "provider": "<provider id>"
}
```

### Translate prompt

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/agents/translate-prompt \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Hola, gracias por llamar…",
    "target_locale": "en-US"
  }'
```
</CodeGroup>

```json Response
{
  "translated_prompt": "Hello, thank you for calling…",
  "source_language_code": "es",
  "source_language_name": "Spanish",
  "provider": "<provider id>",
  "used_fallback": false
}
```

### Generate acknowledgement prompt

Produces a short "filler while thinking" phrase appropriate for
Storm-with-ack products.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/agents/generate-acknowledgement-prompt \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "You are a friendly receptionist for a dental office.",
    "target_locale": "en-US"
  }'
```
</CodeGroup>

```json Response
{
  "acknowledgement_prompt": "Sure, let me take a quick look…",
  "provider": "<provider id>",
  "used_fallback": false
}
```

### Render steps as one prompt

Returns the shared instructions and steps as one prompt, in the form a
stepped agent falls back to when steps cannot run. Use it to turn a stepped
agent back into a single-prompt agent: send the result as `prompt` together
with `"steps": null`. `steps` is checked for shape only, and nothing is saved.
With `"steps": null`, `prompt` comes back unchanged.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/agents/steps/flatten \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "You are Ava, the front desk for Acme Dental.",
    "steps": {
      "start_step": "greet",
      "steps": [
        {
          "id": "greet",
          "name": "Greeting",
          "instructions": "Ask how you can help.",
          "transitions": [{"to": "book", "when": "The caller wants an appointment"}]
        },
        {"id": "book", "name": "Book", "instructions": "Offer open slots and book one."}
      ]
    }
  }'
```
</CodeGroup>

```json Response
{
  "prompt": "You are Ava, the front desk for Acme Dental.\n\n## Conversation flow\n1. Greeting (start here): Ask how you can help.\n   - If The caller wants an appointment → go to Book\n2. Book: Offer open slots and book one.\n"
}
```

### Analyze a prompt

Runs the same advisory checks the agent builder shows under the prompt
editor. A model extracts facts from the prompt text (languages, tools it
mentions, escalation and consent guidance), and the API compares them
with the agent's configuration. Nothing is saved to the agent, so you can
send an unsaved draft. Requires the `member` role or higher.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/agents/123/prompt-analysis \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Eres la recepcionista de una clínica dental. Usa book_appointment para agendar citas.",
    "primary_language": "en",
    "additional_languages": [],
    "voice": "john",
    "integration_ids": [],
    "mcp_server_ids": []
  }'
```
</CodeGroup>

| Field | Type | Description |
|-------|------|-------------|
| `prompt` | string | **Required.** The prompt text to analyze. May be empty. Max 100,000 characters. |
| `primary_language` | string | Language code to check against. |
| `additional_languages` | string[] | Additional language codes to check against. |
| `voice` | string | Voice to check language coverage against. |
| `integration_ids` | integer[] | Integrations to treat as connected. |
| `mcp_server_ids` | integer[] | MCP servers to treat as connected. |
| `integration_public_ids` | string[] | The same as `integration_ids`, by the integration `id` the agent and integration endpoints return. Ignored when `integration_ids` is sent. |
| `mcp_server_public_ids` | string[] | The same as `mcp_server_ids`, by the MCP server `id`. Ignored when `mcp_server_ids` is sent. |

Every field except `prompt` is optional. An omitted field uses the
agent's draft value, or the deployed value when the draft has none, so
the findings depend on the agent unless you send every field, as the
example does.

```json Response
{
  "facts": {
    "languages": {
      "declared": [],
      "written_in": [{"code": "es", "share": 1.0}]
    },
    "tools": {
      "referenced": [
        {"name": "book_appointment", "kind": "identifier", "evidence": "Usa book_appointment para agendar citas"}
      ]
    },
    "escalation": {"present": false, "kind": "none", "evidence": ""},
    "compliance": {"present": false, "evidence": ""}
  },
  "findings": [
    {
      "id": "languages-not-configured",
      "severity": "warning",
      "params": {"languages": [{"code": "es", "supported_by_voice": true}]}
    },
    {
      "id": "primary-language-mismatch",
      "severity": "warning",
      "params": {"detected": "es", "primary": "en"}
    },
    {
      "id": "tool-actions-without-tools",
      "severity": "warning",
      "params": {"tools": ["book_appointment"]}
    },
    {"id": "missing-escalation-guidance", "severity": "warning", "params": {}},
    {"id": "missing-consent-or-privacy-guidance", "severity": "info", "params": {}}
  ]
}
```

| Finding `id` | Severity | Meaning |
|--------------|----------|---------|
| `languages-not-configured` | `warning` | The prompt declares a language, or has at least 20% of its text in one, that the agent isn't configured for. `params.languages` lists each code and whether the voice supports it. |
| `primary-language-mismatch` | `warning` | At least 60% of the prompt is written in `params.detected`, not the primary language `params.primary`. |
| `tool-actions-without-tools` | `warning` or `info` | The prompt promises actions that need an external system, but no integration or MCP server is connected. `warning` when it names a tool identifier, `info` when it only describes an action. `params.tools` lists up to five. |
| `tool-arguments-not-declared` | `warning` | The prompt tells the agent to send arguments that a connected integration does not declare in `spec.function.parameters.properties`. `params.undeclared` lists up to five tools as `{name, arguments}`. |
| `missing-escalation-guidance` | `warning` | The prompt gives no path to a human, transfer or callback. |
| `missing-consent-or-privacy-guidance` | `info` | The prompt has no consent, recording-notice, privacy or disclosure guidance. |

`facts` is what the model extracted; `findings` are computed from the
facts and the configuration on every request. New finding ids and fact
keys may be added, so ignore ones you don't recognize.

The analysis is advisory and never fails the request because the model
did:

- If the model is unavailable or returns something unusable, you get
  `200` with `{"findings": [], "facts": null, "error": "unavailable"}`.
- Facts are cached per agent and prompt text. Repeating a prompt returns
  instantly, with findings recomputed against the current configuration.
- Uncached requests are throttled per agent. A new model request starts
  no sooner than two seconds after the previous one started, and while
  one is still running it holds a 20-second lease. A request inside
  either window returns the last good result with `"stale": true` and
  `retry_after_ms`. If there is no earlier result it returns `202` with
  only `retry_after_ms`. Either way, retry after that many milliseconds.

### Review a prompt

Reviews a prompt against ThunderPhone's voice-agent prompt style guide. MCP
clients can read the guide as the resource `thunderphone://guides/prompt-style`.
A model reads the prompt and the API checks its answer: every quote and edit
is an exact passage of the prompt, and an edit that would not apply is left
out. Nothing about the agent changes; the rule inventory is saved with the
agent's prompt revision for that text, so later reviews keep its ids.
Requires the `member` role or higher and the agent iteration toolkit, which
is enabled per organization while it is in beta: without it the response is
`403` with `code: "feature_not_enabled"` and a `next_step`. An OAuth token
needs the `agents:write` scope, for a dry run too, since a review saves the
prompt's rule inventory and spends credits.

<CodeGroup>
```bash cURL
# 1. Quote it.
curl -X POST https://api.thunderphone.com/v1/agents/123/prompt-review \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true}'

# 2. Run it with the quote_id the dry run returned, capped at the amount you approve.
curl -X POST https://api.thunderphone.com/v1/agents/123/prompt-review \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"quote_id": "<quote_id from step 1>", "max_cost_cents": 30}'
```
</CodeGroup>

The review is paid, so it is quoted first. A `dry_run` returns
`estimated_cost_cents` (the likely cost), `worst_case_cost_cents` (the most
it can cost: every input token uncached and the model's full output
allowance) and a `quote_id`. The quote is signed and valid for 15 minutes,
and it is bound to the agent and to these exact inputs (`prompt`,
`previous_prompt`, `previous_inventory`, `language`) and to the model and
its prices. A run that calls the model sends it back with `max_cost_cents`
and is held to the lower of the two. It is refused before anything is spent,
with `400`, a `code` and a `next_step`, when the quote is missing
(`quote_required`), is not one the API issued, has expired, was issued for
other inputs or prices (`quote_invalid`, `quote_expired`, `quote_mismatch`),
was already used (`quote_used`: a quote pays for one run), or when the run
would now cost more than quoted (`quote_outdated`). Without
`max_cost_cents` the response is `400` with `code: "max_cost_required"`, and
the quote is not used up. The quote is used up just before the model is
called, so a run stopped before that (for example by a `max_cost_cents`
below the call's bound) leaves it usable. From then on it stays used, so a
run that fails after the call was sent needs a new dry run before you repeat
it, and its error's `next_step` says so. A review of text this agent already
had reviewed with the same inputs comes from cache, costs nothing and needs
neither.

| Field | Type | Description |
|-------|------|-------------|
| `prompt` | string | The text to review. Omitted, the agent's draft prompt, or its deployed prompt when there is no draft. Max 100,000 characters. |
| `previous_prompt` | string | The prompt before the edit you are checking. Findings then focus on the passages that changed, and behaviors that are still there keep their inventory ids. |
| `previous_inventory` | object[] | `rule_inventory` from an earlier review. Without it, the inventory stored for `previous_prompt` is used when there is one, else the newest inventory saved for another version of the agent's prompt. |
| `language` | string | Language code the prompt is written in. Defaults to the agent's primary language. |
| `quote_id` | string | The `quote_id` of a dry run with the same inputs. Required unless `dry_run` is set or the review comes from cache. |
| `max_cost_cents` | number | The most this run may cost, in US cents. Required with `quote_id`. |
| `dry_run` | boolean | Return only the quote (`estimated_cost_cents`, `worst_case_cost_cents`, `steps` and `quote_id`), without calling the model. |

```json Response
{
  "agent_id": 123,
  "prompt_source": "draft",
  "prompt_sha256": "9c1f…",
  "findings": [
    {
      "guideline_id": "S1",
      "guideline_title": "One question per turn, and the question ends the turn",
      "quote": "Ask for their name and their phone number, then tell them we will call back.",
      "problem": "Two questions in one turn, with a statement after them that talks over the caller's answer.",
      "severity": "major",
      "suggested_edit": {
        "find": "Ask for their name and their phone number, then tell them we will call back.",
        "replace": "Tell them we will call back, then ask for their name. Once they answer, ask for their phone number."
      }
    }
  ],
  "prompt_edits": [
    {
      "find": "Ask for their name and their phone number, then tell them we will call back.",
      "replace": "Tell them we will call back, then ask for their name. Once they answer, ask for their phone number."
    }
  ],
  "rule_inventory": [
    {
      "id": "b4d1e09a2",
      "behavior": "Ask for the caller's name and phone number to arrange a callback.",
      "quote": "Ask for their name and their phone number",
      "quotes": ["Ask for their name and their phone number"]
    }
  ],
  "overlaps": [],
  "misplaced": [],
  "greeting": "Thanks for calling Northside Plumbing, how can I help?",
  "refactor_suggested": false,
  "refactor_reasons": [],
  "refactor_facts": {"behaviors": 14, "rules_added_since_refactor": null, "repeated": 0, "duplicates": 0, "conflicts": 0, "misplaced": 0},
  "model": "gpt-5-6-terra",
  "cached": false,
  "usage": [
    {"step": "review", "model": "gpt-5-6-terra", "input_tokens": 4810, "cached_input_tokens": 0, "output_tokens": 1630, "reasoning_tokens": 420, "cost_cents": 3.16}
  ],
  "cost_cents": 3.16,
  "validation": {"findings_dropped": 0, "quotes_repaired": 0, "edits_dropped": 0, "edits_repaired": 0, "inventory_dropped": 0, "inventory_ids_reassigned": 0, "inventory_quotes_missing": 0}
}
```

| Field | Meaning |
|-------|---------|
| `findings` | Up to 25, most important first. `guideline_id` names a guideline of the style guide, `quote` is an exact passage of the prompt, `problem` is one sentence in English, and `severity` is `major` (it changes what the agent does or how a caller hears it) or `minor`. `suggested_edit` is `null` when the fix is larger than one edit. With `previous_prompt`, each finding also has `in_changed_passage`. |
| `prompt_edits` | The findings' edits that apply together, in order. Each `find` occurs exactly once in the prompt. Apply them in order and send the result as the agent's `prompt`. |
| `rule_inventory` | The behaviors the prompt asks of the agent, each with an `id`, one sentence, and in `quotes` every passage that asks for it (`quote` is the first). A behavior the prompt states in more than one place has more than one quote. A behavior the model names without a passage of the prompt is left out (counted in `validation.inventory_dropped`), and a carried-over id left out that way counts as `removed`. Ids carry over between reviews of successive versions, and a new behavior gets a new id; a behavior an older version asked for that comes back takes its old id. `meaning` stays the same while a behavior asks for the same thing, however it is worded, so two inventories differ in meaning exactly where their `meaning` tokens differ. |
| `inventory_changes` | Only with a previous inventory: where it came from (`previous_inventory`: `supplied`, `stored` for `previous_prompt`'s, or `agent` for the agent's newest), the ids `added` and `removed` since it, `changed`, the carried-over ids whose behavior now asks the agent for something different, and `added_back`, the added ids an older version of the prompt had. |
| `conversations` | Only when reviewing the agent's own prompt and the agent has test conversations: how many are `active`, how many were written for a prompt whose behaviors differ from this one (`with_behavior_changes`, plus `unknown` when that prompt was never reviewed), `refresh_suggested`, and a `next_step` naming `refresh_conversations`. |
| `overlaps`, `misplaced` | Separate behaviors that contradict each other (`conflict`) or ask for much the same thing (`duplicate`), and rules that sit far from the part of the call they govern. |
| `greeting` | The line the prompt tells the agent to open with word for word, or `null`. |
| `refactor_suggested`, `refactor_reasons` | Whether the prompt is due a [refactor](#refactor-a-prompt): two or more behaviors stated in more than one place, two or more overlaps, three or more misplaced rules, or five or more behaviors added since the last refactor when that is known. Each reason has a `code`, a `count` and a sentence. `refactor_facts.rules_added_since_refactor` counts the behaviors whose ids are not in the inventory of the agent's last verified refactor, once the agent's prompt has been that refactor's text, and is `null` when there is no such refactor. |
| `cost_cents`, `usage` | What the model call cost. A review of text that was already reviewed comes from cache (`"cached": true`) and costs nothing. |
| `validation` | How many of the model's items the API dropped or repaired because they did not match the prompt. |

If the model is unavailable, the response is `503` with a `code` and a
`next_step`, and nothing about the agent changes. A model deployment with no
price on record is refused (`503`, `model_unpriced`), since its cost could not
be capped. A call the provider answers without reporting its usage, or that
times out after it was sent, is counted at its worst case. Prompts in any
language can be reviewed: findings are written in English, and quotes stay
in the prompt's language. Reviews are limited to 60 an hour per user.

The inventory of the agent's current prompt is saved with that prompt
revision. The inventory of other text (a candidate you send, or a rewrite
not applied yet) and each review's result are cached for this agent only:
reviews for 7 days and inventories for 90 days, each under the inventory its
ids were carried over from, so two lines of edits never overwrite each
other. Deleting the agent, or its organization, deletes these cached
entries.

### Refactor a prompt

Rewrites a prompt into the style guide's shape, keeping what it asks the
agent to do, and maps every behavior of its inventory onto the new text.
Use it when a review reports `refactor_suggested`. The rewrite is returned,
not saved: apply it with [Update an agent](#update-an-agent-writes-the-draft),
test the draft, and deploy only when the tests pass. Requires the `member`
role or higher and the agent iteration toolkit (see [Review a prompt](#review-a-prompt)).

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/agents/123/prompt-refactor \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instructions": "Keep the Spanish section at the end.", "dry_run": true}'

curl -X POST https://api.thunderphone.com/v1/agents/123/prompt-refactor \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instructions": "Keep the Spanish section at the end.", "quote_id": "<quote_id>", "max_cost_cents": 90}'
```
</CodeGroup>

A refactor makes up to three paid model calls: a review of the current
prompt when none is on record, the rewrite, and the verification. Quote it
with `dry_run` first: `steps` lists each call with its `estimated_cost_cents`
and `worst_case_cost_cents`, and the `quote_id` binds the run to these exact
inputs (`prompt`, `inventory`, `instructions`, `language`, `verify`) and the
quoted total, as for a [review](#review-a-prompt). Send it back with
`max_cost_cents`; a `max_cost_cents` of the total `worst_case_cost_cents`
lets every step run. Each call is checked against what is left of the lower
of the two before it is sent, using its worst case. When no review of the
text is on record, the quote counts the longest inventory a review can
return, so its worst case is far above the estimate; review the prompt first
for a closer quote.
The whole request also has one time limit (200 seconds); each call gets only
the time that is left.

When the cap or the time limit leaves no room for the review or the rewrite,
that call is not sent: the response is an error (`400` with
`max_cost_too_low`, or `503` with `deadline_reached`) that names the `stage`
and carries what is already done (`inventory`, `greeting`, and `cost_cents`
for any call already made). When the review was sent, the run has used up
its `quote_id`: send a dry run with that `inventory` for a new quote, then
repeat with it, and the review is not paid for again. When nothing was sent,
the quote is still usable. When only the verification no longer fits, the rewrite
is returned with `verification` set to `skipped_cost` or `skipped_deadline`.

| Field | Type | Description |
|-------|------|-------------|
| `prompt` | string | The text to refactor. Omitted, the agent's draft prompt, or its deployed prompt when there is no draft. |
| `inventory` | object[] | `rule_inventory` from a review of this exact text. Without it, the stored inventory is used, or the API reviews the prompt first (a second model call, included in `cost_cents`). |
| `instructions` | string | Anything else the rewrite should do, up to 4,000 characters. |
| `language` | string | Language code the prompt is written in. Defaults to the agent's primary language. |
| `verify` | boolean | Default `true`. Re-read the new prompt to find behaviors the rewrite added, removed or changed (one more review call, included in `cost_cents`). |
| `quote_id` | string | The `quote_id` of a dry run with the same inputs. Required unless `dry_run` is set. |
| `max_cost_cents` | number | The most this run may cost, in US cents, across all its calls. Required with `quote_id`. |
| `dry_run` | boolean | Return only the quote: `estimated_cost_cents`, `worst_case_cost_cents`, `steps` and `quote_id`, including the review and the verification when they would run. |

```json Response
{
  "agent_id": 123,
  "prompt_source": "draft",
  "prompt": "You answer the phone for Northside Plumbing…",
  "summary": "Moved the callback rules into the part of the call where they apply and merged two repeated rules about short answers.",
  "has_dropped_behaviors": false,
  "dropped_behaviors": [],
  "behavior_preserved": false,
  "behavior_changes": {
    "added": [
      {
        "id": "bc248a9ea",
        "behavior": "Ask one question at a time and end each turn with the question.",
        "quote": "Ask one question at a time, and end the turn with the question."
      }
    ],
    "removed": [],
    "changed": []
  },
  "verification": "done",
  "new_findings": [],
  "new_inventory": [{"id": "b4d1e09a2", "behavior": "Ask for the caller's name, then their phone number.", "quote": "ask for their name", "quotes": ["ask for their name"]}],
  "unlocated_behaviors": [],
  "behavior_map": [
    {
      "id": "b4d1e09a2",
      "behavior": "Ask for the caller's name and phone number to arrange a callback.",
      "status": "reworded",
      "new_quote": "ask for their name",
      "located": true,
      "note": "Split into one question per turn."
    },
    {
      "id": "b77c0f1e3",
      "behavior": "Keep answers short.",
      "status": "merged",
      "into_id": "b0a9d4c61",
      "new_quote": "Keep each turn to one or two short sentences",
      "located": true,
      "note": "It repeated the paragraph on how to speak."
    }
  ],
  "greeting": "Thanks for calling Northside Plumbing, how can I help?",
  "diff": "--- current\n+++ refactored\n@@ …",
  "prompt_edits": [{"find": "<the whole current prompt>", "replace": "<the whole new prompt>"}],
  "inventory_source": "review",
  "model": "gpt-6-1-sol",
  "cost_cents": 9.8
}
```

Every behavior of the inventory appears in `behavior_map` exactly once, as
`kept`, `reworded`, `merged` (with `into_id`) or `dropped`. A behavior the
rewrite did not account for is `unaccounted`. Both `dropped` and
`unaccounted` behaviors are listed in `dropped_behaviors`, so check
`has_dropped_behaviors` before you apply the rewrite. `unlocated_behaviors`
lists behaviors the map says were kept whose passage could not be found in
the new text.

The map is the rewrite's own account. With `verify` on (the default), a
separate review then reads the new prompt with the old inventory, so each
behavior keeps its id, and reports what it finds in `behavior_changes`:
`added` (a behavior the old prompt did not ask for), `removed` (an old
behavior the new prompt no longer asks for, with the `refactor_status` the
map gave it), and `changed` (the same behavior, `before` and `after`, where
the new text asks the agent for something different). `behavior_preserved`
is `true` only when all three are empty; review the changes before you apply
a rewrite where it is `false`. `new_findings` are that review's findings on
the new text, and `new_inventory` its inventory, which later reviews of the
new prompt reuse. Once the agent's prompt is the new text, that inventory is
the baseline for `rules_added_since_refactor` in later reviews. If the
verification cannot run, `verification` is `failed` (or `skipped_cost` or
`skipped_deadline`, see above), `behavior_preserved` is `null`, and the
rewrite is still returned. With `verify: false`, `verification` is `off`.

The API rejects a rewrite with `502`, a `code` and a `next_step` when it
comes back empty, cut off or far shorter than the prompt, when it changes a
`{{variable}}` placeholder in any way other than moving it (each one has to
come back exactly as written, default included, as many times as before:
`refactor_changed_placeholders`), or when it changes the line the agent
opens with word for word (`refactor_changed_greeting`), with `verify` on or
off. That line is the one the review of the current prompt found, never the
rewrite's own account of it; when no review of this exact text is on record,
the refactor runs one first. Change the greeting with an edit instead. A rejected rewrite still reports its `cost_cents`. If the model
is unavailable, the response is `503`. Refactors are limited to 20 an hour
per user.

---

## Voices

List the supported voices and languages — or browse the [voice gallery](/api-reference/voices) with playable samples:

```bash
curl 'https://api.thunderphone.com/v1/voices?languages=en,es' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

```json Response
{
  "voices": [
    {
      "name": "john",
      "display_name": "John",
      "gender": "male",
      "category": "multilingual",
      "accent": "american",
      "languages": ["en", "es", "fr", "…"],
      "sample_url": "https://…/john.mp3?v=3"
    }
  ],
  "languages": [ /* language catalog entries */ ],
  "elevenlabs": {
    "provider": "ElevenLabs",
    "model": "eleven_v4_turbo",
    "model_label": "Eleven v4 Turbo",
    "surcharge_cents": 5,
    "hipaa_eligible": false,
    "available": true,
    "unavailable_reason": null,
    "languages": ["ar", "bn", "…"],
    "voices": [
      {
        "name": "elevenlabs:UgBBYS2sOqTuMpoF3BR0",
        "display_name": "Mark",
        "tagline": "Natural Conversations",
        "description": "A casual, young-adult speaking in a natural manner. Perfect for Conversational AI.",
        "gender": "male",
        "age": "young",
        "accent": "american",
        "native_language": "en",
        "use_case": "conversational",
        "sample_url": "https://storage.googleapis.com/eleven-public-prod/…/0Oc7jiXwWN9kRTXfQsmw.mp3"
      }
    ]
  }
}
```

| Query param | Description |
|-------------|-------------|
| `languages` | Comma-separated codes — only voices supporting **all** of them are returned |
| `category` | Filter by voice category |
| `gender` | Filter by voice gender |

The `name` is what you set on an agent's `voice` field.

### ElevenLabs voices

The `elevenlabs` block lists voices from ElevenLabs under ElevenLabs' own names,
on the Eleven v4 Turbo model. Every voice speaks every code in its `languages`,
which is the whole language catalog. On the pricing existing accounts keep
until December 1, 2026, they cost `surcharge_cents` per minute in every
language, in place of any language or premium-voice surcharge. On the
[new pricing](/guides/pricing) there is no surcharge: the voice is billed at
ElevenLabs' list price, plus the markup, and `surcharge_cents` does not apply. The
`gender` filter applies to this block too; `languages` and `category` keep it
only when every requested language is covered or the category is `elevenlabs`.

ElevenLabs voices are **not HIPAA eligible yet** (`hipaa_eligible: false`):

- An agent, draft, step, split-test variant or realtime session whose PHI
  designation resolves to PHI cannot select one. The request fails with
  `"ElevenLabs voices are not HIPAA eligible yet. Ask us to enable HIPAA for them, or pick another voice."`,
  as does switching an agent that uses one to processing PHI.
- `available` is `false` with `unavailable_reason: "phi"` when your whole
  organization resolves to PHI. Individual agents may still be designated as
  not processing PHI; the check above is per agent.
- If a call to an agent with an ElevenLabs voice runs as a PHI call anyway, it
  uses a standard voice for the call language and carries no ElevenLabs charge.

### Every voice

`GET /v1/voices` lists the featured voices. `GET /v1/voices/library` searches
every voice from every voice vendor we use, many thousands in all:

```bash
curl 'https://api.thunderphone.com/v1/voices/library?q=warm+australian&language=en&limit=2' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

```json Response
{
  "voices": [
    {
      "name": "platform:cooper",
      "display_name": "Cooper",
      "tagline": "",
      "description": "Casual, warm Australian male voice, ideal for lifestyle content, travel, and casual narration.",
      "gender": "male",
      "accent": "australian",
      "age": null,
      "use_case": "conversational",
      "languages": ["en"],
      "native_language": "en",
      "group": "platform",
      "surcharge_cents": 0,
      "hipaa_eligible": true,
      "sample_url": "https://api.thunderphone.com/v1/voices/library/sample?voice=platform%3Acooper&sig=…"
    }
  ],
  "total": 14,
  "offset": 0,
  "limit": 2
}
```

| Query param | Description |
|-------------|-------------|
| `q` | Words that must each start a word of the voice's name, description, accent or style (`male` does not match `female`) |
| `group` | `platform` (ThunderPhone platform voices), `cartesia` or `elevenlabs` |
| `language` | Only voices that speak this language code |
| `gender` | `female` or `male` |
| `accent` | Words of the accent, e.g. `australian` |
| `age` | `young`, `middle_aged` or `old` |
| `use_case` | `conversational`, `narrative_story`, `informative_educational`, `social_media`, `advertisement`, `characters_animation` or `entertainment_tv` |
| `hipaa` | `true` for voices an agent that processes PHI may use |
| `compact` | `true` for browsing: without `q` or `accent`, leaves out platform voices in languages other platform voices already cover |
| `exclude_featured` | `true` leaves out the ElevenLabs voices `GET /v1/voices` already lists |
| `names` | Comma-separated voice names to look up (up to 50) instead of searching |
| `limit`, `offset` | Page size (1–200, default 50) and start; `total` counts every match |

Set an agent's `voice` (or a step's, a variant's or a realtime session's) to a
voice's `name`:

- `platform:<id>` and `cartesia-library:<id>` voices speak the codes in their
  `languages`. An agent whose primary or additional languages they don't speak
  is refused, and native voice switching does not apply to them. They are
  HIPAA eligible.
- `elevenlabs:<id>` voices follow the [ElevenLabs rules](#elevenlabs-voices):
  every language, not HIPAA eligible yet.
- `surcharge_cents` is added to the per-minute price, as for featured voices,
  on the pricing existing accounts keep until December 1, 2026. An agent's
  grandfathered premium-voice rate applies to them too. On the
  [new pricing](/guides/pricing) the voice is billed at its provider's list
  price instead, and `surcharge_cents` does not apply.
- `sample_url` plays without an `Authorization` header. Platform and Cartesia
  samples are made the first time anyone plays them, so the first play can
  take a few seconds; the URL works for seven days.

---

## Related

<CardGroup cols={2}>
  <Card title="Voice agent settings" icon="sliders" href="/guides/agent-settings">
    Match API fields to the dashboard controls.
  </Card>
  <Card title="Built-in tools" icon="wrench" href="/guides/built-in-tools">
    Configure platform-run actions and their limits.
  </Card>
  <Card title="Transfer calls" icon="phone-arrow-right" href="/guides/call-transfers">
    Set cold and screened warm-transfer routing.
  </Card>
  <Card title="Phone Numbers" icon="phone" href="/api-reference/phone-numbers">
    Assign agents to inbound/outbound directions on phone numbers.
  </Card>
  <Card title="Reusable instructions" icon="list-check" href="/api-reference/reusable-instructions">
    Organization-wide prompt sections attached via `reusable_instruction_ids`.
  </Card>
  <Card title="Knowledge bases" icon="book" href="/api-reference/knowledge-bases">
    Ground the agent in your documents.
  </Card>
  <Card title="Split testing" icon="shuffle" href="/api-reference/split-testing">
    A/B test prompt and voice variants on live traffic.
  </Card>
  <Card title="Test scenarios" icon="flask" href="/api-reference/test-scenarios">
    Regression-test the agent before deploying.
  </Card>
</CardGroup>

<!-- en: api-reference/prompt-revisions -->
---
title: "Prompt Revisions"
description: "Every change to an agent's prompt text, drafts included, with a diff against the version it replaced."
---

A prompt revision is one version of an agent's prompt text. ThunderPhone
records one every time the text changes, from every place that can change
it: the dashboard builder, the copilot, the REST API, the
[MCP server](/guides/thunderphone-mcp-server), a version restore, an
investigation fix, a deploy, a discarded draft, a duplicate or an import.
[Version history](/api-reference/agents#version-history) records deployed
configurations only; prompt revisions also cover every draft edit in
between, so a test run, a test conversation or a call can name the exact
text it ran.

Revisions form lines. The agent's main line is its draft and deployed
prompt. Each [A/B variant](/api-reference/split-testing) with its own prompt
has its own line, and a prompt that a [replay run](/api-reference/replay-runs)
tested without it ever being the draft is recorded as a `candidate`, off the
main line. A text that comes back later (a rule removed, then added back) is
a new revision linked to the one it replaced.

## The agent iteration toolkit

These endpoints are part of the agent iteration toolkit: prompt revisions,
[test conversations](/api-reference/conversations),
[replay runs](/api-reference/replay-runs), prompt
[review](/api-reference/agents#review-a-prompt) and
[refactor](/api-reference/agents#refactor-a-prompt), and
[talk links](/api-reference/talk-links). The toolkit is enabled per
organization while it is in beta. Without it, every toolkit endpoint answers
`403` with `code: "feature_not_enabled"` and a `next_step`; ask
[support](mailto:support@thunderphone.com) to enable it.

Three rules run through the toolkit:

- **The test split is hidden from API keys.** Each test conversation belongs
  to a dev split, for tuning, or a test split, for measuring a change once.
  API keys and OAuth tokens (and so MCP clients) see a test-split item as
  its id, split, source, status and counts only. People signed in to the
  dashboard see everything. Prompt revisions are the agent's own
  configuration, not call content, so this rule does not apply on this page.
  In an organization with the toolkit, a call whose caller is in an
  agent's test split is held out: the calls API and the MCP call tools
  return it to API keys and OAuth tokens as its id, start time and
  `held_out: true` only (see [test conversations](/api-reference/conversations#dev-and-test-splits)).
  Leave those calls out when tuning.
- **`dry_run` quotes before anything is spent.** Every endpoint that spends
  model or replay credits takes `dry_run: true` and returns an estimate
  without running anything. Conversation jobs (generate, import, refresh)
  and replay runs also return a `quote_id`, and a real run must send it
  back: it is good for 15 minutes, for the same arguments only, and for one
  run. It is used up once, durably, as the run starts; a start that is
  refused or fails before then leaves it usable, and a run that fails after
  it is repeated with a new dry run for a new `quote_id`.
- **`max_cost_cents` is a hard cap.** A real run needs a spend cap in US
  cents. Before each request the run sets aside the most that request can
  cost and stops instead of sending one that does not fit, keeping what it
  already did. So a conversation job or replay run can stop with part of
  its cap unspent: leave about twice the estimate's
  `largest_reservation_cents` of headroom above the expected cost. A run is
  charged what its requests really cost, not what it set aside. Prompt
  review and refactor need a cap for any call not answered from the cache,
  one that covers the dry run's `worst_case_cost_cents`.

With OAuth, the toolkit's endpoints need these scopes: prompt review and
refactor `agents:write` (their dry runs too) and prompt revisions
`agents:read`; test conversations, conversation jobs and replay runs
`testing:read` to read and `testing:write` to start; talk links
`calls:write`. Without the scope the response is `403` with
`error: "insufficient_scope"`.

Reading prompt revisions spends nothing, so these endpoints take neither
`dry_run` nor `max_cost_cents`.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/agents/{agent_id}/prompt-revisions` | List an agent's prompt revisions, newest first |
| `GET` | `/v1/agents/{agent_id}/prompt-revisions/{revision_id}` | Retrieve one revision with its full text |

## Prompt revision object

```json
{
  "id": 4182,
  "agent_id": 123,
  "sha256": "9c1f0b6e2a…",
  "source": "draft",
  "actor": "mcp",
  "author_name": null,
  "author_staff": false,
  "parent_id": 4177,
  "variant_id": null,
  "config_version_revision": null,
  "created_at": "2026-10-19T17:02:11.204Z",
  "text_length": 2214,
  "rule_inventory": [],
  "diff": "--- revision 4177\n+++ revision 4182\n@@ -3 +3 @@\n-Ask for their name and their phone number.\n+Ask for their name. Once they answer, ask for their phone number.\n"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Revision id |
| `sha256` | string | SHA-256 of the text. [Review a prompt](/api-reference/agents#review-a-prompt) returns the same value as `prompt_sha256`, and the MCP `update_agent` tool takes it as `expected_prompt_sha256` |
| `source` | string | `draft` (a draft edit), `deploy`, `variant` (an A/B variant's prompt), `import`, `backfill` (recorded from older version history), or `candidate` (a prompt a replay run tested) |
| `actor` | string | Where the write came from: `dashboard`, `zeus`, `api` (API keys and OAuth), `mcp`, `copilot`, `replay`, or empty for writers with no surface |
| `author_name` | string \| null | The person who made the change, when a person did |
| `author_staff` | boolean | `true` when a ThunderPhone staff member made the change |
| `parent_id` | integer \| null | The revision this one replaced in the same line |
| `variant_id` | integer \| null | The variant whose line this is, for `source: "variant"` |
| `config_version_revision` | integer \| null | The deployed [version](/api-reference/agents#version-history) that carried this text, when one did |
| `text_length` | integer | Characters in the text |
| `rule_inventory` | object[] | The behaviors the prompt asks for, with stable ids, once a [review](/api-reference/agents#review-a-prompt) has read this text; empty before that |
| `diff` | string | Unified diff against the parent revision (against an empty text for the first) |
| `text` | string | The full text. Only on the single-revision endpoint |

Agents created before prompt revisions existed get their history recorded
from their deployed versions (`source: "backfill"`) the first time their
prompt changes.

## List prompt revisions

<CodeGroup>
```bash cURL
curl 'https://api.thunderphone.com/v1/agents/123/prompt-revisions?source=draft&limit=20' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

```python Python
page = requests.get(
    "https://api.thunderphone.com/v1/agents/123/prompt-revisions",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    params={"limit": 20},
).json()
for revision in page["results"]:
    print(revision["id"], revision["source"], revision["actor"])
```
</CodeGroup>

### Query parameters

| Param | Type | Description |
|-------|------|-------------|
| `source` | string | Only revisions from this source |
| `limit` | integer | 1 to 100, default 20. Values outside the range are clamped |
| `offset` | integer | Default 0 |

Returns a page, newest first. The revisions in it have no `text`; fetch one
to read it.

```json
{
  "count": 37,
  "limit": 20,
  "offset": 0,
  "next_offset": 20,
  "results": [{ "id": 4182, "source": "draft", "diff": "…" }]
}
```

`next_offset` is `null` on the last page.

## Retrieve a prompt revision

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/agents/123/prompt-revisions/4182 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Returns the [revision object](#prompt-revision-object) with `text`.

## Errors

| Status | Condition |
|--------|-----------|
| `400` | An unknown `source`, or a `limit` or `offset` that is not an integer |
| `403` | `feature_not_enabled`: the organization does not have the agent iteration toolkit |
| `404` | The agent, or the revision, is not in this organization |

## MCP

The [MCP server](/guides/thunderphone-mcp-server) exposes the list as
`list_prompt_revisions`.

---

## Related

<CardGroup cols={2}>
  <Card title="Agents" icon="robot" href="/api-reference/agents">
    Review and refactor a prompt, and write the draft.
  </Card>
  <Card title="Replay Runs" icon="rotate" href="/api-reference/replay-runs">
    Test a revision on the agent's dev and test splits.
  </Card>
</CardGroup>

<!-- en: api-reference/agent-imports -->
---
title: "Agent imports"
description: "Bring agents, tools, and knowledge bases over from Vapi, Retell, ElevenLabs Agents, or Bland with an API key or a pasted JSON export."
---

An **agent import** fetches everything in a competitor account, maps it onto
ThunderPhone agents, API connections, and knowledge documents, and lets you
review before anything is created. The vendor key is used only for the
import and deleted when it finishes. Admin role is required to start, edit,
commit, or discard an import, or to move a number; members can read it.

## Start an import

`POST /v1/agent-imports`

```json
{ "source": "vapi", "auth_mode": "api_key", "api_key": "…" }
```

`source` is `vapi`, `retell`, `elevenlabs`, or `bland`. `auth_mode` is
`api_key` or `paste` (send the exported JSON as `payload`). Returns `201`
with the import in `queued` status, or `409` with `import_id` if one is
already running.

## Get an import

`GET /v1/agent-imports/{id}` — poll until `status` is `ready`. The response
carries `progress`, one `items[]` entry per source agent (`mapped`,
`warnings`, `selected`), and a `report` of phone numbers, webhooks, and
unsupported tools that are not imported.

Each `report.phone_numbers[]` entry has `ownership`: `customer_carrier` (in
your own carrier account, named by `carrier`: `twilio`, `telnyx`, or
`vonage`), `sip_trunk`, `vendor` (sold by the source platform), or `unknown`.
`carrier_account_id` is the Twilio Account SID when the platform exposed it.

## Edit an item

`PATCH /v1/agent-imports/{id}/items/{item_id}` with any of `selected`,
`name`, `voice`, `product`, `prompt_choice` (`deterministic` or `rewritten`).
Only while the import is `ready`. Setting `voice` on an agent whose source
voice had no close match (`voice_confidence` `default`) marks it `picked`.

## Enter a missing header

`POST /v1/agent-imports/{id}/connection-secrets`

```json
{ "connection": "tool_book", "header_id": "0", "value": "Bearer …" }
```

Source platforms never return stored secrets, so a tool plan lists the
headers it could not copy in `mapped.tools[].missing_headers`
(`id`, `name`, `name_known`, `provided`). `connection` is the plan's `key`,
shared by every agent that uses the tool, so one value covers all of them.
Send `header_name` too when `name_known` is `false`. The value is
write-only: it is encrypted until commit, stored on the API connection it
creates, and never returned. An empty `value` clears it. Only while the
import is `ready`.

## Commit an import

`POST /v1/agent-imports/{id}/commit` — creates the selected agents in the
background; poll the import until `status` is `done`. `result` lists the
created agent, API connection, and knowledge base ids and any failed items.
When a source agent used Cal.com booking tools and the organization has a
Cal.com app connection, commit attaches that connection to the new agent.

## Move a number to an imported agent

`POST /v1/agent-imports/{id}/numbers/move`

```json
{ "number": "+15551112222", "agent_id": 42, "connection_id": 7 }
```

For a `customer_carrier` number on Twilio or Telnyx. `agent_id` must be an
agent this import created, and `connection_id` a
[VoIP connection](/guides/bring-your-own-numbers) for the account that holds
the number. ThunderPhone re-points the number at itself in that account, so
**calls stop going to the source platform**, and sets the agent as the
number's inbound agent. The number starts `provisioning`: when
`needs_verification` is `true`, call
`POST /v1/phone-numbers/{phone_number.id}/verify-voip` to switch it on. A
number already on ThunderPhone in your organization is only re-assigned
(`imported: false`) and needs no `connection_id`. Errors carry a `code`:
`number_not_in_connection` (the account does not hold the number),
`connection_account_mismatch`, `number_not_movable`, `number_in_other_org`
(409), and `carrier_unavailable` (502).

## Discard an import

`DELETE /v1/agent-imports/{id}` — abandons the import and wipes the stored key.

## List imports

`GET /v1/agent-imports` — the organization's 20 most recent imports.

<!-- en: api-reference/voices -->
---
title: "Voices"
description: "Every ThunderPhone voice, with a playable sample."
---

{/* GENERATED FILE — do not edit by hand.
    Source: api/thunderphone_api/data/voice_catalog.json and
    api/thunderphone_api/data/elevenlabs_voice_catalog.json
    Regenerate: python scripts/generate-voices-doc.py */}

Set a voice by `name` on an [agent](/api-reference/agents) or a
[realtime session](/api-reference/realtime). The authoritative list is
always [`GET /v1/voices`](/api-reference/agents#voices); this page is
generated from the same catalog.

Your organization can also create custom voices — see
[Custom voices](/api-reference/custom-voices).

## Multilingual

English, Arabic, Bengali, Bulgarian, Cantonese, Croatian, Czech, Danish, Dutch, Estonian, Finnish, French, German, Greek, Gujarati, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Kannada, Korean, Latvian, Lithuanian, Malayalam, Mandarin, Marathi, Norwegian, Polish, Portuguese, Punjabi, Romanian, Russian, Serbian, Slovak, Slovenian, Spanish, Swahili, Swedish, Tamil, Telugu, Thai, Turkish, Ukrainian, Urdu, Vietnamese.

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah.mp3?v=3)

## American English

**Alec** (`alec`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/alec.mp3?v=3)

**Brandon** (`brandon`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/brandon.mp3?v=3)

**Emma** (`emma`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/emma.mp3?v=3)

**Jake** (`jake`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/jake.mp3?v=3)

**James** (`james`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/james.mp3?v=3)

**Jessica** (`jessica`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/jessica.mp3?v=3)

**Lauren** (`lauren`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/lauren.mp3?v=3)

**Megan** (`megan`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/megan.mp3?v=3)

**Michael** (`michael`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/michael.mp3?v=3)

**Nicole** (`nicole`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/nicole.mp3?v=3)

**Olivia** (`olivia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/olivia.mp3?v=3)

**Rachel** (`rachel`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/rachel.mp3?v=3)

**Ryan** (`ryan`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/ryan.mp3?v=3)

**Tyler** (`tyler`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/tyler.mp3?v=3)

## British English

**Charlotte** (`charlotte`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/charlotte.mp3?v=3)

**Emily** (`emily`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/emily.mp3?v=3)

**Oliver** (`oliver`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/oliver.mp3?v=3)

**William** (`william`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/william.mp3?v=3)

## Indian English & Indic languages

**Ananya** (`ananya`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/ananya.mp3?v=3)

**Diya** (`diya`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/diya.mp3?v=3)

**Isha** (`isha`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/isha.mp3?v=3)

**Kavya** (`kavya`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/kavya.mp3?v=3)

**Priya** (`priya`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/priya.mp3?v=3)

**Riya** (`riya`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/riya.mp3?v=3)

## Bilingual

English, Spanish.

**Carlos** (`carlos`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/carlos.mp3?v=3)

**Diego** (`diego`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/diego.mp3?v=3)

**Isabella** (`isabella`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/isabella.mp3?v=3)

**Valentina** (`valentina`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/valentina.mp3?v=3)

## Premium

**Amit** (`amit`) — male · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/amit.mp3?v=3)

**Andi** (`andi`) — male · indonesian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/andi.mp3?v=3)

**Andrada** (`andrada`) — female · moldovan accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/andrada.mp3?v=3)

**Andrei** (`andrei`) — male · moldovan accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/andrei.mp3?v=3)

**Anika** (`anika`) — female · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anika.mp3?v=3)

**Archie** (`archie`) — male · british accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/archie.mp3?v=3)

**Arlo** (`arlo`) — male · australian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/arlo.mp3?v=3)

**Arun** (`arun`) — male · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/arun.mp3?v=3)

**Aylin** (`aylin`) — female · turkish accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/aylin.mp3?v=3)

**Bence** (`bence`) — male · hungarian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/bence.mp3?v=3)

**Bronte** (`bronte`) — female · australian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/bronte.mp3?v=3)

**Bruno** (`bruno`) — male · brazilian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/bruno.mp3?v=3)

**Caroline** (`caroline`) — female · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/caroline.mp3?v=3)

**Carson** (`carson`) — male · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/carson.mp3?v=3)

**Cathy** (`cathy`) — female · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/cathy.mp3?v=3)

**Chakrit** (`chakrit`) — male · thai accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/chakrit.mp3?v=3)

**Daniel** (`daniel`) — male · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/daniel.mp3?v=3)

**Despina** (`despina`) — female · greek accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/despina.mp3?v=3)

**Divya** (`divya`) — female · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/divya.mp3?v=3)

**Emre** (`emre`) — male · turkish accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/emre.mp3?v=3)

**Eszter** (`eszter`) — female · hungarian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/eszter.mp3?v=3)

**Fraser** (`fraser`) — male · australian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/fraser.mp3?v=3)

**Gemma** (`gemma`) — female · british accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/gemma.mp3?v=3)

**Georgi** (`georgi`) — male · bulgarian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/georgi.mp3?v=3)

**Grace** (`grace`) — female · australian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/grace.mp3?v=3)

**Gurpreet** (`gurpreet`) — male · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/gurpreet.mp3?v=3)

**Hila** (`hila`) — female · israeli accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/hila.mp3?v=3)

**Huda** (`huda`) — female · saudi accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/huda.mp3?v=3)

**Ido** (`ido`) — male · israeli accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/ido.mp3?v=3)

**Ingrid** (`ingrid`) — female · swedish accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/ingrid.mp3?v=3)

**Isha** (`isha-gu`) — female · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/isha-gu.mp3?v=3)

**Ivan** (`ivan`) — male · croatian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/ivan.mp3?v=3)

**Ivana** (`ivana`) — female · bulgarian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/ivana.mp3?v=3)

**Jacqueline** (`jacqueline`) — female · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/jacqueline.mp3?v=3)

**Jakub** (`jakub`) — male · polish accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/jakub.mp3?v=3)

**Jameson** (`jameson`) — male · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/jameson.mp3?v=3)

**Jan** (`jan`) — male · czech accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/jan.mp3?v=3)

**Jana** (`jana`) — female · czech accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/jana.mp3?v=3)

**Jaspreet** (`jaspreet`) — female · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/jaspreet.mp3?v=3)

**Jessie** (`jessie`) — female · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/jessie.mp3?v=3)

**Jianhao** (`jianhao`) — male · chinese accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/jianhao.mp3?v=3)

**Jing** (`jing`) — female · chinese accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/jing.mp3?v=3)

**Jiwoo** (`jiwoo`) — female · korean accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/jiwoo.mp3?v=3)

**Kari** (`kari`) — female · norwegian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/kari.mp3?v=3)

**Kasia** (`kasia`) — female · polish accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/kasia.mp3?v=3)

**Katarina** (`katarina`) — female · slovak accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/katarina.mp3?v=3)

**Katie** (`katie`) — female · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/katie.mp3?v=3)

**Kavita** (`kavita`) — female · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/kavita.mp3?v=3)

**Kavita** (`kavita-ur`) — female · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/kavita-ur.mp3?v=3)

**Kavitha** (`kavitha`) — female · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/kavitha.mp3?v=3)

**Larissa** (`larissa`) — female · brazilian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/larissa.mp3?v=3)

**Lars** (`lars`) — male · norwegian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/lars.mp3?v=3)

**Latha** (`latha`) — female · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/latha.mp3?v=3)

**Lien** (`lien`) — female · vietnamese accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/lien.mp3?v=3)

**Marc** (`marc`) — male · canadian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/marc.mp3?v=3)

**Marco** (`marco`) — male · italian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/marco.mp3?v=3)

**Marta** (`marta`) — female · castilian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/marta.mp3?v=3)

**Matti** (`matti`) — male · finnish accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/matti.mp3?v=3)

**Mette** (`mette`) — female · danish accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mette.mp3?v=3)

**Milla** (`milla`) — female · finnish accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/milla.mp3?v=3)

**Minh** (`minh`) — male · vietnamese accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/minh.mp3?v=3)

**Narin** (`narin`) — female · thai accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/narin.mp3?v=3)

**Natalya** (`natalya`) — female · russian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/natalya.mp3?v=3)

**Nico** (`nico`) — male · german accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/nico.mp3?v=3)

**Nikos** (`nikos`) — male · greek accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/nikos.mp3?v=3)

**Nils** (`nils`) — male · swedish accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/nils.mp3?v=3)

**Noa** (`noa`) — female · dutch accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/noa.mp3?v=3)

**Oleh** (`oleh`) — male · ukrainian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/oleh.mp3?v=3)

**Pauline** (`pauline`) — female · french accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/pauline.mp3?v=3)

**Pavan** (`pavan`) — male · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/pavan.mp3?v=3)

**Peter** (`peter`) — male · slovak accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/peter.mp3?v=3)

**Petra** (`petra`) — female · croatian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/petra.mp3?v=3)

**Pooja** (`pooja`) — female · bangladeshi accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/pooja.mp3?v=3)

**Prakash** (`prakash`) — male · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/prakash.mp3?v=3)

**Ren** (`ren`) — male · japanese accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/ren.mp3?v=3)

**Rodrigo** (`rodrigo`) — male · mexican accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/rodrigo.mp3?v=3)

**Rohan** (`rohan`) — male · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/rohan.mp3?v=3)

**Rohan** (`rohan-ur`) — male · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/rohan-ur.mp3?v=3)

**Ronald** (`ronald`) — male · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/ronald.mp3?v=3)

**Rubel** (`rubel`) — male · bangladeshi accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/rubel.mp3?v=3)

**Sergei** (`sergei`) — male · russian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sergei.mp3?v=3)

**Sindhu** (`sindhu`) — female · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sindhu.mp3?v=3)

**Siti** (`siti`) — female · indonesian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/siti.mp3?v=3)

**Skylar** (`skylar`) — female · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/skylar.mp3?v=3)

**Sofia** (`sofia`) — female · italian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sofia.mp3?v=3)

**Søren** (`soren`) — male · danish accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/soren.mp3?v=3)

**Suresh** (`suresh`) — male · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/suresh.mp3?v=3)

**Taehyun** (`taehyun`) — male · korean accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/taehyun.mp3?v=3)

**Thijs** (`thijs`) — male · dutch accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/thijs.mp3?v=3)

**Vijay** (`vijay`) — male · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/vijay.mp3?v=3)

**Viktoria** (`viktoria`) — female · german accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/viktoria.mp3?v=3)

**Youssef** (`youssef`) — male · saudi accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/youssef.mp3?v=3)

**Yumiko** (`yumiko`) — female · japanese accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/yumiko.mp3?v=3)

## Find voices by language

Expand a language to see and play every voice that speaks it — each sample below is in that language.

<AccordionGroup>
<Accordion title="Arabic — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_ar.mp3?v=3)

**Huda** (`huda`) — female · saudi accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/huda_ar.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_ar.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_ar.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_ar.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_ar.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_ar.mp3?v=3)

**Youssef** (`youssef`) — male · saudi accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/youssef_ar.mp3?v=3)

</Accordion>
<Accordion title="Bengali — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_bn.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_bn.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_bn.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_bn.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_bn.mp3?v=3)

**Pooja** (`pooja`) — female · bangladeshi accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/pooja_bn.mp3?v=3)

**Rubel** (`rubel`) — male · bangladeshi accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/rubel_bn.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_bn.mp3?v=3)

</Accordion>
<Accordion title="Bulgarian — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_bg.mp3?v=3)

**Georgi** (`georgi`) — male · bulgarian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/georgi_bg.mp3?v=3)

**Ivana** (`ivana`) — female · bulgarian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/ivana_bg.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_bg.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_bg.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_bg.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_bg.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_bg.mp3?v=3)

</Accordion>
<Accordion title="Cantonese — 6 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_yue.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_yue.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_yue.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_yue.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_yue.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_yue.mp3?v=3)

</Accordion>
<Accordion title="Croatian — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_hr.mp3?v=3)

**Ivan** (`ivan`) — male · croatian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/ivan_hr.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_hr.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_hr.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_hr.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_hr.mp3?v=3)

**Petra** (`petra`) — female · croatian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/petra_hr.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_hr.mp3?v=3)

</Accordion>
<Accordion title="Czech — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_cs.mp3?v=3)

**Jan** (`jan`) — male · czech accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/jan_cs.mp3?v=3)

**Jana** (`jana`) — female · czech accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/jana_cs.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_cs.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_cs.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_cs.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_cs.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_cs.mp3?v=3)

</Accordion>
<Accordion title="Danish — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_da.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_da.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_da.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_da.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_da.mp3?v=3)

**Mette** (`mette`) — female · danish accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mette_da.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_da.mp3?v=3)

**Søren** (`soren`) — male · danish accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/soren_da.mp3?v=3)

</Accordion>
<Accordion title="Dutch — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_nl.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_nl.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_nl.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_nl.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_nl.mp3?v=3)

**Noa** (`noa`) — female · dutch accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/noa_nl.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_nl.mp3?v=3)

**Thijs** (`thijs`) — male · dutch accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/thijs_nl.mp3?v=3)

</Accordion>
<Accordion title="English — 50 voices">

**Alec** (`alec`) — male · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/alec_en.mp3?v=3)

**Ananya** (`ananya`) — female · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/ananya_en.mp3?v=3)

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_en.mp3?v=3)

**Archie** (`archie`) — male · british accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/archie_en.mp3?v=3)

**Arlo** (`arlo`) — male · australian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/arlo_en.mp3?v=3)

**Brandon** (`brandon`) — male · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/brandon_en.mp3?v=3)

**Bronte** (`bronte`) — female · australian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/bronte_en.mp3?v=3)

**Carlos** (`carlos`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/carlos_en.mp3?v=3)

**Caroline** (`caroline`) — female · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/caroline_en.mp3?v=3)

**Carson** (`carson`) — male · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/carson_en.mp3?v=3)

**Cathy** (`cathy`) — female · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/cathy_en.mp3?v=3)

**Charlotte** (`charlotte`) — female · british accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/charlotte_en.mp3?v=3)

**Daniel** (`daniel`) — male · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/daniel_en.mp3?v=3)

**Diego** (`diego`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/diego_en.mp3?v=3)

**Diya** (`diya`) — female · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/diya_en.mp3?v=3)

**Emily** (`emily`) — female · british accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/emily_en.mp3?v=3)

**Emma** (`emma`) — female · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/emma_en.mp3?v=3)

**Fraser** (`fraser`) — male · australian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/fraser_en.mp3?v=3)

**Gemma** (`gemma`) — female · british accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/gemma_en.mp3?v=3)

**Grace** (`grace`) — female · australian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/grace_en.mp3?v=3)

**Isabella** (`isabella`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/isabella_en.mp3?v=3)

**Isha** (`isha`) — female · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/isha_en.mp3?v=3)

**Jacqueline** (`jacqueline`) — female · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/jacqueline_en.mp3?v=3)

**Jake** (`jake`) — male · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/jake_en.mp3?v=3)

**James** (`james`) — male · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/james_en.mp3?v=3)

**Jameson** (`jameson`) — male · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/jameson_en.mp3?v=3)

**Jessica** (`jessica`) — female · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/jessica_en.mp3?v=3)

**Jessie** (`jessie`) — female · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/jessie_en.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_en.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_en.mp3?v=3)

**Katie** (`katie`) — female · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/katie_en.mp3?v=3)

**Kavya** (`kavya`) — female · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/kavya_en.mp3?v=3)

**Lauren** (`lauren`) — female · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/lauren_en.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_en.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_en.mp3?v=3)

**Megan** (`megan`) — female · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/megan_en.mp3?v=3)

**Michael** (`michael`) — male · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/michael_en.mp3?v=3)

**Nicole** (`nicole`) — female · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/nicole_en.mp3?v=3)

**Oliver** (`oliver`) — male · british accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/oliver_en.mp3?v=3)

**Olivia** (`olivia`) — female · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/olivia_en.mp3?v=3)

**Priya** (`priya`) — female · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/priya_en.mp3?v=3)

**Rachel** (`rachel`) — female · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/rachel_en.mp3?v=3)

**Riya** (`riya`) — female · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/riya_en.mp3?v=3)

**Ronald** (`ronald`) — male · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/ronald_en.mp3?v=3)

**Ryan** (`ryan`) — male · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/ryan_en.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_en.mp3?v=3)

**Skylar** (`skylar`) — female · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/skylar_en.mp3?v=3)

**Tyler** (`tyler`) — male · american accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/tyler_en.mp3?v=3)

**Valentina** (`valentina`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/valentina_en.mp3?v=3)

**William** (`william`) — male · british accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/william_en.mp3?v=3)

</Accordion>
<Accordion title="Estonian — 6 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_et.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_et.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_et.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_et.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_et.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_et.mp3?v=3)

</Accordion>
<Accordion title="Finnish — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_fi.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_fi.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_fi.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_fi.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_fi.mp3?v=3)

**Matti** (`matti`) — male · finnish accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/matti_fi.mp3?v=3)

**Milla** (`milla`) — female · finnish accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/milla_fi.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_fi.mp3?v=3)

</Accordion>
<Accordion title="French — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_fr.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_fr.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_fr.mp3?v=3)

**Marc** (`marc`) — male · canadian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/marc_fr.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_fr.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_fr.mp3?v=3)

**Pauline** (`pauline`) — female · french accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/pauline_fr.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_fr.mp3?v=3)

</Accordion>
<Accordion title="German — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_de.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_de.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_de.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_de.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_de.mp3?v=3)

**Nico** (`nico`) — male · german accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/nico_de.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_de.mp3?v=3)

**Viktoria** (`viktoria`) — female · german accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/viktoria_de.mp3?v=3)

</Accordion>
<Accordion title="Greek — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_el.mp3?v=3)

**Despina** (`despina`) — female · greek accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/despina_el.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_el.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_el.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_el.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_el.mp3?v=3)

**Nikos** (`nikos`) — male · greek accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/nikos_el.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_el.mp3?v=3)

</Accordion>
<Accordion title="Gujarati — 8 voices">

**Amit** (`amit`) — male · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/amit_gu.mp3?v=3)

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_gu.mp3?v=3)

**Isha** (`isha-gu`) — female · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/isha-gu_gu.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_gu.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_gu.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_gu.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_gu.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_gu.mp3?v=3)

</Accordion>
<Accordion title="Hebrew — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_he.mp3?v=3)

**Hila** (`hila`) — female · israeli accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/hila_he.mp3?v=3)

**Ido** (`ido`) — male · israeli accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/ido_he.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_he.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_he.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_he.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_he.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_he.mp3?v=3)

</Accordion>
<Accordion title="Hindi — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_hi.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_hi.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_hi.mp3?v=3)

**Kavita** (`kavita`) — female · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/kavita_hi.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_hi.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_hi.mp3?v=3)

**Rohan** (`rohan`) — male · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/rohan_hi.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_hi.mp3?v=3)

</Accordion>
<Accordion title="Hungarian — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_hu.mp3?v=3)

**Bence** (`bence`) — male · hungarian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/bence_hu.mp3?v=3)

**Eszter** (`eszter`) — female · hungarian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/eszter_hu.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_hu.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_hu.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_hu.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_hu.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_hu.mp3?v=3)

</Accordion>
<Accordion title="Indonesian — 8 voices">

**Andi** (`andi`) — male · indonesian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/andi_id.mp3?v=3)

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_id.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_id.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_id.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_id.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_id.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_id.mp3?v=3)

**Siti** (`siti`) — female · indonesian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/siti_id.mp3?v=3)

</Accordion>
<Accordion title="Italian — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_it.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_it.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_it.mp3?v=3)

**Marco** (`marco`) — male · italian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/marco_it.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_it.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_it.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_it.mp3?v=3)

**Sofia** (`sofia`) — female · italian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sofia_it.mp3?v=3)

</Accordion>
<Accordion title="Japanese — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_ja.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_ja.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_ja.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_ja.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_ja.mp3?v=3)

**Ren** (`ren`) — male · japanese accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/ren_ja.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_ja.mp3?v=3)

**Yumiko** (`yumiko`) — female · japanese accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/yumiko_ja.mp3?v=3)

</Accordion>
<Accordion title="Kannada — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_kn.mp3?v=3)

**Divya** (`divya`) — female · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/divya_kn.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_kn.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_kn.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_kn.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_kn.mp3?v=3)

**Prakash** (`prakash`) — male · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/prakash_kn.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_kn.mp3?v=3)

</Accordion>
<Accordion title="Korean — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_ko.mp3?v=3)

**Jiwoo** (`jiwoo`) — female · korean accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/jiwoo_ko.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_ko.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_ko.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_ko.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_ko.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_ko.mp3?v=3)

**Taehyun** (`taehyun`) — male · korean accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/taehyun_ko.mp3?v=3)

</Accordion>
<Accordion title="Latvian — 6 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_lv.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_lv.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_lv.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_lv.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_lv.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_lv.mp3?v=3)

</Accordion>
<Accordion title="Lithuanian — 6 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_lt.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_lt.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_lt.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_lt.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_lt.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_lt.mp3?v=3)

</Accordion>
<Accordion title="Malayalam — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_ml.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_ml.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_ml.mp3?v=3)

**Latha** (`latha`) — female · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/latha_ml.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_ml.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_ml.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_ml.mp3?v=3)

**Vijay** (`vijay`) — male · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/vijay_ml.mp3?v=3)

</Accordion>
<Accordion title="Mandarin — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_zh.mp3?v=3)

**Jianhao** (`jianhao`) — male · chinese accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/jianhao_zh.mp3?v=3)

**Jing** (`jing`) — female · chinese accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/jing_zh.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_zh.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_zh.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_zh.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_zh.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_zh.mp3?v=3)

</Accordion>
<Accordion title="Marathi — 8 voices">

**Anika** (`anika`) — female · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anika_mr.mp3?v=3)

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_mr.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_mr.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_mr.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_mr.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_mr.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_mr.mp3?v=3)

**Suresh** (`suresh`) — male · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/suresh_mr.mp3?v=3)

</Accordion>
<Accordion title="Norwegian — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_nb.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_nb.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_nb.mp3?v=3)

**Kari** (`kari`) — female · norwegian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/kari_nb.mp3?v=3)

**Lars** (`lars`) — male · norwegian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/lars_nb.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_nb.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_nb.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_nb.mp3?v=3)

</Accordion>
<Accordion title="Polish — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_pl.mp3?v=3)

**Jakub** (`jakub`) — male · polish accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/jakub_pl.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_pl.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_pl.mp3?v=3)

**Kasia** (`kasia`) — female · polish accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/kasia_pl.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_pl.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_pl.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_pl.mp3?v=3)

</Accordion>
<Accordion title="Portuguese — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_pt.mp3?v=3)

**Bruno** (`bruno`) — male · brazilian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/bruno_pt.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_pt.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_pt.mp3?v=3)

**Larissa** (`larissa`) — female · brazilian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/larissa_pt.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_pt.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_pt.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_pt.mp3?v=3)

</Accordion>
<Accordion title="Punjabi — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_pa.mp3?v=3)

**Gurpreet** (`gurpreet`) — male · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/gurpreet_pa.mp3?v=3)

**Jaspreet** (`jaspreet`) — female · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/jaspreet_pa.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_pa.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_pa.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_pa.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_pa.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_pa.mp3?v=3)

</Accordion>
<Accordion title="Romanian — 8 voices">

**Andrada** (`andrada`) — female · moldovan accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/andrada_ro.mp3?v=3)

**Andrei** (`andrei`) — male · moldovan accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/andrei_ro.mp3?v=3)

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_ro.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_ro.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_ro.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_ro.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_ro.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_ro.mp3?v=3)

</Accordion>
<Accordion title="Russian — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_ru.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_ru.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_ru.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_ru.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_ru.mp3?v=3)

**Natalya** (`natalya`) — female · russian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/natalya_ru.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_ru.mp3?v=3)

**Sergei** (`sergei`) — male · russian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sergei_ru.mp3?v=3)

</Accordion>
<Accordion title="Serbian — 6 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_sr.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_sr.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_sr.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_sr.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_sr.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_sr.mp3?v=3)

</Accordion>
<Accordion title="Slovak — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_sk.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_sk.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_sk.mp3?v=3)

**Katarina** (`katarina`) — female · slovak accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/katarina_sk.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_sk.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_sk.mp3?v=3)

**Peter** (`peter`) — male · slovak accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/peter_sk.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_sk.mp3?v=3)

</Accordion>
<Accordion title="Slovenian — 6 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_sl.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_sl.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_sl.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_sl.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_sl.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_sl.mp3?v=3)

</Accordion>
<Accordion title="Spanish — 12 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_es.mp3?v=3)

**Carlos** (`carlos`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/carlos_es.mp3?v=3)

**Diego** (`diego`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/diego_es.mp3?v=3)

**Isabella** (`isabella`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/isabella_es.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_es.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_es.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_es.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_es.mp3?v=3)

**Marta** (`marta`) — female · castilian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/marta_es.mp3?v=3)

**Rodrigo** (`rodrigo`) — male · mexican accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/rodrigo_es.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_es.mp3?v=3)

**Valentina** (`valentina`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/valentina_es.mp3?v=3)

</Accordion>
<Accordion title="Swahili — 6 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_sw.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_sw.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_sw.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_sw.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_sw.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_sw.mp3?v=3)

</Accordion>
<Accordion title="Swedish — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_sv.mp3?v=3)

**Ingrid** (`ingrid`) — female · swedish accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/ingrid_sv.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_sv.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_sv.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_sv.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_sv.mp3?v=3)

**Nils** (`nils`) — male · swedish accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/nils_sv.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_sv.mp3?v=3)

</Accordion>
<Accordion title="Tamil — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_ta.mp3?v=3)

**Arun** (`arun`) — male · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/arun_ta.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_ta.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_ta.mp3?v=3)

**Kavitha** (`kavitha`) — female · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/kavitha_ta.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_ta.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_ta.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_ta.mp3?v=3)

</Accordion>
<Accordion title="Telugu — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_te.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_te.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_te.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_te.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_te.mp3?v=3)

**Pavan** (`pavan`) — male · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/pavan_te.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_te.mp3?v=3)

**Sindhu** (`sindhu`) — female · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sindhu_te.mp3?v=3)

</Accordion>
<Accordion title="Thai — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_th.mp3?v=3)

**Chakrit** (`chakrit`) — male · thai accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/chakrit_th.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_th.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_th.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_th.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_th.mp3?v=3)

**Narin** (`narin`) — female · thai accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/narin_th.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_th.mp3?v=3)

</Accordion>
<Accordion title="Turkish — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_tr.mp3?v=3)

**Aylin** (`aylin`) — female · turkish accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/aylin_tr.mp3?v=3)

**Emre** (`emre`) — male · turkish accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/emre_tr.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_tr.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_tr.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_tr.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_tr.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_tr.mp3?v=3)

</Accordion>
<Accordion title="Ukrainian — 7 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_uk.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_uk.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_uk.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_uk.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_uk.mp3?v=3)

**Oleh** (`oleh`) — male · ukrainian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/oleh_uk.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_uk.mp3?v=3)

</Accordion>
<Accordion title="Urdu — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_ur.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_ur.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_ur.mp3?v=3)

**Kavita** (`kavita-ur`) — female · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/kavita-ur_ur.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_ur.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_ur.mp3?v=3)

**Rohan** (`rohan-ur`) — male · indian accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/rohan-ur_ur.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_ur.mp3?v=3)

</Accordion>
<Accordion title="Vietnamese — 8 voices">

**Anna** (`anna`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/anna_vi.mp3?v=3)

**John** (`john`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/john_vi.mp3?v=3)

**Julia** (`julia`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/julia_vi.mp3?v=3)

**Lien** (`lien`) — female · vietnamese accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/lien_vi.mp3?v=3)

**Maria** (`maria`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/maria_vi.mp3?v=3)

**Mark** (`mark`) — male [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/mark_vi.mp3?v=3)

**Minh** (`minh`) — male · vietnamese accent [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/minh_vi.mp3?v=3)

**Sarah** (`sarah`) — female [▶](https://stthunderphoneprod.z19.web.core.windows.net/voice-samples/sarah_vi.mp3?v=3)

</Accordion>
</AccordionGroup>

## ElevenLabs voices

Voices from ElevenLabs, under ElevenLabs' own names, on the Eleven v4 Turbo
model. Each one speaks every language above. Set one as
`elevenlabs:<voice_id>`. On the [new pricing](/guides/pricing) there is no
voice surcharge: the voice is billed at ElevenLabs' list price inside the call.
Accounts still on their earlier pricing pay a per-minute surcharge in every
language until December 1, 2026. They are not HIPAA eligible yet. See
[ElevenLabs voices](/api-reference/agents#elevenlabs-voices) for pricing and
the PHI rules.

<AccordionGroup>
<Accordion title="All 563 ElevenLabs voices">

**A Top Narrator VO PRO** (`elevenlabs:u4HtmbcjVZVpiJLQ2GZn`) — male · middle&#95;aged · american accent [▶](https://api.us.elevenlabs.io/v1/voices/u4HtmbcjVZVpiJLQ2GZn/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiI2Y2NhYzZmZGY4YzI0NzE5OTU4Y2Q1ZDMyNDZjZmRkYSIsImZpbGVuYW1lIjoiQnZwbDFsWUgyZmhTT1RQS0FPWVUubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Aadhira** (`elevenlabs:QddF6FE7j4ZjMcrHQ2BK`) — female · young [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/QddF6FE7j4ZjMcrHQ2BK/aammbduJMuQTOoNGuTfs.mp3)

**Aaditya** (`elevenlabs:xMagNCpMgZ83QOEsHNre`) — male · middle&#95;aged · indian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/514d94e9241c48e8b7905375729c436f/voices/xMagNCpMgZ83QOEsHNre/yI9vXkproqDv7JIC5nRG.mp3)

**Achieng** (`elevenlabs:77qZTQGw9X7YWOVS6AQQ`) — female · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/77qZTQGw9X7YWOVS6AQQ/a3LUlR5MdxmNzUGuTXtU.mp3)

**Adam** (`elevenlabs:2ST3sI2j7fz4A5oXjnbA`) — male · young · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/2ST3sI2j7fz4A5oXjnbA/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiSDI0WG9vZGxXQk82bEtibFNVN3NtNDQxODBEMiIsImZpbGVuYW1lIjoiYTMwYzVmZWYtZTk2MC00OWQ1LWI4N2EtNTk0MDY5YWM1NGIwLm1wMyIsInRpbWVzdGFtcCI6MTc5MjE4MDgwMDAwMDAwMH0%3D)

**Adam** (`elevenlabs:6FiCmD8eY5VyjOdG5Zjk`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/41e6e19dba0f443c9da914bdbaf41559/voices/6FiCmD8eY5VyjOdG5Zjk/ALUjOcvKvAtbiWxYDXTM.mp3)

**Adam** (`elevenlabs:J17lijyP1BHYcM7ld0Rg`) — male · middle&#95;aged · istanbul accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/1UaUJJmHzOdvXFUVPp0tkvaI8a22/voices/J17lijyP1BHYcM7ld0Rg/ca75ee98-27b0-49e2-8f11-13b2e8dd01ee.mp3)

**Adam** (`elevenlabs:bfGb7JTLUnZebZRiFYyq`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/b3709ae8839847b6a804736de5e5651c/voices/bfGb7JTLUnZebZRiFYyq/sQiMNu3kolXvAQGhCb2s.mp3)

**Adam** (`elevenlabs:hIssydxXZ1WuDorjx6Ic`) — male · middle&#95;aged · mazovian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/OL55YKALeab7lyIfDKwe0l2b1bR2/voices/hIssydxXZ1WuDorjx6Ic/kNa9LiskFM0zlZprIFgg.mp3)

**Adam** (`elevenlabs:s3TPKV1kjDlVtZbl4Ksh`) — male · young · american accent [▶](https://api.us.elevenlabs.io/v1/voices/s3TPKV1kjDlVtZbl4Ksh/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoidTdFaWQ3ZVVucVBJVWdMTHBLbGs3V3dSUU5PMiIsImZpbGVuYW1lIjoibGpLNlpvSzJPT1RSOGtYSjhBcnAubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Adam** (`elevenlabs:uYFJyGaibp4N2VwYQshk`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/ZpYbCaSd2uMVjSr1tTgZPFLl0J92/voices/uYFJyGaibp4N2VwYQshk/P9QQG2a62C0lhe2HlcbL.mp3)

**Adam** (`elevenlabs:wBXNqKUATyqu0RtYt25i`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1b0aef06ad1848988df4847a8d377baf/voices/wBXNqKUATyqu0RtYt25i/92f83238-5f85-4793-ba6b-dc2cdc482735.mp3)

**Adam Composer** (`elevenlabs:x0u3EW21dbrORJzOq1m9`) — male · middle&#95;aged · stockholm accent [▶](https://storage.googleapis.com/eleven-public-prod/Clk6kdJ10yNzb14pOOqXKi1y5qW2/voices/x0u3EW21dbrORJzOq1m9/ffda0752-26f1-4341-8f31-161771679941.mp3)

**Adam Li** (`elevenlabs:hZTuv9Zqrq4yHYrEmF1r`) — male · middle&#95;aged · singapore mandarin accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/quDcGrthgkcACCa12rwG8Xzyp5Q2/voices/hZTuv9Zqrq4yHYrEmF1r/MReL0fdboS5j8sjxEN0K.mp3)

**Adam Stone** (`elevenlabs:NFG5qt843uXKj4pFvR7C`) — male · middle&#95;aged · british accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/NFG5qt843uXKj4pFvR7C/BgPFcmyMBm88O9O05Myn.mp3)

**Adam Stone** (`elevenlabs:auq43ws1oslv0tO4BDa7`) — male · middle&#95;aged · british accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/74WWwFTBRYdFoKb23bK1dZhdsd82/voices/auq43ws1oslv0tO4BDa7/o6onl5WGrtfowgYVv5xd.mp3)

**Adnan** (`elevenlabs:FXFcxnjikw0naYO1PPrU`) — male · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/9d161a9ddf144dd08b59c7c0bd25c0f1/voices/FXFcxnjikw0naYO1PPrU/eDFCKwcEyyQGhcRdt8Mm.mp3)

**Aisiri** (`elevenlabs:1yebI4wPatIbQgkzinlP`) — female · middle&#95;aged [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/1yebI4wPatIbQgkzinlP/KQIkBk7S6L95uIPljuCs.mp3)

**Aisiri** (`elevenlabs:2SDH0owxS12R2YMgMNoG`) — female · middle&#95;aged [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/2SDH0owxS12R2YMgMNoG/RbaLbKw0aVnDopys2kGb.mp3)

**Alberto Rodríguez** (`elevenlabs:l1zE9xgNpUTaQCZzpNJa`) — male · middle&#95;aged · latin american accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/l1zE9xgNpUTaQCZzpNJa/sF0SJSVjERJtMSqfZLPN.mp3)

**Alejandro** (`elevenlabs:sDh3eviBhiuHKi0MjTNq`) — male · middle&#95;aged · mexican accent [▶](https://api.us.elevenlabs.io/v1/voices/sDh3eviBhiuHKi0MjTNq/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJkNWZmODRiN2JlMjk0OTM0OGVkYThmMzEyZDA3ZDQ3ZiIsImZpbGVuYW1lIjoiU3hzbnFUeUlNYmMzR0lCSDJtMzUubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Aleksandra** (`elevenlabs:8EWWaNTDrqObI22Gvo1q`) — female · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/YeFg2N6d27bPgQf4AOzoxqV8Uuz2/voices/8EWWaNTDrqObI22Gvo1q/qz165onZi8sM5COPsLzY.mp3)

**Alex** (`elevenlabs:H5xTcsAIeS5RAykjz57a`) — male · middle&#95;aged · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/H5xTcsAIeS5RAykjz57a/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiT0w1NVlLQUxlYWI3bHlJZkRLd2UwbDJiMWJSMiIsImZpbGVuYW1lIjoiOGZlNGJhNDctZjEwNy00Yjc3LTk2MWMtZWYzYTNlOTM5OTU1Lm1wMyIsInRpbWVzdGFtcCI6MTc5MjE4MDgwMDAwMDAwMH0%3D)

**Alex Bell** (`elevenlabs:TUQNWEvVPBLzMBSVDPUA`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/44c8749f186847bdbd9d3528691abac4/voices/TUQNWEvVPBLzMBSVDPUA/UzWaQN5WUSe5p5VTm1Z5.mp3)

**Alex Nekrasov** (`elevenlabs:9Sj8ugvpK1DmcAXyvi3a`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/422ab51746234a479c3d767267557dd0/voices/9Sj8ugvpK1DmcAXyvi3a/2dCZWU3mjLdCIto8IEde.mp3)

**Alex Wright** (`elevenlabs:GzE4TcXfh9rYCU9gVgPp`) — male · middle&#95;aged · american accent [▶](https://api.us.elevenlabs.io/v1/voices/GzE4TcXfh9rYCU9gVgPp/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiWmZIUlBRdzhYTVE5cENtTXlqVFY5QmVYYk9wMSIsImZpbGVuYW1lIjoiblU3c01lSmZWTDl0ZmNGOVhudDUubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Alexander Kensington** (`elevenlabs:mZ8K1MPRiT5wDQaasg3i`) — male · middle&#95;aged · british accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/mZ8K1MPRiT5wDQaasg3i/GNSKBTqlsTNvS6jIiwHj.mp3)

**Alexandra** (`elevenlabs:kdmDKE6EkgrWrrykO9Qt`) — female · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1df4b21393b74964b03d3690a173eb80/voices/kdmDKE6EkgrWrrykO9Qt/yJT6XwhJHSWv3Pb05OIk.mp3)

**ALH** (`elevenlabs:vwuB7LB3p3SJ4QCWFIY7`) — female · middle&#95;aged · copenhagen accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/4ea572cd3f2c4409921870c205a8d675/voices/vwuB7LB3p3SJ4QCWFIY7/333f1af5-aa01-4de2-93a7-6c90fbe20356.mp3)

**Alisha** (`elevenlabs:ftDdhfYtmfGP0tFlBYA1`) — female · middle&#95;aged · indian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/514d94e9241c48e8b7905375729c436f/voices/ftDdhfYtmfGP0tFlBYA1/ij5PfYlZZeiriPm7LHrO.mp3)

**Allison** (`elevenlabs:Se2Vw1WbHmGbBbyWTuu4`) — female · young · british accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/Se2Vw1WbHmGbBbyWTuu4/3criMPMqBy1hVGIVhW2Q.mp3)

**Amanda** (`elevenlabs:F7hCTbeEDbm7osolS21j`) — female · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/pz6xtsH51FMXjmJXU0Jau9rgo253/voices/F7hCTbeEDbm7osolS21j/gZIBZuGsvZl2rxSqy3Y5.mp3)

**Amandoca** (`elevenlabs:r2fkFV8WAqXq2AqBpgJT`) — female · middle&#95;aged · brazilian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/bhxhV7JK9ENh5SdYnMwMtztTTQD2/voices/r2fkFV8WAqXq2AqBpgJT/e5f91486-26b6-48ee-b0a2-f0c4f7c344dd.mp3)

**Amelia** (`elevenlabs:ZF6FPAbjXT4488VcRRnw`) — female · young · british accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/ZF6FPAbjXT4488VcRRnw/PXswrdJcgsGr8VdoVA43.mp3)

**Amit** (`elevenlabs:uwHajH4FhtzVp6X17pr7`) — male · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/uwHajH4FhtzVp6X17pr7/uNnAXIfyJz5HoqUKjOEh.mp3)

**Ana** (`elevenlabs:XGfMwCpKmpWdTb1sermJ`) — female · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/XGfMwCpKmpWdTb1sermJ/VNaKGy7hqLkWhv4Hwxxw.mp3)

**Ana** (`elevenlabs:ee4SYVdD1aAhcjOJPZdt`) — female · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/ee4SYVdD1aAhcjOJPZdt/zbOiAxFg7j34F0Ce83Zt.mp3)

**Ana** (`elevenlabs:rCmVtv8cYU60uhlsOo1M`) — female · young · british accent [▶](https://storage.googleapis.com/eleven-public-prod/JSdwiNguB8ejxX5k1f64Z6aLdP73/voices/rCmVtv8cYU60uhlsOo1M/0aaceb14-b58e-4f25-9307-61a3edfef63e.mp3)

**Ana Maria** (`elevenlabs:urzoE6aZYmSRdFQ6215h`) — female · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/w3J9bYQwp1QAGGbllSCE43SpSVU2/voices/urzoE6aZYmSRdFQ6215h/23699e46-6ad3-471f-9b50-4f3e39cbf001.mp3)

**Ana Rita** (`elevenlabs:wJqPPQ618aTW29mptyoc`) — female · young · british accent [▶](https://storage.googleapis.com/eleven-public-prod/JSdwiNguB8ejxX5k1f64Z6aLdP73/voices/wJqPPQ618aTW29mptyoc/7f5d3985-6999-49c4-8c53-e0f43ef5a334.mp3)

**Ana SRB** (`elevenlabs:eWKPI657Btpf4xbqX4x6`) — female · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/802421b080714f9eb05103b34e2b55e2/voices/eWKPI657Btpf4xbqX4x6/223557e5-be95-4ca5-b358-c7f3618459dc.mp3)

**Anan** (`elevenlabs:tAV9ucNkXgK2k9TLxWkM`) — male · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/tAV9ucNkXgK2k9TLxWkM/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiIxZGEwNmVhNjc5YTU0OTc1YWQ5NmEyMjIxZmU2NTMwZCIsImZpbGVuYW1lIjoieXZpYWZJVnRtZ0MyTXVybzhXaUoubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Anca** (`elevenlabs:GRHbHyXbUO8nF4YexVTa`) — female · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/xcJacB134LeSMoZpu139fJzoZn73/voices/GRHbHyXbUO8nF4YexVTa/eBYSzFRj1SMs6UR14B4t.mp3)

**Andrea** (`elevenlabs:qHkrJuifPpn95wK3rm2A`) — female · young · latin american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/AUiOudcyrBgldqnAJhuGI9X0Ktn2/voices/qHkrJuifPpn95wK3rm2A/C0HIbK1Fqc9zwzlyvuTI.mp3)

**Andrea Wolff** (`elevenlabs:Crm8VULvkVs5ZBDa1Ixm`) — female · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/Crm8VULvkVs5ZBDa1Ixm/96l03fvHTt0ajBeL4Bgb.mp3)

**Andrej** (`elevenlabs:bYqmvVkXUBwLwYpGHGz3`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/nhzejzhpgsgVFjfm647xakUeR0u2/voices/bYqmvVkXUBwLwYpGHGz3/7zw88eoPx7M0amQdujCP.mp3)

**Andrew** (`elevenlabs:gUABw7pXQjhjt0kNFBTF`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/eR8GN1SLARV1SsZrwn2eoVNdIwg2/voices/gUABw7pXQjhjt0kNFBTF/f5776657-1bda-4fa8-8170-65d3164d02e7.mp3)

**Andrew Griffin** (`elevenlabs:SF9uvIlY93SJRMdV5jeP`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/4567cb2d224245f8b853c0d5e2fd8728/voices/SF9uvIlY93SJRMdV5jeP/242a626d-6d37-4f88-956f-e9c8abcbec5f.mp3)

**Andrew McBeard** (`elevenlabs:hMTrLL2ZiyJiyKrdg2z4`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/a443a1317cf94f65bd8860ba6fef56ad/voices/hMTrLL2ZiyJiyKrdg2z4/5OebBL0UCDqMnYHdQhx9.mp3)

**Andy** (`elevenlabs:DLMxnwJE0a28JQLTMJPJ`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/3460863a5df6464a8fb3cdb9fcd15f89/voices/DLMxnwJE0a28JQLTMJPJ/56rS6pnxmvGBfreMFOr3.mp3)

**Angela** (`elevenlabs:FUfBrNit0NNZAwb58KWH`) — female · middle&#95;aged · american accent [▶](https://api.us.elevenlabs.io/v1/voices/FUfBrNit0NNZAwb58KWH/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJmM2QyNGEzM2NjNWI0ZTgxYTU2MWUzMzJkZjI3ZDFmMSIsImZpbGVuYW1lIjoicVI5QmdKYkpnRnQwSW9vQUdEQngubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Anika** (`elevenlabs:90ipbRoKi4CpHXvKVtl0`) — female · young · indian accent [▶](https://api.us.elevenlabs.io/v1/voices/90ipbRoKi4CpHXvKVtl0/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiI1MTRkOTRlOTI0MWM0OGU4Yjc5MDUzNzU3MjljNDM2ZiIsImZpbGVuYW1lIjoiUkhqdjRQelE4cFRndVVrMWRjTzUubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Anna Kim** (`elevenlabs:uyVNoMrnUku1dZyVEXwD`) — female · young · seoul accent [▶](https://api.us.elevenlabs.io/v1/voices/uyVNoMrnUku1dZyVEXwD/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiI4ODI1YjIzN2U5MmI0YzBjOWFiZjEyMmI5ZDRhODg5NCIsImZpbGVuYW1lIjoiZEE4eFVhMVRERE10ZU1iZ1ZCODgubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Anna Stepanenko** (`elevenlabs:2o2uQnlGaNuV3ObRpxXt`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/Y8vypQsPx3WsqkhmF1egKEBswCV2/voices/2o2uQnlGaNuV3ObRpxXt/BPwgxhh214i0fQmkiTMc.mp3)

**Anna Su** (`elevenlabs:9lHjugDhwqoxA5MhX0az`) — female · young · taiwan mandarin accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/iWxuY2XaYrWRf6GQxIUY2M0J0gJ3/voices/9lHjugDhwqoxA5MhX0az/55SoO0ERY953JPIuC271.mp3)

**Anna Su** (`elevenlabs:r6qgCCGI7RWKXCagm158`) — female · young · taiwan mandarin accent [▶](https://api.us.elevenlabs.io/v1/voices/r6qgCCGI7RWKXCagm158/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiaVd4dVkyWGFZcldSZjZHUXhJVVkyTTBKMGdKMyIsImZpbGVuYW1lIjoiajBTcDZUcTBOanAzOEh4Q0ZBbVkubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Anneli** (`elevenlabs:2sIfP2CLuKcWEgQqZBvh`) — female · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/2sIfP2CLuKcWEgQqZBvh/LOzMf3pAvpIQ8QO0gqne.mp3)

**Annie** (`elevenlabs:a2RZfOPKpyNO38vDv3DD`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/Nwn2wV6asWcmpAiLdI1YPgnnkJH2/voices/a2RZfOPKpyNO38vDv3DD/GxOemTuA4J9cWq6Zzels.mp3)

**Annie K** (`elevenlabs:XW70ikSsadUbinwLMZ5w`) — female · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/d919f501def841d688c8fe932a668ff6/voices/XW70ikSsadUbinwLMZ5w/qiHz4qkrY2iq3OYxmLnX.mp3)

**Annika** (`elevenlabs:ViKqgJNeCiWZlYgHiAOO`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/odbqMoxkrXdDMV3GNWPPwDac98L2/voices/ViKqgJNeCiWZlYgHiAOO/5b56dd42-a14f-4449-a6ff-39b9976eb731.mp3)

**Antonia** (`elevenlabs:3z9q8Y7plHbvhDZehEII`) — female · young [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/3z9q8Y7plHbvhDZehEII/RizL5Q4u5cwB0Qrp02so.mp3)

**Anya** (`elevenlabs:d3MFdIuCfbAIwiu7jC4a`) — female · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/4430550a3eb64c68ba173948661a3b15/voices/d3MFdIuCfbAIwiu7jC4a/0B41hjwD7LUAkQdwtJk4.mp3)

**Archer** (`elevenlabs:Fahco4VZzobUeiPqni1S`) — male · middle&#95;aged · british accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/H8fljyNoujV57QrTUGG0DCtAt4M2/voices/Fahco4VZzobUeiPqni1S/BYI5QD0F6odzbXe3n2Nl.mp3)

**Archer** (`elevenlabs:oQV06a7Gn8pbCJh5DXcO`) — male · middle&#95;aged · british accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/b74d906ca49b4cae8711d6f8e3ba2b67/voices/oQV06a7Gn8pbCJh5DXcO/TenLDz5xUyKyuZBh4enj.mp3)

**Arfa** (`elevenlabs:5WbDBNLwAg4h26Km0GgQ`) — female · young · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/5WbDBNLwAg4h26Km0GgQ/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJlZDliMDVlNjMyNGM0NTc2ODU0OTAzNTJlOWExZWM5MCIsImZpbGVuYW1lIjoiWjJ0SkFqaktKNFVHV3p0cFV1a1EubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Aria** (`elevenlabs:mRTQIE2xdk2oMdoKFGJu`) — female · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/f4d8a86dd9b947ffa2fa7ea7663426f9/voices/mRTQIE2xdk2oMdoKFGJu/45091bb1-9a64-4781-ad6d-8a7ecd2625d5.mp3)

**Armando** (`elevenlabs:TWUKKXAylkYxxlPe4gx0`) — male · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/TWUKKXAylkYxxlPe4gx0/oAJIYIEejJ5U8hAfWADq.mp3)

**Artem Klopotenko** (`elevenlabs:h9NSQvWZaC4NFusYsxT9`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/Jzkh6pLqc9fCLQbd1jVbl97XRT12/voices/h9NSQvWZaC4NFusYsxT9/1PFHddx4cvKqvTAjig2W.mp3)

**Arthur** (`elevenlabs:C1npRmjB19a6yNkEucvx`) — male · middle&#95;aged · american accent [▶](https://api.us.elevenlabs.io/v1/voices/C1npRmjB19a6yNkEucvx/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJlM2ZmYWYyNzBhOTc0ZjExYWQ4YzFlYTkyNzEzOTBhYSIsImZpbGVuYW1lIjoiRUV3VHhpbUJ2SXNTMUxDdmxmS1UubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Arunika** (`elevenlabs:o5s6XRBkPSTD4syv6mZg`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/393648e246bd4c77b26e4e82743a7ad4/voices/o5s6XRBkPSTD4syv6mZg/zWyDjq8hD7sLKmO3lKFg.mp3)

**Ash** (`elevenlabs:ug7mg45jVbzgYHpQBrw5`) — female · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/4n1KuhIZ85S6WouZiwAfsak0V0I3/voices/ug7mg45jVbzgYHpQBrw5/f140fa41-c21a-485c-ab8d-3e756fde5945.mp3)

**Ashwat** (`elevenlabs:1JOQMQINvsOLiEu2pZFd`) — male · young · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/1JOQMQINvsOLiEu2pZFd/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJlZDliMDVlNjMyNGM0NTc2ODU0OTAzNTJlOWExZWM5MCIsImZpbGVuYW1lIjoiOFRFZUhialMzZzVqbk4yRHNBSmcubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Astro** (`elevenlabs:B5vjwBxGgp4GLTiUjDxM`) — male · young · british accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/601992c59fd04a389af932ba6eff25c5/voices/B5vjwBxGgp4GLTiUjDxM/xALlVIafllagz4qTkvd8.mp3)

**Atlas** (`elevenlabs:ejJ1ETWS2ohLMMeCu1H3`) — male · old · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/cb2db20b3bd84f2682182b6822afb08c/voices/ejJ1ETWS2ohLMMeCu1H3/okRpOqtkQllhZvGcFQ3g.mp3)

**Audrey** (`elevenlabs:McVZB9hVxVSk3Equu8EH`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/McVZB9hVxVSk3Equu8EH/fQOpiFrrNtzg6dglRCvf.mp3)

**Aurora** (`elevenlabs:YSabzCJMvEHDduIDMdwV`) — female · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/5849aab0fe5d41b6900406393e93407d/voices/YSabzCJMvEHDduIDMdwV/2kWo0RqG5nwi2Mc8dP23.mp3)

**Ausra** (`elevenlabs:7xYfOWNfkeGBgHlncd2C`) — female · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/7xYfOWNfkeGBgHlncd2C/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiIxZGEwNmVhNjc5YTU0OTc1YWQ5NmEyMjIxZmU2NTMwZCIsImZpbGVuYW1lIjoiWnN4emRra2ZCZFFjcThDZjBhdE0ubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Autumn Veil** (`elevenlabs:KoVIHoyLDrQyd4pGalbs`) — female · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/69d3064e4fe3401dafab9d6d95281003/voices/KoVIHoyLDrQyd4pGalbs/tjml8OPQnxcFs9bUmKAE.mp3)

**Ava** (`elevenlabs:AnvlJBAqSLDzEevYr9Ap`) — female · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/AnvlJBAqSLDzEevYr9Ap/WMSO4Wuwrzy81szsGlvY.mp3)

**Ava** (`elevenlabs:gJx1vCzNCD1EQHT212Ls`) — female · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/8rbGDvAxYshgeKWdI4OE6PHOtQT2/voices/gJx1vCzNCD1EQHT212Ls/1mP3gBL8hmAjLz1zFn8g.mp3)

**Ayesha** (`elevenlabs:xWRIcE4FuE8s9387uHX3`) — female · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/xWRIcE4FuE8s9387uHX3/2IYWvN8kIvsOU5fTFwUK.mp3)

**Baiba** (`elevenlabs:azBQdzUwIzEtXS9PGiGX`) — female · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/azBQdzUwIzEtXS9PGiGX/1818b791-a348-4ba4-8103-e74334636a15.mp3)

**Baraka** (`elevenlabs:90GgjYd3t15Qldd8eZuQ`) — male · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/90GgjYd3t15Qldd8eZuQ/1DmVaUcG1NISazaeRB1m.mp3)

**Beata** (`elevenlabs:W0sqKm1Sfw1EzlCH14FQ`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/1pTpZHj8GMOnZSDE9xYF7VVr6mA2/voices/W0sqKm1Sfw1EzlCH14FQ/7pIZ7hwKQGcJOgKi59Tj.mp3)

**Ben** (`elevenlabs:aTTiK3YzK3dXETpuDE2h`) — male · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/aTTiK3YzK3dXETpuDE2h/yyLoue2p52RyHoDlXIeU.mp3)

**Benjamin** (`elevenlabs:LruHrtVF6PSyGItzMNHS`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/LruHrtVF6PSyGItzMNHS/vhEqnmupM72x52dO30Dl.mp3)

**Bharadwaj** (`elevenlabs:RoLT1qx7XJRXxWSIG5hS`) — male · middle&#95;aged [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/RoLT1qx7XJRXxWSIG5hS/glOcHN7daLBwurcPxbBY.mp3)

**Bharadwaj** (`elevenlabs:ZP395Tqu6ul3fSRx4wAj`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/ZP395Tqu6ul3fSRx4wAj/RJXGnenfTRbQLGVyzrpl.mp3)

**Biju S** (`elevenlabs:FhOnCtjmaAIRIS1Dg2bk`) — male · middle&#95;aged [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/FhOnCtjmaAIRIS1Dg2bk/U26hD8kqnacmvTJIzOvJ.mp3)

**Bill L. Oxley** (`elevenlabs:iiidtqDt9FBdT1vfBluA`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/64971298bfc24086b69026970a21f1f9/voices/iiidtqDt9FBdT1vfBluA/T36MtmAvwCajW33mBOpD.mp3)

**Bill Oxley** (`elevenlabs:T5cu6IU92Krx4mh43osx`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/64971298bfc24086b69026970a21f1f9/voices/T5cu6IU92Krx4mh43osx/t40HRPMEFLWl6H3QtS4k.mp3)

**Bin** (`elevenlabs:jB1Cifc2UQbq1gR3wnb0`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/hSWXaUomcSNh92DBdVimNedwBFB2/voices/jB1Cifc2UQbq1gR3wnb0/886e42f2-9973-476a-aa1f-f348f46d35a3.mp3)

**Binod** (`elevenlabs:iuABfyf7pRoBzuPqzUCt`) — male · young [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/iuABfyf7pRoBzuPqzUCt/gb2e7tMwvalHF0gRO42o.mp3)

**Bogdan** (`elevenlabs:5asM3ZxsegvXfXI5vqKQ`) — male · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/2fE1hRuXFjUFllADtpFlaNnqZCv2/voices/5asM3ZxsegvXfXI5vqKQ/WlshpjGzAl8BOGDEE6Qg.mp3)

**Bogdan** (`elevenlabs:jn6ifzU1eO5tfUZ2ZJVg`) — male · old · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/SWpfSBMFk8RnRE7OgOkgZXoBbOD2/voices/jn6ifzU1eO5tfUZ2ZJVg/dwThNtKnoihElXMqWhAb.mp3)

**Bradford** (`elevenlabs:NNl6r8mD7vthiJatiJt1`) — male · middle&#95;aged · british accent [▶](https://api.us.elevenlabs.io/v1/voices/NNl6r8mD7vthiJatiJt1/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiQ0VaWHhmZENmRWZ5WEQ3eVVOS0lQY3VDS2FCMyIsImZpbGVuYW1lIjoiNmFkY2E0ZTItMGJjMS00ZWNlLWFjMDItZmYwYmNlYWM5YzM2Lm1wMyIsInRpbWVzdGFtcCI6MTc5MjE4MDgwMDAwMDAwMH0%3D)

**Bradley** (`elevenlabs:RexqLjNzkCjWogguKyff`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/RexqLjNzkCjWogguKyff/bKmlc9TbcKuu6w1w1jmF.mp3)

**Bram** (`elevenlabs:X8n8hOy3e8VLQnHTUcc5`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/543bccd98907452ca7ffabfb5da310e3/voices/X8n8hOy3e8VLQnHTUcc5/QdwfLypUbLnIFkfVR7Lb.mp3)

**Brian** (`elevenlabs:Gubgw9l4dtIoQA9YZHgx`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/bb3de32d375e4462a5d1aebc77eb7b0a/voices/Gubgw9l4dtIoQA9YZHgx/0tEqW9hX1QsyouhvnTSQ.mp3)

**Brian** (`elevenlabs:UGTtbzgh3HObxRjWaSpr`) — male · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/apwq4yNNEQathkG8MvDaLwdw7Ig1/voices/UGTtbzgh3HObxRjWaSpr/aJzOasSiI8jIztqGAKHL.mp3)

**Brielle** (`elevenlabs:6u6JbqKdaQy89ENzLSju`) — female · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/UtY8SzQcynWj6pnllKYZlJLRAaI3/voices/6u6JbqKdaQy89ENzLSju/3xgkujlukdHHhcsdsQsY.mp3)

**Bunty** (`elevenlabs:FZkK3TvQ0pjyDmT8fzIW`) — male · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/FZkK3TvQ0pjyDmT8fzIW/k39glMGS9gSdJLHIaJ4K.mp3)

**Burcu Basyigit** (`elevenlabs:DqkEc6nlvKNIUjWfMgVg`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/cFxewCdSbyPkKa9zWzYSo9T1aKu2/voices/DqkEc6nlvKNIUjWfMgVg/52bd8108-b0b4-4a9a-ac53-fc80e7e4be3d.mp3)

**Burt** (`elevenlabs:kdVjFjOXaqExaDvXZECX`) — male · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/OgMJiVAehyeaRuNnrBxSovksRX13/voices/kdVjFjOXaqExaDvXZECX/lDFq3oGBLoiv7q4QyPrd.mp3)

**Burt Reynolds™** (`elevenlabs:4YYIPFl9wE5c4L2eu2Gb`) — male · middle&#95;aged · american accent [▶](https://api.us.elevenlabs.io/v1/voices/4YYIPFl9wE5c4L2eu2Gb/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJmY2FiYWE3Nzc0ZDI0ZGEyOGZlOGI1NmIzZjliNDgwOSIsImZpbGVuYW1lIjoibUpWZzJsVVo5OXNVZHNidGFYbG0ubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Cahaya** (`elevenlabs:iWydkXKoiVtvdn4vLKp9`) — female · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/a0fbabfcbadb466d99065322c43dcb4c/voices/iWydkXKoiVtvdn4vLKp9/DZBbt6Ct6WxuyseL9Cn4.mp3)

**Callie** (`elevenlabs:7YaUDeaStRuoYg3FKsmU`) — female · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/4430550a3eb64c68ba173948661a3b15/voices/7YaUDeaStRuoYg3FKsmU/Q1P5AtU8XIR15XqBsxKN.mp3)

**Carmelo La Rosa** (`elevenlabs:HuK8QKF35exsCh2e7fLT`) — male · middle&#95;aged · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/HuK8QKF35exsCh2e7fLT/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiI5ZjUyMTlhOGI2OTU0NWM3YTVmMjk0OGJjMmU5ZTBlZiIsImZpbGVuYW1lIjoiVVY4ZkhuYW9BUlIzWTJwOGZHRksubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Carolina** (`elevenlabs:UOIqAnmS11Reiei1Ytkc`) — female · middle&#95;aged · peninsular accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/UOIqAnmS11Reiei1Ytkc/iD8yOai01ygsrjOUknQ3.mp3)

**Chai** (`elevenlabs:MeUerI8vM5Ce2GSTXsRT`) — male · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/MeUerI8vM5Ce2GSTXsRT/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiIxZGEwNmVhNjc5YTU0OTc1YWQ5NmEyMjIxZmU2NTMwZCIsImZpbGVuYW1lIjoiMEpyRFFQMVVCQ21vY0I1djBqWjkubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Chi Keung** (`elevenlabs:OfLR95P5vEUdQlgc0yWQ`) — male · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/OfLR95P5vEUdQlgc0yWQ/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiIxZGEwNmVhNjc5YTU0OTc1YWQ5NmEyMjIxZmU2NTMwZCIsImZpbGVuYW1lIjoiaHl3ZG91NGZMa0xFa2tqTGQ0cTEubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Chinmay** (`elevenlabs:3L29IUUN61xcyvsKscMy`) — male · middle&#95;aged [▶](https://api.us.elevenlabs.io/v1/voices/3L29IUUN61xcyvsKscMy/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJlZDliMDVlNjMyNGM0NTc2ODU0OTAzNTJlOWExZWM5MCIsImZpbGVuYW1lIjoiQ1ZqU3oxR2RaSFNwWHYxY3psRmsubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Chris** (`elevenlabs:PDoCXqBQFGsvfO0hNkEs`) — male · young · seoul accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/70d7b643ae574688b481ad2842214f21/voices/PDoCXqBQFGsvfO0hNkEs/HBkpkZhm2qtrGEs3SRyg.mp3)

**Christian** (`elevenlabs:6xPz2opT0y5qtoRh1U1Y`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/ideEvUQCAVRZz99Tr3IrRRUvriH2/voices/6xPz2opT0y5qtoRh1U1Y/24372a6d-c40d-485f-897a-a865ec9ecac1.mp3)

**Christina** (`elevenlabs:X03mvPuTfprif8QBAVeJ`) — female · middle&#95;aged · american accent [▶](https://api.us.elevenlabs.io/v1/voices/X03mvPuTfprif8QBAVeJ/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJlMTU2M2IzYjY1MDQ0NjY1YTEwNDlkZGYwYzExNGViNyIsImZpbGVuYW1lIjoiWFlkTWhRbHN5WEZBOUJwSW1rMGoubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Christopher** (`elevenlabs:G17SuINrv2H9FC6nvetn`) — male · middle&#95;aged · british accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/G17SuINrv2H9FC6nvetn/ofEmJDtVvrmeL3OEs0ig.mp3)

**Chun Wai** (`elevenlabs:2HZgeWhEm3MJfPZ0MsrV`) — male · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/2HZgeWhEm3MJfPZ0MsrV/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiIxZGEwNmVhNjc5YTU0OTc1YWQ5NmEyMjIxZmU2NTMwZCIsImZpbGVuYW1lIjoiOERPOURKYVg1YWhvMmpzcTFqdUcubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Cindy** (`elevenlabs:vCHG6sKIqAbXWNNm5vpY`) — female · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/Qae9t2058ERclThfdUOrfukGEfW2/voices/vCHG6sKIqAbXWNNm5vpY/0b41e9cd-ede3-4b1c-b6ef-e73008b82860.mp3)

**Clara** (`elevenlabs:EIsgvJT3rwoPvRFG6c4n`) — female · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/jrR31yoCg2gTrsSiovAhocmGTi93/voices/EIsgvJT3rwoPvRFG6c4n/kC6KH8bRXrCUGSoTeB46.mp3)

**Clara** (`elevenlabs:Qggl4b0xRMiqOwhPtVWT`) — female · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/waW9Pe5Rj4OtyxqKFSKqrFI9Yu22/voices/Qggl4b0xRMiqOwhPtVWT/nadmzoPR09GCQyNWA8ie.mp3)

**Clara** (`elevenlabs:ZIlrSGI4jZqobxRKprJz`) — female · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/6ahwPSIefHg1kQaMGCN21WiW3HH2/voices/ZIlrSGI4jZqobxRKprJz/qiZRWpZZLIYcQdFcy5o3.mp3)

**Clyde** (`elevenlabs:wyWA56cQNU2KqUW4eCsI`) — male · middle&#95;aged · british accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/T05GPpk2fvSBb625DXd4BJHZtu22/voices/wyWA56cQNU2KqUW4eCsI/RNPfnL6pqQi9eI02rhnL.mp3)

**Corina Ioana** (`elevenlabs:gbLy9ep70G3JW53cTzFC`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/gbLy9ep70G3JW53cTzFC/ORZ4ycrJb2N6RvCCndYi.mp3)

**Cristina Campos** (`elevenlabs:CaJslL1xziwefCeTNzHv`) — female · young · latin american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/c093a158b7da4dadb8f9a5fae10b7211/voices/CaJslL1xziwefCeTNzHv/piQKkajjFXnelvIxcX33.mp3)

**Daisy Mae** (`elevenlabs:S2fYVrVpl5QYHVJ1LkgT`) — female · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/oWQsD2Edq4Y1CWjHr5P3zfBCVzP2/voices/S2fYVrVpl5QYHVJ1LkgT/e0f69299-13df-478a-8071-35726d70d88e.mp3)

**Dakocan** (`elevenlabs:plgKUYgnlZ1DCNh54DwJ`) — male · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/3eec0209b926438181358e9dff604f79/voices/plgKUYgnlZ1DCNh54DwJ/HejSq6IywpJ4DZNrJGpv.mp3)

**Dallin** (`elevenlabs:alFofuDn3cOwyoz1i44T`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/1D73t5OmWJcLCgnlSL28i2bB7Iq2/voices/alFofuDn3cOwyoz1i44T/f3121486-aa47-4540-9e8a-16a642ce77c2.mp3)

**Dan** (`elevenlabs:9F4C8ztpNUmXkdDDbz3J`) — male · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/oDQDaQK0SGT9AtdG8VDe17L4KjX2/voices/9F4C8ztpNUmXkdDDbz3J/4d3e2bc3-b9f8-4bf0-84b2-22e0c15102f6.mp3)

**Dana** (`elevenlabs:V0stpogHp8KBgdErUZbd`) — female · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/V0stpogHp8KBgdErUZbd/Mo2VPCfMO2tYayYknCol.mp3)

**Danielle** (`elevenlabs:FVQMzxJGPUBtfz1Azdoy`) — female · young · canadian accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/FVQMzxJGPUBtfz1Azdoy/gKVnL9faq7ZIq960uZMm.mp3)

**David** (`elevenlabs:M336tBVZHWWiWb4R54ui`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/6b8a385000d74357bb4d658bfdf301e0/voices/M336tBVZHWWiWb4R54ui/uxc8WAoUc3HLYjbOXuZL.mp3)

**David** (`elevenlabs:asDeXBMC8hUkhqqL7agO`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/asDeXBMC8hUkhqqL7agO/oftUfxeCwmNjYZPrWN3K.mp3)

**David Boles** (`elevenlabs:y1adqrqs4jNaANXsIZnD`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/y1adqrqs4jNaANXsIZnD/cOf5zQ2txsGoa0hTO3w2.mp3)

**David Castlemore** (`elevenlabs:XjLkpWUlnhS8i7gGz3lZ`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/T7bhqxLyENgRaSgfnqhPa6vPSID2/voices/XjLkpWUlnhS8i7gGz3lZ/2foqwf4lPNBPWW27H6du.mp3)

**Deb** (`elevenlabs:UVvx1ZKtcJQTxfaKdh06`) — male · young [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/UVvx1ZKtcJQTxfaKdh06/jfzFkJKlWQ7OzFVj6Bp1.mp3)

**Declan Sage** (`elevenlabs:kqVT88a5QfII1HNAEPTJ`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/5d6438deeb7d443ca0a6fc6309d5bb8a/voices/kqVT88a5QfII1HNAEPTJ/Hex3MZnpQ3dCbdgTkKyr.mp3)

**Denisa** (`elevenlabs:OAAjJsQDvpg3sVjiLgyl`) — female · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/7G095XVHsmgoCnhxJhLJeLZUzAR2/voices/OAAjJsQDvpg3sVjiLgyl/4cc64654-5542-4ff8-bfa7-67cf38c8c906.mp3)

**Dennis** (`elevenlabs:s2xtA7B2CTXPPlJzch1v`) — male · middle&#95;aged · oslo accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/kwDwvcboWlRU2ajtdjtXaJ7UZsa2/voices/s2xtA7B2CTXPPlJzch1v/YB9DE4weRg6BTei8hVZ5.mp3)

**Derya** (`elevenlabs:NNn9dv8zq2kUo7d3JSGG`) — female · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/db30946f80fe4cdd9d37842a1ac08f63/voices/NNn9dv8zq2kUo7d3JSGG/Kixe2AJlCEJ4SAgNXFnH.mp3)

**Dhruva S** (`elevenlabs:RmsECPYd2k7yLIMTl1cR`) — male · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/RmsECPYd2k7yLIMTl1cR/pNbQ2LVB6INNTmBxKgha.mp3)

**Dhyogo Azevedo** (`elevenlabs:NGS0ZsC7j4t4dCWbPdgO`) — male · middle&#95;aged [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/NGS0ZsC7j4t4dCWbPdgO/D3DVRd6bPBxKuHsvILTg.mp3)

**Diane** (`elevenlabs:VdlAJiY20k9brfuVL9hQ`) — female · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/fb3dd3849a814695b693936d3ea2a952/voices/VdlAJiY20k9brfuVL9hQ/uX64vkO2Y7OtUIaIvddf.mp3)

**Diego** (`elevenlabs:rpNe0HOx7heUulPiOEaG`) — male · middle&#95;aged · brazilian accent [▶](https://storage.googleapis.com/eleven-public-prod/ExjJpOEYBjb2W5XCccFWBXpJ0pA3/voices/rpNe0HOx7heUulPiOEaG/69643e31-21f1-43c4-8c49-89da52b59157.mp3)

**Doga** (`elevenlabs:ctoYieZ4J7WwcdhujpMq`) — male · middle&#95;aged · istanbul accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/bd6a6321e92640508e2b718a1b5e23a8/voices/ctoYieZ4J7WwcdhujpMq/FElqJVaDhp8OF2A0veP6.mp3)

**Domantas** (`elevenlabs:ZHSr8S1YJobMLHO6EuTw`) — male · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/ZHSr8S1YJobMLHO6EuTw/OTpnPp6WDPaqTLYwgcJq.mp3)

**Donovan** (`elevenlabs:DMyrgzQFny3JI1Y1paM5`) — male · middle&#95;aged · american accent [▶](https://api.us.elevenlabs.io/v1/voices/DMyrgzQFny3JI1Y1paM5/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiVDA1R1BwazJmdlNCYjYyNURYZDRCSkhadHUyMiIsImZpbGVuYW1lIjoib3VZbHVmT2l5aFgwdkltYUZJZUUubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Drew** (`elevenlabs:q0IMILNRPxOgtBTS4taI`) — male · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/b2109416c7514449a5f06540d10f0e73/voices/q0IMILNRPxOgtBTS4taI/jKxasnssCutKQDSwe1bV.mp3)

**Duygu Eris** (`elevenlabs:MzfWWOj9g3sIKex1YFMV`) — female · young · istanbul accent [▶](https://api.us.elevenlabs.io/v1/voices/MzfWWOj9g3sIKex1YFMV/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiT0g0bkNCTlp0SVpqRVZoQlAwaVhFM1NyNXRCMiIsImZpbGVuYW1lIjoiYzViYjYzYTEtN2U5NC00ZDdkLThjYjItMWMwNTUxMWE4Y2YzLm1wMyIsInRpbWVzdGFtcCI6MTc5MjE4MDgwMDAwMDAwMH0%3D)

**Dylan** (`elevenlabs:F2kYsMGahtg8auErVXgY`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/p1RXf5gigAh7WUOGUtta2JxaFTi2/voices/F2kYsMGahtg8auErVXgY/43fc2374-9ef3-4c9f-b6db-4a3ffa98ad42.mp3)

**Egle** (`elevenlabs:neOkJCtTBu6UseSuVtwd`) — female · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/neOkJCtTBu6UseSuVtwd/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiIxZGEwNmVhNjc5YTU0OTc1YWQ5NmEyMjIxZmU2NTMwZCIsImZpbGVuYW1lIjoibE5GNTlCZzVwVENPWHNaT3g0enAubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Ekkarat** (`elevenlabs:H9eYlNHpm1vah6PPgYAk`) — male · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/H9eYlNHpm1vah6PPgYAk/tfh0m2cXqJy1zMtVJkQE.mp3)

**Elin** (`elevenlabs:4Ct5uMEndw4cJ7q0Jx0l`) — female · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/gzzlgU2eOCM4mGVeLO7E5zVABNH3/voices/4Ct5uMEndw4cJ7q0Jx0l/5c2e97c0-0656-47c7-8ed3-edb586056f26.mp3)

**Elise** (`elevenlabs:EST9Ui6982FZPSi7gCHi`) — female · young · american accent [▶](https://api.us.elevenlabs.io/v1/voices/EST9Ui6982FZPSi7gCHi/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiOHJiR0R2QXhZc2hnZUtXZEk0T0U2UEhPdFFUMiIsImZpbGVuYW1lIjoiaWlTa3NSRnpuelZ5cDYwdVlGT1oubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Elizabeth** (`elevenlabs:AXdMgz6evoL7OPd7eU12`) — female · middle&#95;aged · british accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/fbfCwCmqqJb68pPiOa0r5rXel952/voices/AXdMgz6evoL7OPd7eU12/uYgFNx0nabH45Qe0GHdO.mp3)

**Elizabeth** (`elevenlabs:zTQyc4NrQirk2Bu3ZOM7`) — female · young · sofia accent [▶](https://api.us.elevenlabs.io/v1/voices/zTQyc4NrQirk2Bu3ZOM7/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiIyNzQ0OGQwZjhjYjQ0MzMyOTgxYWQ4MmEzZDA2ZWJmOSIsImZpbGVuYW1lIjoiMGZkZjQ5ZjUtYzg5OC00ZWVhLTkwMmMtNGEwMjM4NGIwYWRkLm1wMyIsInRpbWVzdGFtcCI6MTc5MjE4MDgwMDAwMDAwMH0%3D)

**Ellen** (`elevenlabs:BIvP0GN1cAtSRTxNHnWS`) — female · young · german accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/XneWYDMsJGQ7Q0uqR5YiKixJmLn2/voices/BIvP0GN1cAtSRTxNHnWS/ZIkioQ15FEgRXe1XJXoG.mp3)

**Elza** (`elevenlabs:Xi5LaSIxpOwjOzRqTEG1`) — female · young · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/Xi5LaSIxpOwjOzRqTEG1/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiIxZGEwNmVhNjc5YTU0OTc1YWQ5NmEyMjIxZmU2NTMwZCIsImZpbGVuYW1lIjoiNDA4MTMxMjEtMjY5My00NWNiLTk4YzYtYWZiM2I5ODViNmIwLm1wMyIsInRpbWVzdGFtcCI6MTc5MjE4MDgwMDAwMDAwMH0%3D)

**Emma** (`elevenlabs:56bWURjYFHyYyVf490Dp`) — female · middle&#95;aged · australian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/9xPYXJTh5jOgHcAlNS36stwBz8E3/voices/56bWURjYFHyYyVf490Dp/wwX8nkhOs7XXZOoJz328.mp3)

**Emma** (`elevenlabs:OlBRrVAItyi00MuGMbna`) — female · young · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/OlBRrVAItyi00MuGMbna/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiN0V1Z0FRQ0pka09kZG1yNHVwNHFqcmJQcFM5MyIsImZpbGVuYW1lIjoiWTAwM0hKUGdqT3lIb3pDM3N6Z08ubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Emma** (`elevenlabs:b3jcIbyC3BSnaRu8avEk`) — female · young · bergen accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/OSbmAb1GKjNVlChP2UgZukCicWR2/voices/b3jcIbyC3BSnaRu8avEk/bZ5dFORSQeyFBQ7VAv9C.mp3)

**Emrullah Uzun** (`elevenlabs:DpEiQMnL9WxMsymCsjPY`) — male · middle&#95;aged · istanbul accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/75b8acd0ce6b4d0cb222f761cd5ae428/voices/DpEiQMnL9WxMsymCsjPY/wogNSOdxVsT7QIcvn0Fw.mp3)

**Erik** (`elevenlabs:EpYEY8MWJrUGskHBoNMA`) — male · middle&#95;aged · oslo accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/874d0ea9f5f04b44b5d2247b1354245a/voices/EpYEY8MWJrUGskHBoNMA/IwvVxe3iDUWUwD3eqAUP.mp3)

**Eryn** (`elevenlabs:DXFkLCBUTmvXpp2QwZjA`) — female · middle&#95;aged · american accent [▶](https://api.us.elevenlabs.io/v1/voices/DXFkLCBUTmvXpp2QwZjA/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiRGRVdDZsVkZmclVPU2lrSHJDYnMzdGVzTWdFMiIsImZpbGVuYW1lIjoiQlRmbm5VY1h5MHl6Q0xPemZMbngubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Eryn** (`elevenlabs:RaFzMbMIfqBcIurH6XF9`) — female · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/DXCrxxc55DZsEPNKieedZbV9YeB3/voices/RaFzMbMIfqBcIurH6XF9/6v6VQ7XdoZ5F7Mg1JIUk.mp3)

**Eryn** (`elevenlabs:kdnRe2koJdOK4Ovxn2DI`) — female · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/452adc21c9f74693918585d7ef4aa152/voices/kdnRe2koJdOK4Ovxn2DI/PHZPTflbygqpdJbgCqek.mp3)

**Eugene** (`elevenlabs:5DAtyqt3LGjv9jkjNVFd`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/BWIAlj31dDNny5DwqoZoNP8NyZl1/voices/5DAtyqt3LGjv9jkjNVFd/3ec27ae8-a1de-4f1d-bfdc-03e57437f429.mp3)

**Evan Zhao** (`elevenlabs:MI36FIkp9wRP7cpWKPTl`) — male · young · beijing mandarin accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/Z4YmgeFNh2To6n9dYoppEePJeMr1/voices/MI36FIkp9wRP7cpWKPTl/ZdfInoVLSM5izvMkRQFp.mp3)

**Eve** (`elevenlabs:BZgkqPqms7Kj9ulSkVzn`) — female · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/2fb5f7f22a174a62b41adac3b2c17856/voices/BZgkqPqms7Kj9ulSkVzn/XVC95XX3UKyM8DIfXORa.mp3)

**Evgeniy Shevchenko** (`elevenlabs:Ntd0iVwICtUtA6Fvx27M`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/0C5bUhgexLd2XXTbJno4O0594Yz1/voices/Ntd0iVwICtUtA6Fvx27M/etVdkbJAlgLzzPLOHWJc.mp3)

**Faiza** (`elevenlabs:8bTJQunXqF1x0VZwSUMs`) — female · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/8bTJQunXqF1x0VZwSUMs/xloMEpkGwlktzWtMP4VJ.mp3)

**Farah** (`elevenlabs:4wf10lgibMnboGJGCLrP`) — female · young · jordanian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/fb13b5efe4cb40d39da201b46fac22eb/voices/4wf10lgibMnboGJGCLrP/10Ff0P9ozKLVa4QSSIvC.mp3)

**Fernando Martínez** (`elevenlabs:dlGxemPxFMTY7iXagmOj`) — male · middle&#95;aged · latin american accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/dlGxemPxFMTY7iXagmOj/lQty6bCYbkLtTgnwqvDs.mp3)

**Filip** (`elevenlabs:YSnb83dlGetP8Umttfqs`) — male · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/YSnb83dlGetP8Umttfqs/4oeeBqzJJ6sNic2i8U4W.mp3)

**Flint** (`elevenlabs:qAZH0aMXY8tw1QufPN0D`) — male · old · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/759170f692da47489ba9c408ca661b39/voices/qAZH0aMXY8tw1QufPN0D/D9e9wQKrJ8hsb549LFpL.mp3)

**Freddy** (`elevenlabs:WYg5oajoUHxVa6ikQXec`) — male · middle&#95;aged · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/WYg5oajoUHxVa6ikQXec/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiZU1NMmZnbDB1YVlycGxXZkVmR3lJQTBiZU85MiIsImZpbGVuYW1lIjoiekx3S3M0c3c3TTRubUJZZHdPZlAubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Frederick Surrey** (`elevenlabs:j9jfwdrw7BRfcR43Qohk`) — male · middle&#95;aged · british accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/j9jfwdrw7BRfcR43Qohk/Vyj86dr4NJ1Tr82nEPdw.mp3)

**Freja** (`elevenlabs:h5TGSgjuArqhPBRRe0mM`) — female · middle&#95;aged · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/h5TGSgjuArqhPBRRe0mM/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiIxZGEwNmVhNjc5YTU0OTc1YWQ5NmEyMjIxZmU2NTMwZCIsImZpbGVuYW1lIjoiNzYxYmVkYmYtNTMxMC00ODU0LWJiMTYtOTY1YTAwMGM3MDVlLm1wMyIsInRpbWVzdGFtcCI6MTc5MjE4MDgwMDAwMDAwMH0%3D)

**Gabija** (`elevenlabs:jTPAKw6ldJPfYWDB1xXs`) — female · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/jTPAKw6ldJPfYWDB1xXs/bVPZvzB5C3BFIvC5Qq6v.mp3)

**Georgi** (`elevenlabs:31jwlwrRwpOA5yGuVAby`) — male · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/Mzpkm54OnTOrhvKd8T6mVBqGWwu1/voices/31jwlwrRwpOA5yGuVAby/shXNHhSvvGSdshOpKMMC.mp3)

**Georgi** (`elevenlabs:Ywe24jn5elUzaO9vm6vG`) — male · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/dac1b09d04624905964a6315bf13b8e4/voices/Ywe24jn5elUzaO9vm6vG/DC57WJZmcItfXvhSPkMY.mp3)

**Georgios** (`elevenlabs:TN3alZndDSA8GYZSOf3r`) — male · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/F0WCd2w4gZeoVqJoKb41FlCzVgC3/voices/TN3alZndDSA8GYZSOf3r/b64f3e87-1d93-4c13-8b50-7fdaecd40ec5.mp3)

**Giusy** (`elevenlabs:8KInRSd4DtD5L5gK7itu`) — female · middle&#95;aged · sicilian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/e2zT7dnENuXnz5SAZDyijTb0wVi2/voices/8KInRSd4DtD5L5gK7itu/xaChfKaUTDz90Q2amPgO.mp3)

**Guillaume** (`elevenlabs:Qrl71rx6Yg8RvyPYRGCQ`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/Qrl71rx6Yg8RvyPYRGCQ/buzH27F7AdN9DzU1N55C.mp3)

**Hale** (`elevenlabs:dXtC3XhB9GtPusIpNtQx`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/XWwWNeeRhJOfmltwxQgPxrxDmh02/voices/dXtC3XhB9GtPusIpNtQx/1edb5a1f-3169-4351-b850-22f30a915213.mp3)

**Hale** (`elevenlabs:wWWn96OtTHu1sn8SRGEr`) — male · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/1D73t5OmWJcLCgnlSL28i2bB7Iq2/voices/wWWn96OtTHu1sn8SRGEr/zpbMSgfLvQGwGB76UKKQ.mp3)

**Halima** (`elevenlabs:i5oE89JoUCpIgvSOemWx`) — female · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/i5oE89JoUCpIgvSOemWx/uKXrE83WKgPrsmwMkHhQ.mp3)

**Hanka** (`elevenlabs:12CHcREbuPdJY02VY7zT`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/EAn4Akpve4a1fpzrEtD4RmQFD093/voices/12CHcREbuPdJY02VY7zT/153e50e3-9031-4cd3-b264-02b5c5807605.mp3)

**Hanna** (`elevenlabs:NacdHGUYR1k3M0FAbAia`) — female · young · mazovian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/OL55YKALeab7lyIfDKwe0l2b1bR2/voices/NacdHGUYR1k3M0FAbAia/d10ba6a4-e6b5-4ee6-b604-f68b5c2baa76.mp3)

**Hannah** (`elevenlabs:M7ya1YbaeFaPXljg9BpK`) — female · young · australian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/7tvaSRybYYZ7ja2RTmrVkfJ75f93/voices/M7ya1YbaeFaPXljg9BpK/8Wc09F9557roFsMSjG9E.mp3)

**Hans Claesen** (`elevenlabs:s7Z6uboUuE4Nd8Q2nye6`) — male · middle&#95;aged · flemish accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/iQUwCsFoevSxLoIVdyCVsFQHEAJ3/voices/s7Z6uboUuE4Nd8Q2nye6/XR32RcQbL35zmXsczrLQ.mp3)

**Harleen** (`elevenlabs:dLBnQaUzg2TnaMnAjyrs`) — female · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/dLBnQaUzg2TnaMnAjyrs/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiIxZGEwNmVhNjc5YTU0OTc1YWQ5NmEyMjIxZmU2NTMwZCIsImZpbGVuYW1lIjoiUGFEc0VIUzg1ZDRGTzdiQ0lUQXcubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Harper 2.0** (`elevenlabs:QLAlOeRuLwKX0skeTR7R`) — female · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1df4b21393b74964b03d3690a173eb80/voices/QLAlOeRuLwKX0skeTR7R/zzt2ddvmzFhlIWjgiYjD.mp3)

**Hatake Kohei** (`elevenlabs:sRYzP8TwEiiqAWebdYPJ`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/9f98dd6e368e44c394c7c1727e879ae2/voices/sRYzP8TwEiiqAWebdYPJ/daa64a25-7790-488a-9f45-e7e59276ff27.mp3)

**Haytham** (`elevenlabs:IES4nrmZdUBHByLBde0P`) — male · middle&#95;aged · egyptian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/a2bfb04e0f004a808d30b9b123c4092f/voices/IES4nrmZdUBHByLBde0P/Y8RuRq66G8IOa64qczlV.mp3)

**Henry** (`elevenlabs:pVnrL6sighQX7hVz89cp`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/pVnrL6sighQX7hVz89cp/gcm5yRM3bqL34syZ72sF.mp3)

**Hetalben** (`elevenlabs:1wX3DrX9Q7x2fkeiljyg`) — female · young [▶](https://api.us.elevenlabs.io/v1/voices/1wX3DrX9Q7x2fkeiljyg/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJlZDliMDVlNjMyNGM0NTc2ODU0OTAzNTJlOWExZWM5MCIsImZpbGVuYW1lIjoiY0tyUEhGaFM1NVZuYUpMUVRaQlMubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Hey Its Brad** (`elevenlabs:Dslrhjl3ZpzrctukrQSN`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/b2109416c7514449a5f06540d10f0e73/voices/Dslrhjl3ZpzrctukrQSN/eHPz2AP83vzRF9cixck1.mp3)

**Hien** (`elevenlabs:jdlxsPOZOHdGEfcItXVu`) — female · middle&#95;aged · northern accent [▶](https://api.us.elevenlabs.io/v1/voices/jdlxsPOZOHdGEfcItXVu/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiMTdOWnpTYmQ5SVA4MmdqYnd3c2N3eW1kQ0lFMyIsImZpbGVuYW1lIjoiYlF0OHpzOVhLQmo5WjBYcWk5Sm8ubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Ho Yin** (`elevenlabs:Wtbd8FPC9737xkDKioyD`) — male · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/Wtbd8FPC9737xkDKioyD/OKxxI6bNvZ4vBtgxezWW.mp3)

**Hope** (`elevenlabs:OYTbf65OHHFELVut7v2H`) — female · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/sD92HnMHS9WZLXKNTKxmnC8XmJ32/voices/OYTbf65OHHFELVut7v2H/kTLS0DfvlR1QTyjUzOiT.mp3)

**Hope** (`elevenlabs:WAhoMTNdLdMoq1j3wf3I`) — female · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/sD92HnMHS9WZLXKNTKxmnC8XmJ32/voices/WAhoMTNdLdMoq1j3wf3I/OdHq2JoogTP6B2rbqeKz.mp3)

**Hope** (`elevenlabs:WZlYpi1yf6zJhNWXih74`) — female · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/sD92HnMHS9WZLXKNTKxmnC8XmJ32/voices/WZlYpi1yf6zJhNWXih74/s3SNMV6LwXSMvoHFgP48.mp3)

**Hope** (`elevenlabs:cVd39cx0VtXNC13y5Y7z`) — female · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/sD92HnMHS9WZLXKNTKxmnC8XmJ32/voices/cVd39cx0VtXNC13y5Y7z/ZmGEtFLzESmhA9TkCBUW.mp3)

**Hope** (`elevenlabs:iCrDUkL56s3C8sCRl7wb`) — female · young · american accent [▶](https://api.us.elevenlabs.io/v1/voices/iCrDUkL56s3C8sCRl7wb/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoic0Q5MkhuTUhTOVdaTFhLTlRLeG1uQzhYbUozMiIsImZpbGVuYW1lIjoiQ1l1N0pCTjN5bk9MeXNXMjljbHQubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Hope** (`elevenlabs:tnSpp4vdxKPjI9w0GnoV`) — female · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/tnSpp4vdxKPjI9w0GnoV/LiIyxRT1qFJ1QJPr8sWl.mp3)

**Hope** (`elevenlabs:uYXf8XasLslADfZ2MB4u`) — female · young · american accent [▶](https://api.us.elevenlabs.io/v1/voices/uYXf8XasLslADfZ2MB4u/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoic0Q5MkhuTUhTOVdaTFhLTlRLeG1uQzhYbUozMiIsImZpbGVuYW1lIjoiTTBVVGZORmlnSW5oejhMTWI0REEubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Hope** (`elevenlabs:zGjIP4SZlMnY9m93k97r`) — female · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/sD92HnMHS9WZLXKNTKxmnC8XmJ32/voices/zGjIP4SZlMnY9m93k97r/Who63aXv5rpUn6OHVgHv.mp3)

**Hugh** (`elevenlabs:2UMI2FME0FFUFMlUoRER`) — male · middle&#95;aged · british accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/8rbGDvAxYshgeKWdI4OE6PHOtQT2/voices/2UMI2FME0FFUFMlUoRER/HNhUIa0bNKflCqV9MBWg.mp3)

**Hyuk** (`elevenlabs:ZJCNdZEjYwkOElxugmW2`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/hSWXaUomcSNh92DBdVimNedwBFB2/voices/ZJCNdZEjYwkOElxugmW2/dOgEto9Z9e1UqrYhRSe0.mp3)

**Ian Cartwell** (`elevenlabs:e5WNhrdI30aXpS2RSGm1`) — male · middle&#95;aged · american accent [▶](https://api.us.elevenlabs.io/v1/voices/e5WNhrdI30aXpS2RSGm1/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiVDdiaHF4THlFTmdSYVNnZm5xaFBhNnZQU0lEMiIsImZpbGVuYW1lIjoiaXJaNlpUYkdWQTVXalZBd25aY0oubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Ido** (`elevenlabs:dLPO5AsXc3FZDbTh1IKa`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/jP3PwIUWe1P2evwWhH5wYYMIxde2/voices/dLPO5AsXc3FZDbTh1IKa/G2Dg9i8mYc6R6ier63Yi.mp3)

**Ilze** (`elevenlabs:4nP0MRk3S5Qj1fGfXf51`) — female · young · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/4nP0MRk3S5Qj1fGfXf51/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiIxZGEwNmVhNjc5YTU0OTc1YWQ5NmEyMjIxZmU2NTMwZCIsImZpbGVuYW1lIjoiMWMzMTdlMmYtMDUwOC00MTkyLWE1MzYtMzMzZjk3M2VkODhmLm1wMyIsInRpbWVzdGFtcCI6MTc5MjE4MDgwMDAwMDAwMH0%3D)

**Isabella** (`elevenlabs:gIfqD5jrnhkFu8ENVbXC`) — female · young · copenhagen accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/8c5980d0d9a84cbea374328578d2eb2e/voices/gIfqD5jrnhkFu8ENVbXC/bf9d265a-0bc9-418e-b659-f8b534b18495.mp3)

**Ishibashi** (`elevenlabs:Mv8AjrYZCBkdsmDHNwcB`) — male · young · kanto accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/smdM9RgSCIge9Dbjj1mxNOLqVtn1/voices/Mv8AjrYZCBkdsmDHNwcB/BzyYgIBOY4ecjGAkbfEJ.mp3)

**Ishvak** (`elevenlabs:LHMvGhXWZPfzCiDpiEc1`) — male · young [▶](https://api.us.elevenlabs.io/v1/voices/LHMvGhXWZPfzCiDpiEc1/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJlZDliMDVlNjMyNGM0NTc2ODU0OTAzNTJlOWExZWM5MCIsImZpbGVuYW1lIjoiZVNVU3NHQVo2dkNUa3ZOUUU0T0wubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Itai** (`elevenlabs:JIxTgeeS5w0UQyBxEnrl`) — male · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/JIxTgeeS5w0UQyBxEnrl/7za3GB1n0lALVe2bYQkU.mp3)

**Ivan** (`elevenlabs:j96cp162VcYdsYfSp1nc`) — male · middle&#95;aged [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/7ff1b234eed243f3903035c82ee087af/voices/j96cp162VcYdsYfSp1nc/rtADjcCgXD1CAWcYgdB0.mp3)

**Ivana** (`elevenlabs:JDYfAX20MbYfJGIjPTZz`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/520bd9f95097497390691939edf8591d/voices/JDYfAX20MbYfJGIjPTZz/a7409a1a-101e-4462-8d29-e53630f94518.mp3)

**Ivana** (`elevenlabs:WRDS9wgqjRDxow7GyX3w`) — female · middle&#95;aged · western accent [▶](https://api.us.elevenlabs.io/v1/voices/WRDS9wgqjRDxow7GyX3w/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJkMzdiNDNjYTA2NWI0Y2UwYWU4ZjYzOWM1MDA3YjNjOSIsImZpbGVuYW1lIjoiOWYxMmMxNjItYjNhNi00OWYzLWI0MGYtNTA4ZmU1MDUzZjMxLm1wMyIsInRpbWVzdGFtcCI6MTc5MjE4MDgwMDAwMDAwMH0%3D)

**Ivanna** (`elevenlabs:yM93hbw8Qtvdma2wCnJG`) — female · young · american accent [▶](https://api.us.elevenlabs.io/v1/voices/yM93hbw8Qtvdma2wCnJG/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiUGJLcTJpUjRPSWVoZXJBV2kyeEQzRUxLbGZlMiIsImZpbGVuYW1lIjoib01UbEJITUlPdURMd2NtN0kxdkoubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Ivy** (`elevenlabs:MClEFoImJXBTgLwdLI5n`) — female · young · american accent [▶](https://api.us.elevenlabs.io/v1/voices/MClEFoImJXBTgLwdLI5n/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiTUpZOG9wazFEUGM2d1lMZEhjMG1IN0hzR2V0MiIsImZpbGVuYW1lIjoiaTRTN1c4TndzUUNCYjZJUmlrcVgubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Ivy** (`elevenlabs:i4CzbCVWoqvD0P1QJCUL`) — female · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/i4CzbCVWoqvD0P1QJCUL/sn1oBYRT4QiAmOMgLkoi.mp3)

**İrem** (`elevenlabs:uvU9jrgGLWNPeNA4NgNT`) — female · middle&#95;aged · istanbul accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/lBvCViytbQMMb4wFFHqOJtXa2B63/voices/uvU9jrgGLWNPeNA4NgNT/7wCQJoWa3238o83Covsj.mp3)

**Jaakko** (`elevenlabs:JMfkzZiSsox62UXcXUqM`) — male · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/d83501083c7646bba14f9de45fe658a8/voices/JMfkzZiSsox62UXcXUqM/xYL6fnjYv1TNC8DzHGyN.mp3)

**Jack John** (`elevenlabs:7EzWGsX10sAS4c9m9cPf`) — male · middle&#95;aged · american accent [▶](https://api.us.elevenlabs.io/v1/voices/7EzWGsX10sAS4c9m9cPf/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiIyZjkwYTFkMDAwODg0NGMyYWFhMGEyOTE4YWU4YWY2NSIsImZpbGVuYW1lIjoiQTEydFg0YnFUd0dnUGpFeE9Wak8ubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**James** (`elevenlabs:EkK5I93UQWFDigLMpZcX`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/48ab3aae468d4e9baded4b1693820088/voices/EkK5I93UQWFDigLMpZcX/xvjT3EK4vD3zlwfawHeV.mp3)

**James Gao** (`elevenlabs:4VZIsMPtgggwNg7OXbPY`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/qCmCyqVqIbevIuA9FVI25BpgadC2/voices/4VZIsMPtgggwNg7OXbPY/9fLlmDXPhO819IAIRK44.mp3)

**Jan** (`elevenlabs:7FpO7yFcBAfqM6vZJCg7`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/8Ouy1S5qE8Ww08g1I2kbgNdWvDV2/voices/7FpO7yFcBAfqM6vZJCg7/CSI7DBMZDWw337XBup6t.mp3)

**Jan** (`elevenlabs:KIDKfqJyZ6ASuyzsKfh5`) — male · middle&#95;aged · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/KIDKfqJyZ6ASuyzsKfh5/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoic2pKV0xSbHFqOFc5QXJKSWJYRlpZRURjeGpRMiIsImZpbGVuYW1lIjoiZGY4NTY4MjYtMjc1NC00OTFhLWI3NjYtMjViNWJmZDNlM2I3Lm1wMyIsInRpbWVzdGFtcCI6MTc5MjE4MDgwMDAwMDAwMH0%3D)

**Jan** (`elevenlabs:tpBlihqtz4wU2AHMYIto`) — male · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/tpBlihqtz4wU2AHMYIto/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiIxZGEwNmVhNjc5YTU0OTc1YWQ5NmEyMjIxZmU2NTMwZCIsImZpbGVuYW1lIjoidG1qVVo0VW51OHRhVTJsenNZRXEubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Jana** (`elevenlabs:bF7C2fCv7Zf30iT84wZ1`) — female · young · prague accent [▶](https://api.us.elevenlabs.io/v1/voices/bF7C2fCv7Zf30iT84wZ1/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiRllGUk1paEhoOWdGdWNtdDhYNTRvVzJ1MVlUMiIsImZpbGVuYW1lIjoiQkJSc3hYbmtROXdwZEdzWTRsRVIubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Jane** (`elevenlabs:RILOU7YmBhvwJGDGjNmP`) — female · old · british accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/20dd3b9a3ec14f77bc0f5688c9f44ff5/voices/RILOU7YmBhvwJGDGjNmP/rg0TiCrZRw0nfGOZiVoe.mp3)

**Jane Doe** (`elevenlabs:SaqYcK3ZpDKBAImA8AdW`) — female · young · american accent [▶](https://api.us.elevenlabs.io/v1/voices/SaqYcK3ZpDKBAImA8AdW/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiIzZTM2MTk3MTE5ZTE0MGIzOWZiYmE2MGZkZDRjZTgzZCIsImZpbGVuYW1lIjoiYjdqRUFaZ2k1bmJkak94dlNGNU0ubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Jarnathan** (`elevenlabs:c6SfcYrb2t09NHXiT80T`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ae5cf0d6fb064897b39505ab5988252a/voices/c6SfcYrb2t09NHXiT80T/7S2LKVIpyowguc3AxDlB.mp3)

**Jaro** (`elevenlabs:DXwrzy2wtKORwDTbsMwk`) — male · middle&#95;aged · central accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/2695f37c86ec4bbcb3413ccf372f4f25/voices/DXwrzy2wtKORwDTbsMwk/WIsE9JR6NYKF0vtH629f.mp3)

**Jay Wayne** (`elevenlabs:8Ln42OXYupYsag45MAUy`) — male · middle&#95;aged · american accent [▶](https://api.us.elevenlabs.io/v1/voices/8Ln42OXYupYsag45MAUy/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoibjBBQ2tLMEZoSlhaeHhIZ2IxSUdvRU5MSURWMiIsImZpbGVuYW1lIjoiY2daeHpzRHVNWnVnN1hjdmthYmkubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Jayesh Bhai** (`elevenlabs:v9ZPGDUUXnWEDCiJUQkk`) — male · young [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/v9ZPGDUUXnWEDCiJUQkk/5mDQfVXgpx5Dk6FqUJtb.mp3)

**Jeanne** (`elevenlabs:txtf1EDouKke753vN8SL`) — female · young · parisian accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/txtf1EDouKke753vN8SL/KncK9phzELKxzmXlZhBV.mp3)

**Jeddawi** (`elevenlabs:yXEnnEln9armDCyhkXcA`) — male · young · saudi accent [▶](https://api.us.elevenlabs.io/v1/voices/yXEnnEln9armDCyhkXcA/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJmYzZkZGFmMDZlZDM0NDUzOWEyZTg2MDBkY2VhNmQ2ZiIsImZpbGVuYW1lIjoiTnJzbWRGQ1hqZUdrVXA2ckhzbFEubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Jenna** (`elevenlabs:TgnhEILA8UwUqIMi20rp`) — female · middle&#95;aged · canadian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/eFiNAkiBPjPhvrN6QD2zAnlnApt2/voices/TgnhEILA8UwUqIMi20rp/qWh81aKYbMv6xt2Xy6Cf.mp3)

**Jennie** (`elevenlabs:z6Kj0hecH20CdetSElRT`) — female · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/gQj40MTS0aYNIcMt6naYRDbytw63/voices/z6Kj0hecH20CdetSElRT/5ff8eff0-fffa-4ba7-aa8b-1a2bbd92364c.mp3)

**Jessa** (`elevenlabs:yj30vwTGJxSHezdAGsv9`) — female · young · american accent [▶](https://api.us.elevenlabs.io/v1/voices/yj30vwTGJxSHezdAGsv9/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiNWhkTFRwRURiamVnNFVLMXZsOUR2bEFiSjRJMiIsImZpbGVuYW1lIjoidngzdFNRMUlrb1F5TjRycjZvbGgubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Jessi** (`elevenlabs:09AoN6tYyW3VSTQqCo7C`) — female · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/09AoN6tYyW3VSTQqCo7C/kcwjIEhj1vqIC05nQ8a3.mp3)

**Jessica** (`elevenlabs:r1KmysJdVYZjJCm4mL3b`) — female · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/3f9696c671d04ff682b1d6019d5b62fe/voices/r1KmysJdVYZjJCm4mL3b/65478cae-a15a-4f7d-88a4-14cbc8745b2b.mp3)

**Jessica Anne Bogart** (`elevenlabs:g6xIsTj2HwM6VR4iXFCw`) — female · middle&#95;aged · american accent [▶](https://api.us.elevenlabs.io/v1/voices/g6xIsTj2HwM6VR4iXFCw/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJmYjFiZDE4NzA4MDE0ZDhkODBlNzcwZGY1ZWExMWJiNyIsImZpbGVuYW1lIjoiMU9xazlTZXNReFVNeG9wZmdMYjcubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Jessica Anne Bogart** (`elevenlabs:lxYfHSkYm1EzQzGhdbfc`) — female · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/fb1bd18708014d8d80e770df5ea11bb7/voices/lxYfHSkYm1EzQzGhdbfc/JZDpsUoP3T2VAnEEmj4l.mp3)

**Jiyoung** (`elevenlabs:AW5wrnG1jVizOYY7R1Oo`) — female · young · seoul accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/lpCnNtCadTY1Lw6BJ9Ldr7VFCSy1/voices/AW5wrnG1jVizOYY7R1Oo/8PwzNgj6JZ1lLlh4hBYf.mp3)

**Jo** (`elevenlabs:L4so9SudEsIYzE9j4qlR`) — female · middle&#95;aged · british accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/L4so9SudEsIYzE9j4qlR/FuYqAMaVb0vu6e5r3BeU.mp3)

**Johannes** (`elevenlabs:2dhHLsmg0MVma2t041qT`) — male · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/2dhHLsmg0MVma2t041qT/fX3l7ljt7bx6zRPz8VdC.mp3)

**John Doe** (`elevenlabs:7fbQ7yJuEo56rYjrYaEh`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/8RYUsFHsalUXjwVG0LjhNwH1j022/voices/7fbQ7yJuEo56rYjrYaEh/LfgJj1M8v4f7Ca1qWvZI.mp3)

**John Doe** (`elevenlabs:EiNlNiXeDU1pqqOPrYMO`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/8RYUsFHsalUXjwVG0LjhNwH1j022/voices/EiNlNiXeDU1pqqOPrYMO/DyICRR04KQnCeB7Y9B7K.mp3)

**Jolana** (`elevenlabs:GsFe19Xn8iGqNR2RxINi`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/user_8601kddyq20aefer68gqyjgvtazb/voices/GsFe19Xn8iGqNR2RxINi/RF4rSroM4UQgOIBlPP5A.mp3)

**Jolanda** (`elevenlabs:DiUBVrSFwkMaPz4XqWvR`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/9c6af561a08f47358091ade72cd123ce/voices/DiUBVrSFwkMaPz4XqWvR/hnjdTlsZ2zfMsX1FmHmk.mp3)

**Jon** (`elevenlabs:Cz0K1kOv9tD8l0b5Qu53`) — male · middle&#95;aged · american accent [▶](https://api.us.elevenlabs.io/v1/voices/Cz0K1kOv9tD8l0b5Qu53/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiI3YmRkNjlkOWU1ODE0ODFhOGVhNTIxNjQ5MzI3MWY4MSIsImZpbGVuYW1lIjoiZFFGNFBFelRpTmtEZ1d0SDJFUXAubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Jon** (`elevenlabs:MFZUKuGQUsGJPQjTS4wC`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/7bdd69d9e581481a8ea5216493271f81/voices/MFZUKuGQUsGJPQjTS4wC/xEoCh0QqT3VPBukUnnNT.mp3)

**Jon** (`elevenlabs:sB7vwSCyX0tQmU24cW2C`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/7bdd69d9e581481a8ea5216493271f81/voices/sB7vwSCyX0tQmU24cW2C/3oa1J14nnQ9Mk8PXyDJ7.mp3)

**Jora Slobod** (`elevenlabs:OlBp4oyr3FBAGEAtJOnU`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/OlBp4oyr3FBAGEAtJOnU/Uub5cEzcyVo34vqgA9cA.mp3)

**Joseph** (`elevenlabs:J5iaaqzR5zn6HFG4jV3b`) — male · young · american accent [▶](https://api.us.elevenlabs.io/v1/voices/J5iaaqzR5zn6HFG4jV3b/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJhNTIwMWFmM2JjY2M0NDM2OWNjOTliMmIzNDliYzc5MCIsImZpbGVuYW1lIjoiOUtzQlczaEt3cE5tMmpVNnp5cG4ubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Josh** (`elevenlabs:ZoiZ8fuDWInAcwPXaVeq`) — male · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/FRG9eBYz8ogKLVm7y3tLhgw1gv13/voices/ZoiZ8fuDWInAcwPXaVeq/9EwzECjtvTDxjoH3F7fg.mp3)

**Josh** (`elevenlabs:nzFihrBIvB34imQBuxub`) — male · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/b2109416c7514449a5f06540d10f0e73/voices/nzFihrBIvB34imQBuxub/PGPEgmq9nbilpoico1PI.mp3)

**Jovana** (`elevenlabs:g8TYYIFt2Qo27yGQmTYq`) — female · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/g8TYYIFt2Qo27yGQmTYq/QFilWgah5RMdNyosnBaW.mp3)

**Jukka Uusitalo** (`elevenlabs:GdUwr3tVJwSb22ROvLCr`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/iU5t7LNgnNbMMcO064tC1U1OnZE3/voices/GdUwr3tVJwSb22ROvLCr/0808285c-8ddd-422b-a316-a70302a54325.mp3)

**Julia** (`elevenlabs:9Nd358gE1qQp0pDh8FgP`) — female · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/d42876f99fb744e8bb207b14790cefb8/voices/9Nd358gE1qQp0pDh8FgP/f2VxjznzRb2tc20TspYA.mp3)

**Julian** (`elevenlabs:7p1Ofvcwsv7UBPoFNcpI`) — male · old · british accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/7p1Ofvcwsv7UBPoFNcpI/f86HRr1i6v8ZOCi6Dt4a.mp3)

**Juma** (`elevenlabs:85I9qUNaRIEQGWJ91dHe`) — male · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/85I9qUNaRIEQGWJ91dHe/f9AKM0Apl8SuZ2scp3hk.mp3)

**Juma** (`elevenlabs:h65Hy3wCmpuo1Fce3en3`) — male · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/h65Hy3wCmpuo1Fce3en3/8pLlDOiKPaH1rhy6NU5i.mp3)

**Jussi** (`elevenlabs:dlbXHgJnwobU5JdZ8F5M`) — male · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/13nXZgTVsqRs7AUDZdEx1zCVwSz1/voices/dlbXHgJnwobU5JdZ8F5M/54ec1f5d-26e2-4089-bba5-33b69dc8cb2c.mp3)

**Kadir Kayışcı** (`elevenlabs:j82ax9yhzfYwq9lDvRWL`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/3881716ad45a4f748d11279f4dad25e9/voices/j82ax9yhzfYwq9lDvRWL/H8LmVodweSbxtWss4NAi.mp3)

**Kailey** (`elevenlabs:OluJZCsIVfyg64DC1NPq`) — female · young · australian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/2IqDeNvZkScA79KzW0fk0iGlrE42/voices/OluJZCsIVfyg64DC1NPq/KvT7Sg1BxixJAIz9pM8H.mp3)

**Kaisa** (`elevenlabs:2Yg0KQ858zsEJOsoPmT2`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/2Yg0KQ858zsEJOsoPmT2/f1e9f3bb-4015-4fa6-9882-5c6fdc313a61.mp3)

**Kalev** (`elevenlabs:0cuaFlR2we1Gl3woPjeJ`) — male · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/0cuaFlR2we1Gl3woPjeJ/27VfynicYzMhDOWqmiuh.mp3)

**Kalyani** (`elevenlabs:UN3inGyhBayPW0A8lscL`) — female · young [▶](https://api.us.elevenlabs.io/v1/voices/UN3inGyhBayPW0A8lscL/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJlZDliMDVlNjMyNGM0NTc2ODU0OTAzNTJlOWExZWM5MCIsImZpbGVuYW1lIjoiWDNLTUZjdU1RTmRuV1hkNFh6Y2QubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Kalyani** (`elevenlabs:aZaMD7e0iu6aJpSocGIY`) — female · young [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/aZaMD7e0iu6aJpSocGIY/xw5E73m6xbRYmM90Vsgv.mp3)

**Kampana** (`elevenlabs:wgYipW6i4oMTbU78GXhZ`) — female · young [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/wgYipW6i4oMTbU78GXhZ/LinS6dvU9qIDcw1xDiOK.mp3)

**Kamran M** (`elevenlabs:GnmcdQ5D9NktfEwK2h3j`) — male · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/GnmcdQ5D9NktfEwK2h3j/0d6a7f37-c4d8-4783-a956-4dae2a894c62.mp3)

**Kanya** (`elevenlabs:B4NdgwdU97lHqA8Udh2D`) — female · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/B4NdgwdU97lHqA8Udh2D/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiIxZGEwNmVhNjc5YTU0OTc1YWQ5NmEyMjIxZmU2NTMwZCIsImZpbGVuYW1lIjoiTUhVMUdWOXpRZWFaOGFDa1V1RU8ubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Kate** (`elevenlabs:7G0NvIkWRnU0Dqjgz13p`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/d0Mmelcs5mbQZykIK8fo2PNTo0o1/voices/7G0NvIkWRnU0Dqjgz13p/fPwqaz10ByW2RecDZaWS.mp3)

**Katerina** (`elevenlabs:t7C9cEkpMwHG1IMZlJJ5`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/t7C9cEkpMwHG1IMZlJJ5/afce6b57-1a4a-45b4-b6ae-45a67f7d9b70.mp3)

**Katie X** (`elevenlabs:MzqUf1HbJ8UmQ0wUsx2p`) — female · middle&#95;aged · british accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/TBCGBdfm5sahGkhMn2WcXK1i4Ya2/voices/MzqUf1HbJ8UmQ0wUsx2p/t0eGqs22ZknvrpntIlz4.mp3)

**Kelvin** (`elevenlabs:fcJJxRPg9WEEhH0Uqnwn`) — male · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/fcJJxRPg9WEEhH0Uqnwn/xYiU4C9shxQ53fVVHaCG.mp3)

**Kendra** (`elevenlabs:Xkem7o24n3aQyiwIXNeT`) — female · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1df4b21393b74964b03d3690a173eb80/voices/Xkem7o24n3aQyiwIXNeT/CYv5NPfEE7CqgeD88mVJ.mp3)

**Kennedy** (`elevenlabs:c8GqgOMlDjKmhWVDfhvI`) — female · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/jmRxIqTXEhOg7JeVh81cwYsIWg53/voices/c8GqgOMlDjKmhWVDfhvI/12ac2869-bfe6-43f4-9328-bc4dcb46ba81.mp3)

**Kenneth** (`elevenlabs:8z82LG47qQ2qjeeQB8lk`) — male · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/c2c551bea72d4afeb2cc09deb3acef5e/voices/8z82LG47qQ2qjeeQB8lk/8njBWGKktWGqpXfNwMak.mp3)

**Keren** (`elevenlabs:33B4UnXyTNbgLmdEDh5P`) — female · young · brazilian accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/33B4UnXyTNbgLmdEDh5P/ArnzDsFaz6KDoDcDD8V2.mp3)

**Keval** (`elevenlabs:Vv6abBEqLOV9dEJTfjut`) — male · young [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/Vv6abBEqLOV9dEJTfjut/Jt2vo6TENVGNAyynkqLB.mp3)

**Khaled Alnajjar** (`elevenlabs:drMurExmkWVIH5nW8snR`) — male · middle&#95;aged · palestinian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/fTWO37tZNnd4ihmohrzHTeGcGxg1/voices/drMurExmkWVIH5nW8snR/fEYj55DSMODMgTJY46dG.mp3)

**Kinjal Vora** (`elevenlabs:NZhrkS77RQpyhxv2KBbr`) — female · young [▶](https://api.us.elevenlabs.io/v1/voices/NZhrkS77RQpyhxv2KBbr/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJlZDliMDVlNjMyNGM0NTc2ODU0OTAzNTJlOWExZWM5MCIsImZpbGVuYW1lIjoiZmVqOUkyT0lkdGNwOEthU3F1SlYubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Kiều Linh** (`elevenlabs:qByVAGjXwGlkcRDJoiHg`) — female · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/29ca19d1407e47fc86008497a8499f88/voices/qByVAGjXwGlkcRDJoiHg/e95723e3-1ba6-4b30-b302-6e4bcbf5b808.mp3)

**Knox Dark** (`elevenlabs:dPah2VEoifKnZT37774q`) — male · middle&#95;aged · american accent [▶](https://api.us.elevenlabs.io/v1/voices/dPah2VEoifKnZT37774q/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiI4NmI2N2NiODE4OWY0NDRkODc3Zjg3MjMzZGJkYWVmNiIsImZpbGVuYW1lIjoiRFdrYUI2cHJ0NFVRQ0ZsVk5hUzUubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Kosta** (`elevenlabs:gdk0ZsvfAOobfbTtnx6p`) — male · middle&#95;aged · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/gdk0ZsvfAOobfbTtnx6p/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiI5YjQ3MDFkZDRiYjE0ODVjODA3YWE3ZWQwZmE5MTUwOCIsImZpbGVuYW1lIjoiOTg4ZmRmMWItNDg5Mi00MGJkLWExMTAtMTFmYmQ1Y2I0YzRkLm1wMyIsInRpbWVzdGFtcCI6MTc5MjE4MDgwMDAwMDAwMH0%3D)

**Kozy** (`elevenlabs:GxxMAMfQkDlnqjpzjLHH`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/9157dacef36b4b208fb7b6a0f7d8f835/voices/GxxMAMfQkDlnqjpzjLHH/IMg23SvRC1b5gG2PYOkJ.mp3)

**Kristaps** (`elevenlabs:g5sTwAvmq33DtRr9MKWC`) — male · young · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/g5sTwAvmq33DtRr9MKWC/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiIxZGEwNmVhNjc5YTU0OTc1YWQ5NmEyMjIxZmU2NTMwZCIsImZpbGVuYW1lIjoiODMzNjg1NWQtYjk0NC00Mzg2LWJjNDUtNjE4ZjUxZTdiY2I4Lm1wMyIsInRpbWVzdGFtcCI6MTc5MjE4MDgwMDAwMDAwMH0%3D)

**Kristiina** (`elevenlabs:oUcJ06xwmP9H468Qrwdd`) — female · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/oUcJ06xwmP9H468Qrwdd/XH8kfQMISo2kHacyZpuj.mp3)

**Larisa Actrisa** (`elevenlabs:AB9XsbSA4eLG12t2myjN`) — female · young · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/AB9XsbSA4eLG12t2myjN/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiZGRsSFlwaHNzS1k1ZmtHYnR3dWU5YTdPYmZwMSIsImZpbGVuYW1lIjoiNGhwdXRiVTJUbkZmQm9Vam43Q0wubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Lauren** (`elevenlabs:3liN8q8YoeB9Hk6AboKe`) — female · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/3liN8q8YoeB9Hk6AboKe/MZXixZbkbklU2zsfmFe9.mp3)

**Lauren** (`elevenlabs:DODLEQrClDo8wCz460ld`) — female · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/DODLEQrClDo8wCz460ld/MauqrAicWZU5vhA44xSe.mp3)

**Lea** (`elevenlabs:7eVMgwCnXydb3CikjV7a`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/7eVMgwCnXydb3CikjV7a/zMitELWPfkgqNXLr2X9t.mp3)

**Leonie** (`elevenlabs:uvysWDLbKpA4XvpD3GI6`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/uvysWDLbKpA4XvpD3GI6/ezhAOHUNyJPqr5RGmaxn.mp3)

**Liisa** (`elevenlabs:xd3ufyLcuKKZZXDZO9H7`) — female · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/xd3ufyLcuKKZZXDZO9H7/SR3vJRSlTjeNJkBORuaQ.mp3)

**Lily Wolff** (`elevenlabs:qBDvhofpxp92JgXJxDjB`) — female · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/72bdb9c08cad4d3da50eb849856f35d4/voices/qBDvhofpxp92JgXJxDjB/zCF3eM3r5CLzM3esEn8v.mp3)

**Linas** (`elevenlabs:DFrx5dLoBDQyVA8dVe3c`) — male · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/DFrx5dLoBDQyVA8dVe3c/D44zcz4DZg3kWKegaa7M.mp3)

**Linda Fiore** (`elevenlabs:3DPhHWXDY263XJ1d2EPN`) — female · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/3DPhHWXDY263XJ1d2EPN/YcN8v5oIOX09iQfWoPXH.mp3)

**Liz** (`elevenlabs:uMM5TEnpKKgD758knVJO`) — female · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/af050efbdab9479ca29e5d48c00bd675/voices/uMM5TEnpKKgD758knVJO/O0FyWnfz0UI6X55jzQhm.mp3)

**Liz** (`elevenlabs:wvk9Caj0nEx4l3I9LaR6`) — female · young · american accent [▶](https://api.us.elevenlabs.io/v1/voices/wvk9Caj0nEx4l3I9LaR6/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJhMWQ5ODk3NjRmNDc0YTcyOWJhMWExODIyZWQyY2Q4NCIsImZpbGVuYW1lIjoiYmNxV2dYTlg1Uk1lTUpJUHVhZmcubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Lori** (`elevenlabs:TbMNBJ27fH2U0VgpSNko`) — female · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/66f78291e77e465aa11de5b0c0b34b2d/voices/TbMNBJ27fH2U0VgpSNko/cWDvSljlcLDipvaWsmxJ.mp3)

**Lowy** (`elevenlabs:24EI9FmmGvJruwUi7TJM`) — male · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/35EojMw1Tzb8ZhzkfMVTEXODhCB2/voices/24EI9FmmGvJruwUi7TJM/3c8a27f7-2a3b-4f77-8e26-bdfbab5b97e6.mp3)

**Lucan Rook** (`elevenlabs:15CVCzDByBinCIoCblXo`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/XfNHbUnzYlfKcyqwGAOVIYehri33/voices/15CVCzDByBinCIoCblXo/7b63eb9a-f231-4f7e-8214-5810a5913b2e.mp3)

**Lucie** (`elevenlabs:YxrwjAKoUKULGd0g8K9Y`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/gg1lMbn4pfMl9KEjHqq6YAz1IYZ2/voices/YxrwjAKoUKULGd0g8K9Y/WxJo9vU6cjx9EPdS9beN.mp3)

**Lucy** (`elevenlabs:lcMyyd2HUfFzxdCaC4Ta`) — female · young · british accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/On0pjHuDnweq0BS7b0qVjhIq37i1/voices/lcMyyd2HUfFzxdCaC4Ta/iutd7IQOhAGGiTAJT0X8.mp3)

**Luis** (`elevenlabs:WGINef1wh4Hi6O62bfO8`) — male · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/26b6ac0cd0c44218a7b8f34b92f5ccd8/voices/WGINef1wh4Hi6O62bfO8/dxzbKL8dGA3dUPEm2xTf.mp3)

**Luka** (`elevenlabs:SmCUS1ekZnVjC5lqnRQG`) — male · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/SmCUS1ekZnVjC5lqnRQG/8S6OQkbxl1y8RErGAwX4.mp3)

**Luka** (`elevenlabs:ZLYZToA7aDsMbHwM9AOr`) — male · middle&#95;aged · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/ZLYZToA7aDsMbHwM9AOr/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoid3F6UnNaTHpoeUxkWXVxOVVhT0c4RTRobXNUMiIsImZpbGVuYW1lIjoidHBLYTU1QVpTdG85cUxyRFZ2VWoubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Luke** (`elevenlabs:RNnkVeW25AwKYxZgnHBH`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/644c15c542534663bbf30bfe4795f838/voices/RNnkVeW25AwKYxZgnHBH/IQdSpbU4BIb3srbtdTuo.mp3)

**Léo** (`elevenlabs:AfbuxQ9DVtS4azaxN1W7`) — male · middle&#95;aged · parisian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/0c997c49a0d74f83bef0a9d942b92f0f/voices/AfbuxQ9DVtS4azaxN1W7/RdF3GH356ehVu2eylw45.mp3)

**Maahir** (`elevenlabs:d2osXrwa36lUEkuaO4sP`) — male · young [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/d2osXrwa36lUEkuaO4sP/HateJEYRjfulGS4wf8Uk.mp3)

**Madhavi** (`elevenlabs:4XvBGCPMXWyVQa75dbZg`) — female · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/4XvBGCPMXWyVQa75dbZg/QK6vOehJdKmjnD5X9Bl3.mp3)

**Magdalena** (`elevenlabs:N0GCuK2B0qwWozQNTS8F`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/YlIj2XeXrsQMcg7bgHoRSZCzRcu2/voices/N0GCuK2B0qwWozQNTS8F/PqhjD3HxJ0MP4R5cSdEZ.mp3)

**Mahi** (`elevenlabs:aVwNS3gNch2GhQaTeQ54`) — female · middle&#95;aged [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/aVwNS3gNch2GhQaTeQ54/DVoQV5uwO9cgxzYSAcJw.mp3)

**Maja** (`elevenlabs:WwFMMxYWrkm6h88c7f0n`) — female · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/WwFMMxYWrkm6h88c7f0n/t5SIUrxdclULA23SBzij.mp3)

**Maja E** (`elevenlabs:BGEU6wFi2uNm6Kje1Yhk`) — female · middle&#95;aged · oslo accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/BGEU6wFi2uNm6Kje1Yhk/gCIHS9pPkrtwiAjN4VgG.mp3)

**Malee** (`elevenlabs:mYcpTKg1oj1H5CtzUZNO`) — female · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/mYcpTKg1oj1H5CtzUZNO/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiIxZGEwNmVhNjc5YTU0OTc1YWQ5NmEyMjIxZmU2NTMwZCIsImZpbGVuYW1lIjoiRnNqbkJReDYyM2ZNdDIzWnZlOWYubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Maneesh** (`elevenlabs:pTM0m0egrCpo5i9b1gpo`) — male · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/pTM0m0egrCpo5i9b1gpo/uKlbJirxLYw7iLdD3wOB.mp3)

**Manikandan** (`elevenlabs:Eclv6jJwMbGUhEki9Bro`) — male · middle&#95;aged [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/Eclv6jJwMbGUhEki9Bro/1Wp2DZUp3fCW9DmMPTC1.mp3)

**Manikandan** (`elevenlabs:ZDJM0nlhLoAeknyir3H0`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/ZDJM0nlhLoAeknyir3H0/l9kkdUyUqF7n0uePJxn8.mp3)

**Manu** (`elevenlabs:P5Y7cJhVoUoFVrXgyLyN`) — male · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/e88109a6fafc4ba2a0d7dccd0811f898/voices/P5Y7cJhVoUoFVrXgyLyN/bcf9d44c-34b2-43b3-a585-8c153c4f4626.mp3)

**Marco** (`elevenlabs:13Cuh3NuYvWOVQtLbRN8`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/9f5219a8b69545c7a5f2948bc2e9e0ef/voices/13Cuh3NuYvWOVQtLbRN8/x2LttjJl6pNQeAlpU3CY.mp3)

**MarcoTrox** (`elevenlabs:W71zT1VwIFFx3mMGH2uZ`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/9f5219a8b69545c7a5f2948bc2e9e0ef/voices/W71zT1VwIFFx3mMGH2uZ/gxqkkXfQqy1Og9Sa5fHd.mp3)

**Marcèles** (`elevenlabs:fzC7H9Y1bPn3gzVLtghe`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/d93hYIP9x1PXnMEvF5kMjKeP0pF3/voices/fzC7H9Y1bPn3gzVLtghe/6sjKEhNwpOfBWH8WSHUH.mp3)

**Mariia** (`elevenlabs:EDpEYNf6XIeKYRzYcx4I`) — female · middle&#95;aged · moscow accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/OH6cNoruamM0NJggO6ALztvyefv1/voices/EDpEYNf6XIeKYRzYcx4I/d14a20ef-969c-41c2-be25-010fb5057e69.mp3)

**Marina** (`elevenlabs:ymDCYd8puC7gYjxIamPt`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/Ws0NuxiaxGXfCa5Pjid7Cf3DXNI2/voices/ymDCYd8puC7gYjxIamPt/JIvpZszp6VTLxZ35YaHE.mp3)

**Mariya Maro** (`elevenlabs:2OXYbN1uGomXXJtv9Dq6`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/1rswuGKLRSP2VgocvkaJeeXfRfh1/voices/2OXYbN1uGomXXJtv9Dq6/Jo8qs5WAiDZpFE8C8z5S.mp3)

**Mark** (`elevenlabs:1SM7GgM6IMuvQlz2BwM3`) — male · middle&#95;aged · american accent [▶](https://api.us.elevenlabs.io/v1/voices/1SM7GgM6IMuvQlz2BwM3/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJmOTRlMjYwMjAwNzY0Njc4YmFiYzgwN2I5MzViZmIwYiIsImZpbGVuYW1lIjoieTk0RzFyR2l4YXFMMkZ2UDNUdGUubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Mark** (`elevenlabs:UgBBYS2sOqTuMpoF3BR0`) — male · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/f94e260200764678babc807b935bfb0b/voices/UgBBYS2sOqTuMpoF3BR0/0Oc7jiXwWN9kRTXfQsmw.mp3)

**Mark** (`elevenlabs:WTUK291rZZ9CLPCiFTfh`) — male · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/f94e260200764678babc807b935bfb0b/voices/WTUK291rZZ9CLPCiFTfh/bnnCGcGCSiY3m9CS9dGc.mp3)

**Mark** (`elevenlabs:fzqS9sNPYJhLlhsfDm0l`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/as5e4HESufUtAzbrPo2bwJVu0Cm1/voices/fzqS9sNPYJhLlhsfDm0l/WwnNGwsgcz7Hz7UO5nmp.mp3)

**Marko** (`elevenlabs:PcQ1oUfPHim3ZuyULxyk`) — male · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/PcQ1oUfPHim3ZuyULxyk/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiIxZGEwNmVhNjc5YTU0OTc1YWQ5NmEyMjIxZmU2NTMwZCIsImZpbGVuYW1lIjoidXJkSzE4OW5nZU9abEdnTGVNdlEubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Markus** (`elevenlabs:3b1UQOsEeEKASBofmpXR`) — male · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/3b1UQOsEeEKASBofmpXR/Q49FXgACdZ7NIQRHtXiU.mp3)

**Martha** (`elevenlabs:JrrE7QTGDmQKQuUnqk7H`) — female · middle&#95;aged · cypriot accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/5431d2454f514fe89175a88d8251a788/voices/JrrE7QTGDmQKQuUnqk7H/HfAaZpiSuGcqXR53Tn0J.mp3)

**Martin** (`elevenlabs:9pRpxWU0T7UFt2oEMH6n`) — male · middle&#95;aged · oslo accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/RRtw5JYF3wMGUkxyyWxD04DJJi82/voices/9pRpxWU0T7UFt2oEMH6n/5EmH9uT3Xjvhb8O9yb3d.mp3)

**Marusa** (`elevenlabs:e5bituEyQnVOgFN8BncW`) — female · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/e5bituEyQnVOgFN8BncW/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiIxZGEwNmVhNjc5YTU0OTc1YWQ5NmEyMjIxZmU2NTMwZCIsImZpbGVuYW1lIjoiT1ducXVScHkwdm13QU5lQUxjWVIubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Matevz** (`elevenlabs:PlEmLdCbD9b5dxxyCryM`) — male · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/PlEmLdCbD9b5dxxyCryM/Rl7DdecjzOapAxnJ6KjG.mp3)

**Matheus** (`elevenlabs:36rVQA1AOIPwpA3Hg1tC`) — male · young [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/36rVQA1AOIPwpA3Hg1tC/ewP6z1S1gE5Mb9nBSNaV.mp3)

**Mathias** (`elevenlabs:ygiXC2Oa1BiHksD3WkJZ`) — male · middle&#95;aged · jutlandic accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/ygiXC2Oa1BiHksD3WkJZ/MV8Filx4M2vlCNaIVYQH.mp3)

**Max** (`elevenlabs:Gfpl8Yo74Is0W6cPUWWT`) — male · middle&#95;aged · american accent [▶](https://api.us.elevenlabs.io/v1/voices/Gfpl8Yo74Is0W6cPUWWT/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiQ0VaWHhmZENmRWZ5WEQ3eVVOS0lQY3VDS2FCMyIsImZpbGVuYW1lIjoiMWVkMGU2YWYtNTcxYi00YjhlLTlhYTItNzcxNWNmMjRkMDFiLm1wMyIsInRpbWVzdGFtcCI6MTc5MjE4MDgwMDAwMDAwMH0%3D)

**Max F. Baumgartner** (`elevenlabs:JhAQDwsLijg4qbxGNQGH`) — male · young · stockholm accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/6349aadecd6448c09d7f7290244a4431/voices/JhAQDwsLijg4qbxGNQGH/hG04KcVQy39qqysbg9tz.mp3)

**Maya** (`elevenlabs:U3dExJoUNcmTY5H6GMuG`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/YotRl5UtyjbVL8jHQUKk2dY3U7D3/voices/U3dExJoUNcmTY5H6GMuG/ys5zgPKaUeIX1PwdbDwf.mp3)

**Maya** (`elevenlabs:UZzDIQRRTW2Id7YBcbgC`) — female · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/UZzDIQRRTW2Id7YBcbgC/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiIxZGEwNmVhNjc5YTU0OTc1YWQ5NmEyMjIxZmU2NTMwZCIsImZpbGVuYW1lIjoiZ3lVT3cwdklvY1VpR3BpTVJWYXAubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Mazen Lawand** (`elevenlabs:rPNcQ53R703tTmtue1AT`) — male · middle&#95;aged · modern standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/4acdacdfb7724a85a991004c4b2907e3/voices/rPNcQ53R703tTmtue1AT/mcHBML9LE3BlDH6Bc51u.mp3)

**Meera** (`elevenlabs:9TwzC887zQyDD4yBthzD`) — female · middle&#95;aged · british accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/apiwwxzxOkbnkinjLhFNFWfbrnL2/voices/9TwzC887zQyDD4yBthzD/yfB1WlLvJDiStSkwbcCa.mp3)

**Meera** (`elevenlabs:gCr8TeSJgJaeaIoV4RWH`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/514d94e9241c48e8b7905375729c436f/voices/gCr8TeSJgJaeaIoV4RWH/CTpfoY4KKQGv5il8CtEM.mp3)

**Mei Ling** (`elevenlabs:Nw1gFFIqeG59noyldAp1`) — female · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/Nw1gFFIqeG59noyldAp1/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiIxZGEwNmVhNjc5YTU0OTc1YWQ5NmEyMjIxZmU2NTMwZCIsImZpbGVuYW1lIjoia3dZWERqd0ZvTUpxb3cxRlN5MWoubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Mia** (`elevenlabs:RBQdnLdc4yI3og0Z9TQL`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/b7f6c0570a234f6682fbec1a0c83c465/voices/RBQdnLdc4yI3og0Z9TQL/NbRZAnMsB4oFs6778gz8.mp3)

**Michael C. Vincent** (`elevenlabs:n1PvBOwxb8X6m7tahp2h`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/KYjz3Y9IA1hOyAaoFAnINnfyIAR2/voices/n1PvBOwxb8X6m7tahp2h/LZUo9zXnQ6nFMFs5oW7f.mp3)

**Michael C. Vincent** (`elevenlabs:uju3wxzG5OhpWcoi3SMy`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/uju3wxzG5OhpWcoi3SMy/ixYUu11jiy8LIVZidnvA.mp3)

**Mike L** (`elevenlabs:am5XuPVtut7uKJQKMja2`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/VkIDvdKbY9fZF8vrmdbI6F2UYTe2/voices/am5XuPVtut7uKJQKMja2/GoyGgNM4vSbDRFvocyIh.mp3)

**Milena** (`elevenlabs:7IVTG9LKLYndnFiFDLU2`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ca69848b60bc43b39969ac00cad98e4c/voices/7IVTG9LKLYndnFiFDLU2/mtqAVSZ15xJ6o57ESMrV.mp3)

**Milena** (`elevenlabs:M1ydWt7KnBCiuv4CnEDC`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/44af03d036fe4e5493dd910f7b1834ae/voices/M1ydWt7KnBCiuv4CnEDC/QmyVKrtie1aX5rjVUxvz.mp3)

**Milica** (`elevenlabs:ih4fthN0aVU5Vs9NMwgk`) — female · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/ih4fthN0aVU5Vs9NMwgk/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiIxZGEwNmVhNjc5YTU0OTc1YWQ5NmEyMjIxZmU2NTMwZCIsImZpbGVuYW1lIjoiZ2k0NTdVY0JlSExQdDI0QVF0ZU0ubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Milo** (`elevenlabs:GUDYcgRAONiI1nXDcNQQ`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/6ucepsMRFsSPtAkS3qJkLzIdtuw2/voices/GUDYcgRAONiI1nXDcNQQ/aaec8fe5-bb13-4902-8a96-ce845eefca1a.mp3)

**Mimi** (`elevenlabs:CBDgRB8OyxYGowoi5iXR`) — female · young · sofia accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/317cf6a7461f4fa1a998645b4dd5021f/voices/CBDgRB8OyxYGowoi5iXR/751ddf53-2eeb-4acd-9167-ead7a8fe9a7c.mp3)

**Miranda** (`elevenlabs:PoHUWWWMHFrA8z7Q88pu`) — female · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/ZXqeDajThsaYR96DSywtY94M8Dy1/voices/PoHUWWWMHFrA8z7Q88pu/403a094a-c4e4-431f-b96a-7c63ae76508d.mp3)

**Monika Sogam** (`elevenlabs:2zRM7PkgwBPiau2jvVXc`) — female · young · indian accent [▶](https://api.us.elevenlabs.io/v1/voices/2zRM7PkgwBPiau2jvVXc/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiI1MTRkOTRlOTI0MWM0OGU4Yjc5MDUzNzU3MjljNDM2ZiIsImZpbGVuYW1lIjoiTmNFT1E5YXdUWnZnd1VvcXRtVTkubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Monika Sogam** (`elevenlabs:EaBs7G1VibMrNAuz2Na7`) — female · young · indian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/514d94e9241c48e8b7905375729c436f/voices/EaBs7G1VibMrNAuz2Na7/PFvuYioNtADsGVRLtgiE.mp3)

**Monika Sogam** (`elevenlabs:ZUrEGyu8GFMwnHbvLhv2`) — female · young · indian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/ZUrEGyu8GFMwnHbvLhv2/BnX4hQ0sCzHZblR3Y1Kd.mp3)

**Moonglow** (`elevenlabs:vnewfQdVVk9Y9DZWVRNm`) — female · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/fYDCRFvpbqaI670jbcJdIXClcAd2/voices/vnewfQdVVk9Y9DZWVRNm/b7cd4793-0ed8-4c3b-bc7f-17358ab5411c.mp3)

**Morioki** (`elevenlabs:8EkOjt4xTPGMclNlh1pk`) — female · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/MwVnKyOTE3ZRdpgHUo84p20s9zw2/voices/8EkOjt4xTPGMclNlh1pk/09bd3d5e-755b-4046-8ace-c69f0dcc872f.mp3)

**Motivational Coach** (`elevenlabs:84Fal4DSXWfp7nJ8emqQ`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/84Fal4DSXWfp7nJ8emqQ/cY8RJM5BQhNzEERHl9hq.mp3)

**Ms. Walker** (`elevenlabs:DLsHlh26Ugcm6ELvS0qi`) — female · middle&#95;aged · us southern accent [▶](https://api.us.elevenlabs.io/v1/voices/DLsHlh26Ugcm6ELvS0qi/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoidGwybnFQMWVyOFhIWkdzWHpmZU8wREd5cmJFMiIsImZpbGVuYW1lIjoiSUw3aFJtRk1CQ1JzWVFKOW04a1MubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Muskaan** (`elevenlabs:ePwGt0LoQwCKff7XLwbt`) — female · middle&#95;aged [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/ePwGt0LoQwCKff7XLwbt/j8zEoRpRWEsfpjo7AcA1.mp3)

**Muthu** (`elevenlabs:gJvkwI7wGFW2czmyfJhp`) — male · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/gJvkwI7wGFW2czmyfJhp/JgCM4B5PjDYK8E2vgAn1.mp3)

**Mária** (`elevenlabs:WNxHBFUm0NC5fojx98kr`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/user_0301kfk8q535ea0tth2ma3w68k2c/voices/WNxHBFUm0NC5fojx98kr/3yasawYXkV2bN1I7w1dL.mp3)

**Nadia K** (`elevenlabs:BRY5wALXFkJsxVM6sEOH`) — female · middle&#95;aged · oslo accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/f01d34011b1a4e2db16849b04174c91d/voices/BRY5wALXFkJsxVM6sEOH/711e675c-c19e-4df6-bdc2-f7c3a9bcc37d.mp3)

**Natasha** (`elevenlabs:h2sm0NbeIZXHBzJOMYcQ`) — female · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/h2sm0NbeIZXHBzJOMYcQ/rgEQcXdiFIMXlsOGf4Q9.mp3)

**Nathaniel** (`elevenlabs:AeRdCCKzvd23BpJoofzx`) — male · middle&#95;aged · british accent [▶](https://api.us.elevenlabs.io/v1/voices/AeRdCCKzvd23BpJoofzx/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiI1MTRkOTRlOTI0MWM0OGU4Yjc5MDUzNzU3MjljNDM2ZiIsImZpbGVuYW1lIjoibzhjNTJ3WFg4WWRodzZOVkFnMGEubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Navjot** (`elevenlabs:eGmg6o3kXJVO1TqU1fVF`) — female · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/eGmg6o3kXJVO1TqU1fVF/tagW7XS4u8BC9S0GZHSv.mp3)

**Neema** (`elevenlabs:1F0knNkQeIgyHeW4heKC`) — female · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/1F0knNkQeIgyHeW4heKC/MDHbS3c9atCkwt5GEX3M.mp3)

**Neha** (`elevenlabs:QTKSa2Iyv0yoxvXY2V8a`) — female · young · indian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/QTKSa2Iyv0yoxvXY2V8a/f15AyOSSF3gnWeMzjkvw.mp3)

**Ngân Nguyễn** (`elevenlabs:DvG3I1kDzdBY3u4EzYh6`) — female · middle&#95;aged · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/DvG3I1kDzdBY3u4EzYh6/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiYzVrZEpDVG8zYVFzVnF3N0ZGWGIya2FpcGI4MyIsImZpbGVuYW1lIjoia1JUNWRjYjRYaXZ5S2hOSThEd0EubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Nhu** (`elevenlabs:A5w1fw5x0uXded1LDvZp`) — female · young · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/A5w1fw5x0uXded1LDvZp/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiI3ZjcyZmRlMzRmYTc0YTE3OWUyMTE4MmVkMjhhZTA5NCIsImZpbGVuYW1lIjoiUGw0NGR2cUFBR3J3eFpFdGE3bUUubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Nhật Phong** (`elevenlabs:6adFm46eyy74snVn6YrT`) — male · young · northern accent [▶](https://api.us.elevenlabs.io/v1/voices/6adFm46eyy74snVn6YrT/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiIwNTQ1NTBkODc4YzI0MTQ2YTA1MDM4ZjAyNTVkZWNmMyIsImZpbGVuYW1lIjoiSzB5MFdLS01JdHp3b3FxMnBrbVMubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Niander Wallace** (`elevenlabs:bAFkvitDGeDMmqo9gJzO`) — male · middle&#95;aged · german accent [▶](https://api.us.elevenlabs.io/v1/voices/bAFkvitDGeDMmqo9gJzO/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiI0NTU1ZmZiMjYyY2Y0MzI0YmEyMTNhODI4M2E4ZTNiMyIsImZpbGVuYW1lIjoiT1g3NEtDdzNDQzZNTGRJa2ZERzgubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Nichalia Schwartz** (`elevenlabs:XfNU2rGpBa01ckF309OY`) — female · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/XfNU2rGpBa01ckF309OY/kuFJZI5s8GbgYm5f0hMo.mp3)

**Nicolas** (`elevenlabs:aQROLel5sQbj1vuIVi6B`) — male · middle&#95;aged · parisian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/7593eab373974d1db7d45255c5986d46/voices/aQROLel5sQbj1vuIVi6B/shwzqRrR51OISZWUl7EN.mp3)

**Nicolas Petit** (`elevenlabs:AmMsHJaCw4BtwV3KoUXF`) — male · middle&#95;aged [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/6e0a5e48523a4ace847294f69a35dad4/voices/AmMsHJaCw4BtwV3KoUXF/ZbTESeOraWjGeT4n62PH.mp3)

**Niharika** (`elevenlabs:70QpbCWFDvTpWo8ZKOUb`) — female · young [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/70QpbCWFDvTpWo8ZKOUb/HmBxqqFkPNaQ82NneqM6.mp3)

**Nikolay** (`elevenlabs:3EuKHIEZbSzrHGNmdYsx`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/fbf84673baa740ae87ecf80121645a80/voices/3EuKHIEZbSzrHGNmdYsx/eDCArYD3qxTq5zrHJjYL.mp3)

**Nila** (`elevenlabs:C2RGMrNBTZaNfddRPeRH`) — female · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/514d94e9241c48e8b7905375729c436f/voices/C2RGMrNBTZaNfddRPeRH/AIgN0lfgcgEfOLsen6Ki.mp3)

**Nila** (`elevenlabs:gqFUMFHCD2nbbcYVtPGB`) — female · middle&#95;aged · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/gqFUMFHCD2nbbcYVtPGB/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiI1MTRkOTRlOTI0MWM0OGU4Yjc5MDUzNzU3MjljNDM2ZiIsImZpbGVuYW1lIjoic2hQQUVjWnpKY0ZlS0VrWnQ0VXYubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Nimra** (`elevenlabs:sBbi9g93xHziblkRUx5a`) — female · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/sBbi9g93xHziblkRUx5a/ShcPJw4JlgfyjMouaxK4.mp3)

**Nina** (`elevenlabs:0IwLFuWc6siAnpd77hRG`) — female · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/0IwLFuWc6siAnpd77hRG/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiIxZGEwNmVhNjc5YTU0OTc1YWQ5NmEyMjIxZmU2NTMwZCIsImZpbGVuYW1lIjoiVHN0cG00dzdjVDdCMVNOVHBSUDIubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Ninh Đôn** (`elevenlabs:aN7cv9yXNrfIR87bDmyD`) — male · young · northern accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/sOwFF8ejIvSefUvvGpTJ63HXubh1/voices/aN7cv9yXNrfIR87bDmyD/hfxx2raRzt2YVxtQiM8H.mp3)

**Noa** (`elevenlabs:94W4cf0CMSgymY1uoRiX`) — female · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/WU07M32QizTQgTgCMIJ6EWebS0j2/voices/94W4cf0CMSgymY1uoRiX/88ca6f3c-3846-41b4-a2f7-da9c06d99568.mp3)

**Nolen** (`elevenlabs:vPyfZcTRVuFmWwDgQRSd`) — male · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/HOZrfHdrnpe9pZlWrIwZoq4cDsX2/voices/vPyfZcTRVuFmWwDgQRSd/6IqZEWsHGjzHTLNXxChL.mp3)

**Norah** (`elevenlabs:kcQkGnn0HAT2JRDQ4Ljp`) — female · young · latin american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/06c63e017f47462b814df82e5e4bd95e/voices/kcQkGnn0HAT2JRDQ4Ljp/ahsfnWSIKEI3UbM2BaEE.mp3)

**Nueng** (`elevenlabs:RIc0VzgLsI8EhceUkZx4`) — female · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/RIc0VzgLsI8EhceUkZx4/mqiMmMTIuOVv8D5crDH5.mp3)

**Ola Paulakoski** (`elevenlabs:7UMEOkIJdI4hjmR2SWNq`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/HUEGEcVm71WNcKlDpqfXhXNQK602/voices/7UMEOkIJdI4hjmR2SWNq/2OFBWuBWSjTyZtNjdKfR.mp3)

**Oliver** (`elevenlabs:daJ4gHLkIVFskWuoLuDX`) — male · middle&#95;aged · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/daJ4gHLkIVFskWuoLuDX/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiSFk4OEg0VXE5N1RHS1FSMU1kVWF5bllJZXBaMiIsImZpbGVuYW1lIjoiQlZDMkNWNHZkSmhMdGdkMFh4T0YubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Omer** (`elevenlabs:k77ZRVqAFg9Hd0ltAuON`) — male · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/k77ZRVqAFg9Hd0ltAuON/XqZX8EK3EsTgG8ogXuKc.mp3)

**Otani** (`elevenlabs:3JDquces8E8bkmvbh6Bc`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/3JDquces8E8bkmvbh6Bc/PZchZFPBnPlog5kS1miM.mp3)

**Otto** (`elevenlabs:FTNCalFNG5bRnkkaP5Ug`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/FTNCalFNG5bRnkkaP5Ug/MQ8WiEa4ozV4HevPeMba.mp3)

**Paige** (`elevenlabs:NDTYOmYEjbDIVCKB35i3`) — female · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/5dVkyvf9hWQ7Nsxgwk1qbTBVxc63/voices/NDTYOmYEjbDIVCKB35i3/nMSJmS4PAD07h42vKmX0.mp3)

**Parnita** (`elevenlabs:75CHIF904aWz6uq77J3P`) — female · young [▶](https://api.us.elevenlabs.io/v1/voices/75CHIF904aWz6uq77J3P/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJlZDliMDVlNjMyNGM0NTc2ODU0OTAzNTJlOWExZWM5MCIsImZpbGVuYW1lIjoiaEpNVm5xQjdTWlF0NlVmNU5wblAubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Patrick International** (`elevenlabs:9Ft9sm9dzvprPILZmLJl`) — male · middle&#95;aged · australian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/wJJvXY6NcPXqUshhgrZWYNpqhWC2/voices/9Ft9sm9dzvprPILZmLJl/r8hIj3z20ZajJ8djrHh0.mp3)

**Pawel** (`elevenlabs:zzBTsLBFM6AOJtkr1e9b`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/zzBTsLBFM6AOJtkr1e9b/jsLaAOqZnKHhKX1sJTWl.mp3)

**Peter** (`elevenlabs:TumdjBNWanlT3ysvclWh`) — male · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/HOZrfHdrnpe9pZlWrIwZoq4cDsX2/voices/TumdjBNWanlT3ysvclWh/UtdbtjoD1JNS4TtqyzwM.mp3)

**Peter** (`elevenlabs:ZthjuvLPty3kTMaNKVKb`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/T05GPpk2fvSBb625DXd4BJHZtu22/voices/ZthjuvLPty3kTMaNKVKb/2nBO0beUcX6fsrvPZbcE.mp3)

**Peter** (`elevenlabs:d6IbhdqAKkXCCVuJjbie`) — male · young · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/d6IbhdqAKkXCCVuJjbie/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiSE9acmZIZHJucGU5cFpsV3JJd1pvcTRjRHNYMiIsImZpbGVuYW1lIjoiS2RpQWlrV0h6WWlQbkxLRlA5UXYubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Peter** (`elevenlabs:qhEux886xDKbOdF7jkFP`) — male · middle&#95;aged · jutlandic accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/SSkZbuwOOuMWwDdLqxaAaVoAaI63/voices/qhEux886xDKbOdF7jkFP/CN2AcSQbdFelH935S6wh.mp3)

**Peter K** (`elevenlabs:406EiNlYvqFqcz3vsnOm`) — male · middle&#95;aged · sofia accent [▶](https://storage.googleapis.com/eleven-public-prod/hgPss3Iyr5U8wTXr6MepRnIRJJL2/voices/406EiNlYvqFqcz3vsnOm/818538f8-865a-46b9-8b0b-44cf97379ac5.mp3)

**Petra** (`elevenlabs:XOgpjkYNnVH5W7ZAlLYg`) — female · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/user_2201kdw955vdepgvjzhs3me9qrjz/voices/XOgpjkYNnVH5W7ZAlLYg/p6bksLPTNhJxSsPggel5.mp3)

**Piotr** (`elevenlabs:o2xdfKUpc1Bwq7RchZuW`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/WREaahKO7NZBbjp6DTUFGPrnqHD3/voices/o2xdfKUpc1Bwq7RchZuW/FVTB9TXCDzUSEKDPzIvD.mp3)

**Piret** (`elevenlabs:kWXj353oWuglsljFXgLz`) — female · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/kWXj353oWuglsljFXgLz/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiIxZGEwNmVhNjc5YTU0OTc1YWQ5NmEyMjIxZmU2NTMwZCIsImZpbGVuYW1lIjoiYVZxSTkzcW1OVFRtNmNhaXYyUkkubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Prajakta** (`elevenlabs:4QmRQP2RqsuTD7HT9MkW`) — female · young [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/4QmRQP2RqsuTD7HT9MkW/adG4JLiWTw4HrBIpOR71.mp3)

**Prince Nur** (`elevenlabs:gJEfHTTiifXEDmO687lC`) — male · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/fdf00c0e5bee40abad820eb9de6a0acc/voices/gJEfHTTiifXEDmO687lC/bvLjXgefFonQ8qV9UFjN.mp3)

**Prince Nur** (`elevenlabs:oKxkBkm5a8Bmrd1Whf2c`) — male · young · moscow accent [▶](https://api.us.elevenlabs.io/v1/voices/oKxkBkm5a8Bmrd1Whf2c/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiSmx2QWZ6SEhuTlJXWUdxZnBjZndhd0Qyak9mMSIsImZpbGVuYW1lIjoiUG85bTZodkNDalg1QThSejZhMEgubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Priyanka** (`elevenlabs:BpjGufoPiobT79j2vtj4`) — female · young · british accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/BpjGufoPiobT79j2vtj4/nnScGYRfT6p1IunkE3T4.mp3)

**Professor Bill** (`elevenlabs:lnieQLGTodpbhjpZtg1k`) — male · middle&#95;aged · american accent [▶](https://api.us.elevenlabs.io/v1/voices/lnieQLGTodpbhjpZtg1k/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiRDI0SUdGOW50dmVMSGpXVWFWelZwY1BvcmE4MiIsImZpbGVuYW1lIjoiYzdjNTFhNDktYTlkOC00NTk0LWFiMzQtZDcwNTFiODI2YTlhLm1wMyIsInRpbWVzdGFtcCI6MTc5MjE4MDgwMDAwMDAwMH0%3D)

**Putra** (`elevenlabs:RWiGLY9uXI70QL540WNd`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/RWiGLY9uXI70QL540WNd/K9KyX0PpKq51sEVudfou.mp3)

**Putri Maharani** (`elevenlabs:I7sakys8pBZ1Z5f0UhT9`) — female · middle&#95;aged · javanese accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/kpstv3iMbHg7V8ZE8rXn9zVKouq1/voices/I7sakys8pBZ1Z5f0UhT9/46f47948-560b-4921-bdbe-d59b885a0a7f.mp3)

**Quentin** (`elevenlabs:Aa6nEBJJMKJwJkCx8VU2`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/f05ba25e25fc468d8f10e4da894d36b7/voices/Aa6nEBJJMKJwJkCx8VU2/Jjk2LhXGigKZzoLINPd2.mp3)

**Rachelle** (`elevenlabs:ZT9u07TYPVl83ejeLakq`) — female · young · american accent [▶](https://api.us.elevenlabs.io/v1/voices/ZT9u07TYPVl83ejeLakq/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiI4MzExYWUwNTczYTA0NjcyOTFlZjI1Yjc1ZmIzNDA0OCIsImZpbGVuYW1lIjoid2kwTlVFOFdWYWFMaGQwUnhHWjQubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Raju** (`elevenlabs:3gsg3cxXyFLcGIfNbM6C`) — male · middle&#95;aged · indian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/514d94e9241c48e8b7905375729c436f/voices/3gsg3cxXyFLcGIfNbM6C/rGzUET9JqnvDlrj9gNqJ.mp3)

**Raju** (`elevenlabs:eyVoIoi3vo6sJoHOKgAc`) — male · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/514d94e9241c48e8b7905375729c436f/voices/eyVoIoi3vo6sJoHOKgAc/C9WIXpkv2mwy0PwQX3Z2.mp3)

**Raju** (`elevenlabs:pzxut4zZz4GImZNlqQ3H`) — male · young · indian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/pzxut4zZz4GImZNlqQ3H/hlkt0YAChzGPU2chOGvs.mp3)

**Raju** (`elevenlabs:zT03pEAEi0VHKciJODfn`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/zT03pEAEi0VHKciJODfn/E1SwTL1qIKPkIxyZQQfk.mp3)

**Ramaa** (`elevenlabs:ZhJ5LanYnCmLKQUXvsV7`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/514d94e9241c48e8b7905375729c436f/voices/ZhJ5LanYnCmLKQUXvsV7/kwjajADpixsAApuYbsSB.mp3)

**Ramaa** (`elevenlabs:wiDlejywCB3MR5QRP1k5`) — male · middle&#95;aged · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/wiDlejywCB3MR5QRP1k5/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJlZDliMDVlNjMyNGM0NTc2ODU0OTAzNTJlOWExZWM5MCIsImZpbGVuYW1lIjoiSWo1NEh2QzZVd2x6WUZnV01hQjAubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Ranbir** (`elevenlabs:2iAXJEMO2o0PqUHzvZwQ`) — male · middle&#95;aged · indian accent [▶](https://api.us.elevenlabs.io/v1/voices/2iAXJEMO2o0PqUHzvZwQ/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJlZDliMDVlNjMyNGM0NTc2ODU0OTAzNTJlOWExZWM5MCIsImZpbGVuYW1lIjoiNkQyYU5tdWw0Q3pubjlwWkZpaDMubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Ranbir** (`elevenlabs:9PvnT6XRzlljoaDG6Knu`) — male · middle&#95;aged · indian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/514d94e9241c48e8b7905375729c436f/voices/9PvnT6XRzlljoaDG6Knu/ArSYCYa2rKv1tzCta30v.mp3)

**Raqib** (`elevenlabs:TMoHpmi3HTyjpoLh2KMT`) — male · young [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/TMoHpmi3HTyjpoLh2KMT/1vme1u9dvh0i2DjUcZDn.mp3)

**Raquel** (`elevenlabs:GDzHdQOi6jjf8zaXhCYD`) — female · young · brazilian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/t1nBFVlw8ahi8WVJ0bXtyohGNAI2/voices/GDzHdQOi6jjf8zaXhCYD/LCt0ufE4oVO5zb1QbhsQ.mp3)

**Rasmus** (`elevenlabs:3jMasSOd05IQvSnHSd6B`) — male · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/3jMasSOd05IQvSnHSd6B/SwDkw8Alb5yngLk5L5IQ.mp3)

**Reva** (`elevenlabs:UT6USLtoAlXHj5k4sOLY`) — female · middle&#95;aged [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/UT6USLtoAlXHj5k4sOLY/5JdIhu9pKU7Tjown3dtJ.mp3)

**Reva** (`elevenlabs:o85TqPN3F4P7dWae2paA`) — female · middle&#95;aged [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/o85TqPN3F4P7dWae2paA/Ox54OVe0GGi6DP8GWIyy.mp3)

**Rex Thunder** (`elevenlabs:mtrellq69YZsNwzUSyXh`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/b2109416c7514449a5f06540d10f0e73/voices/mtrellq69YZsNwzUSyXh/HI2RU95dZS3K8lka30TH.mp3)

**Richard Yu** (`elevenlabs:fJE3lSefh7YI494JMYYz`) — male · middle&#95;aged [▶](https://storage.googleapis.com/eleven-public-prod/r8nrP4ahK4VM4NiJ8nkMgk9Zv3f1/voices/fJE3lSefh7YI494JMYYz/7671be20-4b1f-4f87-ae0c-068964fdad00.mp3)

**Riley** (`elevenlabs:hA4zGnmTwX2NQiTRMt7o`) — female · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/e2c52f9641c54df8b869fd5d3c9ce4f4/voices/hA4zGnmTwX2NQiTRMt7o/QOnjpHcGLd6v1isrcubk.mp3)

**River** (`elevenlabs:wkqe33083YLBV35we7yB`) — female · young · african american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/19cb3e668a9a49f4b2eed6a74faffc84/voices/wkqe33083YLBV35we7yB/c6b92b11-33d0-4851-a6f4-528ac30628c4.mp3)

**Riya Rao** (`elevenlabs:vYENaCJHl4vFKNDYPr8y`) — female · middle&#95;aged · indian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/514d94e9241c48e8b7905375729c436f/voices/vYENaCJHl4vFKNDYPr8y/4hliaQMin59yWW7TJTqB.mp3)

**Riya Rao** (`elevenlabs:wlmwDR77ptH6bKHZui0l`) — female · middle&#95;aged · indian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/514d94e9241c48e8b7905375729c436f/voices/wlmwDR77ptH6bKHZui0l/vDP823KvNyKcS3acBpIF.mp3)

**Roberta** (`elevenlabs:RGymW84CSmfVugnA5tvA`) — female · young · brazilian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/d2d6d8fb79be40a2a3a1599d78da8346/voices/RGymW84CSmfVugnA5tvA/3vmILerGd3NQICCWM4Wa.mp3)

**Rok** (`elevenlabs:P34CBmxe88icH8Itc8u9`) — male · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/P34CBmxe88icH8Itc8u9/YxyukR0OmSmpQbTkWjhM.mp3)

**Rokas** (`elevenlabs:J4hBweML8Zvda0PeTP7t`) — male · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/J4hBweML8Zvda0PeTP7t/hVYS5b64FybgjGwIpUbm.mp3)

**Roland Rodriguez** (`elevenlabs:iZURAYccQtQd12U8kEcq`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/y62hwvXQhASZI2O6zPoLb5Hjkzy2/voices/iZURAYccQtQd12U8kEcq/NQy5nQOHZBEbP8uKlftB.mp3)

**Rowan** (`elevenlabs:kLhAstPcnnPxqzk6gS5i`) — male · middle&#95;aged · british accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/8rbGDvAxYshgeKWdI4OE6PHOtQT2/voices/kLhAstPcnnPxqzk6gS5i/xJJZFNzM004Xa0NW2cRX.mp3)

**Ruhaan** (`elevenlabs:siw1N9V8LmYeEWKyWBxv`) — male · middle&#95;aged · indian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/514d94e9241c48e8b7905375729c436f/voices/siw1N9V8LmYeEWKyWBxv/cBmcFAhsEDTnsoNcP2Vr.mp3)

**Russell Flemming** (`elevenlabs:pjaLAvgVlOPFqXDLNM3V`) — male · middle&#95;aged · american accent [▶](https://api.us.elevenlabs.io/v1/voices/pjaLAvgVlOPFqXDLNM3V/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiaVh6emduVUNmWVludXBHSnlBSlpIR1dtTkVXMiIsImZpbGVuYW1lIjoialVENDl2TXVwQjJYSXY1UktnMEcubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Ruth** (`elevenlabs:yO6w2xlECAQRFP6pX7Hw`) — female · middle&#95;aged · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/yO6w2xlECAQRFP6pX7Hw/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJhNDA2ODk2NDE4Zjg0Y2ViYmE2NjAzYTA2OTYwODE0OSIsImZpbGVuYW1lIjoiOUkwZ0lueG5hSkg4Vm1IdENnZGEubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Ryan Kurk** (`elevenlabs:rU18Fk3uSDhmg5Xh41o4`) — male · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/rU18Fk3uSDhmg5Xh41o4/1ssldWxzIJ4T23tMR561.mp3)

**Réka** (`elevenlabs:E8fGKK3OUNrGTdmkyRdt`) — female · middle&#95;aged · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/E8fGKK3OUNrGTdmkyRdt/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiIxZGEwNmVhNjc5YTU0OTc1YWQ5NmEyMjIxZmU2NTMwZCIsImZpbGVuYW1lIjoiYjZlMmU4ZTUtM2RiOS00YmJjLWJmYTEtYmZjYzAyOTc4NDkxLm1wMyIsInRpbWVzdGFtcCI6MTc5MjE4MDgwMDAwMDAwMH0%3D)

**Saavi** (`elevenlabs:H8bdWZHK2OgZwTN7ponr`) — female · young · indian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/H8bdWZHK2OgZwTN7ponr/K5VNnxGKfEVi5rKnH4du.mp3)

**Sai Datta** (`elevenlabs:f4UZfBDD7d4QR1DcXAMf`) — male · middle&#95;aged [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/f4UZfBDD7d4QR1DcXAMf/SbrN3HYvTpIYn4WCuGXT.mp3)

**Saira** (`elevenlabs:hA0RyxVmITMttngSpcOF`) — female · young [▶](https://api.us.elevenlabs.io/v1/voices/hA0RyxVmITMttngSpcOF/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJlZDliMDVlNjMyNGM0NTc2ODU0OTAzNTJlOWExZWM5MCIsImZpbGVuYW1lIjoiTlZEOWtIeXFVUUY5bE1reTJ4Z3QubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Salma** (`elevenlabs:a1KZUXKFVFDOb33I1uqr`) — female · young · levantine accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/a1KZUXKFVFDOb33I1uqr/UiaMs7jj02K2CGN2TPAU.mp3)

**Sam** (`elevenlabs:scOwDtmlUjD3prqpp97I`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/60df5e8e85434c87b586860524fe605c/voices/scOwDtmlUjD3prqpp97I/tjCTVpjaOxteXatbVF2L.mp3)

**Samanta** (`elevenlabs:fQmr8dTaOQq116mo2X7F`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/f5cf7717b1b243c68376b06b4096e065/voices/fQmr8dTaOQq116mo2X7F/ohr3Oy4QHzzrbwm1BcEi.mp3)

**Samara X** (`elevenlabs:19STyYD15bswVz51nqLf`) — female · middle&#95;aged · british accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/65ce3d25b2034bf0b490a868052eff08/voices/19STyYD15bswVz51nqLf/zl9HbPmiEEiOdhvLunad.mp3)

**Sami Real** (`elevenlabs:O4cGUVdAocn0z4EpQ9yF`) — female · young · american accent [▶](https://api.us.elevenlabs.io/v1/voices/O4cGUVdAocn0z4EpQ9yF/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoidVVnRjBIV2NrN1BIYlpIY2YwS2lsWWZSZ3ZrMSIsImZpbGVuYW1lIjoiOTM3ZmU5YmMtY2Y4My00NmFkLTkxODAtMjQ3ZWRhM2Q1NzViLm1wMyIsInRpbWVzdGFtcCI6MTc5MjE4MDgwMDAwMDAwMH0%3D)

**Samitha** (`elevenlabs:OVkoEbwxsYHiSRMFV9t3`) — female · middle&#95;aged [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/OVkoEbwxsYHiSRMFV9t3/SMKm03WSCVb1XMjOknac.mp3)

**Sana** (`elevenlabs:XKV307Y3BonMEUh5pCNM`) — female · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/XKV307Y3BonMEUh5pCNM/JjBzVdiqswmd3KylYxzS.mp3)

**Sana** (`elevenlabs:tKZQTIqwDrPzLv6MrPxF`) — female · middle&#95;aged · indian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/514d94e9241c48e8b7905375729c436f/voices/tKZQTIqwDrPzLv6MrPxF/OqxYamtdRapLaSmYnWK0.mp3)

**Sanna Hartfield** (`elevenlabs:4xkUqaR9MYOJHoaC1Nak`) — female · middle&#95;aged · stockholm accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/4xkUqaR9MYOJHoaC1Nak/l4PwfhXHwvKzA0G9XP46.mp3)

**Sanna Hartfield** (`elevenlabs:aSLKtNoVBZlxQEMsnGL2`) — female · middle&#95;aged · stockholm accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/aSLKtNoVBZlxQEMsnGL2/g7yysxvG83AAWczMihDs.mp3)

**Sapphire** (`elevenlabs:zmcVlqmyk3Jpn5AVYcAL`) — female · young · chinese accent [▶](https://api.us.elevenlabs.io/v1/voices/zmcVlqmyk3Jpn5AVYcAL/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiTW02eHNwOTdNQ2I3WW85MHRJSzNZTmpkN0FzMiIsImZpbGVuYW1lIjoibmZiMlNITUtOM0sxV1pBTlgwV08ubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Sara** (`elevenlabs:XTa3iQyMA6f1qrI4F6kZ`) — female · young · modern standard accent [▶](https://api.us.elevenlabs.io/v1/voices/XTa3iQyMA6f1qrI4F6kZ/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJmYjEzYjVlZmU0Y2I0MGQzOWRhMjAxYjQ2ZmFjMjJlYiIsImZpbGVuYW1lIjoiSXgzc3NNNXhZeEtnUk5lVjVURW0ubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Sara** (`elevenlabs:jAAHNNqlbAX9iWjJPEtE`) — female · young · jordanian accent [▶](https://api.us.elevenlabs.io/v1/voices/jAAHNNqlbAX9iWjJPEtE/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiI0YTkzYzU2ODllZTM0MDk5ODA5NTNjZDM2NDU1NTZiZiIsImZpbGVuYW1lIjoidVFZcXVaVmZacVdzZHZ6OVNLeHMubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Sarah** (`elevenlabs:Nhs7eitvQWFTQBsf0yiT`) — female · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/kGguywYBM6ZDW5j5xFRCvBmzqL92/voices/Nhs7eitvQWFTQBsf0yiT/D6QJtXoAUfIBGei8I0WT.mp3)

**Satomi** (`elevenlabs:wcs09USXSN5Bl7FXohVZ`) — female · middle&#95;aged · kyushu accent [▶](https://api.us.elevenlabs.io/v1/voices/wcs09USXSN5Bl7FXohVZ/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJmZmE2MDUxOGY3NmU0NTlkYWVjODI5ZDRlZWRjYjI0MCIsImZpbGVuYW1lIjoiTGNXN25iazRheWtJdEpEdXdFUEsubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Sayali** (`elevenlabs:ObcUVfo3RbQv9i2RBbAe`) — female · young [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/ObcUVfo3RbQv9i2RBbAe/btt1Fp0Fr4M1NlrncSgG.mp3)

**Seeta** (`elevenlabs:QKyvRuehpb8zB3cRkzIn`) — female · middle&#95;aged [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/QKyvRuehpb8zB3cRkzIn/nC3mQW1Xhi8S4ABSIL5g.mp3)

**Serban Popescu** (`elevenlabs:8nBBDfYxYXmDNaqTCxPH`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/nzv6QegAXCVwuS5mwHKKZJ5UY222/voices/8nBBDfYxYXmDNaqTCxPH/zbQ6FRtttuemlxCj28dk.mp3)

**Serge de Beer** (`elevenlabs:UNBIyLbtFB9k7FKW8wJv`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/099d1dc9ca1d4ca8922ad67d26a8327d/voices/UNBIyLbtFB9k7FKW8wJv/fS1o8uRWFIg7F0vzJ3Jn.mp3)

**Seulki** (`elevenlabs:ksaI0TCD9BstzEzlxj4q`) — female · middle&#95;aged · seoul accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/2IzgfYjaHgaiOZ7ej6G902W3kKh1/voices/ksaI0TCD9BstzEzlxj4q/bizji0eQlVSfyOy39GQ7.mp3)

**Sharad** (`elevenlabs:8fqGzH80bdkm2UseeV9f`) — male · middle&#95;aged [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/8fqGzH80bdkm2UseeV9f/jBEaNFvmV9aJUEka1Yt1.mp3)

**Shira** (`elevenlabs:1WOvbtTEb49xcgFUMDu9`) — female · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/1WOvbtTEb49xcgFUMDu9/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiIxZGEwNmVhNjc5YTU0OTc1YWQ5NmEyMjIxZmU2NTMwZCIsImZpbGVuYW1lIjoiT0xaNGFSOHAxWXNBb1Zma2I3UlUubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Shizuka** (`elevenlabs:WQz3clzUdMqvBf0jswZQ`) — female · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/RMHdgNhg2pS9x3XNkTco8dWZO9K2/voices/WQz3clzUdMqvBf0jswZQ/i6AmEdWw199PgEgmzXn0.mp3)

**Shrey** (`elevenlabs:C9v09R5AIM6tOX6Fn06I`) — male · young [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/C9v09R5AIM6tOX6Fn06I/6AGPfg1zAbciAzLIVQJW.mp3)

**Sia** (`elevenlabs:KYiVPerWcenyBTIvWbfY`) — female · young · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/KYiVPerWcenyBTIvWbfY/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJlZDliMDVlNjMyNGM0NTc2ODU0OTAzNTJlOWExZWM5MCIsImZpbGVuYW1lIjoiZ2RTSGI5UlRLTkFRM1FDRmlPOXYubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Signe** (`elevenlabs:6H9DAoiqXpVkBN5eOmIS`) — female · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/6H9DAoiqXpVkBN5eOmIS/63c8f5f8-6b07-42dd-90d3-9f7e7f2463c2.mp3)

**Simarpreet** (`elevenlabs:m9A8WbprzttdIYhmNwdx`) — female · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/m9A8WbprzttdIYhmNwdx/BSyAEW2MGaxYkuU4BQuV.mp3)

**Simran** (`elevenlabs:9UNN0bXPo2Z6G30E64lz`) — female · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/9UNN0bXPo2Z6G30E64lz/YTMgddplNSgvhr5p3T08.mp3)

**Simran** (`elevenlabs:9w21nMuk8CWXIME31V1S`) — female · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/9w21nMuk8CWXIME31V1S/jD5e2Ll3kkLl76h4QDjK.mp3)

**Sini** (`elevenlabs:8X97zFR9k9pK2xyFI7Nr`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/8X97zFR9k9pK2xyFI7Nr/633c4ea5-d305-469a-85cf-f356b7928bf7.mp3)

**Siren** (`elevenlabs:eXpIbVcVbLo8ZJQDlDnl`) — female · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/cbfaa74d559547979fa92c07eae49b0f/voices/eXpIbVcVbLo8ZJQDlDnl/nvbKCMRoZnwNqgIhVjJE.mp3)

**Siriporn** (`elevenlabs:v2NF9R77fF8wZRdbGYTg`) — female · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/v2NF9R77fF8wZRdbGYTg/UczJyRhAwDdHK4XE7577.mp3)

**Slobodan** (`elevenlabs:adxhr4Ei7ASJ3Cz7fxwX`) — male · middle&#95;aged [▶](https://storage.googleapis.com/eleven-public-prod/syjNf9g6SwUCrX6i9O9x6sWdOkJ3/voices/adxhr4Ei7ASJ3Cz7fxwX/02bb0f7c-500b-40cc-a528-5217cf9d2258.mp3)

**Somchai** (`elevenlabs:XLXcyPK1jTjw1pYLLcM9`) — male · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/XLXcyPK1jTjw1pYLLcM9/C8YQH9ZwkciuYabRMTwl.mp3)

**Sophia** (`elevenlabs:7smwXrU3C1PfaspIIUZB`) — female · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/7smwXrU3C1PfaspIIUZB/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiYzNKT0lob0w2bE83b0RZcUJaZ1loTjExb3B2MiIsImZpbGVuYW1lIjoiWHZEVm5VMGJ5Q05FOWpxZjY3TXoubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Spuds Oxley** (`elevenlabs:NOpBlnGInO9m6vDvFkFC`) — male · old · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/64971298bfc24086b69026970a21f1f9/voices/NOpBlnGInO9m6vDvFkFC/M4xySW4rr1SbAKKwMAtI.mp3)

**Srivatsa** (`elevenlabs:K9wMnqOxfnDmtKBIH8oT`) — male · middle&#95;aged [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/K9wMnqOxfnDmtKBIH8oT/u9GkBvyBvoTRJBNXUabj.mp3)

**Srivatsa** (`elevenlabs:UeUC009F3NYPIArcZmq0`) — male · middle&#95;aged [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/UeUC009F3NYPIArcZmq0/y0EPJjZK1nAHRrvidu2P.mp3)

**Stacy** (`elevenlabs:hkfHEbBvdQFNX4uWHqRF`) — female · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/caa5a1882b534d379d7d1037f8cd2248/voices/hkfHEbBvdQFNX4uWHqRF/n5W0eNZRtazdqGAfoBDR.mp3)

**Stefan** (`elevenlabs:5lDS2fR0uHPW5ShjjPzv`) — male · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/5lDS2fR0uHPW5ShjjPzv/gLAhmF22jmjRyop8549F.mp3)

**Stella Gu** (`elevenlabs:BqljjWyTnrioXPCNkCd4`) — female · middle&#95;aged · beijing mandarin accent [▶](https://api.us.elevenlabs.io/v1/voices/BqljjWyTnrioXPCNkCd4/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiWmhOTkFOUmNqSmZGUmdLckZxRFhyZkVQcVFBMyIsImZpbGVuYW1lIjoiVDZ0dFV3V3k1WG85NmplNlo1ZncubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Stephanie** (`elevenlabs:oAoF4NpW2Aqxplg9HdYB`) — female · middle&#95;aged · canadian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/7f98b395fb75455aafa5cb433a285f76/voices/oAoF4NpW2Aqxplg9HdYB/LKsMEF5JsKZzDfxEuUTw.mp3)

**Steven** (`elevenlabs:QbrR6b6YCLjyBkFKH5Xz`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/2VyQuh9mK9cet6bNZziZ2PQCn1J2/voices/QbrR6b6YCLjyBkFKH5Xz/guVTJbRuTM9JhVlqqk3v.mp3)

**Sufi** (`elevenlabs:HkrBPy9A2svfb9tZ9YaL`) — male · middle&#95;aged [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/HkrBPy9A2svfb9tZ9YaL/EYpJhSMqis0Ge3pTgTtr.mp3)

**Suk Yee** (`elevenlabs:7rrBp44bogxpbQBDkenR`) — female · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/7rrBp44bogxpbQBDkenR/FHB7s0lpbsTugFYwG9AG.mp3)

**Sully** (`elevenlabs:wAGzRVkxKEs8La0lmdrE`) — male · old · american accent [▶](https://storage.googleapis.com/eleven-public-prod/Bo6DtogKR9MFeVzUzR8msFIzsz92/voices/wAGzRVkxKEs8La0lmdrE/694524f9-fac6-4c16-a9de-8bb69e178312.mp3)

**Sunaina** (`elevenlabs:8VTILyp3oibFrXwPpZJQ`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/8VTILyp3oibFrXwPpZJQ/6iASXNAHebUVkU85PL5c.mp3)

**Sunaina** (`elevenlabs:AA6iXlJYcLQWoTQnJw8E`) — female · middle&#95;aged [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/AA6iXlJYcLQWoTQnJw8E/WctD6eoqAyvBCjWJo0Ix.mp3)

**Susi** (`elevenlabs:v3V1d2rk6528UrLKRuy8`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/1KI0h0RJuscE0Ta9tVvydENJ9JF3/voices/v3V1d2rk6528UrLKRuy8/8aab3a1d-2faf-4de4-b229-f3a2ebb21c43.mp3)

**Swapnil J** (`elevenlabs:sY45IbgHsqwL3lqU9fLk`) — male · young [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/sY45IbgHsqwL3lqU9fLk/1OunXtw1dq72tVoOgGNX.mp3)

**Swati S** (`elevenlabs:q4yUdydpWxqfmkQH7gK7`) — female · young [▶](https://api.us.elevenlabs.io/v1/voices/q4yUdydpWxqfmkQH7gK7/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJlZDliMDVlNjMyNGM0NTc2ODU0OTAzNTJlOWExZWM5MCIsImZpbGVuYW1lIjoid0JKWHQzYUdDbjhjNFNZR0huajQubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Søren** (`elevenlabs:xj6X4BCUsv9oxohm1E8o`) — male · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/0p667waJGmdxAmxAjBz7Bn3ffbs1/voices/xj6X4BCUsv9oxohm1E8o/90bceee2-33ad-4d97-8a44-84bf43c1f600.mp3)

**Taehyung** (`elevenlabs:m3gJBS8OofDJfycyA2Ip`) — male · young · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/m3gJBS8OofDJfycyA2Ip/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoicUV5SzNDYlZGV2hlRk85c2M5cVNOZ0h6eFRDMiIsImZpbGVuYW1lIjoiU2xwcVFIV2Jzblc4U1JTTWhsSE8ubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Tamara** (`elevenlabs:mcVGxV1BuvLf8VfWWB55`) — female · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/mcVGxV1BuvLf8VfWWB55/Fm3vIxo8cG83EHXouGEB.mp3)

**Tara** (`elevenlabs:P7vsEyTOpZ6YUTulin8m`) — female · young · indian accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/P7vsEyTOpZ6YUTulin8m/S37OM3vG5E7e33WFgs8r.mp3)

**Tarini** (`elevenlabs:kiaJRdXJzloFWi6AtFBf`) — female · young · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/kiaJRdXJzloFWi6AtFBf/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJlZDliMDVlNjMyNGM0NTc2ODU0OTAzNTJlOWExZWM5MCIsImZpbGVuYW1lIjoib2pKNHU5WXFNamhDY3RlUzFxZ2oubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Tatiana Martin** (`elevenlabs:2rigMbVWLdqtBSCahJFX`) — female · middle&#95;aged · latin american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/8RYUsFHsalUXjwVG0LjhNwH1j022/voices/2rigMbVWLdqtBSCahJFX/fZWd6mLqzMJWcNXOh3ea.mp3)

**Teddy Andersen** (`elevenlabs:EU14UTtflRFtOAuWCuVe`) — male · middle&#95;aged · zealandic accent [▶](https://api.us.elevenlabs.io/v1/voices/EU14UTtflRFtOAuWCuVe/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiI2ZTk4NzkzNWQxZWI0OGI4YTlhZDUxMmU4ODc0NGJkOCIsImZpbGVuYW1lIjoiUHJBczNxRGM4S25yTkp1WTdtWHIubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Theos** (`elevenlabs:n0vzWypeCK1NlWPVwhOc`) — male · middle&#95;aged · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/n0vzWypeCK1NlWPVwhOc/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiVGNpRkJxM0JZcGFtdk9iVnlsU0pncTM2RkJMMiIsImZpbGVuYW1lIjoiMnNuZUE3MlZ4TUE1TXU3bjFoWWgubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Tia Mirza** (`elevenlabs:OUBnvvuqEKdDWtapoJFn`) — female · middle&#95;aged · indian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/OUBnvvuqEKdDWtapoJFn/dWE1zZlUmhuFMGc6adVz.mp3)

**Titan** (`elevenlabs:dtSEyYGNJqjrtBArPCVZ`) — male · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/w8lO88ok8DfgaX1qrZryMJbLze32/voices/dtSEyYGNJqjrtBArPCVZ/Pa4Rn2iJ0mvYrc3PU3Vy.mp3)

**Todd** (`elevenlabs:g14YnDYCsy3k7XLlcKlO`) — male · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/user_3501kf3aq734ewy977wwfpybmzz3/voices/g14YnDYCsy3k7XLlcKlO/8PoqmGvhrKkyBTo11v1X.mp3)

**Tomer** (`elevenlabs:yGpVFXFoImvRvaURKypy`) — male · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/yGpVFXFoImvRvaURKypy/8F4UV5JfF9FBLm9O842M.mp3)

**Toomas** (`elevenlabs:znlmOHkG3zvqwPtBn66G`) — male · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/znlmOHkG3zvqwPtBn66G/rBk0IC8Pb9BeZ7e4GJU7.mp3)

**Tri Nugraha** (`elevenlabs:lFjzhZHq0NwTRiu2GQxy`) — male · young [▶](https://storage.googleapis.com/eleven-public-prod/RQwIb5Id6wd09VubvX1MqxHmeir2/voices/lFjzhZHq0NwTRiu2GQxy/f97f401a-cc7c-4b82-9d0a-fd12931225fb.mp3)

**Trieu Duong** (`elevenlabs:UsgbMVmY3U59ijwK5mdh`) — male · young · southern accent [▶](https://api.us.elevenlabs.io/v1/voices/UsgbMVmY3U59ijwK5mdh/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJhODZjMjc1ZmQyMTk0ZjcwOTFkMGMyNjdmYWVmYmRhYyIsImZpbGVuYW1lIjoiZjkwMGEwNDAtMGFiZS00N2RiLWFlYjQtYzIwYjYzMDU2NDMzLm1wMyIsInRpbWVzdGFtcCI6MTc5MjE4MDgwMDAwMDAwMH0%3D)

**Tripti** (`elevenlabs:MwUMLXurEzSN7bIfIdXF`) — female · middle&#95;aged · indian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/MwUMLXurEzSN7bIfIdXF/TrdTr9Wax8NgyefaqiuS.mp3)

**True** (`elevenlabs:tZssYepgGaQmegsMEXjK`) — male · middle&#95;aged · american accent [▶](https://api.us.elevenlabs.io/v1/voices/tZssYepgGaQmegsMEXjK/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJiMjEwOTQxNmM3NTE0NDQ5YTVmMDY1NDBkMTBmMGU3MyIsImZpbGVuYW1lIjoiekJrWVplZGp0NFlxYWRzeXVzZFMubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Trung Caha** (`elevenlabs:ueSxRO0nLF1bj93J2hVt`) — male · middle&#95;aged · northern accent [▶](https://api.us.elevenlabs.io/v1/voices/ueSxRO0nLF1bj93J2hVt/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoieTZmS1RGRUc3RWUxN1oxekRaSG9HRk5zVktZMiIsImZpbGVuYW1lIjoiZGU0YWM2ZTktNzVkNy00NGM1LWJiNTAtMjMwNWRmZGRhMjgwLm1wMyIsInRpbWVzdGFtcCI6MTc5MjE4MDgwMDAwMDAwMH0%3D)

**Tsz Hin** (`elevenlabs:HpEko7A3nBbfFmRdlVW4`) — male · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/HpEko7A3nBbfFmRdlVW4/K8e1LngSIE2swfybQwH5.mp3)

**Tyler Kurk** (`elevenlabs:raMcNf2S8wCmuaBcyI6E`) — male · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/raMcNf2S8wCmuaBcyI6E/i7eNgfmXUnONqBYrrQpn.mp3)

**Ugne** (`elevenlabs:EnnOVsVNRrPWieNQUZem`) — female · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/EnnOVsVNRrPWieNQUZem/lTQkPeqEkdMxHolwwdMK.mp3)

**Vagmin** (`elevenlabs:ZoV3Y9cqdke2p8nzz7XP`) — male · middle&#95;aged [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/ZoV3Y9cqdke2p8nzz7XP/qsLxyqXCSRNGeZBDlCnS.mp3)

**Vaino** (`elevenlabs:Gp43kq9FsSlavD7esRtx`) — male · old · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/k6cgt5bEPYPPZl30WtnGqsy6Uv62/voices/Gp43kq9FsSlavD7esRtx/156dc605-e2bb-4d9e-80ce-2eb1c893e055.mp3)

**Vandana** (`elevenlabs:eh5YJlyB5bmWfcmcEsLN`) — female · young [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/eh5YJlyB5bmWfcmcEsLN/3C9pXQVP1UUXeFWQ1bE8.mp3)

**Vanessa** (`elevenlabs:8DzKSPdgEQPaK5vKG0Rs`) — female · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/pJj966DxwEg3jXdcUkoTbMzkPsL2/voices/8DzKSPdgEQPaK5vKG0Rs/AeRt8yvbNanY84fSNvRc.mp3)

**Varalaxmi** (`elevenlabs:imphBib61OiJ8r9IfSGe`) — female · middle&#95;aged [▶](https://api.us.elevenlabs.io/v1/voices/imphBib61OiJ8r9IfSGe/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJlZDliMDVlNjMyNGM0NTc2ODU0OTAzNTJlOWExZWM5MCIsImZpbGVuYW1lIjoiVHVROFlRSU5zUVdkSnJmWmJJNlgubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Veda Sky** (`elevenlabs:XcXEQzuLXRU9RcfWzEJt`) — female · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/XcXEQzuLXRU9RcfWzEJt/nc3yiwrfwrNGi01JgyXu.mp3)

**Vera** (`elevenlabs:xjlfQQ3ynqiEyRpArrT8`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/8Ouy1S5qE8Ww08g1I2kbgNdWvDV2/voices/xjlfQQ3ynqiEyRpArrT8/fb50230c-5d38-4fb6-9c8f-3db2aa5d7847.mp3)

**Victoria** (`elevenlabs:O31r762Gb3WFygrEOGh0`) — female · young · parisian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/8883bfc00193440ba374c3ecd71610b5/voices/O31r762Gb3WFygrEOGh0/x79aDNW4Q3qgJKq1svTL.mp3)

**Victoria** (`elevenlabs:qSeXEcewz7tA0Q0qk9fH`) — female · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/228d4047a7e64c3ca68131d246d93ef2/voices/qSeXEcewz7tA0Q0qk9fH/zDds5EkXR72GXolhj81V.mp3)

**Vijaya** (`elevenlabs:GGBhcpAgpjSrBIr5MQwR`) — female · middle&#95;aged [▶](https://api.us.elevenlabs.io/v1/voices/GGBhcpAgpjSrBIr5MQwR/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJlZDliMDVlNjMyNGM0NTc2ODU0OTAzNTJlOWExZWM5MCIsImZpbGVuYW1lIjoib3pNcEhhNGRPaDJPQms0ZHJ0N1QubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Vijayesh** (`elevenlabs:F6apuaOciIF8axVr21FB`) — male · middle&#95;aged [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/F6apuaOciIF8axVr21FB/rbuyPRT3kQApc7QmYFdd.mp3)

**Vijayesh** (`elevenlabs:X4vyuTrbgOdUvArVLv7j`) — male · middle&#95;aged [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/X4vyuTrbgOdUvArVLv7j/6kUEvJE2n0wp7jdEYDL0.mp3)

**Vilde** (`elevenlabs:SUVXSJC7hh41K4FtAVuH`) — female · middle&#95;aged · trøndersk accent [▶](https://api.us.elevenlabs.io/v1/voices/SUVXSJC7hh41K4FtAVuH/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJiZGJiYmQ2MzNmOGE0MzYyYjYwMTQ0ZmVlZjg1ZTE0YiIsImZpbGVuYW1lIjoiNDgzYWYxMTUtMDljMC00MTViLWJmMGEtNDc5Mjc1YTdkMWQ0Lm1wMyIsInRpbWVzdGFtcCI6MTc5MjE4MDgwMDAwMDAwMH0%3D)

**Vinayak** (`elevenlabs:rXW8MF4nX2gHMvBmCDnr`) — male · young [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/rXW8MF4nX2gHMvBmCDnr/e6BU02CXmI4QqSs3hKE5.mp3)

**Violetta** (`elevenlabs:gfKKsLN1k0oYYN9n2dXX`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/Mxxy1mLEQkeyXX75dokAIWz8bel1/voices/gfKKsLN1k0oYYN9n2dXX/Z2oJ1Jb0O555Pu7XDZv4.mp3)

**Vira** (`elevenlabs:nCqaTnIbLdME87OuQaZY`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/mGLUsH9ra4W6rflL9dtShIY2uUu2/voices/nCqaTnIbLdME87OuQaZY/IiRrubwJ498oRvAHRYG3.mp3)

**Viraj** (`elevenlabs:1U02n4nD6AdIZ9CjF053`) — male · young · indian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/514d94e9241c48e8b7905375729c436f/voices/1U02n4nD6AdIZ9CjF053/Db0bXQauCCjtE0uaoDAk.mp3)

**Viraj** (`elevenlabs:Ock0AL5DBkvTUDePt4Hm`) — male · young · indian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/Ock0AL5DBkvTUDePt4Hm/ff4Y7yp5eBWi0BtXZ2hL.mp3)

**Vivianna** (`elevenlabs:9QppwToemG29A6UTSbwz`) — female · young · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/9QppwToemG29A6UTSbwz/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiI4OTc3MjVlYTQxZmI0NmM5OWRkYWI3ZjZmYTNmMmUzZSIsImZpbGVuYW1lIjoic3RoVUIxeEs4YTN3QzhDUWRqQUYubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Vytautas** (`elevenlabs:YzAEMXSQhHOIgNWD4uE9`) — male · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/YzAEMXSQhHOIgNWD4uE9/0LTU132njggUpz1uhNV7.mp3)

**W.L. Oxley** (`elevenlabs:gOkFV1JMCt0G0n9xmBwV`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/64971298bfc24086b69026970a21f1f9/voices/gOkFV1JMCt0G0n9xmBwV/bzq9YIfPb3JoAL953C9C.mp3)

**Will** (`elevenlabs:CstacWqMhJQlnfLPxRG4`) — male · middle&#95;aged · brazilian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1d8116e2c9c14d50affe4a07bc647489/voices/CstacWqMhJQlnfLPxRG4/tAJk8VrzwYKmPAybekMz.mp3)

**William Shanks** (`elevenlabs:8Es4wFxsDlHBmFWAOWRS`) — male · middle&#95;aged · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/D24IGF9ntveLHjWUaVzVpcPora82/voices/8Es4wFxsDlHBmFWAOWRS/sMCtthWYyb65Vblz7xFT.mp3)

**Yael** (`elevenlabs:d4eLZ8u5dfBCsjp4YPyz`) — female · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/1da06ea679a54975ad96a2221fe6530d/voices/d4eLZ8u5dfBCsjp4YPyz/iXnapaW1cRDOi0EuTfjD.mp3)

**Yaroslava** (`elevenlabs:0ZQZuw8Sn4cU0rN1Tm2K`) — female · middle&#95;aged · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/0ZQZuw8Sn4cU0rN1Tm2K/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiR0w0NWU0ZVg5d2NlbmhWVk1FTmVKY3M1b2NJMiIsImZpbGVuYW1lIjoiOTMySGNqbzZDOWdDYXlCakFYNHEubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Yatin** (`elevenlabs:ttyKbP9zTIRyRCN6b2Ye`) — male · young [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/ttyKbP9zTIRyRCN6b2Ye/IC5maW748q7E9nSArUrj.mp3)

**Yatin** (`elevenlabs:z0HCBc2pw7Mdq6koP5os`) — male · young [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/z0HCBc2pw7Mdq6koP5os/9mIHtInYPAVOWEzZdbsh.mp3)

**Yazhini** (`elevenlabs:mGboHvCVOXWYeFL8KTR0`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/mGboHvCVOXWYeFL8KTR0/5hC8nmKZKACaFhQOxVmx.mp3)

**Young Jamal** (`elevenlabs:6OzrBCQf8cjERkYgzSg8`) — male · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/custom/voices/6OzrBCQf8cjERkYgzSg8/YmWdAA5ju6tNyK5Zl104.mp3)

**Yu** (`elevenlabs:fQj4gJSexpu8RDE2Ii5m`) — male · young · taiwan mandarin accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/8OXM7U7aZFcKI05Whl3sOM2HBaN2/voices/fQj4gJSexpu8RDE2Ii5m/xXnDtL0jvbLE622bVoEA.mp3)

**Yui** (`elevenlabs:fUjY9K2nAIwlALOwSiwc`) — female · young · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/L1GYYljlF1PEq09aUQgwwlh7DJm1/voices/fUjY9K2nAIwlALOwSiwc/C79oVJJJuCSBWmwsTJYV.mp3)

**Zafar** (`elevenlabs:QbjoF56fjzQK0OTI4hGt`) — male · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/QbjoF56fjzQK0OTI4hGt/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiIxZGEwNmVhNjc5YTU0OTc1YWQ5NmEyMjIxZmU2NTMwZCIsImZpbGVuYW1lIjoiMGRicVNEandkUmNkY1dyY05ZM0YubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Zara** (`elevenlabs:6VrKLjZfyBIk9AEmnZBI`) — female · young · indian accent [▶](https://api.us.elevenlabs.io/v1/voices/6VrKLjZfyBIk9AEmnZBI/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJlZDliMDVlNjMyNGM0NTc2ODU0OTAzNTJlOWExZWM5MCIsImZpbGVuYW1lIjoiaG1zeFFBUmpmeDFvSHN5VmtYOTUubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Zara** (`elevenlabs:ADd2WEtjmwokqUr0Y5Ad`) — female · young · indian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/514d94e9241c48e8b7905375729c436f/voices/ADd2WEtjmwokqUr0Y5Ad/lfI5PpfdGGtnAfpi0Ol7.mp3)

**Zara** (`elevenlabs:MmQVkVZnQ0dUbfWzcW6f`) — female · young · indian accent [▶](https://storage.googleapis.com/eleven-public-prod/database/workspace/ed9b05e6324c457685490352e9a1ec90/voices/MmQVkVZnQ0dUbfWzcW6f/usBrznzdHvDWwhc7OH2V.mp3)

**Zara** (`elevenlabs:OtEfb2LVzIE45wdYe54M`) — female · young · standard accent [▶](https://api.us.elevenlabs.io/v1/voices/OtEfb2LVzIE45wdYe54M/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ3b3Jrc3BhY2VfaWQiOiJlZDliMDVlNjMyNGM0NTc2ODU0OTAzNTJlOWExZWM5MCIsImZpbGVuYW1lIjoiNXlocjNUUUdKWHp5VHpmZWExWVIubXAzIiwidGltZXN0YW1wIjoxNzkyMTgwODAwMDAwMDAwfQ%3D%3D)

**Zara** (`elevenlabs:jqcCZkN6Knx8BJ5TBdYR`) — female · young · american accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/XKwEw9ihVRMYSZkGwKydUfpES0B3/voices/jqcCZkN6Knx8BJ5TBdYR/JKHbp9CMKBoqcDFfzWIf.mp3)

**Zlata** (`elevenlabs:V5O4WAcdw7w3Ccfvma8Z`) — female · middle&#95;aged · standard accent [▶](https://storage.googleapis.com/eleven-public-prod/database/user/Ftqljm09z4hBzS3ZzdbEv4vMI733/voices/V5O4WAcdw7w3Ccfvma8Z/88028689-2447-4c44-b5c4-22a9cc038bb2.mp3)

</Accordion>
</AccordionGroup>

<!-- en: api-reference/custom-voices -->
---
title: "Custom voices"
description: "Request access, clone a voice, track its lifecycle, and use it on an agent."
---

Custom voices let your organization create a reusable agent voice from a
short audio sample. Creation is asynchronous: a new clone starts in `queued`,
moves to `processing`, and finishes as either `ready` or `failed`.

<Note>
  Every endpoint on this page requires
  `Authorization: Bearer sk_live_YOUR_API_KEY`, except a signed preview URL.
  Resources are scoped to the organization associated with the credential.
</Note>

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/voices/policy` | Check access and ThunderPhone quota |
| `POST` | `/v1/voices/quota-requests` | Request access or a larger quota |
| `GET` | `/v1/voices/quota-requests/current` | Retrieve the latest quota request |
| `GET` | `/v1/voices/clones` | List custom voices |
| `POST` | `/v1/voices/clones` | Create a custom voice |
| `GET` | `/v1/voices/clones/{public_id}` | Retrieve a custom voice |
| `PATCH` | `/v1/voices/clones/{public_id}` | Rename a custom voice or set its gender |
| `DELETE` | `/v1/voices/clones/{public_id}` | Delete a custom voice |
| `GET` | `/v1/voices/clones/{public_id}/preview` | Stream the ready voice's MP3 preview |

## Custom voice object

```json
{
  "name": "custom:cv_2f6f90b0e9a34ee8b39be7d1",
  "public_id": "cv_2f6f90b0e9a34ee8b39be7d1",
  "display_name": "Support voice",
  "language": "en",
  "gender": "female",
  "status": "ready",
  "failure_reason": "",
  "created_at": "2026-07-30T14:12:08.317Z",
  "sample_url": "https://api.thunderphone.com/v1/voices/clones/cv_2f6f90b0e9a34ee8b39be7d1/preview?sig=...",
  "agent_id": 42
}
```

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Agent voice value in the form `custom:<public_id>` |
| `public_id` | string | Public identifier used in clone endpoints |
| `display_name` | string | Organization-facing name, 1–100 characters |
| `language` | string | The clone's single language code |
| `gender` | string or null | `male`, `female`, or `null` when the clone was created without one. Set it with `PATCH` |
| `status` | string | `queued`, `processing`, `ready`, or `failed` |
| `failure_reason` | string | Processing failure detail; empty unless the clone failed |
| `created_at` | timestamp | ISO 8601 creation time |
| `sample_url` | string \| null | Signed preview URL when a preview is available; otherwise `null` |
| `agent_id` | integer \| null | The agent the voice was made for, when one was named on create; otherwise `null` |

## Request access and quota

### Check policy

Check whether cloning is enabled and how many of your organization's
ThunderPhone custom voice slots are in use.

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/voices/policy \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

```json Response (200 OK)
{
  "cloning_enabled": true,
  "max_custom_voices": 5,
  "used": 2,
  "custom_voice_surcharge_cents": 1
}
```

| Field | Type | Description |
|-------|------|-------------|
| `cloning_enabled` | boolean | Whether the organization can create custom voices |
| `max_custom_voices` | integer | ThunderPhone custom voice limit for the organization |
| `used` | integer | Non-deleted custom voices currently using that limit |
| `custom_voice_surcharge_cents` | integer | Additional cents per minute when a custom voice is used, for accounts still on their earlier pricing (until December 1, 2026). On the [new pricing](/guides/pricing) there is no custom-voice surcharge: the voice is billed at its provider's list price inside the call |

### Submit a quota request

Use the same flow to request initial access or a larger ThunderPhone limit.
Only one request can be pending for an organization at a time.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/voices/quota-requests \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requested_count": 5,
    "note": "Voices for our support teams"
  }'
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `requested_count` | integer | yes | Requested ThunderPhone custom voice limit; at least 1 |
| `note` | string | no | Context for the request, up to 2,000 characters |

```json Response (201 Created)
{
  "status": "pending",
  "requested_count": 5,
  "created_at": "2026-07-30T13:55:42.104Z"
}
```

| Status | Response | When |
|--------|----------|------|
| `400` | `{"requested_count":"Must be an integer."}` | Count is absent or not an integer |
| `400` | `{"requested_count":"Must be at least 1."}` | Count is less than 1 |
| `400` | `{"note":"Must be 2000 characters or fewer."}` | Note is too long |
| `409` | `{"detail":"A quota request is already pending."}` | The organization already has a pending request |

### Check the latest request

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/voices/quota-requests/current \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

```json Response (200 OK)
{
  "status": "approved",
  "requested_count": 5,
  "created_at": "2026-07-30T13:55:42.104Z",
  "resolved_at": "2026-07-30T14:03:19.880Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `status` | string | `pending`, `approved`, or `denied` |
| `requested_count` | integer | Requested ThunderPhone custom voice limit |
| `created_at` | timestamp | ISO 8601 submission time |
| `resolved_at` | timestamp \| null | ISO 8601 decision time, or `null` while pending |

Returns `404 Not Found` when the organization has never submitted a request.

## Create a custom voice

Upload one WAV or MP3 file as `multipart/form-data`. The sample must contain
3–15 seconds of speech and be no larger than 4 MB. Use one language per
clone, and only upload a voice you have the rights and consent to clone.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/voices/clones \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -F "audio=@support-voice.wav;type=audio/wav" \
  -F "name=Support voice" \
  -F "language=en" \
  -F "gender=female" \
  -F "consent=true"
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `audio` | file | yes | WAV or MP3, no larger than 4 MB, containing 3–15 seconds of speech |
| `name` | string | yes | Display name, 1–100 characters |
| `language` | string | yes | One of `ar`, `zh`, `nl`, `en`, `fr`, `de`, `he`, `hi`, `it`, `ja`, `ko`, `pl`, `pt`, `ru`, or `es` |
| `consent` | boolean | yes | Must be exactly `true` to confirm the right and consent to clone the voice |
| `gender` | string | no | `male` or `female`. ThunderPhone tells the agent's language models which gender the voice has so replies use the matching first-person forms in languages that mark the speaker's gender (Russian, Polish, Hebrew, Hindi, Arabic, ...). Omit it and the agent guesses in those languages; English and other ungendered first-person languages are unaffected. You can add it later with `PATCH` |
| `agent_id` | integer | no | The id of one of your agents the voice is made for. It only records which agent; set the agent's `voice` to `custom:<public_id>` to use it |

```json Response (202 Accepted)
{
  "name": "custom:cv_2f6f90b0e9a34ee8b39be7d1",
  "public_id": "cv_2f6f90b0e9a34ee8b39be7d1",
  "display_name": "Support voice",
  "language": "en",
  "gender": "female",
  "status": "queued",
  "failure_reason": "",
  "created_at": "2026-07-30T14:12:08.317Z",
  "sample_url": null,
  "agent_id": null,
  "warnings": []
}
```

The `202 Accepted` response means the upload was queued, not that the voice is
ready. Poll the clone detail until it reaches a terminal status, or subscribe
to [`voice.ready` and `voice.failed`](/webhooks/events#voice-events) for push
notifications.

`warnings` lists non-blocking problems with the request. It is empty unless
`gender` was omitted (or sent empty) for a language whose first-person verb
forms change with the speaker's gender (`ru`, `pl`, `he`, `hi`, `ar`):

```json
"warnings": [
  {
    "code": "gender_not_set",
    "field": "gender",
    "detail": "Russian first-person verb forms change with the speaker's gender. Without a gender the agent guesses which forms to use; set gender to male or female (PATCH the clone to add it later)."
  }
]
```

| Status | Code or response | When |
|--------|------------------|------|
| `400` | `{"language":"Unsupported custom voice language."}` | Language is missing or unsupported |
| `400` | `{"audio":"An audio file is required."}` | Audio part is missing |
| `400` | `{"audio":"Audio must be a WAV or MP3 file."}` | Filename extension and MIME type are not an accepted WAV or MP3 combination |
| `400` | `{"audio":"Audio must be 4 MB or smaller."}` | File exceeds 4 MB |
| `400` | `{"audio":"Audio must not be empty."}` | File is empty |
| `400` | `{"consent":"Consent must be exactly true to confirm rights to clone this voice."}` | Consent is not exactly `true` |
| `400` | `{"name":"Name is required."}` | Name is empty or absent |
| `400` | `{"name":"Name must be 100 characters or fewer."}` | Name is too long |
| `400` | `{"gender":"Gender must be male or female."}` | Gender is non-empty but not `male` or `female`; an empty value counts as omitted |
| `403` | `cloning_not_enabled` | Custom voice cloning is not enabled for the organization |
| `422` | `custom_voice_quota_exceeded` | The organization's ThunderPhone custom voice limit is already in use |

The `403` response is:

```json
{
  "code": "cloning_not_enabled",
  "detail": "Custom voice cloning is not enabled. Submit a quota request to request access."
}
```

The quota response includes current ThunderPhone usage and limit:

```json
{
  "code": "custom_voice_quota_exceeded",
  "detail": "Custom voice quota exceeded.",
  "current": 5,
  "max": 5
}
```

## List and retrieve clones

List all non-deleted custom voices for the organization, newest first:

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/voices/clones \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

```json Response (200 OK)
[
  {
    "name": "custom:cv_2f6f90b0e9a34ee8b39be7d1",
    "public_id": "cv_2f6f90b0e9a34ee8b39be7d1",
    "display_name": "Support voice",
    "language": "en",
    "gender": "female",
    "status": "ready",
    "failure_reason": "",
    "created_at": "2026-07-30T14:12:08.317Z",
    "sample_url": "https://api.thunderphone.com/v1/voices/clones/cv_2f6f90b0e9a34ee8b39be7d1/preview?sig=..."
  }
]
```

Retrieve one clone with `GET /v1/voices/clones/{public_id}`. It returns the
same [custom voice object](#custom-voice-object), or `404 Not Found` if the
voice does not exist, belongs to another organization, or was deleted.

## Rename a clone or set its gender

`display_name` and `gender` can be changed; send either or both. The
agent-facing `name`, `custom:<public_id>`, stays stable. Use `gender` to
add one to a clone created without it.

<CodeGroup>
```bash cURL
curl -X PATCH \
  https://api.thunderphone.com/v1/voices/clones/cv_2f6f90b0e9a34ee8b39be7d1 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"display_name":"Billing voice","gender":"female"}'
```
</CodeGroup>

Returns the updated [custom voice object](#custom-voice-object).

| Status | Response | When |
|--------|----------|------|
| `400` | `{"detail":"Only display_name and gender may be changed."}` | The body is empty or contains any other field |
| `400` | `{"display_name":"Display name must be between 1 and 100 characters."}` | `display_name` is present but empty or too long |
| `400` | `{"gender":"Gender must be male or female."}` | `gender` is present but unsupported |
| `404` | Not found | The clone is unavailable to the organization |

## Delete a clone

<CodeGroup>
```bash cURL
curl -X DELETE \
  https://api.thunderphone.com/v1/voices/clones/cv_2f6f90b0e9a34ee8b39be7d1 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Returns `204 No Content`. Deletion is soft: the voice disappears from clone
and catalog responses immediately and frees one ThunderPhone custom voice
slot. A deleted voice can no longer be assigned to an agent.

## Play the preview

A ready clone's `sample_url` is a signed URL to:

`GET /v1/voices/clones/{public_id}/preview?sig={signature}`

It streams `audio/mpeg` without an Authorization header. You can also call
the endpoint without `sig` while authenticated:

<CodeGroup>
```bash cURL
curl \
  https://api.thunderphone.com/v1/voices/clones/cv_2f6f90b0e9a34ee8b39be7d1/preview \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  --output preview.mp3
```
</CodeGroup>

An unsigned, unauthenticated request—or one with an invalid or expired
signature—returns `401 Unauthorized`. A valid request returns `404 Not Found`
when the clone is not ready or has no stored preview.

## Use a custom voice

Once `status` is `ready`, pass the clone's `name` to an agent's `voice` or
`draft_voice` field:

<CodeGroup>
```bash cURL
curl -X PATCH https://api.thunderphone.com/v1/agents/42 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"voice":"custom:cv_2f6f90b0e9a34ee8b39be7d1"}'
```
</CodeGroup>

The clone must be ready and owned by the agent's organization. A clone from
another organization, a non-ready clone, or a deleted clone is rejected.

Ready custom voices also appear at the start of the `voices` array returned
by [`GET /v1/voices`](/api-reference/agents#voices):

```json
{
  "name": "custom:cv_2f6f90b0e9a34ee8b39be7d1",
  "display_name": "Billing voice",
  "description": "",
  "gender": "female",
  "category": "custom",
  "accent": null,
  "languages": ["en"],
  "custom": true,
  "surcharges": {"en": 1},
  "sample_url": "https://api.thunderphone.com/v1/voices/clones/cv_2f6f90b0e9a34ee8b39be7d1/preview?sig=..."
}
```

The `surcharges` object is empty when the organization has no custom voice
surcharge. It applies only to accounts still on their earlier pricing; on the
[new pricing](/guides/pricing) a custom voice is billed at its provider's list
price. You can filter the catalog with `?category=custom`, `?languages=en`,
or `?gender=female`.

## Bring your own Cartesia voice

Organizations that keep their voices in their own [Cartesia](https://cartesia.ai)
account can have ThunderPhone speak with them directly. Speech is synthesized
on your Cartesia account with Cartesia's Sonic model, and Cartesia bills your
account for it. ThunderPhone charges nothing for the voice; the call's other
parts are billed as usual. ThunderPhone does not copy the Cartesia voice or
its clone audio into the ThunderPhone voice library: staff store your Cartesia
API key encrypted, each call record keeps the selected voice id, and the key
is never returned.

This is set up by ThunderPhone for your organization, not through the API or
dashboard: contact support with a Cartesia API key created for ThunderPhone's
use. We hold it encrypted and never return it. Until it is configured, a
Cartesia voice is rejected like any unknown voice
(`"Unsupported voice option."`).

Once configured, name the voice on a [realtime session](/api-reference/realtime)
with an inline configuration, using the voice id from your Cartesia dashboard.
For a WebSocket `session.update`, set `session.audio.output.voice`; for a
managed session created with `POST /v1/realtime/sessions`, set `config.voice`:

```json
{
  "type": "session.update",
  "session": {
    "instructions": "You are Javier's assistant, calling to confirm Sunday's plans.",
    "audio": {"output": {"voice": "cartesia:a0e99841-438c-4a64-b679-ae501e7d6091"}},
    "config": {"product": "bolt"}
  }
}
```

- The value is `cartesia:` followed by the voice's UUID. It is accepted only
  on inline realtime sessions; saved agents, ThunderPhone-managed telephony
  calls and widget sessions keep using ThunderPhone and custom voices.
- Any voice in your Cartesia account works, including instant clones, so you
  can choose a different voice per session. The id is not verified against
  your account at session setup: a well-formed id that Cartesia rejects falls
  back on the first turn (below).
- On ordinary `bolt` conversational turns, ThunderPhone streams the reply text
  to Cartesia as it is generated, for the lowest latency. Some paths, such as
  IVR menu turns, and the other products collect the full reply before
  synthesis.
- If synthesis fails before any audio has started (a revoked key, no remaining
  credits, or a deleted voice), ThunderPhone speaks that turn in the default
  ThunderPhone voice rather than leaving it silent and records the error in
  its server logs with the call id. A failure after audio has started is not
  retried, so speech is never repeated.

<!-- en: api-reference/voice-samples -->
---
title: "Voice samples"
description: "Generate a spoken sample of any voice from your own text."
---

Voice samples turn a short piece of your own text into speech in any
ThunderPhone voice — any [catalog voice](/api-reference/voices), any
`platform:` or `cartesia-library:` voice from the
[voice library](/api-reference/agents#every-voice), or any of your
organization's ready [custom voices](/api-reference/custom-voices).
ElevenLabs voices play their own `sample_url` instead.
Use them to audition voices, preview a greeting before an agent goes live,
or let your users hear a voice say their own words.

Samples are meant for exactly that — sampling. Text is capped at 500
characters and generation is rate limited per organization. If you need
longer samples or a higher limit, contact support@thunderphone.com.

<Note>
  Every endpoint on this page requires
  `Authorization: Bearer sk_live_YOUR_API_KEY`, except a signed sample URL.
  Resources are scoped to the organization associated with the credential.
</Note>

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/voices/preview` | Generate a sample and get a signed audio URL |
| `GET` | `/v1/voices/previews/{id}` | Stream a generated sample's MP3 |

## Generate a sample

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/voices/preview \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice": "sarah",
    "language": "en",
    "text": "Thanks for calling Northwind Dental. How can I help you today?"
  }'
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `voice` | string | yes | A voice `name` from [`GET /v1/voices`](/api-reference/agents#voices) — a catalog voice like `sarah`, or one of your ready custom voices like `custom:cv_2f6f90b0e9a34ee8b39be7d1` |
| `language` | string | yes | Language code for the sample. For a custom voice, this must be the clone's language |
| `text` | string | yes | The text to speak, 1–500 characters |

```json Response (200 OK)
{
  "id": "vp_9c2f90b0e9a34ee8b39be7d1",
  "url": "https://api.thunderphone.com/v1/voices/previews/vp_9c2f90b0e9a34ee8b39be7d1?sig=...",
  "cached": false,
  "charged_cents": 3,
  "expires_at": "2026-08-07T14:12:08.317Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Identifier of the generated sample |
| `url` | string | Signed URL that streams the sample's MP3 without authentication |
| `cached` | boolean | `true` when the sample was served from cache instead of freshly generated |
| `charged_cents` | integer | What this request cost: `3` for a fresh generation, `0` for a cache hit |
| `expires_at` | timestamp | ISO 8601 time the signed URL stops working |

## Pricing and caching

A fresh generation costs **3¢** from your prepaid balance. Repeating an
identical request — same voice, language, and text — is served from cache,
costs nothing, and returns `"cached": true` with a fresh signed URL. That
also means expired URLs are cheap to replace: re-send the same request and
you get a new one free.

Generation is limited to 30 fresh samples per organization per hour; cache
hits don't count against the limit.

## Fetch the audio

The `url` in the response is a signed link to:

`GET /v1/voices/previews/{id}?sig={signature}`

It streams `audio/mpeg` without an Authorization header, so you can hand it
straight to an `<audio>` element or a media player. Signed URLs are valid
for 7 days. You can also call the endpoint without `sig` while
authenticated:

<CodeGroup>
```bash cURL
curl \
  https://api.thunderphone.com/v1/voices/previews/vp_9c2f90b0e9a34ee8b39be7d1 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  --output sample.mp3
```
</CodeGroup>

An unsigned, unauthenticated request — or one with an invalid or expired
signature — returns `401 Unauthorized`. A sample generated for another
organization's custom voice returns `404 Not Found`.

## Errors

| Status | Code or response | When |
|--------|------------------|------|
| `400` | `{"voice":"Voice is required."}` | Voice is missing |
| `400` | `{"language":"Language is required."}` | Language is missing |
| `400` | `{"text":"Text must be between 1 and 500 characters."}` | Text is empty or too long |
| `400` | `{"voice":"Voice is not available."}` | Custom voice doesn't exist, isn't ready, or belongs to another organization, or the library voice doesn't exist |
| `400` | `{"language":"Language is not available for this voice."}` | The voice doesn't speak that language |
| `402` | `insufficient_balance` | Prepaid balance is below the sample price |
| `422` | `preview_unavailable_language` | Sample generation isn't available for this voice in that language yet |
| `429` | `preview_rate_limited` | The organization used its 30 fresh generations this hour |
| `502` | `preview_failed` | A library voice's sample could not be made; nothing is charged |

The `402`, `422`, and `429` responses share one shape:

```json
{
  "code": "preview_rate_limited",
  "detail": "Sample generation limit reached. Try again later."
}
```

A `422` means the voice exists but ThunderPhone can't generate ad-hoc
samples for it in that language yet — the voice still works normally on
calls. Pick another voice or language for the sample.

<!-- en: api-reference/split-testing -->
---
title: "Split Testing"
description: "A/B test agent variants on live traffic and compare per-variant outcomes."
---

Split testing routes an agent's live calls across **variants** —
weighted configurations that override specific fields (prompt, voice,
product, …) while inheriting everything else from the agent's deployed
config. Each call records which variant served it
(`agent_variant_id` / `agent_variant_label` on the
[Call object](/api-reference/calls#call-object)), and the stats
endpoint compares outcomes per variant.

The **control** variant (`is_control: true`) represents the agent's
deployed config unchanged. Enabling split testing auto-creates a
control if none exists.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/agents/{agent_id}/variants` | List variants |
| `POST` | `/v1/agents/{agent_id}/variants` | Create a variant |
| `PATCH` | `/v1/agents/{agent_id}/variants/{variant_id}` | Update a variant |
| `DELETE` | `/v1/agents/{agent_id}/variants/{variant_id}` | Delete a variant |
| `POST` | `/v1/agents/{agent_id}/split-testing` | Enable / disable split testing (staged as a draft) |
| `GET` | `/v1/agents/{agent_id}/variant-stats` | Per-variant call stats |

## Variant object

```json
{
  "id": 41,
  "label": "Warmer greeting",
  "weight": 50,
  "is_control": false,
  "prompt": "You are a warm, upbeat support agent…",
  "voice": null,
  "product": null,
  "background_track": null,
  "thinking_level": null,
  "acknowledgement_prompt_mode": null,
  "acknowledgement_prompt": null,
  "inbound_speak_order": null,
  "outbound_speak_order": null,
  "silence_interval_seconds": null,
  "silence_max_checkins": null,
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Variant id |
| `label` | string | ≤ 100 chars |
| `weight` | integer | 0–100, default 50. Traffic is distributed proportionally to weights |
| `is_control` | boolean | At most one control per agent |
| `prompt`, `voice`, `product`, `background_track`, `thinking_level`, `acknowledgement_prompt_mode`, `acknowledgement_prompt`, `inbound_speak_order`, `outbound_speak_order`, `silence_interval_seconds`, `silence_max_checkins` | field type \| null | **Overrides.** `null` = inherit the agent's deployed value; set a value to change just that field for this variant |

`POST` requires `label` (everything else optional) and returns `201`.
`PATCH` accepts any subset; `DELETE` returns `204`.

---

## Enable / disable split testing

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/agents/12/split-testing \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'
```
</CodeGroup>

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | boolean | `true` | |

```json Response
{
  "split_testing_enabled": false,
  "draft_split_testing_enabled": true
}
```

The toggle is staged as a **draft** on the agent — live traffic starts
(or stops) splitting only after you
[deploy](/api-reference/agents#deploy-the-draft). Enabling with no
control variant auto-creates one (`label: "Control"`, `weight: 100`).

---

## Variant stats

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/agents/12/variant-stats \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

```json Response
[
  {
    "variant_id": 40,
    "label": "Control",
    "is_control": true,
    "calls": 132,
    "success_rate": 84.1,
    "avg_duration_seconds": 163
  },
  {
    "variant_id": 41,
    "label": "Warmer greeting",
    "is_control": false,
    "calls": 129,
    "success_rate": 88.4,
    "avg_duration_seconds": 171
  }
]
```

| Field | Type | Description |
|-------|------|-------------|
| `calls` | integer | Total calls served by the variant |
| `success_rate` | number \| null | % of graded, completed calls with `call_outcome="success"` (ungraded calls excluded); `null` when nothing graded yet |
| `avg_duration_seconds` | integer \| null | Mean duration of completed calls |

---

## Related

<CardGroup cols={2}>
  <Card title="Agents" icon="robot" href="/api-reference/agents">
    `split_testing_enabled` lives on the agent (draft/deploy).
  </Card>
  <Card title="Calls" icon="phone" href="/api-reference/calls">
    Filter call history by `agent_variant_id` fields on each call.
  </Card>
</CardGroup>

<!-- en: api-reference/knowledge-bases -->
---
title: "Knowledge"
description: "Upload documents, search them semantically, and ground your agents in your own content."
---

The knowledge store holds **documents** (uploaded files, pasted text, or
imported web pages) that agents can search mid-call via the
built-in `search_knowledge_base` tool. Attach documents (or grouping
**knowledge bases**) to an agent with the `knowledge_base_ids` /
`knowledge_document_ids` fields on [Agents](/api-reference/agents).

Documents are ingested asynchronously: uploads start in
`status="pending"`, move through `processing` (text extraction for
PDF/DOCX, chunking, embedding), and land on `ready` or `failed`.

<Note>
  All **write** operations on this page require the `admin` role (or
  an `sk_live_` key, which carries full access). Reads are available
  to every member.
</Note>

## Endpoints

The primary store is flat ("upload-first") under `/v1/knowledge/`:

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/knowledge/documents` | List documents |
| `POST` | `/v1/knowledge/documents` | Upload file(s) or create a text document |
| `GET` | `/v1/knowledge/documents/{document_id}` | Retrieve a document (includes extracted `content`) |
| `PATCH` | `/v1/knowledge/documents/{document_id}` | Rename / edit text content |
| `DELETE` | `/v1/knowledge/documents/{document_id}` | Delete a document |
| `POST` | `/v1/knowledge/documents/{document_id}/retry` | Re-ingest a `failed` document |
| `GET` | `/v1/knowledge/documents/{document_id}/original` | Download the original uploaded file |
| `POST` | `/v1/knowledge/documents/{document_id}/replace` | Replace the file behind a document |
| `POST` | `/v1/knowledge/documents/import-url` | Import a web page by URL |
| `POST` | `/v1/knowledge/documents/{document_id}/refresh` | Re-fetch a URL-imported page |
| `POST` | `/v1/knowledge/search` | Semantic search across documents |

Legacy **base-scoped** routes remain available as adapters (a base is
now just a named grouping over the flat store):

| Method | Path | Description |
|--------|------|-------------|
| `GET` / `POST` | `/v1/knowledge-bases` | List / create knowledge bases |
| `GET` / `PATCH` / `DELETE` | `/v1/knowledge-bases/{knowledge_base_id}` | Manage one base (delete detaches its documents, it does not delete them) |
| `GET` / `POST` | `/v1/knowledge-bases/{knowledge_base_id}/documents` | List / create documents inside a base |
| `PATCH` / `DELETE` | `/v1/knowledge-bases/{knowledge_base_id}/documents/{document_id}` | Manage a document inside a base |
| `POST` | `/v1/knowledge-bases/{knowledge_base_id}/documents/{document_id}/retry` | Re-ingest |
| `POST` | `/v1/knowledge-bases/{knowledge_base_id}/search` | Search within one base |

## Knowledge document object

```json
{
  "id": "8b2f4a1e-…",
  "name": "Refund policy.pdf",
  "source_type": "file",
  "original_filename": "Refund policy.pdf",
  "mime_type": "application/pdf",
  "byte_count": 482113,
  "estimated_chunk_count": 12,
  "status": "ready",
  "error": "",
  "chunk_count": 12,
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:31.040Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Document id |
| `name` | string | Display name |
| `source_type` | string | `text` (pasted/edited content) or `file` (uploaded) |
| `original_filename` | string | Empty for text documents |
| `mime_type` | string | Canonical MIME type (`text/plain`, `text/markdown`, `text/csv`, `application/pdf`, DOCX) |
| `byte_count` | integer | Size of the original upload (or the UTF-8 text) |
| `estimated_chunk_count` | integer | Persisted indexed count when ready; otherwise an estimate from current extracted content (falling back to the last persisted count until binary extraction is available) |
| `status` | string | `pending`, `processing`, `ready`, or `failed` |
| `error` | string | Ingestion error summary when `failed` |
| `chunk_count` | integer | Chunks actually indexed |
| `source_origin` | string | `upload`, `url`, or `null` |
| `source_url` | string | The imported page address for `url`-origin documents, else `null` |
| `fetched_at` | timestamp | Last successful fetch of `source_url` (`null` while a re-fetch is queued) |
| `created_at`, `updated_at` | timestamp | |

The **detail** endpoint (`GET /v1/knowledge/documents/{id}`) adds:
`content` (the canonical extracted text), `uploaded_by`
(`{id, name, email}` or `null`), `replaced_at`, `has_original`,
`original_size_bytes`, and `original_mime_type`.

### Upload limits

| Kind | Extensions | Max size |
|------|-----------|----------|
| Text | `.txt`, `.md`, `.csv` | 1 MB |
| Binary | `.pdf`, `.docx` | 50 MB |

Anything else is rejected with a `400` field error naming the file.

---

## List documents

<CodeGroup>
```bash cURL
curl 'https://api.thunderphone.com/v1/knowledge/documents?status=ready' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

| Query param | Description |
|-------------|-------------|
| `q` | Substring match on name or content |
| `status` | `pending`, `processing`, `ready`, `failed` |

Returns a plain array of [document objects](#knowledge-document-object),
newest first.

---

## Create documents

Two content types are accepted:

**Multipart upload** — one or more files in `files[]` (or a single
`file` part, optionally with a `name` field):

<CodeGroup>
```bash cURL (files)
curl -X POST https://api.thunderphone.com/v1/knowledge/documents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -F 'files[]=@refund-policy.pdf' \
  -F 'files[]=@faq.md'
```

```bash cURL (text)
curl -X POST https://api.thunderphone.com/v1/knowledge/documents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Escalation playbook", "content": "When a caller asks for a manager…"}'
```
</CodeGroup>

**JSON** — `{name, content}` creates a `source_type="text"` document.

```json Response (201 Created)
{
  "documents": [ /* document objects, status "pending" */ ],
  "warnings": [
    {
      "document_id": "8b2f4a1e-…",
      "duplicate_document_ids": ["77aa…"],
      "message": "This file has the same content as an existing document."
    }
  ]
}
```

Every file is validated before anything is created — one bad file
fails the whole request with `400`. Duplicate-content uploads are
allowed but reported in `warnings`.

---

## Retrieve, edit, delete

`GET /v1/knowledge/documents/{id}` returns the
[detail shape](#knowledge-document-object) including extracted
`content`.

`PATCH` accepts JSON `{name?, content?}` (or a multipart `file` to
swap content). Changing `name` or `content` re-queues ingestion
(`status` returns to `pending`). Returns the updated document.

`DELETE` returns `204 No Content` and removes the document and its
chunks from the index.

---

## Download the original file

For `file`-sourced documents, fetch the exact bytes that were uploaded.

<CodeGroup>
```bash cURL
curl 'https://api.thunderphone.com/v1/knowledge/documents/8b2f4a1e-…/original?download=1' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Returns either the file stream directly or a short-lived signed URL:

```json
{ "url": "https://storage.googleapis.com/…", "expires_in": 900 }
```

`download=1` sets an attachment `Content-Disposition`. Returns `404`
when no original is stored (text documents).

## Replace the file

`POST /v1/knowledge/documents/{id}/replace` with a multipart `file`
part swaps the document's content for the new file (same validation
and limits as upload), stores the new original, stamps `replaced_at`,
and re-queues ingestion.

```json Response
{ "document": { /* document object, status "pending" */ }, "warnings": [] }
```

If the uploaded bytes are identical to the current file, the request
still succeeds and a warning says so.

## Retry ingestion

`POST /v1/knowledge/documents/{id}/retry` re-queues a **failed**
document. Returns the document with `status="pending"`, or `400` with
`{"detail": "Only failed documents can be retried."}` if it is not in
`failed`.

---

## Import a web page by URL

Creates a document from a public web page. The page is fetched
**server-side and asynchronously**: the document is returned
immediately in `status="pending"`, then the ingestion worker fetches
the URL (through the same SSRF-guarded transport as webhooks — private
networks, localhost, and cloud metadata addresses are refused, with at
most 5 redirects, each hop re-validated), extracts the main content
(HTML boilerplate such as navigation and footers is stripped;
`application/pdf` responses go through PDF text extraction), and
indexes it. Pages are capped at 5 MB.

If no `name` is given, the document is named after the URL and adopts
the page title once fetched.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/knowledge/documents/import-url \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/pricing" }'
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | yes | `http://` or `https://` page address (bare domains default to `https://`) |
| `name` | string | no | Display name; defaults to the URL, then the page title |

```json Response (201)
{
  "document": { /* document object, status "pending", source_origin "url" */ },
  "warnings": []
}
```

`warnings` lists earlier documents that were imported from the same
URL. Pages that can't be fetched (HTTP errors, blocked destinations)
or contain no extractable text (for example JavaScript-only apps) land
in `status="failed"` with a readable `error`.

### Refresh a URL-imported document

`POST /v1/knowledge/documents/{document_id}/refresh` re-fetches
`source_url` and re-indexes the document (admin role required; only
`url`-origin documents can be refreshed). The stored `ETag` /
`Last-Modified` validators are sent, so an unchanged page is a cheap
no-op that keeps the existing index.

---

## Search

Semantic (embedding) search over ready documents. This is the same
retrieval the agent's `search_knowledge_base` tool uses at call time.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/knowledge/search \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "what is the refund window?"}'
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | yes | ≤ 4000 chars |
| `document_ids` | array of UUID | no | Restrict the search scope; omit to search everything |

```json Response
{
  "results": [
    {
      "text": "Refunds are available within 30 days of purchase…",
      "document": "Refund policy.pdf",
      "score": 0.874312
    }
  ]
}
```

Results are ranked by cosine similarity (`score` closer to 1 is
better), capped per document so one file can't fill every slot, and
each `text` is length-capped.

`POST /v1/knowledge-bases/{id}/search` takes the same body and scopes
the search to that base's documents.

---

## Knowledge bases (grouping)

A knowledge base is a named group:
`{id (UUID), name, description, document_count, created_at, updated_at}`.
Create with `POST /v1/knowledge-bases` `{name, description?}` (`201`);
update with `PATCH`; `DELETE` (`204`) detaches the base's documents
back into the flat store without deleting them. Attach whole bases to
an agent via `knowledge_base_ids`.

---

## Related

<CardGroup cols={2}>
  <Card title="Agents" icon="robot" href="/api-reference/agents">
    Attach documents and bases via `knowledge_document_ids` / `knowledge_base_ids`.
  </Card>
  <Card title="Calls" icon="phone" href="/api-reference/calls">
    Knowledge lookups appear in the call history as tool calls.
  </Card>
  <Card title="Reusable instructions" icon="list-check" href="/api-reference/reusable-instructions">
    For rules the agent must always follow, put them in the prompt instead of a lookup.
  </Card>
</CardGroup>

<!-- en: api-reference/reusable-instructions -->
---
title: "Reusable instructions"
description: "Write an organization-wide rule once and attach it to any agent; it is appended to the agent's system prompt under its own heading."
---

Reusable instructions are named blocks of markdown that belong to your
organization rather than to one agent: rules like email normalization,
symbol read-back, or retry limits that every agent should follow. Attach an
instruction to an agent with the `reusable_instruction_ids` field on
[Agents](/api-reference/agents). At call start ThunderPhone appends each
attached instruction to the end of that agent's prompt as a section headed
`## <name>`, in the order the instructions were created. Editing an
instruction changes every agent it is attached to from their next call;
deleting one detaches it everywhere and leaves each agent's own prompt
untouched.

Unlike [knowledge](/api-reference/knowledge-bases), instructions are not
looked up through a tool during the call. They are part of the system prompt
on every call the agent handles: inbound and outbound phone calls, web widget
sessions, [realtime sessions](/api-reference/realtime) that name an agent, and
test calls from the agent builder. Because they are prompt text, they make the
combined prompt longer, and a longer prompt
[costs more per minute](/guides/pricing#how-a-call-is-priced) because the
models read it on every reply.

In the dashboard, manage instructions on the **Instructions** page and attach
them from the **Reusable instructions** section of the agent builder
(**Attach instructions**), then deploy the agent. The rest of this page covers
the same flow over the API.

<Note>
  All **write** operations on this page require the `admin` role (or
  an `sk_live_` key, which carries full access). Reads are available
  to every member.
</Note>

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/reusable-instructions` | List the organization's instructions, newest first |
| `POST` | `/v1/reusable-instructions` | Create an instruction |
| `GET` | `/v1/reusable-instructions/{instruction_id}` | Retrieve one instruction |
| `PATCH` | `/v1/reusable-instructions/{instruction_id}` | Rename or edit an instruction |
| `DELETE` | `/v1/reusable-instructions/{instruction_id}` | Delete an instruction and detach it from every agent |

## Instruction object

```json
{
  "id": "0f4d6e2a-3b1c-4c8e-9a7d-2f5e6b8c9d10",
  "name": "Email normalization",
  "content": "When a caller gives an email address, read it back letter by letter and say \"at\" for @ and \"dot\" for periods before moving on.",
  "agent_count": 3,
  "created_at": "2026-09-21T18:24:10.113Z",
  "updated_at": "2026-09-21T18:24:10.113Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | uuid | Stable identifier; use it in `reusable_instruction_ids` on an agent |
| `name` | string | Required, at most 255 characters. Becomes the section heading (`## <name>`) when appended to a prompt, so keep it short and descriptive |
| `content` | string | Required markdown body. Appended under the heading with surrounding whitespace trimmed and no other changes; per-call `{{variables}}` inside it render exactly as they do in the agent's own prompt |
| `agent_count` | integer | Agents with the instruction attached in their **deployed** configuration. Agents that have only staged the attachment in a draft are not counted |
| `created_at`, `updated_at` | timestamp | ISO 8601 UTC |

## Create an instruction

```bash
curl -X POST https://api.thunderphone.com/v1/reusable-instructions \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Retry limits",
    "content": "Ask for a piece of information at most twice. If it is still unclear, offer a callback instead of asking a third time."
  }'
```

Returns the [instruction object](#instruction-object) with `201 Created`.
Both `name` and `content` must be non-blank; a blank value returns `400` with
the field named. `PATCH` accepts either field on its own. Requests for an
instruction id that belongs to another organization return `404`.

## Attach to an agent

Attachment is an agent draft field, so it follows the same stage-then-deploy
flow as every other agent setting:

```bash
curl -X PATCH https://api.thunderphone.com/v1/agents/12 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"reusable_instruction_ids": ["0f4d6e2a-3b1c-4c8e-9a7d-2f5e6b8c9d10"]}'

curl -X POST https://api.thunderphone.com/v1/agents/12/deploy \
  -H "Authorization: Bearer sk_live_..."
```

The list replaces the agent's complete attachment set; send `[]` to detach
everything, or omit the field (or send `null`) to leave it unchanged. Every id
must belong to your organization, otherwise the `PATCH` returns `400`. Test
calls from the agent builder use the staged set; production calls use the
deployed set. The agent response embeds the attached rows as
`reusable_instructions` and the staged ids as `draft_reusable_instruction_ids`.
`POST /v1/agents` accepts the same `reusable_instruction_ids` field and
attaches immediately, since a new agent has no draft.

Deleting an instruction detaches it from every deployed agent immediately.
If an agent has a staged `reusable_instruction_ids` list that still names the
deleted id, its next deploy fails with `400` on `reusable_instruction_ids` and
asks you to update or discard the draft, rather than silently deploying a
smaller set than you reviewed. Version history records which instruction ids
an agent had attached at each deploy, not their text: editing an instruction
is not a new agent version, and the new text is used from the next call.

## Test an instruction

Attach the instruction in the agent builder (or with the `PATCH` above) and
place a test call from the builder; test calls use the staged attachment set,
so you do not need to deploy first. The section is appended after the agent's
own prompt, so ask the agent about something the instruction covers and check
the behavior. The composed prompt is not returned by the API: the agent's
`prompt` field stays exactly what you wrote, and the attached instructions are
listed separately as `reusable_instructions`.

<!-- en: api-reference/provider-connections -->
---
title: "App Connections"
description: "Connect Google Calendar, Sheets, Slack, HubSpot, Salesforce, and Cal.com, and control which tools each agent may use."
---

A **provider connection** links a third-party account to your org and
exposes a curated set of **agent tools** (e.g. "create a calendar
event", "post to Slack"). You control capability at two levels:

- **Connection-level `allowed_operations`** — which operation groups
  the whole connection permits (e.g. Slack `post: false`).
- **Per-agent attachments** — which agents may use the connection, and
  optionally a narrower per-agent operation override.

OAuth-based providers are connected from the dashboard (the browser
OAuth consent flow can't be driven by an API key). Once connected,
everything on this page is manageable via the API. Cal.com uses an API
key instead and can be connected [directly](#connect-with-an-api-key).

<Note>
  Authorization here is **operation-level, not record-level** — see
  [Authorization model](#authorization-model) below before assuming an
  agent's access can be scoped to specific channels, contacts, or
  calendars.
</Note>

## Providers and their tools

| Provider | `provider` | Auth | Operation groups (defaults) | Agent tools |
|----------|-----------|------|------------------------------|-------------|
| Google Calendar | `google_calendar` | OAuth | `view_events` ✓, `create_events` ✓, `update_events` ✗, `delete_events` ✗ | `calendar_list_events`, `calendar_check_availability`, `calendar_create_event`, `calendar_update_event`, `calendar_cancel_event` |
| Google Sheets | `google_sheets` | OAuth | `append_rows` ✓ | `sheets_append_row` (requires [sheet configuration](#configure-the-target-google-sheet)) |
| Slack | `slack` | OAuth | `view` ✓, `post` ✗, `search` ✓ | `slack_list_channels`, `slack_post_message`, `slack_search_messages` |
| HubSpot | `hubspot` | OAuth | `view` ✓, `write` ✗ | `hubspot_search_contacts`, `hubspot_get_contact`, `hubspot_upsert_contact`, `hubspot_add_note` |
| Salesforce | `salesforce` | OAuth | `view` ✓, `write` ✗ | `salesforce_search_records`, `salesforce_get_record`, `salesforce_upsert_lead`, `salesforce_log_activity` |
| Cal.com | `calcom` | API key | `view` ✓, `book` ✓, `manage` ✗ | `calcom_list_event_types`, `calcom_check_availability`, `calcom_create_booking`, `calcom_find_bookings`, `calcom_reschedule_booking`, `calcom_cancel_booking` |

Each tool maps to one operation group — disabling the group removes
every tool it gates from all attached agents.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/provider-connections` | List connections + provider catalog |
| `GET` | `/v1/provider-connections/{connection_id}` | Retrieve one connection |
| `PATCH` | `/v1/provider-connections/{connection_id}` | Update connection-level `allowed_operations` or `send_guest_invitations` |
| `DELETE` | `/v1/provider-connections/{connection_id}` | Disconnect |
| `POST` | `/v1/provider-connections/{connection_id}/test` | Check that the sign-in still works |
| `POST` | `/v1/provider-connections/{provider}/api-key` | Connect an API-key provider (Cal.com) |
| `PUT` | `/v1/provider-connections/{connection_id}/agents/{agent_id}` | Attach an agent (optional per-agent override) |
| `DELETE` | `/v1/provider-connections/{connection_id}/agents/{agent_id}` | Detach an agent |
| `POST` | `/v1/provider-connections/{connection_id}/sheets/picker-token` | Mint a short-lived token for the Google Picker |
| `POST` | `/v1/provider-connections/{connection_id}/sheets/inspect` | List a picked spreadsheet's tabs |
| `POST` | `/v1/provider-connections/{connection_id}/sheets/configure` | Pick the target spreadsheet + sheet |

`{connection_id}` is the connection's **UUID**. All writes require the
`admin` role. (The browser-only OAuth start/callback routes are not
part of the public API.)

## Connection object

```json
{
  "id": "9e1f6a3c-…",
  "provider": "slack",
  "provider_account_email": "ops@acme.com",
  "provider_account_id": "T024BE7LD",
  "provider_metadata": { "team_name": "Acme" },
  "granted_scopes": ["channels:read", "channels:history", "groups:read", "groups:history"],
  "allowed_operations": { "view": true, "post": true, "search": true },
  "effective_operations": { "view": true, "post": false, "search": true },
  "ungranted_operations": ["post"],
  "problems": [
    {
      "code": "missing_access",
      "message": "Slack didn't give ThunderPhone access to post when Slack (Acme Support) was connected, so agents can't do that. …",
      "fix": "reconnect",
      "operations": ["post"]
    }
  ],
  "token_expires_at": null,
  "last_used_at": "2026-04-21T09:02:44.517Z",
  "last_error_at": null,
  "last_error_code": null,
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z",
  "agent_attachments": [
    {
      "agent_id": 12,
      "agent_name": "Customer Support Agent",
      "allowed_operations": null,
      "tool_names": ["slack_list_channels", "slack_post_message", "slack_search_messages"]
    }
  ]
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Connection id |
| `provider` | string | Provider key (see table above) |
| `provider_account_email` / `provider_account_id` | string | Identity of the connected account |
| `provider_metadata` | object | Provider-specific info (e.g. the configured spreadsheet for Sheets) |
| `granted_scopes` | array of string | OAuth scopes actually granted |
| `allowed_operations` | object | Connection-level operation toggles as configured, e.g. `{"view": true, "post": false}`. This is the raw ceiling — it does **not** reflect whether the OAuth grant covers each operation's required scopes |
| `send_guest_invitations` | boolean | Google Calendar only. When `true` (the default), event creates, updates, and cancellations ask Google to email the guests (`sendUpdates=all`). Other providers carry the field but ignore it |
| `effective_operations` | object | Read-only, additive field. The same toggles after intersecting with `granted_scopes` — i.e. what's actually enforced. An operation can show `true` in `allowed_operations` but `false` here if the grant is missing a required scope (re-consent narrowed, a scope was added to an operation after the connection was created, etc.). Use this field, not `allowed_operations`, to know what an agent can really do |
| `ungranted_operations` | string[] | Read-only. Operations that are `true` in `allowed_operations` but not covered by `granted_scopes`, in provider order; empty when the grant covers everything that is on. Non-empty usually means the user left permissions unticked on the provider's consent screen (Google shows a checkbox per permission). Connect the same account again and grant everything: the connection is updated in place and keeps its agents. Always empty for API-key apps |
| `problems` | array | Read-only. Everything that leaves the connection giving agents fewer tools than its toggles say, worst first; empty when it works as configured. Each has a `code`, a plain-English `message` and the `fix`. Codes: `signed_out` (the provider refused the sign-in; fix `reconnect`), `missing_access` (`ungranted_operations` is non-empty, listed in `operations`; fix `reconnect`), `spreadsheet_not_chosen` (Google Sheets with no spreadsheet and tab configured, so no tools; fix `choose_spreadsheet`), `all_operations_off` (every toggle in `allowed_operations` is off; fix `turn_on_operations`). A provider that was only unreachable (`last_error_code: provider_unavailable`) is not listed: the next call retries it |
| `token_expires_at` | timestamp \| null | Access-token expiry (refreshed automatically) |
| `last_used_at` | timestamp \| null | The last time an agent's tool call or a [test](#test-a-connection) got through with this sign-in. Written at most about once a minute |
| `last_error_at` | timestamp \| null | The latest failure. Kept after a later success, as history |
| `last_error_code` | string \| null | `grant_revoked` when the sign-in no longer works (the provider refused a token refresh or answered `401`/`403`): connect the account again. `provider_unavailable` when the provider couldn't be reached. Cleared by the next success or a new sign-in |
| `agent_attachments` | array | Attached agents. `allowed_operations: null` means "inherit the connection's"; `tool_names` is the resulting tool list — connection `allowed_operations`, the per-agent override, and `granted_scopes` all intersected |

Tokens and API keys are **never** returned by any endpoint.

---

## List connections

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/provider-connections \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

```json Response
{
  "configured": true,
  "providers": {
    "slack": {
      "label": "Slack",
      "configured": true,
      "auth_kind": "oauth",
      "default_operations": { "view": true, "post": false, "search": true }
    }
  },
  "connections": [ /* Connection objects */ ],
  "agents": [{ "id": 12, "name": "Customer Support Agent" }]
}
```

`providers` is the full catalog with per-provider availability
(`configured` is false when the ThunderPhone deployment lacks that
provider's OAuth app). `agents` is a convenience list for building
attachment UIs.

---

## Update allowed operations

<CodeGroup>
```bash cURL
curl -X PATCH https://api.thunderphone.com/v1/provider-connections/9e1f6a3c-… \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allowed_operations": {"view": true, "post": true, "search": true}}'
```
</CodeGroup>

`allowed_operations` must be an object whose keys are that provider's
operation groups (unknown keys are rejected with `400`). The body may also
carry `send_guest_invitations` (boolean, Google Calendar only) on its own or
alongside `allowed_operations`; a body with neither is rejected with `400`.
Returns the updated [connection object](#connection-object).

<Warning>
  Enabling an operation the OAuth grant doesn't cover (e.g. turning on
  Slack `post` when `chat:write` wasn't granted) makes the tool fail at
  call time — reconnect from the dashboard to grant the extra scopes.
</Warning>

## Authorization model

There are three layers, evaluated together at tool-synthesis and
tool-execution time:

1. **Connection-level `allowed_operations`** — the ceiling for the
   whole connection, set via [PATCH](#update-allowed-operations).
2. **Per-agent override** (`agent_attachments[].allowed_operations`)
   — an optional narrower subset for one agent, set via
   [attach/detach](#attach-detach-agents). `null` means "inherit the
   connection's ceiling" — an override can only turn operations
   *off*, never grant one the connection ceiling denies.
3. **`granted_scopes`** — what the OAuth grant actually covers. Each
   operation requires specific scopes (e.g. Slack `post` requires
   `chat:write`); an operation enabled at both the connection and
   agent level still can't run if the grant doesn't cover it.

`effective_operations` on the [connection object](#connection-object)
is operations (1) and (3) intersected — it does **not** factor in a
per-agent override, since that's per-attachment. The `tool_names` on
each `agent_attachments` entry is the fully-intersected result: connection
ceiling ∩ per-agent override (if any) ∩ granted scopes. That list is
what the agent's tool schema actually contains, and `execute_provider_tool`
re-checks the same intersection at call time (defense in depth against a
stale route or shared connection dispatching a call the agent's current
config would no longer allow).

<Warning>
  **Authorization is provider-level, not per-record.** Toggling an
  operation on grants (or denies) it across every record the OAuth
  scope reaches — there is no per-channel, per-contact, per-object, or
  per-calendar scoping. Concretely:

  - An agent with Slack `post: true` can post to **any** channel the
    connected bot/user can reach — not a chosen subset of channels.
  - An agent with Slack `view` / `search` can read **any** channel the
    grant reaches, same caveat.
  - An agent with HubSpot or Salesforce `write: true` can create or
    update **any** record type/object the OAuth grant covers, not a
    restricted list of pipelines or object types.
  - Google Calendar operations always act on the connected account's
    **primary calendar** — there's no way to scope an agent to a
    secondary or shared calendar.

  If you need to isolate what one agent can touch within a provider
  (e.g. "this agent may only post in `#support`"), connect a
  **separate provider account** scoped to just that resource (a
  dedicated Slack app/bot invited to one channel, a HubSpot user with
  restricted CRM permissions, a secondary Google account whose primary
  calendar is the one you want exposed) and attach that connection
  instead. Per-resource ACLs on a single connection (e.g. an
  allow-list of Slack channel IDs) are **not implemented** — this has
  come up before as a half-built field with no way to populate it, and
  is tracked as a roadmap item rather than something to configure
  today.
</Warning>

## Disconnect

`DELETE /v1/provider-connections/{id}` returns `204 No Content` and
removes the connection and every agent attachment.

---

## Test a connection

`POST /v1/provider-connections/{id}/test` refreshes the access token if it is due, then
makes one read-only request that only needs the sign-in (Google's userinfo, Slack's
`auth.test`, HubSpot's token info, Salesforce's userinfo, Cal.com's `/me`). Requires
`admin`.

```json Response
{
  "ok": false,
  "code": "grant_revoked",
  "message": "The sign-in no longer works. Connect the account again.",
  "connection": { "id": "9e1f6a3c-…", "last_error_code": "grant_revoked", "…": "…" }
}
```

`code` is `""` when it worked, else the same value the connection's `last_error_code` now
holds. `message` is ThunderPhone's own text; provider responses are never returned.

---

## Connect with an API key

Only for `auth_kind: "api_key"` providers — currently **Cal.com**.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/provider-connections/calcom/api-key \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "cal_live_…"}'
```
</CodeGroup>

The key is validated against the provider before saving; invalid keys
return `400` with an `api_key` field error. Returns `201 Created` with
the [connection object](#connection-object).

---

## Attach / detach agents

Attaching gives the agent the connection's tools on its next deploy
of call config (tool lists are computed per call).

<CodeGroup>
```bash Attach (inherit connection ops)
curl -X PUT https://api.thunderphone.com/v1/provider-connections/9e1f6a3c-…/agents/12 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```bash Attach (narrower override)
curl -X PUT https://api.thunderphone.com/v1/provider-connections/9e1f6a3c-…/agents/12 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allowed_operations": {"view": true, "post": false, "search": false}}'
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `allowed_operations` | object \| null | no | Per-agent override. Omit / `null` to inherit the connection-level toggles |

`PUT` is an upsert — repeat it to change the override. Returns the
[connection object](#connection-object) with updated
`agent_attachments`. `DELETE` on the same path detaches the agent
(`204`).

---

## Configure the target Google Sheet

`sheets_append_row` writes to one configured spreadsheet + sheet per
connection. ThunderPhone holds the per-file `drive.file` Google scope,
so the connection can only open spreadsheets the user has explicitly
granted by picking them in the Google Picker (the dashboard runs this
flow). Setup is three steps (Sheets connections only — other providers
return `404` on these routes):

### Mint a Picker token

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/provider-connections/9e1f6a3c-…/sheets/picker-token \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

```json Response
{ "access_token": "ya29.…" }
```

Returns a short-lived access token for the connection's own Google
credential. Load the [Google Picker](https://developers.google.com/drive/picker/guides/overview)
with this token (`setOAuthToken`) so the user's pick grants file access
to the same credential the agent's tools use at call time.

### Inspect a spreadsheet

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/provider-connections/9e1f6a3c-…/sheets/inspect \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"spreadsheet_id": "1AbC…"}'
```
</CodeGroup>

```json Response
{
  "spreadsheet_id": "1AbC…",
  "title": "Lead intake",
  "sheets": ["Leads", "Archive"]
}
```

Takes the file id returned by the Picker and lists the tab names.
`400` when the spreadsheet has not been granted through the Picker (or
access was revoked).

### Configure

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/provider-connections/9e1f6a3c-…/sheets/configure \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"spreadsheet_id": "1AbC…", "sheet_name": "Leads"}'
```
</CodeGroup>

Reads row 1 of the chosen sheet as the column headers (at least one
non-empty header required — `400` otherwise) and stores
`spreadsheet_id`, `sheet_name`, and the header map in
`provider_metadata`. Returns the updated
[connection object](#connection-object). The agent tool then appends
one row per call, mapping its arguments onto those headers.

---

## Related

<CardGroup cols={2}>
  <Card title="Agents" icon="robot" href="/api-reference/agents">
    Attached tools appear alongside the agent's other tools.
  </Card>
  <Card title="MCP Servers" icon="server" href="/api-reference/mcp-servers">
    Bring arbitrary tools via the Model Context Protocol.
  </Card>
  <Card title="Integrations" icon="plug" href="/api-reference/integrations">
    Wrap any HTTP API as an agent tool.
  </Card>
  <Card title="Calls" icon="phone" href="/api-reference/calls">
    Tool invocations show up in call history.
  </Card>
</CardGroup>

<!-- en: api-reference/mcp-servers -->
---
title: "MCP Servers"
description: "Attach remote MCP tool servers to your agents, and use ThunderPhone itself as an MCP server."
---

Two directions of MCP (Model Context Protocol) integration:

1. **Remote MCP servers** (`/v1/mcp-servers`) — register an external
   MCP server; its tools are synced, cached, and become callable by
   any [agent](/api-reference/agents) you attach the server to via
   `mcp_server_ids`.
2. **ThunderPhone as an MCP server** (`POST /v1/mcp`) — a single
   endpoint that speaks MCP (JSON-RPC over Streamable HTTP), letting
   Claude, coding IDEs, and agent frameworks build, test, validate, and
   operate your voice agents. Authenticate with your `sk_live_` key.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/mcp-servers` | List registered servers |
| `POST` | `/v1/mcp-servers` | Register a server (syncs tools immediately) |
| `GET` | `/v1/mcp-servers/{server_id}` | Retrieve one server |
| `PATCH` | `/v1/mcp-servers/{server_id}` | Update (re-syncs when connection details change) |
| `DELETE` | `/v1/mcp-servers/{server_id}` | Remove a server |
| `POST` | `/v1/mcp-servers/{server_id}/sync-tools` | Re-fetch the server's tool list |
| `POST` | `/v1/mcp` | ThunderPhone's own MCP endpoint (JSON-RPC) |

`{server_id}` is the server's **UUID**. Writes require the `admin`
role.

## MCP server object

```json
{
  "id": "1c9d2e4f-…",
  "display_name": "Internal ops tools",
  "url": "https://mcp.example.com/mcp",
  "transport": "streamable_http",
  "headers": [{ "key": "Authorization" }],
  "enabled": true,
  "last_tools_sync_at": "2026-04-20T18:24:10.113Z",
  "cached_tools": [
    {
      "type": "function",
      "function": {
        "name": "mcp_1c9d2e4f…_create_ticket",
        "description": "Create a support ticket",
        "parameters": { "type": "object", "properties": { "…": {} } }
      },
      "mcp": { "server_id": "1c9d2e4f-…", "tool_name": "create_ticket" }
    }
  ],
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Server id |
| `display_name` | string | 1–255 chars |
| `url` | string | The server's streamable-HTTP endpoint. Must be `http(s)` and resolve **only to public IP addresses** (SSRF guard) |
| `transport` | string | Only `streamable_http` is supported |
| `headers` | array | Static headers sent on every connection. **Key names only** are returned (values are encrypted at rest and never leave the server), and only to `admin+` members — others see `[]` |
| `enabled` | boolean | Disabled servers keep their config but their tools stop being offered to agents |
| `last_tools_sync_at` | timestamp \| null | Last successful tool sync |
| `cached_tools` | array | The synced tool list in OpenAI function format. Tool names are namespaced `mcp_<server-id>_<tool>` to avoid collisions; `mcp.tool_name` is the original name |

---

## Register a server

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/mcp-servers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Internal ops tools",
    "url": "https://mcp.example.com/mcp",
    "headers": [{ "key": "Authorization", "value": "Bearer secret-token" }]
  }'
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `display_name` | string | yes | ≤ 255 chars |
| `url` | string | yes | ≤ 2048 chars; public-IP HTTPS/HTTP endpoint |
| `transport` | string | no | `streamable_http` (the only value) |
| `headers` | array of `{key, value}` | no | Header names must be unique (case-insensitive) |
| `enabled` | boolean | no | Default `true` |

The create **connects to the server and syncs its tools inline** — if
the server is unreachable or the MCP handshake fails, the request
fails with `400` (`{"url": "Unable to synchronize MCP tools: …"}`)
and nothing is saved. Returns `201 Created` with the
[server object](#mcp-server-object).

## Update / delete / re-sync

`PATCH` accepts any subset of the create fields. Changing
`display_name`, `url`, `transport`, or `headers` triggers a re-sync
(same `400` on failure). When updating `headers`, an entry with an
empty `value` keeps the existing stored value for that key — so you
can reorder/rename without re-sending secrets.

`DELETE` returns `204 No Content` (agents attached to the server
simply lose those tools).

`POST /v1/mcp-servers/{id}/sync-tools` re-fetches the tool list and
returns the updated server object — call it after deploying new tools
to your MCP server.

Tool names must be unique on an agent. Turning a server on (`enabled:
true`) returns `400` when one of its tools would share a name with another
tool of an agent that has the server attached, naming the agents and
tools. A sync that would do the same keeps the previous tool list and
explains why in `last_sync_error`.

---

## ThunderPhone as an MCP server

`POST /v1/mcp` is a stateless Streamable HTTP MCP endpoint. It supports
protocol versions `2025-06-18` and `2025-03-26`, plus `initialize`, `ping`,
tools, prompts, resources, and notifications. Point a client at
`https://api.thunderphone.com/v1/mcp` with an `sk_live_` organization API key
as its Bearer token. Session cookies and publishable widget keys are not
accepted.

The server exposes 100 tools, every one listed here by category; the [MCP server guide](/guides/thunderphone-mcp-server) describes each tool's arguments:

| Category | Tools |
| --- | --- |
| Agents | `list_agents`, `get_agent`, `create_agent`, `update_agent`, `deploy_agent`, `discard_agent_draft`, `duplicate_agent`, `delete_agent`, `list_agent_versions`, `review_prompt`, `refactor_prompt`, `list_prompt_revisions`, `list_reusable_instructions`, `create_reusable_instruction` |
| Phone numbers | `list_phone_numbers`, `get_phone_number_limits`, `provision_phone_number`, `list_voip_connections`, `search_voip_numbers`, `import_voip_numbers`, `update_phone_number`, `delete_phone_number`, `get_voip_setup_session`, `answer_voip_setup_question`, `save_voip_setup`, `check_phone_number` |
| Calls | `list_calls`, `get_call`, `get_call_transcript`, `get_call_audio_url`, `get_call_grade`, `place_call`, `export_calls`, `send_sms`, `get_call_analytics`, `get_call_insights` |
| Testing | `list_test_scenarios`, `create_test_scenario`, `generate_test_scenarios`, `run_agent_tests`, `get_test_run`, `list_validation_runs`, `get_validation_status`, `create_talk_link`, `run_simulation`, `get_simulation`, `test_my_agent`, `test_in_text` |
| Agent iteration toolkit (beta, per organization) | `list_conversations`, `get_conversation`, `get_conversation_revisions`, `generate_conversations`, `import_conversations`, `refresh_conversations`, `get_conversation_job`, `run_replays`, `compare_configs`, `get_replay_run` |
| Knowledge | `list_knowledge_bases`, `create_knowledge_base`, `add_knowledge_document`, `import_knowledge_url`, `search_knowledge` |
| Tools and webhooks | `list_integrations`, `create_integration`, `test_integration`, `list_webhook_endpoints`, `create_webhook_endpoint`, `test_webhook_endpoint`, `list_webhook_deliveries`, `list_mcp_servers`, `create_mcp_server`, `sync_mcp_server_tools`, `copy_webhook_endpoint` |
| Campaigns | `list_campaigns`, `create_campaign`, `add_campaign_contacts`, `campaign_action`, `get_campaign_stats`, `check_campaign` |
| Voices | `list_voices`, `preview_voice`, `list_voice_clones` |
| Billing | `get_billing_summary` (read-only; no payment mutation tools) |
| Organization | `get_org_settings`, `update_org_settings`, `get_account_limits`, `list_blocked_callers`, `block_callers`, `unblock_callers` |
| Capabilities and help | `get_supported_languages`, `get_agent_capabilities`, `escalate_to_human`, `request_feature` |
| Imports from other platforms | `start_agent_import`, `get_agent_import`, `commit_agent_import` (the platform key is entered in the dashboard, never passed to a tool) |
| Docs | `search_docs`, `get_doc_page` |
| Connection | `get_connection_identity` (the organization and credential the token belongs to) |

Every tool has `title` and MCP safety annotations. Product tools dispatch
through the same REST views as the public API, retaining organization scoping,
roles, validation, billing admission, quotas, outbound TCPA confirmation,
provider safety, and audit behavior. See
[Use ThunderPhone as an MCP server](/guides/thunderphone-mcp-server) for full
arguments, annotations, prompts, resources, and configuration examples.

Twelve starter prompts cover receptionist creation, test execution,
number provisioning, low-grade call review, knowledge URL attachment,
improving an agent from its calls, checking a change before deploying,
one-step testing, number and campaign diagnosis, a call report and agent
imports. Resources expose `thunderphone://docs/llms.txt`,
`thunderphone://docs/quickstart`, `thunderphone://pricing`, the prompt
style guide that `review_prompt` checks against,
`thunderphone://guides/prompt-style`, and
`thunderphone://guides/working-with-thunderphone`, the working method for
assistants using these tools. Results about an agent, call, number, campaign
or setting carry `web_url`, the matching dashboard page.

Example `tools/call` exchange:

```json Request
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": { "name": "list_agents", "arguments": {} }
}
```

```json Response
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{ "type": "text", "text": "[{\"id\": 12, \"name\": \"Customer Support Agent\", …}]" }],
    "structuredContent": [{ "id": 12, "name": "Customer Support Agent" }],
    "isError": false
  }
}
```

Tool errors are reported in-band (`isError: true`) as a short sentence plus a
JSON block containing `code`, `detail`, and an actionable `next_step`. Unknown
JSON-RPC methods return `-32601` in an HTTP `200` response. Notifications
return `202 Accepted`; JSON-RPC batches return `-32600`; and unsupported GET
or DELETE requests return `405 Method Not Allowed` with `Allow: POST`.

### BAA connector URL

`POST /v1/mcp/baa` is the same server with the same tools. The difference is
call content for organizations whose calls may contain protected health
information (PHI): an organization with a BAA on file, or one whose agents are
designated as processing PHI.

- At `/v1/mcp`, the URL that public assistant directories list, these
  organizations never get call content. `list_calls`, `export_calls`,
  `get_campaign_stats`, `import_conversations`, `refresh_conversations`,
  `run_replays`, `compare_configs` and `get_replay_run` return a tool error
  with `code: "phi_content_unavailable"`. `get_call`, `get_call_transcript`,
  `get_call_audio_url` and `get_call_grade` return it unless the call was
  handled as not containing PHI. Conversation tools serve simulated
  conversations only. Configuration, testing and docs tools are unaffected.
- At `/v1/mcp/baa`, they get call content once an organization admin has
  recorded the [AI assistant BAA confirmation](#ai-assistant-baa-confirmation).
  Without it, the same tool error.

Organizations without PHI see the same results at both URLs. OAuth tokens are
bound to the URL they were issued for: the BAA connector URL has its own
protected-resource metadata at
`/.well-known/oauth-protected-resource/v1/mcp/baa`, and a token issued for
one URL is rejected at the other. Organization API keys work at both.

### AI assistant BAA confirmation

`GET /v1/assistant-baa-attestation` ·
`POST /v1/assistant-baa-attestation` ·
`DELETE /v1/assistant-baa-attestation`

An organization admin's confirmation that every AI assistant workspace the
organization connects through the BAA connector URL is covered by a business
associate agreement between the organization and that assistant's provider.

`GET` returns the current `text_version`, the canonical English statement
(`statement_en`) and its `statement_sha256`, the `connector_url`,
`phi_content_restricted` (whether `/v1/mcp` withholds this organization's call
content), `attested`, and the active `attestation`. `POST` takes
`accepted: true`, the `text_version` and `statement_sha256` from `GET`, and an
optional display `locale`; it returns `201`, or `200` when a confirmation is
already active. `DELETE` withdraws it, effective on the next tool call.

<Note>
  `POST` and `DELETE` need an organization admin signed in as a user. An
  `sk_live_` key gets `403`; `GET` works with a key.
</Note>

---

## Related

<CardGroup cols={2}>
  <Card title="Agents" icon="robot" href="/api-reference/agents">
    Attach servers to an agent with `mcp_server_ids`.
  </Card>
  <Card title="Integrations" icon="plug" href="/api-reference/integrations">
    Simple HTTP tools without an MCP server.
  </Card>
</CardGroup>

<!-- en: api-reference/phone-numbers -->
---
title: "Phone Numbers"
description: "Provision, assign agents to, transfer, and verify phone numbers."
---

A **phone number** belongs to an organization and carries two agent
assignments — one for the inbound direction (who answers) and one for
the outbound direction (who is placed on the caller side). Numbers can
be provisioned by ThunderPhone (a **ThunderPhone number**,
`number_type="thunderphone"` in the API) or brought in through your own VoIP
provider and verified via a [VoIP connection](/api-reference/voip-connections)
(`number_type="voip"`).

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/phone-numbers` | List phone numbers |
| `GET` | `/v1/phone-numbers/limits` | Get the organization cap and usage |
| `GET` | `/v1/phone-numbers/health` | Outbound health of every number |
| `GET` | `/v1/phone-numbers/{phone_number_id}/health` | Outbound health of one number |
| `POST` | `/v1/phone-numbers` | Provision a new number |
| `GET` | `/v1/phone-numbers/{phone_number_id}` | Retrieve a single number |
| `PUT` / `PATCH` | `/v1/phone-numbers/{phone_number_id}` | Assign agents / update status |
| `DELETE` | `/v1/phone-numbers/{phone_number_id}` | Release the number |
| `POST` | `/v1/phone-numbers/{phone_number_id}/transfer` | Move a number to another org |
| `GET` | `/v1/phone-numbers/{phone_number_id}/versions` | List prior assignments |
| `POST` | `/v1/phone-numbers/{phone_number_id}/verify-voip` | Verify a VoIP-sourced number |
| `POST` | `/v1/phone-numbers/{phone_number_id}/test-inbound` | Test that calls to a VoIP-sourced number reach ThunderPhone |
| `GET` | `/v1/outbound-platform-number-request` | Read ThunderPhone-number outbound access and the latest request |
| `POST` | `/v1/outbound-platform-number-request` | Request outbound access for ThunderPhone numbers |

## Phone number object

```json
{
  "id": 201,
  "number": "+15551234567",
  "label": "Support line",
  "source": "voip",
  "number_type": "voip",
  "status": "active",
  "inbound_agent_id": 12,
  "inbound_agent_version_id": null,
  "inbound_agent_version": null,
  "outbound_agent_id": null,
  "voip_connection_id": 5,
  "voip_verification_status": "verified",
  "voip_last_verified_at": "2026-04-20T18:24:10.113Z",
  "voip_inbound_status": "passed",
  "voip_inbound_tested_at": "2026-04-20T18:30:02.518Z",
  "voip_inbound_result": {
    "reason": "arrived",
    "detail": "A test call to +15551234567 reached ThunderPhone after 2.3 seconds.",
    "seconds": 2.3,
    "from_number": "+15550100000"
  },
  "outbound_eligible": true,
  "outbound_ineligible_reason": null,
  "sms_capable": true,
  "sms_capability_checked_at": "2026-09-19T15:42:10.113Z",
  "timezone": null,
  "expected_attestation": {
    "level": "full_expected",
    "label": "Full (A) expected from your carrier"
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Server-assigned number id |
| `number` | string | E.164-formatted phone number (e.g. `+15551234567`) |
| `label` | string | Your display label for the number (also settable via `PATCH`) |
| `number_type` | string | `thunderphone` (provisioned by ThunderPhone) or `voip` (brought via a [VoIP connection](/api-reference/voip-connections)) |
| `source` | string | **Deprecated**, use `number_type`. The same information under legacy values: `demo` means a ThunderPhone number (the value name predates production ThunderPhone numbers and is kept so existing integrations keep working) and `voip` means a VoIP number |
| `status` | string | `provisioning`, `active`, `failed`, `releasing`, or `released` |
| `inbound_agent_id` | integer \| null | Agent that answers inbound calls to this number. When the agent has a [call setup webhook](/webhooks/call-incoming#agent-call-setup-webhook), it runs first to fill in the agent's variables and the call's context. Without an agent, the [`telephony.incoming`](/webhooks/call-incoming) webhook decides; a caller returning one of the number's outbound calls goes to the agent that called them when the webhook gives no answer ([Callbacks](/webhooks/call-incoming#callbacks)) |
| `inbound_agent_version_id` | integer \| null | The published version of the inbound agent this number answers with, an `id` from [`GET /v1/agents/{id}/versions`](/api-reference/agents#version-history). `null` is **Latest**: the agent's published settings at the time of each call. See [Answer with one version of an agent](#answer-with-one-version-of-an-agent) |
| `inbound_agent_version` | object \| null | The pinned version's `id`, `revision` (its number in the agent's history) and `created_at` (when it was published); `null` for Latest |
| `outbound_agent_id` | integer \| null | Agent used when placing outbound calls from this number. ThunderPhone numbers can set this after staff approves outbound access for the organization |
| `voip_connection_id` | integer \| null | Linked VoIP connection (only when `number_type="voip"`) |
| `voip_verification_status` | string | `unverified`, `verified` (an answered probe call), `carrier_accepted` (the carrier accepted the trunk, credentials and caller ID but would not route ThunderPhone's test destination — routable, shown with a caveat), or `failed` |
| `voip_last_verified_at` | timestamp \| null | Last successful verify |
| `voip_inbound_status` | string | Result of the optional [inbound test](#test-inbound-calls-to-a-voip-number): `untested`, `passed` (a call to the number arrived at ThunderPhone) or `failed`. Reads `untested` again once the VoIP connection's routing changes or the number is re-imported. Informational only: it never changes `status` or `voip_verification_status`. Always `untested` for ThunderPhone numbers |
| `voip_inbound_tested_at` | timestamp \| null | When the inbound test behind `voip_inbound_status` ran; `null` while `untested` |
| `voip_inbound_result` | object \| null | That test's `reason`, `detail`, `seconds` (to arrival, on a pass), the `from_number` it called from and its `method` (`loopback` or `platform`, see the [inbound test](#test-inbound-calls-to-a-voip-number)); `null` while `untested` |
| `voip_inbound_test_method` | string \| null | How the next [inbound test](#test-inbound-calls-to-a-voip-number) starts: `loopback` (the number first calls itself through its own outbound SIP trunk; it may still fall back to `platform`) or `platform` (a ThunderPhone test number calls it). `null` for ThunderPhone numbers |
| `voip_outbound_test_method` | string \| null | How the next [verification](#verify-a-voip-sourced-number) calls: `self_call` (manual SIP numbers outside the US and Canada: the number first calls itself through its own SIP trunk; it may still fall back to `platform`) or `platform` (it calls a ThunderPhone number). `null` for ThunderPhone numbers |
| `carrier_routing` | string | Read-only. How your carrier sends this number's calls to ThunderPhone: `direct` for a normal import, `customer` when you route calls yourself (import left the number's call settings at your provider unchanged; see [Keep your own call routing](/guides/bring-your-own-numbers#keep-your-own-call-routing)), or `migration_split` while a migration from another voice platform splits the number's calls between ThunderPhone and that platform. A `migration_split` number cannot be released, re-imported or given another inbound agent until the split is rolled back or completed |
| `outbound_eligible` | boolean | Whether the same local routing and trunk-configuration gate used at call placement currently allows this number to originate a call. This does not probe the carrier or LiveKit over the network. |
| `outbound_ineligible_reason` | string \| null | Stable reason code from the placement gate. ThunderPhone-number access uses `managed_number_inbound_only` before a request, `managed_number_outbound_pending` during review, `managed_number_outbound_denied` after denial, and `managed_number_outbound_revoked` when a prior approval is no longer enabled. Routing failures include codes such as `number_released`, `voip_verification_failed`, `voip_connection_error`, `voip_verification_stale`, and `outbound_trunk_unavailable` |
| `sms_capable` | boolean \| null | Cached carrier capability for customer-connected numbers. `null` means not checked yet. ThunderPhone numbers cannot send SMS |
| `sms_capability_checked_at` | timestamp \| null | When the carrier capability was last checked |
| `timezone` | string \| null | IANA timezone of the number's area code (US and Canada) or country, for example `America/Los_Angeles` for a +1 415 number. `null` when the number spans several zones, such as toll-free numbers. New [campaigns](/api-reference/campaigns) from this number default to it |
| `expected_attestation` | object | The STIR/SHAKEN attestation to expect on calls from this number, as `level` and a plain-English `label`. See [Expected attestation](#expected-attestation) |

---

## List phone numbers

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/phone-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

```python Python
numbers = requests.get(
    "https://api.thunderphone.com/v1/phone-numbers",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
).json()
```
</CodeGroup>

Returns an array of [Phone number objects](#phone-number-object), sorted by `created_at` descending.

---

## Provision a number

Requests a new ThunderPhone number from ThunderPhone's pool, up to the
organization's cap (see [Phone number limits](#phone-number-limits)). To bring
your own number through a VoIP provider, see
[Import VoIP numbers](/api-reference/voip-connections#import-numbers).

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/phone-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"area_code": "415"}'
```

```python Python
number = requests.post(
    "https://api.thunderphone.com/v1/phone-numbers",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={"area_code": "415"},
).json()
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `area_code` | string | no | 3-digit area code to prefer |
| `city` | string | no | US city name |
| `state` | string | no | 2-letter US state code |

Returns `201 Created` with the new [Phone number object](#phone-number-object) in
`status="provisioning"`. The upstream provider usually transitions to
`active` within seconds; poll the detail endpoint to observe the change.

---

## Retrieve a phone number

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/phone-numbers/201 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Returns `200 OK` with a [Phone number object](#phone-number-object), or `404` if not found.

---

## Assign agents / update status

`PATCH` clears or changes inbound/outbound agent assignments. The new
agents must belong to the same org.

<CodeGroup>
```bash cURL
curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/201 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inbound_agent_id": 12,
    "outbound_agent_id": 13
  }'
```

```python Python
number = requests.patch(
    f"https://api.thunderphone.com/v1/phone-numbers/{phone_number_id}",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={"inbound_agent_id": 12, "outbound_agent_id": 13},
).json()
```
</CodeGroup>

| Field | Type | Description |
|-------|------|-------------|
| `inbound_agent_id` | integer \| null | Pass `null` to clear. An agent whose settings use a `{{variable}}` with no default can only be assigned once it has a [call setup webhook](/webhooks/call-incoming#agent-call-setup-webhook) to fill it in; otherwise `400` names the variables |
| `inbound_agent_version_id` | integer \| null | A published version of the inbound agent to answer with, or `null` for Latest. Changing `inbound_agent_id` without it goes back to Latest. See [Answer with one version of an agent](#answer-with-one-version-of-an-agent) |
| `outbound_agent_id` | integer \| null | Pass `null` to clear. ThunderPhone numbers reject assignment with `400` until staff approves outbound access for the organization |
| `label` | string | Display label |
| `status` | string | Usually set by the server; write access is limited to toggling between `active` and `released`. Setting `released` also clears both agent assignments |

Returns `200 OK` with the updated [Phone number object](#phone-number-object).

### Answer with one version of an agent

By default a number answers with its agent's latest published settings,
so every deploy reaches it. To keep a number on one published version
while you change the agent (for example a test number on the next
version, or the main line held back), pin it:

```bash
curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/201 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbound_agent_id": 12, "inbound_agent_version_id": 3051}'
```

Calls to a pinned number run that version's settings: its prompt,
voice, steps, tools, knowledge, transfer numbers and call setup webhook,
and each call records the version it ran. A few things always follow the agent as it is now: its
name, its recording, consent and AI disclosure settings, its PHI
setting, its recorded intro clip, and connected-app tools such as
calendars. A tool connection's own settings are read as they are now;
versions record which connections an agent used, not what was in them.
A pinned number does not take part in the agent's split test.

A version that can no longer run as it was published, because a tool
connection, MCP server, knowledge base or document, reusable instruction,
custom voice or handoff agent it used has been deleted, is refused with
`400`. If one is deleted after you pin the version, calls still run that
version without the missing piece and never switch to Latest on their
own. `"inbound_agent_version_id": null` goes back to Latest.

---

## Outbound platform-number access

ThunderPhone numbers start inbound-only. An organization admin can
request permission to use its ThunderPhone numbers as outbound caller IDs.
Organization API keys cannot submit this request; use a current
human session token or the Phone Numbers page in the dashboard.

<Tip>
We recommend [connecting your own VoIP account](/api-reference/voip-connections)
for outbound calling. Numbers from your own provider can place outbound calls
right away, with no daily limit and no approval step.
</Tip>

### Daily limit

The first request asks for a daily limit: how many outbound calls per day the
organization needs from its ThunderPhone numbers (100 unless you ask for a
different number). ThunderPhone staff approve that number or a different one.
Every call attempt counts, whether or not it is answered, and the count resets
at 00:00 UTC. Once outbound access is enabled, an admin can request a higher
daily limit; staff review each increase. Calls from numbers on your own VoIP
connections never count.

A call that would go over the limit is refused with `429 Too Many Requests`
before anything is dialed:

```json Response
{
  "code": "platform_outbound_daily_limit_reached",
  "detail": "This organization has used all 100 outbound calls for today from ThunderPhone numbers. The limit resets at 00:00 UTC. You can request a higher limit on the Phone numbers page. Calls from your own VoIP numbers have no daily limit.",
  "daily_call_limit": 100,
  "resets_at": "2026-09-29T00:00:00Z"
}
```

Campaigns that reach the limit keep their remaining contacts pending and
continue after the reset.

### Read access and usage

`GET /v1/outbound-platform-number-request` returns the current outbound-access
state and today's usage separately from the latest request. A historical
approval does not mean access is still enabled after ThunderPhone revokes it.

```json Response
{
  "platform_outbound_enabled": true,
  "daily_call_limit": 100,
  "calls_today": 37,
  "resets_at": "2026-09-29T00:00:00Z",
  "default_daily_call_limit": 100,
  "request": {
    "id": 91,
    "kind": "outbound_platform_numbers",
    "status": "approved",
    "requested_count": 100,
    "use_case": "Appointment reminders",
    "expected_daily_calls": null,
    "consent_source": "Patients opt in on the intake form",
    "website": "https://clinic.example.com",
    "denial_reason": "",
    "created_at": "2026-09-19T18:00:00Z",
    "resolved_at": "2026-09-19T19:00:00Z"
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `platform_outbound_enabled` | boolean | Whether ThunderPhone numbers can currently place outbound calls |
| `daily_call_limit` | integer \| null | Outbound calls allowed per UTC day; `null` until enabled |
| `calls_today` | integer | Outbound call attempts from ThunderPhone numbers since 00:00 UTC |
| `resets_at` | timestamp | The next 00:00 UTC |
| `default_daily_call_limit` | integer | The daily limit a first request asks for when it sends no `requested_count` |
| `request` | object \| null | The latest request. `requested_count` is the daily limit it asks for. `expected_daily_calls` is only set on older requests or when you send it |

`request` is `null` before the first request. A denied request, or an approved
request whose access was later revoked, can be followed by a new request.
The same state appears on each ThunderPhone number as
`managed_number_inbound_only`, `managed_number_outbound_pending`,
`managed_number_outbound_denied`, or `managed_number_outbound_revoked` in
`outbound_ineligible_reason`. Once outbound access is enabled, the
number can place calls while it is active, its outbound calling
configuration is available, and the daily limit is not used up.

### Request access or a higher limit

<CodeGroup>
```bash First request
curl -X POST https://api.thunderphone.com/v1/outbound-platform-number-request \
  -H "Authorization: Token tp_sess_YOUR_HUMAN_SESSION" \
  -H "X-ThunderPhone-Org: 42" \
  -H "Content-Type: application/json" \
  -d '{
    "requested_count": 100,
    "use_case": "Appointment reminders",
    "consent_source": "Patients opt in on the intake form",
    "website": "https://clinic.example.com"
  }'
```
```bash Higher limit
curl -X POST https://api.thunderphone.com/v1/outbound-platform-number-request \
  -H "Authorization: Token tp_sess_YOUR_HUMAN_SESSION" \
  -H "X-ThunderPhone-Org: 42" \
  -H "Content-Type: application/json" \
  -d '{
    "requested_count": 500,
    "use_case": "Appointment reminders",
    "consent_source": "Patients opt in on the intake form",
    "website": "https://clinic.example.com"
  }'
```
</CodeGroup>

`requested_count` is the daily limit you ask for, from 1 to 1,000,000. On the
first request it is optional and defaults to 100. Once outbound access is
enabled, it is required and must be more than the current `daily_call_limit`.
`website` accepts a full URL or a bare domain such as `clinic.example.com`,
which is stored as `https://clinic.example.com`. `expected_daily_calls` is
optional.

The response is `201 Created` with the pending request. A request while another
one is pending returns `409 Conflict`.

---

## Release a phone number

<CodeGroup>
```bash cURL
curl -X DELETE https://api.thunderphone.com/v1/phone-numbers/201 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Returns `204 No Content`. ThunderPhone numbers are returned to the pool
(and stop billing); VoIP numbers are detached from the phone record but
remain in your VoIP provider.

---

## Transfer a number to another org

Atomically move a number between orgs. Requires `admin+` in both orgs.
On transfer, the number's inbound/outbound agent assignments are
cleared (agents don't cross org boundaries).

A number always moves to a different organization, so this endpoint needs a
signed-in session (`Authorization: Token <session-token>` plus
`X-ThunderPhone-Org` for the source org). An `sk_live_` API key is limited to
its own organization and gets `403`.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/phone-numbers/201/transfer \
  -H "Authorization: Token YOUR_SESSION_TOKEN" \
  -H "X-ThunderPhone-Org: 42" \
  -H "Content-Type: application/json" \
  -d '{"target_org_id": 77}'
```

```python Python
result = requests.post(
    f"https://api.thunderphone.com/v1/phone-numbers/{phone_number_id}/transfer",
    headers={"Authorization": "Token YOUR_SESSION_TOKEN", "X-ThunderPhone-Org": "42"},
    json={"target_org_id": 77},
).json()
```
</CodeGroup>

```json Response
{
  "source_org_id": 42,
  "target_org_id": 77,
  "cleared_agent_assignments": true,
  "phone_number": { /* Phone number object in the target org */ }
}
```

---

## Version history

Every assignment change records a snapshot so you can audit who
changed what.

<CodeGroup>
```bash cURL
curl 'https://api.thunderphone.com/v1/phone-numbers/201/versions?limit=20' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

```json Response
{
  "count": 2,
  "results": [
    {
      "id": 88,
      "revision": 2,
      "created_by_id": 7,
      "created_at": "2026-04-20T18:24:10.113Z",
      "snapshot": { /* Phone number object at this revision */ },
      "changed_fields": ["inbound_agent_id"]
    }
  ]
}
```

`created_by_id` is the integer user id that made the change (`null`
for system-initiated changes).

---

## Verify a VoIP-sourced number

For numbers imported through a VoIP connection, run (or re-run) the
verification flow. Provider connections (Twilio, Telnyx) re-check the
provider credentials and SIP reachability. **Manual SIP** connections
place a short probe call from this number, through the connection's
trunk, to a ThunderPhone number (LiveKit hangs it up after a few
seconds; your carrier bills it like any call). The carrier's SIP
answer is classified in the evidence — `401`/`407` credentials,
`403` forbidden (credentials or caller ID), `404`/`484` unroutable,
`480`/`408` no answer, `5xx` provider error — and the same text is
returned as the failure reason. One exception is known to be a
post-authentication answer: DIDWW's `403 Destination number
blacklisted by routing plan` means the trunk and credentials were
accepted but the customer's plan does not route ThunderPhone's test
destination. That number becomes `voip_verification_status =
"carrier_accepted"` (evidence `outcome: "carrier_accepted"`): routable,
but calls to other destinations were not tested. Only an answered call
yields `verified`.

**Self-call.** A manual SIP number outside the US and Canada (its
`voip_outbound_test_method` is `self_call`) instead calls itself through
the connection's trunk: a domestic call, so a trunk barred from
international calls can verify. When the call comes back to ThunderPhone
it is hung up before anything answers (no agent, call record or billing),
the number is `verified`, the evidence has `proof: "self-call"`, and the
number's [inbound test](#test-inbound-calls-to-a-voip-number) is
recorded as `passed` too. Answered somewhere else, it is `verified` on
outgoing alone. A `401`/`407`/`403`, or any final refusal 10 seconds or
more after dialing (usually a recorded message such as no credit), fails
verification with that reason. Other refusals, ringing out or a call that
comes back under another caller ID are inconclusive: the number then
calls the ThunderPhone number as above, and the evidence keeps the
self-call under `self_call`. The evidence's `test_method` says which call
decided (`self-call` or `target-call`). The self-call rings for up to 25
seconds. Re-verification that ThunderPhone runs on its own (after a
connection change) never rings a phone unasked: it self-calls only a
number whose inbound test is current and passed, and otherwise calls the
ThunderPhone number.

Verification is admin-only, rate-limited, and serialised per number
(`409` while a verification of the same number is in flight, and
`409` if the number or its connection changed while the probe was
running — verify again). Numbers that are `released` cannot be
verified.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/phone-numbers/201/verify-voip \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

```json Response
{
  "phone_number_id": 201,
  "status": "active",
  "voip_verification_status": "verified",
  "provider_charge_estimate_cents": 0,
  "provider_charge_currency": "usd",
  "provider_charge_note": ""
}
```

Verification may take several seconds; the response reflects the final
state. If verification fails, `voip_verification_status` becomes
`failed` and the phone status returns to `provisioning` — fix the VoIP
connection (credentials, trunk, SIP allowlist) and call this endpoint
again.

Verification proves that the number can place calls. Except for a
self-call that comes back, it never calls the number, so it does not
prove that calls to it reach ThunderPhone; use the inbound test below for
that.

---

## Test inbound calls to a VoIP number

`POST /v1/phone-numbers/{phone_number_id}/test-inbound` calls the number
and checks that your carrier delivers the call back to ThunderPhone. When
it arrives, ThunderPhone hangs up both legs: no agent answers, and nothing
appears in call history or billing. The response reflects the result.

The test uses one of two methods, reported as `inbound_probe.method`:

- `loopback`: for numbers on a connection with its own outbound SIP trunk
  (manual SIP, and Twilio once ThunderPhone has provisioned outbound
  calling in the customer's Twilio account), the number first calls itself
  through that trunk. The number's `voip_inbound_test_method` says in
  advance whether it will. The call goes out through your carrier and back
  in on the number's inbound routing. When it arrives under the number's
  own caller ID, `inbound_probe.proves_outbound` is `true`: that call also
  proves your carrier accepts ThunderPhone's calls as the number. It rings
  for up to 8 seconds (25 seconds outside the US and Canada, where no
  `platform` call can follow it), and waits up to 8 seconds on an answered
  call. A
  phone the number forwards to may therefore ring twice: once showing the
  number's own caller ID, then ThunderPhone's test number if the test
  falls back. A self-call that is refused, rings out or is
  answered without arriving is inconclusive (some carriers refuse or don't
  connect a call from a number to itself), never a failure: the test then
  falls back to `platform`, and `inbound_probe.loopback` records what the
  self-call did (`outcome` `refused`, `no_arrival`, `answered_no_arrival`
  or `platform_error`, with `sip_status_code` and the carrier's
  `carrier_message`).
- `platform`: a ThunderPhone test number calls the number. It rings for up
  to 8 seconds; if something answers before the call reaches ThunderPhone
  (a Twilio app that answers and then forwards, a phone menu), the test
  stays on the line for up to 15 seconds waiting for the forwarded call.

The whole test takes up to about 30 seconds, or about 50 when a self-call
falls back.

The test is optional and informational. It never changes the number's
`status`, `voip_verification_status` or whether it can route calls, and
ThunderPhone never runs it on its own (re-verification after a connection
change is outbound only). The number must be `active` and verified
(`voip_verification_status` of `verified` or `carrier_accepted`), otherwise
the request returns `400`. It is admin-only, shares verification's rate
limit, and returns `409` while a verification or another inbound test of
the same number is running, or if the number or its connection changed
during the test.

`inbound_probe.status` is one of:

| Status | Meaning |
|--------|---------|
| `pass` | The call reached ThunderPhone, with `seconds_to_arrival`. `reason` is `arrived`, or `arrived_caller_id_changed` when a call to the number arrived during the test under another caller ID, most likely the test call after a carrier changed its caller ID. That call is handled as an ordinary call, so your agent may answer it for a moment |
| `fail` | It did not. `reason` is `no_arrival` (it rang for 8 seconds without reaching ThunderPhone), `answered_elsewhere` (something answered it and it had not reached ThunderPhone 15 seconds later: a phone, voicemail, another service, or a forward to the wrong address), `busy`, `unroutable` or `forbidden` (refused by the carrier). On a Manual SIP connection with Allowed Source IPs, a call that reached ThunderPhone in a way real calls are refused also fails: `direct_source_not_allowed` (it came straight to ThunderPhone, not through `sip.thunderphone.com`), `edge_source_not_allowed` (it came from an address not on the list; `detail` names it) or `edge_source_unverified` (its source address couldn't be verified) |
| `unavailable` | ThunderPhone could not run the test (not configured, a problem on ThunderPhone's side, or `reason` `country_not_dialable`: ThunderPhone can't place test calls to the number's country yet, currently numbers outside the US and Canada). After an inconclusive self-call that the `platform` method cannot follow up, `reason` is `loopback_refused` (the self-call was refused; see `loopback.carrier_message`) or `loopback_inconclusive` (it went out but didn't come back). `source_unconfirmed`: the call reached ThunderPhone, but where it came from couldn't be read, so whether Allowed Source IPs let it in is unknown. None of these says anything about the number's inbound routing. Nothing is recorded and the previous result stays |

A `pass` or `fail` is stored on the number as `voip_inbound_status`,
`voip_inbound_tested_at` and `voip_inbound_result`, and resets to
`untested` when the VoIP connection's routing or Allowed Source IPs
change, or the number is re-imported. If `answered_elsewhere` comes back, your carrier answered the
test call somewhere else; it may bill up to about 20 seconds.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/phone-numbers/201/test-inbound \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

```json Response
{
  "phone_number_id": 201,
  "voip_inbound_status": "passed",
  "voip_inbound_tested_at": "2026-04-20T18:30:02.518Z",
  "inbound_probe": {
    "status": "pass",
    "reason": "arrived",
    "detail": "A test call to +15551234567 reached ThunderPhone after 2.3 seconds.",
    "seconds_to_arrival": 2.3,
    "from_number": "+15550100000",
    "tested_at": "2026-04-20T18:30:02.518Z",
    "method": "platform",
    "loopback": null,
    "proves_outbound": false
  }
}
```

---

## Outbound number health

Carrier analytics (Hiya for AT&T, TNS for Verizon, First Orion for T-Mobile)
label numbers as spam from how they call: how many calls a number places a
day, how many end within seconds, and how often a person answers. They don't
share their scores. These endpoints read the same signals from your own
outbound calls, so you can slow down or fix a number before it gets labeled.
Treat them as a guide, not as any carrier's actual label.

`GET /v1/phone-numbers/health` returns every number in the organization in one
response; `GET /v1/phone-numbers/{phone_number_id}/health` returns one. Both
take the same authentication as listing phone numbers. A number that placed no
outbound calls comes back `good` with zeros.

```json
{
  "phone_number_id": 201,
  "number": "+15551234567",
  "expected_attestation": {"level": "full_expected", "label": "Full (A) expected from your carrier"},
  "status": "at_risk",
  "reasons": [
    {
      "code": "high_daily_volume",
      "severity": "at_risk",
      "message": "Over 100 calls a day from one number",
      "params": {"calls": 100}
    }
  ],
  "windows": {
    "1d": {"outbound_calls": 142, "connected_calls": 61, "rang_unanswered_calls": 74, "peak_calls_per_day": 142, "answer_outcome_calls": 135, "human_answer_rate": 0.31, "voicemail_rate": 0.12, "short_call_share": 0.36, "short_ring_share": 0.08, "average_talk_seconds": 74.2, "average_ring_seconds": 24.5, "status": "at_risk", "reasons": [{"code": "high_daily_volume", "severity": "at_risk", "message": "Over 100 calls a day from one number", "params": {"calls": 100}}]},
    "7d": {"...": "same fields"},
    "30d": {"...": "same fields"}
  }
}
```

The list endpoint wraps these in `{"results": [...]}`.

| Field | Description |
|-------|-------------|
| `status`, `reasons` | From the last 7 days: `good`, `watch` or `at_risk`, with the reasons worst first. Each reason has a `code`, a `severity` (`watch` or `at_risk`), a plain-English `message` and the numbers in it as `params` |
| `windows` | The same figures for the last day (`1d`), week (`7d`) and 30 days (`30d`), each with its own `status` and `reasons` |
| `outbound_calls` | Outbound calls placed from the number |
| `connected_calls` | Calls that were answered (by anyone or anything) |
| `rang_unanswered_calls` | Calls that rang out, were busy or were declined |
| `peak_calls_per_day` | Calls on the busiest day, in the number's own time zone (its area code's, else your organization's, else UTC). For `1d`, the last 24 hours |
| `answer_outcome_calls` | Calls the answer rates are computed on: answered calls that say who answered ([`answered_by`](/api-reference/calls#call-object)), and calls that rang out since your organization's calls started saying so. Earlier calls are left out rather than counted as unanswered |
| `human_answer_rate` | Share of `answer_outcome_calls` a person answered (`answered_by` `human`). `null` with none |
| `voicemail_rate` | Share that went to voicemail, on the same base |
| `short_call_share` | Share of answered calls that lasted under 10 seconds |
| `short_ring_share` | Share of unanswered calls that rang under 12 seconds (below the 14-second [outbound ring floor](/api-reference/outbound-calls), so it counts calls the callee declined or the carrier cut off) |
| `average_talk_seconds`, `average_ring_seconds` | Average time on answered calls, and average ring time of unanswered ones |

| Reason `code` | `watch` | `at_risk` |
|------|---------|-----------|
| `high_daily_volume` | Over 50 calls on the busiest day | Over 100 |
| `low_answer_rate` | Fewer than 1 in 5 calls reach a person | Fewer than 1 in 10 |
| `short_calls` | Over 30% of answered calls under 10 seconds | Over half |
| `short_rings` | Over half of unanswered calls ring under 12 seconds | — |

Answer rates and short-call shares count only once a window has enough calls:
20 `answer_outcome_calls` for `low_answer_rate`, 10 answered for `short_calls`, 10 rung out for
`short_rings`. More reason codes may be added; show `message` for any you don't
recognize.

### Expected attestation

Carriers sign each outbound call with a STIR/SHAKEN attestation: **A** when
they know the caller owns the number, **B** when they know the caller but not
the number. B calls are labeled spam more often. ThunderPhone can't see the
signature a call actually got, so `expected_attestation` says what to expect
from where the number lives:

| `level` | Number | `label` |
|---------|--------|---------|
| `full` | A ThunderPhone number | Full (A) |
| `full_expected` | A number on your Telnyx, SignalWire or Vonage account, or a Twilio number with approved verified caller ID | Full (A) expected from your carrier |
| `carrier` | A number on a manual SIP trunk | Set by your carrier. Ask them for A attestation. |
| `partial_likely` | A caller ID your carrier account does not own. Reserved: not returned yet, since every imported number comes from your carrier account's own list | Partial (B) likely; calls are more likely to be labeled spam |
| `partial_until_registered` | A Twilio number without approved verified caller ID ([register it](/guides/caller-id-and-spam-registration)). Twilio signs its calls B until then | Partial (B) until you register verified caller ID |
| `unknown` | A VoIP number whose connection is gone | Unknown |

---

## Phone number limits

`GET /v1/phone-numbers/limits` returns the current organization's ThunderPhone
number cap and usage. Authentication and organization selection are the same as
for listing phone numbers.

```json
{"max_platform_numbers": 25, "platform_numbers_used": 3}
```

Usage counts platform numbers that are provisioning, active, or releasing.
Request a higher limit from the Phone numbers page.

---

## Related

<CardGroup cols={2}>
  <Card title="Agents" icon="robot" href="/api-reference/agents">
    Configure the voice agents you assign to these numbers.
  </Card>
  <Card title="VoIP Connections" icon="phone-volume" href="/api-reference/voip-connections">
    Bring your own phone numbers via Twilio, Telnyx, and more.
  </Card>
  <Card title="Phone Number Labels" icon="tag" href="/api-reference/phone-number-labels">
    Tag caller phone numbers that show up in call history.
  </Card>
  <Card title="Calls" icon="phone" href="/api-reference/calls">
    See call history filtered by phone number.
  </Card>
</CardGroup>

<!-- en: api-reference/caller-registration -->
---
title: "Caller Registration"
description: "Set the caller name your ThunderPhone numbers show, and register numbers in your own Twilio or Telnyx account for caller name, verified caller ID and spam-filter registration."
---

These endpoints manage what carriers show and how they score your calls. The
product guide is [Caller ID and spam registration](/guides/caller-id-and-spam-registration).
Everything here is free.

- **ThunderPhone numbers** get the organization's caller name automatically:
  on purchase, and again whenever the caller name is saved.
- **Numbers in your own carrier account** are registered only when you ask:
  Telnyx numbers can get a caller name; Twilio numbers can get a caller name,
  verified caller ID (SHAKEN/STIR) and spam-filter registration (Twilio Voice
  Integrity). ThunderPhone uses the credentials saved on the number's
  [VoIP connection](/api-reference/voip-connections).

Reads, and `POST /refresh`, are open to any organization role. Other changes
need an admin or owner.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/caller-registration` | Caller name setting and every number's registrations |
| `PUT` | `/v1/caller-registration/caller-name` | Save the caller name |
| `POST` | `/v1/caller-registration/register` | Register numbers in your own carrier account |
| `GET` | `/v1/caller-registration/twilio-business-profile` | Check a Twilio account's Primary Business Profile |
| `POST` | `/v1/caller-registration/refresh` | Check registrations under review now |
| `DELETE` | `/v1/caller-registration/registrations/{registration_id}` | Turn off a Telnyx caller name |

## Registration object

```json
{
  "id": 41,
  "phone_number_id": 812,
  "kind": "shaken_stir",
  "provider": "twilio",
  "status": "in_review",
  "display_name": "",
  "status_detail": "Twilio is reviewing it. This usually takes 1 to 3 days.",
  "trust_product_sid": "BU0123456789abcdef0123456789abcdef",
  "submitted_at": "2026-10-23T18:02:11.204Z",
  "checked_at": "2026-10-23T19:02:40.517Z",
  "updated_at": "2026-10-23T19:02:40.517Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Registration id |
| `phone_number_id` | integer | The [phone number](/api-reference/phone-numbers) it belongs to |
| `kind` | string | `cnam` (caller name), `shaken_stir` (verified caller ID) or `voice_integrity` (spam-filter registration) |
| `provider` | string | `telnyx` or `twilio`: the account the registration lives in |
| `status` | string | `pending` (being sent), `submitted`, `in_review`, `approved`, `rejected`, `failed` or `off` |
| `display_name` | string | `cnam` only: the name shown on calls |
| `status_detail` | string | Plain-language detail: a rejection reason, what failed, or what happens next |
| `trust_product_sid` | string | Twilio only: the Trust Hub registration the number joined |
| `submitted_at`, `checked_at`, `updated_at` | timestamp or null | ISO 8601 UTC. `checked_at` is the last time ThunderPhone read the status from the carrier |

ThunderPhone sends pending registrations within a few minutes and retries when
the carrier is unreachable. It checks registrations under review about once an
hour; carriers usually decide within 1 to 3 days. A registration whose number
leaves your account, or its carrier account, turns `off`.

---

## Get registrations

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/caller-registration \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

```json
{
  "caller_name": {
    "caller_name": "",
    "enabled": true,
    "default_caller_name": "Acme Plumbing",
    "effective_caller_name": "Acme Plumbing",
    "max_length": 15
  },
  "numbers": [
    {
      "phone_number_id": 812,
      "number": "+12125550101",
      "label": "Main line",
      "number_type": "voip",
      "carrier": "twilio",
      "voip_connection_id": 37,
      "eligible_kinds": ["cnam", "shaken_stir", "voice_integrity"],
      "registrations": {
        "cnam": null,
        "shaken_stir": { "id": 41, "kind": "shaken_stir", "status": "in_review", "...": "..." },
        "voice_integrity": null
      }
    }
  ],
  "voice_integrity_use_cases": ["Appointment Reminders", "Customer Support", "..."],
  "twilio_trust_hub_url": "https://console.twilio.com/us1/account/trust-hub/overview"
}
```

| Field | Description |
|-------|-------------|
| `caller_name.caller_name` | The saved name; blank means "use the organization's name" |
| `caller_name.default_caller_name` | The organization name cut to a valid caller name; blank when the organization still has its generated name (such as "Jane's Team") |
| `caller_name.effective_caller_name` | What ThunderPhone numbers show; blank when turned off or when there is no usable name |
| `numbers[].carrier` | `thunderphone`, `twilio`, `telnyx`, `signalwire`, `vonage`, `manual` or `other` |
| `numbers[].eligible_kinds` | What you can register on this number yourself. Empty for ThunderPhone numbers (handled automatically) and for carriers ThunderPhone can't register with; never `cnam` for toll-free or non-US numbers |
| `numbers[].registrations` | One [registration object](#registration-object) or `null` per kind |

---

## Save the caller name

Applies to every ThunderPhone number the organization has, and to numbers it
buys later.

<CodeGroup>
```bash cURL
curl -X PUT https://api.thunderphone.com/v1/caller-registration/caller-name \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"caller_name": "Acme Plumbing", "enabled": true}'
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `caller_name` | string | no | 1 to 15 letters, numbers and spaces, starting with a letter. `""` uses the organization's name |
| `enabled` | boolean | no | `false` stops showing a caller name on ThunderPhone numbers |

Returns `200 OK` with the same body as [Get registrations](#get-registrations).
An invalid name returns `400` with the reason under `caller_name`.

---

## Register numbers

Registers numbers in the organization's own Twilio or Telnyx account. This
changes that account: for Twilio, ThunderPhone adds each number to the
account's Primary Business Profile, reuses the account's existing registration
of that kind (or creates one), adds the numbers to it and submits it for
review. Repeating a request never creates duplicates.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/caller-registration/register \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "voice_integrity",
    "phone_number_ids": [812, 813],
    "voice_integrity": {
      "use_case": "Appointment Reminders",
      "employee_count": 12,
      "daily_call_volume": 300
    }
  }'
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `kind` | string | yes | `cnam`, `shaken_stir` or `voice_integrity`. Telnyx numbers take `cnam` only |
| `phone_number_ids` | integer[] | yes | 1 to 200 of your numbers on a Twilio or Telnyx connection |
| `display_name` | string | no | `cnam` only. Defaults to the organization's caller name |
| `voice_integrity` | object | for `voice_integrity` | `use_case` (one of `voice_integrity_use_cases`), `employee_count` and `daily_call_volume` (whole numbers, 1 or more) |

Returns `202 Accepted` with `{"registrations": [...]}` (status `pending`).

When the Twilio account already has a registration of that kind, the numbers
join it. For `voice_integrity` the answers sent now are then not used; change
them in Twilio's Trust Hub.

| Status | When |
|--------|------|
| `400` | A ThunderPhone number (its caller name is automatic), a kind the number's carrier doesn't support (caller names are for US local numbers only, not toll-free), an invalid name, missing Voice Integrity answers, or no contact email on the requesting user (Twilio needs one) |
| `404` | A number that isn't in your organization |
| `409` | The Twilio account has no approved Primary Business Profile: `code` is `business_profile_required`, with `console_url` and `business_profile_status`. A `409` with no `code` means the Twilio credentials are incomplete or Twilio refused the check; the reason is in `detail` |
| `503` | Twilio couldn't be reached to check the Business Profile; try again |

---

## Check a Twilio Business Profile

`GET /v1/caller-registration/twilio-business-profile?connection_id=37` reads the
Twilio account behind that connection.

```json
{
  "connection_id": 37,
  "business_profile": {
    "sid": "BU0123456789abcdef0123456789abcdef",
    "friendly_name": "Acme Plumbing",
    "status": "twilio-approved",
    "approved": true
  },
  "console_url": "https://console.twilio.com/us1/account/trust-hub/overview"
}
```

`business_profile` is `null` when the account has none. `status` is Twilio's:
`draft`, `pending-review`, `in-review`, `twilio-approved` or `twilio-rejected`.

---

## Refresh status

`POST /v1/caller-registration/refresh` reads every registration under review
from the carrier now (each at most once a minute) and returns the same body as
[Get registrations](#get-registrations).

---

## Turn off a Telnyx caller name

`DELETE /v1/caller-registration/registrations/{registration_id}` removes the
caller name from a number in your Telnyx account. Returns `202` with the
registration (status `pending`, then `off`). It returns `400` for Twilio
registrations (remove those in Twilio's Trust Hub) and for a ThunderPhone
number's caller name (turn that off with [Save the caller name](#save-the-caller-name)).

## Related

- [Caller ID and spam registration](/guides/caller-id-and-spam-registration)
- [Phone numbers](/api-reference/phone-numbers)
- [VoIP connections](/api-reference/voip-connections)

<!-- en: api-reference/sms -->
---
title: "SMS"
description: "Send and inspect SMS messages through your connected VoIP carrier account."
---

SMS uses a number on your organization's connected Twilio or Telnyx account.
ThunderPhone-owned numbers cannot send SMS. Your carrier account must have the
required messaging profile, registration, consent, and funds.
Every text honors your organization's [opt-out list](/api-reference/opt-outs):
a text to a number opted out of `sms` is refused with `409`
`contact_opted_out`, and so are the agent tool's texts, follow-ups and
retries. ThunderPhone does not handle inbound STOP replies in this release;
the person's carrier and your carrier configuration enforce those. When the
carrier refuses a text because the recipient opted out with it, the number is
recorded on the opt-out list as a `carrier` row.

To send a text later, such as an appointment reminder, use
[scheduled sends](/api-reference/scheduled-sends).

A US local number on Twilio can send only once it is registered for A2P 10DLC:
the number must be in a Twilio Messaging Service whose A2P campaign Twilio has
approved (`VERIFIED`). US carriers block texts from unregistered local numbers.
ThunderPhone sends Twilio messages through the number's Messaging Service, and
the phone number's `sms_registration_status` and `sms_not_ready_reason` say
what is missing. Toll-free numbers are not checked for toll-free verification.

A carrier capability failure is cached for at most five minutes. After fixing
a Twilio capability or registration, or attaching a Telnyx messaging profile,
retry after that window; the next configuration or send check refreshes the
negative result. A number waiting on its 10DLC registration is also rechecked
hourly.

An `accepted` response means the carrier accepted the request. It does not
confirm handset delivery. For Twilio senders, ThunderPhone records Twilio's
later delivery report on the message: `delivery_status` (`queued`, `sending`,
`sent`, `delivered`, `undelivered` or `failed`), `delivered_at` or
`delivery_failed_at`, and Twilio's numeric code in `provider_error_code`. An
undelivered or failed report also sets `error_code` and `error_message` and
emits `sms.failed`; `status` stays `accepted`. Telnyx delivery receipts and
inbound messages are not part of this release.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/sms` | Send an SMS |
| `GET` | `/v1/sms` | List SMS messages |
| `GET` | `/v1/sms/{message_id}` | Retrieve one SMS message |

OAuth clients need `sms:write` to send and `sms:read` to list or retrieve.
Send requests are limited per organization. The default is 30 requests per
minute across REST, agent-tool, post-call follow-up, campaign pre-call and
[scheduled](/api-reference/scheduled-sends) sends. Each call is
also limited to three requests that reach the shared send service, including
validation, capability, and carrier failures. Tool requests rejected before
that service, such as a malformed argument or unauthorized label, do not use a
slot.

## Send a message

```bash
curl -X POST https://api.thunderphone.com/v1/sms \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Idempotency-Key: appointment-confirmation-123" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to": "+14155550199",
    "body": "Your appointment is confirmed for Tuesday at 2 PM."
  }'
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `from_number` | E.164 string | yes | Active SMS-capable number on this organization's connected Twilio or Telnyx account |
| `to` | E.164 string | yes | Recipient |
| `body` | string | yes | Non-empty plain text, up to 10 SMS segments |

`Idempotency-Key` is a required request header containing 1–128 characters.
It is scoped to your organization. Replaying the same key with the identical
sender, recipient, and body returns the original outcome without sending
again. Reusing it with different content returns `409 Conflict`.

The body is capped at 1600 characters and 10 encoded SMS segments. The segment
limit is usually reached first.

Returns `201 Created` when the carrier accepts the message. The response
includes `status: "accepted"`, the carrier `provider_id`, and `segment_count`.
Carrier acceptance is not a delivery receipt.

An identical idempotent replay may return `202 Accepted` while the original
durable message is still pending. Poll `GET /v1/sms/{message_id}` for its
terminal outcome; the replay never starts a second send.

Permanent carrier rejection returns an actionable error and the durable failed
message record when an attempt reached the carrier. Stable error codes include:

| Code | Meaning |
|------|---------|
| `messaging_not_registered` | The customer sender needs carrier messaging registration (such as US A2P 10DLC) or a messaging profile |
| `recipient_opted_out` | The carrier refused the text because the recipient opted out from this sender |
| `contact_opted_out` | `409`: the recipient is on your organization's [opt-out list](/api-reference/opt-outs) for texts. Nothing was sent |
| `invalid_number` | A sender or recipient is not valid for SMS |
| `not_sms_capable` | The carrier does not report SMS support for the sender |
| `carrier_rejected` | The carrier rejected the request for another permanent reason |
| `carrier_response_invalid` | The carrier returned success without a readable message id; status is `unknown`, so check the carrier log before any manual resend |
| `delivery_outcome_unknown` | The carrier may have accepted the message, but ThunderPhone did not receive or persist a definitive outcome; check the carrier log and do not blindly resend |
| `rate_limited` / `carrier_unavailable` | A documented carrier non-acceptance or failure proven to occur before request bytes may receive a bounded retry; capability preflight failures share the same attempt bound, while an organization limit does not contact the carrier |

`status: "unknown"` is terminal. It covers read timeouts, post-send connection
resets, and interruptions after sending may have started but before the outcome
was recorded. ThunderPhone never retries an `unknown` message automatically.
`sms.failed` is emitted with `status: "unknown"` so webhook consumers can
distinguish it from a confirmed carrier rejection.

Before manually resending an `unknown` message, reconcile it with the carrier;
an empty carrier log alone is not proof of non-delivery, and if the original
attempt cannot be confirmed finished, a resend may create a duplicate. Waiting
for a fixed amount of time does not prove that the original attempt has ended.

ThunderPhone may retry only when it can establish that no carrier request
started. Once a request may have reached the carrier, any unconfirmed outcome
is terminal `unknown`. HTTP 5xx and gateway responses are also terminal
`unknown` because they do not prove that the carrier rejected the request.

ThunderPhone never falls back to a platform-owned sender.

## Agent recipient permissions

The built-in `send_sms` tool always permits the other party on a telephone
call. Set `sms_allowed_recipients` on the agent to authorize up to 10 named
contacts, such as an on-call technician or office manager. Each entry contains
a unique E.164 `number` and a unique normalized, case-insensitive `label`;
labels are 1–60 characters and cannot look like phone numbers or contain
control, bidi, or invisible characters. Labels are caller-visible public
metadata. The model sees only labels; the server resolves a label to the
private number from the immutable call-time routing snapshot.

Configured contacts also make the tool available to widget, mic, realtime,
and simulation sessions, which have no telephone other party. The call-time
recipient list is immutable for that session, so editing the agent does not
change an active call's authority.

<Warning>
  These are real sends, including from public widgets and test/simulation
  sessions. A visitor or tester can ask the agent to text any configured
  contact. The three-request per-call cap and shared organization rate limit
  bound this exposure; use only labels and contacts suitable for callers.
</Warning>

`sms_allow_other_recipients` is the broadest tier. When it is `true`, the agent
can text any valid E.164 number, including any number a caller dictates. Leave
it `false` when the caller and configured contacts are sufficient.

## List messages

```bash
curl 'https://api.thunderphone.com/v1/sms?status=accepted&limit=50' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

Optional filters are `status`, `direction`, `from_number`, `to`, `call_id`,
and `agent_id`. `limit` is 1–200 and `offset` is at most 100000. Results are
newest first and scoped to the authenticated organization.

`source` says what sent the message: `api`, `agent_tool`, `followup` (a
post-call follow-up), `pre_call` (a campaign's
[text before calling](/api-reference/campaigns#text-before-calling)) or
`scheduled` (a [scheduled send](/api-reference/scheduled-sends)).
Pre-call texts are never retried automatically.

```json
{
  "count": 1,
  "results": [
    {
      "id": "313a3117-827b-46e9-a01a-ac1493838724",
      "from_number": "+15551234567",
      "to": "+14155550199",
      "body": "Your appointment is confirmed for Tuesday at 2 PM.",
      "direction": "outbound",
      "source": "api",
      "status": "accepted",
      "provider": "twilio",
      "provider_id": "SM0123456789abcdef0123456789abcdef",
      "segment_count": 1,
      "error_code": "",
      "error_message": "",
      "call_id": null,
      "agent_id": null,
      "attempt_count": 1,
      "attempt_started_at": null,
      "next_attempt_at": null,
      "accepted_at": "2026-09-19T15:42:10.113Z",
      "delivery_status": "delivered",
      "delivered_at": "2026-09-19T15:42:13.402Z",
      "delivery_failed_at": null,
      "provider_error_code": "",
      "created_at": "2026-09-19T15:42:09.901Z",
      "updated_at": "2026-09-19T15:42:10.113Z"
    }
  ]
}
```

## Retrieve a message

```bash
curl https://api.thunderphone.com/v1/sms/313a3117-827b-46e9-a01a-ac1493838724 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

Returns the same message object, or `404` when the id is not in the
authenticated organization.

<!-- en: api-reference/scheduled-sends -->
---
title: "Scheduled Sends"
description: "Schedule a text or an outbound call to one contact at a set time, then move, edit or cancel it before it goes out."
---

A scheduled send is one text or one outbound call to one contact at a set
time: an appointment reminder, a follow-up the next morning, a callback. You
create it now; ThunderPhone sends it when it comes due. One list holds every
send, so you can look them up and cancel them in one place.

- **Texts** go out through [`/v1/sms`](/api-reference/sms) rules: an active,
  SMS-capable number on your connected Twilio or Telnyx account.
- **Calls** are placed like [`POST /v1/call`](/api-reference/outbound-calls)
  with a saved agent, and need the same outbound-enabled `from_number` and
  [TCPA confirmation](/api-reference/outbound-calls#outbound-tcpa-confirmation).
- A send is checked when you create it, so you hear about a problem at once,
  and checked again when it comes due.
- Nothing is sent late. A send that cannot go out before its `expires_at` is
  skipped, never sent afterwards.
- Every send honors your organization's [opt-out list](/api-reference/opt-outs).

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/scheduled` | Schedule a text or call |
| `GET` | `/v1/scheduled` | List scheduled sends |
| `GET` | `/v1/scheduled/{send_id}` | Retrieve a scheduled send |
| `PATCH` | `/v1/scheduled/{send_id}` | Move or edit a send that is still `scheduled` |
| `DELETE` | `/v1/scheduled/{send_id}` | Cancel one send |
| `POST` | `/v1/scheduled/cancel` | Cancel every queued send for an `external_id` or a number |

Authenticate with an organization API key. These endpoints are not available
to OAuth clients. In a dashboard session any member can schedule texts, and
scheduling or editing a call requires an admin or owner, the same as
`POST /v1/call`; organization API keys are not limited by role.

## Scheduled send object

```json
{
  "id": "6f1c0b8e-3a52-4c1f-9a0b-2f4f7d8a91c3",
  "type": "sms",
  "status": "scheduled",
  "status_reason": "",
  "status_detail": "",
  "send_at": "2026-11-03T17:00:00Z",
  "expires_at": "2026-11-03T17:30:00Z",
  "from_number": "+15551234567",
  "to": "+14155550199",
  "body": "Hi {{name}}, a reminder of your appointment tomorrow at {{time}}.",
  "agent_id": null,
  "variables": {"name": "Ada", "time": "10:30 AM"},
  "context": "",
  "timezone": "America/Los_Angeles",
  "allow_quiet_hours": false,
  "external_id": "appointment-4815",
  "source": "api",
  "source_call_id": null,
  "consent": {"type": "customer_attests"},
  "simulated": false,
  "sms_message_id": null,
  "call_id": null,
  "sent_at": null,
  "created_at": "2026-11-01T18:02:11.204Z",
  "updated_at": "2026-11-01T18:02:11.204Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | string (UUID) | Id of the send |
| `type` | string | `sms` or `call` |
| `status` | string | See [statuses](#statuses) |
| `status_reason` | string | Why a send was `skipped` or `failed`; empty otherwise |
| `status_detail` | string | Readable explanation of `status_reason` |
| `send_at` | timestamp | When it goes out |
| `expires_at` | timestamp | It is never sent after this |
| `from_number` | string | Sending number, E.164 |
| `to` | string | Recipient, E.164 |
| `body` | string | Texts: the template, as stored. `{{name}}` placeholders are filled from `variables` when the text is sent. Empty for calls |
| `agent_id` | integer \| null | Calls: the agent that places the call. Null for texts, or when the agent was deleted |
| `variables` | object \| null | Values for `{{name}}` placeholders: the text's body, or the call's agent prompt as in [call variables](/guides/call-variables) |
| `context` | string | Calls: free text added to the agent's prompt for this call |
| `timezone` | string | The recipient's time zone that quiet hours were checked in; empty when it could not be told |
| `allow_quiet_hours` | boolean | `true` when you chose to send outside quiet hours |
| `external_id` | string | Your own key for the send, such as an appointment id |
| `source` | string | What created it: `api` |
| `source_call_id` | integer \| null | The call that created it, when one did |
| `consent` | object | The consent the send relies on. API sends record `{"type": "customer_attests"}`: your organization attests that it has the contact's consent |
| `simulated` | boolean | `true` for sends created on a test call. They are never sent |
| `sms_message_id` | string \| null | Texts: the [SMS message](/api-reference/sms#retrieve-a-message) it produced |
| `call_id` | integer \| null | Calls: the [call](/api-reference/calls) it placed |
| `sent_at` | timestamp \| null | When it went out |
| `created_at`, `updated_at` | timestamp | ISO 8601 UTC |

### Statuses

| Status | Meaning |
|--------|---------|
| `scheduled` | Waiting for `send_at`. Only a `scheduled` send can be edited or canceled |
| `sending` | Being sent now |
| `sent` | Went out. For a text, the carrier accepted it; for a call, it was placed. See `sms_message_id` or `call_id` for what happened next |
| `canceled` | You canceled it |
| `skipped` | Not sent, on purpose. `status_reason` says why |
| `failed` | Tried and did not go out. `status_reason` holds the send's own error code, such as an [SMS error code](/api-reference/sms#send-a-message) or the call's refusal reason |

`skipped` reasons:

| `status_reason` | Meaning |
|-----------------|---------|
| `expired` | It could not go out before `expires_at`, so it was not sent late |
| `opted_out` | The number is on your [opt-out list](/api-reference/opt-outs) for this channel |
| `quiet_hours` | It came due outside 8am to 9pm in the recipient's time zone, for example after waiting behind other texts |
| `sender_not_ready` | The text's `from_number` can no longer send, for example its messaging registration lapsed |
| `outbound_tcpa_unconfirmed` | A call came due before your organization's TCPA confirmation was recorded |

A send that ends `skipped` or `failed` fires the
[`scheduled.skipped` or `scheduled.failed`](/webhooks/events#scheduled-events)
webhook. A sent text fires the usual `sms.*` events with `scheduled_send_id`
set; a placed call fires the usual call events, and its
[`telephony.complete`](/webhooks/call-complete) event carries `scheduled_send_id`.

## Schedule a send

<CodeGroup>
```bash Text
curl -X POST https://api.thunderphone.com/v1/scheduled \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sms",
    "send_at": "2026-11-03T09:00:00-08:00",
    "from_number": "+15551234567",
    "to": "+14155550199",
    "body": "Hi {{name}}, a reminder of your appointment tomorrow at {{time}}.",
    "variables": {"name": "Ada", "time": "10:30 AM"},
    "external_id": "appointment-4815",
    "idempotency_key": "appointment-4815-reminder"
  }'
```

```bash Call
curl -X POST https://api.thunderphone.com/v1/scheduled \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "call",
    "send_at": "2026-11-03T10:00:00-08:00",
    "from_number": "+15551234567",
    "to": "+14155550199",
    "agent_id": 12,
    "variables": {"name": "Ada"},
    "context": "Ada asked for a call back about rescheduling her appointment.",
    "external_id": "appointment-4815"
  }'
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `type` | string | yes | `sms` or `call` |
| `send_at` | timestamp | yes | ISO 8601 with a UTC offset; a time without one is read as UTC. At most 90 days ahead. A time up to a minute in the past goes out on the next run |
| `to` | string | yes | Recipient, E.164 |
| `from_number` | string | yes | Texts: an SMS-capable number on your connected carrier account. Calls: an active, outbound-enabled number of your organization |
| `body` | string | texts | The text, up to 1600 characters and 10 SMS segments. `{{name}}` placeholders are filled from `variables` when it is sent. Texts only |
| `agent_id` | integer | calls | The saved agent that places the call. Calls only |
| `variables` | object | no | Values for `{{name}}` placeholders |
| `context` | string | no | Calls only: free text added to the agent's prompt for this call, up to 20,000 characters |
| `external_id` | string | no | Your own key, up to 128 characters, such as an appointment id. Use it to find or cancel every send tied to it |
| `expires_at` | timestamp | no | Never sent after this. Defaults to `send_at` plus 30 minutes; at most 24 hours after `send_at` |
| `allow_quiet_hours` | boolean | no | `true` sends outside 8am to 9pm in the recipient's time zone. Default `false` |
| `idempotency_key` | string | no | Up to 128 characters, unique in your organization |

Returns `201 Created` with the send. A send created with problems you should
know about has a `warnings` array of `{"code", "message"}`:

| Warning `code` | Meaning |
|----------------|---------|
| `timezone_unknown` | The recipient's time zone could not be told from their number, the agent or your organization, so quiet hours were not checked. Make sure `send_at` suits them |
| `variables_missing` | The text's body has placeholders with no value in `variables`; they are left out |
| `may_expire` | Enough other texts are due by then that this one may reach its `expires_at` before your organization's text rate lets it out. Spread `send_at` times or give it a later `expires_at` |

### Quiet hours

Texts and calls go out only between 8am and 9pm in the recipient's time zone.
The zone comes from the recipient's number, else the agent's
[`timezone`](/api-reference/agents#deployed-fields), else your organization's.
A `send_at` outside those hours is refused with `quiet_hours` and the next
allowed time:

```json
{
  "error": {
    "code": "quiet_hours",
    "message": "send_at is outside 8am to 9pm in the recipient's time zone (America/Los_Angeles). The next allowed time is next_allowed_at. To send anyway, pass allow_quiet_hours: true; your organization then takes responsibility for the timing.",
    "next_allowed_at": "2026-11-03T16:00:00+00:00",
    "timezone": "America/Los_Angeles"
  }
}
```

Pass `allow_quiet_hours: true` to send at that time anyway; your organization
takes responsibility for the timing. When no zone can be found, the send is
created with a `timezone_unknown` warning instead. Quiet hours are checked
again when the send comes due: a send held up past 9pm is skipped with
`quiet_hours` rather than sent late at night.

### Texts

- **Templates.** The body is stored as written and filled from `variables`
  when the text goes out, so a moved appointment needs only a
  [`PATCH`](#move-or-edit-a-send) of `send_at` or `variables`.
- **Opt-out line.** The first text your organization sends a number gets
  "Reply STOP to opt out." added on a new line. A body that already contains
  the word STOP in capitals is sent as written, and later texts to the same number are not changed.
  The body's length is checked with that line included.
- **Pacing.** Scheduled texts share your organization's text rate (30 a minute
  by default) with `/v1/sms`, agent tools and follow-ups. Sends are checked
  every minute; when more texts are due than the rate allows, the rest wait for
  the next minute, oldest `send_at` first, until their `expires_at`.
- A scheduled text is not counted against a call's three-text limit.

### Calls

A scheduled call is placed like `POST /v1/call` with `agent_id`, `variables`
and `context`, under the same checks: [blocked destinations](/api-reference/outbound-calls#blocked-destinations),
balance and [call limits](/api-reference/introduction#call-limits). A call
held back by your concurrent-call, same-number or daily limit stays queued and
is tried again the next minute until its `expires_at`. If the agent is deleted
before the call is due, the send fails with `agent_deleted`.

### Limits

- `send_at` at most 90 days ahead.
- `expires_at` after `send_at` and at most 24 hours after it.
- At most 10,000 pending (`scheduled` or `sending`) sends per organization.

### Idempotency

Send an `idempotency_key` to make retries safe. Repeating a request with the
same key and the same fields returns the original send with `200 OK` and
creates nothing. The same key with different fields returns `409`
`idempotency_conflict`.

### Errors

Errors have the shape `{"error": {"code", "message"}}`. A field that is
missing or the wrong type returns `400` with that field's error instead, such
as `{"send_at": ["This field is required."]}`.

| Status | `code` | Meaning |
|--------|--------|---------|
| `400` | `invalid_number` | `to` is not a valid phone number |
| `400` | `send_at_in_past` | `send_at` is in the past |
| `400` | `send_at_too_far` | `send_at` is more than 90 days ahead |
| `400` | `invalid_expires_at` | `expires_at` is not after `send_at`, or is more than 24 hours after it |
| `400` | `quiet_hours` | See [quiet hours](#quiet-hours) |
| `400` | `body_required` | A text needs a `body` |
| `400` | `body_too_long` | The body, filled in and with the opt-out line, is too long. A `body` over 1,600 characters as written is refused earlier, with a field error on `body` |
| `400` | `agent_required` | A call needs `agent_id` |
| `400` | `invalid_request` | Fields that don't fit the type, such as `body` on a call, or invalid `variables` or `context` |
| `400`–`503` | SMS sender codes | The text's `from_number` cannot send, such as `messaging_not_registered` or `not_sms_capable`. See [SMS](/api-reference/sms) |
| `403` | `outbound_tcpa_confirmation_required` | Calls: your organization's [TCPA confirmation](/api-reference/outbound-calls#outbound-tcpa-confirmation) is missing |
| `404` | `agent_not_found` | `agent_id` is not an agent of your organization |
| `404` | `from_number_not_owned` | Calls: `from_number` is not an active number of your organization |
| `409` | `contact_opted_out` | `to` is on your [opt-out list](/api-reference/opt-outs) for this channel |
| `409` | `idempotency_conflict` | The key was used with different fields |
| `429` | `too_many_pending` | Your organization already has 10,000 pending sends. Cancel some first |

## List scheduled sends

```bash
curl 'https://api.thunderphone.com/v1/scheduled?external_id=appointment-4815&status=scheduled,sending' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

| Parameter | Description |
|-----------|-------------|
| `external_id` | Exact match |
| `to` | Recipient number |
| `status` | One status, or several separated by commas |
| `type` | `sms` or `call` |
| `source` | `api` |
| `send_after` | ISO 8601; sends with `send_at` at or after it |
| `send_before` | ISO 8601; sends with `send_at` before it |
| `order` | `asc` (default, soonest first) or `desc` by `send_at` |
| `limit` | 1–200, default 50 |
| `offset` | Default 0 |

```json
{
  "count": 1,
  "results": [ { "id": "6f1c0b8e-3a52-4c1f-9a0b-2f4f7d8a91c3", "type": "sms", "status": "scheduled", "...": "..." } ]
}
```

## Retrieve a scheduled send

```bash
curl https://api.thunderphone.com/v1/scheduled/6f1c0b8e-3a52-4c1f-9a0b-2f4f7d8a91c3 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

Returns the send, or `404` `not_found` when the id is not in your
organization.

## Move or edit a send

```bash
curl -X PATCH https://api.thunderphone.com/v1/scheduled/6f1c0b8e-3a52-4c1f-9a0b-2f4f7d8a91c3 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "send_at": "2026-11-04T09:00:00-08:00",
    "variables": {"name": "Ada", "time": "9:00 AM"}
  }'
```

You can change `send_at`, `expires_at`, `body` (texts), `variables`,
`context` (calls) and `allow_quiet_hours` while the send is `scheduled`.
Other fields are ignored: to change `to`, `from_number` or the agent, cancel
the send and create a new one.
Moving `send_at` without `expires_at` keeps the deadline the same time after
it. The same time, quiet-hours and body checks as creation apply, and the
response can carry `warnings`. A send that is no longer `scheduled` returns
`409` `not_editable`.

## Cancel a send

```bash
curl -X DELETE https://api.thunderphone.com/v1/scheduled/6f1c0b8e-3a52-4c1f-9a0b-2f4f7d8a91c3 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

Returns the send with `status: "canceled"`. Canceling a canceled send is a
no-op. A send that is already `sending` or finished returns `409`
`not_cancelable`.

## Cancel by external_id or number

```bash
curl -X POST https://api.thunderphone.com/v1/scheduled/cancel \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "appointment-4815"}'
```

Cancels every `scheduled` send that matches. Send `external_id`, `to`, or
both; add `type` (`sms` or `call`) to cancel only texts or only calls.
Sends already going out are not affected.

```json
{ "canceled": 2 }
```

<!-- en: api-reference/opt-outs -->
---
title: "Opt-outs"
description: "Your organization's do-not-contact list: numbers that asked not to be texted or called."
---

The opt-out list holds numbers that asked your organization not to text them,
not to call them, or both. ThunderPhone checks it before every outbound text
and call:

- **Texts** to a number opted out of `sms` are refused: [`POST /v1/sms`](/api-reference/sms),
  the agent's `send_sms` tool, post-call follow-ups, retries and
  [scheduled texts](/api-reference/scheduled-sends).
- **Calls** to a number opted out of `call` are refused: [`POST /v1/call`](/api-reference/outbound-calls),
  [campaigns](/api-reference/campaigns) and scheduled calls.
- Adding a number skips the queued [scheduled sends](/api-reference/scheduled-sends)
  to it on that channel, with status `skipped` and reason `opted_out`.
- **Asked on a call.** When the person on an outbound call asks not to be
  called again, the agent apologizes, ends the call and adds the number to the
  list for `call`, with source `call_request`. If they hang up before the agent
  ends the call, ThunderPhone checks the transcript after the call, on calls
  that keep a transcript, and adds the number then. This is on for every agent unless you
  [turn it off](#turning-detection-off).

Use these endpoints to keep the list in step with your own CRM's opt-outs.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/opt-outs` | List opt-outs |
| `POST` | `/v1/opt-outs` | Add a number |
| `DELETE` | `/v1/opt-outs` | Remove a number |
| `GET` / `POST` | `/v1/do-not-call-detection-disable-attestation` | Read or record the attestation that lets agents [turn detection off](#turning-detection-off) |

For the opt-out list itself, authenticate with an organization API key. These endpoints are not available
to OAuth clients. In a dashboard session any member can list and add numbers;
removing one requires an admin or owner, because it lets your organization
contact someone who asked it not to. Organization API keys are not limited by
role.

## Opt-out object

```json
{
  "id": 318,
  "number": "+14155550199",
  "channel": "sms",
  "source": "api",
  "source_reference": "api_key:12",
  "blocks": true,
  "created_at": "2026-11-01T18:02:11.204Z",
  "updated_at": "2026-11-01T18:02:11.204Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Id of the row |
| `number` | string | E.164 |
| `channel` | string | `sms` or `call`. A number opted out of both has one row for each |
| `source` | string | Where it came from: `api`, `manual` (added in the dashboard), `carrier`, or `call_request` (the person asked the agent on an outbound call not to be called again). `inbound_stop` (the person replied STOP) is reserved for inbound SMS support and not recorded yet |
| `source_reference` | string | What added it, such as `api_key:<id>`, `user:<id>`, `sms:<message id>` for a carrier refusal, `call:<call id>` for a request on a call, or `call:<call id>:post_call` for one found in the transcript after the call |
| `blocks` | boolean | Whether ThunderPhone refuses texts or calls for this row. `false` for `carrier` rows |
| `created_at`, `updated_at` | timestamp | ISO 8601 UTC |

### Carrier opt-outs

When Twilio or Telnyx refuses a text because the recipient opted out with the
carrier (error code `recipient_opted_out`), ThunderPhone records a `carrier`
row for that number. The carrier enforces these itself, so a `carrier` row is
recorded but not enforced by ThunderPhone (`blocks: false`): it skips the
scheduled texts already queued to that number, but new texts are passed to the
carrier as usual. That way a person who opts back in with the carrier, for
example by texting START, is not kept blocked here. A `carrier` row is removed
when the carrier next accepts a text to that number.

Adding the same number through the API or dashboard turns a `carrier` row into
a blocking one.

## List opt-outs

```bash
curl 'https://api.thunderphone.com/v1/opt-outs?channel=sms' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

| Parameter | Description |
|-----------|-------------|
| `number` | One number, in any format the API can read as a phone number |
| `channel` | `sms` or `call` |
| `source` | `api`, `manual`, `carrier`, `inbound_stop` or `call_request` |
| `limit` | 1–500, default 50 |
| `offset` | Default 0 |

Results are newest first.

```json
{
  "count": 1,
  "results": [
    {
      "id": 318,
      "number": "+14155550199",
      "channel": "sms",
      "source": "api",
      "source_reference": "api_key:12",
      "blocks": true,
      "created_at": "2026-11-01T18:02:11.204Z",
      "updated_at": "2026-11-01T18:02:11.204Z"
    }
  ]
}
```

## Add a number

```bash
curl -X POST https://api.thunderphone.com/v1/opt-outs \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number": "+14155550199", "channel": "both"}'
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `number` | string | yes | The number, E.164 |
| `channel` | string | no | `sms`, `call` or `both` (default) |

Returns the number's row for each channel, `201 Created` when any row is new
and `200 OK` when the number was already on the list:

```json
{
  "results": [
    { "id": 318, "number": "+14155550199", "channel": "sms", "source": "api", "source_reference": "api_key:12", "blocks": true, "created_at": "2026-11-01T18:02:11.204Z", "updated_at": "2026-11-01T18:02:11.204Z" },
    { "id": 319, "number": "+14155550199", "channel": "call", "source": "api", "source_reference": "api_key:12", "blocks": true, "created_at": "2026-11-01T18:02:11.204Z", "updated_at": "2026-11-01T18:02:11.204Z" }
  ]
}
```

A number that is not a valid phone number returns `400` `invalid_number`.

## Remove a number

```bash
curl -X DELETE 'https://api.thunderphone.com/v1/opt-outs?number=%2B14155550199&channel=sms' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

`number` is required; `channel` is `sms`, `call` or `both` (default). Remove a
number only when the person has opted back in.

```json
{ "deleted": 1 }
```

`deleted` is the number of rows removed, `0` when the number was not on the
list.

## Turning detection off

An agent's `do_not_call_detection_enabled` setting controls the
**Asked on a call** behavior above. It is `true` by default. Before any agent
can set it to `false`, an organization admin must record an attestation that
your organization takes responsibility for do-not-call and opt-out compliance
on those agents' calls. In Zeus, turning off an agent's **Stop-calling
requests** setting shows the statement to agree to.

`GET /v1/do-not-call-detection-disable-attestation` ·
`POST /v1/do-not-call-detection-disable-attestation`

`GET` returns the current `text_version`, the English statement
(`statement_en`) and its `statement_sha256`, and whether your organization
has an active attestation (`attested`, `attestation`).

`POST` takes `accepted: true`, the `text_version` and `statement_sha256` from
`GET`, and an optional display `locale` (default `en`; the English statement
governs). It returns `201` with the attestation, or `200` with the existing
one.

<Note>
  An organization admin records the attestation signed in as a user. `POST`
  with an organization API key returns `403`; `GET` works with a key.
</Note>

Without an active attestation, saving, publishing or creating an agent with
`do_not_call_detection_enabled: false` returns `400`, unless the agent already
has it off. If ThunderPhone suspends or revokes the attestation, detection comes
back on for every agent until a new one is recorded, and those agents carry the
`do_not_call_detection_off_without_attestation` warning. Turning detection back on never needs one. Numbers
already on your opt-out list stay blocked either way.

| Status | Condition |
|--------|-----------|
| `201` | Attestation recorded (POST) |
| `200` | Your organization already has an active attestation (POST) |
| `400` | `accepted` was not `true`, `locale` is blank, `text_version` is not current, or `statement_sha256` does not match the statement |
| `403` | API key, or the caller is not an organization admin (POST) |

## What a refusal looks like

| Request | Response |
|---------|----------|
| [`POST /v1/sms`](/api-reference/sms#send-a-message) | `409` with `error.code` `contact_opted_out` |
| [`POST /v1/scheduled`](/api-reference/scheduled-sends#errors) | `409` with `error.code` `contact_opted_out` |
| [`POST /v1/call`](/api-reference/outbound-calls#blocked-destinations) | `400` `destination_not_allowed` with `reason` `contact_opted_out` |
| Campaign contact | The contact fails; the campaign keeps running |
| Scheduled send already queued | `skipped` with `status_reason` `opted_out` |

<!-- en: api-reference/phone-number-labels -->
---
title: "Phone Number Labels"
description: "Attach human-readable labels to external phone numbers so call history, transcripts, and exports show meaningful names instead of raw digits everywhere."
---

Phone number labels let you tag the external numbers that call you or
that you call out to — e.g. "Aetna Insurance" for a specific
`+1-555-...` customer line. Labels are org-scoped (everyone in your org
shares the same label set) and are applied by E.164 number string, not
by phone-number resource id. Labels show up in the call detail view and
in call history exports.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/phone-number-labels` | List labels |
| `POST` | `/v1/phone-number-labels` | Upsert a label for a phone number |
| `DELETE` | `/v1/phone-number-labels/{label_id}` | Delete a label |

## Label object

```json
{
  "id": 7,
  "phone_number": "+15551234567",
  "label": "Aetna Insurance",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Label id used by the delete endpoint |
| `phone_number` | string | E.164-formatted phone number being labeled |
| `label` | string | Display text, 1–100 chars |
| `created_at`, `updated_at` | timestamp | ISO 8601 UTC |

---

## List labels

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/phone-number-labels \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Returns an array of [Label objects](#label-object), sorted by
`phone_number` ascending.

---

## Upsert a label

Idempotent: if a label already exists for this phone number in your org,
it's updated; otherwise a new one is created.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/phone-number-labels \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+15551234567",
    "label": "Aetna Insurance"
  }'
```

```python Python
label = requests.post(
    "https://api.thunderphone.com/v1/phone-number-labels",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={"phone_number": "+15551234567", "label": "Aetna Insurance"},
).json()
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `phone_number` | string | yes | E.164-formatted |
| `label` | string | yes | 1–100 chars |

Returns `200 OK` with the [Label object](#label-object) — both insert
and update cases return the same status because the endpoint is
upsert-style.

---

## Delete a label

<CodeGroup>
```bash cURL
curl -X DELETE https://api.thunderphone.com/v1/phone-number-labels/7 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Returns `204 No Content`.

---

## Related

<CardGroup cols={2}>
  <Card title="Manage numbers in the dashboard" icon="tags" href="/guides/get-a-phone-number#label-phone-numbers">
    Add, edit, and remove labels from Phone Numbers or call history.
  </Card>
  <Card title="Phone Numbers" icon="phone" href="/api-reference/phone-numbers">
    Manage numbers your agents answer on and call from.
  </Card>
  <Card title="Calls" icon="phone" href="/api-reference/calls">
    Call history shows labels beside each external number.
  </Card>
</CardGroup>

<!-- en: api-reference/blocked-callers -->
---
title: "Blocked Callers"
description: "Refuse inbound calls from specific caller numbers: blocked calls end before an agent answers and are not billed."
---

The blocklist is a per-organization list of caller numbers. When a listed
number calls any of your organization's phone numbers, ThunderPhone refuses the
call before an agent starts and hangs up. The attempt is not billed. It appears
in call history as a failed inbound call with `end_reason` `caller_blocked`,
zero duration and zero cost, and it sends the same completion webhooks as any
other failed call.

- Numbers are stored in E.164 form (`+14155550123`) and compared with the
  caller ID in E.164 form, so `+1 (415) 555-0123` and `14155550123` match the
  same entry.
- Calls with a withheld or anonymous caller ID are never matched.
- A caller blocked while a call is in progress is not cut off; the block
  applies to their next call.
- Outbound calls are not affected: you can still call a blocked number.
- [SIP address](/api-reference/sip-addresses) calls are checked too when the
  caller presents a phone number. A caller identified only by a SIP URI
  cannot be blocked.
- An organization can block up to 10,000 numbers.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/blocked-callers` | List blocked callers |
| `POST` | `/v1/blocked-callers` | Block a caller |
| `POST` | `/v1/blocked-callers/bulk` | Block up to 500 callers at once |
| `DELETE` | `/v1/blocked-callers/{blocked_caller_id}` | Unblock a caller |

Any organization member can list blocked callers. Adding and removing them
requires an admin or owner. OAuth clients need `numbers:read` to list and
`numbers:write` to change the list.

## Blocked caller object

```json
{
  "id": 42,
  "number": "+14155550123",
  "note": "Robocaller",
  "created_by_email": "ops@example.com",
  "created_at": "2026-09-30T18:24:10.113Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Id used to unblock |
| `number` | string | Blocked caller number, E.164 |
| `note` | string | Optional note, up to 200 characters |
| `created_by_email` | string \| null | Who added it; null for a removed user |
| `created_at` | timestamp | ISO 8601 UTC |

## Number formats

Send numbers in E.164 (`+14155550123`). Spaces, dashes, dots and parentheses
are ignored. A national format such as `(415) 555-0123` is accepted only when
all of your organization's phone numbers are in one country; it is read as a
number in that country. Otherwise the request fails with
`400` and asks for the `+` and country code.

---

## List blocked callers

<CodeGroup>
```bash cURL
curl 'https://api.thunderphone.com/v1/blocked-callers?limit=50' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

| Query parameter | Description |
|-----------------|-------------|
| `limit` | Page size, 1–200 (default 50) |
| `offset` | Number of entries to skip (default 0) |
| `search` | Case-insensitive match on part of the number or the note |
| `number` | One exact number, in any accepted format. Use it to check whether a caller is blocked |

Returns `{"count": <total matches>, "results": [...]}` with
[Blocked caller objects](#blocked-caller-object), newest first.

---

## Block a caller

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/blocked-callers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number": "+14155550123", "note": "Robocaller"}'
```

```python Python
blocked = requests.post(
    "https://api.thunderphone.com/v1/blocked-callers",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={"number": "+14155550123", "note": "Robocaller"},
).json()
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `number` | string | yes | Caller number; see [Number formats](#number-formats) |
| `note` | string | no | Up to 200 characters |

Returns `201 Created` with the [Blocked caller object](#blocked-caller-object).
Returns `400` when the number is invalid, when it is one of your
organization's own phone numbers, when it is already blocked
(`{"number": ["This number is already blocked."]}`), or when the organization
already blocks 10,000 numbers (`"code": "blocklist_limit_reached"`).

---

## Block several callers

Adds up to 500 numbers in one request and reports a result for each input, in
order. One bad entry does not fail the others.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/blocked-callers/bulk \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"numbers": ["+14155550123", "+14155550124", "not a number"], "note": "Spam wave"}'
```
</CodeGroup>

```json
{
  "added": 1,
  "already_blocked": 1,
  "invalid": 1,
  "limit_reached": 0,
  "results": [
    {"input": "+14155550123", "status": "added", "number": "+14155550123", "id": 43, "error": null},
    {"input": "+14155550124", "status": "already_blocked", "number": "+14155550124", "id": 12, "error": null},
    {"input": "not a number", "status": "invalid", "number": null, "id": null, "error": "Enter a phone number, for example +14155550123."}
  ]
}
```

| `status` | Meaning |
|----------|---------|
| `added` | Now blocked |
| `already_blocked` | Was already on the list, or repeats an earlier entry in the same request |
| `invalid` | Not a usable phone number, or one of your organization's own numbers; `error` says why |
| `limit_reached` | Not added because the organization reached 10,000 blocked numbers |

The optional `note` applies to every number added by the request.

---

## Unblock a caller

<CodeGroup>
```bash cURL
curl -X DELETE https://api.thunderphone.com/v1/blocked-callers/42 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Returns `204 No Content`. Calls from the number are answered again from the
next call on.

---

## Related

<CardGroup cols={2}>
  <Card title="Manage blocked callers in the dashboard" icon="ban" href="/guides/organization-settings#blocked-callers">
    Add, paste and remove blocked numbers, or block a caller from call history.
  </Card>
  <Card title="Calls" icon="phone" href="/api-reference/calls">
    Blocked attempts appear with end reason `caller_blocked`.
  </Card>
</CardGroup>

<!-- en: api-reference/calls -->
---
title: "Calls"
description: "List and inspect every call your agents handle: read transcripts and grades, export recordings and structured data, and report issues on calls that need review."
---

Every inbound call to your phone numbers, every call triggered from
[POST /v1/call](/api-reference/outbound-calls), every browser mic
session, and every widget call produces a **call log** record. These
endpoints let you enumerate and inspect them, fetch recordings and
transcripts, record AI quality grades, file issue reports, and export
history.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/calls` | List calls (paginated, filterable) |
| `GET` | `/v1/calls/export` | Bulk export up to 1,000 calls as CSV or JSON |
| `GET` | `/v1/calls/party-numbers` | Phone numbers seen on your calls, for filter autocomplete |
| `GET` | `/v1/calls/report-summary` | Call-report numbers for a date range and the previous period of the same length |
| `GET` | `/v1/calls/{call_id}` | Retrieve a single call |
| `GET` | `/v1/calls/handoff` | Look up a call the agent handed to your contact center |
| `DELETE` | `/v1/calls/{call_id}` | Permanently delete a call and its content (admin) |
| `POST` | `/v1/calls/bulk-delete` | Permanently delete up to 100 calls (admin) |
| `POST` | `/v1/calls/bulk-delete/preview` | Count what deleting up to 100 calls would also remove (admin) |
| `GET` | `/v1/calls/{call_id}/audio` | Get a time-limited recording URL |
| `GET` | `/v1/consent-announcements/{asset_hash}` | Stream the consent announcement that played on a call |
| `GET` | `/v1/calls/{call_id}/transcript` | Fetch the transcript |
| `GET` | `/v1/calls/{call_id}/history` | Fetch the full structured turn history |
| `GET` | `/v1/calls/{call_id}/tool-calls/{turn}` | Fetch one tool call: what was sent, what came back, the wait |
| `GET` | `/v1/calls/{call_id}/grade` | Fetch the latest AI quality grade |
| `POST` | `/v1/calls/{call_id}/grade` | Run (or re-run) AI grading |
| `POST` | `/v1/calls/{call_id}/extract` | Re-run structured data extraction |
| `GET` | `/v1/calls/{call_id}/issue-reports` | List issue reports for a call |
| `POST` | `/v1/calls/{call_id}/issue-reports` | File an issue report |
| `POST` | `/v1/calls/{call_id}/listen` | Mint a listen-only token for a live call |
| `POST` | `/v1/calls/{call_id}/whisper` | Send private text guidance to the agent on a live call |
| `POST` | `/v1/calls/{call_id}/promote-to-scenario` | Turn a real call into a regression [test scenario](/api-reference/test-scenarios#promote-a-call-to-a-scenario) |
| `POST` | `/v1/calls/{call_id}/create-agent` | Turn a call that ran an inline config into a saved agent |

## Call object

```json
{
  "call_id": 987654321,
  "agent_id": 12,
  "agent_variant_id": null,
  "agent_variant_label": null,
  "direction": "inbound",
  "from_number": "+14155550199",
  "to_number": "+15551234567",
  "start_time": "2026-04-20T18:24:10.113Z",
  "end_time": "2026-04-20T18:25:04.822Z",
  "duration_seconds": 54,
  "status": "completed",
  "end_reason": "user_hangup",
  "answered_by": null,
  "outbound_dial_sip_status": null,
  "outbound_dial_sip_reason": "",
  "outbound_dial_sip_kind": null,
  "recording_url": null,
  "recording_started_at": "2026-04-20T18:24:12.501Z",
  "recording_stopped_at": null,
  "recording_stopped_reason": null,
  "consent_evidence": {},
  "is_simulation": false,
  "is_test_call": false,
  "is_scenario_call": false,
  "prompt_snapshot": "You are a helpful support agent for Acme Ops…",
  "tool_snapshot": [],
  "cloud_run_execution_name": null,
  "livekit_room_name": "call-987654321",
  "livekit_room_sid": "RM_xxxxxxxxxxxx",
  "product": "spark",
  "voice": "john",
  "billable_minutes": 1.25,
  "billing_total_cents": 3,
  "billed_at": "2026-04-20T18:25:05.101Z",
  "transfer_outcome": null,
  "transfer_bridge_kind": null,
  "transfer_destination": "",
  "transfer_sip_status": null,
  "transfer_bridge_seconds": null,
  "transfer_bridge_total_cents": null,
  "voip_connection_id": null,
  "grade_score": 92,
  "grade_status": "completed",
  "grade_updated_at": "2026-04-20T18:25:11.002Z",
  "call_outcome": "success",
  "extracted_data": {
    "status": "completed",
    "fields": {
      "customer_name": "Alex Morgan",
      "appointment_date": "2026-04-23"
    },
    "evidence": {
      "customer_name": {
        "quote": "My name is Alex Morgan",
        "speaker_role": "caller",
        "turn_index": 4
      },
      "appointment_date": {
        "quote": "April 23 works for me",
        "speaker_role": "caller",
        "turn_index": 7
      }
    },
    "verification": "verified",
    "field_reasons": {},
    "schema_version": "92850758e231a3c95a...",
    "schema_snapshot": [
      { "key": "customer_name", "type": "string", "description": "Caller's full name" },
      { "key": "appointment_date", "type": "date", "description": "Requested appointment date" }
    ],
    "extracted_at": "2026-04-20T18:25:09.120Z"
  },
  "issue_count": 0,
  "critical_issue_count": 0,
  "summary": "Alex Morgan called to book a follow-up visit and confirmed Thursday, April 23.",
  "summary_status": "completed",
  "report": {
    "status": "completed",
    "outcome_key": "appointment_set",
    "outcome_label": "Appointment set",
    "outcome_color": "green",
    "outcome_reasoning": "A follow-up visit was booked on the call.",
    "needs_attention": false,
    "attention_reason": "",
    "attention_note": "",
    "attention_turn_index": null,
    "attention_time_seconds": null,
    "caller_name": "Alex",
    "caller_is_new": false,
    "call_reason": "Book a follow-up visit",
    "one_line_summary": "Alex, follow-up visit, booked Thu Apr 23",
    "caller_frustrated": false,
    "frustration_cause": "",
    "caller_experience_note": "Alex was comfortable talking to the assistant.",
    "hangup_stage": "",
    "handled_start_to_finish": true,
    "appointment_set": true,
    "appointment_new_client": false,
    "transfer_result": "not_attempted",
    "booking_result": "succeeded",
    "detail_capture_trouble": false,
    "generated_at": "2026-04-20T18:25:11.002Z"
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `call_id` | integer | Server-assigned call id (also the key in every other endpoint on this page) |
| `agent_id` | integer \| null | Agent that handled the call |
| `agent_variant_id` | integer \| null | [Split-testing](/api-reference/split-testing) variant selected for this call; `null` when no split test ran |
| `agent_variant_label` | string \| null | Label of that variant, snapshotted at call time (survives variant deletion) |
| `direction` | string | `inbound`, `outbound`, `test` (test call in the agent builder), or `web` (web call from the embeddable widget) |
| `from_number` | string | E.164 caller number. Test calls (`direction: "test"`) use an internal identifier |
| `to_number` | string | E.164 destination number |
| `sip_headers` | object \| null | The `X-*` and `User-to-User` SIP headers an inbound call arrived with (SIP addresses and manual SIP connections): header name in lower case → value. `null` when it had none. See [SIP headers](/guides/sip-addresses#pass-call-context-in-sip-headers) |
| `external_call_id` | string | Your platform's own id for the call, from the first of its `X-Amzn-ConnectContactId`, `x-inin-cnv`, `X-Talkdesk-Interaction-Id`, `X-ZOOM-Call-Sid`, `X-CallID`, `X-Call-ID` or `X-Genesys-Conversation-Id` headers; `""` when it sent none |
| `start_time`, `end_time` | timestamp \| null | ISO 8601 UTC. `end_time` is null while `status="in_progress"`. A [queued call's](/api-reference/outbound-calls#queued-calls) `start_time` moves to when it starts dialing |
| `duration_seconds` | integer \| null | Derived |
| `status` | string | `in_progress`, `completed`, or `failed` |
| `queued_at` | timestamp \| null | Set while an outbound call is [waiting for room to dial](/api-reference/outbound-calls#queued-calls), with `status` `in_progress` and nothing dialed yet. `null` otherwise |
| `end_reason` | string \| null | Why the call ended, e.g. `user_hangup`, `ai_hangup`, `voicemail_hangup`, `max_duration`, `ai_transfer`, `price_cap_reached` (the call reached the agent's hard price cap), or `caller_blocked` for an inbound call refused by your [blocklist](/api-reference/blocked-callers) |
| `answered_by` | string \| null | Who answered an outbound call: `human` (a person), `voicemail`, `screener` (a call screening assistant such as iOS Call Screening or Pixel Call Screen), `ivr` (a phone menu) or `unknown` (the call connected but nobody could be told apart, e.g. silence). A person who picked up after a screener or menu, or during the voicemail message, counts as `human`. `null` for other directions, outbound calls nobody answered, and calls from before October 2026 |
| `outbound_dial_sip_status` | integer \| null | For an outbound call that never connected: the SIP status the carrier answered the dial with, e.g. `403` when it refused the call, `486` busy, `480` no answer. `null` when no carrier answered (the call failed before reaching one) and for every other call |
| `outbound_dial_sip_reason` | string | The carrier's own reason text with `outbound_dial_sip_status`, e.g. `Account is disabled D17`; `""` when the carrier gave none or `outbound_dial_sip_status` is `null`. Credential-like text in it is replaced with `[hidden]` |
| `outbound_dial_sip_kind` | string \| null | What `outbound_dial_sip_status` means: `refused` (the carrier refused the call), `busy`, `no_answer` or `declined`. `null` when `outbound_dial_sip_status` is `null` |
| `recording_url` | string \| null | Storage URL when set — not guaranteed playable. Use `/audio` for a signed, playable URL |
| `recording_started_at` | timestamp \| null | When the recorder actually began capturing (1–3 s after `start_time`). Transcript `start_ms`/`end_ms` are anchored to this when present; `null` on older calls |
| `recording_stopped_at` | timestamp \| null | When the recording was stopped before the call ended; nothing after this moment is in the recording. `null` when the recording ran to the end of the call, on calls that were not recorded, and on calls from before this field was added |
| `recording_stopped_reason` | string \| null | Why the recording stopped early. `warm_transfer`: it stops just before a [warm transfer](/guides/call-transfers) calls the destination, which never hears a recording notice, and stays off even if the transfer fails and the caller returns to the agent. Treat other values as informational; more may be added. `null` when `recording_stopped_at` is `null` |
| `is_simulation` | boolean | True if the call was produced by a [simulation](/api-reference/test-calls) run |
| `is_test_call` | boolean | Deprecated alias for `is_simulation`; retained during the transition |
| `is_scenario_call` | boolean | True only for runs launched from a [scenario batch](/api-reference/test-scenarios) — ad-hoc simulations stay `false` |
| `prompt_snapshot` | string \| null | The user-authored agent prompt in effect at call time, with the call's [variables](/guides/call-variables) filled in and its [context](/guides/call-variables#context) block added |
| `tool_snapshot` | array \| null | The tool definitions the agent had at call time |
| `cloud_run_execution_name` | string \| null | **Internal identifier** for the worker that ran the call. Useful only when corresponding with support; may be `null` |
| `livekit_room_name`, `livekit_room_sid` | string \| null | **Internal identifiers** for the underlying media room. Do not build on these; they exist for supervision/support tooling |
| `product`, `voice` | string \| null | The [Agent](/api-reference/agents) config in effect at call time |
| `billable_minutes` | number \| null | Minutes billed, rounded to the nearest quarter minute (15-second increments, minimum 0.25). Straight-to-voicemail calls still report their actual metered minutes here, but the charge is capped at one minute at the plan rate. |
| `billing_total_cents` | integer \| null | Final bill in USD cents. A call billed on metered usage is `null` until its charge settles, a few minutes after it ends, and includes any later increase from usage that arrived after the charge (see [`call.billed`](/webhooks/events#call-billed)) |
| `billed_at` | timestamp \| null | When billing finalised |
| `transfer_outcome` | string \| null | How the call's [transfer](/guides/call-transfers) ended: `refer_accepted`, `bridged`, `bridge_unanswered` or `failed` (see [`call.transfer_completed`](/webhooks/events#call-transfer-completed)). `null` for a call without a transfer, and until the outcome arrives, which is after the call ends |
| `transfer_bridge_kind` | string \| null | For a `bridged` transfer: `cold_fallback` (the carrier refused a cold transfer and ThunderPhone connected the call itself) or `warm` (a warm transfer's two people after the agent left). `null` otherwise |
| `transfer_destination` | string | The number the call was transferred to; `""` for a call without a transfer |
| `transfer_sip_status` | integer \| null | The carrier's SIP status when it refused a cold transfer (`403`, `405` or `501`); `null` when it did not |
| `transfer_bridge_seconds` | integer \| null | Bridged time billed, in seconds; `null` until the bridge ends, and for calls without one |
| `transfer_bridge_total_cents` | integer \| null | What the bridge cost in USD cents after any free call credit. It is billed on its own, not included in `billing_total_cents`; `null` until the bridge ends |
| `voip_connection_id` | integer \| null | The [VoIP connection](/api-reference/voip-connections) the call's number is imported through now (a number re-imported on another connection reports the new one, also on older calls); `null` for a ThunderPhone number, and once the number or its connection is deleted. When that carrier refuses cold transfers, [turn them on](/api-reference/voip-connections#turn-on-call-transfers) for the connection |
| `grade_score` | integer \| null | 0–100 quality score from the latest AI grading |
| `grade_status` | string \| null | `pending`, `completed`, or `failed` |
| `grade_updated_at` | timestamp \| null | Last grading run |
| `call_outcome` | string \| null | From the latest grade: `success`, `failure`, `unknown`, or `no_conversation` |
| `extracted_data` | object \| null | Structured post-call extraction result. Lists include the lightweight `status`, `fields`, and `schema_version`; call detail also includes `evidence` (the exact structurally checked quote, at most 1,000 characters, plus speaker role and turn index per non-null field), `verification`, `field_reasons`, `schema_snapshot`, `error_message`, and `extracted_at`. Longer model-returned evidence quotes are rejected instead of truncated. `verified` means every candidate received exactly one valid independent verdict. `unavailable` covers failed, timed-out, skipped, malformed, or partial verification; valid partial verdicts still apply, while candidates without one valid verdict are nulled. Evidence is `null` whenever its field is `null`; the whole object is `null` when no extraction exists |
| `summary` | string \| null | Plain-language post-call summary (two to four sentences, at most 2,000 characters) when the agent has [`call_summary_enabled`](/api-reference/agents#deployed-fields) and generation succeeded; `null` otherwise. Present in both list and detail responses. Generated in the post-call extraction step, so when the [call-complete webhook](/webhooks/call-complete) was sent without waiting for extraction this is where the summary appears afterwards |
| `summary_status` | string \| null | `completed`; `failed` (the model call failed or ran out of time; if the post-call step is retried, for example because extraction also failed, the summary is generated again); `exhausted` (the post-call step was retried three times without producing one); `skipped` (the call ended within 30 seconds with no caller speech, or no transcript was available); or `skipped_recording_disabled`. `null` when the agent had summaries turned off for this call |
| `issue_count` | integer | Total issue reports filed against this call |
| `critical_issue_count` | integer | Subset with severity `critical` |
| `report` | object \| null | The [call report](#call-report): what happened, who called, whether someone should follow up, and how the caller felt. `null` until the grade that produces it has landed (usually a few minutes after the call) |
| `steps_trace` | array \| null | The order the call moved through its agent's steps and handoffs: each entry has `t_ms` (milliseconds since the call started), `agent` (the agent's key, `a` plus its ID), `step` (the step ID, or `null` on a handoff to an agent without steps) and `via` (`start`, `model`, `condition`, `on_enter` or `handoff`). `null` for calls whose agent has no steps or handoffs, and in list responses (read it from a single call) |
| `collected_values` | object \| null | The values the agent collected in its steps, keyed by collect field name, plus `<tool>_result` for each step's `on_enter_tool` result. `null` for calls whose agent has no steps or handoffs, for calls whose content is not retained (recording turned off), and in list responses |
| `call_start_tools` | array \| null | The [call-start tools](/tools/overview#run-a-tool-at-the-start-of-the-call) that ran before the greeting, each `{name, arguments, result, failed, duration_ms, completed_at_wall_ms, in_greeting}`: the arguments sent, what the tool returned (clipped as the agent saw it), whether it failed, how long it took, when it finished (Unix epoch milliseconds) and whether the result arrived in time for the greeting (`null` when the caller spoke first, so there was no greeting to wait for). `null` for calls without call-start tools, for calls whose content is not retained (recording turned off), and in list responses |
| `context_report` | object \| null | How full the agent's working memory got on this call, and which tool results were cut or set aside: `{budget_tokens, peak_tokens_estimate, near_full, aged_out_results, aged_out_chars, aged_out_tools, size_capped_results, size_capped_tools}`. `aged_out_*` counts earlier tool results the agent set aside once a long call filled up (it can run a lookup again); `size_capped_*` counts results over the 100,000-character limit, of which the agent saw only the start. Present on calls with recording turned off (it holds sizes and tool names, not call content). `null` for calls before October 22, 2026 and in list responses |
| `callback` | object \| null | On an inbound call from someone the number called in the last 30 days: `{returning_call, routed_as_callback, config_webhook_failure}`. `returning_call` is the earlier outbound call (`{call_id, agent_id, started_at, outcome}`), `routed_as_callback` is `true` when the agent that placed it answered because the number had no agent and no webhook answer, and `config_webhook_failure` (`{kind, attempts, http_status, host}`, else `null`) records the config webhook failure that call answered in place of. `null` on every other call. See [Callbacks](/webhooks/call-incoming#callbacks) |
| `config_webhook_failure` | object \| null | On an inbound call whose number's [configuration webhook](/webhooks/call-incoming), or whose agent's [call setup webhook](/webhooks/call-incoming#agent-call-setup-webhook), failed: `{kind, attempts, http_status, host, source}`. `kind` is what went wrong (`http_error`, `timeout`, `connection`, `dns`, `tls`, `response_too_large`, `blocked_url`, `other`, `invalid_json`, `non_object_json` or `invalid_config`), `attempts` how many requests were sent, `http_status` the last response's status (`null` when none came), `host` the webhook's host name, and `source` which webhook it was (`number` or `agent_setup`). Set when the failure ended the call (`end_reason` `inbound_config_webhook_failed`) and when a [callback](/webhooks/call-incoming#callbacks) answered past it; `null` on every other call |
| `call_setup_webhook` | object \| null | On an inbound call answered by an agent with a [call setup webhook](/webhooks/call-incoming#agent-call-setup-webhook): `{outcome, agent_id, failure}`. `outcome` is `assigned_agent` (the webhook filled in the number's agent), `other_agent` (it named another agent, which answered), `inline_config` (it answered a full configuration, which ran instead of the agent) or `webhook_failed` (it gave no usable answer and the agent, which needs no variables, answered without it). `agent_id` is the number's agent, whose webhook ran. `failure` is `{kind, attempts, http_status, host, source}` for `webhook_failed`, else `null`. `null` on every other call |
| `failure` | object \| null | On a call that failed or was cut off: `{owner, cause}`, whose problem it was. `owner` is `thunderphone` (our platform failed), `configuration` (something in your account's settings, such as an empty balance or a blocked caller), `external` (outside ThunderPhone: your webhook, your own carrier trunk, or the person called being busy, not answering or declining) or `unknown` (the call doesn't say). `cause` is `platform_error`, `platform_cut_off` (ours, partway through a call that otherwise ran), `out_of_balance`, `spending_limit`, `balance_ran_out`, `call_limit`, `caller_blocked`, `scheduled_skipped`, `destination_not_allowed`, `number_cannot_dial`, `webhook_failed`, `not_answered`, `busy`, `declined`, `number_unreachable`, `carrier_refused` or `unknown`. `null` when nothing went wrong |
| `consent_evidence` | object | Consent-announcement evidence record — see [Consent evidence](#consent-evidence). `{}` when no announcement played |
| `held_out` | boolean | Only for organizations with the agent iteration toolkit: `true` when the call's caller is in one of the organization's agents' [test splits](/api-reference/conversations#dev-and-test-splits). Also on the transcript response. An API key, OAuth token or legacy token gets a held-out call as exactly `{"call_id": 1234, "start_time": "2026-10-19T15:02:11Z", "held_out": true}`, here, in the transcript response, in exports (whose rows name it `started_at`) and over [MCP](/guides/thunderphone-mcp-server); every other field is absent, even ones listed as always present, and writes on it are refused (`403 held_out_call`); the dashboard sees it in full, as does an API key an admin gave `include_held_out_calls` (off by default). Leave held-out calls out when tuning a prompt; the test split measures a change |

### Consent evidence

Calls on agents with the consent announcement enabled carry a read-only
`consent_evidence` object recording exactly what played and what the caller
did afterwards:

| Field | Type | Description |
|-------|------|-------------|
| `asset_version`, `asset_hash` | string | Identity of the exact audio asset that played; `asset_hash` keys the [consent announcement audio](#get-consent-announcement-audio) endpoint |
| `language`, `announcement_text` | string | Announcement language and verbatim text |
| `playback_started_at`, `playback_completed_at`, `capture_started_at` | timestamp | Ordered: playback completes before caller-audio capture is enabled |
| `continuation_event` | object \| absent | First caller activity **after** the announcement completed: `{event_type: "speech" \| "dtmf", at, participant_identity, dtmf_digit?}`. Only actual confirmed speech or a keypad press counts — a merely connected line never produces this event |
| `objection_events` | array \| absent | Detectable objection/withdrawal signals, each `{event_type, at, participant_identity, dtmf_digit?, seconds_after_playback_completed?}` with `event_type` one of `dtmf_during_announcement`, `hangup_during_announcement`, `hangup_after_announcement_without_activity` (the latter only for hangups shortly after the notice with no caller activity; a later silent hangup is not recorded as an objection) |

`continuation_event` and `objection_events` document caller behavior around
the notice; they are not proof the caller heard the announcement and are not
a substitute for affirmative (press-1) consent where a jurisdiction requires
it.

---

## List calls

<CodeGroup>
```bash cURL
curl 'https://api.thunderphone.com/v1/calls?limit=50' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

```python Python
page = requests.get(
    "https://api.thunderphone.com/v1/calls",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    params={"limit": 50, "direction": "inbound"},
).json()
for call in page["results"]:
    ...
```

```javascript Node.js
const url = new URL("https://api.thunderphone.com/v1/calls");
url.searchParams.set("limit", "50");
const page = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.THUNDERPHONE_API_KEY}` },
}).then((r) => r.json());
```
</CodeGroup>

### Query parameters

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `limit` | integer | 50 | Page size (1–200) |
| `offset` | integer | 0 | |
| `agent_id` | integer | | Filter by agent |
| `prompt_revision_id` | integer | | Only calls that ran this prompt revision (an `id` from [List prompt revisions](/api-reference/prompt-revisions)) |
| `agent_config_version_id` | integer | | Only calls that ran this agent version (an `id` from the agent's [version history](/api-reference/agents#version-history)) |
| `hours` | string | | `business` or `after_hours`, judged in the organization's [reporting time zone and business hours](/guides/organization-settings#reporting), or the agent's own when it has them. Without a schedule every call is business hours |
| `needs_attention` | boolean | | `1` keeps only calls whose report flags a follow-up |
| `outcome_key` | string | | Comma-separated report outcome keys (for example `appointment_set,callback_requested`) |
| `exclude_test_numbers` | boolean | | `1` drops calls from or to the organization's excluded test numbers |
| `attention_first` | boolean | | `1` sorts flagged calls to the top (newest first within each group) instead of pure recency |
| `direction` | string | | `inbound`, `outbound`, `test` (test call in the agent builder), `web` (web call from the embeddable widget). Legacy `mic` and `widget` values remain accepted as filters during migration. Historical webhook data may still contain those old values. |
| `status` | string | | `in_progress`, `completed`, `failed` |
| `phone_number` | string | | Matches either side of the call (`from_number` or `to_number`); formatted numbers are normalized before matching |
| `from_number` | string | | E.164 |
| `to_number` | string | | E.164 |
| `start_date` | ISO 8601 | | Earliest `start_time` |
| `end_date` | ISO 8601 | | Latest `start_time` |
| `exclude_test_calls` | boolean | `false` | `true` leaves out test traffic: agent-builder test calls (and their SIP legs), [simulation](/api-reference/test-calls) runs, and builder Talk sessions (`direction=test`). Web widget calls are kept. Values other than `true` or `false` (case-insensitive) return `400`. |
| `include_snapshots` | boolean | `true` | `false` leaves `prompt_snapshot` and `tool_snapshot` out of each call, which makes large pages much smaller. Values other than `true` or `false` (case-insensitive) return `400`. |

### Paginated response

```json
{
  "results": [ /* Call objects */ ],
  "total": 1234,
  "limit": 50,
  "offset": 0
}
```

Use `offset` + `limit` to page forward; check `total` to know when
you've reached the end.

---

## Call report

A call's `report` is the customer-facing read of what happened. It is
`null` until grading writes one. For a conversation, the full grade writes
the report in the same model pass. When recording is enabled, calls that
end before a conversation and calls with no transcript get a basic report
without a model pass. An early heuristic grade can leave `report` as
`null`. While batch grading is queued, `report.status` may be `pending`;
its fields are placeholder defaults, not findings, so read them only when
`status` is `completed`. Calls made with recording disabled get a report
with `status` `skipped` and no findings. If full grading fails, a report
may stay `null` or `pending`; that does not mean the call needs no
follow-up.

The outcome comes from the agent's
[`outcome_labels`](/api-reference/agents#deployed-fields) (Success /
Failure unless the agent defines its own list). The agent's
`report_instructions` ask the grader how to write `one_line_summary`,
`call_reason`, `caller_experience_note` and `attention_note`. For example,
you can ask it to omit health details. These are AI writing instructions,
not guaranteed redaction. They do not change the transcript, recording or
the separate Call object's `summary`.

| Field | Type | Description |
|-------|------|-------------|
| `status` | string | `completed` once written; `pending` while batch grading is queued (fields are placeholders); `skipped` when recording was disabled for the call (no findings) |
| `outcome_key` | string | The configured key picked for the call. `""` on Success / Failure when there was no conversation to judge. On an agent with its own labels, a call with no conversation starts with `""` and takes one of them within minutes, with no further webhook |
| `outcome_label` | string | The picked label. On Success / Failure, a call with no conversation shows `No conversation`; `""` when no label is available |
| `outcome_color` | string | The picked label's colour: `green` / `red` for the platform Success / Failure, the business's choice for its own labels (`gray` when unset), `""` when no outcome applies |
| `outcome_reasoning` | string | One sentence on why that label fits |
| `needs_attention` | boolean | Someone at the business should follow up or review the call |
| `attention_reason` | string | `urgent`, `caller_frustrated`, `asked_for_person`, `agent_did_not_know`, `detail_capture_trouble`, `booking_failed`, `transfer_failed`, or `""` |
| `attention_note` | string | One sentence on what the follow-up is about |
| `attention_turn_index`, `attention_time_seconds` | integer \| null | The transcript turn and recording second where the reason became apparent |
| `caller_name` | string | As the caller gave it; `""` when never stated |
| `caller_is_new` | boolean \| null | New (`true`), existing (`false`), or unknown |
| `call_reason` | string | Why the caller called. The grader aims for at most eight words; the value is capped at 200 characters |
| `one_line_summary` | string | A receptionist-style summary, e.g. "Jack, turning 65, booked Tue 2pm". The grader aims for under 120 characters; the value is capped at 240 |
| `caller_frustrated` | boolean | Whether the caller showed frustration |
| `frustration_cause` | string | When `caller_frustrated` is `true`, one of `long_waits`, `repeated_questions`, `misheard_details`, `could_not_help`, `wanted_a_person`, `did_not_want_ai`, or `other`; otherwise `""` |
| `caller_experience_note` | string | How the caller seemed to feel about the call, including whether they were fine talking to an AI |
| `hangup_stage` | string | An early caller hang-up: `at_greeting`, `mid_conversation`, or `after_ask` (after the agent asked for information or made a request). `""` when no early hang-up was identified, including a normal goodbye |
| `handled_start_to_finish` | boolean \| null | Fully handled on the call with nothing left for the business to do |
| `appointment_set`, `appointment_new_client` | boolean, boolean \| null | An appointment, booking or reservation was confirmed; whether it was for a new client |
| `transfer_result`, `booking_result` | string | On a completed report: `not_attempted`, `succeeded`, or `failed`. Pending and skipped reports use `""` |
| `detail_capture_trouble` | boolean | The agent struggled to get an email, name, number or other detail right |
| `generated_at` | timestamp | |

The same object rides on the [`call.graded`](/webhooks/events#call-graded) event.

---

## Report summary

`GET /v1/calls/report-summary`

Returns the five call-report numbers shown on dashboard Home and in each
agent's **Calls** tab. It compares the selected date range with the
previous period of the same length. Counts always leave out the
organization's excluded test numbers.

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `start_date`, `end_date` | `YYYY-MM-DD` or ISO 8601 | last 30 days | Bare dates select whole local days in the reporting time zone, both ends included. ISO timestamps are exact: the start is included, the end is not. At most 366 days |
| `agent_id` | integer | | Filter by agent |
| `direction` | string | | `inbound`, `outbound`, `test`, or `web`. Historical `mic` and `widget` rows can be queried by those literal legacy values |
| `hours` | string | | `business` or `after_hours` |

```json
{
  "period": { "start": "2026-08-25T07:00:00Z", "end": "2026-09-24T07:00:00Z" },
  "previous_period": { "start": "2026-07-26T07:00:00Z", "end": "2026-08-25T07:00:00Z" },
  "timezone": "America/Los_Angeles",
  "has_business_hours": true,
  "excluded_numbers": 2,
  "metrics": {
    "calls_handled": { "value": 212, "previous": 187, "after_hours": 61, "after_hours_previous": 48, "good_direction": "up" },
    "handled_start_to_finish": { "value": 150, "previous": 121, "good_direction": "up" },
    "went_badly": { "value": 19, "previous": 26, "breakdown": { "hung_up": 9, "detail_capture_trouble": 5, "booking_failed": 3, "transfer_failed": 2 }, "good_direction": "down" },
    "caller_experience": { "value": 171, "previous": 140, "conversations": 180, "frustrated": 9, "frustrated_previous": 14, "top_cause": "wanted_a_person", "top_cause_count": 4, "causes": [ { "cause": "wanted_a_person", "count": 4 } ], "good_direction": "up" },
    "appointments_set": { "value": 64, "previous": 51, "new_clients": 22, "new_clients_previous": 15, "good_direction": "up" }
  },
  "needs_attention": { "value": 14, "previous": 20, "reasons": [ { "reason": "caller_frustrated", "count": 6 } ] },
  "success_rate": { "graded": 198, "succeeded": 171, "graded_previous": 170, "succeeded_previous": 139 },
  "outcomes": [ { "key": "appointment_set", "label": "Appointment set", "count": 64 } ],
  "agents": [
    { "agent_id": 12, "agent_name": "Front desk", "calls": 140, "after_hours": 40, "handled": 101, "went_badly": 11, "frustrated": 5, "no_frustration": 118, "conversations": 123, "appointments": 48, "appointments_new": 17, "needs_attention": 9, "graded": 132, "succeeded": 116, "reported": 136 }
  ],
  "reported": 205,
  "pending_reports": 7
}
```

`good_direction` says which way is good for each metric; colour arrows by
it, not by their sign (fewer calls that went badly is green).

Every report metric counts answered calls only: non-rejected inbound and
web calls, plus outbound calls once the other side answered. Browser tests
and simulations are left out, matching the Home call-volume chart.
`calls_handled` is that count.
`caller_experience.value` counts judged conversations with no frustration;
`frustrated` and `frustrated_previous` count frustrated callers (the
dashboard shows those). `went_badly.value` counts calls with a hang-up
mid-conversation or after the ask, trouble getting a detail right, a failed
booking or a failed transfer; one call can fall in several `breakdown`
buckets. `reported` counts calls with a completed report and
`pending_reports` the answered calls still waiting for one (a `skipped`
report is not pending). `excluded_numbers` is the number of configured
test numbers. It is not a count of excluded calls, and it includes
configured numbers with no calls in this date range. `agents` is
the same breakdown per agent for the current period, busiest first; an
agent with its own [`business_hours`](/api-reference/agents#deployed-fields)
is judged by them for after-hours.

---

## Export calls

Bulk-download up to 1,000 of the most recent calls as either CSV
(metadata only) or JSON (includes transcripts). The export honors the
same filter parameters as [List calls](#list-calls), so what you export
matches what you filtered. Both formats carry the report columns
(`outcome`, `needs_attention`, `attention_reason`, `caller_name`,
`caller_is_new`, `call_reason`, `summary`, `caller_frustrated`,
`hangup_stage`, `appointment_set`, ...), blank until the call has a
completed report.

<CodeGroup>
```bash CSV
curl 'https://api.thunderphone.com/v1/calls/export?export_format=csv' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -o calls.csv
```

```bash JSON (filtered)
curl 'https://api.thunderphone.com/v1/calls/export?export_format=json&status=completed&start_date=2026-07-01T00:00:00Z' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -o calls.json
```
</CodeGroup>

### Query parameters

| Param | Required | Description |
|-------|----------|-------------|
| `export_format` | yes | `csv` or `json` |
| `agent_id` | | Filter by agent |
| `prompt_revision_id` | | Same as List calls: only calls that ran this prompt revision |
| `agent_config_version_id` | | Same as List calls: only calls that ran this agent version |
| `direction` | | Same values as List calls (`inbound`, `outbound`, `test`, `web`; legacy `mic`/`widget` accepted) |
| `status` | | `in_progress`, `completed`, `failed` |
| `phone_number` | | Matches either side of the call (`from_number` or `to_number`); formatted numbers are normalized before matching |
| `from_number` | | E.164 |
| `to_number` | | E.164 |
| `start_date` | | ISO 8601 — earliest `start_time` |
| `end_date` | | ISO 8601 — latest `start_time` |
| `exclude_test_calls` | | `true` or `false` (default). Same behavior as List calls: `true` leaves out test calls and simulations and keeps widget calls |

`limit`/`offset` are not accepted — the export always returns the most
recent matches up to its fixed cap.

### Response

The response includes a `Content-Disposition: attachment` header with a
dated filename (`calls-export-YYYY-MM-DD.csv`).

Exports cap at the 1,000 most recent calls **matching the filters**.
When more calls match than the cap allows, the response carries
truncation signals so you can detect an incomplete export:

| Signal | Where | Meaning |
|--------|-------|---------|
| `X-Truncated` | header (CSV and JSON) | `true` when the filtered match count exceeds the row cap, else `false` |
| `X-Total-Count` | header (CSV and JSON) | Untruncated count of calls matching the filters |
| `truncated` | JSON body field | Same signal as `X-Truncated`, for JSON consumers |

For a truncated window, narrow the date range (`start_date`/`end_date`)
and export in slices, or use the list endpoint with offset pagination.

---

## List party numbers

Distinct phone numbers that have appeared on either side of your
organization's calls, most recently seen first. Use it to autocomplete
the `from_number` / `to_number` filters of [List calls](#list-calls) —
it includes external callers, not only numbers you own. Placeholder
parties for browser, widget and test sessions are omitted.

```bash
curl 'https://api.thunderphone.com/v1/calls/party-numbers?q=631456' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

### Query parameters

| Param | Required | Description |
|-------|----------|-------------|
| `q` | | Digit search. Punctuation is ignored on both sides, so `(631) 456` matches `+16314566068` |
| `limit` | | Maximum numbers to return (default 50, max 200) |

### Response

```json
{
  "numbers": ["+16314566068", "+15137061124"]
}
```

---

## Retrieve a call

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/calls/987654321 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Returns `200 OK` with a [Call object](#call-object), or `404` if the
call does not belong to your organization.

---

## Look up a handed-off call

When the agent transfers or returns a call to your contact center, your
platform can fetch what it needs with its own id for the call or the id
ThunderPhone sent with the transfer. See
[Pass context to your contact center](/guides/call-transfers#pass-context-to-your-contact-center).

<CodeGroup>
```bash cURL
curl "https://api.thunderphone.com/v1/calls/handoff?external_call_id=6a1b2c3d-genesys-conv" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

### Query parameters

Send exactly one.

| Parameter | Description |
|-----------|-------------|
| `external_call_id` | Your platform's own id for the call, as it sent it in a SIP header (the call's `external_call_id`). |
| `handoff_id` | The id ThunderPhone sent with the transfer: `{{handoff_id}}` in a transfer header, or `X-TP-Handoff-Id` on a return's `BYE`. |

### Response

The most recent matching call in your organization.

```json Response
{
  "call_id": 987654321,
  "status": "in_progress",
  "external_call_id": "6a1b2c3d-genesys-conv",
  "handoff": {
    "handoff_id": "Zr3mY0b1Q9xWw2kPq4s7Tg",
    "summary": "Wants a refund for order 7731; address already confirmed.",
    "intent": "billing_dispute",
    "at": "2026-10-30T17:04:11.512Z"
  },
  "sip_headers": { "x-inin-cnv": "6a1b2c3d-genesys-conv" },
  "variables": { "account_id": "A-17" },
  "summary": null,
  "extracted_data": null
}
```

| Field | Description |
|-------|-------------|
| `handoff` | What the agent passed at the transfer: `handoff_id`, `summary` and `intent` (empty when the agent gave none), and `at` (UTC). The latest when the call was handed off more than once; `null` when it never was. A call that keeps no transcript has no `summary` or `intent`. |
| `sip_headers`, `variables` | What the call started with, as in the [Call object](#call-object). |
| `summary`, `extracted_data` | `null` while the call is in progress. Once it has ended, the call's summary and extracted data (`status`, `fields`, `schema_version`) as the call list shows them; they can take a few seconds after the call to appear. |

| Status | Condition |
|--------|-----------|
| `200` | Call found |
| `400` | Neither or both parameters sent |
| `404` | No call in your organization matches |

---

## Delete a call

Permanently deletes one call and its content. Only owners and admins can
delete calls. An API key acts with the role of the user who created it, so
a key created by a member gets `403`.

<CodeGroup>
```bash cURL
curl -X DELETE https://api.thunderphone.com/v1/calls/987654321 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Deleting a call removes:

- the recording and every other stored audio file for the call
- the transcript and the full turn history
- the summary, call report, extracted data and AI grades
- issue reports filed on the call
- stored copies of webhook events about the call
- [validation examples](/api-reference/validation-sets) made from the call,
  with their copied turns and caller audio

Your billing history keeps the charge for the call (amount, billed minutes
and call ID) without any call content, so balances and invoices do not
change. Test scenarios created from the call and text messages sent during
it are separate records and are not deleted. To see how many validation
examples a deletion would remove before you delete, use
[Preview a deletion](#preview-a-deletion).

The call disappears from the API and the dashboard as soon as the request
returns. Stored files are deleted in the background, normally within a
minute, and a recently ended call's storage is checked again an hour later
for a recording that finished uploading after the delete. Backups age out on a roughly 35-day cycle, and a deleted call is
deleted again if a backup is ever restored. Deletion cannot be undone and
sends no webhook event.

| Status | Condition |
|--------|-----------|
| `204` | Call deleted |
| `403` | The authenticated user is not an owner or admin |
| `404` | No such call in your organization, including a call that was already deleted |
| `409` | `code: "call_in_progress"`: the call is live, or its billing is still being settled right after it ended. Retry in a few minutes. `code: "call_legal_hold"`: the call is under a legal hold |

---

## Delete calls in bulk

`POST /v1/calls/bulk-delete` deletes up to 100 calls in one request, with
the same rules and effects as [deleting one call](#delete-a-call). The
response has one result per distinct call ID.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/calls/bulk-delete \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"call_ids": [987654321, 987654322, 987654323]}'
```
</CodeGroup>

```json Response
{
  "results": [
    {"call_id": 987654321, "status": "deleted", "detail": ""},
    {"call_id": 987654322, "status": "not_found", "detail": ""},
    {"call_id": 987654323, "status": "in_progress", "detail": "This call is still in progress. Wait for it to end, then delete it."}
  ],
  "deleted": 1
}
```

| `status` | Meaning |
|----------|---------|
| `deleted` | Deleted by this request |
| `not_found` | No such call in your organization, or it was already deleted |
| `in_progress` | Live, or its billing is still being settled; nothing was deleted. Retry later |
| `legal_hold` | Under a legal hold; nothing was deleted |

The request returns `400` for an empty list, more than 100 IDs, or IDs that
are not positive integers, and `403` when the authenticated user is not an
owner or admin.

---

## Preview a deletion

`POST /v1/calls/bulk-delete/preview` takes the same body as
[bulk delete](#delete-calls-in-bulk) and deletes nothing. It returns how
many validation examples were made from those calls, which deleting them
would also remove. IDs that are not calls in your organization count
nothing. Owners and admins only, like deletion.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/calls/bulk-delete/preview \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"call_ids": [987654321, 987654322]}'
```
</CodeGroup>

```json Response
{
  "validation_examples": 2
}
```

The request returns `400` and `403` in the same cases as bulk delete.

---

## Get recording audio

Returns a short-lived signed URL to the MP3 recording on Google Cloud
Storage. Stream the URL directly to your audio player — do not store
it (it expires).

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/calls/987654321/audio \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

```json Response
{ "url": "https://storage.googleapis.com/thunderphone-recordings/..." }
```

| Status | Condition |
|--------|-----------|
| `200` | Recording exists, URL returned |
| `404` | Call or recording not found |

---

## Get caller audio

`GET /v1/calls/{call_id}/caller-audio?ref={ref}`

Streams what the caller actually said for one turn of the conversation.
`ref` comes from a transcript entry's `caller_audio_refs`, present on caller
turns whose audio was captured.

| Status | Condition |
|--------|-----------|
| `200` | Audio stream returned |
| `404` | Call, turn, or audio not found |

---

## Get consent announcement audio

`GET /v1/consent-announcements/{asset_hash}`

Streams the exact consent-announcement asset that played at the start of a
call, as a 48 kHz mono WAV. Calls that played an announcement carry a
`consent_evidence` object (asset hash, announcement text, playback and
capture timestamps); pass its `asset_hash` here to retrieve the audio whose
content hash matches it byte-for-byte. This endpoint is the programmatic
evidence-access path; the stored call recording itself also begins with
this announcement — it is muxed in at recording finalization, and
`consent_evidence` then carries `recording_announcement_offset_seconds` /
`recording_announcement_duration_seconds` marking where the prepended
segment sits inside the recording. When additional participants joined
mid-call (for example a warm-transfer target), the same object also carries
a `legs` array — one entry per joining leg with the leg's identity, join
time, its own playback/capture timestamps for the same content-addressed
asset, and post-notice continuation details.

Authorization is by evidence linkage: the hash must appear in the
`consent_evidence` of a call your organization can access. Responses are
never cacheable (`Cache-Control: no-store`), and the endpoint is
rate-limited per user.

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/consent-announcements/f1d6b49f4ac8f391cfc933591f53415bc71083a62d723acb4de5606cea3d4d73 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  --output consent-announcement.wav
```
</CodeGroup>

| Status | Condition |
|--------|-----------|
| `200` | WAV audio stream returned |
| `404` | Hash malformed, not linked to any of your org's calls, or the asset is no longer cached |
| `429` | Rate limit exceeded — retry later |

---

## Get transcript

Simplified, user-facing transcript (role-tagged speech only; no system
events). For the full structured history including function calls,
interruptions, and latency metrics use [`/history`](#get-history).

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/calls/987654321/transcript \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

```json Response
{
  "call_id": 987654321,
  "transcripts": [
    {
      "role": "user",
      "content": "Hi, I have a question about my policy.",
      "start_ms": 1200,
      "end_ms": 3400,
      "caller_audio_refs": ["…", "…"]
    },
    {
      "role": "agent",
      "content": "Of course — could I have your member id?",
      "start_ms": 3800,
      "end_ms": 6100,
      "ttfa_ms": 412
    }
  ]
}
```

| Field | Type | Description |
|-------|------|-------------|
| `role` | string | `user`, `agent`, `tool_call`, `tool_response`, or `system` |
| `content` | string | Human-readable content. For `tool_call`/`tool_response` turns this is a JSON string |
| `start_ms`, `end_ms` | integer | Offset in milliseconds, anchored to the recording when `recording_started_at` is set. Omitted when timing could not be reconstructed |
| `ttfa_ms` | integer | Time-to-first-audio for the first agent turn of a response. Present on agent turns only |
| `caller_audio_refs` | array of string | Opaque references to the audio of what the caller said, in the order they were spoken. Pass each to [`/caller-audio`](#get-caller-audio) to fetch it. Present on `user` turns only, and omitted entirely — never `null` — when no audio was captured |

Caller audio is always the call audio as received, never a noise-suppressed
version, so re-listening to two different turns is always comparing like with
like. A long caller turn can span several recordings; fetch them in the order
given and concatenate.

| Query param | Description |
|-------------|-------------|
| `live=true` | Use a lenient serializer that includes not-yet-resolved turns — for real-time display while the call is still in progress. Caller turns carry `caller_audio_refs` here too, so audio can be fetched while the call is still running |

<Note>
The audio is uploaded before the turn appears in the transcript, but the two
are not transactional. A reference can briefly 404 immediately after it first
appears; retry for a few seconds. Measured worst case on a live call was under
a second. A reference that never becomes available is dropped from later reads
rather than left pointing at a recording that does not exist.
</Note>

---

## Get history

Full structured turn history. Use this when you need raw function-call
arguments, interruption markers, ack-prompt annotations, or first-byte
latencies.

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/calls/987654321/history \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Returns an array of typed entries. See the ThunderPhone [call-history
schema reference](/api-reference/calls#get-history)
for the full shape — the top-level entries include `span`, `completion`,
`patch`, `function_call`, `function_response`, `interrupt`, and
`acknowledgement`.

---

## Get a tool call

One tool call the agent made on a call: what it sent, what came back, how long
the tool took, and what the agent said around it. `turn` is the tool call's
row in [`/transcript`](#get-transcript) (a `tool_call` row, counted from 0).

Credentials are hidden from what was sent and what came back: values under
secret-named keys (`api_key`, `password`, `Authorization`, …) and
credential-shaped text (bearer tokens, API keys, card numbers) read
`[hidden]`. Long values are cut short.

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/calls/987654321/tool-calls/3 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

```json Response
{
  "call_id": 987654321,
  "turn": 3,
  "tool": "check_calendar",
  "arguments": { "day": "2026-10-24", "time": "14:00", "api_key": "[hidden]" },
  "response": { "free": false, "next_free": ["14:30", "15:00"] },
  "outcome": "ok",
  "duration_ms": 2400,
  "at": 41.8,
  "lines": [
    { "text": "One moment while I check the calendar.", "at": 0.0 }
  ],
  "next_line": { "text": "That time was just taken. I have two thirty or three.", "at": 2.9 }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `tool` | string | The tool's name, as the agent's configuration names it |
| `arguments` | object | What the agent sent, credentials hidden |
| `response` | any \| null | What came back, credentials hidden; `null` when nothing did |
| `outcome` | string | `ok`, `error` (the tool reported an error or a 4xx/5xx status), `timeout` (it did not answer in time), or `no_answer` (no answer before the call ended) |
| `duration_ms` | integer \| null | How long the tool took, when the call recorded it |
| `at` | number \| null | Seconds into the recording the tool call started |
| `lines` | array | What the agent said while the caller waited: the line said as the call started and any holding lines. `at` is seconds after the tool call started, or `null` when untimed |
| `next_line` | object \| null | The agent's next line after the answer, with its `at` |

| Status | Meaning |
|--------|---------|
| `200` | The tool call |
| `404` | No such call in your organization, the call keeps no transcript, or `turn` is not a tool call |

---

## AI call grading

### Get latest grade

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/calls/987654321/grade \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

```json Response
{
  "id": 88,
  "call_id": 987654321,
  "status": "completed",
  "score": 92,
  "call_outcome": "success",
  "outcome_reasoning": "The caller's policy question was answered fully and confirmed.",
  "summary": "Caller asked about their policy and got a full answer…",
  "rubric_breakdown": { "accuracy": 95, "tone": 90 },
  "detected_issues": [],
  "grader_model": "heuristic-v1",
  "grader_version": "v1",
  "error_message": null,
  "graded_at": "2026-04-20T18:25:11.002Z",
  "created_at": "2026-04-20T18:25:11.002Z",
  "updated_at": "2026-04-20T18:25:11.002Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Grade row id |
| `call_id` | integer | |
| `status` | string | `pending`, `completed`, or `failed` |
| `score` | integer \| null | 0–100 |
| `call_outcome` | string | `success`, `failure`, `unknown`, or `no_conversation` |
| `outcome_reasoning` | string | Why the grader chose that outcome |
| `summary` | string | One-paragraph call summary |
| `rubric_breakdown` | object | Per-criterion scores |
| `detected_issues` | array | Machine-detected issues; completed grades sync these into [issue reports](#issue-reports) with `source: "system"` |
| `grader_model`, `grader_version` | string | Which grader produced the row |
| `error_message` | string \| null | Set when `status="failed"` |
| `graded_at` | timestamp \| null | When grading completed |
| `created_at`, `updated_at` | timestamp | |

Returns `200 OK` with the latest grade row, or `404` if the call has
not been graded.

### Run grading

Grade the call. Grading runs synchronously within the request. If a
completed grade already exists it is returned as-is unless you pass
`force=true`.

Any request that would invoke the grader — a forced regrade, or a request
whose latest grade is missing, pending, or failed — must first claim a
per-call cooldown. The standard cooldown is 15 minutes. If the latest grade
is a retryable failure, the cooldown is 90 seconds so a retry can recover
sooner. At most one new grading run can be claimed per window.

<CodeGroup>
```bash cURL
curl -X POST 'https://api.thunderphone.com/v1/calls/987654321/grade?force=true' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

A request inside the active cooldown returns `429 Too Many Requests`. The
`Retry-After` response header and `retryAfterSeconds` body field contain the
same number of seconds to wait:

```json
{
  "detail": "This call was recently submitted for grading. Please retry later.",
  "retryAfterSeconds": 90
}
```

| Status | Condition |
|--------|-----------|
| `200` | An existing completed grade was reused (no `force`) |
| `201` | A new grade completed |
| `429` | The per-call cooldown is active; use `Retry-After` or `retryAfterSeconds` before retrying |
| `502` | Grading failed — the returned grade row has `status="failed"` and an `error_message`; retry later |

A regrade judges the call against the [outcome labels](/api-reference/agents#deployed-fields) the call
started with, not the agent's current ones. To move past calls onto an agent's new labels, use
[relabel past calls](/api-reference/agents#relabel-past-calls), which changes only the outcome label and its
reason and runs no full regrade.

---

## Run data extraction

Re-run structured data extraction for a completed call using the agent's
current deployed extraction schema. This admin-only endpoint overwrites the
call's prior extraction row and emits `call.data_extracted` when extraction
completes.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/calls/987654321/extract \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

```json Response
{
  "id": 412,
  "call_id": 987654321,
  "agent_id": 12,
  "schema_snapshot": [
    {
      "key": "customer_name",
      "type": "string",
      "description": "The caller's full name",
      "required": true,
      "ask": true
    }
  ],
  "schema_version": "92850758e231a3c95a...",
  "data": {"customer_name": "Alex Morgan"},
  "evidence": {
    "customer_name": {
      "quote": "My name is Alex Morgan",
      "speaker_role": "caller",
      "turn_index": 4
    }
  },
  "verification": "verified",
  "field_reasons": {},
  "status": "completed",
  "error_message": "",
  "model": "<model id>",
  "extracted_at": "2026-04-20T18:25:11.002Z",
  "created_at": "2026-04-20T18:25:11.002Z",
  "updated_at": "2026-04-20T18:25:11.002Z"
}
```

The response is still `200 OK` when the extraction row has `status="failed"`
or `status="skipped"`; inspect `error_message` for the reason. Calls whose
immutable recording policy disabled retained content return `409 Conflict`
with `status="skipped_recording_disabled"` and are never sent to the model.
A call outside the authenticated organization returns `404`.

---

## Make an agent from a call

Creates a saved agent from the inline config a call ran, so you can pass
`agent_id` instead of sending the config with every call. It works for calls
that ran an inline config:

- an outbound call placed with `config` ([POST /v1/call](/api-reference/outbound-calls));
- an inbound call your config webhook answered with a config (`telephony.incoming`);
- a widget session your webhook answered with a config (`web.incoming`);
- a [realtime session](/api-reference/realtime) started with `config`.

The agent gets the config's prompt and settings and is deployed as version 1,
exactly as if you had created it with [POST /v1/agents](/api-reference/agents#create-an-agent).
The prompt is the one you sent, with its `{{variables}}` still in place: the
values filled in for this call are not copied into the agent. Creating an
agent this way needs the same access as creating one directly. An OAuth app
also needs to be allowed to read calls: it needs both the `agents:write` and
`calls:read` scopes, because the new agent holds the call's config.

Each call makes at most one agent. Repeating the request (a retry, a double
click) returns the agent already made, with `200 OK` and `already_existed:
true`, instead of making another. Once that agent is deleted, the call can
make a new one. While it still exists in another organization (it was moved
there), the call cannot make another and the request returns `409`.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/calls/987654321/create-agent \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Order desk"}'
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | no | The new agent's name. Defaults to the config's `agent_name`, else "Agent from call `<call_id>`". |

```json Response (201 Created)
{
  "agent": {
    "id": 42,
    "name": "Order desk",
    "prompt": "Hi {{first_name|there}}. Help with orders.",
    "voice": "james",
    "product": "bolt",
    "...": "every other agent field"
  },
  "already_existed": false,
  "source_call_id": 987654321,
  "not_copied": [
    {
      "field": "tools",
      "reason": "A saved agent's tools are API connections (lookup_order): add each as an integration and attach it to the agent. Their endpoints and headers are not kept, so enter them again."
    },
    {
      "field": "consent_announcement_enabled",
      "reason": "New agents must be created with the consent announcement enabled. Create the agent, record an attestation, then disable it."
    }
  ],
  "next_step": "Pass agent_id 42 instead of an inline config from now on, and move anything that changes from call to call into {{variables}} in the prompt or into per-call context. Then add the config's tools as integrations and attach them to the agent."
}
```

`agent` is the full [agent object](/api-reference/agents#agent-object).
`not_copied` lists the config's fields the agent does not have; it uses its
defaults for them instead:

- **Tools.** A saved agent calls your endpoints through
  [integrations](/api-reference/integrations), so the config's `tools` are
  listed by name for you to add. ThunderPhone keeps only each tool's name,
  description and parameters with the call, never its endpoint URL, headers
  or other connection details, so enter those again.
- **Settings an agent cannot start with.** A new agent starts with the consent
  announcement on, so a config that had it off is listed; record a
  [consent attestation](/api-reference/agents#consent-attestations) to turn it
  off. The same goes for any other value the agent validator refuses. The
  validator's message is the reason.
- **Realtime session settings**: `outbound`, `call_events` and `placeholders`
  when the session set them, `ivr_mode` on an outbound session (an inbound
  session's is always `off`, as an agent session's is), and `telephony` when
  the session turned it off. They belong to the session, not the agent: send
  them with each session, at the top level beside `agent_id` (see
  [Realtime](/api-reference/realtime#create-a-managed-realtime-session));
  `next_step` names them.

A config without `silence_interval_seconds` gives the agent a `null` interval,
so its check-ins keep ThunderPhone's own pacing rather than the agent default
of 15 seconds.

| Status | Condition |
|--------|-----------|
| `200` | An earlier request already made an agent from this call; it is returned with `already_existed: true` |
| `201` | Agent created |
| `400` | `code: "call_ran_saved_agent"`: the call ran a saved agent (its id is in `agent_id`) |
| `400` | `code: "no_stored_config"`: the call is from before calls answered by a config webhook, a widget webhook or a realtime session kept their config |
| `400` | `code: "config_too_large"`: a config webhook answer, widget webhook answer or realtime session config whose stored copy (its prompt and settings, with tools reduced to name, description and parameters) was over 64 KB, too large to keep with the call (`bytes` gives its size; the call itself ran normally). Create the agent with [POST /v1/agents](/api-reference/agents#create-an-agent). Outbound calls placed with `config` keep their whole config, so this limit does not apply to them |
| `400` | The agent validator refused the name, prompt or voice |
| `403` | An OAuth app without both the `agents:write` and `calls:read` scopes |
| `404` | Call not found in your organization |
| `409` | `code: "agent_moved"`: the agent made from this call has since moved to another organization, so the call cannot make another |

---

## Issue reports

Issue reports let your team (or automated grading) flag specific calls
for review. Reports have a severity and optional title/description and
appear in the org-wide [Issue Reports feed](/api-reference/issue-reports).

### List reports for a call

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/calls/987654321/issue-reports \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Returns an array of Issue Report objects — see [Issue Reports](/api-reference/issue-reports#issue-report-object).

### File a report

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/calls/987654321/issue-reports \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Agent paused too long",
    "description": "Five second silence before responding to the main question.",
    "severity": "warning"
  }'
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `title` | string | yes | 1–255 chars |
| `description` | string | no | Free-form. Defaults to `""` |
| `severity` | string | no | `info`, `warning`, or `critical`. Defaults to `warning` |
| `source` | string | no | `user` (default) or `system` |
| `timestamp_seconds` | integer ≥ 0 \| null | no | Offset into the call where the issue occurred |
| `detected_issue_ref` | string | no | Up to 128 chars — correlates the report with a grader-detected issue |
| `metadata` | object | no | Arbitrary JSON. Defaults to `{}` |

Returns `201 Created` with the [Issue Report object](/api-reference/issue-reports#issue-report-object).
To update a report's status later, use the
[issue-reports endpoints](/api-reference/issue-reports#update-a-reports-status)
(reports are addressed by `trace_id`).

---

## Live call supervision

Both endpoints work only while `status="in_progress"`; once the call
ends they return `409 Conflict` with `{"detail": "Call is not live."}`.
The dashboard's **Live** page is built on the same primitives.

### Listen in

Mints a hidden, subscribe-only token for the call's media room. The
listener is invisible: the agent, the caller, and the recording are
unaffected.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/calls/987654321/listen \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

```json Response
{
  "token": "eyJhbGciOi...",
  "room_name": "call-987654321",
  "server_url": "wss://livekit.thunderphone.com"
}
```

Connect to `server_url` with a LiveKit client SDK using `token` and
subscribe to the room's audio. The token is valid for up to 2 hours;
the session ends when the call's room closes.

| Status | Condition |
|--------|-----------|
| `200` | Token minted |
| `404` | Call not found |
| `409` | Call is not live |

### Whisper to the agent

Sends private text guidance that **only the agent hears** — the caller
is never aware of it. The agent weaves the guidance into its next
turns. Use it to coach an agent through an unusual situation mid-call.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/calls/987654321/whisper \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Offer the caller a 10% discount if they mention cancelling."}'
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `text` | string | yes | 1–1000 chars of operator guidance |

```json Response (202 Accepted)
{ "status": "sent" }
```

| Status | Condition |
|--------|-----------|
| `202` | Guidance delivered to the live session |
| `404` | Call not found |
| `409` | Call is not live (including the brief window after hang-up) |
| `502` | Delivery to the call runtime failed |

---

## Related

<CardGroup cols={2}>
  <Card title="Outbound Calls" icon="arrow-up-right" href="/api-reference/outbound-calls">
    Trigger a new outbound call via `POST /v1/call`.
  </Card>
  <Card title="Mic Sessions" icon="microphone" href="/api-reference/mic-sessions">
    Test an agent live from a browser.
  </Card>
  <Card title="Issue Reports" icon="triangle-exclamation" href="/api-reference/issue-reports">
    Org-wide feed of issue reports across calls.
  </Card>
  <Card title="Simulations" icon="flask" href="/api-reference/test-calls">
    Programmatic batched simulations against an agent.
  </Card>
</CardGroup>

<!-- en: api-reference/outbound-calls -->
---
title: "Outbound Calls"
description: "Trigger an outbound voice call from an outbound-enabled phone number."
---

Place an outbound call from one of your own [phone numbers](/api-reference/phone-numbers)
to a target number. You can reference a saved [agent](/api-reference/agents)
by id, or inline a one-off configuration for this call only.

## Endpoint

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/call` | Place an outbound call |
| `POST` | `/v1/calls/{call_id}/cancel` | Cancel a [queued](#queued-calls) call before it dials |

<Note>
  `from_number` must be an outbound-enabled number in your organization.
  Customer VoIP numbers continue to support outbound calling. ThunderPhone
  numbers start inbound-only; an organization admin can request outbound
  calling from the Phone Numbers page. ThunderPhone reviews each request
  manually, and approved numbers can place calls and run campaigns.
</Note>

## Place a call

<CodeGroup>
```bash Using an agent id
curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155552671",
    "agent_id":    12,
    "idempotency_key": "crm-task-4815"
  }'
```

```bash Inline config (one-off)
curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155552671",
    "config": {
      "prompt": "You are calling on behalf of Acme to confirm…",
      "voice":  "john",
      "product": "spark",
      "tools": []
    }
  }'
```

```bash Saved agent with variables and context
curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number": "+14155552671",
    "agent_id": 12,
    "variables": {"name": "Ada", "account_id": "A-17"},
    "context": "Ada asked to be called back about the late fee on her March invoice."
  }'
```

```python Python
result = requests.post(
    "https://api.thunderphone.com/v1/call",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={
        "from_number": "+15551234567",
        "to_number":   "+14155552671",
        "agent_id":    12,
    },
).json()
```
</CodeGroup>

### Request fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `from_number` | string | yes | E.164. Must be an outbound-enabled number owned by this organization |
| `to_number` | string | yes | E.164 target. A number without a country code is read in the `from_number`'s country and called in E.164 |
| `agent_id` | integer | see below | An [agent](/api-reference/agents) id in this org |
| `variables` | object | no | Per-call values for `{{name}}` and `{{name\|Friend}}` placeholders. Strings, numbers, booleans, or null; 32 KB maximum. Applies to the saved agent or inline prompt. See [call variables](/guides/call-variables). |
| `context` | string | no | Free-form text for this call, such as a task description or notes collected earlier, up to 20,000 characters. Added after the prompt in a delimited block and not rendered as a template. Works with `agent_id`, `config` or the number's outbound agent. Also accepted inside `config`; when both are sent they must match. See [call variables and context](/guides/call-variables#context) |
| `config` | object | see below | Inline config — schema matches the `call.incoming` webhook response |
| `max_hold_seconds` | integer | no | Override the agent's hold timeout for this call only |
| `timezone` | string | no | IANA time zone for this call only, such as `America/Chicago`. The agent states the date and time and offers times in it, ahead of the agent's own [`timezone`](/api-reference/agents#deployed-fields). Use it when one agent calls contacts in different zones. Also accepted inside `config`. A name that is not an IANA zone is ignored (the call goes ahead in the agent's zone) and reported in the response's `warnings` |
| `idempotency_key` | string (1–128 characters) | no | Prevent duplicate origination when the same normalized request is retried. Unique within the organization for the lifetime of the retained call record. |

Exactly **one** of:

1. `agent_id` — use the saved configuration.
2. `config` — inline a one-off configuration (same shape as a `call.incoming`
   [webhook response](/webhooks/call-incoming#response-schema)).
3. Neither — the call uses the number's configured `outbound_agent`. Fails
   with `400` if no outbound agent is set.

### Response

Returns `201 Created`:

```json
{
  "call_id": 987654321,
  "status":  "initiated"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `call_id` | integer | Assigned id — use it on the [call endpoints](/api-reference/calls) to follow the call. |
| `status` | string | Always `"initiated"` on success. This is the *initiation* status, not the [call state machine](/api-reference/calls#call-object); poll `GET /v1/calls/{call_id}` for the live `status` (`in_progress` → `completed`/`failed`). |
| `queued_at` | timestamp | Only present when the call is [waiting for room](#queued-calls): when it began waiting. |
| `warnings` | array | Only present when part of the request was ignored, each `{"code", "message"}`. `timezone_invalid`: `timezone` was not an IANA zone. |

`201` means LiveKit accepted the origination request. The endpoint does **not**
wait for the destination to answer. Busy, no-answer, rejection, and trunk
failures therefore normally arrive asynchronously: poll
[`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call) or subscribe
to [`telephony.complete`](/webhooks/call-complete). A failed dial transitions
the call to `failed`, releases its billing reservation, and reports a sanitized
`end_reason`.

The call rings for the agent's [`ring_duration_seconds`](/api-reference/agents#deployed-fields)
(60 seconds when unset) and never less than 14 seconds: a call that rings
briefly and drops looks like a one-ring scam call. Once it connects and ends,
the call's [`answered_by`](/api-reference/calls#call-object) says whether a
person, voicemail, a call screening assistant or a phone menu answered.

If the LiveKit submission response times out, ThunderPhone cannot safely know
whether LiveKit accepted the call. The API returns `202 Accepted` with the same
`call_id` and `"status": "unknown"`; ThunderPhone then reconciles the
deterministic room and SIP participant. It never treats that timeout as a
definite failure or blindly originates a second call.

### Idempotent retries

Send `idempotency_key` when a client might retry `POST /v1/call`. The key is
scoped to the organization and remains reserved for as long as the `CallLog`
is retained. The request fingerprint covers the normalized `from_number`,
`to_number`, `agent_id`, complete inline `config`, language override,
`max_hold_seconds`, `timezone`, `variables` and `context`.

A replay of the same request returns `200 OK`, the original `call_id`, and
`"idempotent_replay": true` without originating a second call. Its `status`
reflects the durable outcome: `pending`, `unknown`, `initiated`, `in_progress`,
`completed`, or `failed`. Failed replays also include the stored sanitized
`failure_reason`. Reusing a key with a different normalized request returns
`409 Conflict`.

Poll [`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)
to observe state transitions:

| Live `status` | Meaning |
|---------------|---------|
| `in_progress` | SIP dialing or connected, or [waiting for room](#queued-calls) when `queued_at` is set |
| `completed` | Call ended normally |
| `failed` | Call could not be established (trial-mode, unverified number, provider error) |

### Queued calls

ThunderPhone keeps some of its shared outbound capacity free for live
transfers. When the rest is in use, a call from a ThunderPhone number waits
in line instead of being refused. The response is the usual `201` with the
same `call_id` and `status`, plus `queued_at`, when it began waiting:

```json Queued
{
  "call_id": 987654321,
  "status": "initiated",
  "queued_at": "2026-10-31T18:00:00Z"
}
```

While it waits, [`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)
shows `status` `in_progress` and the same `queued_at`, and nothing has been
dialed. `queued_at` becomes `null` once the call starts dialing.

- Calls dial in the order they were placed, usually within a minute of room
  opening. Calls through your own carrier never queue.
- A queued call is not billed, holds no credit and does not count toward your
  [concurrent-call limit](/api-reference/introduction#call-limits). When its
  turn comes it is checked as a new call would be. If your organization is at
  its limit, out of balance, called that number too recently, or the number has
  opted out, the call ends as `failed` with that reason as its `end_reason`:
  `concurrent_call_limit_reached`, `insufficient_balance`,
  `spending_limit_reached`, `same_number_too_soon` or `contact_opted_out`.
- A call still waiting after **10 minutes** ends as `failed` with `end_reason`
  `outbound_queue_timeout`. It is not billed, and nothing was dialed.
- Queuing sends no webhook. [`telephony.complete`](/webhooks/events#telephony-complete)
  fires once when the call ends, with `status` `failed` if it never dialed. No
  `call.billed` follows a call that never dialed.
- Sending the same `idempotency_key` again returns the same call, still waiting,
  and does not move it in line.
- An organization may have up to **50 calls** waiting. Past that, a new call is
  not accepted: `429` with `code` `outbound_queue_full`. Retry after the seconds
  in `Retry-After`.

To stop a queued call, cancel it. It ends as `failed` with `end_reason`
`outbound_queue_canceled`, not billed. Repeating a cancel that succeeded returns
the same result. Once the call has started dialing or ended some other way, the
request returns `409` with `code` `call_not_queued`. A queued call cannot be
[deleted](/api-reference/calls#delete-a-call) until it has been cancelled.

```bash Cancel a queued call
curl -X POST https://api.thunderphone.com/v1/calls/987654321/cancel \
  -H "Authorization: Bearer $THUNDERPHONE_API_KEY"
```

### Error responses

| Status | Body `code`/`detail` hint | Meaning |
|--------|--------------------------|---------|
| `400` | `from_number and to_number are required` | Missing required fields |
| `400` | `Provide either agent_id or config, not both` | Both supplied |
| `400` | `{ "code": "destination_not_allowed", "reason": "...", "detail": "..." }` | `to_number` is a destination ThunderPhone does not call. See [blocked destinations](#blocked-destinations) |
| `402` | Insufficient balance | Org balance is ≤ $0.00. Top up first |
| `403` | `outbound_tcpa_confirmation_required` | The org's [one-time TCPA confirmation](#outbound-tcpa-confirmation) is missing |
| `404` | `from_number is not registered to this organization` | The number is unknown, belongs to another organization, or is not active when the request first looks it up |
| `404` | `Agent not found` | `agent_id` invalid or wrong org |
| `409` | Idempotency key already used with a different request | Use the original request or a new key |
| `409` | `{ "code": "...", "detail": "...", "retryable": false }` | The number is not eligible to place this call. Correct the number's state before trying again; do not retry the same request unchanged. |
| `429` | `concurrent_call_limit_reached` | Your organization already has as many calls in progress as its [concurrent-call limit](/api-reference/introduction#call-limits). Nothing was dialed; retry after `Retry-After` seconds or when a call ends |
| `429` | `same_number_too_soon` | Your organization called this `to_number` less than its [same-number spacing](/api-reference/introduction#call-limits) ago (10 seconds by default). Retry after `Retry-After` seconds |
| `429` | `outbound_queue_full` | Your organization already has 50 [queued calls](#queued-calls) waiting. Nothing was accepted; retry after `Retry-After` seconds |
| `429` | `platform_outbound_daily_limit_reached` | Today's [daily limit](/api-reference/phone-numbers#daily-limit) for calls from ThunderPhone numbers is used up |
| `500` | `{ "detail": "..." }` | No outbound trunk is configured. Contact support; this is not a number-state problem you can correct. |
| `502` | Upstream SIP / LiveKit submission failure | The stored attempt is failed. Correct the reported issue or retry as a new call with a new idempotency key. |

Eligibility conflicts use one of these stable `code` values:

- ThunderPhone-number review state: `managed_number_inbound_only`,
  `managed_number_outbound_pending`, `managed_number_outbound_denied`, or
  `managed_number_outbound_revoked`.
- Number state: `number_provisioning`, `number_failed`, `number_releasing`,
  `number_released`, or `number_missing`.
- Customer VoIP state: `voip_verification_failed`, `voip_connection_missing`,
  `voip_connection_wrong_organization`, `voip_connection_error`,
  `voip_connection_pending`, `voip_connection_testing`,
  `voip_verification_unverified`, or `voip_verification_stale`.

The request first looks up an active `from_number`. A number that is already
provisioning, failed, releasing, or released fails that lookup with `404`. If an
initially active number becomes ineligible after the request is accepted but
before the call is placed, the final eligibility check returns the `409` payload
above with the corresponding `number_*` code.

The other `409` response is the existing idempotency conflict. It has a
`detail` field but does not include `code` or `retryable`.

### Blocked destinations

Every outbound call, from any number, refuses `to_number` values that are not
valid phone numbers (`reason` `invalid_number`), emergency numbers such as 911,
112 or 999 (`emergency_number`), short codes (`short_code`), and numbers in
Cuba, Iran, North Korea or Syria (`sanctioned_country`). Calls from a number
on your own carrier ([VoIP connection](/api-reference/voip-connections)) are
refused only for these reasons; any other number, including premium-rate and
shared-cost numbers, is up to you and your carrier.

A number on your organization's [opt-out list](/api-reference/opt-outs) for
calls is refused with `reason` `contact_opted_out`, from any number.

Calls from ThunderPhone numbers can also only reach ordinary US and Canadian
numbers: landline, mobile, toll-free or VoIP. Premium-rate numbers return
`premium_rate`, other countries `platform_country_not_supported`, other number
types `platform_number_type_not_supported`, and the fictional 555-0100 to
555-0199 range `fictional_number`. To call these, use a number on your own
carrier.

<Warning>
  Make sure your account has enough balance. Calls block at `<= $0.00`
  (402). See [Billing → Top up](/api-reference/billing#top-up-balance).
</Warning>

## Changelog

- **2026-08-06:** `POST /v1/call` now returns after origination is accepted
  instead of waiting for answer; ring failures finalize asynchronously.
  Added optional `idempotency_key`, durable dial-state reconciliation, and
  `202 status=unknown` for ambiguous submission timeouts.

---

## Outbound TCPA confirmation

Before an organization's **first** outbound-enabling action, an
organization admin must record a one-time confirmation that its outbound
calling complies with applicable telemarketing/robocall law (including
the TCPA). Until it exists, `POST /v1/call` and
[campaign](/api-reference/campaigns) creation/`start` reject with:

```json
{
  "code":   "outbound_tcpa_confirmation_required",
  "detail": "Outbound calling requires a one-time TCPA compliance confirmation…"
}
```

with status `403`. The confirmation is **per organization and one-time**
— once recorded, it is never requested again. It applies only to
**organizations created on or after 2026-08-03**; organizations that
existed before then (and enterprise-agreement organizations) are fully
exempt — `GET /v1/outbound-tcpa-confirmation` reports this as
`"gate_applies": false`. The gate covers only originating outbound
calls: inbound calls, live-call transfers, and campaigns that are
already running are never affected.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/outbound-tcpa-confirmation` | Confirmation status + current `text_version` |
| `POST` | `/v1/outbound-tcpa-confirmation` | Record the confirmation (org **admin** sessions only) |

`GET` returns:

```json
{
  "text_version": "outbound-tcpa-v4-2026-08-03",
  "statement_en": "I confirm on behalf of my organization that its outbound calls through ThunderPhone will comply with applicable calling laws — the TCPA and FCC rules for U.S. calls, and the destination country's laws elsewhere.",
  "fcc_link_url": "https://www.ecfr.gov/current/title-47/chapter-I/subchapter-B/part-64/subpart-L/section-64.1200",
  "docs_link_url": "https://thunderphone.com/docs/guides/outbound-calling-laws",
  "gate_applies": true,
  "confirmed": false,
  "confirmation": null
}
```

`POST` takes `{ "accepted": true, "text_version": "…", "locale": "en",
"rendered_text": "…" }`. `rendered_text` must be **exactly** the
canonical statement for the submitted `text_version` — the statement is
server-pinned, and a mismatch returns `400`. It is stored server-side as
a SHA-256 hash, with the UI locale, confirming user + role, IP, and user
agent, as the evidence record. `text_version` may be the current version
from `GET` or any still-accepted earlier version (so a dialog fetched
just before a statement update still submits cleanly, paired with that
version's own statement text). Returns `201` (or `200` if the org is
already confirmed — repeat confirms are idempotent).

<Note>
  The confirmation is an organization-binding representation, so it
  cannot be recorded with an `sk_live_` API key — an organization
  admin confirms once, normally via the dashboard prompt that appears
  on the first outbound action (`403` on `POST` with a key). API-key
  calls to `/v1/call` are gated all the same until that happens.
</Note>

---

## Related

<CardGroup cols={2}>
  <Card title="Agents" icon="robot" href="/api-reference/agents">
    Configure the prompt, voice, and tools for outbound calls.
  </Card>
  <Card title="VoIP Connections" icon="phone-volume" href="/api-reference/voip-connections">
    Set up the VoIP provider credentials that back outbound calls.
  </Card>
  <Card title="Calls" icon="phone" href="/api-reference/calls">
    Observe the call as it runs and inspect the transcript afterward.
  </Card>
  <Card title="Billing" icon="credit-card" href="/api-reference/billing">
    Keep your prepaid balance topped up so outbound calls can place.
  </Card>
</CardGroup>

<!-- en: api-reference/sip-addresses -->
---
title: "SIP Addresses"
description: "Register one-time SIP URIs for calls, and manage permanent SIP endpoints that route to an agent."
---

Reach an agent over SIP without a phone number. For how and when to use each
kind, see [Connect over SIP](/guides/sip-addresses).

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/calls/register-sip` | Register a call and get a one-time SIP URI |
| `GET` | `/v1/sip-endpoints` | List SIP endpoints |
| `POST` | `/v1/sip-endpoints` | Create a SIP endpoint (returns its password once) |
| `GET` | `/v1/sip-endpoints/{id}` | Get a SIP endpoint |
| `PATCH` | `/v1/sip-endpoints/{id}` | Update name, agent, authentication, source-IP allowlist, dial-in numbers, SRTP or status |
| `DELETE` | `/v1/sip-endpoints/{id}` | Delete a SIP endpoint |
| `POST` | `/v1/sip-endpoints/{id}/rotate-password` | Issue a new password (returned once; `digest` endpoints only) |

Creating, updating and deleting require an organization API key, or a
dashboard session with the admin role or higher.

## Register a call

`POST /v1/calls/register-sip`

### Request fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `agent_id` | integer | yes | Agent in your organization that answers the call |
| `to_number` | string | no | E.164 number the caller dialed on your side; stored as the call's destination |
| `variables` | object | no | Values for the agent prompt's `{{placeholders}}` |

### Response (`201`)

| Field | Type | Description |
|-------|------|-------------|
| `call_id` | integer | Id the call will have in call history |
| `sip_uri` | string | One-time SIP URI to dial: `sip:c-<token>@sip.thunderphone.com`. Treat it as a secret until used |
| `expires_at` | string | When the URI stops working (5 minutes after registration) |
| `agent_id` | integer | The answering agent |
| `to_number` | string \| null | The registered destination, if any |

The URI works for one call. After that call, or after `expires_at`, calls to it
are refused.

### Errors

| Status | When |
|--------|------|
| `400` | Unknown agent, `to_number` not in E.164 format, or invalid `variables` |
| `403` | Dashboard session below the admin role |
| `503` | SIP addresses are not available in this environment |

## SIP endpoint object

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Endpoint id |
| `name` | string | Your label |
| `agent_id` | integer \| null | Agent that answers calls to the endpoint |
| `sip_uri` | string | Permanent address: `sip:agent-<id>-<letters>@sip.thunderphone.com` |
| `auth` | string | `digest` (username and password) or `ip_allowlist` (source IP only, no password) |
| `username` | string \| null | SIP digest username; `null` when `auth` is `ip_allowlist` |
| `password` | string | Only in responses that issue one: create and `rotate-password` with `digest`, and an update that switches `auth` to `digest` |
| `allowed_source_cidrs` | string[] | Source IP ranges allowed to call. With `digest`, empty means any source with valid credentials. Checked for TCP/TLS calls only: an endpoint with an allowlist refuses UDP calls |
| `dial_in_numbers` | string[] | Phone numbers a contact-center platform dials to reach the endpoint, as stored (see below). Empty for most endpoints |
| `srtp` | string | Media encryption: `disabled`, `optional` or `required`. Always `disabled` with `digest` |
| `status` | string | `active`, `disabled` (calls refused) or `provisioning` (setup in progress or failed; cannot receive calls) |
| `created_at` | string | Creation time |

## Create a SIP endpoint

`POST /v1/sip-endpoints`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `agent_id` | integer | yes | Agent in your organization |
| `name` | string | no | Label, up to 120 characters |
| `auth` | string | no | `digest` (default) or `ip_allowlist` |
| `allowed_source_cidrs` | string[] | with `ip_allowlist` | Up to 50 IPv4/IPv6 addresses or CIDR ranges |
| `dial_in_numbers` | string[] | no | Up to 5 numbers the platform dials; `ip_allowlist` only (see [Dial-in numbers](#dial-in-numbers)) |
| `srtp` | string | no | `disabled` (default), `optional` (SRTP when the caller offers it) or `required` (calls without SRTP fail). `optional` and `required` need `ip_allowlist` |

Returns `201` with the endpoint object, including `password` for a `digest`
endpoint. An `ip_allowlist` endpoint has no username or password.

`allowed_source_cidrs` entries are normalized and deduplicated. `0.0.0.0/0`
and `::/0` are refused (they are not an allowlist). With `digest`, use `[]`
to allow any source with valid credentials.

With `ip_allowlist`, the list is the only check on who can call, so it must
contain at least one entry and every entry must be:

- an IPv4 range of `/16` or narrower, or an IPv6 range of `/48` or narrower;
- public: private, loopback, link-local, shared (`100.64.0.0/10`),
  documentation, reserved and multicast ranges are refused;
- outside ThunderPhone's and LiveKit's own addresses.

An `ip_allowlist` endpoint accepts calls over TCP (port 5060) or TLS (port
5061) only. Calls over UDP are refused, because a UDP source address can be
forged.

### Dial-in numbers

Some contact-center platforms (Five9, NICE CXone, Zoom Contact Center) send a
call to a phone number and can't dial the `agent-…` user of `sip_uri`. List
the numbers they dial in `dial_in_numbers`; a call to
`sip:<number>@sip.thunderphone.com` then reaches the endpoint like a call to
its `sip_uri`.

- Only with `auth` set to `ip_allowlist`. A number adds an address, not a
  credential: calls to it need the same allowed source, over TCP or TLS, as
  calls to `sip_uri`.
- At most 5. Each is 6 to 15 digits with an optional leading `+`. Spaces,
  dashes and parentheses are removed; the number is otherwise stored as
  written, so enter it the way the platform dials it (Zoom's 15-digit
  `999…` numbers have no `+`). Numbers that differ only in the `+` count once.
- A number can't be on another SIP endpoint, in any organization, or be a
  ThunderPhone phone number. `+14155550142`, `14155550142` and `4155550142`
  count as the same number.
- The call's destination in call history is the number in `X-Original-To` or
  `Diversion` when the platform sends one, otherwise the dial-in number.

`srtp` set to `optional` or `required` also needs `ip_allowlist`; a `digest`
endpoint takes only `disabled`. Platforms that need SRTP, such as Zoom Contact
Center and Talkdesk, authenticate by source IP. Use SRTP with TLS.

| Status | When |
|--------|------|
| `400` | Unknown agent, invalid field, invalid CIDR, an `ip_allowlist` list that is missing or breaks the rules above, an invalid dial-in number or more than 5, or dial-in numbers or SRTP with `digest` |
| `403` | Dashboard session below the admin role |
| `409` | A dial-in number is already in use |
| `502` | The address could not be set up. Retry the request |
| `503` | SIP addresses are not available in this environment |

After a `502`, create the endpoint again. A leftover endpoint in
`provisioning` never received a password, cannot receive calls and is removed
automatically; don't wait for it to become active.

## List and get SIP endpoints

`GET /v1/sip-endpoints` returns `200` with `{"results": [...]}`, newest first.
`GET /v1/sip-endpoints/{id}` returns one endpoint; an unknown id, or one in
another organization, returns `404`. Read responses never include `password`.

## Update a SIP endpoint

`PATCH /v1/sip-endpoints/{id}` accepts any of `name`, `agent_id`, `auth`,
`allowed_source_cidrs`, `dial_in_numbers`, `srtp` and `status` (`active` or
`disabled`). Returns the endpoint object. Changing the agent or the allowlist
takes effect for the next call. Changing `status`, `auth`, `dial_in_numbers`
or `srtp` returns `409` while the endpoint is still `provisioning`.

`dial_in_numbers` replaces the whole list; send `[]` to remove every number.
The same rules as on create apply, and a number already in use returns `409`
with nothing changed. If the response is `502`, the new list is saved but
calls to a newly added number fail until you send the same request again.
Changing `srtp` behaves the same way. Setting `dial_in_numbers` or turning
`srtp` on for a `digest` endpoint returns `400`.

Changing `auth`:

- **To `ip_allowlist`:** send a valid `allowed_source_cidrs` in the same
  request, unless the endpoint's current list already meets the
  `ip_allowlist` rules. The password stops working. If the response is `502`,
  calls to the endpoint are refused until you send the same request again.
- **To `digest`:** the response includes a new `password`, returned only
  once; the username stays the same. The allowlist is kept unless you change
  it in the same request. An endpoint with dial-in numbers or SRTP returns
  `409` unless the same request sends `"dial_in_numbers": []` and
  `"srtp": "disabled"` as needed. If the response is
  `502`, nothing changed and the endpoint still accepts calls by source IP
  only.

Setting `auth` to the value it already has issues no new password; use
`rotate-password` for that.

## Rotate the password

`POST /v1/sip-endpoints/{id}/rotate-password` returns the endpoint object with
a new `password`. The old password stops working immediately. An
`ip_allowlist` endpoint has no password and returns `409`.

## Delete a SIP endpoint

`DELETE /v1/sip-endpoints/{id}` returns `204`. Calls to the address are refused
from then on. Call history is kept. It returns `409` while the endpoint is
still `provisioning`; an endpoint whose setup failed is removed automatically,
usually within an hour.

<!-- en: api-reference/realtime -->
---
title: "Realtime WebSocket"
description: "Exchange live call audio, transcripts, and call-control events over one WebSocket."
---

The Realtime WebSocket API provides bidirectional audio over a single
connection. It uses a focused realtime event subset for connecting
ThunderPhone agents to your telephony stack.

For a setup walkthrough and test checklist, see [Use ThunderPhone with OpenAI
Realtime clients](/guides/use-with-openai-realtime).

One WebSocket connection represents one call. Realtime calls appear in
[call history](/api-reference/calls) and are billed like any other call
([pricing](/guides/pricing)). A session whose client never joins is not billed.

## Create a managed realtime session

`POST /v1/realtime/sessions` creates a LiveKit room and returns a scoped
participant token. Authenticate with a secret API key and provide either a
saved `agent_id` or an inline `config`, but not both.

```bash
curl -X POST https://api.thunderphone.com/v1/realtime/sessions \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": 12}'
```

Two optional top-level fields carry per-call input, with either `agent_id` or
`config` (see [call variables and context](/guides/call-variables)):

| Field | Type | Description |
|-------|------|-------------|
| `variables` | object | Values for `{{name}}` and `{{name\|Friend}}` placeholders in the prompt. Strings, numbers, booleans, or null; 32 KB maximum |
| `context` | string \| null | Free-form text for this call, such as a task description or notes collected earlier, up to 20,000 characters. Added after the prompt in a delimited block and not rendered as a template. Top level only: an inline `config` rejects it |

A `variables` or `context` value that fails validation returns `400` before any
room is created.

A session with `agent_id` also takes the session's own options at the top
level. An inline session sets `telephony`, `outbound`, `ivr_mode`,
`call_events` and `placeholders` inside `config` instead. `language` is
top-level for both kinds of session (an inline `config` can also use
`primary_language`).

| Field | Type | Description |
|-------|------|-------------|
| `telephony` | boolean | `true` (default) for phone audio, `false` for browser audio |
| `outbound` | boolean | The session is an outbound call: the agent speaks first or waits by its `outbound_speak_order` (default: it waits for the other side; an inline session always waits), can wait on hold, and handles phone menus. Default `false` |
| `ivr_mode` | string | With `outbound`: phone-menu handling, `auto` (default), `on`, or `off`. `auto` or `on` without `outbound` returns `400` |
| `call_events` | boolean | Deliver [`call.*` events](#call-events) and give the agent `transfer_call` (cold only, to its transfer numbers once directories apply) and, on outbound sessions, `send_keypad_input`. Your client carries them out. Default `false` |
| `placeholders` | array of string | Up to 10 lines, 200 characters each, said while a reply is still being written, in place of the agent's own filler lines (while its filler phrases are on). Default none |
| `language` | string | The language the session starts in, a supported language code such as `es` (`es-MX` is read as `es`). The agent speaks it with its voice for that language: its [`language_voices`](/api-reference/agents#deployed-fields) entry; else, with `native_voice_switching`, the native voice it would switch to; else its own voice when that voice speaks it, and its other languages and its primary language stay available. Otherwise the language's default voice (a custom voice is kept) and that language alone. An unsupported code is `400`. Default: the agent's primary language |

A value that fails validation returns `400` before any room is created.
Tools your client runs are not a session option: a session with `agent_id`
uses the agent's tools only.

Inline configuration accepts only `prompt`, `voice`, `product`, `tools`,
`primary_language`, `additional_languages`, `background_track`,
`additional_audio_context`, `words`, `telephony`,
`placeholders`, `outbound`, `ivr_mode`, `call_events`, `transfer_destinations` (see
[Call capabilities](#call-capabilities)), and `max_hold_seconds` (optional integer,
10–900 seconds; `null` uses the default). `prompt` is required.
Unknown keys are rejected with a validation error rather than silently
ignored.

```json
{
  "config": {
    "prompt": "Listen carefully and help complete the call.",
    "voice": "olivia",
    "product": "spark"
  }
}
```

The operation returns `201 Created` with the room credentials:

```json
{
  "call_id": 123456789,
  "room_name": "realtime-123456789",
  "livekit_url": "wss://your-livekit-host.example.com",
  "token": "<scoped-participant-token>"
}
```

A realtime session is a call and counts toward your organization's
[concurrent-call limit](/api-reference/introduction#call-limits). At the
limit, this request returns `429 Too Many Requests` with code
`concurrent_call_limit_reached` and a `Retry-After` header. Over the
WebSocket, the same refusal arrives as an `error` event.

## Endpoint

| Protocol | URL | Description |
|----------|-----|-------------|
| WebSocket | `wss://api.thunderphone.com/v1/realtime` | Start one realtime call |

<Note>
  The realtime endpoint shares its host with the REST API — the same
  `api.thunderphone.com` base URL and API key work for both.
</Note>

## Connect and authenticate

Authenticate the WebSocket upgrade with your secret API key:

```http
Authorization: Bearer sk_live_YOUR_API_KEY
```

Browser clients that cannot set an upgrade header can pass the key in the
query string instead:

```text
wss://api.thunderphone.com/v1/realtime?api_key=sk_live_YOUR_API_KEY
```

<Warning>
  A query-string key can appear in browser history and network logs. Use the
  `Authorization` header whenever your WebSocket client supports it, and
  never expose a secret API key in public client code.
</Warning>

After the connection opens, the server sends `session.created`. Configure
the call with `session.update`; the server confirms the accepted settings
with `session.updated`.

## Configure the session

Send the GA nested session shape before streaming audio. The first
`session.update` starts an inline session, and a saved-agent session that
the update selects or that waits for it (`wait_for_session_update=1`); a
saved agent named in the URL otherwise starts at connect. For an inline session, `instructions` is the
call's prompt; when it is omitted or empty, ThunderPhone uses `You are a
helpful voice assistant.` To run a saved agent instead, see [Use a saved
agent](#use-a-saved-agent).

```json
{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "instructions": "Listen to the caller and help them complete the call.",
    "audio": {
      "input": {
        "format": { "type": "audio/pcm", "rate": 16000 }
      },
      "output": {
        "format": { "type": "audio/pcm", "rate": 16000 },
        "voice": "olivia"
      }
    }
  }
}
```

### Session fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `session.type` | string | no | Use `"realtime"` |
| `session.instructions` | string | no | Inline sessions: the prompt that defines the agent's behavior for this call. Saved-agent sessions: this session's brief, added to the agent's prompt as context |
| `session.prompt` | object | no | Runs a saved agent: `{"id": "12", "variables": {...}}`, where `id` is the agent ID. `version` is accepted and ignored. See [Use a saved agent](#use-a-saved-agent) |
| `session.audio.input.format.type` | string | no | `"audio/pcm"` (default), `"audio/pcmu"`, or `"audio/pcma"`; beta names `"pcm16"`, `"g711_ulaw"`, `"g711_alaw"` are also accepted |
| `session.audio.input.format.rate` | integer | no | PCM input rate: `24000` (default) or `16000` Hz; G.711 is always `8000`. Send the rate explicitly if your client is not at 24 kHz — a mismatch plays audio at the wrong speed rather than erroring |
| `session.audio.input.noise_reduction` | object | no | `{"type":"near_field"}` selects noise cancellation tuned for wideband or browser-style audio; `{"type":"far_field"}` or omission uses the default telephony tuning |
| `session.audio.output.format.type` | string | no | `"audio/pcm"` (default), `"audio/pcmu"`, or `"audio/pcma"`; beta names `"pcm16"`, `"g711_ulaw"`, `"g711_alaw"` are also accepted |
| `session.audio.output.format.rate` | integer | no | PCM output rate: `24000` (default) or `16000` Hz; G.711 is always `8000`. Send the rate explicitly if your client is not at 24 kHz — a mismatch plays audio at the wrong speed rather than erroring |
| `session.audio.output.voice` | string | no | ThunderPhone voice name from the [voice gallery](/api-reference/voices); omitted (or an OpenAI voice name) falls back to the default voice. Entitled organizations can pass `custom:<public_id>` for a ready [custom voice](/api-reference/custom-voices#use-a-custom-voice), or `cartesia:<voice_id>` for a voice in their own Cartesia account once ThunderPhone has [configured it](/api-reference/custom-voices#bring-your-own-cartesia-voice) |
| `session.binary_output` | boolean | no | When `true`, return audio deltas as raw binary WebSocket frames instead of base64 JSON events |
| `session.live_transcripts` | boolean | no | When `true`, stream caller transcript deltas while the caller is still speaking, ahead of the settled transcript — see [Live transcripts](#live-transcripts). Also accepted as `session.config.live_transcripts`. Can be sent in any `session.update`, including after the session starts. The extra transcription is billed for the whole session once enabled |
| `session.config.tools` | array | no | Inline function definitions delivered back to this client when the agent calls them |
| `session.config.product` | string | no | Product tier for the call, such as `storm-base` (the default) |
| `session.config.variables` | object | no | Values for `{{name}}` placeholders in the prompt: strings, numbers, booleans, or `null` (`null` uses the `{{name\|default}}` default). See [Call variables](/guides/call-variables) |
| `session.config.additional_audio_context` | boolean \| null | no | Include the last few turns of caller audio rather than only the most recent turn, improving corrections and spelling/number-heavy data collection at a small latency/cost overhead. Defaults on for browser/WebSocket sessions; `null` keeps the default |

`session.config` accepts only `voice`, `product`, `tools`,
`primary_language`, `additional_languages`, `background_track`, `telephony`,
`placeholders`, `outbound`, `ivr_mode`, `call_events`, `additional_audio_context`,
`words`, `transfer_destinations`, `variables`, `live_transcripts`, `binary_output`, and `max_hold_seconds` (optional integer, 10–900 seconds; `null` uses the default). An inline
call's prompt comes from `session.instructions`; `session.config.prompt` is
rejected. Unknown keys are rejected with a
validation error rather than silently ignored. Set `telephony` to `false` for
the same wideband or browser-style input tuning selected by
`session.audio.input.noise_reduction.type` set to `near_field`.

All audio is mono. PCM audio is signed 16-bit little-endian at 16000 or
24000 Hz; G.711 (`audio/pcmu` μ-law, `audio/pcma` A-law) is 8000 Hz, matching
telephony trunks — no client-side transcoding needed. Input and output formats
are configured independently, but neither can change after the call starts.
After the call starts, agent configuration is immutable: `instructions`,
`prompt`, `voice`, `tools`, `product`, and other `session.config` fields,
including `variables`, cannot change.
Bridge-local transport options such as `binary_output` remain changeable.

For compatibility, flat `instructions`, `voice`, `input_audio_format`, and
`output_audio_format` fields are also accepted on `session.update`. New
integrations should use the nested shape above.

Inline sessions can define custom functions under `session.config.tools`. The
function schema is available to the agent; your WebSocket client remains
responsible for executing the function and returning its output.

```json
{
  "type": "session.update",
  "session": {
    "instructions": "Help callers check an order.",
    "config": {
      "tools": [
        {
          "type": "function",
          "function": {
            "name": "lookup_order",
            "description": "Look up an order by id.",
            "parameters": {
              "type": "object",
              "properties": { "order_id": { "type": "string" } },
              "required": ["order_id"]
            }
          }
        }
      ]
    }
  }
}
```

Custom tools on saved-agent sessions continue to use the routing configured on
the saved agent; they are not delivered to the WebSocket client.

### Inline sessions are client-steered

With inline configuration, ThunderPhone adds no automatic greeting or spoken
silence check-ins, and by default nothing is spoken while a response is being prepared.
If you want progress speech during slow responses — for example while the
agent waits on one of your tool results — set `placeholders` in the session
config to a list of short phrases in your own words (e.g.
`{"placeholders": ["One moment.", "Still checking."]}`). They are spoken in
the session voice, cycling only when a response takes long enough to need
them.
If the caller goes quiet, the platform's silent-call limit ends the session
after 600 seconds by default. Silence-behavior config keys are not accepted and
are rejected with a validation error.

To have the agent open the call, configure the session, append a system or user
message, and explicitly request one response:

```json
{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "instructions": "Help the caller."
  }
}
```

```json
{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "system",
    "content": [
      { "type": "input_text", "text": "Greet the caller and offer help." }
    ]
  }
}
```

```json
{ "type": "response.create" }
```

`session.created` is sent as soon as the WebSocket connects. `session.updated`
is sent only after the configuration has been accepted and the session fully
provisioned, so it is the signal that the call is live; a rejected
configuration produces an `error` event instead, and the session stays usable
for a corrected retry. You do not need to wait, though: message items and
`response.create` sent early are buffered and delivered in order once the
agent is ready, so the opening sequence above is safe to send immediately
after `session.update`.

Saved-agent sessions use the deployed prompt, voice, product, languages,
knowledge, and compatible server-run tools. The greeting remains available,
but Realtime disables saved-agent silence check-ins. `transfer_call` and
`send_keypad_input` are offered only with the session's `call_events` (see
the top-level session options above).

### Use a saved agent

A saved [agent](/api-reference/agents) holds what every call shares: its
prompt, voice, product, languages, knowledge, and tools, with the versions
and test sets you manage in ThunderPhone. Select it with `session.prompt`, the
OpenAI reusable-prompt field, in the first `session.update`, and send what
changes per session alongside it:

```json
{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "prompt": {
      "id": "12",
      "variables": { "user_name": "Ada Park", "business": "Costco" }
    },
    "instructions": "Ada is a Costco member in Mountain View. Call the store and ask for today's opening hours.",
    "audio": {
      "input": { "format": { "type": "audio/pcm", "rate": 16000 } },
      "output": { "format": { "type": "audio/pcm", "rate": 16000 } }
    }
  }
}
```

- `prompt.id` is the agent ID, as a string or a number. `prompt.version` is
  accepted for compatibility and ignored: the agent's deployed configuration
  runs. Any other `prompt` shape, such as an OpenAI `pmpt_` id, is rejected
  with an `error` event.
- `instructions` is this session's brief, such as who the user is and what
  the call is for, up to 20,000 characters. It becomes the call's
  [context](/guides/call-variables#context): added after the agent's prompt
  for this call only, while the agent's own prompt still applies.
- `prompt.variables` fills `{{name}}` placeholders in the agent's prompt, the
  same way [call variables](/guides/call-variables) do for phone calls. Values
  are strings, numbers, booleans, or `null`, which uses the placeholder's
  `{{name|default}}` default. `session.config.variables` is accepted
  too; when both are sent, `prompt.variables` wins for a name in both.

That `session.update` starts the call, and `session.updated` confirms it.
Besides instructions and variables, a saved-agent session takes from the
session:

- audio formats, `binary_output`, and `live_transcripts`;
- the session options in `session.config` under the same names as an inline
  session: `telephony`, `outbound`, `ivr_mode`, `call_events`, and
  `placeholders` (the [top-level session options](#create-a-managed-realtime-session)
  of a managed session, with the same rules).
  `noise_reduction` `{"type": "near_field"}` means `telephony: false`, as
  for inline sessions;
- the language the call starts in: `session.config.primary_language`, or
  `language` in the connection URL, which wins. The agent speaks it with its
  voice for that language, as the top-level `language` option describes.

Everything else comes from the agent. A voice, `product`, another agent
setting, or an OpenAI field ThunderPhone does not use with a saved agent
(`tool_choice`, `turn_detection`, `transcription`, `speed`,
`output_modalities`, `model`) produces an `error` event with code
`unsupported_parameter` whose `param` names the field; the field is ignored
and the call starts on the agent's configuration. That holds for the update
that starts the saved agent; once it has started (an `?agent_id=` session
starts at connect), a later update that changes such a field gets an
`invalid_request_error` because the session's settings cannot change after it
starts. Tools are different: a
saved-agent session runs only the agent's own ThunderPhone-run tools, and
client-executed tools need an inline session, so a
`session.update` that sends tools (`session.tools` or `session.config.tools`)
with a saved agent is refused whole with an `unsupported_parameter` error:
it starts nothing, and none of its other fields (such as `binary_output`)
apply, also after the call has started. Values that ask for nothing, such as `"tools": []`,
`"tool_choice": "auto"`, or the defaults `session.updated` reports, are
accepted silently. If ThunderPhone rejects the update (for example, an
unknown agent ID), nothing starts and you can send a corrected one.

You can also put the agent ID in the connection URL:

```text
wss://api.thunderphone.com/v1/realtime?agent_id=12
```

A URL-selected agent starts as soon as the socket connects, before your first
event, so a `session.update` is not required. Instructions or variables sent
after it starts produce an `error` event and do not change the call. To pass
per-session input with `agent_id`, add `wait_for_session_update=1`:

```text
wss://api.thunderphone.com/v1/realtime?agent_id=12&wait_for_session_update=1
```

The agent then starts at your first accepted `session.update`, whose
instructions and variables apply as above; a `prompt.id` in it must match the
URL's or the update is rejected. Until then:

- Caller audio is held (up to 60 seconds of it, oldest dropped first) rather
  than starting the agent without your brief. As in every session, audio that
  arrives before the call is connected feeds the
  [live transcript](#live-transcripts) when it is on, but is not replayed to
  the agent, which would otherwise answer it late.
- Other events, such as `conversation.item.create` or `response.create`, are
  refused with an `error` event whose code is `session_not_started`.
- If no `session.update` starts the agent within 10 seconds of connecting,
  the server sends an `error` with code `session_update_timeout` and closes
  the socket with code 1008.

Set a URL-selected agent's wire audio before it starts with the optional
`input_audio_format`, `output_audio_format`, `input_rate`, and `output_rate`
query parameters. Formats accept `audio/pcmu`, `audio/pcma`, `g711_ulaw`,
`g711_alaw`, or `pcm16`; PCM rates accept `16000` or `24000` (G.711 is always
8000 Hz). For example:

```text
wss://api.thunderphone.com/v1/realtime?agent_id=12&input_audio_format=g711_ulaw&output_audio_format=pcm16&output_rate=24000
```

Add `call_events=1` to the query to receive [`call.*` events](#call-events)
and give the agent `transfer_call`, for a URL-selected agent that starts at
connect. Such a session starts inbound with default session options: the URL
carries no `telephony`, `outbound`, `ivr_mode` or `placeholders`, and its
session config cannot change once it has started. A saved-agent session that
needs any of those (an outbound call, with `send_keypad_input`, for example)
selects the agent in its first `session.update`, or connects with
`?agent_id=12&wait_for_session_update=1`, and puts them in that starting
update. Sessions that start at a `session.update` can opt in to events
through `session.config.call_events` too.

Prompt, voice, product, languages, knowledge, and compatible tools come from
the deployed saved agent. Realtime disables spoken silence check-ins, and
offers `transfer_call` and `send_keypad_input` only with `call_events`.

## Client events

Send client events as JSON text frames unless otherwise noted.

| Event | Fields | Behavior |
|-------|--------|----------|
| `session.update` | `session` | Configures the session using the nested shape above; flat compatibility fields are also accepted |
| `input_audio_buffer.append` | `audio` | Appends a base64-encoded mono pcm16 audio chunk |
| Raw binary frame | binary pcm16 | Appends audio without base64 encoding; this is a ThunderPhone extension |
| `input_audio_buffer.commit` | — | Acknowledged with `input_audio_buffer.committed`; turn detection remains automatic |
| `input_audio_buffer.clear` | — | Acknowledged with `input_audio_buffer.cleared`; turn detection remains automatic |
| `conversation.item.create` | `item` | Sends a caller utterance (`user`) or silent guidance (`system`/`developer`), or acknowledges a function call; message items are acknowledged with `conversation.item.added` then `conversation.item.done` using your item id |
| `conversation.item.truncate` | `item_id`, `content_index`, `audio_end_ms` | Acknowledged with `conversation.item.truncated` |
| `conversation.item.delete` | `item_id` | Acknowledged with `conversation.item.deleted` |
| `response.cancel` | `response_id` optional | Stops the in-progress response's remaining audio and closes it with status `cancelled`; errors with `response_cancel_not_active` when nothing is streaming |
| `response.create` | — | Triggers exactly one model response using the conversation so far; if a response is active, emits an `error` with code `conversation_already_has_active_response` and does not start another |

### Append audio

```json
{
  "type": "input_audio_buffer.append",
  "audio": "<base64-pcm16>"
}
```

Send audio at its natural pace rather than uploading an entire recording at
once. You can send each chunk as a raw binary frame instead; no session flag
is required for binary input.

### Send text guidance

Message items are appended to the conversation and never trigger a response by
themselves. Use `user` for a completed caller utterance and `system`, with
`developer` accepted as an alias, for silent guidance. A response begins either
from server turn detection on audio or from an explicit `response.create`.
Message items are acknowledged with `conversation.item.added` followed by
`conversation.item.done`; both echo the client-provided `item.id`, or a
generated id when it is absent. Text is not converted into caller audio.

```json
{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "user",
    "content": [
      { "type": "input_text", "text": "Ask whether they need anything else." }
    ]
  }
}
```

For silent guidance, set `"role": "system"` in the same message shape.
Assistant-role message injection is unsupported.

### Request a response

`response.create` may carry `response.metadata` (an object of your own keys);
the server echoes it on the `response.created` that answers the request, as
OpenAI does, so SDKs can match the reply they asked for.

Send `response.create` to trigger exactly one response using the conversation
so far. If a response is already in progress, the server emits an `error` event
with code `conversation_already_has_active_response` and does not start another.

After handling a custom function call, the client must send a
`function_call_output` item with the received `call_id`. The `output` can be a
JSON string or object. The default deadline is 30 seconds. If the deadline
expires, the conversation continues with an error result so the agent can
recover. Every function call names one of your declared tools and expects a
`function_call_output`; platform actions arrive as `call.*` events instead
(see below) and take no output. A `call_id` is at most 32 characters, OpenAI's
limit, so SDKs that enforce it pass it through unchanged. An accepted output is
acknowledged with
`conversation.item.added` and `conversation.item.done` carrying the item (and
your `id`, if you set one), as OpenAI does.

```json
{
  "type": "conversation.item.create",
  "item": {
    "type": "function_call_output",
    "call_id": "call_abc123",
    "output": "{\"status\":\"ok\"}"
  }
}
```

## Server events

Server events are JSON text frames. Each JSON event includes a unique
`event_id`.

| Event | Important fields | Description |
|-------|------------------|-------------|
| `session.created` | `session` | Sent when the WebSocket opens with the session id and defaults |
| `session.updated` | `session` | Confirms the current session configuration |
| `conversation.item.added` | `item` | A conversation item (user or assistant message, or function call) was added |
| `conversation.item.done` | `item` | A conversation item reached its final state |
| `conversation.item.input_audio_transcription.delta` | `item_id`, `delta` | Caller transcript text. By default sent once per turn with `delta` carrying the whole transcript; with `live_transcripts` on, a stream of word fragments while the caller speaks — see [Caller transcripts](#caller-transcripts) |
| `conversation.item.input_audio_transcription.completed` | `item_id`, `transcript`, `audio` | The settled caller transcript, plus a signed link to the caller's audio |
| `conversation.item.truncated` | `item_id`, `audio_end_ms` | Acknowledges `conversation.item.truncate` |
| `conversation.item.deleted` | `item_id` | Acknowledges `conversation.item.delete` |
| `response.created` | `response` | Starts an agent response |
| `rate_limits.updated` | `rate_limits` | Emitted after each `response.created` |
| `response.output_item.added` | `response_id`, `item` | Adds an audio message or function call to the response |
| `response.content_part.added` | `response_id`, `item_id`, `part` | Opens the audio content part of a message item |
| `response.output_audio.delta` | `response_id`, `item_id`, `delta` | Base64-encoded output audio; replaced by raw binary frames when binary output is enabled |
| `response.output_audio_transcript.delta` | `response_id`, `item_id`, `delta` | Agent transcript segment |
| `response.output_audio.done` | `response_id`, `item_id` | Output audio for the item is complete |
| `response.output_audio_transcript.done` | `response_id`, `item_id`, `transcript` | Final agent transcript for the response |
| `response.content_part.done` | `response_id`, `item_id`, `part` | Closes the audio content part with the final transcript |
| `response.function_call_arguments.delta` | `call_id`, `delta` | Incremental JSON arguments for a function call |
| `response.function_call_arguments.done` | `call_id`, `arguments` | Complete JSON arguments for a function call |
| `response.output_item.done` | `response_id`, `item` | Completes an audio message or function-call item |
| `response.done` | `response` | Completes the response |
| `input_audio_buffer.speech_started` | `audio_start_ms`, `item_id` | The server detected the start of caller speech; `item_id` is a stable advisory id for the speech interval and may not match the later history item id |
| `input_audio_buffer.speech_stopped` | `audio_end_ms`, `item_id` | The server detected the end of caller speech; `item_id` is a stable advisory id for the speech interval and may not match the later history item id |
| `input_audio_buffer.committed` | `item_id`, `previous_item_id` | The caller utterance was committed (also acknowledges a manual `commit`) |
| `input_audio_buffer.cleared` | — | Acknowledges `input_audio_buffer.clear` |
| `error` | `error.type`, `error.code`, `error.message`, `error.param`, `error.event_id` | Reports an authentication, validation, or server error. `error.type` says whose fault it is (`invalid_request_error` means do not retry unchanged); `error.code` can be more specific, such as `invalid_value` or `unsupported_parameter`. When the error refuses one of your events, `error.event_id` is that event's `event_id` and `error.param` names the refused field, such as `session.config.product` |

## Caller transcripts

A caller's transcript improves as the turn proceeds — a later pass can
rewrite words an earlier one produced. ThunderPhone therefore does not
stream partial caller text by default (opt in with
[`live_transcripts`](#live-transcripts)). Each caller turn is announced
**once**, when its transcript has settled:

```text
input_audio_buffer.committed
conversation.item.added
conversation.item.input_audio_transcription.delta
conversation.item.input_audio_transcription.completed
conversation.item.done
```

Two consequences worth designing around:

- **The single `delta` carries the entire transcript**, identical to the
  `completed` transcript. Concatenating every delta for an item yields
  exactly the final text.
- **The turn is announced once the agent has acted on it** — begun replying,
  pressed keypad digits, or called a tool — because that is the earliest
  point the text is settled. Use `previous_item_id` to reconstruct
  conversation order rather than arrival order.

### Transcript finality

The text in `completed` matches the durable per-call record (the same text
the dashboard and `GET /v1/calls/{call_id}/history` show) for every caller
turn that finished before the call ended. When the call ends normally — the
agent hangs up, or the far end does — the session reconciles against the
final record before `call.ended`, so a turn is never left unannounced.

Two cases fall outside that. A turn still in progress when the call ends has
no settled text yet: its words arrive as live deltas (when enabled) and its
final text exists only in the durable record. And if the call is torn down
abnormally — the media session drops rather than the agent or the far end
hanging up — there is no final record to reconcile against, so the last
turns are released with the most recent text the session had, which may be
superseded in the durable record.

In both cases the durable record is authoritative and reachable with the
`call_id` on `session.updated`. A client that must not miss a correction
should reconcile against `GET /v1/calls/{call_id}/history` after the call;
one that treats the WebSocket as the record of truth will be right on every
normally-ended call.

The platform `call_id` for fetching that record appears on
`session.updated` (`session.call_id`) and on `call.ended`.

### Live transcripts

Set `session.live_transcripts: true` to also receive caller words **while the
caller is speaking**. A separate streaming transcription runs on the caller
audio and its output is put on the wire immediately; the settled transcript
described above still arrives and is still the text of record. Per caller
turn the sequence becomes:

```text
input_audio_buffer.committed
conversation.item.added                                  (status: in_progress)
conversation.item.input_audio_transcription.delta        (repeated, word fragments)
conversation.item.input_audio_transcription.completed    (the settled transcript)
conversation.item.done
```

Rules for a client:

- **Deltas are genuine fragments.** Concatenate the deltas of an item to
  render the live caption. They begin roughly a second behind the caller's
  voice, before `input_audio_buffer.speech_started` in some cases, and
  before the agent has replied.
- **`completed` replaces the concatenated deltas, and it is terminal.** It
  carries the settled transcript, which is generally better than the live
  text and can differ from it. Show that text and discard the fragments. An
  item receives exactly one `completed`, and never a `delta` after it;
  `conversation.item.done` closes the item.
- **The item is opened before its place in the conversation is certain.**
  Words are streamed as soon as they are heard, so at a turn boundary (a
  keypad press, the caller resuming right as the agent replies) the last
  words of one turn can briefly show on the previous item until that item's
  `completed` replaces its text. Anchor each item to its first delta's
  timestamp; the settled text always lands on the right item.
- Items are always closed. If a call ends before a live item's transcript
  settles, its `completed` carries the live text.

Live transcripts are a WebSocket-only addition. The extra transcription is
billed as part of hearing the caller (see [Pricing](/guides/pricing)).
They are off by default. Turn them on with `session.live_transcripts: true`
in any `session.update`, including the one that starts the call or, for a
saved agent that starts at connect, a later one:

```json
{ "type": "session.update", "session": { "live_transcripts": true } }
```

Once enabled, the extra transcription is billed for the whole session; a later
`session.update` with `live_transcripts: false` stops the stream but does not
remove the charge. If the server cannot provide live transcripts at any
point, the session continues with settled transcripts only and a non-fatal
`error` event says so.

### One `completed` per item

Each caller item receives exactly one
`conversation.item.input_audio_transcription.completed`, and never a
`delta` after it. Persist by `item_id` and treat `completed` as the final
text. In the rare case a better transcript is produced after an item was
announced, it is kept in the call's history and dashboard but is not sent
again over the WebSocket.

### Caller audio

`conversation.item.input_audio_transcription.completed` carries an `audio`
object with a pre-signed link to what the caller said for that turn:

```json
{
  "url": "https://...",
  "expires_at": "2026-08-12T19:04:00Z",
  "format": "audio/wav"
}
```

The turn's duration is already on the same event as `usage.seconds`; it is
not repeated here.

The recording is WAV, 16-bit PCM, mono, 16 kHz, and covers the whole turn.
It is the audio as received on the call, not a noise-suppressed version.
Issue a plain `GET` — the URL is already signed, so do not send an
`Authorization` header. Links expire 24 hours after they are issued and are
not reissued, so download and store the bytes rather than the URL.

The `audio` object arrives once, on the item's single `completed`, so store
it on sight.

The `audio` field is **omitted** — not null — whenever no recording of the
turn exists, including when call recording is disabled for your
organization. Treat it as optional on every item. Whether a turn has a
recording is decided once, so an item that arrives without `audio` will not
gain one later.

It rides the transcription event rather than the item's content part
because the GA schema types a content part's `audio` as a base64 string, so
an object there would fail strict validation in the official SDK. It is an
extra top-level key, which GA models accept because they permit unknown
fields.

Note that ThunderPhone's [call events](#call-events) are a different kind of
addition: they are new event *types*, not extra keys, so a validator that
rejects unknown event types will not recognise them. Route on `type` and
ignore what you do not handle.

### Conformance notes

Item ids are opaque and carry no structure — do not parse them or derive
ordering from them. Use `previous_item_id` for conversation order and
`item_id` for identity.

Caller items are announced once their transcript settles, which is after the
agent has begun replying, so arrival order is not conversation order (with
`live_transcripts` on they open as soon as words are heard instead).
`previous_item_id` always reflects conversation order: an agent item names
the caller turn it answers, even though that turn is announced moments
later.

One consequence to build for: **`previous_item_id` can name an item you have
not received yet.** It arrives within the next few events. Accumulate items
and resolve the order afterwards rather than assuming a predecessor is
already present when an item arrives.

Usage counters on `response.done` are always zero. Calls are metered per
minute rather than per token, so ThunderPhone reports honest zeros instead
of fabricated token counts. The `usage` on transcription events is real and
reports the caller audio duration.

ThunderPhone supports PCM at 16000 Hz as an extension. The OpenAI GA schema
pins `audio/pcm` to 24000 Hz, so strict validators of `session.created` and
`session.updated` should also allow rate 16000.

The normal audio response sequence is:

```text
response.created
rate_limits.updated
response.output_item.added
conversation.item.added
response.content_part.added
response.output_audio.delta (repeated)
response.output_audio_transcript.delta (repeated)
response.output_audio.done
response.output_audio_transcript.done
response.content_part.done
response.output_item.done
conversation.item.done
response.done
```

Audio and transcript deltas can be interleaved within the response.

## Function calls

Function calls arrive as `function_call` output items and always name one of
the tools your client declared. Read the function name and `call_id` from
`response.output_item.added`, accumulate argument deltas, and act after
`response.function_call_arguments.done`. Platform actions are never function
calls — they arrive as [call events](#call-events).

### Call capabilities

Every session's agent can end the call and can deliberately stay silent for a
turn while the far side is still talking. Inline sessions with `outbound: true`
can also wait out hold queues. Inline outbound sessions with `call_events`
enabled can press keypad digits, and inline sessions with `call_events` can
request a cold transfer for your client to execute from the `call.transfer`
instruction. Saved-agent sessions with `call_events` get the same: a cold
transfer, plus keypad digits when outbound, for your client to carry out from
the `call.*` events. Capabilities
that instruct your client are granted only when the event channel exists to
carry the instruction.

To limit where an inline session can transfer, send `transfer_destinations`
in the config: up to 50 `{name, number}` entries, validated like an agent's
[transfer numbers](/api-reference/agents#transfer-numbers). The agent then
transfers by name, sees only the names, and cannot transfer anywhere else; a
`call.transfer` event carries both the entry's number and its `destination`
name. A transfer to anything else is refused and the conversation continues,
and so is a transfer to a `sip:` entry: Realtime sessions can't transfer to
SIP addresses. An empty list removes the transfer capability. Without `transfer_destinations`,
the agent chooses the number itself and `call.transfer` carries only
`phone_number`.

A set of function names is reserved for the platform and rejected in your
`tools` with a validation error: `end_call`, `transfer_call`,
`send_keypad_input`, `no_response`, `wait_on_hold`, `search_knowledge_base`,
`play_sound`, `send_email`, `send_sms`, `calculate`, `release_probe_echo`,
`speak_uninterruptible`.

### Call events

Platform call actions and state changes are delivered as dedicated events in
the `call.*` namespace — a ThunderPhone extension to the realtime event set.
They are an explicit opt-in: set `call_events: true` in the session config to
receive them, or add `call_events=1` to the URL of a saved agent that starts
at connect (its session config can no longer change). They are notifications: nothing is sent in reply, and there is
no `call_id` or output. Handle every type below in your event loop — clients
ported from other realtime APIs often switch on known event types and would
otherwise drop them.

| Event | Payload | Meaning |
|-------|---------|---------|
| `call.keypad` | `{"digits":"2#"}` | Send these keypad digits out-of-band through your telephony stack now |
| `call.transfer` | `{"phone_number":"+15551234567", "destination":"Billing"?}` | Transfer your telephony leg to this number now; a `call.ended` with reason `transfer` follows. `destination` is the entry name, present only when the session has `transfer_destinations` |
| `call.ended` | `{"reason":"agent_hangup" \| "remote_hangup" \| "transfer" \| "error", "call_id":"…"}` | The call is over; the server closes the WebSocket shortly after this event, so drive your teardown from it. `call_id` addresses the durable per-call record (`GET /v1/calls/{call_id}/history`) |
| `call.hold.started` / `call.hold.ended` | — | The agent is waiting out a hold queue / the hold ended and normal conversation resumed |
| `call.speech_ignored` | `{"reason":"no_response" \| "hold" \| "superseded" \| "response_create_dropped", "detail":"…"?}` | The far side said something and the agent deliberately produced no response — it judged the audio as an automated system still talking (`no_response`), hold content while waiting for a human (`hold`), or newer audio made its drafted response stale and it was dropped (`superseded`). `response_create_dropped` means a `response.create` you sent was discarded because the agent was busy; `detail` says why (`assistant_speaking`, `caller_speaking`, `turn_active`, `hold`, `not_ready`, or `queued_then_blocked`) — re-issue the trigger when the blocking state clears (for example after `response.done`) |

```json
{ "type": "call.keypad", "event_id": "event_1a2b", "digits": "2" }
```

```json
{ "type": "call.ended", "event_id": "event_3c4d", "reason": "agent_hangup" }
```

### Outbound calls

Set `outbound: true` in the session config of the update that starts the
session (a saved agent named in the URL needs `wait_for_session_update=1`)
when the session is an outbound call — the agent dialed out, so the far side may be an automated menu, a hold
queue, voicemail, or a screener rather than a person. This enables the
engine's outbound call handling: the agent recognizes and navigates automated
systems reliably, responds immediately when a human picks up so they are not
met with dead air, and applies cost-saving measures that keep the price down
while the call is working through menus, waiting on hold, or handling
voicemail. It is off by default; sessions without it treat the far side as a
human caller. Menu navigation and hold handling need no further
configuration — steer them through your instructions:

```json
{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "instructions": "Call the pharmacy, navigate the phone menu, and ask whether the prescription is ready.",
    "audio": {
      "output": { "voice": "olivia" }
    },
    "config": {
      "outbound": true,
      "call_events": true,
      "tools": [
        {
          "type": "function",
          "function": {
            "name": "report_status",
            "description": "Report the prescription status back to the app.",
            "parameters": {
              "type": "object",
              "properties": { "status": { "type": "string" } },
              "required": ["status"]
            }
          }
        }
      ]
    }
  }
}
```

`ivr_mode` sets how an outbound session handles automated phone menus (IVRs):

| Value | Behavior |
|-------|----------|
| `auto` (default) | The agent paces itself for a phone menu until it hears a person, then talks to that person normally for the rest of the call. The short pickup greeting ("Hello. Can you hear me?") plays only when a person picks up after menu or hold audio, and only if the agent has not spoken since. |
| `on` | The whole call is handled as a phone menu: the agent waits for complete menu prompts before answering, and it plays the pickup greeting as soon as it detects a person. This was the behavior of every outbound session before `ivr_mode` existed. |
| `off` | No phone-menu mode: the agent replies to whoever answers as it would to a person, and the pickup greeting never plays. Hold waiting and, with `call_events`, keypad input stay available. |

`ivr_mode` needs `outbound: true`; setting it to `auto` or `on` without that is
rejected with a validation error.

A standalone function call follows this sequence:

```text
response.created
response.output_item.added
response.function_call_arguments.delta
response.function_call_arguments.done
response.output_item.done
response.done
```

## Using the official OpenAI SDK

Existing OpenAI Realtime integrations work by changing only the WebSocket
base URL and the API key. Pass the base ending at `/v1` — the SDK appends
`/realtime` itself, mirroring `wss://api.openai.com/v1`:

For prerequisites, configuration choices, and an end-to-end test checklist,
see [Use ThunderPhone with OpenAI Realtime
clients](/guides/use-with-openai-realtime).

```python
import os

from openai import AsyncOpenAI

client = AsyncOpenAI(
    api_key=os.environ["THUNDERPHONE_API_KEY"],
    websocket_base_url="wss://api.thunderphone.com/v1",
)

async with client.realtime.connect(model="thunderphone-realtime") as connection:
    await connection.session.update(session={
        "type": "realtime",
        "instructions": "Listen to the caller and help them complete the call.",
    })
    async for event in connection:
        ...
```

The `model` argument is echoed back but does not change behavior; the agent
configuration comes from the session instructions or a saved agent.

## Minimal Python client

Install `websockets`, set `THUNDERPHONE_API_KEY`, and provide an uncompressed
mono pcm16 WAV file sampled at 16000 Hz:

```bash
pip install websockets
export THUNDERPHONE_API_KEY=sk_live_YOUR_API_KEY
python realtime_client.py caller.wav
```

```python
import asyncio
import base64
import json
import os
import sys
import wave

import websockets

URL = "wss://api.thunderphone.com/v1/realtime"
RATE = 16_000
CHUNK_MS = 100


def read_wav(path):
    with wave.open(path, "rb") as wav:
        if (wav.getnchannels(), wav.getsampwidth(), wav.getframerate()) != (1, 2, RATE):
            raise ValueError("WAV must be mono pcm16 at 16000 Hz")
        return wav.readframes(wav.getnframes())


async def send_audio(ws, pcm):
    chunk_size = RATE * 2 * CHUNK_MS // 1000
    loop = asyncio.get_running_loop()
    deadline = loop.time()
    for offset in range(0, len(pcm), chunk_size):
        chunk = pcm[offset : offset + chunk_size]
        await ws.send(json.dumps({
            "type": "input_audio_buffer.append",
            "audio": base64.b64encode(chunk).decode("ascii"),
        }))
        deadline += CHUNK_MS / 1000
        await asyncio.sleep(max(0, deadline - loop.time()))


async def receive(ws):
    async for message in ws:
        if isinstance(message, bytes):
            continue  # output audio, when binary output is enabled
        event = json.loads(message)
        event_type = event["type"]
        if event_type == "conversation.item.input_audio_transcription.completed":
            print("caller:", event.get("transcript", ""))
        elif event_type == "response.output_audio_transcript.delta":
            print(event.get("delta", ""), end="", flush=True)
        elif event_type == "response.output_audio_transcript.done":
            print()
        elif event_type == "response.output_item.done":
            item = event.get("item", {})
            if item.get("type") == "function_call":
                arguments = json.loads(item.get("arguments") or "{}")
                print("function:", item["name"], arguments)
                # Run your declared tool here and return its output.
        elif event_type == "error":
            print("error:", event["error"], file=sys.stderr)


async def main(path):
    headers = {"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"}
    async with websockets.connect(URL, additional_headers=headers) as ws:
        await ws.send(json.dumps({
            "type": "session.update",
            "session": {
                "type": "realtime",
                "instructions": "Listen carefully and help complete the call.",
                "audio": {
                    "input": {"format": {"type": "audio/pcm", "rate": RATE}},
                    "output": {
                        "format": {"type": "audio/pcm", "rate": RATE},
                        "voice": "olivia",
                    },
                },

            },
        }))
        while json.loads(await ws.recv())["type"] != "session.updated":
            pass
        await asyncio.gather(send_audio(ws, read_wav(path)), receive(ws))


asyncio.run(main(sys.argv[1]))
```

## Protocol notes

- Turn detection uses server-side voice activity detection and is always on.
  Clients do not need to commit or clear the input audio buffer.
- Transcript events are emitted as per-utterance segments, not token-by-token
  deltas. Use the `completed` and `done` events as final text.
- Unknown or unsupported client event types produce an `error` event without
  closing the WebSocket. The client can correct the request and continue.

<!-- en: api-reference/mic-sessions -->
---
title: "Mic Sessions"
description: "Start browser-audio sessions that let you talk to an agent in real time from a web page — the same path the dashboard uses for agent testing and live demos."
---

Mic sessions let you talk to an agent directly from a web browser using
your microphone — no phone number required. ThunderPhone creates a
LiveKit room and returns a join token; your front-end uses the
LiveKit Web SDK to publish audio. This endpoint is typically used for
agent iteration and demos.

## Endpoint

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/mic-session` | Create a mic session against an agent |

## Create a session

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/mic-session \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": 12}'
```

```python Python
session = requests.post(
    "https://api.thunderphone.com/v1/mic-session",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={"agent_id": 12},
).json()
```

```javascript Node.js
const session = await fetch("https://api.thunderphone.com/v1/mic-session", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.THUNDERPHONE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ agent_id: 12 }),
}).then((r) => r.json());
```
</CodeGroup>

### Request fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `agent_id` | integer | yes | Agent id in this org |

### Response

```json
{
  "call_id": 987654321,
  "token": "<livekit-jwt>",
  "room_name": "mic-987654321",
  "server_url": "wss://livekit.thunderphone.com"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `call_id` | integer | Call id — the session appears in [Call history](/api-reference/calls) with `direction="test"` |
| `token` | string | Short-lived LiveKit JWT |
| `room_name` | string | LiveKit room |
| `server_url` | string | LiveKit WebSocket URL — pass to the Web SDK |

### Connecting from the browser

Use the LiveKit Web SDK to join the room with the returned token. The
agent joins the room from Core's side and you publish your microphone
as the local participant.

```javascript
import { Room, RoomEvent } from "livekit-client";

const room = new Room();
await room.connect(session.server_url, session.token);
await room.localParticipant.setMicrophoneEnabled(true);

room.on(RoomEvent.TrackSubscribed, (track) => {
  if (track.kind === "audio") track.attach(document.body);
});
```

### Errors

| Status | Condition |
|--------|-----------|
| `400` | `agent_id is required` |
| `402` | Insufficient balance |
| `404` | Agent not found |
| `429` | `concurrent_call_limit_reached`: the organization is at its [concurrent-call limit](/api-reference/introduction#call-limits); retry after `Retry-After` seconds |
| `502` | LiveKit room creation failed |

<Note>
  Mic sessions count as calls for billing purposes. The session is
  billed as a regular voice call using the agent's `product` tier.
</Note>

---

## Related

<CardGroup cols={2}>
  <Card title="Agents" icon="robot" href="/api-reference/agents">
    Configure the agent you'll talk to.
  </Card>
  <Card title="Calls" icon="phone" href="/api-reference/calls">
    Inspect mic-session call logs and transcripts.
  </Card>
  <Card title="Web Widget" icon="window-maximize" href="/widget/overview">
    Embed a production-ready mic widget on your own site.
  </Card>
</CardGroup>

<!-- en: api-reference/talk-links -->
---
title: "Talk Links"
description: "Create a single-use link that opens a browser page where a person talks to an agent's current draft, the same conversation as the dashboard's Talk button."
---

A talk link is a URL you can hand to a person: they open it, click **Start
talking**, and talk to the agent's current draft from their browser. They
need no ThunderPhone account. It is the same conversation as the dashboard's
**Talk** button and the [mic session](/api-reference/mic-sessions) endpoint:
the draft configuration, recorded and billed like any test call.

Coding agents use it to ask someone to try a change: edit the draft, create
a link, and send it with a note about what to listen for.

Each link works once and expires after 30 minutes unless you set another
expiry (at most 120 minutes). The page shows only the agent's name.

Creating a link is part of the agent iteration toolkit, which is enabled per
organization while it is in beta. A link already created keeps working
either way.

## Endpoints

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| `POST` | `/v1/agents/{agent_id}/talk-links` | API key | Create a talk link |
| `GET` | `/v1/talk-links/{token}` | none | Check a link before connecting |
| `POST` | `/v1/talk-links/{token}/session` | none | Start the conversation (works once) |

The two `{token}` endpoints are what the talk page calls. You only need them
to build your own page; the token in the URL is their credential.

## Create a talk link

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/agents/12/talk-links \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expires_in_minutes": 30, "note": "shorter greeting"}'
```

```python Python
link = requests.post(
    "https://api.thunderphone.com/v1/agents/12/talk-links",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={"expires_in_minutes": 30, "note": "shorter greeting"},
).json()
print(link["url"])
```

```javascript Node.js
const link = await fetch("https://api.thunderphone.com/v1/agents/12/talk-links", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.THUNDERPHONE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ expires_in_minutes: 30, note: "shorter greeting" }),
}).then((r) => r.json());
```
</CodeGroup>

### Request fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `variant_id` | integer | no | Talk to one [A/B variant](/api-reference/split-testing) of the draft instead of the plain draft |
| `language` | string | no | Language code for the conversation, such as `es`. Defaults to the agent's primary language |
| `expires_in_minutes` | integer | no | Minutes until an unused link stops working. Default `30`, between `1` and `120` |
| `note` | string | no | Your own label for the link, up to 500 characters. Never shown on the talk page |

### Response

`201 Created`

```json
{
  "url": "https://app.thunderphone.com/talk/Vh3k…",
  "expires_at": "2026-10-19T18:30:00Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `url` | string | The page to send. It contains the link's token; treat it like a password until it is used |
| `expires_at` | string | When an unused link stops working (ISO 8601) |

ThunderPhone stores only a hash of the token, so a lost URL cannot be shown
again. Create another link instead.

### Errors

| Status | Condition |
|--------|-----------|
| `400` | `expires_in_minutes` outside 1–120, an unknown `language`, or a `variant_id` that is not one of this agent's variants |
| `403` | `feature_not_enabled`: the organization does not have the agent iteration toolkit, which is enabled per organization while it is in beta. The body's `next_step` says what to do |
| `404` | Agent not found in this organization |

## Check a link

`GET /v1/talk-links/{token}` needs no authentication. It returns what the
talk page shows before the person connects, and nothing else about your
organization.

```json
{
  "agent_name": "Front Desk",
  "expires_at": "2026-10-19T18:30:00Z",
  "used": false,
  "recorded": true
}
```

`recorded` says whether the conversation will be recorded, from the agent
draft's recording setting (the session runs the draft).

`404` with `code: "talk_link_not_found"` means the token is unknown or the
link's agent has moved to another organization.

## Start the conversation

`POST /v1/talk-links/{token}/session` needs no authentication and no body.
The first successful request uses the link and starts a browser session with
the agent's draft at that moment, exactly like
[`POST /v1/mic-session`](/api-reference/mic-sessions):

```json
{
  "call_id": 987654321,
  "token": "<livekit-jwt>",
  "room_name": "mic-987654321",
  "server_url": "wss://livekit.thunderphone.com",
  "agent_name": "Front Desk"
}
```

Join the room with the LiveKit Web SDK as described under
[Connecting from the browser](/api-reference/mic-sessions#connecting-from-the-browser).
The conversation appears in [call history](/api-reference/calls) with
`direction="test"`.

### Errors

| Status | Condition |
|--------|-----------|
| `400` | The link's `language` can no longer be used with the agent's current voice. The link stays unused |
| `402` | The organization's balance or test-call budget cannot cover a call. The link stays unused |
| `404` | `talk_link_not_found`: unknown token, or the link's agent has moved to another organization |
| `410` | `talk_link_used`: the link was already used. `talk_link_expired`: it expired before use, or its agent was moved to another organization and back |
| `422` | The agent's voice cannot be used, for example a custom voice that was deleted. The link stays unused |
| `429` | Too many requests for this link or from this address, or the organization is at its [concurrent-call limit](/api-reference/introduction#call-limits). The link stays unused |
| `503` | Voice infrastructure unavailable. The link stays unused |

<Note>
  A talk-link conversation is billed to the organization that created the
  link, exactly like a Talk test call, and is recorded according to the
  agent's recording setting. Anyone holding an unused link can start one
  conversation, so send it only to the person who should talk to the agent.
</Note>

## MCP

The [ThunderPhone MCP server](/guides/thunderphone-mcp-server) exposes this as
`create_talk_link`, so a coding agent can create the link and hand you the URL.

---

## Related

<CardGroup cols={2}>
  <Card title="Mic Sessions" icon="microphone" href="/api-reference/mic-sessions">
    Start the same session from your own page with an API key.
  </Card>
  <Card title="Agents" icon="robot" href="/api-reference/agents">
    Edit the draft the link talks to.
  </Card>
</CardGroup>

<!-- en: api-reference/campaigns -->
---
title: "Campaigns"
description: "Run outbound calling campaigns: upload contacts, set calling windows, and track outcomes."
---

A **campaign** dials a list of contacts with one of your agents, from
one or more of your outbound-capable numbers (its
[number pool](#number-pools-and-pacing)), inside a daily calling window in
the timezone you pick. The runner respects a per-campaign concurrency
cap and your organization's [call limits](/api-reference/introduction#call-limits)
(a contact that meets a limit waits for a later pass without using an
attempt), and retries contacts whose calls ended in outcomes you selected
(`no_answer`, `voicemail`, `failed`, …) with a configurable backoff,
up to `max_attempts` per contact. See
[calling hours and retry limits](#calling-hours-and-retry-limits) for
the timezone default, each contact's local time, the window warnings,
spread retries, double dial, and the retry bounds.
A campaign can also [text each contact before the first
call](#text-before-calling).

Lifecycle: `draft` → (`scheduled` →) `running` → `completed`, with
`paused` and `cancelled` reachable via [actions](#campaign-actions).
Contacts are only editable while the campaign is a `draft`.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/campaigns` | List campaigns |
| `POST` | `/v1/campaigns` | Create a campaign (starts in `draft`) |
| `GET` | `/v1/campaigns/{campaign_id}` | Retrieve a campaign incl. contacts |
| `PATCH` | `/v1/campaigns/{campaign_id}` | Update a `draft`/`scheduled`/`paused` campaign |
| `DELETE` | `/v1/campaigns/{campaign_id}` | Delete a campaign |
| `POST` | `/v1/campaigns/{campaign_id}/contacts` | Add contacts (CSV upload or JSON) |
| `GET` | `/v1/campaigns/{campaign_id}/stats` | Progress counters + recent calls |
| `POST` | `/v1/campaigns/{campaign_id}/{action}` | `start`, `pause`, or `cancel` |

`{campaign_id}` is the campaign's **UUID** (`public_id`).

## Campaign object

```json
{
  "public_id": "3f6b2c9e-…",
  "name": "May win-back",
  "agent": 12,
  "agent_name": "Customer Support Agent",
  "from_number": "+15551234567",
  "from_numbers": ["+15551234567", "+12125550143"],
  "max_calls_per_number_per_day": 75,
  "status": "draft",
  "blocked_reason": null,
  "blocked_detail": null,
  "timezone": "America/Los_Angeles",
  "window_timezone_mode": "contact",
  "daily_window_start": "09:00:00",
  "daily_window_end": "17:00:00",
  "start_at": null,
  "end_at": null,
  "max_concurrent_calls": 3,
  "max_attempts": 2,
  "retry_backoff_minutes": 60,
  "retry_strategy": "spread",
  "retry_on": ["no_answer", "voicemail", "failed"],
  "double_dial": false,
  "total_count": 0,
  "completed_count": 0,
  "failed_count": 0,
  "in_progress_count": 0,
  "pre_call_sms_enabled": false,
  "pre_call_sms_from_number": "",
  "pre_call_sms_template": "Hi {{first_name}}, this is {{org_name}}. We'll call you in a few minutes from {{call_from_number}}. Reply STOP to opt out of texts.",
  "pre_call_sms_lead_minutes": 2,
  "warnings": [],
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `public_id` | UUID | Campaign id (used in every path) |
| `name` | string | 1–255 chars |
| `agent` | integer | The [Agent](/api-reference/agents) that speaks on every call (writable) |
| `agent_name` | string | Read-only convenience |
| `from_number` | string | The first number of the pool. Sending only `from_number` makes a pool of that one number. ThunderPhone numbers are accepted after outbound calling is approved for your organization |
| `from_numbers` | array of string | The [number pool](#number-pools-and-pacing): 1–50 outbound-capable E.164 numbers in your org, in order. Duplicates are dropped. Send this or `from_number`; `from_number` is always `from_numbers[0]` |
| `max_calls_per_number_per_day` | integer \| null | Outbound calls each pool number may place in a rolling 24 hours, 1–500. Default `75` for new campaigns; `null` means no per-number limit (campaigns created before pools have `null`). See [number pools and pacing](#number-pools-and-pacing) |
| `status` | string | `draft`, `scheduled`, `running`, `paused`, `completed`, `cancelled` (read-only — change via actions) |
| `blocked_reason` | string \| null | Why a `running` campaign is holding contacts back right now (read-only): `per_number_daily_limit` (every pool number reached its limit) or `org_daily_limit` (today's limit for ThunderPhone numbers is used up). `null` while it can dial and whenever it is not running |
| `blocked_detail` | string \| null | A sentence explaining `blocked_reason` (read-only) |
| `timezone` | string | IANA timezone the daily window is evaluated in, and with `window_timezone_mode` `contact` the fallback for contacts without a US or Canadian area code. When omitted on create, it defaults to the first pool number's zone (its area code in the US and Canada, its country elsewhere), else `UTC` |
| `window_timezone_mode` | string | `contact`: the daily window runs in each contact's local time, from the contact's US or Canadian area code. `campaign`: it runs in `timezone` for every contact. Default `contact` for new campaigns; campaigns created before this setting are `campaign` |
| `daily_window_start`, `daily_window_end` | time | Local calling window, e.g. `"09:00:00"`–`"17:00:00"`. Calls start from `daily_window_start` up to, not at, `daily_window_end`. On create, send both or neither; neither means `"09:00:00"`–`"17:00:00"`. An end earlier than the start makes an overnight window (`"22:00:00"`–`"02:00:00"` dials from 10pm until 2am the next day) |
| `start_at`, `end_at` | timestamp \| null | Optional overall schedule bounds. `end_at` must be after `start_at` |
| `max_concurrent_calls` | integer | 1–10, default 3 |
| `max_attempts` | integer | 1–10, default 2 — total tries per contact. The upper bound is per organization and staff can raise it |
| `retry_backoff_minutes` | integer | Delay before a retryable contact is attempted again. At least 30, default 60. Staff can lower the minimum per organization |
| `retry_strategy` | string | `spread`: each retry goes to a later day and a different part of the contact's day, at least `retry_backoff_minutes` after the last call. `fixed`: exactly `retry_backoff_minutes` later. Default `spread` for new campaigns; campaigns created before this setting are `fixed`. See [spread retries](#spread-retries-and-double-dial) |
| `retry_on` | array of string | Call outcomes that trigger a retry. Default `["no_answer", "voicemail", "failed"]` |
| `double_dial` | boolean | After a call rings out unanswered, call once more from the same number 30–60 seconds later. The redial is not an attempt. Default `false` |
| `total_count`, `completed_count`, `failed_count`, `in_progress_count` | integer | Progress counters (read-only) |
| `pre_call_sms_enabled` | boolean | Text each contact before their first call. Default `false`. See [Text before calling](#text-before-calling) |
| `pre_call_sms_from_number` | string | E.164 number the text is sent from: an SMS-capable number on your own connected Twilio or Telnyx account. Required when `pre_call_sms_enabled` is `true` |
| `pre_call_sms_template` | string | The text, up to 1600 characters, with `{{variable}}` placeholders. Blank means the default text, which is what the field then returns |
| `pre_call_sms_lead_minutes` | integer | Minutes between the text and the call, 1–60, default 2. With texting on, the daily window must be at least this plus 12 minutes, or the save returns `400`. A texted contact holds its call slot until called, so long leads slow the campaign |
| `warnings` | array of object | Saved settings worth a second look, each `{code, field, detail}` (read-only). `outside_calling_hours` for a window that starts before 08:00 (`field` is `daily_window_start`) or ends after 21:00 or crosses midnight (`daily_window_end`), one entry per edge. `window_crosses_midnight` for an overnight window and `empty_window` for equal start and end, which does not dial. `pre_call_sms_sender_not_ready` (`field` is `pre_call_sms_from_number`) when the text number cannot send yet, such as a US number waiting on A2P 10DLC approval; `detail` says what is missing, and contacts are called without a text until it is fixed. Empty when there is nothing to flag |

---

## Create a campaign

<Note>
  For organizations created on or after 2026-08-03, campaign creation
  and the `start` action require the organization's one-time
  [outbound TCPA
  confirmation](/api-reference/outbound-calls#outbound-tcpa-confirmation).
  Without it they return `403` with
  `"code": "outbound_tcpa_confirmation_required"`. Older organizations
  are fully exempt. `pause`/`cancel` and all reads are unaffected, and
  already-running campaigns are never interrupted.
</Note>

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/campaigns \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "May win-back",
    "agent": 12,
    "from_numbers": ["+15551234567", "+12125550143"],
    "max_calls_per_number_per_day": 75,
    "timezone": "America/Los_Angeles",
    "daily_window_start": "09:00",
    "daily_window_end": "17:00",
    "max_concurrent_calls": 3,
    "max_attempts": 2,
    "retry_on": ["no_answer", "voicemail"]
  }'
```
</CodeGroup>

Required: `name`, `agent`, and `from_number` or `from_numbers`.
`daily_window_start` and `daily_window_end` default to 09:00–17:00. Returns `201 Created` with the campaign in
`status="draft"`. Validation errors (`400`) cover unknown agents,
pool numbers not registered to your org (the error names the number), a
`from_number` that differs from `from_numbers[0]`, a
`max_calls_per_number_per_day` outside 1–500, ThunderPhone numbers when outbound calling
has not been approved for your organization, invalid IANA timezones,
`end_at <= start_at`, and retry settings outside your organization's
bounds (below). Daily windows are never refused; unusual ones come back
with `warnings`.

### Calling hours and retry limits

- **Timezone default.** Omit `timezone` and the campaign uses the
  first pool number's zone: its area code for US and Canadian numbers
  (`+1 415…` is `America/Los_Angeles`), its country elsewhere. Numbers
  that span several zones, such as toll-free numbers, fall back to `UTC`.
  The same value is on the [phone number object](/api-reference/phone-numbers#phone-number-object)
  as `timezone`. A `timezone` you send always wins.
- **Calling-hours warning.** Calls outside 8am–9pm local time may break
  calling-hours rules such as the TCPA's. A window that starts before
  `08:00` or ends after `21:00` is saved, and the response lists an
  `outside_calling_hours` entry in `warnings`. With
  `window_timezone_mode` `campaign`, the window runs in the campaign's
  timezone, not each contact's: a 9am start in New York reaches a Los
  Angeles contact at 6am. Use `contact` (the default for new campaigns)
  to avoid that.
- **Each contact's local time.** With `window_timezone_mode` `contact`,
  a 09:00–17:00 window means 9am–5pm where each contact is, by the
  contact's area code: a New York contact is called from 9am Eastern and
  a Los Angeles contact from 9am Pacific. Contacts with a toll-free,
  non-US/Canadian or unrecognized number use the campaign's `timezone`.
  An area code that spans two zones (such as 208 in Idaho) is called only
  while the window is open in both.
  A contact whose window is closed simply waits; it uses no attempt.
- **Overnight windows.** A `daily_window_end` earlier than
  `daily_window_start` crosses midnight: `22:00`–`02:00` dials from 10pm
  until 2am the next day. It is saved with `window_crosses_midnight` and
  `outside_calling_hours` warnings, for example when your contacts sit in
  a timezone hours away from the campaign's. Equal start and end
  (`09:00`–`09:00`) is saved with an `empty_window` warning and never
  dials.
- **Retry bounds.** `max_attempts` is at most **10** and
  `retry_backoff_minutes` at least **30**. Values outside them return
  `400` on that field. Staff can raise both for your organization;
  contact support.

```json 400 Bad Request
{
  "max_attempts": ["Campaigns can make at most 10 attempts per contact. Contact support to raise this limit."]
}
```

### Spread retries and double dial

- **Spread retries.** With `retry_strategy` `spread`, the calling window
  is split into morning, midday and late afternoon. Each retry goes to
  the next of those parts after the one the last call was in, on a later
  day, a few minutes either side of the middle of that part, and never
  sooner than `retry_backoff_minutes` after the last call. For a
  09:00–17:00 window, a 10am call that goes unanswered is retried around
  1pm the next day, then around 3:40pm the day after. People who are busy
  every morning get reached in the afternoon, and calls do not land at the
  same minute every day. When the spread slot would fall at or after the
  campaign's `end_at`, the retry uses the plain backoff instead.
- **Double dial.** With `double_dial` on, a call that rings out with no
  answer is redialed once, 30–60 seconds later, from the same number. On
  iPhone, a second call from the same number within three minutes rings
  through Do Not Disturb when its "Allow Repeated Calls" setting is on.
  The redial is part of the same attempt: it uses no attempt
  and does not wait for the backoff. It never follows a busy signal, a
  declined call or voicemail, and there is at most one per attempt. Your
  organization's spacing between calls to the same person and the
  number's daily limit still apply; when either would refuse it, there is
  no redial. A redial that could not start within about three minutes of
  the first call (a long ring plus a long same-number spacing) is skipped.

### Number pools and pacing

Carrier analytics flag numbers that place many calls a day or call in
bursts, and people answer local area codes more often. Spreading calls
across several local numbers keeps each number under those thresholds
and shows each contact a local area code.

- **Which number calls a contact.** At dial time the runner picks, in
  order: the number the contact was last called from (so retries come
  from the same caller ID) while it is still in the pool and under its
  limit; else a pool number with the contact's area code (US and
  Canada); else one in the contact's timezone; else the pool number with
  the fewest outbound calls in the last 24 hours. The contact's
  `from_number` records the choice.
- **Per-number limit.** `max_calls_per_number_per_day` counts every
  outbound call from that number in your organization over a rolling
  24 hours, including calls from other campaigns and the API, because a
  number's reputation is shared by everything it dials.
- **Warm-up.** A ThunderPhone number with less than a week of outbound
  calls gets a lower limit: 20 calls on its first day, rising evenly to
  the full limit on day 7. A limit below 20 applies as is. Numbers on
  your own carrier skip the warm-up.
- **Waiting, not failing.** When no pool number has room, due contacts
  stay `pending` without using an attempt, the campaign stays `running`,
  and `blocked_reason` says why. Dialing resumes on its own as calls age
  out of the 24-hour window. To go faster, pause the campaign and add
  numbers or raise the limit.
- **Numbers that stop working.** `start` refuses a pool with a number
  that cannot place outbound calls. If a number stops working while the
  campaign runs, the runner dials from the rest of the pool, and pauses
  the campaign only when no pool number is left.
- Your organization's other limits still apply: the daily limit for
  ThunderPhone numbers, concurrent calls, and spacing between calls to
  the same person.
### Text before calling

With `pre_call_sms_enabled`, the campaign texts each contact a few
minutes before their first call, so the person knows who is calling
and from which number. Turn it on at create or with `PATCH`:

<CodeGroup>
```bash cURL
curl -X PATCH https://api.thunderphone.com/v1/campaigns/3f6b2c9e-… \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pre_call_sms_enabled": true,
    "pre_call_sms_from_number": "+15557654321",
    "pre_call_sms_template": "Hi {{first_name}}, {{agent_name}} from {{org_name}} will call you shortly from {{call_from_number}}. Reply STOP to opt out of texts.",
    "pre_call_sms_lead_minutes": 2
  }'
```
</CodeGroup>

- **Sender.** `pre_call_sms_from_number` is checked with the same rules
  as [`POST /v1/sms`](/api-reference/sms): it must be an SMS-capable
  number on your own connected Twilio or Telnyx account. ThunderPhone
  numbers cannot text, and choosing one returns `400` with "Texts go out
  through your own Twilio or Telnyx number. Connect one under Phone
  numbers." A US number whose only gap is its A2P 10DLC registration
  saves with a `pre_call_sms_sender_not_ready` warning; its contacts are
  called without a text until the carrier approves it.
- **Template.** Placeholders are the contact's variables plus
  `{{org_name}}`, `{{agent_name}}` and `{{call_from_number}}` (the
  [pool number](#number-pools-and-pacing) the runner picks for the
  contact, formatted like `+1 415-555-0100`; the contact's `from_number`
  is set to it, so the call comes from that number while it stays in the
  pool and under its limit). Those three
  win over a contact variable of the same name. `{{first_name}}` falls
  back to the first word of the contact's `name`. `{{first_name|there}}`
  sets a fallback; a missing variable renders as nothing and the space it
  leaves is tidied (`Hi {{first_name}}, this is` becomes `Hi, this is`).
  The default text:

  ```text
  Hi {{first_name}}, this is {{org_name}}. We'll call you in a few minutes from {{call_from_number}}. Reply STOP to opt out of texts.
  ```
- **Timing.** Only a contact's first attempt gets a text, once; retries
  never do. After a text the carrier accepted, or one it may have sent
  (`unknown`), the call waits
  `pre_call_sms_lead_minutes` and goes out on the next runner pass,
  which runs every 5 minutes. With the default 2 minutes, the call comes
  about 5 minutes after the text. A texted contact is called ahead of
  due retries, and holds its call slot and room on its number until
  then, so a long lead slows the campaign; keep it to a few minutes.
- **Calling window.** No text goes out unless the window is open now and
  still open 5 minutes after the lead time, so the call lands inside it
  even when a pass runs late. Otherwise the contact waits, untexted and
  undialed, for the next window. In each contact's local time
  (`window_timezone_mode` `contact`) this is the contact's own window. A
  daily window must be at least the
  lead time plus 12 minutes; a save that breaks this returns `400`. If a
  campaign's window or `end_at` still leaves no room, its contacts are
  called without a text, recorded as `skipped` with `window_too_short` or
  `campaign_ending`.
- **Pacing.** Texts go out only for call slots the campaign can expect on
  the next pass, counting `max_concurrent_calls`, the organization's
  outbound calls in progress and the calls the number pool has room for
  under `max_calls_per_number_per_day`, so a large campaign, a busy
  organization or a pool at its limits does not text people it cannot
  call soon. When the
  organization [SMS rate limit](/api-reference/sms#endpoints) is reached,
  the remaining texts wait for a later pass, and those contacts are not
  dialed until they are texted. When the carrier cannot be reached to
  check the sending number, texts wait up to 3 passes; then the contacts
  are called without a text, recorded with the carrier's error code.
- **Failures never block the call.** A text that fails or is skipped is
  recorded on the contact, which is dialed right away. Numbers that do
  not look like they can receive texts, such as landlines, are skipped
  with `not_mobile`. Pre-call texts are never retried: a late text about
  a call that already happened would mislead.

Each text is a normal SMS message: it appears in
[`GET /v1/sms`](/api-reference/sms#list-messages) with `source:
"pre_call"` and emits the usual [`sms.sent` and
`sms.failed`](/webhooks/events#sms-events) webhooks. It is sent at most
once per contact. Its outcome is on the [contact
object](#contact-object) as `pre_call_sms`.

<Warning>
  Texting a contact needs the same consent as calling them; texts fall
  under the TCPA and carrier rules too. A US local number needs an
  approved A2P 10DLC campaign on your Twilio account, a toll-free number
  needs toll-free verification, and a Telnyx number needs a messaging
  profile. Carrier fees are billed to your carrier account. ThunderPhone
  does not receive replies yet, so STOP replies are handled by your
  carrier's opt-out handling: Twilio blocks further texts to a number
  that opted out, and those sends fail with `recipient_opted_out`.
</Warning>

## Retrieve / update / delete

`GET /v1/campaigns/{id}` returns the campaign **plus** a `contacts`
array (first 500 [contact objects](#contact-object); filter with
`?contact_status=pending|scheduled|calling|completed|failed|exhausted`).

`PATCH` accepts any subset of the writable fields, but only while
status is `draft`, `scheduled`, or `paused` — otherwise
`409 Conflict`. `from_numbers` replaces the whole pool; `from_number`
alone replaces it with a pool of that one number.

Campaigns saved before the retry bounds keep running exactly as
configured. Sending a `max_attempts` or `retry_backoff_minutes` outside
the bounds is refused only when it changes the saved value, so other
edits still succeed.

`DELETE` returns `204 No Content` and removes the campaign and its
contacts (already-made call logs are kept).

---

## Add contacts

Only allowed while the campaign is a **draft** (`409` otherwise).
Two formats:

<CodeGroup>
```bash CSV upload
curl -X POST https://api.thunderphone.com/v1/campaigns/3f6b2c9e-…/contacts \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -F 'file=@contacts.csv'
```

```bash JSON
curl -X POST https://api.thunderphone.com/v1/campaigns/3f6b2c9e-…/contacts \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "phone_number": "+14155552671", "first_name": "Jamie", "account_id": "A-1042" }
    ]
  }'
```
</CodeGroup>

- **CSV:** UTF-8, must have a `phone` or `phone_number` column. Every
  **other** column becomes a per-contact variable.
- **JSON:** a top-level list, or `{"contacts": [...]}` — each object
  needs `phone_number` (or `phone`); all other keys become variables.
- Max **5,000 rows** per request. Numbers are normalized to E.164
  (8–15 digits); invalid rows are rejected individually, not the whole
  batch.
- Rows with a number ThunderPhone does not call are rejected the same way,
  under the [outbound call rules](/api-reference/outbound-calls#blocked-destinations):
  emergency numbers, short codes, sanctioned countries, and, for a
  ThunderPhone caller ID in the pool, premium-rate numbers and anything but ordinary US
  and Canadian numbers. The row's `reason` field names the rule. A contact that
  reaches dial time with such a number fails with `last_outcome`
  `destination_not_allowed` and is not retried.

```json Response (201 Created)
{
  "accepted": 148,
  "rejected": 2,
  "errors": [
    { "row": 17, "value": "555-0100", "error": "\"555-0100\" isn't a valid phone number. Check the digits and the country code.", "reason": "invalid_number" },
    { "row": 42, "value": "", "error": "Expected an object." }
  ],
  "errors_truncated": false
}
```

`errors` carries at most 100 entries; `errors_truncated` is `true` when more
rows were rejected than listed. `value` is the phone value of the rejected row
(empty when the row was not an object).

### Contact object

`{id, phone_number, from_number, variables, status, attempts, next_attempt_at, last_outcome, call_id, dial_sip_status, dial_sip_reason, dial_sip_kind, pre_call_sms, created_at, updated_at}`
— `status` is `pending`, `scheduled`, `calling`, `completed`,
`failed`, or `exhausted` (retries used up); `from_number` is the pool
number the contact was last dialed from (`""` before its first call); `call_id` links the most
recent [call](/api-reference/calls). `dial_sip_status`, `dial_sip_reason`
and `dial_sip_kind` are that call's `outbound_dial_sip_status`,
`outbound_dial_sip_reason` and `outbound_dial_sip_kind` (e.g. `403`,
`Account is disabled D17` and `refused` when your carrier refused the
dial); all are `null` when there is no call or no carrier answered it.

`pre_call_sms` is `null` until the runner has handled the contact's
[pre-call text](#text-before-calling), then:

```json
{
  "status": "sent",
  "error_code": null,
  "error_message": null,
  "sms_id": "313a3117-827b-46e9-a01a-ac1493838724",
  "delivery_status": "delivered",
  "at": "2026-10-23T16:02:00.412Z"
}
```

| Field | Description |
|-------|-------------|
| `status` | `sent` (the carrier accepted it), `failed`, `unknown` (the carrier may have sent it) or `skipped` (not sent) |
| `error_code`, `error_message` | Why it failed or was skipped. Common codes: `not_mobile`, `empty_message` (the template rendered to nothing), `no_sender`, `messaging_not_registered`, `not_sms_capable`, `recipient_opted_out`, plus the [SMS error codes](/api-reference/sms#send-a-message) |
| `sms_id` | The [SMS message](/api-reference/sms#retrieve-a-message), or `null` when none was sent |
| `delivery_status` | What the carrier reported later (Twilio only), e.g. `delivered` or `undelivered` |
| `at` | When the outcome was recorded |

---

## Campaign actions

`POST /v1/campaigns/{id}/{action}` where `action` is:

| Action | Body | Effect |
|--------|------|--------|
| `start` | `{"consent_to_charge": true}` (required) | `draft`/`paused`/`scheduled`/`cancelled` → `running` (or `scheduled` when `start_at` is in the future). Requires at least one contact, every pool number able to place outbound calls, and the org's [outbound TCPA confirmation](/api-reference/outbound-calls#outbound-tcpa-confirmation) |
| `pause` | — | `running`/`scheduled` → `paused` |
| `cancel` | — | Any non-terminal status → `cancelled` |

Returns `200 OK` with the updated campaign. Invalid transitions return
`409`; unknown actions return `404`.

---

## Stats

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/campaigns/3f6b2c9e-…/stats \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

```json Response
{
  "total": 150,
  "completed": 41,
  "failed": 3,
  "in_progress": 2,
  "by_status": { "pending": 96, "scheduled": 8, "calling": 2, "completed": 41, "failed": 3 },
  "recent_calls": [
    {
      "contact_id": 9911,
      "phone_number": "+14155552671",
      "from_number": "+15551234567",
      "call_id": 987654321,
      "status": "completed",
      "outcome": "completed",
      "started_at": "2026-04-20T18:24:10.113Z"
    }
  ]
}
```

`recent_calls` holds the 20 most recently updated contacts that have a
call attached; `from_number` is the number that call was placed from.

---

## Related

<CardGroup cols={2}>
  <Card title="Outbound Calls" icon="arrow-up-right" href="/api-reference/outbound-calls">
    Place a single ad-hoc outbound call instead.
  </Card>
  <Card title="Phone Numbers" icon="phone" href="/api-reference/phone-numbers">
    Campaigns need an outbound-enabled customer VoIP or ThunderPhone number.
  </Card>
  <Card title="Agents" icon="robot" href="/api-reference/agents">
    The agent that speaks on campaign calls.
  </Card>
  <Card title="Calls" icon="phone-volume" href="/api-reference/calls">
    Every attempt appears in call history.
  </Card>
</CardGroup>

<!-- en: api-reference/issue-reports -->
---
title: "Issue Reports"
description: "Org-wide feed of issue reports filed against calls."
---

Issue reports flag specific calls for quality review. They are created
on a per-call basis via
[`POST /v1/calls/{call_id}/issue-reports`](/api-reference/calls#file-a-report)
and can also be filed automatically by [call grading](/api-reference/calls#ai-call-grading)
when it detects an issue pattern. This page documents the **org-wide feed**
— use it to build dashboards and route issues to your QA workflow.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/issue-reports` | List issue reports across all calls (paginated) |
| `PATCH` | `/v1/issue-reports` | Bulk-update status by `trace_id` |
| `PATCH` | `/v1/issue-reports/{trace_id}` | Update one report's status |

## Issue report object

```json
{
  "id": 4321,
  "trace_id": "5f9a...",
  "call_id": 987654321,
  "agent_id": 12,
  "source": "user",
  "severity": "warning",
  "status": "open",
  "title": "Agent paused too long",
  "description": "Five-second silence before responding to the main question.",
  "what_went_wrong": "",
  "suggested_fix": "",
  "timestamp_seconds": 48,
  "failing_turn_index": null,
  "detected_issue_ref": null,
  "metadata": {},
  "reported_by_id": 7,
  "linked_test_cases": [],
  "regression_guarded": false,
  "created_at": "2026-04-20T18:25:11.002Z",
  "updated_at": "2026-04-20T18:25:11.002Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Issue report id |
| `trace_id` | UUID | Stable id for external linking — also the key for status updates |
| `call_id` | integer | Parent call |
| `agent_id` | integer \| null | Agent that handled the parent call |
| `source` | string | `user` (manually filed from the UI / API) or `system` (automatically filed — e.g. by call grading) |
| `severity` | string | `info`, `warning`, or `critical` |
| `status` | string | `open`, `acknowledged`, or `resolved` |
| `title` | string | Short description, 1–255 chars |
| `description` | string | Free-form body |
| `what_went_wrong` | string | Grader analysis of the failure (system reports) |
| `suggested_fix` | string | Grader-suggested remediation (system reports) |
| `timestamp_seconds` | integer \| null | Offset in seconds into the call the issue refers to |
| `failing_turn_index` | integer \| null | Transcript turn index where the issue manifested — used by [investigations](/api-reference/investigations) to replay from the right point |
| `detected_issue_ref` | string \| null | Free-form id set by grading to correlate recurring patterns |
| `metadata` | object | Free-form bag for your own app data |
| `reported_by_id` | integer \| null | User id of the reporter. `null` when created by the system |
| `linked_test_cases` | array | [Test scenarios](/api-reference/test-scenarios) created from this issue: `{id, agent_id, title, source, latest_verdict, created_at}` |
| `regression_guarded` | boolean | True when the issue has linked scenarios and every one currently passes |
| `created_at`, `updated_at` | timestamp | ISO 8601 UTC |

---

## List issue reports

<CodeGroup>
```bash cURL
curl 'https://api.thunderphone.com/v1/issue-reports?severity=critical' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

```python Python
issues = requests.get(
    "https://api.thunderphone.com/v1/issue-reports",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    params={"severity": "critical"},
).json()
```
</CodeGroup>

### Query parameters

| Param | Type | Description |
|-------|------|-------------|
| `severity` | string | Filter: `info`, `warning`, `critical` |
| `status` | string | Filter: `open`, `acknowledged`, `resolved` |
| `call_id` | integer | Filter to a single call |
| `agent_id` | integer | Filter to reports on calls handled by this agent |
| `start_date` | ISO 8601 | Earliest `created_at` |
| `end_date` | ISO 8601 | Latest `created_at` |
| `limit` | integer | Page size (default 100, capped at 500) |
| `offset` | integer | |

Returns `200 OK` with a paginated envelope of
[Issue report objects](#issue-report-object), ordered by severity
(`critical` → `warning` → `info`) and then newest first:

```json
{
  "results": [ /* Issue report objects */ ],
  "total": 42,
  "limit": 100,
  "offset": 0
}
```

---

## Update a report's status

Reports move through `open` → `acknowledged` → `resolved` (any
transition is allowed). Both update endpoints accept only `status`.

### Single report

<CodeGroup>
```bash cURL
curl -X PATCH https://api.thunderphone.com/v1/issue-reports/5f9a... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "resolved"}'
```
</CodeGroup>

The path key is the report's **`trace_id`** (not the integer `id`).
Returns `200 OK` with the updated
[Issue report object](#issue-report-object), or `404` if no report
with that `trace_id` exists in your org.

### Bulk

<CodeGroup>
```bash cURL
curl -X PATCH https://api.thunderphone.com/v1/issue-reports \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trace_ids": ["5f9a...", "77b1..."],
    "status": "acknowledged"
  }'
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `trace_ids` | array of UUID | yes | 1–500 ids |
| `status` | string | yes | `open`, `acknowledged`, or `resolved` |

```json Response
{ "updated": 2 }
```

Unknown `trace_ids` are skipped silently — `updated` counts the rows
actually changed.

---

## Issue clusters

Reports that share a failure mechanism are grouped into **clusters** — the
rows on the dashboard's Issues page. Each cluster carries a name, a
failure-mode description, a fix lane, aggregate counts, and (when one exists)
a summary of its latest investigation.

### List issue clusters

`GET /v1/issue-clusters`

Returns `{ "results": [...], "total": n, "limit": n, "offset": n }`. Each
cluster includes `fix_lane` (`prompt`, `audio`, `runtime`, `model`, `config`,
`infra`, `other`), `severity`, `call_count`, `report_count`,
`investigation_summary`, and `flagged_at` — when the cluster was flagged to
ThunderPhone (platform-side lanes are flagged automatically; so are prompt
issues whose investigation ended without a confirmed fix).

### Update a cluster

`PATCH /v1/issue-clusters/{cluster_id}`

Accepts `status` (`open`, `acknowledged`, `resolved`) and/or `fix_lane` with
`fix_lane_source`. Setting a status cascades to the cluster's reports;
reclassifying onto a platform-side lane flags the cluster to ThunderPhone
automatically.

### Escalate a cluster

`POST /v1/issue-clusters/{cluster_id}/escalate`

Body: `{ "note": "..." }`. Sends the cluster to ThunderPhone with a full
evidence bundle (reports, evidence values, recent investigation results).
Escalating again appends your note to the open escalation. Emits the
`issue.escalated` webhook.

---

## Related

<CardGroup cols={2}>
  <Card title="Call issue reports" icon="triangle-exclamation" href="/api-reference/calls#issue-reports">
    File a report on a specific call.
  </Card>
  <Card title="Call grading" icon="chart-line" href="/api-reference/calls#ai-call-grading">
    AI-detected issues automatically produce reports here.
  </Card>
</CardGroup>

<!-- en: api-reference/investigations -->
---
title: "Investigations"
description: "AI-assisted root-cause analysis: generate hypotheses and prompt fixes for recurring call issues, test them, and apply the winner."
---

An **investigation** takes a cluster of related
[issue reports](/api-reference/issue-reports) on one agent and works
toward a prompt fix: the AI generates **hypotheses** about the root
cause, drafts **prompt candidates** (you can add your own), each
candidate can be tested in an **experiment** (replaying the failing
calls' inputs against the candidate prompt), and the winning candidate
is **applied** to the agent.

Status flow: `idle` → `generating_hypotheses` → `awaiting_candidates`
→ `searching` → `ready` → `applied`. A run can instead end as
`not_replayable` or `not_reproducible`, and you can set it to `dismissed`.
Starting an investigation kicks off the whole flow automatically —
diagnosis, candidate prompt changes, and replay testing for each one.
Steps run asynchronously — poll the detail endpoint.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/investigations` | List investigations (`?agent_id=`, `?status=`) |
| `POST` | `/v1/investigations` | Start an investigation |
| `GET` | `/v1/investigations/{investigation_id}` | Full detail with candidates + experiments |
| `PATCH` | `/v1/investigations/{investigation_id}` | Update `experiment_config`, or dismiss |
| `POST` | `/v1/investigations/{investigation_id}/hypotheses` | Re-kick diagnosis on an idle investigation |
| `POST` | `/v1/investigations/{investigation_id}/candidates/manual` | Add your own candidate prompt |
| `POST` | `/v1/investigations/{investigation_id}/candidates/{candidate_id}/experiments` | Run an experiment for a candidate |
| `GET` | `/v1/investigations/{investigation_id}/experiments/{experiment_id}` | Poll one experiment |
| `POST` | `/v1/investigations/{investigation_id}/apply` | Apply a candidate's prompt to the agent |

All ids on this page are **UUIDs** except `agent_id` and `call_ids`.

## Investigation object

```json
{
  "id": "e7a91c2d-…",
  "issue_pattern_id": "long-pauses-before-answering",
  "issue_trace_ids": ["5f9a…", "77b1…"],
  "agent_id": 12,
  "baseline_prompt": "You are a helpful support agent…",
  "call_ids": [987654321, 987654322],
  "status": "ready",
  "experiment_config": { "sample_size": 5 },
  "hypotheses": [
    { "id": "h1", "title": "Prompt over-constrains responses", "rationale": "…" }
  ],
  "baseline_results": null,
  "candidates": [
    {
      "id": "c3d4…",
      "source": "ai",
      "hypothesis_id": "h1",
      "label": "Loosen response constraints",
      "prompt": "You are a helpful support agent… (revised)",
      "rationale": "…",
      "created_at": "2026-04-20T18:30:00.000Z",
      "latest_experiment_id": "a1b2…"
    }
  ],
  "experiments": [
    {
      "id": "a1b2…",
      "candidate_id": "c3d4…",
      "status": "completed",
      "config": { "sample_size": 5 },
      "samples": [
        {
          "id": "s1…",
          "call_id": 987654321,
          "sample_index": 0,
          "user_input": "…",
          "original_output": "…",
          "replayed_output": "…",
          "grade": { "verdict": "improved" },
          "created_at": "2026-04-20T18:31:00.000Z"
        }
      ],
      "summary": { "improved": 4, "regressed": 0, "unchanged": 1 },
      "created_at": "2026-04-20T18:30:30.000Z",
      "completed_at": "2026-04-20T18:32:10.000Z",
      "error_message": null
    }
  ],
  "applied_candidate_id": null,
  "applied_agent_version": null,
  "error_message": null,
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:32:10.000Z"
}
```

The **list** endpoint returns `{"results": [...]}` with the same
fields minus the nested `candidates` and `experiments`.

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Investigation id |
| `issue_pattern_id` | string | Your identifier for the issue cluster (≤ 255 chars) |
| `issue_trace_ids` | array of string | The issue reports under investigation |
| `agent_id` | integer | The agent being fixed |
| `baseline_prompt` | string | Snapshot of the agent prompt when the investigation started |
| `call_ids` | array of integer | Example failing calls used as evidence |
| `status` | string | `idle`, `generating_hypotheses`, `awaiting_candidates`, `generating_candidates` (historical), `searching`, `ready`, `not_replayable`, `not_reproducible`, `applied`, or `dismissed` |
| `experiment_config` | object | Default config passed to experiments |
| `hypotheses` | array | AI-generated root-cause hypotheses |
| `candidates` | array | Prompt candidates — `source` is `ai` or `manual`; `hypothesis_id` links back to a hypothesis |
| `experiments` | array | All experiments across candidates, newest first. Sample `grade` compares `original_output` vs `replayed_output` |
| `applied_candidate_id` | UUID \| null | Set once applied |
| `applied_agent_version` | integer \| null | The [agent version](/api-reference/agents#version-history) revision the apply created |

---

## Start an investigation

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/investigations \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "issue_pattern_id": "long-pauses-before-answering",
    "issue_trace_ids": ["5f9a…", "77b1…"],
    "agent_id": 12,
    "call_ids": [987654321, 987654322]
  }'
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `issue_pattern_id` | string | yes | ≤ 255 chars |
| `issue_trace_ids` | array of string | yes | Non-empty |
| `agent_id` | integer | yes | Must belong to your org (`404` otherwise) |
| `call_ids` | array of integer | yes | Non-empty |
| `experiment_config` | object | no | Defaults to `{}` |

Returns `201` with the investigation already running
(`status="generating_hypotheses"`) — creation launches the full flow
automatically: diagnosis and baseline replays, then the autonomous fix
search. Poll `GET …/{investigation_id}` until `status="ready"` and read
`search_result`.

## Drive the workflow

1. **Poll `GET …/{investigation_id}`** — the investigation advances
   through `generating_hypotheses` → `awaiting_candidates` →
   `searching` → `ready` on its own.
2. **`POST …/candidates/manual`** — add your own candidate at any
   non-terminal point: `{"label", "prompt", "rationale"?}` → `201`
   with the new candidate. Manual candidates join the next search
   round, or can be tested directly (next step).
3. **`POST …/candidates/{candidate_id}/experiments`** — body
   `{"config": {…}}` (optional). Replays the failing calls' inputs
   against the candidate prompt asynchronously. Returns `201` with the
   experiment (`status: "running"`); poll
   `GET …/experiments/{experiment_id}` until `completed` / `failed`.
4. **`POST …/apply`** — body `{"candidate_id": "…"}`. Writes the
   candidate's prompt to the agent, records an agent config version,
   sets status `applied`, and auto-resolves the investigation's
   linked issue reports. Allowed from `ready` / `awaiting_candidates`
   (`409` otherwise). Returns the final investigation.
5. **`POST …/hypotheses`** — re-kick diagnosis on an investigation
   that ended `idle` (for example after an interrupted run). `409`
   when a run is already in progress.

To abandon an investigation:
`PATCH /v1/investigations/{id}` with `{"status": "dismissed"}` —
`dismissed` is the only status a client may set directly.

<Note>
  `apply` merges the fix into the agent's **draft** when the exact prompt
  section it was based on still matches. Unrelated draft edits are preserved,
  and the live prompt is untouched until you deploy. Pass `"deploy": true` to deploy in the same call, and
  `"with_ack": true` on a tier-upgrade candidate to enable
  acknowledgements at the same time. A `409` means the relevant prompt section
  changed or its anchor is ambiguous. Re-run the investigation against the
  current prompt.
</Note>

## Run the fix search

`POST /v1/investigations/{investigation_id}/search`

Runs the autonomous fix search: the AI drafts diverse prompt changes (and,
for eligible agents, a tier upgrade), screens each one in parallel replays of
the AI turn, culls weak variants, and confirms the best result on fresh
replays plus calls without the issue. The investigation's `search_result`
carries the outcome — `tier` is `fixed` (eliminated in a confirmation round),
`improved` (a confirmed reduction), or `null` when no change was confirmed.
A completed search with no winner flags the cluster to ThunderPhone with the
replay evidence; when `stopped_early` is `"testing_incomplete"` or
`"replay_budget_exhausted"` the search could not finish verifying its
candidates, nothing is flagged, and rerunning the search is the right next
step (previous searches' best unconfirmed changes are carried into the new
round automatically).

---

## Related

<CardGroup cols={2}>
  <Card title="Fix issues in the dashboard" icon="wand-magic-sparkles" href="/guides/issues#fix-with-ai">
    See the same investigation flow from the Issues page.
  </Card>
  <Card title="Issue Reports" icon="triangle-exclamation" href="/api-reference/issue-reports">
    The raw material investigations start from.
  </Card>
  <Card title="Test Scenarios" icon="list-check" href="/api-reference/test-scenarios">
    Guard the fix with a promoted regression scenario.
  </Card>
  <Card title="Agents" icon="robot" href="/api-reference/agents">
    Applied fixes appear in the agent's version history.
  </Card>
  <Card title="Calls" icon="phone" href="/api-reference/calls">
    Evidence calls are ordinary call logs.
  </Card>
</CardGroup>

<!-- en: api-reference/test-calls -->
---
title: "Simulations"
description: "Run one-shot or batched AI caller simulations against an agent or a phone number, follow their progress, and inspect graded transcripts when they finish."
---

Simulations let you programmatically validate an agent: an AI test
caller role-plays a scenario against your agent, and the run captures
the resulting call, transcript, and grade. Each run produces a real
[call log](/api-reference/calls). Billing itemizes the selected agent,
the simulated caller, and any telephony leg; `charge_multiplier` is retained
as a response field for compatibility and is `1` for current runs. Use
**runs** for one-shot tests and **batches**
to execute several scenarios (or repetitions) with staggered starts.

For scripted, repeatable regression testing — saved scenarios, AI
scenario generation, condition matrices, and release-gate suites — see
[Test scenarios & suites](/api-reference/test-scenarios).

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/simulations` | List simulation runs |
| `POST` | `/v1/simulations` | Start a single simulation run |
| `GET` | `/v1/simulations/{simulation_id}` | Retrieve one run |
| `GET` | `/v1/simulations/batches` | List batches |
| `POST` | `/v1/simulations/batches` | Start a batch |
| `GET` | `/v1/simulations/batches/{batch_id}` | Retrieve batch status and child run ids |

<Note>
  **Deprecated aliases.** `/v1/test-calls` (list + create runs),
  `/v1/test-call-batches`, and `/v1/test-call-batches/{batch_id}`
  are older aliases for the same handlers. They keep working, but new
  integrations should use the canonical `/v1/simulations` routes.
</Note>

<a id="test-call-run-object"></a>

## Simulation run object

```json
{
  "id": 7110,
  "target_type": "agent",
  "target_id": 12,
  "target_name": "Customer Support Agent",
  "agent_name": "Customer Support Agent",
  "direction": "outbound",
  "mode": "bot",
  "target_number": "",
  "scenario_prompt": "Roleplay as a customer asking about refunds.",
  "status": "completed",
  "charge_multiplier": 1,
  "estimated_cost_cents": 16,
  "call_id": 987654321,
  "error_message": "",
  "metadata": {},
  "requested_by_id": 7,
  "started_at": "2026-04-20T18:24:10.113Z",
  "completed_at": "2026-04-20T18:25:04.822Z",
  "created_at": "2026-04-20T18:24:09.011Z",
  "updated_at": "2026-04-20T18:25:04.822Z",
  "duration_seconds": 54,
  "recording_url": "https://storage.googleapis.com/…",
  "transcript": [
    { "role": "user", "content": "Hi, I want a refund.", "timestamp": null }
  ],
  "grade": {
    "id": 88,
    "status": "completed",
    "score": 92,
    "call_outcome": "success",
    "outcome_reasoning": "…",
    "summary": "…",
    "rubric_breakdown": {},
    "detected_issues": [],
    "grader_model": "heuristic-v1",
    "grader_version": "v1",
    "graded_at": "2026-04-20T18:25:11.002Z"
  }
}
```

In an organization with the agent iteration toolkit, a run from a
[held-out test scenario](/api-reference/test-scenarios) reaches an API key,
OAuth token or legacy token as exactly
`{"id": 7110, "scenario_id": 77, "held_out": true}`, in the list and in
[Retrieve a run](#retrieve-a-run); every other field below is absent. Other
runs carry `held_out: false` there.

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Simulation run id |
| `target_type` | string | `agent` or `phone_number` — what the test caller exercises |
| `target_id` | integer \| null | Id of the target agent / phone number |
| `target_name` | string | Name of the target (agent name or phone number) |
| `agent_name` | string \| null | The voice agent's name, resolved even for `phone_number` targets |
| `direction` | string | `outbound` (test caller places the call) or `inbound` (test caller answers) |
| `mode` | string | How the run was wired internally: `bot` (bot-to-bot) or `sip` (SIP loopback). Read-only — not settable on create |
| `target_number` | string | Optional E.164 override for the remote side; empty uses the platform default |
| `scenario_prompt` | string | Free-form role-play prompt driving the test caller |
| `status` | string | `queued`, `in_progress`, `completed`, `failed` |
| `charge_multiplier` | number | Compatibility field. Current runs use `1`; pricing is itemized per bot and telephony leg |
| `estimated_cost_cents` | integer \| null | Pre-call estimate for both sides, in USD cents |
| `call_id` | integer \| null | The [call log](/api-reference/calls) the run produced |
| `error_message` | string | Populated on `status="failed"` |
| `metadata` | object | Internal diagnostics (e.g. start errors) |
| `requested_by_id` | integer \| null | User who started the run (null for API-key runs) |
| `started_at`, `completed_at` | timestamp \| null | Run lifecycle |
| `duration_seconds` | integer \| null | Derived from the underlying call |
| `recording_url` | string \| null | Short-lived playable recording URL |
| `transcript` | array | Simplified turns: `{role, content, timestamp}` |
| `grade` | object \| null | Latest [grade](/api-reference/calls#ai-call-grading) of the underlying call, or `null` if ungraded |

---

## List runs

<CodeGroup>
```bash cURL
curl 'https://api.thunderphone.com/v1/simulations?limit=100' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

### Query parameters

| Param | Type | Description |
|-------|------|-------------|
| `limit` | integer | Default 100, max 500 |
| `offset` | integer | |
| `target_type` | string | Filter by `agent` or `phone_number` |
| `target_id` | integer | Filter by target id (combine with `target_type`) |
| `status` | string | Filter by status |

Returns a plain array of [simulation run objects](#simulation-run-object),
newest first. Listing also self-heals runs whose completion signal was
lost (stale `queued`/`in_progress` runs are marked `failed`).

---

## Start a single run

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/simulations \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_type": "agent",
    "target_id":   12,
    "direction":   "outbound",
    "scenario_prompt": "Roleplay as a customer asking about refunds.",
    "consent_to_charge": true
  }'
```

```python Python
run = requests.post(
    "https://api.thunderphone.com/v1/simulations",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={
        "target_type": "agent",
        "target_id": 12,
        "direction": "outbound",
        "scenario_prompt": "Roleplay as a customer asking about refunds.",
        "consent_to_charge": True,
    },
).json()
```
</CodeGroup>

### Request fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `target_type` | string | yes | `agent` or `phone_number` |
| `target_id` | integer | yes | Id of the target in this org |
| `direction` | string | no | `outbound` (default) or `inbound` |
| `target_number` | string | no | E.164 for the remote side — defaults to the platform test number |
| `scenario_prompt` | string | no | ≤ 4000 chars. Drives the test caller |
| `language` / `primary_language` | string | no | Language for the test caller (ISO 639 or BCP-47; normalized server-side; unsupported codes are rejected) |
| `simulator_product` | string | no | Turn engine for the simulated caller: `testing` (default, bot-vs-bot guards) or `spark` (behaves like a responsive human — useful for warm-transfer consult testing) |
| `consent_to_charge` | boolean | yes | Must be `true` — required to prevent accidental charges |

Returns `201 Created` with the [run object](#simulation-run-object),
status `in_progress`: the call has started. It ends `completed` or
`failed`; poll [`GET /v1/simulations/{simulation_id}`](#retrieve-a-run)
until it does.

Errors:

| Status | Condition |
|--------|-----------|
| `400` | Validation failure (e.g. `consent_to_charge` missing / false) |
| `402` | Insufficient balance |
| `404` | Target agent or phone number not found |
| `429` | More than 10 simulation runs already `queued`/`in_progress` in the org |
| `429` | `concurrent_call_limit_reached`: the organization is at its [concurrent-call limit](/api-reference/introduction#call-limits); retry after `Retry-After` seconds |
| `502` | The run could not be started (run is marked `failed` with an `error_message`) |

---

## Retrieve a run

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/simulations/7110 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Returns the [run object](#simulation-run-object), the same as the list
does. Poll it after starting a run until `status` is `completed` or
`failed`; then `recording_url`, `transcript` and `grade` are filled in as
far as the call produced them (`recording_url` stays `null` when the agent
does not record calls, and `grade` is `null` until grading finishes). Like
the list, this marks a run whose completion signal was lost as `failed`.
`404` means the run is not in this organization.

The [MCP server](/guides/thunderphone-mcp-server) exposes starting an
agent simulation as `run_simulation` and this endpoint as `get_simulation`.

---

## Batches

A batch executes N staggered runs against the same target. The
response returns immediately with a batch in `in_progress`; poll the
detail endpoint for progress and per-run results.

### Batch object

```json
{
  "id": 201,
  "name": "",
  "target_type": "agent",
  "target_id": 12,
  "direction": "outbound",
  "target_number": "",
  "scenario_prompts": ["Ask about refunds.", "…"],
  "matrix_dimensions": null,
  "run_count": 5,
  "stagger_seconds": 2,
  "status": "in_progress",
  "total_runs": 5,
  "completed_runs": 0,
  "failed_runs": 0,
  "estimated_minutes": 10,
  "estimated_cost_cents": 80,
  "error_message": "",
  "requested_by_id": 7,
  "started_at": "2026-04-20T18:24:09.011Z",
  "completed_at": null,
  "created_at": "2026-04-20T18:24:09.011Z",
  "updated_at": "2026-04-20T18:24:09.011Z",
  "run_ids": [7110, 7111, 7112, 7113, 7114]
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Batch id |
| `name` | string | Optional label |
| `scenario_prompts` | array of string | Prompts rotated across runs. For an API key or OAuth token, the text of a [held-out test scenario](/api-reference/test-scenarios) reads `[held out]` |
| `matrix_dimensions` | object \| null | Set when the batch was produced by a [scenario matrix execution](/api-reference/test-scenarios) — records which condition axes were expanded |
| `run_count`, `stagger_seconds` | integer | As requested |
| `status` | string | Batch status |
| `total_runs`, `completed_runs`, `failed_runs` | integer | Progress counters |
| `estimated_minutes` | integer \| null | Pre-flight duration estimate |
| `estimated_cost_cents` | integer \| null | Pre-flight cost estimate |
| `run_ids` | array of integer | Child [run](#simulation-run-object) ids — fetch runs via `GET /v1/simulations` |

### List batches

`GET /v1/simulations/batches` — query params `status`, `limit`
(default 100, max 500), `offset`. Returns a plain array of batch
objects, newest first.

### Start a batch

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/simulations/batches \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_type":  "agent",
    "target_id":    12,
    "direction":    "outbound",
    "run_count":    5,
    "stagger_seconds": 2,
    "scenario_prompts": [
      "Ask about refunds.",
      "Ask for hours of operation.",
      "Complain about a delayed shipment.",
      "Ask to speak with a human.",
      "Ask an unrelated trivia question."
    ],
    "consent_to_charge": true
  }'
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `target_type` | string | yes | `agent` or `phone_number` |
| `target_id` | integer | yes | |
| `direction` | string | no | `outbound` (default) or `inbound` |
| `run_count` | integer | no | 1–20, default 3 |
| `stagger_seconds` | integer | no | Delay between spawning successive runs (0–60, default 5) |
| `scenario_prompts` | array of string | no | Up to 20 prompts (≤ 4000 chars each), rotated per run (modulo) |
| `target_number` | string | no | |
| `name` | string | no | ≤ 255 chars |
| `language` / `primary_language` | string | no | Language for the test callers |
| `consent_to_charge` | boolean | yes | Must be `true` |

Returns `201 Created` with the [batch object](#batch-object). Errors
match [single-run errors](#start-a-single-run) (`400`/`402`/`404`).

### Get batch detail

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/simulations/batches/201 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Returns the [batch object](#batch-object), or `404`. `run_ids` is a
list of child-run ids, not nested run objects — fetch each run via
[`GET /v1/simulations`](#list-runs) or follow the `call_id` on each
run to [`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call).

---

## Related

<CardGroup cols={2}>
  <Card title="Test scenarios & suites" icon="list-check" href="/api-reference/test-scenarios">
    Saved scenarios, AI scenario generation, condition matrices, and release-gate suites.
  </Card>
  <Card title="Agents" icon="robot" href="/api-reference/agents">
    Build the agent being tested — simulations exercise the agent's draft config.
  </Card>
  <Card title="Calls" icon="phone" href="/api-reference/calls">
    Inspect the resulting call logs and transcripts.
  </Card>
  <Card title="Billing" icon="credit-card" href="/api-reference/billing">
    Simulation charges itemize the selected agent, simulated caller, and any telephony leg.
  </Card>
</CardGroup>

<!-- en: api-reference/test-scenarios -->
---
title: "Test Scenarios & Suites"
description: "Saved regression scenarios, AI scenario generation, condition-matrix runs, and release-gate suites."
---

Where [Simulations](/api-reference/test-calls) are ad-hoc, **test
scenarios** are saved, repeatable test cases for an agent. Scenarios
can be written by hand, generated by AI from the agent's prompt, or
**promoted from a real production call** (optionally anchored to an
issue report). Executing scenarios produces a **test run** (a
[simulation batch](/api-reference/test-calls#batch-object) under the
hood), optionally expanded across a matrix of audio/speech/behavior
conditions. **Suites** bundle scenarios into a pass/fail release gate
that can run on a schedule.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` / `POST` | `/v1/agents/{agent_id}/test-scenarios` | List / create scenarios |
| `GET` / `PATCH` / `DELETE` | `/v1/agents/{agent_id}/test-scenarios/{scenario_id}` | Manage one scenario |
| `POST` | `/v1/agents/{agent_id}/test-scenarios/generate` | AI-generate scenarios from the agent prompt |
| `POST` | `/v1/agents/{agent_id}/test-scenarios/refresh` | Re-generate stale scenarios after prompt changes |
| `POST` | `/v1/calls/{call_id}/promote-to-scenario` | Turn a real call into a scenario |
| `GET` | `/v1/agents/{agent_id}/test-runs` | List the agent's test runs (scenario batches) |
| `POST` | `/v1/agents/{agent_id}/test-runs/execute` | Execute scenarios (with optional condition matrix) |
| `GET` | `/v1/agents/{agent_id}/test-runs/{batch_id}` | Test-run detail with per-scenario results |
| `GET` / `POST` | `/v1/suites` | List / create suites |
| `GET` / `PATCH` / `DELETE` | `/v1/suites/{suite_id}` | Manage one suite (UUID id) |

## Scenario object

```json
{
  "id": 311,
  "agent_id": 12,
  "title": "Caller asks for a refund past the window",
  "scenario_prompt": "You bought the product 45 days ago and demand a refund…",
  "labels": ["refunds", "edge-case"],
  "audio_conditions": { "noise_asset": "none" },
  "speech_style": { "pace": "natural", "disfluencies": "none", "accent": "default" },
  "caller_behavior": { "long_silence_seconds": 0, "dtmf_sequence": "", "topic_change": "" },
  "telephony": { "voicemail_answer": false },
  "direction": "inbound",
  "source": "ai",
  "prompt_hash": "d41d8…",
  "source_call_id": null,
  "source_issue_trace_id": null,
  "source_turn_index": null,
  "latest_verdict": "pass",
  "is_stale": false,
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Scenario id |
| `title` | string | ≤ 200 chars |
| `scenario_prompt` | string | ≤ 4000 chars — the role-play brief for the test caller |
| `labels` | array of string | Up to 10 labels, ≤ 50 chars each |
| `audio_conditions` | object | `noise_asset` ∈ `none/cafe/street/car/office`; `snr_db` ∈ `0/5/10/20` (required when a noise asset is set) |
| `speech_style` | object | `pace` ∈ `natural/slow/fast`; `disfluencies` ∈ `none/light`; `accent` ∈ `default/en-US/en-GB/en-IN/es-MX/en-AU/fr-CA` |
| `caller_behavior` | object | `long_silence_seconds` 0–15; `dtmf_sequence` (≤ 12 of `0-9*#`); `topic_change` (≤ 500 chars) |
| `telephony` | object | `voicemail_answer` boolean — answer as a voicemail machine |
| `direction` | string | `inbound` or `outbound` |
| `source` | string | `manual`, `ai`, or `production` (promoted from a call) |
| `prompt_hash` | string | Hash of the agent prompt the scenario was generated against |
| `source_call_id` / `source_issue_trace_id` / `source_turn_index` | mixed \| null | Provenance for promoted scenarios |
| `latest_verdict` | string | `pass`, `fail`, or `unknown` — from the most recent run |
| `is_stale` | boolean | True for `ai`/`production` scenarios whose `prompt_hash` no longer matches the agent prompt |
| `held_out` | boolean | Only for organizations with the agent iteration toolkit: `true` when the scenario was promoted from a [held-out call](/api-reference/conversations#dev-and-test-splits), one whose caller is in an agent's test split. An API key or OAuth token gets such a scenario as exactly `{"id": 77, "held_out": true}`, here, in test runs and in suites, and each simulation run from it as exactly `{"id": 7110, "scenario_id": 77, "held_out": true}`, in test runs and in [simulations](/api-reference/test-calls); every other field is absent, even ones listed as always present; editing, deleting or refreshing it is refused with `403 held_out_call`. Test runs and suites still run it, and their counts include it. Its simulated calls are held out like the caller's. The dashboard sees everything |

### Create / update / delete

`POST` requires `title` + `scenario_prompt` (other fields optional,
defaults above) and returns `201`. `PATCH` accepts any subset.
`DELETE` returns `204`.

### AI-generate scenarios

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/agents/12/test-scenarios/generate \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"count": 6, "include_edge_cases": true, "locale": "en"}'
```
</CodeGroup>

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `count` | integer | 6 | 1–12 scenarios |
| `include_edge_cases` | boolean | `true` | Mix in adversarial cases |
| `locale` | string | `en` | Language of the generated briefs |

Returns `201` with `{"scenarios": [ … ]}` (`source: "ai"`), or `502`
if generation failed.

### Refresh stale scenarios

After you change the agent's prompt, AI scenarios go `is_stale: true`.
`POST /test-scenarios/refresh` with `{"scenario_ids": [...]}` (≤ 50)
or `{"only_stale": true}` (or an empty body to refresh **all**)
re-generates their briefs against the current prompt and returns
`{"scenarios": [...]}`. `502` on generation failure.

### Promote a call to a scenario

Builds one regression scenario from a real call's transcript, grade,
and (optionally) a filed issue.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/calls/987654321/promote-to-scenario \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"issue_trace_id": "5f9a…", "failing_turn_index": 7}'
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `issue_trace_id` | UUID | no | Anchor the scenario to an [issue report](/api-reference/issue-reports) on this call |
| `failing_turn_index` | integer ≥ 0 | no | Transcript index of the **agent** turn that went wrong — focuses generation on a ±3-turn window |

Returns `201` with the new scenario (`source: "production"`). If the
same call (+ same issue) was already promoted, returns `200` with the
existing scenario instead of creating a duplicate. `400` when the turn
index is out of range or not an agent turn. `403 held_out_call` when
the call is [held out](/api-reference/conversations#dev-and-test-splits)
and the request comes from an API key or OAuth token.

---

## Test runs (execute scenarios)

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/agents/12/test-runs/execute \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "web",
    "scenario_ids": [311, 312],
    "matrix": {
      "audio_conditions": [{ "noise_asset": "none" }, { "noise_asset": "cafe", "snr_db": 10 }]
    },
    "consent_to_charge": true
  }'
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `channel` | string | yes | `web` (browser-style calls against the agent) or `telephony` (real calls through a phone number) |
| `phone_number_id` | integer | for `telephony` | Which of your numbers to exercise |
| `scenario_ids` | array of integer | no | ≤ 50 — omit to run **all** of the agent's scenarios |
| `matrix` | object | no | Condition axes to expand: `audio_conditions` (≤ 5), `speech_style` (≤ 7), `caller_behavior` (≤ 8), `telephony` (≤ 2) — each scenario runs once per combination. Total expanded run count is capped; oversize matrices return `400` |
| `stagger_seconds` | integer | no | 0–60, default 5 |
| `consent_to_charge` | boolean | yes | Must be `true` |

Returns `201` with the [test-run object](#test-run-object). `422` when
no scenarios match; `404` for a missing phone number.

### Test-run object

Test runs are returned by `GET /test-runs` (array, `limit` ≤ 200
default 50, `offset`) without per-run details, and by
`GET /test-runs/{batch_id}` with a `runs` array:

```json
{
  "id": 201,
  "agent_id": 12,
  "channel": "web",
  "phone_number_id": null,
  "phone_number_display": null,
  "status": "in_progress",
  "total": 4,
  "completed": 1,
  "failed": 0,
  "pass_count": 1,
  "fail_count": 0,
  "matrix_dimensions": { "audio_conditions": [ … ] },
  "estimated_minutes": 8,
  "estimated_cost_cents": 64,
  "agent_prompt_hash": "d41d8…",
  "error_message": "",
  "requested_by_id": 7,
  "started_at": "2026-04-20T18:24:09.011Z",
  "completed_at": null,
  "created_at": "2026-04-20T18:24:09.011Z",
  "updated_at": "2026-04-20T18:24:09.011Z",
  "runs": [
    {
      "id": 7110,
      "batch_id": 201,
      "scenario_id": 311,
      "scenario_title": "Caller asks for a refund past the window",
      "scenario_prompt": "…",
      "scenario_labels": ["refunds"],
      "condition_dimensions": { "audio_conditions": { "noise_asset": "cafe", "snr_db": 10 } },
      "test_call_run_id": 7110,
      "call_id": 987654321,
      "status": "completed",
      "verdict": "pass",
      "grade_score": 92,
      "duration_seconds": 54,
      "transcript_excerpt": "…",
      "transcript": [ { "role": "user", "content": "…", "timestamp": null } ],
      "grade": { /* grade object */ },
      "recording_url": "https://…",
      "error_message": "",
      "started_at": "2026-04-20T18:24:10.113Z",
      "completed_at": "2026-04-20T18:25:04.822Z"
    }
  ]
}
```

Per-run `verdict` is `pass` / `fail` / `unknown` (derived from the
grade when the run completes). `call_id` is the public call id — link
it to [`GET /v1/calls/{call_id}`](/api-reference/calls).

---

## Suites (release gates)

A **suite** is a named set of scenarios for one agent plus pass
criteria. Suite runs are recorded against the suite; scheduled runs
fire automatically (hourly / daily / weekly), and the dashboard's
Simulations page can trigger them on demand.

### Suite object

```json
{
  "id": "b4e7c1a9-…",
  "name": "Release gate — support agent",
  "agent_id": 12,
  "agent_name": "Customer Support Agent",
  "scenario_ids": [311, 312],
  "scenarios": [
    { "id": 311, "title": "Caller asks for a refund past the window", "labels": ["refunds"], "is_stale": false }
  ],
  "criteria": { "min_pass_rate": 100, "zero_critical_failures": true },
  "schedule": {
    "enabled": true,
    "frequency": "daily",
    "timezone": "America/Los_Angeles",
    "hour": 6,
    "minute": 0,
    "weekday": 0,
    "next_run_at": "2026-04-21T13:00:00+00:00",
    "last_run_at": null
  },
  "last_green_at": null,
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z",
  "runs": [
    {
      "id": "9d2f…",
      "suite_id": "b4e7c1a9-…",
      "batch_id": 201,
      "baseline_run_id": null,
      "trigger": "schedule",
      "status": "running",
      "verdict": "pending",
      "pass_rate": null,
      "critical_failure_count": 0,
      "regression_count": 0,
      "error_message": "",
      "results": [],
      "regressions": [],
      "accepted_at": null,
      "completed_at": null,
      "created_at": "2026-04-20T18:24:10.113Z"
    }
  ]
}
```

### Create / update a suite

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/suites \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Release gate — support agent",
    "agent_id": 12,
    "scenario_ids": [311, 312],
    "criteria": { "min_pass_rate": 100, "zero_critical_failures": true },
    "schedule": { "frequency": "daily", "timezone": "America/Los_Angeles", "hour": 6 }
  }'
```
</CodeGroup>

| Field | Type | Required on create | Description |
|-------|------|--------------------|-------------|
| `name` | string | yes | ≤ 200 chars |
| `agent_id` | integer | yes | |
| `scenario_ids` | array of integer | yes | 1–50 scenarios; every one must belong to the suite's agent |
| `criteria.min_pass_rate` | integer | no | 0–100, default 100 |
| `criteria.zero_critical_failures` | boolean | no | Default `true` |
| `schedule` | object \| null | no | `frequency` ∈ `hourly/daily/weekly` (required inside the object), `timezone` (IANA, default UTC), `hour` 0–23, `minute` 0–59, `weekday` 0–6 (weekly). Pass `null` to remove the schedule |

`POST /v1/suites` returns `201`; `PATCH /v1/suites/{suite_id}` accepts
any subset; `DELETE` returns `204`. List and detail responses embed
the suite's most recent runs (up to 50). A run's `verdict` becomes
`pass` only when the pass rate meets `min_pass_rate` and (if enabled)
no critical-severity failures occurred; `regressions` lists scenarios
that passed in the baseline run but fail now. Suite runs include an
`error_message` string with the batch-level dispatch failure reason;
it is not nullable, and an empty string means there was no dispatch
failure. Each object in `results` also includes a non-nullable
`error_message` with that scenario's dispatch failure reason, or an
empty string when no dispatch failure was recorded.

---

## Related

<CardGroup cols={2}>
  <Card title="Simulations" icon="flask" href="/api-reference/test-calls">
    The run/batch primitives test runs are built on.
  </Card>
  <Card title="Issue Reports" icon="triangle-exclamation" href="/api-reference/issue-reports">
    Promote issues into regression scenarios and track `regression_guarded`.
  </Card>
  <Card title="Agents" icon="robot" href="/api-reference/agents">
    Scenario staleness tracks the agent's prompt.
  </Card>
  <Card title="Calls" icon="phone" href="/api-reference/calls">
    Every scenario run produces a call log.
  </Card>
</CardGroup>

<!-- en: api-reference/validation-sets -->
---
title: "Validation Sets"
description: "Frozen real-call turns replayed against your draft configuration, graded automatically before you deploy."
---

Where [Test Scenarios](/api-reference/test-scenarios) simulate whole
calls end-to-end, a **validation set** is a collection of frozen
single turns from real calls. Each **validation example** pins the
exact conversation history and caller audio of one agent turn, plus
an expectation of how the agent should respond. Running the set
replays every example against the agent's **current draft
configuration** and grades each response with two automated judges —
one listens to the pinned caller audio for contradictions, the other
checks the response against the agent's prompt and the example's
expectation. The result is a pass rate and a list of regressions you
can review before deploying.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/calls/{call_id}/validation-examples` | Promote a call turn into a validation example |
| `GET` | `/v1/agents/{agent_id}/validation-examples` | List the agent's examples |
| `GET` | `/v1/validation-examples` | List every example in the org, across agents |
| `GET` / `PATCH` / `DELETE` | `/v1/validation-examples/{example_id}` | Manage one example |
| `GET` | `/v1/validation-examples/{example_id}/audio/{span_index}` | Stream a pinned caller-audio span |
| `POST` | `/v1/validation-examples/{example_id}/replay` | Replay one example against the draft config |
| `GET` / `POST` | `/v1/agents/{agent_id}/validation-runs` | List / start validation runs |
| `GET` | `/v1/validation-runs/{run_id}` | Run detail with per-example results |
| `GET` | `/v1/agents/{agent_id}/validation-status` | Deploy-time summary for the agent |
| `GET` | `/v1/validation-sets` | Org-wide overview across agents |

## Example object

```json
{
  "id": 42,
  "agent_id": 12,
  "kind": "failure",
  "status": "pending_review",
  "labels": ["refunds"],
  "expectation": "Confirms the refund window and offers to escalate.",
  "accepted_responses": [{ "spoken_response": "…", "tool_calls": [] }],
  "original_response": { "spoken_response": "…", "tool_calls": [] },
  "target_turn_index": 7,
  "source_call_id": 903212880123,
  "source_issue_id": null,
  "prompt_hash": "d41d8…",
  "is_stale_prompt": false,
  "audio_span_indices": [3, 5, 7],
  "expectation_proposal_error": null,
  "last_verdict": "pass",
  "last_run_id": 9,
  "context": [ { "role": "user", "content": "…" } ],
  "created_at": "2026-07-22T18:24:10.113Z",
  "updated_at": "2026-07-22T18:24:10.113Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `kind` | string | `failure` (promoted from a bad turn), `golden` (known-good turn), or `manual` |
| `status` | string | `pending_review` → `active` once the expectation is confirmed; `archived` examples are excluded from runs. Archived examples can be restored to `active`; pending examples can be archived directly. |
| `expectation` | string | What the agent should do on this turn. New examples get an AI-proposed expectation to review (`expectation_proposal_error` is set if proposing failed). |
| `accepted_responses` | array | Optional known-good responses (`spoken_response` + `tool_calls`) |
| `original_response` | object | What the agent actually said/did on the source call |
| `prompt_hash` / `is_stale_prompt` | string / boolean | Hash of the prompt at freeze time; `is_stale_prompt` is true once the draft prompt has changed since |
| `audio_span_indices` | array of integer | Turn indices whose caller audio is pinned for this example |
| `last_verdict` / `last_run_id` | string \| null | Latest completed-run outcome for this example |
| `context` | array | Display transcript excerpt around the frozen turn (list endpoints omit it) |

### Promote a call turn

`POST /v1/calls/{call_id}/validation-examples` with `turn_index`
(the agent turn to freeze), `kind`, and optionally `source_issue_id`.
Returns the created example with `201`. The turn's history and caller
audio are snapshotted immediately. The example is a copy of the call's
content, so [deleting the source call](/api-reference/calls#delete-a-call)
deletes the example too. Promoting the same turn twice returns `409` with
`existing_id`.

### List examples

`GET /v1/agents/{agent_id}/validation-examples` returns
`{ "examples": [...] }` (without `context`).

`GET /v1/validation-examples` returns the same shape across every
agent in the organization, newest first, with `agent_name` added to
each row. Optional query filters: `agent_id`, `status`, `kind`.

### Manage one example

`GET` returns the full example. `PATCH` accepts any subset of
`expectation`, `accepted_responses`, `labels`, `kind`, and `status`
(allowed transitions: `pending_review → active|archived`,
`active → archived`, `archived → active`). `DELETE` removes the
example and its pinned audio.

### Caller audio

`GET /v1/validation-examples/{example_id}/audio/{span_index}` streams
the pinned WAV for one of the example's `audio_span_indices`.

### Replay one example

`POST /v1/validation-examples/{example_id}/replay` (empty body)
replays the frozen turn against the agent's current draft
configuration and returns:

```json
{
  "replayed_output": { "spoken_response": "…", "tool_calls": [] },
  "replay_metadata": { "audio_spans_expected": 3, "audio_spans_loaded": 3, "skipped": false },
  "raw_prompt_hash": "ab12…",
  "cached": false
}
```

If any pinned audio span fails to load, `skipped` is true and the
result is never graded or counted. Identical replays (same draft
config) are served from cache with `cached: true`.

## Validation runs

`POST /v1/agents/{agent_id}/validation-runs` starts a batch run over
the agent's **active** examples (body is optional;
`config_source: "draft"` is the only supported value). Returns the
run with `201`. One run per agent may be in flight (`409` with
`existing_id` otherwise), and concurrent runs per organization are
capped (`429`). Starting a run with no active examples returns `400`.

```json
{
  "id": 9,
  "agent_id": 12,
  "config_source": "draft",
  "status": "completed",
  "prompt_hash": "ab12…",
  "pass_count": 11,
  "warn_count": 1,
  "fail_count": 2,
  "skipped_count": 1,
  "total_count": 15,
  "pass_rate": 0.786,
  "regressions": [{ "example_id": 42, "previous": "pass", "current": "fail" }],
  "estimated_cost_cents": 8,
  "error_message": null,
  "created_at": "2026-07-22T18:24:10.113Z",
  "started_at": "2026-07-22T18:24:11.001Z",
  "completed_at": "2026-07-22T18:26:44.913Z",
  "triggered_by_name": "Alec Bell"
}
```

`status` is `pending`, `running`, `completed`, or `failed`.
`pass_rate` excludes skipped examples from the denominator.
`regressions` lists examples that passed in the previous completed
run but failed in this one.

### Run detail

`GET /v1/validation-runs/{run_id}` returns the run plus `results`,
one per graded example:

```json
{
  "results": [
    {
      "id": 71,
      "example_id": 42,
      "example_expectation": "Confirms the refund window…",
      "example_kind": "failure",
      "verdict": "fail",
      "replayed_output": { "spoken_response": "…", "tool_calls": [] },
      "replay_metadata": { "audio_spans_expected": 3, "audio_spans_loaded": 3, "skipped": false },
      "audio_verdict": { "contradiction": true, "explanation": "…" },
      "instruction_verdict": { "followed": false, "explanation": "…" },
      "created_at": "2026-07-22T18:25:02.113Z"
    }
  ]
}
```

`verdict` combines both judges: `pass`, `warn`, `fail`, or `skipped`
(audio unavailable). Each judge verdict includes an explanation you
can surface to reviewers.

### List runs

`GET /v1/agents/{agent_id}/validation-runs` returns
`{ "runs": [...] }` — the 20 most recent runs, newest first.

## Validation status

`GET /v1/agents/{agent_id}/validation-status` powers the
deploy-confirmation check:

```json
{
  "active_example_count": 15,
  "latest_run": { "…": "run object or null" },
  "latest_run_matches_draft": true
}
```

`latest_run_matches_draft` is true when the latest completed run was
executed against the current draft prompt — i.e. the pass rate on
screen reflects what you are about to deploy.

## Org overview

`GET /v1/validation-sets` returns one row per agent in the
organization that has validation examples, for a cross-agent
dashboard view:

```json
{
  "agents": [
    {
      "agent_id": 12,
      "agent_name": "Support line",
      "active_count": 15,
      "pending_count": 2,
      "archived_count": 1,
      "latest_run": { "…": "run object or null" },
      "latest_run_matches_draft": true
    }
  ]
}
```

Agents without any validation examples are omitted. Rows are sorted
by agent name.

<!-- en: api-reference/conversations -->
---
title: "Test Conversations"
description: "The conversations an agent is tested against: written by simulated callers for a new agent, or imported from its real calls, with their hardest moments turned into validation examples, and kept up to date as the prompt changes."
---

A test conversation is a whole conversation with one agent, kept so that
changes to the agent can be tested against it. Each one has a source:

| Source | Where it comes from |
|--------|---------------------|
| `production` | One of the agent's real calls, [imported](#import-calls) |
| `test_call` | One of the agent's builder test calls, imported with `include_test_calls` |
| `simulated` | [Generated](#generate-conversations): an invented caller talks to the agent |
| `adversarial` | Generated with `style: "adversarial"`: a caller who pushes on the prompt's weak spots |
| `manual` | Written by hand |

The hardest moments of each conversation become
[validation examples](/api-reference/validation-sets), each with an answer
key (the replies that would be acceptable at that moment, and what the agent
is expected to do). [Replay runs](/api-reference/replay-runs) replay those
moments against a changed configuration and judge the new replies against
the keys.

A conversation keeps every version of its turns as revisions, so the
version a run tested stays readable after the conversation changes. When a
prompt change adds, removes or changes a behavior, a
[refresh](#refresh-conversations) brings each conversation up to the new
prompt as a new revision.

## The agent iteration toolkit

These endpoints are part of the agent iteration toolkit, which is enabled
per organization while it is in beta. Without it they answer `403` with
`code: "feature_not_enabled"` and a `next_step`; ask
[support](mailto:support@thunderphone.com) to enable it.

### Dev and test splits

Each conversation is assigned once to the agent's **dev** split or its
**test** split, half and half by default. Imported calls are assigned by
their caller, so one caller's calls never sit in both splits; generated
conversations are assigned by their id, and adversarial ones always go to
dev.

The dev split is for tuning: try a change, replay the dev examples, read
the failures, repeat. The test split is for measuring a finished change
once. To keep it that way, API keys and OAuth tokens (and so MCP clients
and coding agents) never see a test-split conversation's content: they get
its id, split, source, status and counts, with `"hidden": true`. People
signed in to the dashboard see everything.

A test result spends its examples. Test conversations fill **cohorts**: each
new one joins the agent's open cohort, which seals when it holds 20
conversations, and the next one opens another. A [test replay
run](/api-reference/replay-runs#dev-and-test-splits) replays one sealed
cohort and spends it with its first result, so the next test run, for any
prompt, needs another. Importing calls or generating conversations fills new
cohorts; with none left, a test run is refused with `409 no_test_cohort`.

A production hold-out protects the moments taken from calls, their answer
keys and the test conversations. In an organization with the toolkit, a
call whose caller is in one of its agents' test splits is held out, on the
[calls API](/api-reference/calls) and MCP alike. An API key, an OAuth token
or a legacy token gets it as its `call_id`, its start time and
`"held_out": true` only, without its transcript, recording, history, grade
or report, on the call list and search, detail, transcript, audio, grade,
issue reports and exports; a write on it (grading, promoting it to a test
scenario, regenerating a turn) is refused with `403 held_out_call`. Views
across many calls (report summaries, issue clusters, investigations,
pipeline reports) leave held-out calls out of their counts and samples and
withhold text a model wrote from them. A test scenario promoted from a
held-out call is its id and `"held_out": true`, and so are the simulated
calls run from it. Splits are per agent, so a caller held out by one agent
can sit in another agent's dev split: a dev conversation or example copied
from their call reads like a test-split one, with `"held_out": true`. People
signed in to the dashboard see everything, and an admin can give one API key
`include_held_out_calls` (off by default, set only in the dashboard) for an
integration that needs every call; MCP never uses it. Leave held-out calls
out when tuning. One caller sits in one split of an agent: examples promoted
from a call follow the same caller rule as conversations.

When a call's recording is turned off, or the call is deleted, the
conversations imported from it go too, with their revisions, their
examples, the examples promoted straight from the call, the examples'
pinned caller audio and their replay results, and Core's replay cache for
the call. A purge that fails is retried until it finishes, so nothing
derived from the call outlives it. Until it has, a result of such an
example reads as its verdict and ids only, with `content_withheld:
"recording_disabled"`.

An agent runs one conversation job (generate, import or refresh) or one
[replay run](/api-reference/replay-runs#one-run-or-job-at-a-time) at a
time, so a refresh never rewrites the examples a replay is running on. A
job start while another job is going is refused with `409 job_active`
(`existing_job_id`), and while a replay run is going with `409
replay_run_active` (`existing_run_id`).

### `dry_run`, `quote_id` and `max_cost_cents`

Generating, importing and refreshing conversations spends model credits:
personas, simulated caller and agent turns, and reads of each conversation
to find its hard moments or its out-of-date turns. All three quote first.
Send the request with `"dry_run": true` and the response is a cost quote,
step by step, with a `quote_id`, and nothing runs. The quote counts every
request the run can make (its call counts are the run's upper bound) at a
typical size, without prompt-cache discounts.

A real run needs that `quote_id` and `max_cost_cents`, a cap in US cents
from 1 to 10,000. The `quote_id` is good for 15 minutes, for the same
agent and the same arguments, and for one job: it is used up once,
durably, in the transaction that creates the job, and a second run with it
is refused with `quote_used`. A start that is refused or fails before the
job exists (`409 job_active` or `replay_run_active`, a database error)
leaves it usable: retry with it. Once the job exists the quote is spent,
so a job that then fails or stops is repeated with a new dry run and its
new `quote_id`. It is refused when it is
missing, expired, forged or issued for other arguments, when the models or
prices changed, or when the run would now cost more than it quoted (the
prompt, the calls or the conversations changed since). A refresh's quote
also covers the prompt reviews it runs to read the prompts' behaviors, and
binds the target prompt and the conversations it selected: when either
changes before the run, it is refused with `quote_mismatch`.

The cap is hard. Before each request the job sets aside the most that
request can cost (its whole input at the uncached price plus its output
limit; an agent turn at the token budget the agent's model is held to) and
stops instead of sending one that does not fit (status `stopped`), keeping
what it already wrote. Because of that set-aside, a job stops with up to
one request's bound per worker unspent: the quote's
`largest_reservation_cents` is the largest, and to let a job finish, set
`max_cost_cents` to about `total_cents` plus twice
`largest_reservation_cents`. The job is charged what its requests really
cost, not what it set aside.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/agents/{agent_id}/conversations` | List an agent's test conversations |
| `GET` | `/v1/conversations/{conversation_id}` | Retrieve one conversation with its current turns |
| `GET` | `/v1/conversations/{conversation_id}/revisions` | Every revision of a conversation: how and why it changed, with row diffs |
| `POST` | `/v1/agents/{agent_id}/conversations/generate` | Generate conversations with simulated callers |
| `POST` | `/v1/agents/{agent_id}/conversations/import` | Import the agent's recent calls |
| `POST` | `/v1/agents/{agent_id}/conversations/refresh` | Bring conversations up to the current prompt |
| `GET` | `/v1/conversation-jobs/{job_id}` | Follow a generate, import or refresh job |

## Conversation object

```json
{
  "id": 812,
  "agent_id": 123,
  "source": "simulated",
  "split": "dev",
  "status": "active",
  "retired_reason": "",
  "source_call_id": null,
  "persona": {
    "name": "Dana",
    "wants": "A plumber today for a leaking kitchen sink.",
    "knows": ["Lives at 14 Elm Street", "Free after 3 pm"],
    "traits": ["rambling"],
    "manner": "Friendly, gives more detail than asked.",
    "language": "en",
    "hangs_up_when": "A visit is booked or the agent cannot help.",
    "pushes_on": "",
    "tactics": [],
    "style": "normal"
  },
  "conversation_started_at": "2026-10-19T16:40:03Z",
  "current_revision": {
    "id": 990,
    "number": 1,
    "prompt_revision_id": 4182,
    "change_kind": "created",
    "row_count": 14,
    "audio_real_through": null,
    "created_at": "2026-10-19T16:40:31Z"
  },
  "revision_count": 1,
  "metadata": { "end_reason": "agent_ended" },
  "created_at": "2026-10-19T16:40:31Z",
  "updated_at": "2026-10-19T16:40:31Z",
  "rows": [
    { "role": "assistant", "content": "Northside Plumbing, how can I help?" },
    { "role": "user", "content": "Hi, my kitchen sink is leaking under the cabinet." }
  ]
}
```

| Field | Type | Description |
|-------|------|-------------|
| `source` | string | See the table above |
| `split` | string | `dev` or `test` |
| `status` | string | `active`, or `retired`: kept and readable, but left out of runs. Once a split has 50 real conversations, the next import retires its simulated ones (not adversarial ones); `retired_reason` says why |
| `source_call_id` | integer \| null | The [call](/api-reference/calls) an imported conversation came from |
| `persona` | object \| null | The simulated caller: who they are, what they want and know, how they talk, when they hang up, and for adversarial callers the passage they push on (`pushes_on`) and how (`tactics`) |
| `current_revision` | object | The version of the turns runs use now: its `number`, the prompt revision it matches, how it was made (`change_kind`: `created`, `refreshed`, `restored` or `manual`), its row count, and the last row whose caller audio is still the real recording (`audio_real_through`, `null` for text-only conversations) |
| `revision_count` | integer | How many revisions the conversation has |
| `metadata` | object | Details such as why a generated conversation ended (`end_reason`: `agent_ended`, `transferred`, `caller_hung_up`, `caller_gave_up`, `turn_cap` or `cost_cap`) |
| `rows` | object[] | The current revision's turns in order, as role and content plus any tool calls and results. Only on the single-conversation endpoint |

A test-split conversation read with an API key has only `id`, `agent_id`,
`split`, `source`, `status`, `row_count`, `revision_count`,
`cohort_number`, `hidden` and `hidden_reason`.

## List conversations

<CodeGroup>
```bash cURL
curl 'https://api.thunderphone.com/v1/agents/123/conversations?split=dev&status=active' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

| Param | Type | Description |
|-------|------|-------------|
| `split` | string | `dev` or `test` |
| `source` | string | One of the sources above |
| `status` | string | `active` or `retired` |
| `limit` | integer | 1 to 100, default 20 |
| `offset` | integer | Default 0 |

Returns a page (`count`, `limit`, `offset`, `next_offset`, `results`) of
conversations without `rows`, newest first.

## Retrieve a conversation

```bash
curl https://api.thunderphone.com/v1/conversations/812 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

Returns the [conversation object](#conversation-object) with `rows`.

## Conversation revisions

`GET /v1/conversations/{conversation_id}/revisions` lists every revision,
newest first, with `limit` and `offset`. Nothing is deleted: a refresh adds
a revision, and the ones before it stay readable here.

```json
{
  "id": 1204,
  "number": 3,
  "parent_id": 1150,
  "prompt_revision_id": 4190,
  "change_kind": "refreshed",
  "change_note": "Refreshed for prompt revision 4190 (from 4182). Removed: Ask for the caller's date of birth before booking. 5 of 16 rows differ from the previous revision. Examples: 1 kept.",
  "behaviors": {
    "added": [],
    "removed": [{ "id": "b7a1c2d3e", "behavior": "Ask for the caller's date of birth before booking." }],
    "changed": [],
    "reworded": ["b4d1e09a2"]
  },
  "restored_from": null,
  "refresh": {
    "from_prompt_revision_id": 4182,
    "to_prompt_revision_id": 4190,
    "out_of_date": [
      { "turn": 3, "behavior": "b7a1c2d3e", "how": "does_removed", "caller_responds": true, "note": "Asks for the date of birth." }
    ],
    "rewrite": { "from_agent_turn": 3, "agent_turns_written": 3, "caller_lines_kept": 2, "caller_lines_written": 1, "caller_turns_dropped": { "4": "Answered the removed date-of-birth question." }, "end_reason": null, "tool_results": [] },
    "examples": { "repointed": [5101], "retired": [], "brought_back": [], "moment_changed": [5101], "answer_keys_rewritten": [5101] },
    "note": ""
  },
  "changed_rows": [6, 7, 8, 9, 10],
  "audio_real_through": 5,
  "created_by": "refresh_conversations",
  "created_at": "2026-10-19T18:02:44Z",
  "row_count": 16,
  "diff": [{ "op": "replace", "parent_rows": [6, 11], "rows": [6, 11], "parent_content": [], "content": [] }]
}
```

| Field | Description |
|-------|-------------|
| `change_kind` | `created`, `refreshed` (brought up to a new prompt revision), `restored` (rows copied back from an earlier revision) or `manual` |
| `behaviors` | Between the prompt revision the parent matched and this one's: behaviors `added`, `removed` and `changed` in meaning, and the ids `reworded` (wording only, which rewrites nothing) |
| `restored_from` | For a restore, the earlier revision the rows came from (`revision_id`, `number`, `prompt_revision_id`) |
| `refresh` | For a revision a refresh wrote: the prompt revisions it went from and to, the agent turns that were `out_of_date` (each with the behavior, `how`: `does_removed`, `misses_added` or `does_old_version`, and whether the caller's next line answered it), the `rewrite` when turns were rewritten, and the `examples` moved, retired, brought back or given new answer keys. `null` for other revisions |
| `changed_rows` | Indices of rows that differ from the parent |
| `diff` | The changed ranges of rows, each with `op` (`replace`, `insert` or `delete`), the parent's and the new row ranges, and the rows themselves |

The response also carries the `conversation`. For a test-split
conversation read with an API key, `results` is empty and `hidden` is
`true`.

## Generate conversations

For an agent with few or no calls. A model writes invented callers from the
agent's prompt and tools, each with a reason to call and a way of talking.
Each caller then talks to the agent turn by turn: the agent's replies come
from the same text pipeline a call uses, with the agent's real prompt,
tools and model, and the agent writes its own opening line. Tools that call
your webhooks are not called; a model writes a plausible result from the
tool's definition instead. A conversation ends when the agent ends the call
or transfers it, the caller hangs up, or it reaches `max_caller_turns`.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/agents/123/conversations/generate \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"count": 5, "dry_run": true}'
```

```python Python
quote = requests.post(
    "https://api.thunderphone.com/v1/agents/123/conversations/generate",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={"count": 5, "dry_run": True},
).json()
print(quote["estimate_cents"], quote["estimate"]["largest_reservation_cents"])

job = requests.post(
    "https://api.thunderphone.com/v1/agents/123/conversations/generate",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={"count": 5, "quote_id": quote["quote_id"], "max_cost_cents": 150},
).json()
```
</CodeGroup>

| Field | Type | Description |
|-------|------|-------------|
| `count` | integer | Conversations to write, 1 to 20. Default 5 |
| `style` | string | `normal` (default) or `adversarial`: callers who interrupt, refuse, answer a different question, give details in an odd format, ask for a person or try to steer the agent off its task, each aimed at a passage of the prompt |
| `target` | string | `changed_behaviors`: aim the callers at the passages that changed in the agent's last prompt edit |
| `use_draft` | boolean | Talk to the draft (default `true`) or the deployed configuration |
| `direction` | string | `inbound` (default: the caller rings the agent) or `outbound` |
| `max_caller_turns` | integer | 1 to 16, default 16 |
| `max_moments` | integer | Hard moments per conversation to turn into examples, 0 to 5. Default 3 |
| `dry_run` | boolean | Return the quote only |
| `quote_id` | string | The dry run's `quote_id`; required unless `dry_run` |
| `max_cost_cents` | integer | Hard spend cap, 1 to 10,000; required unless `dry_run` |

A dry run returns `200`:

```json
{
  "dry_run": true,
  "kind": "generate",
  "params": { "count": 5, "style": "normal", "target": null, "use_draft": true, "direction": "inbound", "max_caller_turns": 16, "max_moments": 3 },
  "estimate_cents": 61.4,
  "estimate": {
    "total_cents": 61.4,
    "total_usd": 0.61,
    "largest_reservation_cents": 9.814,
    "steps": [
      { "step": "personas", "model": "gpt-6-1-sol", "calls": 1, "input_tokens_per_call": 5200, "output_tokens_per_call": 2550, "usd_per_million_input": 2.5, "usd_per_million_output": 10.0, "cents": 3.85 }
    ],
    "notes": [],
    "expected_cents": null
  },
  "quote_id": "eyJvcmciOjQyLC…",
  "quote_expires_in_seconds": 900,
  "next_step": "Show this quote, then run again with the same parameters, without dry_run, with this quote_id and with max_cost_cents (the job never spends more)."
}
```

A real run returns `202` with the [job](#conversation-job-object) and the
estimate it was started on.

## Import calls

Turns the agent's recent finished calls into conversations. Calls with
recording turned off are skipped, as are calls already imported and
AI-caller simulations. At most two calls per caller are taken, spread over
days and over the agent's prompt revisions, newest first.

Each call's caller turns are checked for hard moments: signals the call
already stored (transcription seats that disagreed, a reply cut off, a gap
of more than 3 seconds, the caller hanging up mid-flow, a flagged issue),
and one model read of the call (the caller repeating or correcting
themselves, the agent asking again, missing something, or not following an
instruction, which it quotes). The flagged moments are kept, plus one
ordinary moment so the set also measures what already works.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/agents/123/conversations/import \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"since_days": 30, "max_calls": 40, "dry_run": true}'
```
</CodeGroup>

| Field | Type | Description |
|-------|------|-------------|
| `since_days` | integer | How far back to look, 1 to 365. Default 30 |
| `max_calls` | integer | Calls to import at most, 1 to 200. Default 40 |
| `include_test_calls` | boolean | Also import the agent's builder test calls. Default `false` |
| `max_moments` | integer | Hard moments per call to turn into examples, 0 to 5. Default 3 |
| `dry_run` | boolean | Return the quote only. Its `estimate.calls_selected` says how many calls would be imported |
| `quote_id` | string | The dry run's `quote_id`; required unless `dry_run` |
| `max_cost_cents` | integer | Hard spend cap, 1 to 10,000; required unless `dry_run` |

The responses match [Generate conversations](#generate-conversations).

## Refresh conversations

After a prompt change that adds, removes or changes a behavior, some
conversations no longer match what the agent would do: the agent still asks
for a date of birth the new prompt no longer wants, say. A replay run on
them tests the new prompt on histories it could not have produced. A
refresh brings each active conversation up to the agent's current prompt
revision as a new revision. The agent's own
[review](/api-reference/agents#review-a-prompt) reports when one is due:
`conversations.refresh_suggested` and how many conversations it would
update.

For each conversation, a refresh:

1. **Compares behaviors.** It diffs the rule inventories of the prompt the
   conversation was written for and the current one. A change in wording
   only rewrites nothing: the conversation is re-pointed to the new
   revision with the same rows.
2. **Finds the out-of-date turns.** One model read lists the agent turns
   that do something a removed behavior asked for, miss an added one, or
   follow the old version of a changed one. A conversation with none before
   its last example is re-pointed, and examples whose own reply changed get
   new answer keys.
3. **Restores before it rewrites.** When an earlier revision of the
   conversation was written for a prompt with these behaviors in their
   current state (a rule removed and later added back, for example), its
   rows are copied back, real caller audio included, as a `restored`
   revision.
4. **Otherwise rewrites the affected span**, from the first out-of-date
   agent turn to the last example's caller turn. Agent turns come from the
   same text pipeline a call uses, with the new prompt. A caller line that
   answered a removed question is dropped; the others are kept, with their
   real audio, when they still fit, and a simulated caller writes the rest.
   Rows after the last example are kept as they were.
5. **Moves the examples** to the new revision with rebuilt histories, and
   rewrites answer keys whose moment changed. An example whose caller turn
   is no longer in the conversation is retired with the reason, and comes
   back if a later refresh brings the turn back.

A conversation is retired when rewrites cover more than 60% of its agent
turns, or when it is more than 8 prompt revisions behind and no refresh can
bring it up to date. Retired conversations stay readable.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/agents/123/conversations/refresh \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true}'
```
</CodeGroup>

| Field | Type | Description |
|-------|------|-------------|
| `conversation_ids` | integer[] | Refresh only these conversations of the agent, at most 500. Default: every active one |
| `from_prompt_revision_id` | integer | Refresh only the conversations written for this [prompt revision](/api-reference/prompt-revisions) |
| `use_draft` | boolean | Bring the conversations up to the draft prompt (default `true`) or the deployed one |
| `dry_run` | boolean | Return the quote only. Its `estimate.conversations` counts the `selected` conversations by how they stand: `current`, `no_behavior_change`, `behavior_changes`, `unknown` and `unrefreshable`, and lists the unrefreshable ones with the reason in `unrefreshable_conversations` (`id`, `reason`) |
| `quote_id` | string | The dry run's `quote_id`; required unless `dry_run` |
| `max_cost_cents` | integer | Hard spend cap, 1 to 10,000; required unless `dry_run` |

The responses match [Generate conversations](#generate-conversations).
A refresh's quote prices every conversation it reads as if it were
rewritten, every model call at its output limit, so a refresh usually
spends well under it. A conversation whose prompt revision is not known
cannot be refreshed, since nothing tells what changed since it was
written: it is quoted at 0, and the job leaves it as it is and reports it
as `skipped` with that `reason`. That is a conversation imported from a
call made before calls recorded their prompt revision, unless the agent
has exactly one deployed revision with the call's prompt text, which the
import then links it to. A refresh an API key, OAuth token or legacy token
starts (MCP included) leaves test-split conversations, and conversations
copied from held-out calls, out of its selection, its quote, its progress
and its cost; naming one in `conversation_ids` returns `403
test_conversation`, with nothing about the conversation. A person
refreshes them from the dashboard, and that job's rows for them show API
keys ids and counts only, without their outcome, and `outcome_counts`
counts only the rows the caller can see. An `active` example whose
history, reply or answer key a refresh rewrites goes back to
`pending_review` with the label `refreshed_needs_review`, so the
dashboard's validation runs do not grade against a key nobody reviewed;
an example someone archived meanwhile stays archived. A refresh runs
as a background job like generate and import; if its worker stops, it is
resumed and skips the conversations it already did. It runs on the target
prompt and the conversations frozen when it started: when the agent's
prompt changes while it runs, the job ends `failed`, keeping what it
refreshed.

## Retrieve a job

`GET /v1/conversation-jobs/{job_id}` reports a job's progress. Poll it
until `status` is `completed`, `stopped` or `failed`.

### Conversation job object

```json
{
  "id": 77,
  "agent_id": 123,
  "kind": "generate",
  "status": "completed",
  "params": { "count": 5, "style": "normal" },
  "estimate_cents": 61.4,
  "max_cost_cents": 150,
  "cost_cents": 48.9,
  "progress": { "done": 5, "total": 5, "step": "moments" },
  "error": "",
  "result": {
    "conversations": [
      { "id": 812, "split": "dev", "source": "simulated", "status": "active", "persona": { "name": "Dana" }, "end_reason": "agent_ended", "source_call_id": null, "example_ids": [5101, 5102] },
      { "id": 813, "agent_id": 123, "split": "test", "source": "simulated", "status": "active", "row_count": 14, "revision_count": 1, "cohort_number": 2, "hidden": true, "hidden_reason": "This item is in the agent's test split, whose content is hidden from API keys and coding agents. People can review it in the ThunderPhone dashboard." }
    ],
    "conversation_count": 2,
    "example_count": 2,
    "split_counts": { "dev": 1, "test": 1 },
    "errors": [],
    "hidden_error_count": 0
  },
  "created_at": "2026-10-19T16:39:58Z",
  "started_at": "2026-10-19T16:40:00Z",
  "completed_at": "2026-10-19T16:43:12Z"
}
```

| Field | Description |
|-------|-------------|
| `status` | `pending`, `running`, `completed`, `stopped` (at the cost cap; what it wrote is kept) or `failed` |
| `cost_cents` | What the job has spent so far, against `max_cost_cents` |
| `progress` | Done and total counts, the current step, and cost by step |
| `result.conversations` | What the job wrote. For API keys, a test-split conversation appears as the [hidden shape](#conversation-object) of a conversation, without its example count. For a refresh, each visible row also has its `outcome` (`current`, `repointed`, `restored`, `rewritten`, `retired`, `skipped` or `failed`), the new `revision_id`, how many examples were retired, brought back or given new answer keys, and a `reason` when there is one |
| `result.example_count` | Examples of the conversations the caller can see: for API keys, the dev split's |
| `result.outcome_counts` | A refresh job's outcomes, counted over the rows the caller can see |
| `result.errors` | Conversations or calls that failed without stopping the job, each with its `conversation_id`, `split` and `message`. For API keys, errors about test-split conversations, and conversations copied from held-out calls, are left out, and a call that failed before its conversation existed has a fixed message: the call id and the error's type |
| `result.hidden_error_count` | How many errors were left out for this caller |

The examples a job creates have status `pending_review`. Replay runs use
them right away; [validation runs](/api-reference/validation-sets) use them
once someone sets them `active`.

## Errors

| Status | Condition |
|--------|-----------|
| `400` | `validation_error`: an unknown field, a value of the wrong type or out of range, or a real run without `max_cost_cents` (the response includes `estimate_cents`) |
| `400` | `quote_required`, `quote_expired`, `quote_invalid`, `quote_mismatch` (another agent, kind or set of arguments, or the models or prices changed), `quote_outdated` (the run would now cost more than quoted) or `quote_used` (the quote already paid for a job): run the dry run again and send its `quote_id` |
| `503` | `quote_unverifiable`: the quote could not be recorded as used right now, so nothing ran; retry with it |
| `403` | `feature_not_enabled`: the organization does not have the agent iteration toolkit. `insufficient_scope`: an OAuth token without `testing:write` (`testing:read` to read) |
| `403` | For a refresh started by an API key, OAuth token or legacy token: `test_conversation`, a `conversation_ids` entry is a test-split conversation or one copied from a held-out call (refresh those from the dashboard) |
| `404` | The agent, conversation or job is not in this organization |
| `400` | For a refresh: `conversation_ids` that are not the agent's, more than 500 of them, or a `from_prompt_revision_id` that is not one of the agent's prompt revisions |
| `409` | `job_active`: the agent already has a job running (`existing_job_id`). `replay_run_active`: the agent has a [replay run](/api-reference/replay-runs) going (`existing_run_id`). Each agent runs one job or replay run at a time; the quote stays usable |

## MCP

The [MCP server](/guides/thunderphone-mcp-server) exposes these as
`list_conversations`, `get_conversation`, `get_conversation_revisions`,
`generate_conversations`, `import_conversations`, `refresh_conversations`
and `get_conversation_job`.

---

## Related

<CardGroup cols={2}>
  <Card title="Replay Runs" icon="rotate" href="/api-reference/replay-runs">
    Replay the examples against a changed configuration.
  </Card>
  <Card title="Validation Sets" icon="list-check" href="/api-reference/validation-sets">
    The examples and their answer keys.
  </Card>
</CardGroup>

<!-- en: api-reference/replay-runs -->
---
title: "Replay Runs"
description: "Replay an agent's test moments under its draft or a changed configuration, judge each new reply against its answer key, and compare configurations side by side."
---

A replay run takes a sample of an agent's [validation examples](/api-reference/validation-sets),
replays each moment under a configuration, and judges the new reply against
the example's answer key. Use it to check a prompt edit before you deploy
it, and to compare configurations (product, audio tier, feedback mode,
voice, endpointing, language or a candidate prompt) on the same examples.

The examples come from the agent's [test conversations](/api-reference/conversations):
generated ones for a new agent, imported calls once it has some.

## How a moment is replayed

Each example is one caller turn with the conversation before it. The run
replays it with one of two engines:

- **Exact** replays the turn as a live call would. The turn's recorded
  caller audio is played into a real call session in Core with the
  configuration being tested, so transcription, end-of-speech detection,
  the wait cover (an acknowledgement, ticks or silence) and the reply run
  as in production. Exact replay needs a Bolt v2 configuration and a turn
  with recorded caller audio. It reports latency to the first audio and
  what covered the wait.
- **Text** sends the conversation's transcript to the agent's model with
  the configuration's prompt and tools, and judges the reply text.
  Generated conversations have no audio, so they always replay as text.

`engine: "auto"` (the default) uses exact replay where it can and text
everywhere else; each result says which engine ran and why. `engine:
"exact"` skips the examples that cannot be replayed exactly. On the dev
split, `auto` also falls back to text when Core cannot run an exact replay
(it predates the endpoint, or does not confirm the replay's budget); the
result says so and the run is `degraded`. On the test split each example's
engine is set before the run from the example's data (exact for recorded
caller audio, text for a text-only example), a configuration with no exact
path for an audio example is refused, `engine` must be omitted or `auto`
(`exact` or `text` is refused with `test_engine_per_example`), and
nothing falls back (see
[Dev and test splits](#dev-and-test-splits)). Pass rates are always
reported per engine.

A model judge reads each reply against the prompt and the example's answer
key and returns `pass`, `warn` or `fail`, with each issue's type, severity
(`warn` or `fail`), explanation and evidence. An example that could not be replayed or judged is `skipped` or
`error`; errors count against the pass rate.

## The agent iteration toolkit

These endpoints are part of the agent iteration toolkit, which is enabled
per organization while it is in beta. Without it they answer `403` with
`code: "feature_not_enabled"` and a `next_step`; ask
[support](mailto:support@thunderphone.com) to enable it.

### Dev and test splits

Every example belongs to the agent's dev split or its test split (see
[Dev and test splits](/api-reference/conversations#dev-and-test-splits)).
Tune on the dev split: `split: "dev"` (the default) returns every example's
replayed reply, the judge's verdict and the examples fixed and broken
against a baseline. Measure a finished change on the test split:

- a test result spends its examples. The test split is divided into
  cohorts: each new test conversation joins the agent's open cohort, which
  seals when it is full. A test run replays one sealed cohort, the oldest
  unused one that has an example to replay (a cohort with none is passed
  over, so it never blocks the next), whole: `sample_size` and `sample_seed` are ignored, so the
  totals never narrow to a chosen example. The run claims its cohort when
  it is created, before anything is queued, and its first result that
  discloses anything spends it. A later test run, for any prompt, needs
  another cohort; a run that ends before disclosing anything (refused, or
  stopped by its cap before the first reply) hands its cohort back;
- with no unused cohort left, a test run is refused with
  `409 no_test_cohort` and a `next_step`: import more calls or generate
  conversations, which fill new cohorts;
- comparisons are dev-only: a request with `configs` on the test split is
  refused with `400 comparison_dev_only`. Compare on dev, then run the test
  split once for the configuration you pick, so the test result is never
  the basis of the choice;
- each example's engine is set before the run, from the example's data: an
  example with recorded caller audio replays exactly, a text-only
  (simulated) one as text. Leave `engine` out: any value but `auto` is
  refused with `400 test_engine_per_example`, before a cohort is claimed.
  Totals come per engine;
- a test run never spends recorded caller audio on text. Exact replay
  exists for Bolt v2 only, so when the cohort holds an example with
  recorded caller audio and the configuration is anything else, the run is
  refused with `409 test_needs_exact_replay` and a `next_step` before
  anything is evaluated, and the cohort stays unused. Measure such a
  configuration on the dev split, where its text replays of audio examples
  are marked `degraded`. A cohort of text-only examples runs on text under
  any configuration;
- a test run never falls back to text. Where its examples replay exactly,
  its first exact replay runs alone, before anything is judged; when Core
  has no exact replay or does not confirm its budget, the run ends `failed`
  with `stop_reason: "exact_replay_unavailable"`, no results, and its
  cohort unused. When Core's replay capacity stays busy through every
  retry, it ends `failed` with `stop_reason: "core_busy"`, its cohort
  unused too;
- with an API key or OAuth token (and so over MCP), a test run returns its
  totals only: pass rate, verdict counts, failures by severity and kind,
  latency and cost, with `"hidden": true`. People signed in to the
  dashboard see every example.

On the dev split, an example copied from a held-out caller's call (their
caller sits in another agent's test split; see [held-out
calls](/api-reference/conversations#dev-and-test-splits)) reaches API keys
and OAuth tokens as its `example_id` and `"held_out": true` only, and is
left out of the summary and flips; the run says how many with
`held_out_example_count`.

A change made after reading test results is measured on a fresh cohort.

### One run or job at a time

An agent runs one replay run or one [conversation
job](/api-reference/conversations#retrieve-a-job) (generate, import or
refresh) at a time, so a refresh never rewrites the examples a replay is
running on. A start while a replay run is going is refused with `409
replay_run_active` (`existing_run_id`), and while a conversation job is
going with `409 conversation_job_active` (`existing_job_id`). Wait for it to
finish, then start again with the same `quote_id`. A run whose worker
stopped and did not come back within minutes does not block: the next
start replaces it.

### Data lifecycle

When a call's recording is turned off, or the call is deleted, the test
conversations imported from it, their examples, the examples promoted
straight from the call, those examples' replay results and Core's replay
cache for the call are removed. A purge that fails is retried until it
finishes, and the replay cache is swept once more an hour later, for a
replay that was still running. Until then a result of such an example
returns its `verdict` and ids only, with `content_withheld:
"recording_disabled"`, to every caller.

### PHI

Each example replays under its source call's PHI designation, the one the
call ran with; an example whose call recorded none replays as PHI. When any
sampled example, the deployed agent or the draft is PHI, every
configuration runs as PHI, and one that a PHI call cannot run (an
ElevenLabs voice, an experimental product, an audio or endpointing tier
without a BAA) is refused with `400` and the reason rather than replayed
under its label with something else.

### `dry_run`, `quote_id` and `max_cost_cents`

Replays and judging spend credits. Send the request with `"dry_run": true`
first: the response is the estimate, how many examples were sampled, the
`sample_seed` it drew, which engine each configuration would use, and a
`quote_id`, and nothing runs. For the test split it also gives the cohort
the run would spend (`test_cohort`: its `number` and `example_count`) and
how many unused cohorts are left (`test_cohorts_left`), or `409
no_test_cohort` when there is none.

A real run sends the same request again without `dry_run`, with that
`quote_id` and `sample_seed`, so it replays exactly the quoted sample. The
`quote_id` is good for 15 minutes, for this agent and request only (the
configurations and overrides, split, engine, configuration source, sample
size and seed or test cohort, baseline run), and for one run: it is used up
once, durably, in the transaction that creates the run, and a second run
with it is refused with `quote_used`. A start that is refused or fails
before the run exists, such as `409 replay_run_active` or a database
error, leaves it usable. Once the run exists the quote is spent, so a run
that then fails or stops is repeated with a new dry run and its new
`quote_id`. It is refused when it is missing,
expired or forged, when the request or the replay prices differ, or when
the run would now cost more than it quoted (the prompt or the examples
changed since). A test run quoted on a cohort that another test run
claimed meanwhile is refused with `quote_mismatch`: quote again.

The real run also needs `max_cost_cents`, a cap in US cents from 1 to 100,000,
shared by every configuration of a comparison. The cap is hard. Before
each request (a replay, then the judge's read of its reply) the run sets
aside the most that request can cost, and stops instead of sending one
that does not fit: the example is `skipped` with `skipped_reason:
"cost_cap"`, every example after it too, and the run's `stop_reason` is
`cost_cap`. What the requests really cost is then booked from their usage,
and that is what the run is charged. A text replay runs under a token
budget the agent's model is held to. An exact replay carries a hard budget
that Core enforces on every model and Decisions request of the replayed
turn, sized for a normal turn: each span's reply race and end-of-speech
checks, the hearing tier's fork, on a Lite configuration one more reply
leg per span (the standard lane takes over a reply that is only a tool
call), one watchdog or failover leg, and one
re-run of the kind production takes (the reply race again, after a spoken
tool call on every leg, an empty reply or the language-switch guard, and
the watchdog's retry), counted in UTF-8 bytes; its transcript seats are
bounded by the turn's audio. The run sets aside that budget at the prices
of the models the configuration can reach, plus the seats:
about 85 cents to $1.25 per exact replay for a typical turn,
against a real cost of a few cents. A trace that does not
confirm the budget is booked at that set-aside; on the dev split the rest
of the run replays as text (`engine_fallback:
"core_did_not_enforce_replay_limits"`), and a test run is refused. A turn
that needs more than its budget (a second re-run, more retries) has the
extra request refused by Core and is an `error` with `error_code:
"replay_budget_exhausted"`, not a verdict, since its reply may not be what
a call would say; the summary counts it as `budget_exhausted`, outside the
pass rate. On the test split such a result keeps nothing of the replay and
spends no cohort, so a test run whose only results are such turns hands
its cohort back unused. A request that costs more than its set-aside stops the run
(`stop_reason: "cost_over_bound"`).

Because of the set-aside, a run stops with up to one request's bound per
worker unspent. A set-aside is released when its request ends, and each
worker replays one example at a time, so a cap only needs the expected
spend plus one set-aside per concurrent worker. The dry run's
`largest_reservation_cents` is the largest single request,
`concurrent_workers` how many examples the run replays at once, and
`suggested_max_cost_cents` the cap that lets it finish:
`estimated_cost_cents` plus `concurrent_workers` times
`largest_reservation_cents`. With exact replays, that is well above what
the run will be charged, and a cap below it can stop the run early.
`upper_bound_cents` is the most the run can spend, every request at its
bound, and `min_max_cost_cents` is the smallest cap that starts anything.
Replays reuse stored work, so a run usually costs less than its estimate.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/agents/{agent_id}/replay-runs` | Start a replay run or a comparison, or estimate one |
| `GET` | `/v1/agents/{agent_id}/replay-runs` | The agent's 20 most recent replay runs |
| `GET` | `/v1/replay-runs/{run_id}` | One run with its results |
| `GET` | `/v1/replay-run-groups/{group_id}` | A comparison: each configuration side by side |

## Start a replay run

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/agents/123/replay-runs \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"split": "dev", "sample_size": 20, "dry_run": true}'
```

```python Python
estimate = requests.post(
    "https://api.thunderphone.com/v1/agents/123/replay-runs",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={"split": "dev", "sample_size": 20, "dry_run": True},
).json()

run = requests.post(
    "https://api.thunderphone.com/v1/agents/123/replay-runs",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={
        "split": "dev",
        "sample_size": 20,
        "sample_seed": estimate["sample_seed"],
        "quote_id": estimate["quote_id"],
        "max_cost_cents": 200,
    },
).json()
```
</CodeGroup>

### Request fields

| Field | Type | Description |
|-------|------|-------------|
| `split` | string | `dev` (default) or `test` |
| `engine` | string | `auto` (default), `exact` or `text` |
| `config_source` | string | Start from the agent's `draft` (default) or its `deployed` configuration |
| `overrides` | object | Changes to that configuration for this run; see [Overrides](#overrides). Not with `configs` |
| `label` | string | Your name for the run, up to 100 characters |
| `configs` | object[] | 2 to 4 configurations, each `{label, overrides}`, replayed on the same examples. The first is the baseline. Starts a [comparison](#compare-configurations); dev split only |
| `sample_size` | integer | Examples to replay, 1 to 200. Default 20. Ignored on the test split, which replays one whole test cohort |
| `sample_seed` | integer | The same seed draws the same examples. A dry run returns the seed it drew with. Ignored on the test split |
| `max_cost_cents` | integer | Spend cap, 1 to 100,000; required unless `dry_run`. A hard cap; it only needs the expected spend plus the dry run's `largest_reservation_cents` per concurrent worker, which the dry run returns as `suggested_max_cost_cents` |
| `dry_run` | boolean | Return the estimate and a `quote_id` only |
| `quote_id` | string | The `quote_id` of a dry run of this same request; required unless `dry_run`, and good for one run. Send the dry run's `sample_seed` with it |
| `baseline_run_id` | integer | An earlier replay run of this agent on the same split; the run reports the examples fixed and broken against it |

Examples are drawn by weight: recent conversations, real calls, conversations
that match the newest prompt revisions, and conversations that have been
rewritten least come first. Examples from calls whose recording was later
turned off are left out, and removed (see [Data
lifecycle](#data-lifecycle)).

### Overrides

| Field | Description |
|-------|-------------|
| `prompt` | A candidate prompt instead of the configuration's. The run records it as a `candidate` [prompt revision](/api-reference/prompt-revisions) without changing the draft |
| `product` | The product tier, as the agent's `product` field |
| `thinking_level` | `base` or `extra` |
| `storm_feedback_mode` | `acknowledgement`, `tick` or `none`: what the caller hears while a slow reply is prepared |
| `voice` | A voice name |
| `language` | The language the call runs in |
| `audio_tier` | The Bolt v2 audio tier: `lean`, `standard`, `hearing` or `deep_hearing` (not generally available). Plain Bolt only; a configuration on another product that sets `lean`, `hearing` or `deep_hearing` is refused with `400`, and `standard` passes. With `deep_hearing`, an `intelligence` other than `standard` is refused |
| `endpointing` | The Bolt v2 endpointing tier, how long the caller must stay quiet before the reply request: `faster`, `fast`, `normal` or `patient` |
| `intelligence` | The Bolt v2 intelligence tier, the model that writes the replies: `lite` or `standard`. Plain Bolt on v2 only; a configuration on another product that sets `lite` is refused with `400`, and `standard` passes |

An override applies where the agent's own field would, so it passes
through the same composition and voice rules a call does. `null` means the
configuration's own value.

### Responses

A dry run returns `200`:

```json
{
  "dry_run": true,
  "split": "dev",
  "engine": "auto",
  "phi_mode": "phi",
  "sample_seed": 1802233117,
  "max_cost_cents": null,
  "example_count": 20,
  "configs": [
    { "label": "", "overrides": {}, "engines": { "exact": 14, "text": 6, "skipped": 0 }, "estimated_cost_cents": 128.94, "upper_bound_cents": 1881.97 }
  ],
  "estimated_cost_cents": 128.94,
  "upper_bound_cents": 1881.97,
  "largest_reservation_cents": 103.605,
  "min_max_cost_cents": 104,
  "concurrent_workers": 2,
  "suggested_max_cost_cents": 337,
  "judge_max_completion_tokens": 4000,
  "notes": [
    "Exact replays are estimated with an empty stage cache; the judge at its output bound.",
    "max_cost_cents is a hard cap: each request reserves its upper bound before it is sent and is refused when that does not fit what is left, and the run then stops. A reservation is released when its request ends, and this run replays 2 examples at a time, so a cap only needs the expected spend plus one largest_reservation_cents per concurrent worker: set max_cost_cents to about suggested_max_cost_cents (337), estimated_cost_cents plus 2 times largest_reservation_cents. upper_bound_cents is the most the run can spend.",
    "Both engines run under a token budget Core enforces (replay_limits): …"
  ],
  "quote_id": "eyJvcmciOjQyLC…",
  "quote_expires_in_seconds": 900,
  "next_step": "Show this estimate, then run again with the same request and this sample_seed, without dry_run, with this quote_id and with max_cost_cents."
}
```

This is the estimator's answer for 14 examples with recorded caller audio
and 6 text-only ones, under a Bolt v2 draft with a 10 KB prompt, replayed as
PHI: each exact replay sets aside about a dollar (`largest_reservation_cents`)
and costs a few cents, so a cap of `estimated_cost_cents` plus one
set-aside for each of its two workers (`suggested_max_cost_cents`) lets
the run finish; `min_max_cost_cents` is only the floor.

A test-split dry run adds `test_cohort` (`{"number": 3, "example_count":
41}`) and `test_cohorts_left`.

A real run returns `201` with the [run](#replay-run-object), status
`pending`. A comparison returns `201` with the
[comparison](#compare-configurations). Poll until the status is `completed`
or `failed`.

## Replay run object

`GET /v1/replay-runs/{run_id}` returns the run with its results. Add
`include_trace=true` for Core's full trace of each exact replay instead of
its summary.

```json
{
  "id": 9031,
  "agent_id": 123,
  "label": "shorter callback rule",
  "split": "dev",
  "engine": "auto",
  "config_source": "draft",
  "config_overrides": {},
  "status": "completed",
  "stale": false,
  "degraded": false,
  "stop_reason": null,
  "error_message": null,
  "compare_group_id": null,
  "baseline_run_id": 9020,
  "prompt_revision_id": 4182,
  "prompt_hash": "5b0e…",
  "sample_seed": 1802233117,
  "sample_size": 20,
  "max_cost_cents": 200,
  "estimated_cost_cents": 93.0,
  "cost_cents": 51.6,
  "test_cohort": null,
  "created_at": "2026-10-19T17:10:02Z",
  "started_at": "2026-10-19T17:10:03Z",
  "completed_at": "2026-10-19T17:14:40Z",
  "summary": {
    "total": 20,
    "replayed": 20,
    "phi_mode": "no_phi",
    "verdicts": { "pass": 16, "warn": 2, "fail": 2, "error": 0, "skipped": 0 },
    "budget_exhausted": 0,
    "pass_rate": null,
    "by_engine": {
      "exact": { "verdicts": { "pass": 12, "warn": 1, "fail": 1, "error": 0, "skipped": 0 }, "budget_exhausted": 0, "pass_rate": 0.857 },
      "text": { "verdicts": { "pass": 4, "warn": 1, "fail": 1, "error": 0, "skipped": 0 }, "budget_exhausted": 0, "pass_rate": 0.667 }
    },
    "degraded": false,
    "failures": { "by_severity": { "fail": 2, "warn": 2 }, "by_kind": { "missed_instruction": 3, "two_questions": 1 } },
    "engine_fallbacks": 0,
    "latency_to_first_audio_s": { "p50": 0.94, "p90": 1.61 },
    "latency_to_reply_audio_s": { "p50": 1.42, "p90": 2.37 },
    "wait_cover_share": { "acknowledgement": 0.07, "ticks": 0.0, "silence": 0.93, "filler": 0.0, "none": 0.0 },
    "fork_rate": 0.07,
    "cost_cents": 51.6,
    "cost_per_turn_cents": 2.58
  },
  "flips": { "baseline_run_id": 9020, "by_engine": { "exact": { "compared": 13, "fixed": [5102, 5110], "broken": [5131] }, "text": { "compared": 6, "fixed": [], "broken": [] } }, "not_comparable": 0 },
  "results": [
    {
      "example_id": 5131,
      "verdict": "fail",
      "engine_used": "exact",
      "engine_fallback": null,
      "exact_unavailable": null,
      "skipped_reason": null,
      "error": null,
      "expectation": "Confirm the callback number digit by digit before ending the call.",
      "accepted_responses": [{ "spoken_response": "Just to confirm, that's five five five, zero one four seven?", "tool_calls": [], "does": "Reads the number back before ending the call.", "required_values": ["5550147"], "basis": "" }],
      "original_response": { "spoken_response": "Great, we'll call you back soon. Anything else?", "tool_calls": [] },
      "replayed_output": { "spoken_response": "Thanks, we'll call you back. Goodbye.", "tool_calls": [] },
      "instruction_verdict": { "status": "fail", "summary": "The agent ended the call without confirming the callback number.", "issues": [{ "severity": "fail", "type": "missed_instruction", "explanation": "The prompt asks to read the number back before ending the call.", "evidence": "Thanks, we'll call you back. Goodbye." }], "confidence": 0.9 },
      "metrics": { "first_audio_s": 0.91, "reply_audio_s": 1.38, "wait_cover": "silence", "forked": false },
      "cost_cents": 4.5,
      "source_call_id": 88213,
      "caller": { "text": "Yeah, just have someone call me back at five five five, zero one four seven.", "span_indices": [6] },
      "trace_summary": { "reply": "…", "wait_cover": "…", "end_of_speech": "…" }
    }
  ]
}
```

| Field | Description |
|-------|-------------|
| `status` | `pending`, `running`, `completed` or `failed` |
| `stop_reason` | Why the run stopped early: `cost_cap` (the next request did not fit `max_cost_cents`), `cost_over_bound` (a request cost more than its set-aside), `core_limits_unsupported` (the text replay was not held to its token budget) or, for a test run, `exact_replay_unavailable` (Core could not replay its examples exactly under a confirmed budget) or `core_busy` (Core's replay capacity stayed busy); either test stop leaves the run `failed` and its cohort unused |
| `stale` | `true` while the run's worker has stopped; it resumes within minutes, or a new run for the agent replaces it |
| `degraded` | `true` when an exact replay fell back to text (dev runs only) or nothing could be judged |
| `test_cohort` | A test run's cohort: its `number`, and `spent` once a result disclosed anything. `null` on the dev split |
| `prompt_revision_id` | The [prompt revision](/api-reference/prompt-revisions) the run tested |
| `summary.pass_rate` | Passes over judged examples, errors included, when one engine replayed every example; `null` when exact and text both ran (read `summary.by_engine`) or before any is judged |
| `summary.by_engine` | Verdicts and pass rate per engine (`exact`, `text`); exact and text verdicts are never mixed into one number |
| `summary.budget_exhausted` | Exact replays that needed more than their budget (`error_code: "replay_budget_exhausted"`), counted apart from the verdicts and outside the pass rate; also per engine |
| `summary.phi_mode` | The PHI designation the configuration ran under |
| `summary.latency_to_first_audio_s` | p50 and p90 seconds from the caller's last speech to the agent's first audio, over exact replays |
| `summary.wait_cover_share` | Over exact replays, how often the caller waited on an acknowledgement, ticks, silence or filler |
| `flips` | Against `baseline_run_id`, per engine: how many examples both runs judged on that engine, and the ids now passing (`fixed`) and now failing (`broken`). An example judged on different engines counts in `not_comparable`. Dev runs only |
| `results[].engine_fallback` | Why an exact replay ran as text instead (dev runs only): `core_has_no_replay_endpoint`, `core_did_not_enforce_replay_limits` or `turn_audio_unreadable` |
| `results[].error_code` | `replay_budget_exhausted` when the replayed turn needed more than its budget and Core refused the extra request; the result is an `error`, not a verdict |
| `results[].exact_unavailable` | Why `auto` chose text: `configuration_not_bolt_v2` or `no_turn_audio` |
| `results[].skipped_reason` | `cost_cap` (or the run's other `stop_reason`), `configuration_not_bolt_v2` or `no_turn_audio` (with `engine: "exact"`), `core_busy` (Core's replay capacity stayed busy; nothing ran or was charged), `recording_disabled`, or `history_audio_missing` |
| `results[].content_withheld` | `recording_disabled` when the example's source call turned recording-disabled after the run judged it: the result keeps its `verdict` and ids, and its expectation, answer key, replies, instruction verdict, metrics and trace are empty, for every caller |
| `results[].accepted_responses` | The example's answer key: the replies the judge accepts at that moment (`spoken_response`, `tool_calls`, what the reply `does`, `required_values`, and the prompt passage it rests on as `basis`). Empty for an example without one |
| `results[].original_response` | What the agent said and which tools it called at that moment originally (`spoken_response`, `tool_calls`) |
| `results[].replayed_output` | The same for the replay |
| `results[].caller` | The caller turn the reply answers: `text`, the caller's words (read from the source call's transcript for recorded audio; empty when it is gone), and `span_indices`, the pinned audio spans that hold them (`GET /v1/validation-examples/{id}/audio/{span_index}`). Absent when `content_withheld` is set |
| `results[].source_call_id` | The call the example was copied from, or `null` for simulated content |

A test-split run read with an API key has no `flips` or `results`, and has
`"hidden": true`.

`GET /v1/agents/{agent_id}/replay-runs` returns `{"runs": [...]}`, the
agent's 20 most recent runs without results.

## Compare configurations

Send `configs` instead of `overrides` to replay the same examples under 2
to 4 configurations. One run is created per configuration; the first is the
baseline, and every other run reports its flips against it. Comparisons run
on the dev split only; on the test split they are refused with `400
comparison_dev_only`. Check the
configuration before blaming the prompt: some failures belong to the
setup, such as mishearing spelled letters on a lower audio tier, or a slow
reply, or one that cuts the caller off, from the endpointing tier.

```json
{
  "configs": [
    { "label": "standard", "overrides": {} },
    { "label": "hearing", "overrides": { "audio_tier": "hearing" } }
  ],
  "sample_size": 30,
  "sample_seed": 77120394,
  "quote_id": "<quote_id of the dry run of this request>",
  "max_cost_cents": 400
}
```

The response, and `GET /v1/replay-run-groups/{group_id}`, is the comparison:

```json
{
  "id": "0f6b4f1e-9a51-4f7e-8a43-1c2a5d3e6b70",
  "agent_id": 123,
  "split": "dev",
  "engine": "auto",
  "config_source": "draft",
  "status": "running",
  "stop_reason": null,
  "sample_seed": 77120394,
  "sample_size": 30,
  "max_cost_cents": 400,
  "cost_cents": 12.4,
  "baseline_run_id": 9040,
  "configs": [
    { "run_id": 9040, "label": "standard", "overrides": {}, "baseline": true, "status": "running", "prompt_revision_id": 4182, "summary": { "pass_rate": null } },
    { "run_id": 9041, "label": "hearing", "overrides": { "audio_tier": "hearing" }, "baseline": false, "status": "pending", "prompt_revision_id": 4182, "summary": { "pass_rate": null }, "flips": null }
  ],
  "created_at": "2026-10-19T17:20:00Z"
}
```

Each configuration's `summary` has the fields of a
[run's summary](#replay-run-object), so pass rate, latency, wait cover and
cost per turn line up side by side. `GET /v1/replay-runs/{run_id}` for any
run of the comparison also returns the comparison as `group`.

## Errors

| Status | Condition |
|--------|-----------|
| `400` | An unknown field or a value out of range, an unsupported override, `max_cost_required` (a real run without `max_cost_cents`), `max_cost_below_minimum` (a `max_cost_cents` below the quote's `min_max_cost_cents`, which the response repeats: no replay could start), `no_examples` (the dev split has no examples yet), `configuration_refused` (a configuration a PHI replay cannot run, with the reason), `comparison_dev_only` (`configs` on the test split), `test_engine_per_example` (an `engine` other than `auto` on the test split), or a `baseline_run_id` that is not a run of this agent on the same split |
| `403` | `insufficient_scope`: an OAuth token without `testing:write` (`testing:read` to read runs) |
| `403` | `feature_not_enabled`: the organization does not have the agent iteration toolkit |
| `404` | The agent, run or comparison is not in this organization |
| `400` | `quote_required`, `quote_expired`, `quote_invalid`, `quote_mismatch` (another agent or request, the prices changed, or another test run took the quoted cohort), `quote_outdated` (the run would now cost more than quoted) or `quote_used` (the quote already paid for a run): run the dry run again and send its `quote_id` and `sample_seed` |
| `409` | `replay_run_active`: the agent already has a run going (`existing_run_id`). `conversation_job_active`: the agent has a conversation job going (`existing_job_id`). `no_test_cohort`: no unused test cohort is left, or none is full yet. `test_cohort_changed`: another test run claimed the cohort first. `test_cohort_empty`: the next cohort's conversations have no examples yet. `test_needs_exact_replay`: the test cohort holds recorded caller audio and the configuration has no exact path (anything but Bolt v2); nothing ran and the cohort stays unused, so measure it on the dev split |
| `503` | `quote_unverifiable`: the quote could not be recorded as used right now, so nothing ran; retry with it |
| `429` | `replay_run_limit`: the organization already has 8 replay runs going |

Every error body has a `detail`; most also have a `code` and a `next_step`.

## MCP

The [MCP server](/guides/thunderphone-mcp-server) exposes these as
`run_replays`, `compare_configs` and `get_replay_run`.

---

## Related

<CardGroup cols={2}>
  <Card title="Test Conversations" icon="comments" href="/api-reference/conversations">
    Where the examples come from.
  </Card>
  <Card title="Prompt Revisions" icon="clock-rotate-left" href="/api-reference/prompt-revisions">
    The prompt text each run tested.
  </Card>
</CardGroup>

<!-- en: api-reference/billing -->
---
title: "Billing"
description: "Inspect your prepaid balance, top up by card, configure auto-reload thresholds and amounts, and list every transaction behind your organization's usage."
---

ThunderPhone is prepaid. Each organization carries a USD balance that
decrements as calls are placed; if the balance reaches `$0.00`, inbound
calls are rejected and outbound calls return `402 Payment Required`.
These endpoints let you query balance state, top up via Stripe, and
configure automatic reloads.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/billing` | Get billing account state |
| `PATCH` | `/v1/billing` | Update auto-reload settings |
| `POST` | `/v1/billing/top-up` | Create a top-up payment intent (one-time charge) |
| `POST` | `/v1/billing/setup-intent` | Create a Stripe SetupIntent for saving a card |
| `POST` | `/v1/billing/default-payment-method` | Set the default payment method |
| `GET` | `/v1/billing/payment-methods` | List saved cards |
| `DELETE` | `/v1/billing/payment-methods/{payment_method_id}` | Remove a saved card |
| `GET` | `/v1/billing/transactions` | List balance transactions |
| `GET` | `/v1/billing/transactions/{transaction_id}/receipt` | Get the receipt link for a top-up |

<Warning>
  The `GET` endpoints work with an `sk_live_` API key. Everything that
  moves money or changes how it moves (auto-reload and the monthly limit,
  top-ups, saving, removing, or choosing the default card) returns `403` to
  an API key and needs a signed-in admin session (`Authorization: Token
  <session-token>` plus `X-ThunderPhone-Org`), so a leaked key can't top up
  from your card or raise your limits. Most teams do this in the dashboard
  under **Organization → Billing Settings**. See
  [What API keys can't do](/api-reference/introduction#what-api-keys-cant-do).
</Warning>

## Billing account object

```json
{
  "balance_cents": 125000,
  "balance_usd": "1250.00",
  "currency": "usd",
  "auto_reload_enabled": true,
  "auto_reload_minimum_cents": 1000,
  "auto_reload_amount_cents": 5000,
  "auto_reload_monthly_limit_cents": null,
  "auto_reload_status": "ok",
  "auto_reload_next_retry_at": null,
  "auto_reload_failed_amount_cents": null,
  "auto_reload_failed_at": null,
  "auto_reload_consecutive_declines": null,
  "last_auto_reload": {
    "amount_cents": 5000,
    "created_at": "2026-09-20T14:02:11.482Z"
  },
  "auto_reload_month_spend_cents": 5000,
  "month_spend_cents": 1170,
  "average_daily_spend_cents_7d": 390,
  "balance_runway_days": 320,
  "last_top_up": {
    "amount_cents": 5000,
    "created_at": "2026-09-20T14:02:11.482Z",
    "kind": "auto"
  },
  "has_payment_method": true,
  "has_ever_topped_up": true
}
```

| Field | Type | Description |
|-------|------|-------------|
| `balance_cents` | integer | Current balance in USD cents |
| `balance_usd` | string | Formatted, e.g. `"1250.00"` |
| `currency` | string | Always `usd` |
| `auto_reload_enabled` | boolean | Whether automatic top-ups are on. Turned off automatically when a top-up is refunded or disputed; set it back to `true` to resume |
| `auto_reload_minimum_cents` | integer | Balance threshold that triggers a reload |
| `auto_reload_amount_cents` | integer | Amount to charge on reload |
| `auto_reload_monthly_limit_cents` | integer \| null | Cap on auto-reload spend per calendar month. `null` = no cap. Sending `0` is treated as `null` |
| `auto_reload_status` | string | Read-only. `off` (auto-reload disabled), `ok`, `retrying` (the default card was declined, or Stripe could not charge it at all, in which case `auto_reload_failure_code` is `payment_method_unusable`; the next attempt waits out a 1h / 6h / 24h backoff), `stopped` (the bank refused the default card outright, or the card was declined 5 times in a row, in which case `auto_reload_failure_code` is `repeated_declines`; it is not retried until you set another default card, the card's details are updated, or a manual top-up succeeds), or `capped` (this month's auto-reloads plus `auto_reload_amount_cents` would exceed `auto_reload_monthly_limit_cents`, so no auto-reload runs until the next calendar month in UTC or a higher limit) |
| `auto_reload_next_retry_at` | string \| null | Read-only. ISO 8601 end of the current backoff while `retrying`. Can be in the past: the retry runs on the next call after it, including a call attempt that is rejected because the balance is below zero |
| `auto_reload_failed_amount_cents` | integer \| null | Read-only. Amount the declined auto-reload tried to charge, while `retrying` or `stopped` |
| `auto_reload_failed_at` | string \| null | Read-only. ISO 8601 time of the latest decline, while `retrying` or `stopped` |
| `auto_reload_consecutive_declines` | integer \| null | Read-only. Failed auto-reloads in a row on the current default card, while `retrying` or `stopped`; `null` otherwise |
| `last_auto_reload` | object \| null | Read-only. `amount_cents` and `created_at` of the newest successful auto-reload, or `null` before the first one |
| `auto_reload_month_spend_cents` | integer | Read-only. Auto-reload credits this calendar month (UTC), as `auto_reload_monthly_limit_cents` counts them |
| `month_spend_cents` | integer | Read-only. Usage charges (calls, phone-number rent, conversion reports, voice samples) this calendar month in the organization's reporting time zone, today included. Top-ups, auto-reloads and adjustments are excluded |
| `average_daily_spend_cents_7d` | integer \| null | Read-only. Usage charges over last week, the 7 whole days ending yesterday in the organization's reporting time zone, averaged per day of history (7 days, or the account's age if younger, at least 1 day; an account opened today counts today so far as one day), rounded. Top-ups, auto-reloads and adjustments are excluded. `null` when there was no usage in that window |
| `balance_runway_days` | integer \| null | Read-only. Whole days `balance_cents` lasts at that daily average (`0` means less than a day). `null` when the balance is zero or negative or there was no recent usage |
| `last_top_up` | object \| null | Read-only. `amount_cents`, `created_at` and `kind` (`manual` or `auto`) of the newest successful top-up, or `null` before the first one |
| `has_payment_method` | boolean | Derived — true iff a default Stripe payment method is set |
| `has_ever_topped_up` | boolean | Derived — true once the account has at least one successful manual top-up or auto-reload |

---

## Get billing account

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/billing \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Returns `200 OK` with a [Billing account object](#billing-account-object).

---

## Update auto-reload

Enable, disable, or reconfigure automatic balance reloads. A
payment method must be on file (`has_payment_method: true`) before
`auto_reload_enabled` can be set to `true` — otherwise the server
returns `422 Unprocessable Entity` with
`{"detail": "Auto-reload requires a default payment method. Create a setup intent first."}`.

<CodeGroup>
```bash Enable auto-reload
curl -X PATCH https://api.thunderphone.com/v1/billing \
  -H "Authorization: Token YOUR_SESSION_TOKEN" \
  -H "X-ThunderPhone-Org: 42" \
  -H "Content-Type: application/json" \
  -d '{
    "auto_reload_enabled": true,
    "auto_reload_minimum_cents": 1000,
    "auto_reload_amount_cents": 5000,
    "auto_reload_monthly_limit_cents": 50000
  }'
```

```bash Disable auto-reload
curl -X PATCH https://api.thunderphone.com/v1/billing \
  -H "Authorization: Token YOUR_SESSION_TOKEN" \
  -H "X-ThunderPhone-Org: 42" \
  -H "Content-Type: application/json" \
  -d '{"auto_reload_enabled": false}'
```
</CodeGroup>

| Field | Type | Required when enabling |
|-------|------|------------------------|
| `auto_reload_enabled` | boolean | |
| `auto_reload_minimum_cents` | integer ≥ 0 | yes — triggers a reload once balance drops below |
| `auto_reload_amount_cents` | integer > 0 | yes — amount charged on reload |
| `auto_reload_monthly_limit_cents` | integer ≥ 0, or `null` | no — `null` means unlimited |

Returns `200 OK` with the updated [Billing account object](#billing-account-object).

---

## Top up balance

Create a one-time charge to increase your balance. Uses the default
payment method unless `payment_method_id` is supplied.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/billing/top-up \
  -H "Authorization: Token YOUR_SESSION_TOKEN" \
  -H "X-ThunderPhone-Org: 42" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents": 10000}'
```

```python Python
result = requests.post(
    "https://api.thunderphone.com/v1/billing/top-up",
    headers={"Authorization": "Token YOUR_SESSION_TOKEN", "X-ThunderPhone-Org": "42"},
    json={"amount_cents": 10000},
).json()
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `amount_cents` | integer ≥ 1 | yes | USD cents. No server-enforced maximum; the dashboard suggests common amounts |
| `payment_method_id` | string | no | Stripe PM id. Defaults to the org's default |

Returns `201 Created`:

```json
{
  "payment_intent_id": "pi_abc123",
  "status":            "succeeded",
  "client_secret":     "pi_abc123_secret_..."
}
```

| Field | Type | Description |
|-------|------|-------------|
| `payment_intent_id` | string | Stripe PaymentIntent id |
| `status` | string | Mirrors Stripe's own `PaymentIntent.status` — typically `succeeded`, `requires_action`, or `requires_payment_method` |
| `client_secret` | string | Pass to Stripe.js / stripe-react on the client side if `status === "requires_action"` (3DS) |

When `status === "succeeded"` the balance is credited synchronously
from the request. When `status === "requires_action"`, complete the
3DS flow client-side and wait for the `payment_intent.succeeded`
webhook — then poll [`GET /v1/billing`](#get-billing-account) to
observe the credit.

### Errors

Validation problems (e.g. a missing or non-positive `amount_cents`)
return `400` with a standard DRF field-error body:

```json
{ "amount_cents": ["Ensure this value is greater than or equal to 1."] }
```

Payment failures return a structured error body with a
machine-readable `code`, plus `message`/`detail`, a `retryable` hint,
and a `next_action` your client can act on:

```json 402 example
{
  "code": "payment_authentication_required",
  "message": "This card requires additional verification. Please retry and complete authentication when prompted.",
  "detail": "This card requires additional verification. Please retry and complete authentication when prompted.",
  "retryable": true,
  "next_action": "authenticate_payment"
}
```

| Status | `code` | `retryable` | `next_action` | Condition |
|--------|--------|-------------|---------------|-----------|
| `402` | `payment_authentication_required` | `true` | `authenticate_payment` | 3-D Secure / SCA required — complete authentication client-side with the PaymentIntent's `client_secret`, then retry |
| `402` | `card_declined` | `false` | `update_payment_method` | The bank declined the card (all decline reasons are collapsed into this one code) |
| `422` | `billing_request_invalid` | `false` | `update_payment_method` | Stripe rejected the request (bad parameters, unknown customer) |
| `503` | `billing_provider_unavailable` | `true` | `retry_payment` | Transient Stripe outage or rate limit; retry shortly |
| `502` | `billing_provider_error` | `true` | `retry_payment` | Any other unexpected Stripe error |

These same coded errors are returned by the other billing write
endpoints when they hit Stripe (`/setup-intent`,
`/default-payment-method`).

---

## Add / save a payment method

Two-step flow: create a SetupIntent, confirm it client-side, then set
the resulting payment-method id as the org's default.

### 1. Create a SetupIntent

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/billing/setup-intent \
  -H "Authorization: Token YOUR_SESSION_TOKEN" \
  -H "X-ThunderPhone-Org: 42"
```
</CodeGroup>

```json Response
{
  "setup_intent_id": "seti_abc123",
  "client_secret": "seti_abc123_secret_...",
  "status": "requires_payment_method"
}
```

### 2. Confirm client-side with Stripe.js

See the [Stripe documentation](https://docs.stripe.com/js/setup_intents/confirm_card_setup)
for `stripe.confirmCardSetup()`. On success you receive a
`payment_method` id.

### 3. Mark the payment method as default

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/billing/default-payment-method \
  -H "Authorization: Token YOUR_SESSION_TOKEN" \
  -H "X-ThunderPhone-Org: 42" \
  -H "Content-Type: application/json" \
  -d '{"payment_method_id": "pm_abc123"}'
```
</CodeGroup>

Returns `200 OK` with the updated [Billing account object](#billing-account-object);
`has_payment_method` is now `true`.

To switch the default to a card that is already saved, call this endpoint
with that card's id from [List saved cards](#list-saved-cards).

---

## List saved cards

Returns every card saved on the organization, the default first and the
rest newest first. Top-ups and auto-reloads charge the default card.
Requires the admin or owner role.

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/billing/payment-methods \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

```json Response
{
  "payment_methods": [
    {
      "id": "pm_abc123",
      "brand": "visa",
      "last4": "4242",
      "exp_month": 4,
      "exp_year": 2031,
      "is_default": true,
      "is_backup": false
    },
    {
      "id": "pm_def456",
      "brand": "mastercard",
      "last4": "4444",
      "exp_month": 12,
      "exp_year": 2030,
      "is_default": false,
      "is_backup": true
    }
  ]
}
```

`is_backup` marks the backup card: when the bank declines the default card
during an auto-reload, that auto-reload charges the backup card once
instead. Manual top-ups never use it. An admin sets the backup in the
dashboard's billing settings. An organization that has never saved a card
gets an empty list.

---

## Remove a saved card

Detaches the card from the organization. This cannot be undone; save the
card again to use it later. Requires the admin or owner role.

<CodeGroup>
```bash cURL
curl -X DELETE https://api.thunderphone.com/v1/billing/payment-methods/pm_def456 \
  -H "Authorization: Token YOUR_SESSION_TOKEN" \
  -H "X-ThunderPhone-Org: 42"
```
</CodeGroup>

Returns `204 No Content`.

| Status | `code` | Meaning |
|--------|--------|---------|
| `404` | — | No saved card with that id on this organization |
| `409` | `default_payment_method` | The card is the default. Set another card as default first |
| `409` | `payment_method_in_use` | An auto-reload is charging this card right now. Retry shortly |

---

## List transactions

Returns every ledger entry on the account — top-ups, per-call usage,
monthly number fees, and manual adjustments — newest first.

<CodeGroup>
```bash cURL
curl 'https://api.thunderphone.com/v1/billing/transactions?limit=200' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

```python Python
txns = requests.get(
    "https://api.thunderphone.com/v1/billing/transactions",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    params={"limit": 200},
).json()
```
</CodeGroup>

### Query parameters

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `limit` | integer | 200 | 1–1000 |
| `offset` | integer | 0 | |
| `kind` | string | | Filter to one [transaction kind](#transaction-object) |
| `start_date` | ISO 8601 | | Filter on `created_at` |
| `end_date` | ISO 8601 | | |

The response is a **plain JSON array** of transaction objects (no
`{results, total}` envelope). Page forward by increasing `offset`
until you receive fewer rows than `limit`.

### Transaction object

```json
{
  "id": 3421,
  "kind": "call_usage",
  "description": "Call usage — metered",
  "amount_cents": -18,
  "amount_usd": "-0.18",
  "call_id": 987654321,
  "phone_number_id": 201,
  "phone_number_value": "+15551234567",
  "metadata": {},
  "has_receipt": false,
  "created_at": "2026-04-20T18:25:06.201Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Transaction id |
| `kind` | string | One of `manual_topup`, `auto_reload`, `call_usage`, `phone_number_monthly`, `conversion_report`, `adjustment` |
| `description` | string | Human-readable summary |
| `amount_cents` | integer | Negative for usage/fees, positive for credits |
| `amount_usd` | string | Formatted signed amount |
| `call_id` | integer \| null | Set on `call_usage` rows |
| `phone_number_id` | integer \| null | Set on `phone_number_monthly` rows |
| `phone_number_value` | string \| null | E.164 for the number billed |
| `metadata` | object | Kind-specific details |
| `has_receipt` | boolean | `true` on card-funded `manual_topup` and `auto_reload` credits. [Get a receipt](#get-a-receipt) for these rows |
| `payment_method_brand` | string \| null | Card brand charged for a `manual_topup` or `auto_reload` credit, such as `visa`. `null` on other rows and on older credits |
| `payment_method_last4` | string \| null | Last four digits of that card |
| `created_at` | timestamp | |

---

## Get a receipt

Returns a link to the payment receipt for a top-up or automatic top-up,
for rows where `has_receipt` is `true`. The receipt is hosted by our
payment processor, Stripe, and shows the amount, date, and card charged.
Owners and admins can fetch it; other members get `403`, because the receipt shows the card brand and last four digits.

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/billing/transactions/3398/receipt \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

```python Python
receipt = requests.get(
    "https://api.thunderphone.com/v1/billing/transactions/3398/receipt",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
).json()
print(receipt["receipt_url"])
```
</CodeGroup>

```json Response
{
  "receipt_url": "https://pay.stripe.com/receipts/payment/..."
}
```

| Status | `code` | Meaning |
|--------|--------|---------|
| `404` | — | No transaction with that id on this organization, or the transaction has no receipt |
| `404` | `receipt_unavailable` | The payment has no receipt yet. Try again later |

---

## Stripe webhook

ThunderPhone receives Stripe webhooks at
`/v1/stripe/webhook` internally — you don't interact with this endpoint
directly. It processes `payment_intent.succeeded`,
`payment_intent.payment_failed`, and `setup_intent.succeeded` events to
update balances and mark payment methods ready.

---

## Related

<CardGroup cols={2}>
  <Card title="Outbound Calls" icon="arrow-up-right" href="/api-reference/outbound-calls">
    Outbound calls require positive balance.
  </Card>
  <Card title="Pricing" icon="credit-card" href="https://thunderphone.com/pricing">
    Per-minute pricing by product tier.
  </Card>
</CardGroup>

<!-- en: api-reference/developer-api-keys -->
---
title: "API Keys"
description: "Create, list, rotate, and revoke the sk_live_ secret keys your server-side integrations use to call the ThunderPhone REST API on behalf of your organization."
---

API keys (`sk_live_...`) are the primary credential for the
ThunderPhone REST API. They are **secret** — treat them like a
password. Each key is bound to exactly one organization; when an API
call authenticates with a key, we look up the bound org automatically,
which is why the rest of this reference never asks for an org id in
the URL path.

This page documents the endpoints for **creating, listing, renaming and
revoking** keys — the same operations the dashboard exposes at
**Settings → Keys**. You can create your first key from the
dashboard without ever using this API.

## Endpoints

| Method | Path | Required role | Description |
|--------|------|---------------|-------------|
| `GET` | `/v1/whoami` | any authenticated role | Validate a connection and identify its organization |
| `GET` | `/v1/developer/api-keys` | `admin+` | List API keys |
| `POST` | `/v1/developer/api-keys` | `admin+` | Create a new API key |
| `PATCH` | `/v1/developer/api-keys/{key_id}` | `admin+` | Rename an API key |
| `DELETE` | `/v1/developer/api-keys/{key_id}` | `admin+` | Revoke an API key |

<Warning>
  The API-key list, create, rename and revoke endpoints require an `admin` or
  `owner` role and a signed-in session (`Authorization: Token
  <session-token>` plus `X-ThunderPhone-Org`). An `sk_live_` key gets `403`
  from all four, so a leaked key can't mint its own replacement or revoke
  yours. `GET /v1/whoami` is available to any authenticated role, API keys
  included. See
  [What API keys can't do](/api-reference/introduction#what-api-keys-cant-do).
</Warning>

## API key object

```json
{
  "id": "b1c2d3e4-...",
  "name": "production",
  "key_prefix": "sk_live_abcde12",
  "is_active": true,
  "created_at": "2026-04-20T18:24:10.113Z",
  "created_by_name": "Dana Reyes",
  "last_used_at": "2026-04-20T18:25:06.201Z",
  "revoked_at": null
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Public id used by the revoke endpoint |
| `name` | string | Display label |
| `key_prefix` | string | First 15 chars of the raw key for UI display (always `sk_live_` + 7 hex chars). The full key is NOT returned after creation |
| `is_active` | boolean | `false` once the key is revoked |
| `created_at` | timestamp | |
| `created_by_name` | string \| null | Who made the key: their name, or their email when they have no name. `null` when unknown or the person was removed |
| `last_used_at` | timestamp \| null | Updated best-effort on every successful request |
| `revoked_at` | timestamp \| null | If set, the key is revoked and will no longer authenticate |

---

## Validate a connection

`GET /v1/whoami` is a cheap credential check for integration setup. It
accepts an organization API key, a human session token with
`X-ThunderPhone-Org`, or an OAuth access token. OAuth tokens do not need an
additional product scope for this endpoint.

```bash
curl https://api.thunderphone.com/v1/whoami \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

```json Response
{
  "organization": {"id": 42, "name": "Example Co"},
  "credential_kind": "api_key",
  "key_label": "Zapier production",
  "key_prefix": "sk_live_abcde12",
  "oauth_client_id": null,
  "scopes": [],
  "role": "owner"
}
```

Only safe identifiers are returned. Raw keys and tokens are never included.
For OAuth, `oauth_client_id` and the access token's `scopes` are populated;
for human sessions, the key and OAuth fields are `null`.

---

## List API keys

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/developer/api-keys \
  -H "Authorization: Token YOUR_SESSION_TOKEN" \
  -H "X-ThunderPhone-Org: 42"
```
</CodeGroup>

Returns an array of [API key objects](#api-key-object) — both active
and revoked keys, sorted by `created_at` descending.

---

## Create an API key

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/developer/api-keys \
  -H "Authorization: Token YOUR_SESSION_TOKEN" \
  -H "X-ThunderPhone-Org: 42" \
  -H "Content-Type: application/json" \
  -d '{"name": "production"}'
```

```python Python
result = requests.post(
    "https://api.thunderphone.com/v1/developer/api-keys",
    headers={"Authorization": "Token YOUR_SESSION_TOKEN", "X-ThunderPhone-Org": "42"},
    json={"name": "production"},
).json()
new_key = result["key"]
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | no | Display label, 1–120 chars. Defaults to `"Default key"` |

Returns `201 Created` with the [API key object](#api-key-object) plus
an extra top-level `key` field containing the raw `sk_live_` value:

```json
{
  "id": "b1c2d3e4-...",
  "name": "production",
  "key_prefix": "sk_live_abcde12",
  "is_active": true,
  "created_at": "2026-04-20T18:24:10.113Z",
  "created_by_name": "Dana Reyes",
  "last_used_at": null,
  "revoked_at": null,
  "key": "sk_live_abcdef1234567890abcdef1234567890abcdef123456"
}
```

<Warning>
  **`key` is returned only once.** Store it in your secret manager
  immediately — if you lose it, revoke it and create a new one. Every
  subsequent `GET` returns only the `key_prefix`.
</Warning>

---

## Rename an API key

<CodeGroup>
```bash cURL
curl -X PATCH https://api.thunderphone.com/v1/developer/api-keys/b1c2d3e4-... \
  -H "Authorization: Token YOUR_SESSION_TOKEN" \
  -H "X-ThunderPhone-Org: 42" \
  -H "Content-Type: application/json" \
  -d '{"name": "Zapier production"}'
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | yes | The new label, 1–120 chars after trimming spaces |

Returns `200` with the [API key object](#api-key-object). The key itself
doesn't change, keeps working, and is never returned.

---

## Revoke an API key

<CodeGroup>
```bash cURL
curl -X DELETE https://api.thunderphone.com/v1/developer/api-keys/b1c2d3e4-... \
  -H "Authorization: Token YOUR_SESSION_TOKEN" \
  -H "X-ThunderPhone-Org: 42"
```
</CodeGroup>

Returns `204 No Content`. Revoked keys are permanently invalidated —
all future requests using the key return `401 Unauthorized`. You
cannot un-revoke; create a new key instead.

<Note>
  Revoking a key takes effect immediately: the next request that uses it
  gets `401`. Move your services to the replacement key first.
</Note>

---

## Related

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/introduction">
    How `sk_live_` keys are attached to requests.
  </Card>
  <Card title="Publishable Keys" icon="window-maximize" href="/api-reference/publishable-keys">
    Public `pk_live_` keys for the widget — different lifecycle.
  </Card>
</CardGroup>

<!-- en: api-reference/publishable-keys -->
---
title: "Publishable Keys"
description: "Create, list, and revoke the pk_live_ publishable keys that let the embeddable web widget start browser voice sessions with your agents from your own site."
---

Publishable keys (`pk_live_...`) are **public** credentials that the
embeddable web widget uses from the browser. Unlike secret API keys,
they are scoped to a specific agent (or a webhook that will dynamically
resolve one) and gated to a list of allowed origins — safe to ship in
your front-end code. The origin list stops casual reuse on other sites;
it is not authentication, since a non-browser client can send any
`Origin` header. That is why the session settings a browser may send
are off by default (see `allowed_overrides`).

Each key is associated with exactly one of:

* `mode = "agent"`: fixed binding to an agent id. Simplest setup.
* `mode = "webhook"`: the widget calls your
  [`call.incoming` webhook](/webhooks/call-incoming) to dynamically
  resolve an agent per visitor.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/publishable-key` | List publishable keys |
| `POST` | `/v1/publishable-key` | Create a publishable key |
| `GET` | `/v1/publishable-key/{key_id}` | Retrieve a key |
| `PATCH` | `/v1/publishable-key/{key_id}` | Update name / allowed domains / mode / browser overrides |
| `DELETE` | `/v1/publishable-key/{key_id}` | Deactivate a key |
| `POST` | `/v1/publishable-key/{key_id}/transfer` | Copy or move to another org |

## Publishable key object

```json
{
  "id": 9,
  "name": "Marketing site (prod)",
  "key": "pk_live_abc123...",
  "key_prefix": "pk_live_abc",
  "allowed_domains": ["example.com", "*.example.com"],
  "is_active": true,
  "is_enabled": true,
  "mode": "agent",
  "agent_id": 12,
  "agent_name": "Customer Support Agent",
  "webhook_url": null,
  "allowed_overrides": ["context"],
  "max_call_duration_seconds": 1800,
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Key id |
| `name` | string | Display name |
| `key` | string | The raw `pk_live_...` value. Publishable keys are public, so the full value is retrievable at any time |
| `key_prefix` | string | First 12 chars for display (e.g. `pk_live_abc`) |
| `allowed_domains` | array of string | Origin allowlist — exact hostnames and `*.subdomain` wildcards. `localhost` is not allowed automatically in production; list it to test locally |
| `is_active` | boolean | `false` after deactivation; a deactivated key stops working |
| `is_enabled` | boolean | Temporary disable toggle (separate from `is_active`) |
| `mode` | string | `agent` or `webhook` |
| `agent_id` | integer \| null | Required for `mode="agent"` |
| `agent_name` | string \| null | Read-only convenience — the linked agent's name |
| `webhook_url` | string \| null | Required for `mode="webhook"` — overrides the org-level webhook |
| `allowed_overrides` | array of string | Session settings the browser may send to [`POST /v1/widget/session`](/widget/overview): any of `context`, `variables`, `voice`, `language`. A request carrying one that is not listed fails with `400 override_not_allowed`. `[]` for new keys; keys created before the setting existed allow all four |
| `max_call_duration_seconds` | integer \| null | Longest a widget session may run, in seconds: 60–21600, default 1800 (30 minutes). A session ends at this or at the agent's own max call duration, whichever is shorter. `null` uses the agent's (or webhook config's) own limit alone |
| `created_at`, `updated_at` | timestamp | |

---

## List publishable keys

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/publishable-key \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Returns an array of [Publishable key objects](#publishable-key-object).

---

## Create a publishable key

<CodeGroup>
```bash Agent-bound key
curl -X POST https://api.thunderphone.com/v1/publishable-key \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing site (prod)",
    "mode": "agent",
    "agent_id": 12,
    "allowed_domains": ["example.com", "*.example.com"]
  }'
```

```bash Webhook-mode key
curl -X POST https://api.thunderphone.com/v1/publishable-key \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dynamic widget",
    "mode": "webhook",
    "webhook_url": "https://example.com/thunderphone-webhook",
    "allowed_domains": ["example.com"]
  }'
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | no | Defaults to `"Web Widget"` |
| `mode` | string | no | `agent` (default) or `webhook` |
| `agent_id` | integer | yes (if `mode="agent"`) | |
| `webhook_url` | string | yes (if `mode="webhook"`) | HTTPS URL |
| `allowed_domains` | array of string | **yes** | At least one entry required. See rules below |
| `is_enabled` | boolean | no | Defaults to `true` |
| `allowed_overrides` | array of string | no | Any of `context`, `variables`, `voice`, `language`. Defaults to `[]` (the browser may set none) |
| `max_call_duration_seconds` | integer \| null | no | 60–21600, default 1800 (30 minutes). `null` leaves only the agent's own limit |

### Allowed-domain rules

* An exact match: `example.com`
* A wildcard match: `*.example.com` (matches `api.example.com` but not
  bare `example.com`)
* `localhost` and `127.0.0.1` are not allowed automatically in
  production. List them to test a local page against the production API
* Bare wildcards (`*` or `*.*`) are rejected with `400`
* **At least one entry is required** — passing an empty array returns
  `400 allowed_domains: "At least one allowed domain is required."`

Returns `201 Created` with the new [Publishable key object](#publishable-key-object).
The `key` field is included on creation **and** is retrievable later
via `GET` — publishable keys are public by design.

---

## Update / delete

`PATCH` accepts any subset of `name`, `allowed_domains`, `mode`,
`agent_id`, `webhook_url`, `is_enabled`, `embed_config`,
`allowed_overrides`, `max_call_duration_seconds`. Switching between modes
requires providing the new required field (`agent_id` or
`webhook_url`).

`DELETE` sets `is_active=false` — the key stops working but remains
visible in list responses so you can audit prior deployments. There is
no hard delete.

---

## Transfer a publishable key

Copy or move a publishable key to another organization where you are an admin.

An `sk_live_` API key is limited to its own organization: with a key,
`target_org_id` must be the key's organization, and any other target
returns `403`. Copy or move between organizations from a signed-in session
(`Authorization: Token <session-token>` plus `X-ThunderPhone-Org` for the
source org), as below.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/publishable-key/9/transfer \
  -H "Authorization: Token YOUR_SESSION_TOKEN" \
  -H "X-ThunderPhone-Org: 42" \
  -H "Content-Type: application/json" \
  -d '{"target_org_id": 77, "mode": "copy"}'
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `target_org_id` | integer | yes | |
| `mode` | string | yes | `copy` or `move` |
| `name` | string | no | Override the copy's name |

---

## Related

<CardGroup cols={2}>
  <Card title="Widget overview" icon="window-maximize" href="/widget/overview">
    How the widget uses `pk_live_` keys at runtime.
  </Card>
  <Card title="Dynamic webhook config" icon="bolt" href="/webhooks/call-incoming">
    Shape the `call.incoming` webhook must respond with in webhook mode.
  </Card>
</CardGroup>

<!-- en: api-reference/voip-connections -->
---
title: "VoIP Connections"
description: "Bring your own phone numbers into ThunderPhone from Twilio or Telnyx, or from SignalWire, Vonage, Plivo and any other SIP trunk as manual connections: create VoIP connections, verify credentials, and manage imported numbers."
---

VoIP connections let you plug your existing telephony provider into
ThunderPhone. Once connected, you can list, import, and verify phone
numbers from your provider account; imported numbers become
[Phone number](/api-reference/phone-numbers) resources you can assign
agents to.

## Supported providers

| Provider | `provider` id | Setup methods |
|----------|---------------|---------------|
| Twilio | `twilio` | `api_key` |
| Telnyx | `telnyx` | `api_key`, `guided_telnyx` |
| SignalWire | `signalwire` | Not available yet — connect it as `manual` (the API returns `400` for `provider: "signalwire"`) |
| Vonage | `vonage` | Not available yet — connect it as `manual` (the API returns `400` for `provider: "vonage"`) |
| Manual (any SIP trunk) | `manual` | `manual` |

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/voip-connections` | List connections |
| `POST` | `/v1/voip-connections` | Create a connection |
| `GET` | `/v1/voip-connections/{connection_id}` | Retrieve a connection |
| `PATCH` | `/v1/voip-connections/{connection_id}` | Update credentials / name |
| `DELETE` | `/v1/voip-connections/{connection_id}` | Remove a connection |
| `POST` | `/v1/voip-connections/{connection_id}/enable-transfers` | Turn call transfers on at the carrier (Twilio) |
| `POST` | `/v1/voip-connections/test` | Test raw credentials (no persisted connection) |
| `GET` | `/v1/voip-connections/sip-host` | The SIP host your trunk sends inbound calls to (manual connections) |
| `POST` | `/v1/voip-connections/suggest-name` | Infer a display name from credentials |
| `POST` | `/v1/voip-connections/twilio/subaccounts` | Discover the subaccounts under a Twilio parent account |
| `POST` | `/v1/voip-connections/twilio/subaccounts/connect` | Create one Twilio connection per chosen subaccount |
| `GET` | `/v1/voip-connections/{connection_id}/available-numbers` | List numbers already owned in the provider account |
| `POST` | `/v1/voip-connections/{connection_id}/import-numbers` | Import selected numbers |
| `GET` | `/v1/voip-connections/{connection_id}/search-numbers` | Search purchasable numbers (guided provisioning) |
| `POST` | `/v1/voip-connections/{connection_id}/provision-number` | Buy a number through the connection (guided provisioning) |

## Connection object

```json
{
  "id": 5,
  "name": "Acme Telnyx Main",
  "provider": "telnyx",
  "status": "connected",
  "setup_method": "api_key",
  "inferred_name": false,
  "credentials": { "apiKey": "********", "connectionId": "123456" },
  "sip_config": { "domain": "acme.sip.telnyx.com" },
  "test_result": { "checks": { "credentials_valid": true } },
  "last_tested_at": "2026-04-20T18:24:10.113Z",
  "numbers_imported": 3,
  "provisioning_supported": true,
  "provisioning_message": null,
  "transfer_refused_at": null,
  "transfer_enabled_at": null,
  "relay": null,
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Connection id |
| `name` | string | Display name |
| `provider` | string | `twilio`, `telnyx`, `signalwire`, `vonage`, `manual` |
| `status` | string | `pending`, `testing`, `connected`, `error` (read-only) |
| `setup_method` | string | `api_key`, `manual`, `guided_telnyx` |
| `inferred_name` | boolean | `true` when we auto-generated the name (read-only) |
| `credentials` | object | Returned with sensitive values **masked** — any key containing `key`, `token`, `secret`, or `password` reads `"********"`. Writable on create/update |
| `sip_config` | object | Provider-specific SIP config. Writable on create/update; sensitive values masked on read the same way. A `manual` connection set up from a named provider in the dashboard also carries `preset` (`signalwire`, `vonage` or `plivo`); it is a label only and does not change routing |
| `test_result` | object | Result payload of the most recent credential test (read-only) |
| `last_tested_at` | timestamp \| null | Last credential test (read-only) |
| `numbers_imported` | integer | Count of phone numbers imported through this connection (read-only) |
| `provisioning_supported` | boolean | Whether [guided number provisioning](#search-purchasable-numbers) works for this provider (currently Telnyx and Twilio) |
| `provisioning_message` | string \| null | When unsupported: an explanation, e.g. `"Provisioning not yet supported for twilio; use Import."` |
| `transfer_refused_at` | timestamp \| null | Latest time the carrier refused a cold transfer on this connection, so ThunderPhone connected the call itself. Cleared when [transfers are turned on](#turn-on-call-transfers); a refusal on a call that ended before then does not set it again (read-only) |
| `transfer_enabled_at` | timestamp \| null | When call transfers were turned on at the carrier through [Turn on call transfers](#turn-on-call-transfers) (read-only) |
| `relay` | object \| null | Set when ThunderPhone's SIP registration relay signs in to the carrier for this connection, for carriers that only deliver calls to a registered device. Enabled by ThunderPhone support. `state` is `registering`, `registered`, `refused` (the carrier refused the username or password), `unreachable`, `evicted` (another device signed in with the same account), `relay_down` or `off`; `reason_code` is the carrier's SIP status or the relay's reason for `refused`, `unreachable` and `evicted`; `since` is when it entered that state; `last_registered_at`; `relay_ip` is the relay's address, which ThunderPhone adds to the connection's inbound allowlist (not part of `sip_config.inboundSourceIps`, and not removable). Never carries credentials (read-only) |

<Note>
  The masked `credentials` object shows which keys are configured
  without revealing values. To rotate credentials, `PATCH` with a full
  new `credentials` object.
</Note>

---

## List connections

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/voip-connections \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Returns an array of [Connection objects](#connection-object).

---

## Retrieve a connection

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/voip-connections/12 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Returns one [Connection object](#connection-object), with secrets masked as in the list. `404` when the
connection isn't in your organization.

---

## Create a connection

Creation is a two-phase flow:

1. Call [`POST /v1/voip-connections/test`](#test-credentials) with the
   credentials and get back a **verification evidence id** if the test
   passes.
2. Call this endpoint with the same credentials plus
   `verification_evidence_id` — the evidence proves the credentials
   were already validated, avoiding double-billing for the test.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/voip-connections \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Telnyx Main",
    "provider": "telnyx",
    "setup_method": "api_key",
    "credentials": {
      "apiKey": "KEY...",
      "connectionId": "123456"
    },
    "sip_config": { "domain": "acme.sip.telnyx.com" },
    "verification_evidence_id": "b9a2..."
  }'
```
</CodeGroup>

### Request fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `provider` | string | yes | Provider id (see table above) |
| `name` | string | no | Defaults to a provider-inferred value |
| `setup_method` | string | no | Defaults to `api_key`; Telnyx supports `guided_telnyx` |
| `credentials` | object | yes, unless `external_account_handle` is set | Provider-specific key/secret/connection fields |
| `external_account_handle` | string | no | Instead of `credentials`: the handle (`ext_...`) of a carrier account already saved with Zeus. ThunderPhone reads its key on the server. Send the same handle to the test |
| `sip_config` | object | no | Extra SIP config — e.g. `{"domain": "..."}` |
| `verification_evidence_id` | UUID | yes | Id returned by `POST /voip-connections/test` |
| `enable_transfers` | boolean | no | Twilio only. Also turn call transfers on for the connection's SIP trunk, exactly as [Turn on call transfers](#turn-on-call-transfers) does. Defaults to `false`; `400` for other providers |

Returns `201 Created` with the [Connection object](#connection-object). With
`enable_transfers`, a Twilio error never fails the create: the connection is
saved without transfers, `transfer_enabled_at` stays `null`, and
`test_result.transfer_enable_error` says why. Call
[Turn on call transfers](#turn-on-call-transfers) to try again; success
removes `transfer_enable_error`.

Errors:

| Status | Condition |
|--------|-----------|
| `400` | Provider mismatch (evidence generated for a different provider) |
| `400` | Evidence reused / stale / missing |
| `422` | Credentials failed re-verification |

---

## Update a connection

<CodeGroup>
```bash cURL
curl -X PATCH https://api.thunderphone.com/v1/voip-connections/5 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Renamed"}'
```
</CodeGroup>

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | |
| `credentials` | object | Rotate credentials. Requires a fresh `verification_evidence_id` when the merged value differs from what is stored |
| `sip_config` | object | Manual connections: the full SIP settings. Changing them requires a fresh `verification_evidence_id`; the connection returns `status: "pending"` and every number on it drops to `provisioning` while ThunderPhone rebuilds the trunk pair and re-verifies each number with a probe call in the background (`numbers_pending_verification` in the response lists them). Numbers return to `active` only after their probe call succeeds. A change to `inboundSourceIps` alone (order, blanks and duplicates do not count) on a `connected` connection is applied to the inbound trunk immediately instead: the connection stays `connected`, its numbers stay `active` and verified, and each number's incoming-call test resets to `untested`. If the trunk cannot be updated the request returns `502` and nothing is saved. A `pending` or `error` connection re-verifies as above |
| `verification_evidence_id` | UUID | Required whenever `credentials` or `sip_config` actually change |

Secrets are **merged, never echoed**: a key containing `key`, `token`,
`secret` or `password` that you send as `"********"`, as an empty
string, or omit entirely keeps its stored value; send `null` to clear
it. A request that only echoes the masked read-back is not a credential
change and needs no evidence.

---

## Delete a connection

<CodeGroup>
```bash cURL
curl -X DELETE https://api.thunderphone.com/v1/voip-connections/5 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Returns `204 No Content`. Phone numbers imported through the deleted
connection are **not** removed — they stay in your org with
`voip_connection_id` cleared.

---

## Turn on call transfers

Twilio trunks refuse cold transfers until the trunk allows them. This sets
the connection's Twilio SIP trunk to `TransferMode=enable-all` and leaves the
trunk's caller-ID setting as it is. With Twilio's default
(`TransferCallerId=from-transferee`), the transferred call shows the number
of the person being transferred (the caller on inbound calls, the person
your agent called on outbound calls). Transferred calls are then carried and
billed on your Twilio account. Admin or owner only.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/voip-connections/5/enable-transfers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Returns `200` with the [connection object](#connection-object):
`transfer_enabled_at` set and `transfer_refused_at` cleared. It is safe to
call again: Twilio is left unchanged if transfers are already on, and the call
returns `200`.

| Status | When |
|--------|------|
| `409` | Not a Twilio connection (turn on call transfers, SIP REFER, in your carrier's settings; `detail` says where), the connection has no SIP trunk or credentials, or Twilio has no such trunk |
| `502` | Twilio rejected the stored credentials or the update failed |

---

## Test credentials

Probes the provider API with the supplied credentials (for `manual`,
checks that the SIP host resolves to a public address and, for TCP/TLS,
accepts a connection on the port — a real call is only placed when a
number is verified). On success, the response includes a
`verification_evidence_id` you can pass to
[Create](#create-a-connection) or [Update](#update-a-connection) to
create/rotate the connection without a second round trip.

Instead of `credentials`, a test can name a carrier account already saved
with Zeus by its handle, as `external_account_handle` (`"ext_..."`).
ThunderPhone reads the key on the server and never returns it.

Pass `connection_id` to test an **edit**: the submitted `credentials` /
`sip_config` are merged over the stored connection (masked, blank or
omitted secrets keep their stored values, exactly as
[Update](#update-a-connection) will merge them), so the evidence matches
the update you are about to send.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/voip-connections/test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider":    "telnyx",
    "credentials": { "apiKey": "KEY...", "connectionId": "123456" },
    "sip_config":  { "domain": "acme.sip.telnyx.com" }
  }'
```
</CodeGroup>

```json Response (success)
{
  "status": "pass",
  "verification_evidence_id": "b9a2...",
  "suggested_connection_name": "Telnyx: Acme Main (+15550001234)",
  "checks": {
    "credentials_valid": true,
    "inbound_reachable": true,
    "outbound_authorized": true
  }
}
```

---

## Get the inbound SIP host

`GET /v1/voip-connections/sip-host`

Returns the SIP host a `manual` connection's trunk must send inbound
calls to: `sip.thunderphone.com`, ThunderPhone's SIP edge. Point the
trunk at `<sip_host>:5060` for UDP or TCP, or `<sip_host>:5061` for TLS,
and address each call to the dialed number in E.164 form, with the
same number, including the `+`, in both the request line and the `To`
header (`sip:+14155550142@<sip_host>`). Read it from here rather than
keeping a copy. Trunks set up earlier with a
`<your-project>.sip.livekit.cloud` address keep working while the
connection has no allowed source IPs. The edge's IP addresses
are listed under
[IP allowlisting](/guides/voip-providers#ip-allowlisting-and-trunk-authentication).

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/voip-connections/sip-host \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

```json Response
{
  "sip_host": "sip.thunderphone.com"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `sip_host` | string \| null | Hostname only, without scheme or port. `null` when inbound SIP is not configured in this environment; contact support |

---

## Suggest a connection name

Asks the provider for an inferred display name. Used by the dashboard
onboarding flow.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/voip-connections/suggest-name \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider":    "telnyx",
    "credentials": { "apiKey": "KEY..." }
  }'
```
</CodeGroup>

```json Response
{
  "suggested_connection_name": "Telnyx: Acme Main",
  "suggested_connection_name_inferred": true
}
```

---

## Discover Twilio subaccounts

Lists the active subaccounts a Twilio parent account can see, marking
the ones this org already has a connection for. Pass either raw parent
`credentials` or the `connection_id` of an existing Twilio connection.
Subaccount auth tokens are read from Twilio and kept server-side under
the returned `discovery_id` (valid for 30 minutes); they are never
returned. Admin role required.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/voip-connections/twilio/subaccounts \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": { "accountSid": "ACparent...", "authToken": "..." }
  }'
```
</CodeGroup>

```json Response
{
  "discovery_id": "7c1e...",
  "parent": { "sid": "ACparent...", "friendly_name": "Acme" },
  "subaccounts": [
    { "sid": "ACsupport...", "friendly_name": "Acme Support", "already_connected": false, "connection_id": null },
    { "sid": "ACsales...",   "friendly_name": "Acme Sales",   "already_connected": true,  "connection_id": 5 }
  ]
}
```

An empty `subaccounts` array means the credentials belong to an
account with no active subaccounts (or to a subaccount itself).

---

## Connect Twilio subaccounts

Creates one ordinary Twilio connection per selected subaccount, each
with its own verification evidence and SIP trunk inside that
subaccount. Rows are independent: one subaccount failing never blocks
the others, and a failed `sid` can be sent again with the same
`discovery_id` until it expires. Admin role required.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/voip-connections/twilio/subaccounts/connect \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "discovery_id":   "7c1e...",
    "subaccount_sids": ["ACsupport...", "ACsales..."]
  }'
```
</CodeGroup>

```json Response
{
  "results": [
    { "sid": "ACsupport...", "friendly_name": "Acme Support", "status": "created", "connection": { "id": 9, "provider": "twilio", "setup_method": "twilio_subaccount", "...": "..." }, "error": null },
    { "sid": "ACsales...",   "friendly_name": "Acme Sales",   "status": "skipped", "connection": { "id": 5, "...": "..." }, "error": null }
  ]
}
```

| `status` | Meaning |
|----------|---------|
| `created` | A new connection (and trunk) exists; `connection` is the new [Connection object](#connection-object) |
| `skipped` | The org already had a connection for this subaccount; `connection` is that one |
| `failed` | Nothing was created; `error` says why (Twilio rejected the token, trunk creation failed, unknown `sid`) |

Returns `400` when the `discovery_id` has expired ("Subaccount
discovery expired. Run discovery again.").

---

## List available numbers

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/voip-connections/5/available-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Returns the list of phone numbers visible to this connection's
credentials that are **not** yet imported into any ThunderPhone org:

```json
[
  {
    "id": "provider-handle-abc",
    "number": "+15550001234",
    "friendlyName": "Main office",
    "type": "local",
    "capabilities": ["voice"],
    "region": "US-CA",
    "monthlyFee": 100
  }
]
```

---

## Import numbers

Moves the selected numbers into ThunderPhone as
[Phone number](/api-reference/phone-numbers) resources. Imports start
in `status="provisioning"` — call
[`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number)
to complete verification. For a manual SIP connection that places a
short probe call from the number, through your trunk, to a ThunderPhone
number — see [Verify a VoIP-sourced number](/api-reference/phone-numbers#verify-a-voip-sourced-number).

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/voip-connections/5/import-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"numbers": ["+15550001234", "+15550009999"]}'
```
</CodeGroup>

```json Response
{
  "imported_count": 2,
  "provider_charge_estimate_cents": 0,
  "provider_charge_note": "Import does not create ThunderPhone charges. Provider charges are billed by your VoIP provider only.",
  "results": [
    { "id": 201, "number": "+15550001234", "status": "provisioning" },
    { "id": 202, "number": "+15550009999", "status": "provisioning" }
  ]
}
```

| Field | Required | Description |
|-------|----------|-------------|
| `numbers` | yes | 1–50 numbers in E.164 |
| `call_routing` | no | Twilio and Telnyx only. `thunderphone` (default): point the numbers' incoming calls at ThunderPhone in your provider account. `customer`: leave their call settings at your provider unchanged; your own routing sends calls to `sip:<number>@sip.thunderphone.com` when the agent should answer. The number's `carrier_routing` is then `customer` |

A number already on another of your connections moves to this one,
unless a Twilio or Telnyx connection sends its calls to ThunderPhone
(remove it there first). If the import fails, any change it made at your
provider is put back. A refused import is `400` with the reason in `detail`.
A `502` means your provider or ThunderPhone's call routing failed; its
`detail` says whether every change was put back, and when one was not,
contact support before trying again.

---

## Search purchasable numbers

For connections where `provisioning_supported` is `true` (currently
**Telnyx** only), search the provider's inventory for numbers you can
buy without leaving ThunderPhone.

<CodeGroup>
```bash cURL
curl 'https://api.thunderphone.com/v1/voip-connections/5/search-numbers?country=US&area_code=415&type=local' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

| Query param | Required | Description |
|-------------|----------|-------------|
| `country` | yes | Two-letter ISO country code |
| `type` | yes | `local` or `toll-free` |
| `area_code` | no | Digits only |

```json Response
{
  "results": [
    {
      "id": "provider-handle-abc",
      "number": "+14155550123",
      "friendlyName": "+1 415 555 0123",
      "type": "local",
      "capabilities": ["voice"],
      "region": "US-CA",
      "monthlyFee": 100,
      "monthlyFeeCurrency": "USD"
    }
  ],
  "provider_charge_note": "Purchasing this number and its recurring monthly service are billed directly by Telnyx. ThunderPhone does not add a provisioning fee."
}
```

| Status | Condition |
|--------|-----------|
| `200` | Search results |
| `501` | Provider does not support guided provisioning — use [Import](#import-numbers) |
| `502` | Provider API error / temporarily unavailable |

## Provision (buy) a number

Places a number order with the provider using the connection's
credentials, then registers the number in ThunderPhone. The provider —
not ThunderPhone — bills the purchase and monthly fee.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/voip-connections/5/provision-number \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number": "+14155550123"}'
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `number` | string | yes | Explicit E.164 number from a [search](#search-purchasable-numbers) result |

```json Response (201 Created)
{
  "order_id": "ord_abc123",
  "order_status": "pending",
  "provider_charge_note": "Purchasing this number and its recurring monthly service are billed directly by Telnyx. ThunderPhone does not add a provisioning fee.",
  "result": { "id": 203, "number": "+14155550123", "status": "provisioning" }
}
```

Returns `201 Created` when a new order was placed, or `200 OK` when
the number was already owned and only registration was needed.

| Status | Condition |
|--------|-----------|
| `400` | Invalid number / order rejected |
| `501` | Provider does not support guided provisioning |
| `502` | Provider API error / temporarily unavailable |

---

## Related

<CardGroup cols={2}>
  <Card title="Phone Numbers" icon="phone" href="/api-reference/phone-numbers">
    Assign agents to imported numbers and run verify-voip.
  </Card>
  <Card title="Outbound Calls" icon="arrow-up-right" href="/api-reference/outbound-calls">
    Place calls from a customer VoIP number or an approved ThunderPhone number.
  </Card>
</CardGroup>

<!-- en: api-reference/integrations -->
---
title: "Integrations"
description: "Define reusable HTTP tool integrations with endpoint, auth, and parameter schemas that any of your agents can call mid-conversation to reach external systems."
---

Integrations are reusable tool definitions — an endpoint URL + method +
headers + a JSON schema for arguments — that you can attach to one or
more agents. During a call the agent uses the tool's schema to decide
when to call out; ThunderPhone makes the outbound HTTP request on the
agent's behalf using the integration's saved configuration.

See also [Function Tools](/tools/overview) for the shape of the JSON
schema an integration's `spec` must follow.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/integrations` | List integrations |
| `POST` | `/v1/integrations` | Create an integration |
| `GET` | `/v1/integrations/{integration_id}` | Retrieve an integration |
| `PATCH` | `/v1/integrations/{integration_id}` | Update an integration |
| `DELETE` | `/v1/integrations/{integration_id}` | Delete an integration |
| `POST` | `/v1/integrations/{integration_id}/transfer` | Copy / move to another org |
| `GET` | `/v1/integrations/{integration_id}/versions` | List prior configuration revisions |
| `POST` | `/v1/integrations/test-request` | Probe an integration endpoint from a sandbox |

## Integration object

```json
{
  "id": "f9b5a1a4-...",
  "display_name": "Weather API",
  "spec": {
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Return the current weather for a zip code.",
      "parameters": { /* JSON Schema */ }
    }
  },
  "endpoint_url": "https://api.example.com/weather",
  "endpoint_method": "GET",
  "request_format": "standard",
  "headers": [
    { "key": "X-Api-Key" }
  ],
  "wizard_input": "Use https://api.example.com/weather with X-Api-Key header.",
  "validation_status": "validated",
  "trigger": "agent",
  "call_start_arguments": null,
  "warnings": [],
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Integration id |
| `display_name` | string | 1–255 chars |
| `spec` | object | OpenAI-style function tool schema (see [Function Tools](/tools/overview)) |
| `endpoint_url` | string | Outbound HTTP URL the tool calls. Empty string when the integration is still being configured |
| `endpoint_method` | string | `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`. Defaults to `POST` |
| `request_format` | string | `standard` (default), `vapi`, or `retell`. Controls the body envelope for `POST`, `PUT`, and `PATCH`; `GET` and `DELETE` always use query parameters |
| `headers` | array | Headers sent with every tool invocation. **Key names only** are returned: header values are write-only, encrypted at rest, and never appear in API responses, version history, or call records |
| `wizard_input` | string | Free-form text from the "describe this integration" wizard; kept for audit only |
| `validation_status` | string | `untested`, `validated`, `error` — updated by [test-request](#test-integration-request) |
| `trigger` | string | `agent` (default): the agent calls the tool when it decides to. `call_start`: the tool also runs automatically at the start of every phone call, before the greeting, and the agent gets the result. See [Run a tool at the start of the call](/tools/overview#run-a-tool-at-the-start-of-the-call) |
| `call_start_arguments` | object or null | With `trigger` `call_start`: the arguments sent at call start, one value per parameter. `null` otherwise |
| `created_at`, `updated_at` | timestamp | ISO 8601 UTC |
| `warnings` | array of object | Saved settings worth a second look, each `{code, field, detail}` (read-only). `tool_has_no_inputs` (`field` is `spec.function.parameters`) when the tool declares no input properties, so the agent may call it without the data the endpoint needs. Never blocks a save. Empty when there is nothing to flag |

---

## List integrations

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/integrations \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Returns an array of [Integration objects](#integration-object).

---

## Create an integration

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/integrations \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Weather API",
    "spec": {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Return the current weather for a zip code.",
        "parameters": {
          "type": "object",
          "properties": {
            "zip": { "type": "string" }
          },
          "required": ["zip"]
        }
      }
    },
    "endpoint_url":    "https://api.example.com/weather",
    "endpoint_method": "GET",
    "request_format":  "standard",
    "headers": [
      { "key": "X-Api-Key", "value": "abc..." }
    ]
  }'
```
</CodeGroup>

### Request fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `display_name` | string | yes | 1–255 chars |
| `spec` | object | yes | Function-tool JSON schema. `spec.type` must be `"function"`. `spec.function.name` can't be a built-in or connected-app tool name; it may repeat across integrations (see [Tool names](#tool-names)) |
| `endpoint_url` | string | no | HTTPS URL; defaults to empty string if omitted |
| `endpoint_method` | string | no | `GET`, `POST` (default), `PUT`, `PATCH`, `DELETE` |
| `request_format` | string | no | `standard` (default), `vapi`, or `retell`; see [Function Tools request formats](/tools/overview#request-format) |
| `headers` | array | no | `[{key, value}]` pairs. Each header needs a value. Names must be unique (case-insensitive) |
| `copy_header_values_from` | UUID | no | Another integration in the same organization. A header sent without a `value` takes that integration's stored value for the same name (how the dashboard's **Clone** copies secrets it cannot read) |
| `wizard_input` | string | no | Free-form notes |
| `trigger` | string | no | `agent` (default) or `call_start` |
| `call_start_arguments` | object | with `call_start` | A value for every required parameter, and only declared parameters. Values are strings, numbers or booleans; strings may use `{{caller_number}}`, `{{caller_number_national}}` and `{{agent_number}}`. Returned in responses and shown to the agent, so keep secrets in `headers`. A `PATCH` that changes `spec` must leave these valid. Cleared when `trigger` is set to `agent` |

Returns `201 Created` with the new [Integration object](#integration-object) in
`validation_status="untested"`.

<Note>
  Header values are write-only. They are encrypted at rest, decrypted only to
  send the tool request, and never returned: responses list header names only.
</Note>

### Tool names

Tool names are unique per agent, not per organization. Two integrations in
one organization may share a `spec.function.name`, for example a
`save_information` tool for each of two agents that save to different
endpoints. One agent can't have two tools with the same name, because
every call on it would fail: attaching a second one through
`integration_ids` or `mcp_server_ids` on an [agent](/api-reference/agents),
creating an agent with both, or publishing a draft with both returns `400`
naming the tool.

---

## Retrieve / update / delete

`GET`, `PATCH`, and `DELETE` behave conventionally. `PATCH` accepts any
subset of the create fields. Deleting an integration removes it from
every agent it was linked to. A `PATCH` that renames `spec.function.name`
returns `400` when an agent that has the integration, live or in its draft,
already has another tool with the new name.

`headers` on `PATCH` replaces the whole list, with the same rules as
[MCP server headers](/api-reference/mcp-servers):

- An entry with an empty or omitted `value` keeps the stored value for that
  header name (matched case-insensitively), so you can save an integration
  you read back without re-sending its secrets.
- An entry with a `value` sets or replaces it.
- A header left out of the list is removed.
- A new header name without a `value` is rejected with `400`.

---

## Transfer an integration

Copy or move an integration to another organization where you are an admin.

An `sk_live_` API key is limited to its own organization: with a key,
`target_org_id` must be the key's organization, and any other target
returns `403`. Copy or move between organizations from a signed-in session
(`Authorization: Token <session-token>` plus `X-ThunderPhone-Org` for the
source org), as below.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/integrations/f9b5a1a4-.../transfer \
  -H "Authorization: Token YOUR_SESSION_TOKEN" \
  -H "X-ThunderPhone-Org: 42" \
  -H "Content-Type: application/json" \
  -d '{"target_org_id": 77, "mode": "copy"}'
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `target_org_id` | integer | yes | |
| `mode` | string | yes | `copy` or `move` |
| `name` | string | no | Override the copy's display name |

Returns `201 Created` for `copy` / `200 OK` for `move`:

```json
{ "mode": "copy", "target_org_id": 77, "integration": { /* ... */ } }
```

---

## Version history

<CodeGroup>
```bash cURL
curl 'https://api.thunderphone.com/v1/integrations/f9b5a1a4-.../versions?limit=20' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Response is analogous to [Agent versions](/api-reference/agents#version-history):
`{count, results[]}` with each result containing `id`, `revision`,
`created_by`, `snapshot`, and `changed_fields`. Snapshots record header
names only, so a change to a header's value alone does not create a new
revision.

---

## Test integration request

Execute a one-off HTTP request against the integration endpoint
(from ThunderPhone's servers) to validate connectivity before linking
the integration to an agent. The sandbox enforces SSRF guards — no
requests to localhost or private IP ranges.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/integrations/test-request \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/weather?zip=94110",
    "method": "GET",
    "tool_name": "get_weather",
    "request_format": "standard",
    "headers": { "X-Api-Key": "abc..." }
  }'
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | yes | HTTPS; `http://` is only allowed for localhost during local dev |
| `method` | string | yes | `GET`, `POST`, `PUT`, `PATCH`, `DELETE` |
| `headers` | object | no | Header-name → value map |
| `body` | string \| object | no | For `standard`, a JSON body or raw string. For `vapi`/`retell`, a JSON object of tool arguments |
| `tool_name` | string | no | Tool name used in a Vapi or Retell envelope; defaults to `test_tool` |
| `request_format` | string | no | `standard` (default), `vapi`, or `retell`. Body methods use the selected envelope; `GET`/`DELETE` are unchanged |
| `timeout_seconds` | integer | no | 1–60 (default 20) |
| `integration_id` | UUID | no | A saved integration in your organization. Any header sent with an empty value is filled with that integration's stored value for the same name, so you can test a saved integration without re-entering its secrets. Requires `admin` or `owner` |

```json Response
{
  "ok": true,
  "status_code": 200,
  "latency_ms": 187,
  "response_headers": { "content-type": "application/json" },
  "response_body_preview": "{\"temperature_f\": 64, ...}",
  "response_truncated": false
}
```

Response bodies are truncated at 6 kB. SSRF-blocked requests return
`400` with `code="url_not_allowed"`.

---

## Related

<CardGroup cols={2}>
  <Card title="Agents" icon="robot" href="/api-reference/agents">
    Attach integrations to agents via `integration_ids`.
  </Card>
  <Card title="Function Tools" icon="screwdriver-wrench" href="/tools/overview">
    The JSON schema shape for `spec`.
  </Card>
</CardGroup>

<!-- en: api-reference/webhook-deliveries -->
---
title: "Webhook Deliveries"
description: "Inspect recent webhook delivery outcomes without exposing event payloads or transcripts."
---

Use the delivery history endpoint to confirm whether ThunderPhone attempted a webhook,
the safe outcome category, and whether another retry is scheduled. It merges the
recommended [webhook endpoint system](/webhooks/endpoints) with the legacy single-URL
call-finished webhook.

<Note>
  Delivery history never includes the webhook payload. Call-completion payloads can
  contain transcripts, so this endpoint returns delivery metadata only. URLs omit
  paths, user credentials, query strings, and fragments. Responses include only an
  HTTP status and an allowlisted failure category, never stored error or response text.
</Note>

The same recent history appears in the dashboard under **Agents → select an agent →
Webhooks → Recent deliveries**. Each row identifies the endpoint label and the safe URL
origin used by its latest attempt.

This history is recent operational state, not an immutable audit log. The endpoint system
stores only the latest outcome for each queued delivery, and deleting an endpoint also
deletes its delivery rows. Retrieve any records you need to retain before deleting an endpoint.

## List deliveries

```http
GET /v1/developer/webhook-deliveries
```

Requires an organization admin. Authenticate with a server API key, an admin session
token, or OAuth authorized for the organization with `integrations:read`. OAuth access
still uses the current user's live organization role, so members cannot read this route.

<CodeGroup>
```bash cURL
curl "https://api.thunderphone.com/v1/developer/webhook-deliveries?status=retrying&limit=50" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

```python Python
deliveries = requests.get(
    "https://api.thunderphone.com/v1/developer/webhook-deliveries",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    params={"agent_id": 42, "since": "2026-09-18T00:00:00Z"},
).json()
```
</CodeGroup>

### Filters

| Parameter | Type | Description |
|-----------|------|-------------|
| `agent_id` | integer | Deliveries associated with one agent |
| `endpoint_id` | UUID or `legacy` | One endpoint, or only the legacy single-URL webhook |
| `event_type` | string | Exact event type, such as `telephony.complete` |
| `status` | string | `delivered`, `retrying`, or `failed` |
| `since` | RFC 3339 timestamp | Result-change window; defaults to 7 days ago and is clamped to at most 30 days ago |
| `limit` | integer | Page size, 1–50; defaults to 50 |
| `cursor` | string | Opaque `next_cursor` from the previous page; reuse it only with the same organization, filters, `since`, and `limit` |

### Response

```json
{
  "results": [
    {
      "id": "0b6f8a6e-4e1c-4d8e-9a43-7f1d2c3b4a59",
      "source": "endpoint",
      "endpoint_id": "00000000-0000-4000-8000-000000000001",
      "endpoint_label": "n8n production",
      "url": "https://n8n.example.com",
      "event_type": "telephony.complete",
      "call_id": 1001,
      "status": "retrying",
      "attempt_count": 2,
      "http_status": 404,
      "failure_category": "http_error",
      "last_attempt_at": "2026-09-19T16:20:00Z",
      "next_retry_at": "2026-09-19T16:25:00Z",
      "duration_ms": 412,
      "is_test": false,
      "can_resend": false,
      "was_resent": false,
      "created_at": "2026-09-19T16:15:00Z",
      "resent_at": null
    }
  ],
  "limit": 50,
  "has_more": false,
  "next_cursor": null
}
```

`source` is `endpoint` for the endpoint-based system and `legacy` for the
single-URL call-finished webhook. Legacy rows use `endpoint_id: "legacy"`.
`url` is the sanitized origin used by the most recent recorded attempt. It is
`null` for rows created before destination snapshots were available.
`http_status` can be `null` when no response was received or the legacy success
path did not retain the status code. `failure_category` is `timeout`, `dns`, `tls`,
`connection`, `http_error`, `other`, or `null` when there is no failure. Legacy rows
created before destination snapshots were added return a generic label and `url: null`.
`next_retry_at` is present only while the delivery is retrying.

`id` is the event's `event_id`, the same value the envelope carries; with `endpoint_id`
it identifies one delivery. It is `null` on legacy rows. `duration_ms` is how long the
endpoint took to answer, or to fail, on the latest attempt; it is `null` before an attempt
reached the endpoint and on legacy rows. `is_test` marks test sends. `can_resend` is `true`
for a real delivery whose retries ran out (`failed`); see [Resend a delivery](#resend-a-delivery).
`was_resent` is `true` once someone has resent it, and `resent_at` says when. `created_at` is
when the event was first queued for the endpoint; a resend changes `last_attempt_at`, not
`created_at`.

### Interpreting common failures

- `404` from n8n: confirm the workflow is active, the webhook uses `POST`, and
  the production URL is configured instead of n8n's test URL.
- `401` or `403`: the destination rejected authentication. Check its credentials,
  authorization policy, and ThunderPhone signature verification.
- `timeout`: the destination did not answer before the webhook timeout. Check its
  availability and response time.
- `dns`: check that the configured hostname resolves publicly.
- `tls`: check the certificate chain, hostname, and certificate expiry.
- `connection`: check that the destination accepts and keeps HTTPS connections.
- `other`: the stored failure could not be safely classified; no raw response is exposed.

## Resend a delivery

```http
POST /v1/developer/webhook-endpoints/{endpoint_id}/deliveries/{id}/resend
```

Sends a `failed` delivery to its endpoint once more, right away, and returns the updated
delivery row plus `resent`. Requires an organization admin, the same as the list.

- The envelope keeps its `event_id`, so a receiver that already processed the event can
  drop the copy. It is signed when it is sent, with the endpoint's current secret.
- Only real deliveries whose retries ran out can be resent. A delivered, still-retrying or
  test delivery gets `409` with a `code` (`already_delivered`, `already_retrying`,
  `test_delivery`). Turn a paused or disabled endpoint back on first (`endpoint_not_active`).
- A resend is one attempt. If it fails, the delivery stays `failed` and the endpoint is
  not paused again.
- A webhook that no longer subscribes to the event's type gets `409` with
  `event_not_subscribed`.
- Pass `idempotency_key`, a value unique to the click or request. Repeating the request
  with the key of the delivery's latest resend sends nothing and returns `resent: false`.
- Resends are limited per endpoint (`429` when exceeded).

<CodeGroup>
```bash cURL
curl -X POST "https://api.thunderphone.com/v1/developer/webhook-endpoints/00000000-0000-4000-8000-000000000001/deliveries/0b6f8a6e-4e1c-4d8e-9a43-7f1d2c3b4a59/resend" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"idempotency_key": "8c1f4a2e-resend-1"}'
```
</CodeGroup>

<!-- en: widget/overview -->
---
title: "Embeddable Voice Widget"
description: "Add a voice AI agent to any website with a few lines of code"
---

The ThunderPhone embeddable voice widget lets your website visitors talk to an AI agent directly from the browser. No phone call required -- users click a button and start a real-time voice conversation powered by ThunderPhone.

The widget renders as a glassmorphic bar that adapts to light and dark themes, with customizable accent colors and positioning. It is distributed as the `@thunderphone/widget` npm package and is also available via CDN for non-bundler environments.

<Frame>
  <img src="/images/widget-showcase.png" alt="ThunderPhone widget in light and dark themes with various accent colors" />
</Frame>

## Prerequisites

Before embedding the widget, complete these three steps in the [ThunderPhone Dashboard](https://app.thunderphone.com):

<Steps>
<Step title="Create a web widget">
  Go to **Web Widgets** in the dashboard and create a widget. Select the agent you want to expose. Each widget has its own publishable key (`pk_live_...`), which is safe to include in client-side code; the agent is resolved from the key.
</Step>

<Step title="Configure allowed domains">
  On the same widget, add the domains where it will be embedded. Wildcards are supported (e.g., `*.example.com`). The list keeps the widget from working when someone copies your key onto another site; it is not authentication, since a script outside a browser can send any `Origin` header. `localhost` is not allowed automatically in production: add it to the list to test locally against the production API.
</Step>

<Step title="Choose browser overrides">
  If your page sets `language`, `voice`, or `context`, turn each one on under **Browser overrides**. New widgets accept none, and a session request carrying a setting that is off fails with `400 override_not_allowed`. See [Browser overrides](/guides/embed-web-widget#browser-overrides).
</Step>
</Steps>

<Warning>
  Publishable keys (`pk_live_...`) are **not** the same as your secret API tokens. Publishable keys are designed for client-side use and are scoped to widget sessions on your allowed domains. Never use your secret API token in client-side code.
</Warning>

<Note>
  Widget sessions end after 30 minutes by default, or sooner if the agent's own max call duration is shorter. Change the limit per key with `max_call_duration_seconds` on the [publishable key](/api-reference/publishable-keys) (up to 6 hours), or set it to `null` to use the agent's own limit.
</Note>

---

## Quick Start

Install the package:

```bash
npm install @thunderphone/widget
```

Drop the widget into your app:

```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      theme="dark"
      primaryColor="#8b5cf6"
    />
  )
}
```

That's it. Your users will see a glassmorphic call bar that connects them to your AI agent with a single click.

---

## Customization

The widget has four appearance props:

| Prop | Default | Description |
|------|---------|-------------|
| `theme` | `'light'` | `'light'` for white glass, `'dark'` for dark glass |
| `primaryColor` | `'#000000'` (light) / `'#ffffff'` (dark) | Accent color for the start button, waveform, and connecting indicator |
| `title` | `'Voice assistant'` | Text displayed in the widget |
| `position` | `'bottom-right'` | Viewport corner: `'bottom-right'`, `'bottom-left'`, `'top-right'`, `'top-left'` |

<CodeGroup>
```tsx Light theme (default)
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
/>
```

```tsx Dark theme with custom color
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  theme="dark"
  primaryColor="#8b5cf6"
  title="Ask our AI"
/>
```
</CodeGroup>

Three more props customize the session rather than the look -- all are forwarded to the session request when a call starts. Each works only when the widget's publishable key allows it under **Browser overrides**; otherwise the session request fails with `400 override_not_allowed`:

| Prop | Description |
|------|-------------|
| `language` | Per-session language override -- a code or locale such as `en`, `es`, or `fr-FR` |
| `voice` | Per-session voice override -- a voice name such as `maria` |
| `context` | Factual page or site context passed to the agent (truncated server-side to 12,000 characters) |

See the [React component reference](/widget/react) for the full props table.

For a fully custom UI, use the [headless hook](/widget/headless-hook) to manage the voice session while you build your own interface. The hook exposes real-time audio levels for building audio-reactive visualizations.

Each widget conversation is a call. It counts toward your organization's [concurrent-call limit](/api-reference/introduction#call-limits) (20 calls in progress by default, shared with phone and other calls) and a widget cap of 25 active sessions (or your concurrent-call limit, if that is higher). At either limit, a new conversation cannot start until a call ends.

---

## Integration Options

Choose the integration method that fits your stack:

<CardGroup cols={3}>
  <Card title="React Component" icon="react" href="/widget/react">
    Pre-built UI component with built-in call controls and status display. Import, pass props, done.
  </Card>
  <Card title="Headless Hook" icon="code" href="/widget/headless-hook">
    Full control over the UI. The `useThunderPhone` hook manages the voice session while you build your own interface.
  </Card>
  <Card title="CDN / Script Tag" icon="globe" href="/widget/cdn-script-tag">
    No bundler required. Load the widget via a script tag for static sites, WordPress, and other non-React environments.
  </Card>
</CardGroup>

---

## Styling

The widget ships with built-in light and dark themes controlled by the `theme` prop, and an accent color controlled by the `primaryColor` prop. For deeper customization, you can override CSS custom properties and classes. See the [Styling guide](/widget/styling) for details.

<Note>
  Need help? Contact us at [support@thunderphone.com](mailto:support@thunderphone.com)
</Note>

<!-- en: widget/react -->
---
title: "React Component"
description: "Embed the ThunderPhone voice widget in a React application"
---

The `ThunderPhoneWidget` component renders a glassmorphic call bar with built-in controls for muting, ending the call, and displaying connection status. It is the fastest way to add voice AI to a React app.

## Installation

```bash
npm install @thunderphone/widget
```

## Basic Usage

```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
    />
  )
}
```

<Warning>
  You **must** import the CSS file for the widget to render correctly. Without it, the widget will be unstyled.
</Warning>

---

## Props

The component accepts the following props via `ThunderPhoneWidgetProps`:

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `publishableKey` | `string` | Yes | -- | Publishable API key (`pk_live_...`) from **Web Widgets** in the dashboard. The agent is resolved automatically from the key's widget configuration. |
| `theme` | `'light' \| 'dark'` | No | `'light'` | Color scheme. Applies `tp--light` or `tp--dark` class to the widget root. |
| `primaryColor` | `string` | No | `'#000000'` (light) / `'#ffffff'` (dark) | CSS color string used as the accent color (call button, waveform, active indicators). |
| `title` | `string` | No | `'Voice assistant'` | Text displayed in the widget bar. |
| `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | No | `'bottom-right'` | Fixed viewport position for the widget. |
| `apiBase` | `string` | No | `'https://api.thunderphone.com/v1'` | API base URL override. |
| `language` | `string` | No | -- | Per-session language override -- a language code or locale such as `en`, `es`, or `fr-FR`. When unset, the agent's configured language applies. Requires `language` under the key's [browser overrides](/guides/embed-web-widget#browser-overrides). |
| `voice` | `string` | No | -- | Per-session voice override -- a voice name such as `maria`. When unset, the agent's configured voice applies. Requires `voice` under the key's [browser overrides](/guides/embed-web-widget#browser-overrides). |
| `context` | `string` | No | -- | Per-session factual page or site context passed to the agent (for example, details of the page the visitor is viewing). Truncated server-side to 12,000 characters. Requires `context` under the key's [browser overrides](/guides/embed-web-widget#browser-overrides). |
| `onConnect` | `() => void` | No | -- | Called when the voice session successfully connects. |
| `onDisconnect` | `() => void` | No | -- | Called when the session ends. |
| `onError` | `(error) => void` | No | -- | Called on errors. The `error` object has `error` (code) and `message` fields. |
| `className` | `string` | No | -- | Additional CSS class name applied to the widget container. |
| `ringtone` | `boolean \| string` | No | `false` | Play a ringtone while connecting. `true` for the default ringtone, or a URL string for custom audio. |

---

## Examples

### Dark Theme with Custom Color

```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      theme="dark"
      primaryColor="#8b5cf6"
      title="Talk to our AI"
    />
  )
}
```

### Custom Position

```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      position="bottom-left"
    />
  )
}
```

### Per-Session Language, Voice, and Context

The `language`, `voice`, and `context` props are forwarded to the session request (`POST /widget/session`) when a call starts, overriding the agent's configured defaults for that session. Turn each prop you use on under **Browser overrides** for the widget in the dashboard (or in the key's `allowed_overrides`). New widgets accept none, and a session request carrying one that is off fails with `400 override_not_allowed`; see [Browser overrides](/guides/embed-web-widget#browser-overrides).

```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function PricingPageWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      language="es"
      voice="maria"
      context="Page: Pricing. Plans: Starter $29/mo, Pro $99/mo. Annual billing saves 20%."
    />
  )
}
```

Use `context` to give the agent factual knowledge about the page the visitor is on -- product details, pricing, or page-specific FAQs. The agent treats it as page content, not as instructions. It is truncated server-side to 12,000 characters.

### With Event Callbacks

```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function SupportWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      onConnect={() => {
        console.log('Voice session connected')
        analytics.track('widget_call_started')
      }}
      onDisconnect={() => {
        console.log('Voice session ended')
        analytics.track('widget_call_ended')
      }}
      onError={(error) => {
        console.error(`Widget error: ${error.error} - ${error.message}`)
      }}
    />
  )
}
```

### With Custom Styling

```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function BrandedWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      primaryColor="#4a90d9"
      className="my-custom-widget"
    />
  )
}
```

```css
.my-custom-widget .tp-button--end {
  background-color: #e74c3c;
}
```

See the [Styling guide](/widget/styling) for all available CSS classes and custom properties.

### With Ringtone

Play a phone-ringing sound while the connection is being established:

```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function PhoneWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      ringtone={true}
    />
  )
}
```

Use a custom ringtone by passing an audio file URL:

```tsx
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  ringtone="https://example.com/my-ringtone.mp3"
/>
```

The ringtone loops while the widget is in the `connecting` state and fades out smoothly when the agent connects.

### With Custom API Base

<Tip>
  You only need to set `apiBase` if you are using a self-hosted or proxy API endpoint. The default points to `https://api.thunderphone.com/v1`.
</Tip>

```tsx
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  apiBase="https://your-proxy.example.com/v1"
/>
```

---

## Error Handling

When the `onError` callback fires, it receives an error object with two fields:

| Field | Type | Description |
|-------|------|-------------|
| `error` | `string` | Machine-readable error code |
| `message` | `string` | Human-readable error description |

Common error codes include domain not allowed, agent not found, and invalid API key.

---

## Next Steps

<CardGroup cols={2}>
  <Card title="Headless Hook" icon="code" href="/widget/headless-hook">
    Need full control over the UI? Use the `useThunderPhone` hook instead.
  </Card>
  <Card title="Styling" icon="palette" href="/widget/styling">
    Customize colors, sizes, and layout with CSS custom properties.
  </Card>
</CardGroup>

<!-- en: widget/headless-hook -->
---
title: "Headless Hook"
description: "Build a fully custom voice UI with the useThunderPhone React hook"
---

The `useThunderPhone` hook gives you complete control over the user interface while ThunderPhone manages the voice session, audio routing, and connection state. Use it when you want a fully custom UI -- your own buttons, layouts, animations, and branding -- while ThunderPhone handles everything under the hood.

## When to Use the Headless Hook

The pre-built `ThunderPhoneWidget` component covers most use cases, but reach for the headless hook when you need:

- A completely custom call UI that matches your app's design system
- Audio-reactive visualizations (waveforms, orbs, pulsing indicators) driven by real-time audio levels
- Custom call flows such as pre-call forms, post-call surveys, or inline chat alongside voice
- Integration into an existing component library (Material UI, Chakra, Radix, etc.)

---

## Installation

```bash
npm install @thunderphone/widget
```

<Note>
  The headless hook does **not** require importing `@thunderphone/widget/style.css` since you are providing your own UI. However, you must still install the same `@thunderphone/widget` package.
</Note>

---

## Basic Usage

```tsx
import { useThunderPhone } from '@thunderphone/widget'

function CustomCallButton() {
  const phone = useThunderPhone({
    publishableKey: 'pk_live_your_publishable_key',
  })

  const handleClick = () => {
    if (phone.state === 'connected') {
      phone.disconnect()
    } else {
      phone.connect()
    }
  }

  return (
    <>
      <button onClick={handleClick} disabled={phone.state === 'connecting'}>
        {phone.state === 'connecting'
          ? 'Connecting...'
          : phone.state === 'connected'
            ? 'End call'
            : 'Start call'}
      </button>
      {phone.audio}
    </>
  )
}
```

<Warning>
  **You must render `phone.audio` somewhere in your component tree.** It is an invisible React element that manages the underlying audio connection. If you omit it, no audio will play and the session will not work.
</Warning>

---

## Options

Pass these options to `useThunderPhone` via `UseThunderPhoneOptions`:

| Option | Type | Required | Default | Description |
|--------|------|----------|---------|-------------|
| `publishableKey` | `string` | Yes | -- | Publishable API key (`pk_live_...`). The agent is resolved automatically from the key's widget configuration. |
| `apiBase` | `string` | No | `'https://api.thunderphone.com/v1'` | API base URL override. |
| `language` | `string` | No | -- | Per-session language override -- a language code or locale such as `en`, `es`, or `fr-FR`. When unset, the agent's configured language applies. Requires `language` under the key's [browser overrides](/guides/embed-web-widget#browser-overrides). |
| `voice` | `string` | No | -- | Per-session voice override -- a voice name such as `maria`. When unset, the agent's configured voice applies. Requires `voice` under the key's [browser overrides](/guides/embed-web-widget#browser-overrides). |
| `context` | `string` | No | -- | Per-session factual page or site context passed to the agent. Truncated server-side to 12,000 characters. Requires `context` under the key's [browser overrides](/guides/embed-web-widget#browser-overrides). |
| `onConnect` | `() => void` | No | -- | Called when the voice session connects. |
| `onDisconnect` | `() => void` | No | -- | Called when the session ends. |
| `onError` | `(error) => void` | No | -- | Called on errors. Error has `error` (code) and `message` fields. |
| `ringtone` | `boolean \| string` | No | `false` | Play a ringtone while connecting. `true` for the default ringtone, or a URL string for custom audio. |

<Note>
  The hook is headless: it does **not** accept the `ThunderPhoneWidget` appearance props (`theme`, `primaryColor`, `title`, `position`, `className`). Passing them is a TypeScript error -- presentation is entirely yours to build.
</Note>

---

## Return Value

The hook returns a `UseThunderPhoneReturn` object:

| Property | Type | Description |
|----------|------|-------------|
| `state` | `'idle' \| 'connecting' \| 'connected' \| 'disconnected' \| 'error'` | Current connection state. |
| `connect` | `() => void` | Start a voice session. |
| `disconnect` | `() => void` | End the current session. |
| `toggleMute` | `() => void` | Toggle microphone mute on/off. |
| `isMuted` | `boolean` | Whether the microphone is currently muted. |
| `error` | `string \| undefined` | Error message when state is `'error'`. |
| `agentName` | `string \| undefined` | Display name of the connected agent. |
| `audioLevel` | `number` | **Deprecated -- always `0`.** A static placeholder kept for backwards compatibility; it never updates. Read `audioLevelRef.current` instead. |
| `audioLevelRef` | `React.RefObject<number>` | A mutable ref containing the real-time audio level (0--1) -- the louder of the agent's voice and the visitor's microphone -- updated on every animation frame, outside of React's render cycle. Read `audioLevelRef.current` inside `requestAnimationFrame` loops for smooth, jank-free animations, or sample it on an interval when you need the value in React state. |
| `audio` | `ReactNode` | Invisible element that handles the audio connection -- **must be rendered**. |

---

## Audio-Reactive UI

The `audioLevelRef` ref gives you frame-rate audio levels without triggering React re-renders, making it ideal for driving smooth waveform visualizations, pulsing orbs, or any animation tied to the conversation. The level reflects whichever is louder: the agent's voice or the visitor's microphone.

### Waveform Example

```tsx
import { useRef, useEffect } from 'react'
import { useThunderPhone } from '@thunderphone/widget'

function WaveformCall() {
  const phone = useThunderPhone({
    publishableKey: 'pk_live_your_publishable_key',
  })
  const canvasRef = useRef<HTMLCanvasElement>(null)

  useEffect(() => {
    if (phone.state !== 'connected') return
    const canvas = canvasRef.current
    if (!canvas) return
    const ctx = canvas.getContext('2d')!

    let animId: number
    const draw = () => {
      const level = phone.audioLevelRef.current ?? 0
      ctx.clearRect(0, 0, canvas.width, canvas.height)

      // Draw bars that react to audio level
      const barCount = 24
      const barWidth = canvas.width / barCount
      for (let i = 0; i < barCount; i++) {
        const distance = Math.abs(i - barCount / 2) / (barCount / 2)
        const height = level * canvas.height * (1 - distance * 0.6)
        const y = (canvas.height - height) / 2
        ctx.fillStyle = '#0ea5e9'
        ctx.fillRect(i * barWidth + 1, y, barWidth - 2, height)
      }

      animId = requestAnimationFrame(draw)
    }
    animId = requestAnimationFrame(draw)
    return () => cancelAnimationFrame(animId)
  }, [phone.state, phone.audioLevelRef])

  return (
    <div>
      {phone.state === 'connected' && (
        <canvas ref={canvasRef} width={240} height={80} />
      )}
      <button
        onClick={phone.state === 'connected' ? phone.disconnect : phone.connect}
        disabled={phone.state === 'connecting'}
      >
        {phone.state === 'connected' ? 'End call' : 'Start call'}
      </button>
      {phone.audio}
    </div>
  )
}
```

### Pulsing Orb Example

```tsx
import { useRef, useEffect } from 'react'
import { useThunderPhone } from '@thunderphone/widget'

function PulsingOrb() {
  const phone = useThunderPhone({
    publishableKey: 'pk_live_your_publishable_key',
  })
  const orbRef = useRef<HTMLDivElement>(null)

  useEffect(() => {
    if (phone.state !== 'connected') return
    let animId: number
    const animate = () => {
      const level = phone.audioLevelRef.current ?? 0
      if (orbRef.current) {
        const scale = 1 + level * 0.5
        orbRef.current.style.transform = `scale(${scale})`
        orbRef.current.style.opacity = `${0.6 + level * 0.4}`
      }
      animId = requestAnimationFrame(animate)
    }
    animId = requestAnimationFrame(animate)
    return () => cancelAnimationFrame(animId)
  }, [phone.state, phone.audioLevelRef])

  return (
    <div style={{ textAlign: 'center' }}>
      <div
        ref={orbRef}
        style={{
          width: 80,
          height: 80,
          borderRadius: '50%',
          background: '#0ea5e9',
          margin: '20px auto',
          transition: 'transform 0.05s ease-out',
        }}
      />
      <button
        onClick={phone.state === 'connected' ? phone.disconnect : phone.connect}
        disabled={phone.state === 'connecting'}
      >
        {phone.state === 'connected' ? 'End call' : 'Call'}
      </button>
      {phone.audio}
    </div>
  )
}
```

### Speaking Indicator Example

For React-rendered UI that changes with volume -- like a threshold-based "speaking" badge -- sample `audioLevelRef.current` on an interval and store the result in state:

```tsx
import { useEffect, useState } from 'react'
import { useThunderPhone } from '@thunderphone/widget'

function SpeakingBadge() {
  const phone = useThunderPhone({
    publishableKey: 'pk_live_your_publishable_key',
  })
  const [speaking, setSpeaking] = useState(false)

  useEffect(() => {
    if (phone.state !== 'connected') {
      setSpeaking(false)
      return
    }
    const interval = setInterval(() => {
      setSpeaking((phone.audioLevelRef.current ?? 0) > 0.1)
    }, 100)
    return () => clearInterval(interval)
  }, [phone.state, phone.audioLevelRef])

  return (
    <div>
      {phone.state === 'connected' && (
        <span>{speaking ? 'Speaking' : 'Listening'}</span>
      )}
      <button onClick={phone.state === 'connected' ? phone.disconnect : phone.connect}>
        {phone.state === 'connected' ? 'End call' : 'Start call'}
      </button>
      {phone.audio}
    </div>
  )
}
```

<Warning>
  Always read levels from `audioLevelRef.current`. The `audioLevel` number on the return object is **deprecated and always `0`** -- any logic built on it will silently read zero.
</Warning>

---

## State Machine

The `state` property follows this lifecycle:

```
idle --> connecting --> connected --> disconnected --> idle (after 1.5s)
                  \
                   --> error (stays until connect() is called again)
```

| State | Description |
|-------|-------------|
| `idle` | No active session. Ready to call `connect()`. |
| `connecting` | Session is being established. Disable the call button during this state. |
| `connected` | Voice session is active. The user is talking to the agent. |
| `disconnected` | Session has ended cleanly. Transitions back to `idle` automatically after 1.5 seconds. |
| `error` | Something went wrong. Check `phone.error` for the message. The state does **not** clear on its own -- calling `connect()` again starts a fresh attempt and resets the error. |

---

## Examples

### With Mute Control

```tsx
import { useThunderPhone } from '@thunderphone/widget'

function CallWithMute() {
  const phone = useThunderPhone({
    publishableKey: 'pk_live_your_publishable_key',
  })

  return (
    <div>
      {phone.state === 'connected' && (
        <div>
          <p>Talking to {phone.agentName ?? 'Agent'}</p>
          <button onClick={phone.toggleMute}>
            {phone.isMuted ? 'Unmute' : 'Mute'}
          </button>
          <button onClick={phone.disconnect}>End call</button>
        </div>
      )}

      {phone.state !== 'connected' && (
        <button
          onClick={phone.connect}
          disabled={phone.state === 'connecting'}
        >
          {phone.state === 'connecting' ? 'Connecting...' : 'Call support'}
        </button>
      )}

      {phone.state === 'error' && (
        <p style={{ color: 'red' }}>{phone.error}</p>
      )}

      {phone.audio}
    </div>
  )
}
```

### With Ringtone

Play a ringing sound while connecting to simulate a phone call:

```tsx
import { useThunderPhone } from '@thunderphone/widget'

function PhoneCallButton() {
  const phone = useThunderPhone({
    publishableKey: 'pk_live_your_publishable_key',
    ringtone: true, // or a custom URL: 'https://example.com/ringtone.mp3'
  })

  return (
    <>
      <button
        onClick={phone.state === 'connected' ? phone.disconnect : phone.connect}
        disabled={phone.state === 'connecting'}
      >
        {phone.state === 'connecting'
          ? 'Ringing...'
          : phone.state === 'connected'
            ? 'Hang up'
            : 'Call'}
      </button>
      {phone.audio}
    </>
  )
}
```

The ringtone loops during the `connecting` state and fades out when the agent connects. Pass `true` for the built-in default ringtone, or a URL string to use your own audio file.

### With Event Callbacks

```tsx
import { useThunderPhone } from '@thunderphone/widget'

function TrackedCallButton() {
  const phone = useThunderPhone({
    publishableKey: 'pk_live_your_publishable_key',
    onConnect: () => {
      analytics.track('call_started')
    },
    onDisconnect: () => {
      analytics.track('call_ended')
    },
    onError: (error) => {
      analytics.track('call_error', { code: error.error, message: error.message })
    },
  })

  return (
    <>
      <button
        onClick={phone.state === 'connected' ? phone.disconnect : phone.connect}
        disabled={phone.state === 'connecting'}
      >
        {phone.state === 'connected' ? 'Hang up' : 'Talk to AI'}
      </button>
      {phone.audio}
    </>
  )
}
```

### Full Custom UI

```tsx
import { useThunderPhone } from '@thunderphone/widget'

function FullCustomUI() {
  const phone = useThunderPhone({
    publishableKey: 'pk_live_your_publishable_key',
  })

  return (
    <div className="call-panel">
      <div className="call-status">
        {phone.state === 'idle' && <span>Ready</span>}
        {phone.state === 'connecting' && <span className="pulse">Connecting...</span>}
        {phone.state === 'connected' && (
          <span>On call with {phone.agentName}</span>
        )}
        {phone.state === 'error' && <span className="error">{phone.error}</span>}
      </div>

      <div className="call-controls">
        {phone.state === 'connected' ? (
          <>
            <button className="mute-btn" onClick={phone.toggleMute}>
              {phone.isMuted ? 'Unmute' : 'Mute'}
            </button>
            <button className="end-btn" onClick={phone.disconnect}>
              End
            </button>
          </>
        ) : (
          <button
            className="start-btn"
            onClick={phone.connect}
            disabled={phone.state === 'connecting'}
          >
            Start call
          </button>
        )}
      </div>

      {/* Required -- handles audio under the hood */}
      {phone.audio}
    </div>
  )
}
```

---

## Tips

<AccordionGroup>
  <Accordion title="Always render phone.audio">
    The `phone.audio` element is invisible but required. Place it anywhere in your JSX -- it renders no visible DOM but manages the WebRTC audio connection internally.
  </Accordion>

  <Accordion title="Disable the button while connecting">
    The `connecting` state can last 1-3 seconds. Disable the call button during this state to prevent duplicate connection attempts.
  </Accordion>

  <Accordion title="Handle the error state gracefully">
    When the state is `error`, display `phone.error` to the user and keep your call button enabled. The hook does not leave the `error` state on its own -- calling `connect()` again starts a fresh attempt and clears the previous error.
  </Accordion>

  <Accordion title="Use callbacks for side effects">
    The `onConnect`, `onDisconnect`, and `onError` callbacks are ideal for analytics, logging, or triggering other application logic without polling the state.
  </Accordion>

  <Accordion title="Read audio levels from audioLevelRef">
    `audioLevelRef` is the only live audio-level source. Read `audioLevelRef.current` inside `requestAnimationFrame` for smooth animations like waveforms (reading a ref does not cause re-renders), or sample it on an interval and store the result in state for React-rendered UI. The `audioLevel` number is deprecated and always `0` -- do not build logic on it.
  </Accordion>
</AccordionGroup>

<!-- en: widget/cdn-script-tag -->
---
title: "CDN / Script Tag"
description: "Add the ThunderPhone voice widget to any website without a bundler"
---

The CDN build bundles React internally, so you can use the widget on static sites, WordPress, Webflow, or any page where you can add HTML. No npm, no bundler, no framework required.

## CDN URLs

<CodeGroup>
```html Latest (recommended)
<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
```

```html Pinned version
<!-- Each stable release also publishes an immutable /widget/vX.Y.Z/ path
     matching the @thunderphone/widget npm version (v1.1.2 at the time of
     writing). If you pin, you own updating the URL for new releases. -->
<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/v1.1.2/style.css" />
<script src="https://cdn.thunderphone.com/widget/v1.1.2/widget.js"></script>
```
</CodeGroup>

<Tip>
  The `latest` URLs are what the dashboard's embed snippet generator produces. They are cached for 5 minutes and pick up new stable releases automatically. Pinned `/widget/vX.Y.Z/` paths are immutable and cached long-term -- if you pin, match the version to the `@thunderphone/widget` npm release you develop against.
</Tip>

---

## Basic Usage

```html
<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
</head>
<body>

  <div id="thunderphone"></div>

  <script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
  <script>
    ThunderPhone.mount({
      element: '#thunderphone',
      publishableKey: 'pk_live_your_publishable_key',
    })
  </script>

</body>
</html>
```

The widget mounts into the target element and renders as a **fixed-position bar in a corner of the viewport** (default `bottom-right`, controlled by the `position` option). The mount element is only the React root -- its location in the page does not affect where the widget appears.

---

## Mount Options

`ThunderPhone.mount()` accepts the same options as the React component, plus the `element` property:

| Option | Type | Required | Default | Description |
|--------|------|----------|---------|-------------|
| `element` | `string \| HTMLElement` | Yes | -- | CSS selector (e.g., `'#thunderphone'`) or a DOM element reference. |
| `publishableKey` | `string` | Yes | -- | Publishable API key (`pk_live_...`). The agent is resolved automatically from the key's widget configuration. |
| `theme` | `'light' \| 'dark'` | No | `'light'` | Color scheme. |
| `primaryColor` | `string` | No | `'#000000'` (light) / `'#ffffff'` (dark) | CSS color string used as the accent color. |
| `title` | `string` | No | `'Voice assistant'` | Text displayed in the widget bar. |
| `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | No | `'bottom-right'` | Fixed viewport position. |
| `apiBase` | `string` | No | `'https://api.thunderphone.com/v1'` | API base URL override. |
| `language` | `string` | No | -- | Per-session language override -- a language code or locale such as `en`, `es`, or `fr-FR`. When unset, the agent's configured language applies. Requires `language` under the key's [browser overrides](/guides/embed-web-widget#browser-overrides). |
| `voice` | `string` | No | -- | Per-session voice override -- a voice name such as `maria`. When unset, the agent's configured voice applies. Requires `voice` under the key's [browser overrides](/guides/embed-web-widget#browser-overrides). |
| `context` | `string` | No | -- | Per-session factual page or site context passed to the agent. Truncated server-side to 12,000 characters. Requires `context` under the key's [browser overrides](/guides/embed-web-widget#browser-overrides). |
| `onConnect` | `() => void` | No | -- | Called when the voice session connects. |
| `onDisconnect` | `() => void` | No | -- | Called when the session ends. |
| `onError` | `(error) => void` | No | -- | Called on errors. Error has `error` (code) and `message` fields. |
| `ringtone` | `boolean \| string` | No | `false` | Play a ringtone while connecting. `true` for the default ringtone, or a URL string for custom audio. |

---

## Cleanup

`ThunderPhone.mount()` returns a widget instance with cleanup methods:

```html
<script>
  var widget = ThunderPhone.mount({
    element: '#thunderphone',
    publishableKey: 'pk_live_your_publishable_key',
  })

  // Later, when you want to remove the widget:
  widget.unmount()

  // Or equivalently:
  widget.destroy()
</script>
```

Both `unmount()` and `destroy()` do the same thing -- they disconnect any active voice session and remove the widget from the DOM. Use whichever reads better in your code.

<Note>
  Always clean up the widget when navigating away in single-page applications or when the containing element is removed. This ensures active voice sessions are properly disconnected.
</Note>

---

## Examples

### Dark Theme with Custom Color

```html
<div id="thunderphone"></div>

<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
<script>
  ThunderPhone.mount({
    element: '#thunderphone',
    publishableKey: 'pk_live_your_publishable_key',
    theme: 'dark',
    primaryColor: '#8b5cf6',
    title: 'Talk to our AI',
  })
</script>
```

### Custom Position

```html
<div id="thunderphone"></div>

<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
<script>
  ThunderPhone.mount({
    element: '#thunderphone',
    publishableKey: 'pk_live_your_publishable_key',
    position: 'bottom-left',
  })
</script>
```

### With Event Callbacks

```html
<div id="thunderphone"></div>

<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
<script>
  ThunderPhone.mount({
    element: '#thunderphone',
    publishableKey: 'pk_live_your_publishable_key',
    onConnect: function () {
      console.log('Call started')
    },
    onDisconnect: function () {
      console.log('Call ended')
    },
    onError: function (error) {
      console.error('Widget error:', error.error, error.message)
    },
  })
</script>
```

### With Ringtone

```html
<div id="thunderphone"></div>

<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
<script>
  ThunderPhone.mount({
    element: '#thunderphone',
    publishableKey: 'pk_live_your_publishable_key',
    ringtone: true, // or a custom URL: 'https://example.com/ringtone.mp3'
  })
</script>
```

### Using a DOM Element Reference

```html
<div id="thunderphone"></div>

<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
<script>
  var container = document.getElementById('thunderphone')

  ThunderPhone.mount({
    element: container,
    publishableKey: 'pk_live_your_publishable_key',
  })
</script>
```

### WordPress / CMS Integration

Add this to a Custom HTML block or your theme's footer:

```html
<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>

<div id="thunderphone-widget"></div>
<script>
  ThunderPhone.mount({
    element: '#thunderphone-widget',
    publishableKey: 'pk_live_your_publishable_key',
  })
</script>
```

<Tip>
  The `<div>` can go anywhere -- it is only the mount point. The widget itself renders as a fixed overlay in a viewport corner (set by the `position` option) and does not flow with surrounding content.
</Tip>

---

## Troubleshooting

<AccordionGroup>
  <Accordion title="Widget doesn't appear">
    Make sure both the CSS and JS files are loaded. Check the browser console for network errors. Verify that the target element exists in the DOM before calling `ThunderPhone.mount()`.
  </Accordion>

  <Accordion title="ThunderPhone is not defined">
    The script has not loaded yet. Ensure the `<script>` tag for `widget.js` appears before your mount call, or wrap the mount call in a `DOMContentLoaded` listener.
  </Accordion>

  <Accordion title="Domain not allowed error">
    Add your domain to the widget's allowed domains on the **Web Widgets** page at [app.thunderphone.com](https://app.thunderphone.com). `localhost` is not allowed automatically in production; add it to the list to test locally.
  </Accordion>
</AccordionGroup>

---

## Next Steps

<CardGroup cols={2}>
  <Card title="Styling" icon="palette" href="/widget/styling">
    Customize the widget appearance with CSS custom properties.
  </Card>
  <Card title="React Component" icon="react" href="/widget/react">
    Using React? The component integration is simpler.
  </Card>
</CardGroup>

<!-- en: widget/styling -->
---
title: "Styling"
description: "Customize the appearance of the ThunderPhone voice widget with CSS"
---

The widget renders as a glassmorphic bar with built-in light and dark themes. Customization is available at three levels: props for common options, CSS custom properties for theming, and CSS class overrides for full control.

<Note>
  These styling options apply to the pre-built widget rendered by the `ThunderPhoneWidget` React component and the `ThunderPhone.mount()` CDN method. If you need a completely custom UI, use the [headless hook](/widget/headless-hook) instead.
</Note>

---

## Themes

The `theme` prop controls the widget's color scheme. It applies a `tp--light` or `tp--dark` class to the widget root:

```tsx
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  theme="dark"
/>
```

| Theme | Class | Description |
|-------|-------|-------------|
| `'light'` | `tp--light` | Light background with dark text. Default. |
| `'dark'` | `tp--dark` | Dark background with light text. |

Both themes use the glassmorphic bar design with backdrop blur and subtle transparency.

---

## CSS Custom Properties

The widget exposes CSS custom properties (variables) that you can override to change colors without touching individual classes. They are defined by the theme class (`.tp--light` or `.tp--dark`) applied to the `.tp-widget` root:

| Property | Default (light) | Default (dark) | Description |
|----------|-----------------|-----------------|-------------|
| `--tp-accent` | `#000` | `#fff` | Accent color: start button, waveform bars, connecting dot, connected-status text. Set **inline** from the `primaryColor` prop. |
| `--tp-bg` | `rgba(255, 255, 255, 0.82)` | `rgba(15, 15, 15, 0.85)` | Bar background (translucent; blurred by `--tp-glass`). |
| `--tp-surface` | `rgba(0, 0, 0, 0.04)` | `rgba(255, 255, 255, 0.07)` | Mute-button background. |
| `--tp-surface-hover` | `rgba(0, 0, 0, 0.07)` | `rgba(255, 255, 255, 0.12)` | Mute-button hover background. |
| `--tp-border` | `rgba(0, 0, 0, 0.08)` | `rgba(255, 255, 255, 0.1)` | Bar and button borders. |
| `--tp-border-hover` | `rgba(0, 0, 0, 0.14)` | `rgba(255, 255, 255, 0.18)` | Border color on hover. |
| `--tp-text` | `rgba(0, 0, 0, 0.88)` | `rgba(255, 255, 255, 0.95)` | Primary text (title, agent name). |
| `--tp-text-2` | `rgba(0, 0, 0, 0.5)` | `rgba(255, 255, 255, 0.55)` | Secondary text (subtitle, status line, call timer). |
| `--tp-glass` | `blur(32px) saturate(180%)` | `blur(32px) saturate(180%)` | `backdrop-filter` that creates the glass effect on the bar. |
| `--tp-shadow` | three-layer shadow stack | three-layer shadow stack | The bar's `box-shadow` (ring + near + far layers). |
| `--tp-shadow-hover` | three-layer shadow stack | three-layer shadow stack | Declared for hover elevation; not currently applied by any rule. |
| `--tp-glow` | `inset 0 1px 0 0 rgba(255,255,255,0.5)` | `inset 0 1px 0 0 rgba(255,255,255,0.06)` | Inner top highlight layered onto the bar shadow. |
| `--tp-connected` | `#059669` | `#34d399` | Connected-state indicator color (status dot). |
| `--tp-error` | `#dc2626` | `#fb7185` | Error-state status text color. |
| `--tp-end-bg` | `rgba(239, 68, 68, 0.08)` | `rgba(251, 113, 133, 0.12)` | End-call button background. |
| `--tp-end-color` | `#ef4444` | `#fb7185` | End-call button icon color. |
| `--tp-end-border` | `rgba(239, 68, 68, 0.12)` | `rgba(251, 113, 133, 0.15)` | End-call button border. |
| `--tp-end-hover` | `rgba(239, 68, 68, 0.14)` | `rgba(251, 113, 133, 0.2)` | End-call button hover background. |
| `--tp-idle-opacity` | `0.4` | `0.3` | Declared for idle-state dimming; not currently applied by any rule. |

### Overriding Custom Properties

Set the accent color via the `primaryColor` prop:

```tsx
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  primaryColor="#e11d48"
/>
```

<Warning>
  `--tp-accent` is set as an **inline style** from the `primaryColor` prop, so stylesheet overrides of `--tp-accent` have no effect. Change the accent with the prop. Every other custom property can be overridden in CSS.
</Warning>

Override the other custom properties with CSS. Use a two-class selector (`.tp-widget.tp--light` / `.tp-widget.tp--dark`) so your rule outweighs the theme class that defines the defaults, regardless of stylesheet order:

```css
.tp-widget.tp--light {
  --tp-bg: rgba(0, 0, 0, 0.9);
  --tp-text: rgba(255, 255, 255, 0.95);
  --tp-text-2: rgba(255, 255, 255, 0.55);
  --tp-border: rgba(255, 255, 255, 0.15);
}
```

---

## CSS Classes

All widget classes are prefixed with `tp-` to avoid conflicts with your existing styles.

| Class | Element | Description |
|-------|---------|-------------|
| `.tp-widget` | Root wrapper | Fixed-position container (`position: fixed`, corner set by the `position` prop, `z-index: 9999`). Carries the theme class and base font settings; no visual chrome of its own. |
| `.tp--light` / `.tp--dark` | Theme modifiers | Applied to `.tp-widget` alongside the theme; define all `--tp-*` custom properties. |
| `.tp-bar` | The bar | The glassmorphic pill itself: background, backdrop blur, border, `99px` radius, shadow. `300px` wide. |
| `.tp-meta` | Text block | Container for all text -- title and subtitle when idle, agent name and status during a call. |
| `.tp-name` | Primary label | Shows the `title` prop when idle, and the connected agent's name (falling back to `title`) during a call. |
| `.tp-sub` | Subtitle | The "Available now" line shown when idle. |
| `.tp-start` | Idle call button | The circular accent start button (42px). Uses `--tp-accent` as background. |
| `.tp-dot` | Connecting dot | Pulsing accent dot shown at the left of the bar while connecting. |
| `.tp-wave` / `.tp-wave--idle` | Waveform | The five-bar waveform. `--idle` adds the slow breathing animation; during a call the bars are audio-reactive. |
| `.tp-button` | In-call buttons | Base style for the in-call controls (42px, rounded 12px). |
| `.tp-button-group` | Button row | Wraps the mute and end buttons during a call. |
| `.tp-button--start` | Connect button variant | Accent-colored variant shown while a call is starting. |
| `.tp-button--mute` | Mute toggle | Mutes/unmutes the mic during a call. Uses `--tp-surface`. |
| `.tp-button--end` | End call button | Hangs up. Uses the `--tp-end-*` palette. |
| `.tp-button--loading` | Loading modifier | Dims the button while connecting. |
| `.tp-icon` / `.tp-spin` | Icons | Button icon sizing; `tp-spin` animates the connecting spinner. |
| `.tp-status` | In-call status block | Wraps the status line during connecting/connected/error states. |
| `.tp-status__text` | Status line | Connection state text (e.g., "Connecting...") or the call timer. Gets `.tp-status--connected` (accent color) or `.tp-status--error` (error color) per state. |
| `.tp-status__name` | Agent-name slot | Part of the status block, but not rendered in the current bar layout -- the agent name appears in `.tp-name` instead. |
| `.tp-status__dot` | Status dot | Pulsing connected-state dot style (uses `--tp-connected`). |

---

## Examples

### Custom Accent via Props

The simplest way to brand the widget:

```tsx
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  theme="light"
  primaryColor="#059669"
  title="Talk to support"
/>
```

### Custom Colors via CSS

Override the custom properties for full color control. Remember that the accent comes from the `primaryColor` prop, not CSS:

```tsx
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  primaryColor="#059669"
/>
```

```css
/* Emerald theme for everything else */
.tp-widget.tp--light {
  --tp-bg: rgba(236, 253, 245, 0.85);
  --tp-text: rgba(6, 78, 59, 0.95);
  --tp-text-2: rgba(4, 120, 87, 0.8);
  --tp-border: rgba(5, 150, 105, 0.2);
}
```

### Custom Size

Make the widget larger or smaller by adjusting the bar, button, and text dimensions:

```css
/* Wider bar */
.tp-bar {
  width: 340px;
}

/* Larger buttons (42px by default) */
.tp-start,
.tp-button {
  width: 56px;
  height: 56px;
}

/* Larger text */
.tp-name {
  font-size: 16px;
}

.tp-sub,
.tp-status__text {
  font-size: 14px;
}
```

### Hide the Text Labels

All of the widget's text lives in `.tp-meta`. Hide it entirely to keep just the waveform and buttons:

```css
.tp-meta {
  display: none;
}
```

Or hide individual pieces:

```css
/* Hide only the idle "Available now" subtitle */
.tp-sub {
  display: none;
}

/* Hide only the in-call status line (connection state / timer) */
.tp-status {
  display: none;
}
```

<Note>
  The idle label lives in `.tp-name`/`.tp-sub`, not `.tp-status` -- hiding `.tp-status` alone still shows the title when the widget is idle.
</Note>

### Theme-Specific Overrides

Target a specific theme with the theme class:

```css
/* Only affect dark theme */
.tp--dark .tp-start {
  box-shadow: 0 0 20px rgba(255, 255, 255, 0.25);
}

/* Only affect light theme */
.tp-widget.tp--light {
  --tp-bg: rgba(255, 255, 255, 0.95);
}
```

---

## Scoping with className

When using the React component, pass a `className` prop to scope your overrides to a specific widget instance:

```tsx
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  theme="dark"
  className="support-widget"
/>
```

Then target that class in your CSS:

```css
.support-widget.tp--dark {
  --tp-bg: rgba(30, 30, 46, 0.9);
}

.support-widget .tp-name {
  font-weight: 700;
}
```

This lets you have multiple widget instances on the same page with different styles. Give each instance its own accent through its `primaryColor` prop (CSS cannot override `--tp-accent` -- it is set inline).

---

## Fully Custom UI

If CSS overrides are not enough, the [headless hook](/widget/headless-hook) gives you full control. You provide all the HTML and styling while `useThunderPhone` handles the voice session. The hook also provides `audioLevelRef` for building audio-reactive visualizations like waveforms.

```tsx
import { useThunderPhone } from '@thunderphone/widget'

function MyWidget() {
  const phone = useThunderPhone({
    publishableKey: 'pk_live_your_publishable_key',
  })

  return (
    <div className="my-totally-custom-widget">
      {/* Your own buttons, animations, layouts -- anything */}
      <button onClick={phone.state === 'connected' ? phone.disconnect : phone.connect}>
        {phone.state === 'connected' ? 'Hang up' : 'Call us'}
      </button>
      {phone.audio}
    </div>
  )
}
```

<Tip>
  The headless hook is the right choice when you need audio-reactive animations, custom layouts, or integration into an existing component library. CSS overrides and custom properties are better for quick theming adjustments.
</Tip>

<!-- en: webhooks/overview -->
---
title: "Webhooks Overview"
description: "How ThunderPhone delivers real-time events, how to verify signatures, and how the legacy and endpoint-based delivery models compare."
---

ThunderPhone sends HTTP `POST` requests to your server when things
happen during a call — an inbound call starts, a call ends, a grading
run completes, an alert fires, and so on. There are **two delivery
models**:

<CardGroup cols={2}>
  <Card title="Webhook endpoints (recommended)" icon="bolt" href="/webhooks/endpoints">
    Multiple URLs, per-endpoint secrets, per-endpoint event filters,
    and automatic retries.
    Manage via `GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints`.
  </Card>
  <Card title="Single-URL legacy webhook" icon="link" href="/api-reference/organizations#legacy-single-url-webhook">
    One URL per org. Carries the call-lifecycle events, including the
    **blocking** configuration exchanges. Managed at `GET/PUT /v1/webhook`.
  </Card>
</CardGroup>

All listed event types in the [events catalog](/webhooks/events) are
delivered through webhook endpoints. The six call-lifecycle events
(`telephony.incoming`, `telephony.complete`, `telephony.tool`,
`web.incoming`, `web.complete`, `web.tool`) are **also** sent to the
legacy single-URL webhook — if you have both a legacy URL and a
matching endpoint, you receive the event on **both** paths. Blocking
behavior (the [`telephony.incoming` / `web.incoming` configuration
exchange](/webhooks/call-incoming) and webhook-mode
[tool dispatch](/tools/overview#webhook-mode-dispatch)) lives
exclusively on the legacy path; every endpoint delivery is a
fire-and-forget notification.

## Payload format

Endpoint deliveries are a JSON object with `data`, `event_id`, and
`type`:

```json
{
  "data": {
    "call_id": 987654321,
    "from_number": "+14155550199",
    "to_number": "+15551234567"
  },
  "event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11",
  "type": "telephony.incoming"
}
```

`event_id` is unique per emitted event. It is identical across retries
**and** across every endpoint that receives the event — dedup on it.

The legacy single-URL webhook sends the same `type` and `data` but
**without** `event_id`:

```json
{
  "type": "telephony.incoming",
  "data": { "call_id": 987654321, "from_number": "+14155550199", "to_number": "+15551234567" }
}
```

On the wire, every body is serialized canonically — keys sorted
alphabetically, no whitespace, UTF-8. The pretty-printed examples in
these docs are for readability only.

See the [Events catalog](/webhooks/events) for the full list of event
types and payload fields.

## Signature verification

Every request carries two signatures, both HMAC-SHA256 keyed with the
endpoint's `secret` (or your org-level webhook `secret` for legacy
deliveries):

- `X-ThunderPhone-Signature-V2: t=<unix seconds>,v1=<hex>` signs the
  timestamp, the method, the path and query, and the raw body. Verify
  this one, and reject requests whose `t` is more than **5 minutes** from
  your clock so a captured request cannot be replayed later. Retries are
  signed again when they are sent.
- `X-ThunderPhone-Signature` signs the raw body only. It is still sent,
  unchanged, so existing verifiers keep working.

### Steps

1. Read the header, the method, the raw path and query, and the raw
   body **before** any parsing.
2. Compute the hex HMAC-SHA256 of
   `<t>\n<METHOD>\n<path and query>\n<body>` with your secret.
3. Reject the request if `t` is more than 300 seconds off, or if the
   result does not match `v1` in a constant-time comparison.

Bodies are the canonical JSON serialization (sorted keys, compact
separators), and we sign exactly the bytes we transmit. The
[verification guide](/guides/verify-webhook-signatures) has the exact
signed string, a worked example, code without the SDK, and the legacy
header.

<CodeGroup>
```python Python (Flask)
from flask import Flask, abort, request
from thunderphone import verify_signature

app = Flask(__name__)

@app.post("/thunderphone-webhook")
def handle():
    query = request.query_string.decode()
    if not verify_signature(
        request.headers.get("X-ThunderPhone-Signature-V2"),
        secret=WEBHOOK_SECRET,
        method=request.method,
        path=request.path + (f"?{query}" if query else ""),
        body=request.get_data(),  # raw bytes
    ):
        abort(401)
    event = request.get_json()
    # dispatch on event["type"] …
    return "", 204
```

```javascript Node.js (Express)
import express from "express";
import { verifySignature } from "@thunderphone/sdk";

const app = express();
app.post(
  "/thunderphone-webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const ok = verifySignature({
      header: req.header("X-ThunderPhone-Signature-V2"),
      secret: process.env.WEBHOOK_SECRET,
      method: req.method,
      path: req.originalUrl,
      body: req.body,
    });
    if (!ok) return res.sendStatus(401);
    const event = JSON.parse(req.body.toString("utf8"));
    // dispatch on event.type …
    res.sendStatus(204);
  },
);
```
</CodeGroup>

## Delivery semantics

These semantics apply to **endpoint** deliveries. The legacy single-URL
webhook is a single synchronous attempt with no retries, except the
phone-call [`telephony.incoming`](/webhooks/call-incoming#timeouts-and-retries)
configuration exchange, which is retried once.

<AccordionGroup>
  <Accordion title="Retries">
    Each event is attempted once immediately. Any `2xx` response
    acknowledges the delivery. On any other outcome (non-2xx,
    connection error, timeout) we retry at **1 m, 5 m, 30 m, 2 h, 6 h,
    12 h, and 24 h after the first attempt** — 8 attempts spanning
    24 hours. If every attempt fails, delivery stops and the endpoint
    is marked `status="failing"` in
    [webhook endpoints](/webhooks/endpoints); we email your organization's
    owners and admins and show it in the dashboard. Return `2xx` as soon as
    the payload is durably accepted; process asynchronously.
    Test sends from the endpoint test API get one retry about a minute after
    the first attempt and never change the endpoint's status.
  </Accordion>

  <Accordion title="Ordering">
    Delivery ordering is best-effort. In practice we deliver in the
    order events are emitted, but retries can reorder on failure.
    Always dedup and reconcile by `call_id` / object id.
  </Accordion>

  <Accordion title="Duplicates">
    Delivery is **at-least-once**: a retry after a response we never
    saw can duplicate an event. Every retry carries the same
    `event_id`, so store processed ids and skip repeats. `event_id` is
    also shared across endpoints — two endpoints subscribed to the
    same event receive the same `event_id`.
  </Accordion>

  <Accordion title="Timeouts">
    Endpoint deliveries have a **30 s** timeout per attempt. On the
    legacy path, blocking requests that drive live call behavior — the
    [`telephony.incoming` / `web.incoming`](/webhooks/call-incoming)
    configuration exchange — are limited to **10 s** for a phone call's
    first attempt and **13 s** for the whole exchange including its one
    retry, and to **10 s** for a widget session. A slow response delays
    call pickup, so aim to answer within a couple of seconds. Webhook-mode [tool dispatch](/tools/overview) allows 20 s
    by default, and tool declarations may set a top-level `timeout`.
  </Accordion>

  <Accordion title="Source IPs">
    Outbound webhooks originate from ThunderPhone's cloud IP range.
    If your firewall requires an allowlist, contact support and we'll
    share the current ranges.
  </Accordion>
</AccordionGroup>

## Choosing between legacy and endpoint-based webhooks

| Feature | Legacy (`/v1/webhook`) | Endpoints (`/v1/developer/webhook-endpoints`) |
|---------|------------------------|----------------------------------------------|
| Number of URLs | 1 per org | Many per org |
| Event coverage | `telephony.*` / `web.*` only | All 10 event types |
| Event filter | — | Per-endpoint |
| Retries | None, except one for the phone-call configuration exchange | 8 attempts over 24 h |
| Envelope | `type` + `data` | `type` + `data` + `event_id` |
| Secret rotation | Replaces single secret | Per-endpoint secret |
| Disable without delete | `PUT /v1/webhook` with `{"url": ""}` | `status=disabled` |
| Status visibility | — | `active` / `disabled` / `failing` |
| Blocking config exchange | Yes ([`telephony.incoming` / `web.incoming`](/webhooks/call-incoming)) | Never — notifications only |
| Best for | Dynamic call configuration | Event consumption in production |

New integrations should consume events through endpoint-based
webhooks. Keep (or add) a legacy URL only if you configure calls
dynamically at pickup time or use webhook-mode tool dispatch — those
request/response exchanges only run on the legacy path.

---

## Related

<CardGroup cols={2}>
  <Card title="Events catalog" icon="list" href="/webhooks/events">
    All event types and their payloads.
  </Card>
  <Card title="Webhook endpoints" icon="bolt" href="/webhooks/endpoints">
    Manage multiple endpoints, event filters, and secrets.
  </Card>
  <Card title="telephony.incoming / web.incoming" icon="phone" href="/webhooks/call-incoming">
    The blocking request your server must answer to configure calls.
  </Card>
  <Card title="telephony.complete / web.complete" icon="phone" href="/webhooks/call-complete">
    Post-call payload with transcript, recording, and metrics.
  </Card>
</CardGroup>

<!-- en: webhooks/endpoints -->
---
title: "Webhook Endpoints"
description: "Manage multiple webhook URLs with per-endpoint secrets and event filters."
---

The endpoint-based webhook system lets you register **multiple**
destinations per organization, each with its own secret, its own
status, and its own subscription to a subset of event types. This is
the recommended model for all new integrations.

Compare to the [legacy single-URL webhook](/api-reference/organizations#legacy-single-url-webhook),
which is kept for backward compatibility but only supports one URL per
org.

## Endpoints

| Method | Path | Required role | Description |
|--------|------|---------------|-------------|
| `GET` | `/v1/developer/webhook-endpoints` | `admin+` | List endpoints |
| `POST` | `/v1/developer/webhook-endpoints` | `admin+` | Create an endpoint |
| `PATCH` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Update label / URL / events / status |
| `DELETE` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Delete an endpoint |
| `POST` | `/v1/developer/webhook-endpoints/{endpoint_id}/rotate-secret` | `admin+` | Replace the signing secret |
| `POST` | `/v1/developer/webhook-endpoints/{endpoint_id}/test` | `admin+` | Send a signed test delivery |
| `GET` | `/v1/developer/webhook-deliveries` | `admin+` | Inspect recent endpoint and legacy delivery results |

## Endpoint object

```json
{
  "id": "c4d5e6f7-...",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "agent_id": 42,
  "agent_name": "Support Agent",
  "secret_hint": "a1b2…9f0e",
  "paused_at": null,
  "pause_last_error": "",
  "pause_undelivered_count": null,
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Endpoint id |
| `label` | string | Display name, 1–120 chars |
| `url` | string | HTTPS URL; `http://localhost` allowed for dev |
| `events` | array of string | Subscribed event types (see [valid values](#valid-event-types)). Empty array subscribes to all events except the explicit-only per-turn events (`telephony.turn` / `web.turn`) |
| `status` | string | `active`, `disabled` (manually paused), or `failing` (auto-set when a delivery exhausts its 24 h retry schedule without a single 2xx) |
| `agent_id` | integer \| null | Agent this endpoint is scoped to; `null` means organization-wide |
| `agent_name` | string \| null | Name of the scoped agent, or `null` for an organization-wide endpoint |
| `secret_hint` | string | First 4 and last 4 characters of the signing secret with an ellipsis (`a1b2…9f0e`) — enough to cross-reference the secret you saved locally without exposing the full value |
| `paused_at` | timestamp \| null | When ThunderPhone set the endpoint to `failing`. `null` while it is `active` or `disabled` |
| `pause_last_error` | string | The last delivery error when the endpoint was paused, for example `HTTP 503: Service Unavailable`. Empty unless `failing` |
| `pause_undelivered_count` | integer \| null | Events not delivered since the endpoint's last successful delivery, counted when it was paused |
| `created_at`, `updated_at` | timestamp | |

<Note>
  The endpoint's full `secret` is returned **once** on creation and
  never again. Store it securely — if you lose it,
  [rotate it](#rotate-the-signing-secret) to get a new one.
</Note>

### Valid event types

`events` is validated against this exact set — values outside the list
return `400`. See [Events catalog](/webhooks/events) for each type's
payload shape.

- `telephony.incoming`, `telephony.complete`, `telephony.tool`, `telephony.turn`
- `web.incoming`, `web.complete`, `web.tool`, `web.turn`
- `sms.sent`, `sms.failed`
- `sms.received` (reserved; not emitted yet)
- `scheduled.skipped`, `scheduled.failed`
- `call.graded`, `call.data_extracted`, `call.transfer_completed`
- `campaign.completed`
- `issue.reported`, `issue.escalated`
- `test-call.completed`
- `alert.triggered`
- `phone_number.spam_risk_changed`

`issue.escalated` and `phone_number.spam_risk_changed` have no agent context and
are delivered only to organization-wide endpoints.

`voice.ready` and `voice.failed` cannot be selected explicitly. To receive
them, create an organization-wide endpoint with `events: []`. An empty event
list receives every supported event except `telephony.turn` and `web.turn`,
which must be selected explicitly.

### Endpoint statuses

- `active` — deliveries flow normally.
- `disabled` — manually paused via `PATCH`. No requests are sent. We
  never change a `disabled` endpoint's status; flipping it back to
  `active` is always your call.
- `failing` — set automatically when a delivery to the endpoint burns
  through its entire retry schedule (8 attempts over 24 hours) without
  ever getting a 2xx. A failing endpoint receives no further traffic.
  We email your organization's owners and admins when this happens, and
  the dashboard shows the paused endpoint with a Re-activate button.
  Once the endpoint is fixed, `PATCH` its status back to `active`;
  deliveries whose retry schedule hasn't run out yet resume where they
  left off.

---

## List endpoints

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Returns an array of [Endpoint objects](#endpoint-object).
Pass `?agent_id=42` to return only endpoints scoped to that agent.

### Agent-scoped endpoints

Organization-wide endpoints receive every matching event. An endpoint with
`agent_id` receives only matching events for calls handled by that agent;
events without agent context, such as `alert.triggered`, never reach it. You
can also create and manage these endpoints from the agent builder's
**Webhooks** section.

---

## Create an endpoint

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call events",
    "url":    "https://example.com/thunderphone/hook",
    "events": ["telephony.incoming", "telephony.complete"]
  }'
```

```python Python
result = requests.post(
    "https://api.thunderphone.com/v1/developer/webhook-endpoints",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={
        "label":  "Production — Call events",
        "url":    "https://example.com/thunderphone/hook",
        "events": ["telephony.incoming", "telephony.complete"],
    },
).json()
secret = result["secret"]
endpoint_id = result["id"]
```
</CodeGroup>

### Request fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `label` | string | yes | 1–120 chars |
| `url` | string | yes | HTTPS URL (`http` allowed only for `localhost` / `127.0.0.1`) |
| `events` | array | no | Empty/omitted subscribes to all events except `telephony.turn` / `web.turn`, which require an explicit subscription. Must use the values listed in [Valid event types](#valid-event-types); duplicates are removed |
| `agent_id` | integer \| null | no | Scope delivery to an agent in this organization; omit or use `null` for an organization-wide endpoint |

Returns `201 Created` with the [Endpoint object](#endpoint-object) plus
an extra top-level `secret` field containing the raw signing key — a
48-character hex string:

```json
{
  "id": "c4d5e6f7-…",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "secret_hint": "a1b2…9f0e",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z",
  "secret": "a1b2c37e08d94f5b16a2c8d90e7f3a4b5c6d7e8f90a19f0e"
}
```

<Warning>
  `secret` is returned **only on creation**. Subsequent `GET` responses
  include only the `secret_hint`. Copy the full value to your secret
  manager before dismissing the response.
</Warning>

---

## Update an endpoint

<CodeGroup>
```bash cURL
curl -X PATCH https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call + Grade events",
    "events": ["telephony.incoming", "telephony.complete", "call.graded"]
  }'
```
</CodeGroup>

| Field | Type | Description |
|-------|------|-------------|
| `label` | string | |
| `url` | string | |
| `events` | array | |
| `status` | string | `active` or `disabled`. Set `active` to re-enable an endpoint the server marked `failing` |
| `agent_id` | integer \| null | Set an agent id to scope the endpoint, or `null` to make it organization-wide |

Returns `200 OK` with the updated [Endpoint object](#endpoint-object).

---

## Rotate the signing secret

Replace an endpoint's signing secret, for example when it was lost or
may have leaked. For an agent-scoped endpoint you can also use the
dashboard: open the agent's **Webhooks** section and choose
**Regenerate secret** on the endpoint. Organization-wide endpoints are
rotated through the API.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../rotate-secret \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```
</CodeGroup>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `include_copies` | boolean | no | Default `true`. Also gives the new secret to your organization's other endpoints that have the same URL and the same current secret, such as copies of this endpoint on other agents, so one receiver keeps verifying with one secret |

Returns `200 OK`:

```json
{
  "endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
  "secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
  "rotated_endpoint_ids": ["c4d5e6f7-..."]
}
```

| Field | Type | Description |
|-------|------|-------------|
| `endpoint` | object | The [Endpoint object](#endpoint-object) with its new `secret_hint` |
| `secret` | string | The new signing secret. Returned only in this response |
| `rotated_endpoint_ids` | array of UUID | Every endpoint that now uses the new secret |

<Warning>
  The old secret stops being used immediately: the next delivery,
  retries included, is signed with the new one. Until your receiver has
  the new secret, deliveries fail its signature check; if it answers
  those with a non-2xx status they are retried on the normal 24 h
  schedule, so update the receiver promptly. If your receiver rolls out
  in stages, have it accept both secrets during the rollout — the SDK
  verification helpers take a list of secrets (see
  [Verify webhook signatures](/guides/verify-webhook-signatures)).
</Warning>

---

## Send a test delivery

Send a synthetic `webhook.test` event to one endpoint using the normal
delivery pipeline, including canonical JSON serialization, both
signature headers, delivery recording, and retry bookkeeping.
The test targets the selected endpoint regardless of its `events` filter.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

The endpoint receives an envelope like:

```json
{
  "data": {
    "message": "ThunderPhone webhook test",
    "sent_at": "2026-07-17T20:12:34.567890+00:00"
  },
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "type": "webhook.test"
}
```

The API returns `200 OK` after the first attempt, even if the destination
returns an error. Inspect `success`, `status`, `response_code`, and `error`
for the delivery outcome:

```json
{
  "success": true,
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "event_type": "webhook.test",
  "status": "delivered",
  "response_code": 204,
  "error": ""
}
```

`webhook.test` is synthetic and cannot be added to an endpoint's `events`
subscription. If the first attempt fails, ThunderPhone retries it once about
one minute later and then stops; the delivery then shows `status: "failed"`
under [Debug deliveries](#debug-deliveries). A test delivery never marks
the endpoint `failing`.

To configure a trigger against a real event shape, pass an optional
`event_type`. The delivery is still synthetic and contains `"sample": true`;
call-related samples use `call_id: 0` and `agent_id: 0`.

```bash
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_type":"call.graded"}'
```

`event_type` accepts any value from [Valid event types](#valid-event-types).
Omitting it preserves the generic `webhook.test` behavior.

---

## Delete an endpoint

<CodeGroup>
```bash cURL
curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Returns `204 No Content`. Delivery to the URL stops immediately;
in-flight retries are abandoned.

---

## Debug deliveries

Before concluding that a webhook was not sent, inspect
[`GET /v1/developer/webhook-deliveries`](/api-reference/webhook-deliveries).
It shows recent attempts from both webhook systems, including the call id,
URL origin, HTTP status, attempt count, allowlisted failure category, and next
retry time. It never returns the event payload, transcript, stored error text,
response body, or URL path.

You can also see the same recent history in **Agents → select an agent → Webhooks →
Recent deliveries**. Rows show the endpoint label and the URL origin used by the latest
attempt. This is operational state rather than an immutable audit log: deleting an endpoint
also deletes its delivery rows.

For an n8n `404`, first confirm the workflow is active, accepts `POST`, and uses
the production webhook URL rather than the test URL. A `401` or `403` points to
authentication or signature validation; timeouts point to destination latency
or availability; TLS errors point to the certificate chain, hostname, or expiry.

---

## Related

<CardGroup cols={2}>
  <Card title="Events catalog" icon="list" href="/webhooks/events">
    The full list of `events` values you can subscribe to.
  </Card>
  <Card title="Webhooks overview" icon="bolt" href="/webhooks/overview">
    Signature verification and delivery semantics.
  </Card>
</CardGroup>

<!-- en: webhooks/events -->
---
title: "Events Catalog"
description: "All webhook event types ThunderPhone emits."
---

Every webhook body has a `type` field whose value is one of the event
types on this page. When you subscribe to an
[endpoint](/webhooks/endpoints), the `events` array must contain the
event types you want (or be empty to subscribe to everything —
except the per-turn events [`telephony.turn`](#telephony-turn) /
[`web.turn`](#web-turn), which are delivered only to endpoints that
name them explicitly).

Two delivery styles carry these events:

* **Endpoint deliveries** are always **non-blocking** notifications
  with [retries](/webhooks/overview#delivery-semantics): respond with
  any 2xx; the envelope carries an `event_id` to dedup on.
* **Blocking** exchanges run only on the
  [legacy single-URL webhook](/webhooks/overview): the
  [`telephony.incoming` / `web.incoming`](/webhooks/call-incoming)
  configuration request (webhook-mode numbers: 13 s including one
  retry; webhook-mode widget keys: 10 s) and webhook-mode
  [tool dispatch](/tools/overview#webhook-mode-dispatch). Your response
  shapes the live call.

Example payloads below show the endpoint envelope in its wire order
(keys sorted alphabetically: `data`, `event_id`, `type`); legacy
deliveries carry the same `data` without `event_id`.

## Call events

### `telephony.incoming`

Sent when an inbound call reaches one of your
[phone numbers](/api-reference/phone-numbers). Endpoint deliveries are
fire-and-forget notifications sent for **every** inbound call, whether
the number is agent-configured or webhook-configured. Numbers without
an assigned agent additionally receive the **blocking** configuration
request on the legacy webhook — see
[`telephony.incoming` / `web.incoming`](/webhooks/call-incoming) for
the full request / response schema.

```json
{
  "data": {
    "call_id": 987654321,
    "from_number": "+14155550199",
    "to_number": "+15551234567"
  },
  "event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11",
  "type": "telephony.incoming"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `agent_id` | integer \| null | Agent that handled the call, when one was assigned |
| `agent_name` | string \| null | Agent that handled the call, when one was assigned |
| `returning_call` | object | Present only when the number called this caller in the last 30 days: the earlier call's `call_id`, `agent_id`, `started_at` and `outcome`. See [Callbacks](/webhooks/call-incoming#callbacks) |
| `sip_headers` | object | Present only when the call arrived with `X-*` or `User-to-User` SIP headers (SIP addresses and manual SIP connections): header name in lower case → value. See [SIP headers](/guides/sip-addresses#pass-call-context-in-sip-headers) |

### `telephony.complete`

Sent when an inbound or outbound telephony call ends. Non-blocking.
Includes the transcript, recording URL when available, and billing summary. See
[`telephony.complete` / `web.complete`](/webhooks/call-complete) for
the payload schema.

| Field | Type | Description |
|-------|------|-------------|
| `agent_id` | integer \| null | Agent that handled the call, when one was assigned |
| `agent_name` | string \| null | Agent that handled the call, when one was assigned |

### `telephony.tool`

Sent after a telephony call invokes a
[function tool](/tools/overview). Non-blocking audit notification —
the tool has already executed when this event is delivered; it covers
your own function tools and the built-in `send_sms` tool (not other built-in,
knowledge-base, app-connection, or MCP tools). For `send_sms`,
both `arguments.to` and `arguments.body` are `[REDACTED]`. Completion
transcripts also redact them; retrieve the content and recipient from the
organization-scoped SMS resource using the response's `message_id`.

```json
{
  "data": {
    "arguments": { "date": "2026-04-21" },
    "call_id": 987654321,
    "from_number": "+14155550199",
    "response": {
      "response": { "available_slots": ["9:00 AM", "2:00 PM"] },
      "status": 200
    },
    "to_number": "+15551234567",
    "tool_name": "search_appointments"
  },
  "event_id": "1f0a7c3e-52d4-4a0e-8f4b-b1a6a1c0d9e2",
  "type": "telephony.tool"
}
```

`response` is the executed result: `{"status": <http status>,
"response": <your endpoint's JSON>}` on success, or
`{"status": <status>, "error": "<message>"}` on failure.

| Field | Type | Description |
|-------|------|-------------|
| `agent_id` | integer \| null | Agent that handled the call, when one was assigned |
| `agent_name` | string \| null | Agent that handled the call, when one was assigned |

### `telephony.turn`

Sent while a telephony call is **in progress**, once for each
speech-bearing turn as it happens — the agent's spoken completions and
the caller's transcribed turns. Lets you follow the live conversation
over plain webhooks instead of polling
[`GET /v1/calls/{call_id}/transcript`](/api-reference/calls#get-transcript).
Non-blocking.

<Note>
  **Explicit subscription required.** Unlike every other event type,
  turn events are never delivered through an empty `events` array
  (subscribe-to-all). An endpoint receives them only when its `events`
  list contains `telephony.turn` / `web.turn` explicitly.
</Note>

```json
{
  "data": {
    "call_id": 987654321,
    "entry_type": "completion",
    "from_number": "+14155550199",
    "position": 7,
    "role": "assistant",
    "start_ms": 15200,
    "text": "How many employees does your company have?",
    "to_number": "+15551234567"
  },
  "event_id": "8d3f5a2c-7b1e-4c9a-b6d0-2e4f6a8c0d1e",
  "type": "telephony.turn"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `agent_id` | integer \| null | Agent that handled the call, when one was assigned |
| `agent_name` | string \| null | Agent that handled the call, when one was assigned |
| `position` | integer | The turn's index in the call history — a stable identity for ordering |
| `role` | string | `assistant` (agent speech) or `user` (caller speech) |
| `text` | string | The turn's transcript text as known at emission time |
| `entry_type` | string | The underlying history entry type: `completion` (agent), or `user_turn` / `span` (caller) |
| `start_ms`, `end_ms` | integer | Audio offsets in ms since call start; present only when playout timing was already known at emission time |

<Note>
  Delivery is at-least-once and turns may arrive **out of order**:
  dedup on the envelope's `event_id` and order by `position`. Caller
  transcripts may still refine after emission; the post-call
  [`telephony.complete`](/webhooks/call-complete) transcript is
  authoritative. Only spoken turns emit — tool calls, whispers, and
  other internal entries never appear on this stream.
</Note>

### `web.incoming`

The web-channel equivalent of `telephony.incoming`, sent when a
[web widget](/widget/overview) session or a builder mic test call
starts. Endpoint deliveries are fire-and-forget for every web session.
Publishable keys in `mode="webhook"` additionally receive the
**blocking** configuration request on the legacy webhook — that
blocking request has a different shape (`origin_domain`,
`publishable_key_prefix`; no phone numbers). See
[`telephony.incoming` / `web.incoming`](/webhooks/call-incoming).

```json
{
  "data": {
    "call_id": 987654322,
    "from_number": "web",
    "origin_domain": "https://example.com",
    "publishable_key_prefix": "pk_live_a1b2",
    "to_number": "+15551234567"
  },
  "event_id": "9a2b4c6d-8e0f-4a1b-9c2d-3e4f5a6b7c8d",
  "type": "web.incoming"
}
```

`from_number` is always the literal `"web"`. For webhook-mode widget
sessions `to_number` is empty (the session's agent number is assigned
after configuration); for builder mic test calls `origin_domain` and
`publishable_key_prefix` are empty.

| Field | Type | Description |
|-------|------|-------------|
| `agent_id` | integer \| null | Agent that handled the call, when one was assigned |
| `agent_name` | string \| null | Agent that handled the call, when one was assigned |

### `web.complete`

The web-channel equivalent of `telephony.complete`, covering web
widget calls (`direction: "web"`) and builder mic test calls
(`direction: "test"`). Non-blocking. Same payload shape as
[`telephony.complete`](/webhooks/call-complete), plus `origin_domain`,
with `from_number` set to `"web"`.

| Field | Type | Description |
|-------|------|-------------|
| `agent_id` | integer \| null | Agent that handled the call, when one was assigned |
| `agent_name` | string \| null | Agent that handled the call, when one was assigned |

<Note>
  On the legacy single-URL webhook, builder mic test calls
  historically report as `telephony.complete` — only `direction:
  "web"` calls use the `web.complete` type there. The endpoint system
  maps both web and test calls to `web.*`. Historical payloads may
  contain the legacy `direction` values `widget` or `mic`.
</Note>

### `web.tool`

The web-channel equivalent of `telephony.tool`. The `data` carries
`origin_domain` instead of `from_number` / `to_number`.

| Field | Type | Description |
|-------|------|-------------|
| `agent_id` | integer \| null | Agent that handled the call, when one was assigned |
| `agent_name` | string \| null | Agent that handled the call, when one was assigned |

### `web.turn`

The web-channel equivalent of [`telephony.turn`](#telephony-turn),
covering web widget calls and builder mic test calls. Same payload
shape, with `origin_domain` instead of `from_number` / `to_number`.
Like `telephony.turn`, it requires an **explicit subscription** — it
is never delivered through an empty `events` array.

| Field | Type | Description |
|-------|------|-------------|
| `agent_id` | integer \| null | Agent that handled the call, when one was assigned |
| `agent_name` | string \| null | Agent that handled the call, when one was assigned |

### `call.transfer_completed`

Sent once per call with the final outcome of a
[call transfer](/guides/call-transfers): a cold transfer, or the human
bridge a warm transfer leaves behind after the agent drops out.
Non-blocking, and delivered to endpoints only (never to the legacy
single-URL webhook). It arrives after the call's `telephony.complete`:
once the carrier takes the call or the transfer fails, or, when
ThunderPhone bridged the call, once the bridge ends.

```json
{
  "data": {
    "agent_id": 12,
    "agent_name": "Front desk",
    "bridge_kind": "cold_fallback",
    "bridge_seconds": 255,
    "bridge_total_cents": 5,
    "call_id": 987654321,
    "destination": "+15555550102",
    "sip_status": 403,
    "transfer_outcome": "bridged"
  },
  "event_id": "5b0f6c1e-9d2a-5e7b-8c4d-1a2b3c4d5e6f",
  "type": "call.transfer_completed"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `call_id` | integer | The call that was transferred |
| `agent_id` | integer \| null | Agent that handled the call, when one was assigned |
| `agent_name` | string \| null | Agent that handled the call, when one was assigned |
| `transfer_outcome` | string | `refer_accepted`: the carrier took the call over. `bridged`: ThunderPhone kept the caller and the destination connected itself, either because the carrier refused a cold transfer or because a warm transfer's agent dropped out. `bridge_unanswered`: the carrier refused a cold transfer and the destination did not answer ThunderPhone's own call. `failed`: the transfer did not go through and the call ended |
| `destination` | string \| null | The number the call was transferred to |
| `sip_status` | integer \| null | The carrier's SIP status when it refused the cold transfer: `403` (for example a Twilio trunk without call transfer), `405` or `501`. `null` when the carrier did not refuse it |
| `bridge_kind` | string \| null | `bridged` only: `cold_fallback` (a refused cold transfer ThunderPhone connected) or `warm` (a warm transfer's two people after the agent left) |
| `bridge_seconds` | integer \| null | `bridged` only: the bridged time ThunderPhone billed, in seconds |
| `bridge_total_cents` | integer \| null | `bridged` only: what the bridge cost in USD cents after any free call credit, billed separately from the call's `billing_total_cents` |

The same values are on the [call object](/api-reference/calls#call-object)
as `transfer_outcome`, `transfer_destination`, `transfer_sip_status`,
`transfer_bridge_kind`, `transfer_bridge_seconds` and
`transfer_bridge_total_cents`. `event_id` is the same on every delivery
for a call, so a repeated report never produces a second event.

### `call.billed`

Sent for a call billed on metered usage: when its charge settles, a few
minutes after the call ends once its usage is in, and again whenever
usage that arrived later raises the charge. The call's
[`telephony.complete` / `web.complete`](/webhooks/call-complete) event
carries `billing_pending: true` and `null` billing fields. Non-blocking,
and delivered to endpoints only (never to the legacy single-URL webhook).
Calls billed when they end carry their billing in the completion event
and get no `call.billed`.

Order is not guaranteed: the charge normally waits for the completion
event, but `call.billed` can arrive before it (a completion event held
up for an hour, or deliveries retried at different times), and two
`call.billed` events can arrive out of order. Keep the event with the
highest `billing_seq` for each `call_id`.

```json
{
  "data": {
    "adjustment_cents": null,
    "agent_id": 12,
    "agent_name": "Front desk",
    "billable_minutes": 3.0,
    "billing_seq": 1,
    "billing_total_cents": 10,
    "call_id": 987654321,
    "reason": "settled"
  },
  "event_id": "7c1d2e3f-4a5b-5c6d-8e7f-9a0b1c2d3e4f",
  "type": "call.billed"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `call_id` | integer | The call that was billed |
| `agent_id` | integer \| null | Agent that handled the call, when one was assigned |
| `agent_name` | string \| null | Agent that handled the call, when one was assigned |
| `reason` | string | `settled`: the call's charge. `adjusted`: usage that arrived after the charge raised it (a charge is never lowered) |
| `billing_seq` | integer | `1` for the charge, then `2`, `3`, ... for each increase. The highest one received is the call's current billing |
| `billable_minutes` | number | Minutes billed, rounded to the nearest quarter minute |
| `billing_total_cents` | integer | Everything the call has been charged so far in USD cents, after any free call credit, `adjusted` increases included |
| `adjustment_cents` | integer \| null | `adjusted` only: this increase in USD cents, after any free call credit |

The same totals are on the [call object](/api-reference/calls#call-object)
as `billable_minutes` and `billing_total_cents`. `event_id` is the same on
every delivery of one `billing_seq`, so a repeated report never produces
a second event.

---

## SMS events

SMS events describe messages sent through the organization's connected
Twilio or Telnyx account. The message body is omitted and `to` is redacted.
Retrieve the organization-scoped message from
[`GET /v1/sms/{message_id}`](/api-reference/sms#retrieve-a-message) when its
content or recipient is needed. `source` is `api`, `agent_tool`, `followup`
or `pre_call` (a campaign's text before calling), as on the
[message object](/api-reference/sms#list-messages).

Every SMS event carries `scheduled_send_id`: the id of the
[scheduled send](/api-reference/scheduled-sends) the text went out for, or
`null` for a text that was not scheduled. Scheduled texts have `source`
`"scheduled"`.

### `sms.sent`

Sent when the customer's carrier accepts an outbound SMS request. This is not
a handset delivery receipt.

```json
{
  "data": {
    "accepted_at": "2026-09-19T15:42:10.113Z",
    "agent_id": 12,
    "call_id": 987654321,
    "created_at": "2026-09-19T15:42:09.901Z",
    "direction": "outbound",
    "error_code": null,
    "error_message": null,
    "from_number": "+15551234567",
    "id": "313a3117-827b-46e9-a01a-ac1493838724",
    "provider": "twilio",
    "provider_id": "SM0123456789abcdef0123456789abcdef",
    "scheduled_send_id": null,
    "segment_count": 1,
    "source": "agent_tool",
    "status": "accepted",
    "to": "[REDACTED]"
  },
  "event_id": "0ae347b4-1716-45bb-9a0e-b52373586e37",
  "type": "sms.sent"
}
```

### `sms.failed`

Sent after a permanent carrier rejection, after transient retries are
exhausted, when the outcome is terminally unknown, or when Twilio reports an
accepted message undelivered or failed. In that last case the message's
`sms.sent` was already sent, and `status` stays `"accepted"`. `error_code` is a stable
ThunderPhone code and `error_message` states the customer action when one is
available. `status: "unknown"` means the carrier may have accepted the SMS;
reconcile it in the carrier log because ThunderPhone will not resend it
automatically.

### `sms.received`

Reserved for inbound SMS support. No `sms.received` events are emitted in the
current release. Inbound carrier webhook configuration and signature
verification will ship separately.

---

## Scheduled events

[Scheduled sends](/api-reference/scheduled-sends) that do not go out fire one
of these events. A send that goes out fires the usual events instead: the
`sms.*` events with `scheduled_send_id` set for a text, the call events for a
call, with `scheduled_send_id` on its `telephony.complete`. Both are non-blocking. When the send has an agent, agent-scoped
endpoints for that agent receive them too.

The payload carries ids, status and times only: never the text's body or the
call's variables or context, and `to` is redacted. Fetch
[`GET /v1/scheduled/{id}`](/api-reference/scheduled-sends#retrieve-a-scheduled-send)
for the rest.

### `scheduled.skipped`

Sent when a send is not sent on purpose. `reason` is `expired` (it could not go
out before `expires_at`), `opted_out` (the number is on the
[opt-out list](/api-reference/opt-outs), including one added after the send
was created), `quiet_hours` (it came due outside 8am to 9pm in the
recipient's time zone), `sender_not_ready` (the text's number can no longer
send) or `outbound_tcpa_unconfirmed` (a call came due before the
organization's TCPA confirmation was recorded).

```json
{
  "data": {
    "agent_id": null,
    "created_at": "2026-11-01T18:02:11.204Z",
    "detail": "The send could not go out before its expires_at, so it was not sent late.",
    "expires_at": "2026-11-03T17:30:00Z",
    "external_id": "appointment-4815",
    "from_number": "+15551234567",
    "id": "6f1c0b8e-3a52-4c1f-9a0b-2f4f7d8a91c3",
    "reason": "expired",
    "send_at": "2026-11-03T17:00:00Z",
    "source": "api",
    "status": "skipped",
    "to": "[REDACTED]",
    "type": "sms"
  },
  "event_id": "2b0f6c43-74c9-4d43-a1f4-0d6a2f8e51a7",
  "type": "scheduled.skipped"
}
```

### `scheduled.failed`

Sent when ThunderPhone tried to send and it did not go out. `reason` is the
send's own error: an [SMS error code](/api-reference/sms#send-a-message) such
as `carrier_rejected` for a text, or the call's refusal or failure reason,
such as the blocked-destination rule (`premium_rate`, for example) or
`agent_deleted`. The payload has the same
fields as `scheduled.skipped`.

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | The scheduled send's id |
| `type` | string | `sms` or `call` |
| `status` | string | `skipped` or `failed` |
| `reason` | string | Why, as above; the same value as the send's `status_reason` |
| `detail` | string | Readable explanation |
| `source` | string | What created the send: `api` |
| `external_id` | string \| null | Your key for the send, or `null` |
| `from_number` | string | Sending number |
| `to` | string | Always `"[REDACTED]"` |
| `agent_id` | integer \| null | Calls: the agent; texts: `null` |
| `send_at`, `expires_at`, `created_at` | timestamp | ISO 8601 |

---

## Voice events

Custom voice creation is asynchronous. These non-blocking events let you
react to a terminal result instead of polling the
[clone detail endpoint](/api-reference/custom-voices#list-and-retrieve-clones).

`voice.ready` and `voice.failed` are delivered only to an organization-wide
endpoint with `events: []`. They cannot be selected as explicit event filters.

### `voice.ready`

Sent when a custom voice finishes processing and can be assigned to an
agent.

```json
{
  "data": {
    "voice": {
      "created_at": "2026-07-30T14:12:08.317Z",
      "display_name": "Support voice",
      "failure_reason": "",
      "gender": "female",
      "id": "cv_2f6f90b0e9a34ee8b39be7d1",
      "language": "en",
      "name": "custom:cv_2f6f90b0e9a34ee8b39be7d1",
      "status": "ready",
      "updated_at": "2026-07-30T14:13:31.605Z"
    }
  },
  "event_id": "2d5f0a61-e9b5-4a3c-b684-29d7d9e4b214",
  "type": "voice.ready"
}
```

### `voice.failed`

Sent when custom voice processing reaches a permanent failure.

```json
{
  "data": {
    "reason": "audio sample could not be processed",
    "voice": {
      "created_at": "2026-07-30T14:12:08.317Z",
      "display_name": "Support voice",
      "failure_reason": "audio sample could not be processed",
      "gender": "female",
      "id": "cv_2f6f90b0e9a34ee8b39be7d1",
      "language": "en",
      "name": "custom:cv_2f6f90b0e9a34ee8b39be7d1",
      "status": "failed",
      "updated_at": "2026-07-30T14:13:31.605Z"
    }
  },
  "event_id": "3493e985-1a75-4f77-a10a-e74af440cd31",
  "type": "voice.failed"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `voice.id` | string | Custom voice public id |
| `voice.name` | string | Agent voice value in the form `custom:<public_id>` |
| `voice.display_name` | string | Organization-facing voice name |
| `voice.language` | string | The clone's single language code |
| `voice.gender` | string | `male`, `female`, or an empty string |
| `voice.status` | string | `ready` for `voice.ready`; `failed` for `voice.failed` |
| `voice.failure_reason` | string | Empty on success; processing failure detail on failure |
| `voice.created_at`, `voice.updated_at` | timestamp | ISO 8601 timestamps |
| `reason` | string | Failure detail; present only on `voice.failed` |

---

## Quality events

### `call.graded`

Sent whenever an [AI grading run](/api-reference/calls#ai-call-grading)
completes for a call. Non-blocking.

```json
{
  "data": {
    "call_id": 987654321,
    "grade": {
      "call_outcome": "success",
      "created_at": "2026-04-20T18:25:11.002Z",
      "detected_issues": [],
      "graded_at": "2026-04-20T18:25:11.002Z",
      "grader_model": "heuristic-v1",
      "id": 5512,
      "score": 92,
      "status": "completed",
      "summary": "Caller asked about their policy and got a full answer…"
    },
    "report": null
  },
  "event_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "type": "call.graded"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `agent_id` | integer \| null | Agent that handled the call, when one was assigned |
| `agent_name` | string \| null | Agent that handled the call, when one was assigned |
| `grade.id` | integer | Grade id |
| `grade.score` | integer \| null | 0–100 |
| `grade.call_outcome` | string | `success`, `failure`, `unknown`, or `no_conversation` |
| `grade.summary` | string | One-paragraph summary |
| `grade.detected_issues` | array | Issue strings found by the grader |
| `grade.status` | string | Always `completed` — only finished runs emit |
| `grade.grader_model` | string | Which grader produced the result (e.g. `heuristic-v1`) |
| `grade.graded_at`, `grade.created_at` | timestamp | |
| `report` | object \| null | The customer-facing [call report](/api-reference/calls#call-report): outcome label, needs-attention flag and reason, caller, one-line summary, caller experience. On an early heuristic grade it is `null` or a `pending` report whose fields are placeholders; the full grade's event carries the completed one |

<Note>
  A call can be graded more than once — a fast heuristic grade is
  often followed by a full model grade once the recording is
  available, and manual regrades are possible. Each completed run
  emits its own `call.graded` event; treat the latest `graded_at` as
  authoritative.
</Note>

### `call.data_extracted`

Sent whenever structured data extraction completes successfully, including a
late retry after `telephony.complete` / `web.complete` or a manual re-run via
[`POST /v1/calls/{call_id}/extract`](/api-reference/calls#run-data-extraction).
Non-blocking.

In a blocking extraction mode, the completion event normally waits no more
than the 75-second extraction budget. If the extraction worker process is
lost, the production finalization drain (every five minutes) releases a
completion whose `blocking_deadline_at` has passed before it starts another
extraction attempt. A later success is delivered separately as this event.

<Warning>
  Extracted values are a model's interpretation of the conversation. Each
  non-null value includes the quote, speaker role, and turn index it was based
  on, plus a run-level verification flag. Verify the result before decisions
  involving money, identity, or access.
</Warning>

```json
{
  "data": {
    "call_id": 987654321,
    "agent_id": 12,
    "agent_name": "Acme intake",
    "extracted_data": {
      "status": "completed",
      "fields": {
        "customer_name": "Alex Morgan",
        "appointment_date": "2026-04-23"
      },
      "evidence": {
        "customer_name": {
          "quote": "My name is Alex Morgan",
          "speaker_role": "caller",
          "turn_index": 4
        },
        "appointment_date": {
          "quote": "April 23 works for me",
          "speaker_role": "caller",
          "turn_index": 7
        }
      },
      "verification": "verified",
      "field_reasons": {},
      "schema_version": "92850758e231a3c95a..."
    },
    "extracted_at": "2026-04-20T18:25:11.002Z",
    "model": "<model id>",
    "summary": "Alex Morgan called to book a follow-up visit and confirmed Thursday, April 23."
  },
  "event_id": "4d79ef1d-c2b1-4ed6-85b8-8326bd2895ef",
  "type": "call.data_extracted"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `agent_id` | integer \| null | Agent that handled the call, when one was assigned |
| `agent_name` | string \| null | Agent that handled the call, when one was assigned |
| `summary` | string \| null | The completed [call summary](/webhooks/call-complete) when the agent has **Generate a call summary** on, so a late extraction event also delivers a summary that missed the completion window; `null` otherwise. Agents with a summary but no extraction fields never emit this event: read a late summary from `GET /v1/calls/{call_id}` |
| `extracted_data.status` | string | Always `completed` for this event |
| `extracted_data.fields` | object | Values keyed by the configured extraction field keys; unavailable values are `null` |
| `extracted_data.evidence` | object | Evidence keyed by extraction field. A non-null value has the exact structurally checked quote (at most 1,000 characters), `speaker_role` (`caller` or `agent`), and `turn_index`; longer model-returned quotes are rejected instead of truncated, and evidence is `null` whenever its field is `null` |
| `extracted_data.verification` | string | `verified` only when the independent evidence pass returned exactly one valid verdict for every candidate field. `unavailable` means the pass failed, timed out, lacked enough budget, or returned malformed or partial output. A wholly unavailable pass preserves structurally grounded values for customer review. For partial output, valid verdicts are applied and each candidate without exactly one valid verdict is nulled |
| `extracted_data.field_reasons` | object | Reasons keyed by fields that were nulled by structural grounding or the independent verifier |
| `extracted_data.schema_version` | string | Hash of the exact field schema used for this extraction |
| `extracted_at` | timestamp | ISO 8601 completion time |
| `model` | string | Model used for the extraction |

### `campaign.completed`

Sent once when a campaign moves from `running` to `completed`, whether its
schedule ended or all contacts reached terminal states. Runner retries do not
emit another event. This organization-level lifecycle event is delivered only
to organization-scoped endpoints, not agent-scoped endpoints. Non-blocking.

```json
{
  "data": {
    "campaign_id": "3f6b2c9e-2a0d-4c63-b6d6-a708dc98f403",
    "name": "May win-back",
    "agent_id": 12,
    "status": "completed",
    "started_at": "2026-04-20T17:00:00Z",
    "completed_at": "2026-04-20T18:25:11Z",
    "counts": {
      "contacts_total": 150,
      "completed": 121,
      "failed": 11,
      "no_answer": 18,
      "remaining": 0
    }
  },
  "event_id": "8d8f52ce-6b46-423f-9dde-cea0b91ec135",
  "type": "campaign.completed"
}
```

The four outcome counts are disjoint and add up to `contacts_total`:
`completed` contains successful contacts; `no_answer` contains terminal
failed/exhausted contacts whose final outcome was no answer; `failed` contains
all other terminal failed/exhausted contacts; and `remaining` contains pending,
scheduled, or currently calling contacts. A contact waiting for a retry is
`remaining`, even when its most recent attempt was no answer. In-flight calls
are reconciled before the once-only completion snapshot. `started_at` is the
configured campaign start, or the campaign creation time when no start was
configured.

### `issue.reported`

Sent when an [issue report](/api-reference/issue-reports) is created —
either filed by a user from the dashboard (`source: "user"`) or
automatically by call grading (`source: "system"`). Non-blocking.

```json
{
  "data": {
    "call_id": 987654321,
    "issue_report": {
      "created_at": "2026-04-20T18:25:11.002Z",
      "description": "Five-second silence before responding to the main question.",
      "id": 4321,
      "severity": "warning",
      "source": "system",
      "status": "open",
      "title": "Agent paused too long"
    }
  },
  "event_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
  "type": "issue.reported"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `agent_id` | integer \| null | Agent that handled the call, when one was assigned |
| `agent_name` | string \| null | Agent that handled the call, when one was assigned |
| `issue_report.severity` | string | `critical`, `warning`, or `info` |
| `issue_report.status` | string | `open` or `resolved` |
| `issue_report.source` | string | `user` (filed from the dashboard) or `system` (created by grading) |

<Note>
  Regrading a call rebuilds its system-generated issue reports, which
  re-emits `issue.reported` for the recreated reports. Dedup on
  `call_id` + `title` if you only want one notification per underlying
  problem.
</Note>

### `issue.escalated`

Sent when an issue pattern is sent to ThunderPhone for staff review: after
**Report to ThunderPhone**, or when Fix with AI cannot confirm a customer-side
fix and routes the issue automatically. Only organization-wide endpoints
receive this event.

```json
{
  "data": {
    "automatic": false,
    "cluster_id": "7ac2844c-2df0-4fa8-a560-7378da649e19",
    "escalation_id": "ec99f52b-c8c0-41dd-a4f2-dd8a07b10894",
    "status": "open"
  },
  "event_id": "d8f8f420-7a42-45ba-bcf1-b747f9bbecda",
  "type": "issue.escalated"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `automatic` | boolean | `true` for an automatic escalation; `false` for a manual escalation |
| `cluster_id` | UUID | Escalated issue pattern |
| `escalation_id` | UUID | Escalation record |
| `status` | string | `open` when the event is emitted |

This is a notification, not the evidence bundle. Use `cluster_id` to correlate
it with the issue pattern. See [Report to ThunderPhone](/guides/issues#report-to-thunderphone).

---

## Test call events

### `test-call.completed`

Sent when a
[test-call run](/api-reference/test-calls#test-call-run-object)
reaches a terminal status — `completed` or `failed`, including runs
that failed at launch and never produced a call. Non-blocking. Useful
for wiring batch CI runs into your chat/notifications systems.

```json
{
  "data": {
    "test_call_run": {
      "call_id": 987654321,
      "completed_at": "2026-04-20T18:25:04.822Z",
      "error_message": "",
      "id": 7110,
      "status": "completed",
      "target_id": 12,
      "target_type": "agent"
    }
  },
  "event_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
  "type": "test-call.completed"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `agent_id` | integer \| null | Agent that handled the call, when one was assigned |
| `agent_name` | string \| null | Agent that handled the call, when one was assigned |
| `test_call_run.target_type` | string | `agent` or `phone_number` |
| `test_call_run.target_id` | integer | The agent id or phone-number id the run targeted, matching `target_type` |
| `test_call_run.status` | string | `completed` or `failed` |
| `test_call_run.call_id` | integer \| null | `null` when the run failed before a call was placed |
| `test_call_run.error_message` | string | Empty on success |

---

## Alert events

### `alert.triggered`

Sent when an [alert rule](/guides/alerts) with the **Deliver to
developer webhooks** channel enabled crosses its threshold.
Non-blocking. A rule fires once and then respects its cooldown, so a
sustained breach produces one event per cooldown window.

```json
{
  "data": {
    "comparator": "lt",
    "event_id": "b8e6a1d4-2c3f-4a5b-9c8d-7e6f5a4b3c2d",
    "fired_at": "2026-04-20T18:00:00+00:00",
    "metric": "success_rate",
    "metric_value": 71.4,
    "rule_id": "d2c3b4a5-6f7e-4d8c-9b0a-1c2d3e4f5a6b",
    "rule_name": "Success rate below 80%",
    "threshold": 80.0,
    "window_hours": 24
  },
  "event_id": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a",
  "type": "alert.triggered"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `event_id` (in `data`) | UUID | The alert **firing** id — distinct from the envelope's delivery `event_id` |
| `rule_id`, `rule_name` | UUID, string | The rule that fired |
| `metric` | string | `success_rate`, `failure_rate`, `avg_score`, `call_volume`, or `suite_regression` |
| `comparator` | string | `lt`, `lte`, `gt`, or `gte` |
| `metric_value` | number | The metric's value over the window when the rule fired |
| `threshold` | number | The configured threshold |
| `window_hours` | integer | Trailing evaluation window |
| `fired_at` | timestamp | |

See the [Alerts guide](/guides/alerts) for creating rules, metrics,
cooldowns, and the email / Slack channels.

---

## Phone number events

### `phone_number.spam_risk_changed`

Sent when spam-label monitoring (a paid add-on, on request through support)
sees a monitored number's spam risk rise to `medium` or `high` (from `low`, from
no reading yet, or from `medium` to `high`). Non-blocking. A number that stays
flagged is not sent again; one that recovers to `low` and is flagged later is.
The event has no agent context, so only organization-wide endpoints receive it.
The organization's owners and admins also get an email.

```json
{
  "data": {
    "checked_at": "2026-10-21T14:41:07+00:00",
    "phone_number": "+13125550100",
    "phone_number_id": 412,
    "previous_spam_risk": "low",
    "scores": {
      "connection": 31,
      "engagement": 40,
      "maturity": 82,
      "sentiment": 22
    },
    "spam_category": "Telemarketer",
    "spam_risk": "high"
  },
  "event_id": "6f1c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f",
  "type": "phone_number.spam_risk_changed"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `phone_number` | string | The number, in E.164 |
| `phone_number_id` | integer \| null | Its id in [Phone Numbers](/api-reference/phone-numbers) |
| `spam_risk` | string | `medium` or `high` |
| `previous_spam_risk` | string \| null | The risk at the last reading, `null` before the first one |
| `spam_category` | string \| null | The label carriers may show, such as `Telemarketer` or `Survey`. Treat it as free text |
| `scores` | object | 0 to 100 each, or `null` until there is enough call volume: `maturity` (how established the number is), `connection` (do people answer), `engagement` (do they stay on), `sentiment` (do they block or report it) |
| `checked_at` | timestamp | When ThunderPhone read the result |

---

## Migration events

### `migration.call.complete`

Sent when a call placed through
[`POST /v1/migrations/{id}/calls`](/api-reference/migration-calls) ends,
whichever platform took it. Non-blocking. It arrives up to about 5 minutes
after the call ends. `data` has every field of
[`telephony.complete`](/webhooks/call-complete) plus a `migration` block. A
call ThunderPhone placed also sends `telephony.complete` as usual, with the
same `call_id`. `answered_by` is `null` for a call the other platform took. A call on the other platform that has not ended after 2
hours, or whose migration finished or lost its key first, is sent with
`status: "unknown"` and no transcript.

```json
{
  "data": {
    "agent_id": 42,
    "agent_name": "Front desk",
    "answered_by": null,
    "billable_minutes": null,
    "billing_total_cents": null,
    "call_id": null,
    "direction": "outbound",
    "duration_seconds": 94,
    "end_reason": "user_hangup",
    "end_time": "2026-10-06T17:01:34+00:00",
    "extracted_data": null,
    "from_number": "+15551234567",
    "migration": {
      "arm": "vendor",
      "id": "5f0c2a9e-7b1d-4c3e-8a6f-2d9e1b4c7a30",
      "metadata": {
        "lead_id": "8812"
      },
      "routing_id": "9b2f8c1e-4d3a-4f6b-8e2d-1a7c5b9e0f34",
      "vendor": "retell",
      "vendor_call_id": "call_6a1f0e",
      "vendor_cost_usd": "0.1240"
    },
    "product": "",
    "recording_mode": "vendor",
    "recording_url": "https://…",
    "start_time": "2026-10-06T17:00:00+00:00",
    "status": "completed",
    "summary": "The callee booked a table for two on Thursday.",
    "thunderphone_retained_call_content": true,
    "to_number": "+14155552671",
    "transcripts": [
      {
        "content": "Hi Ada, this is Rosa's calling about your booking.",
        "role": "agent"
      },
      {
        "content": "Yes, Thursday works.",
        "role": "user"
      }
    ],
    "transfer_number": null,
    "unresolved_variables": [],
    "variables": {
      "first_name": "Ada"
    },
    "voice": ""
  },
  "event_id": "7c1e2f3a-4b5c-4d6e-8f7a-9b0c1d2e3f4a",
  "type": "migration.call.complete"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `migration.id` | UUID | The migration |
| `migration.routing_id` | UUID | The routed call, as returned when you placed it |
| `migration.arm` | string | `ours` (ThunderPhone placed it) or `vendor` (the other platform did) |
| `migration.vendor` | string | `retell`, `vapi`, `elevenlabs`, or `bland` |
| `migration.vendor_call_id` | string \| null | The other platform's call id; `null` for `ours` |
| `migration.metadata` | object | The `metadata` you sent when placing the call |
| `migration.vendor_cost_usd` | string \| null | What the other platform reported the call cost, when it did |
| `call_id` | integer \| null | The ThunderPhone call id; `null` for `vendor` |
| `status` | string | For `vendor`: `completed` when the callee spoke, `failed` when they did not, `unknown` as above. For `ours`: as in `telephony.complete` |

For a `vendor` call, ThunderPhone has no billing or extraction data:
`billable_minutes`, `billing_total_cents` and `extracted_data` are `null`,
`product` and `voice` are empty, `recording_mode` is `vendor`, and
`recording_url` is the other platform's link, when it gave one.

### `migration.rollback`

Sent when a migration's gradual switch moves every call back to the other
platform on its own: 3 calls failed to connect to ThunderPhone within 15
minutes, 2 calls sent to ThunderPhone ended before the agent answered, or
ThunderPhone's task outcome rate fell more than the configured gap below the
other platform's. Non-blocking, once per rollback. After it, ThunderPhone's
share is 0% and the migration is paused until someone resumes it on the
agent's Migration tab. The payload carries no phone numbers, transcripts or
call ids.

```json
{
  "data": {
    "agent_id": 42,
    "agent_name": "Front desk",
    "dropped": 0,
    "migration_id": "5f0c2a9e-7b1d-4c3e-8a6f-2d9e1b4c7a30",
    "ours": {
      "graded": 20,
      "success_rate": 0.8
    },
    "ours_failed": 3,
    "ours_percent": 0,
    "previous_percent": 25,
    "reason": "ours_failed_burst",
    "rolled_back_at": "2026-10-10T12:05:00+00:00",
    "step": 1,
    "theirs": {
      "graded": 20,
      "success_rate": 0.8
    },
    "vendor": "retell"
  },
  "event_id": "3d1f6b2a-8c4e-5a7b-9d0e-2f1a3b4c5d6e",
  "type": "migration.rollback"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `migration_id` | UUID | The migration |
| `vendor` | string | `retell`, `vapi`, `elevenlabs`, or `bland` |
| `reason` | string | `ours_failed_burst` (3 failed connections in 15 minutes), `dropped_calls` (2 calls ended before the agent answered, within 30 minutes), or `rate_gap` (task outcome rate gap over at least `rollback_min_calls` graded calls per side) |
| `previous_percent` | integer | ThunderPhone's share of calls before the rollback |
| `ours_percent` | integer | Always `0` |
| `step` | integer \| null | The schedule step it was on (0-based) |
| `ours` / `theirs` | object \| null | Graded calls in the current step and their success rate; `theirs` may be the last 30 days when the step has too few calls. `null` when there were none |
| `ours_failed` | integer | Failed connections counted in the last 15 minutes |
| `dropped` | integer | Calls counted as dropped in the last 30 minutes |
| `rolled_back_at` | timestamp | |

---

## Related

<CardGroup cols={2}>
  <Card title="telephony.incoming / web.incoming" icon="phone" href="/webhooks/call-incoming">
    The blocking inbound-call payload you must respond to.
  </Card>
  <Card title="telephony.complete / web.complete" icon="phone-slash" href="/webhooks/call-complete">
    Post-call transcript and metrics.
  </Card>
  <Card title="Webhook endpoints" icon="bolt" href="/webhooks/endpoints">
    Subscribe a URL to a subset of these events.
  </Card>
  <Card title="Function Tools" icon="screwdriver-wrench" href="/tools/overview">
    How `telephony.tool` / `web.tool` events are generated.
  </Card>
</CardGroup>

<!-- en: webhooks/call-incoming -->
---
title: "telephony.incoming / web.incoming"
description: "Blocking webhook that shapes an inbound call's configuration in real time."
---

When an inbound phone call reaches a number **without an assigned
agent** (see [Callbacks](#callbacks) for callers returning your
outbound calls), or a web widget session starts on a publishable key in
`mode="webhook"`, ThunderPhone sends a **blocking**
`telephony.incoming` / `web.incoming` request to your
[legacy webhook URL](/api-reference/organizations#legacy-single-url-webhook)
and waits for a configuration response: up to **13 seconds** for a
phone call, one retry included, and up to **10 seconds** for a widget
session (see [Timeouts and retries](#timeouts-and-retries)). Use this
exchange to dynamically choose a prompt, voice, and tools per call —
see the [dynamic call configuration guide](/guides/dynamic-call-config)
for the end-to-end pattern.

A number **with** an assigned agent answers with that agent. When the
agent has its own [call setup webhook](#agent-call-setup-webhook), the
same blocking exchange runs first, at the agent's URL, to fill in the
agent's variables and the call's context.

<Note>
  Subscribed [webhook endpoints](/webhooks/endpoints) also receive
  `telephony.incoming` / `web.incoming` — for **every** inbound call
  and web session, agent-configured or not — but those deliveries are
  fire-and-forget notifications with an `event_id`, never blocking.
  Only the legacy single-URL webhook carries the configuration
  exchange on this page. Endpoint notification shapes are in the
  [events catalog](/webhooks/events#telephony-incoming).
</Note>

## Timeouts and retries

Answer fast: the caller is waiting on the line while you decide.

For a phone call (`telephony.incoming`):

- The first attempt may take up to **10 seconds**.
- If it times out, cannot connect, or gets a `5xx`, `408` or `429`
  response, ThunderPhone tries once more. The retry gets whatever is
  left of a **13-second** budget for the whole exchange: about 3 seconds after
  a first attempt that timed out, nearly all 13 after a fast failure.
  There is no retry when less than 2 seconds would be left.
- Any other `4xx` response, a response over the
  [size limit](#response-size-limit), or a `2xx` whose body is not a
  valid configuration is final and is not retried.
- Both attempts send the same body, the same `X-ThunderPhone-Signature`,
  and the same `X-ThunderPhone-Idempotency-Key` header
  (`telephony-incoming-<call_id>`), so a handler that has side effects
  can recognize the retry.

If no usable configuration arrives, the call is ended right away
instead of leaving the caller on a silent line. It appears in call
history as a failed, unbilled call with `end_reason`
`inbound_config_webhook_failed`, and the usual
[`telephony.complete`](/webhooks/call-complete) event is sent. The call's
page in the dashboard, and `config_webhook_failure` in
[`GET /v1/calls/{call_id}`](/api-reference/calls), say what your webhook
did: `{kind, attempts, http_status, host, source}`, where `kind` is `http_error`,
`timeout`, `connection`, `dns`, `tls`, `response_too_large`,
`blocked_url`, `other`, `invalid_json`, `non_object_json` or
`invalid_config`, `host` is your webhook's host name, and `source` is
`number` (this webhook) or `agent_setup` (an agent's call setup webhook).
For `invalid_config`, `reason` says why the answer could not be used and
`fields` names the fields it is about: `no_agent` (neither `agent_id` nor
`prompt`; `fields` lists the keys that were ignored, such as a misspelled
`agentId`), `agent_not_found`, `agent_id_not_integer`, `unexpected_fields`
(keys other than `variables`, `context`, `timezone` and `language` next to
`agent_id`), `invalid_variables`, `invalid_context`, `invalid_language`,
`unsupported_language`, `invalid_config_fields` or `agent_settings_invalid`.
Otherwise `reason` is `null` and `fields` is empty. The one
exception is a caller returning one of your outbound calls when the
exchange itself failed: see [Callbacks](#callbacks).

A widget session (`web.incoming`) gets a single attempt of up to 10
seconds. If it fails, the session request fails with `502` or `422`.

<Warning>
  **Webhook-configured calls carry no ThunderPhone consent
  announcement.** Calls configured through this exchange bypass the
  agent-level call-start announcement and are expressly excluded from
  ThunderPhone's consent-announcement framework (Terms of Service,
  "Recording and consent" section). Your organization is solely
  responsible for every recording, monitoring, AI-participation, and
  caller-identification notice and consent required on these calls —
  the calls can still be recorded, transcribed, analyzed, and served
  by AI. Build the required disclosures into your own call flow before
  enabling this path.
</Warning>

## Request payload

For phone calls (`telephony.incoming`):

```json
{
  "type": "telephony.incoming",
  "data": {
    "call_id":     987654321,
    "from_number": "+14155550199",
    "to_number":   "+15551234567"
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `call_id` | integer | Call id — stable across all events for this call |
| `from_number` | string | E.164 caller number |
| `to_number` | string | E.164 destination (one of your ThunderPhone numbers) |
| `returning_call` | object | Present only when this number called the caller in the last 30 days. See [Callbacks](#callbacks) |
| `sip_headers` | object | Present only when the call arrived on a manual SIP connection with `X-*` or `User-to-User` SIP headers: header name in lower case → value. See [SIP headers](/guides/sip-addresses#pass-call-context-in-sip-headers) |

For web widget sessions (`web.incoming`) the `data` identifies the
embedding page instead of phone numbers:

```json
{
  "type": "web.incoming",
  "data": {
    "call_id": 987654322,
    "origin_domain": "https://example.com",
    "publishable_key_prefix": "pk_live_a1b2"
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `call_id` | integer | Call id |
| `origin_domain` | string | The page origin hosting the widget, as the browser sent it. A non-browser client can send any value, so do not treat it as proof of where the request came from |
| `publishable_key_prefix` | string | First characters of the publishable key that opened the session |
| `language`, `primary_language` | string | Present when the widget session requested a language override |
| `voice` | string | Present when the widget session requested a voice override |
| `website_context` | string | Present when the widget passed per-session page context |

The override fields (`language`, `voice`, `website_context`, and any
browser `variables`) arrive only when the publishable key allows them in
its [browser overrides](/guides/embed-web-widget#browser-overrides). A
session request carrying one the key does not allow is rejected before
this webhook is called.

<Note>
  Webhook-mode widgets deliver this request to the publishable key's
  own `webhook_url` when one is set, falling back to the org-level
  webhook URL. Either way it is signed with the org webhook `secret`.
</Note>

---

## Response schema

Return a JSON object describing the agent configuration for this call.
`prompt` and `voice` are required; everything else is optional.

```json
{
  "prompt":  "You are a helpful booking assistant for Acme Restaurant.",
  "voice":   "john",
  "product": "spark",
  "background_track": null,
  "tools":   []
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `prompt` | string | yes | System prompt driving the agent |
| `voice` | string | yes | Voice id from [`GET /v1/voices`](/api-reference/agents#voices), e.g. `john`. `voice_name` is accepted as an alias. Unknown voices fail validation and reject the call |
| `product` | string | no | Defaults to `spark`. Allowed: `spark`, `bolt`, `storm-base`, `storm-base-with-ack`, `storm-extra`, `storm-extra-with-ack` |
| `thinking_level` | string | no | `minimal`, `base` (default), or `extra`. Overridden for Storm products: `storm-extra*` forces `extra`, other `storm-*` force `base` |
| `audio_context_mode` | string | no | `full` (default) or `reduced` |
| `watchdog_enabled` | boolean | no | Enable supervision for this call. Default `false` |
| `additional_audio_context` | boolean \| null | no | Include the last few turns of caller audio rather than only the most recent turn, improving corrections and spelling/number-heavy data collection at a small latency/cost overhead. Defaults on for inbound sessions and off for outbound phone calls; `null` keeps the default |
| `storm_feedback_mode` | string | no | `none`, `acknowledgement` (default), or `tick`. Also what the caller hears while the audio models work out a turn when `audio_tier` is `hearing` or `deep_hearing` |
| `language` | string | no | Shorthand for `primary_language`. Also allowed next to `agent_id`, where it is the language this call starts in, spoken with the agent's voice for it; see [Set the language per call](/guides/dynamic-call-config#set-the-language-per-call) |
| `primary_language` | string | no | Language code, normalized (default `en`). Unresolvable codes reject the call |
| `has_additional_languages` | boolean | no | Default `false` |
| `additional_languages` | array of string | no | Extra languages the agent may switch to |
| `native_voice_switching` | boolean | no | Default `false`. When the call switches to another language, swap to a voice native to that language (matched by gender) instead of keeping the configured voice |
| `language_switching` | string \| null | no | `ask_first` (default) or `follow_caller`; `null` is the same as `ask_first`. How a multilingual agent handles the other person speaking another of its languages. `ask_first` switches at once when they ask for the language or say a full sentence in it, and asks whether to continue in it after something short, like a "sí". `follow_caller` switches to whatever configured language they speak, even a single word. Applies only when `additional_languages` is set |
| `audio_tier` | string \| null | no | `product: "bolt"` only. `standard` (default; `""` and `null` mean the same) runs three transcribers (calls that process PHI use only BAA-covered transcribers). `lean` downgrades to one transcriber, which mishears more often. `hearing` upgrades to `standard` plus a powerful ensemble of audio models that listens to the caller's audio on some turns, which take about 1–2 seconds longer. `deep_hearing`, the highest tier, is for exceptionally hard cases like rare languages; replies take about 3–4 seconds, and the call runs `standard` intelligence (`intelligence` is ignored). Not generally available: for an organization it has not been enabled for, the call runs `hearing` and the `intelligence` you name (an outbound call request with it is refused with `400`). Other products ignore it |
| `endpointing` | string \| null | no | `faster` (200 ms), `fast` (300 ms), `normal` (500 ms, default) or `patient` (800 ms); `null` is the same as `normal`. How long a Bolt v2 agent waits after the caller stops before asking the model for a reply. Shorter waits can answer sooner but send more requests that the caller's next words make stale, which raises the model cost. Other products ignore it |
| `eagerness` | string \| null | no | Deprecated: the name of `endpointing` until October 19, 2026, still read. Ignored when `endpointing` is set |
| `intelligence` | string \| null | no | `lite` or `standard` (default); `null` is the same as `standard`. The intelligence tier of a `bolt` agent on the Bolt v2 pipeline: which model writes its replies. `lite` is ~700 ms to first word, cheapest and a little less reliable (on calls treated as PHI, ~900 ms and less reliable); `standard` is ~900 ms, our production model; Lite replies that would only call a tool are handed to the Standard model. The retired `plus` and `max` run on `standard`. Ignored when `audio_tier` is `deep_hearing`. Other products ignore it |
| `faster_replies` | boolean \| null | no | Default `true`. On a `bolt` agent on the Bolt v2 pipeline, on replies where it helps, sends two requests and uses whichever answers first, which uses twice the model tokens on those replies. `false` turns that off (the Hearing audio tier's audio check can still send extra requests). Other products ignore it |
| `background_track` | string \| null | no | Ambient audio id or `null` |
| `acknowledgement_prompt_mode` | string | no | `auto` (default) or `manual` (Storm-with-ack products) |
| `acknowledgement_prompt` | string | no | Used when `acknowledgement_prompt_mode="manual"` |
| `silence_interval_seconds` | integer \| null | no | 5–120. Seconds of caller silence before a check-in |
| `silence_max_checkins` | integer \| null | no | 1–10 |
| `silence_checkins_enabled` | boolean | no | Default `true` |
| `silence_final_action` | string | no | After the last check-in: `hang_up` (default) or `transfer` to `silence_transfer_destination` |
| `silence_transfer_destination` | string | no | Name of an entry in this config's `transfer_destinations`; required with `transfer`. Without `transfer_destinations` the transfer can't be placed and the agent hangs up |
| `silence_final_message` | string | no | ≤ 300 chars, read as written; `""` (default) uses the default line |
| `connect_tone_enabled` | boolean | no | Default `false` |
| `pronunciation_dicts` | boolean \| null | no | Default `false`; `null` is the same as `false`. When `true`, the call's Cartesia speech uses ThunderPhone's pronunciation dictionary for the call's language, where one exists. Works for phone and widget calls. Applies only to ThunderPhone's own Cartesia voices, not to voices on your own Cartesia API key. Not used with `agent_id`, where the saved agent's settings apply |
| `words` | array \| null | no | How the agent says specific words, the same entries as an agent's [`words`](/api-reference/agents#words) without `support`. An entry without `language` takes this config's language. `null` and `[]` mean none. Not used with `agent_id`, where the saved agent's words apply |
| `voicemail_action` | string | no | `prompt` (default), `hangup`, or `message` |
| `voicemail_message` | string | no | Used when `voicemail_action="message"` |
| `agent_name` | string | no | Display name reported to dashboards and the widget |
| `org_name` | string | no | Organization display name for the agent's persona |
| `tools` | array | no | Inline function-tool schemas (see [Function Tools](/tools/overview)) |
| `transfer_destinations` | array of object \| null | no | Up to 50 `{name, number}` entries this call may transfer to, validated like an agent's [transfer numbers](/api-reference/agents#transfer-numbers). The agent transfers by name and only to these; `[]` means no transfers. Omit it or send `null` to let the agent transfer to a number it chooses |
| `timezone` | string | no | IANA time zone for this call, such as `America/Chicago`. The agent states the date and time in it, ahead of the agent's own time zone. Also allowed next to `agent_id`. Values that are not IANA zones are ignored. See [Set the time zone per call](/guides/dynamic-call-config#set-the-time-zone-per-call) |
| `context` | string \| null | no | Free-form text for this call, such as notes your system collected, up to 20,000 characters. Added after the prompt in a delimited block and not rendered as a template. Also allowed next to `agent_id`. A value that is not a string, or is longer, rejects the call. See [call variables and context](/guides/call-variables#context) |
| `call_id` | integer | no | Optional echo of the request's call id; ignored |

<Note>
  Unknown top-level keys are silently **ignored** — a typo'd field
  name doesn't reject the config, it just doesn't apply. Speak-order
  and `max_hold_seconds` are not accepted here; they are only
  configurable on the [Agent](/api-reference/agents) itself.
</Note>

Because `prompt` and `voice` are required, returning `{}` or any
response that fails validation rejects the call: a phone call is ended
as described in [Timeouts and retries](#timeouts-and-retries), and a
widget session request fails with `422`. This holds for returning
callers too: any JSON object your webhook returns is its answer, and
`{}` is the way to decline a call.

---

## Agent call setup webhook

An agent can have its own call setup webhook: the **Call setup webhook**
field in its settings, or [`call_setup_webhook_url`](/api-reference/agents#agent-object)
in the API. Assign the agent to a number, and before each inbound call
on that number the agent answers, ThunderPhone asks the webhook for that
call's variables and context. The number keeps its agent, so the phone
numbers page and the agent page show which agent answers it.

It is a setting like the agent's others: staged as a draft, published on
deploy, kept in the version history. A number
[pinned to an older version](/api-reference/phone-numbers#answer-with-one-version-of-an-agent)
asks that version's URL. Requests are signed with the agent's own
`call_setup_webhook_signing_secret` (not the organization's webhook
secret), with the same `X-ThunderPhone-Signature` header, timeouts,
retry and idempotency key as [above](#timeouts-and-retries). The secret is
write-only: set one your endpoint checks (in the agent's settings, or with
`PATCH /v1/agents/{id}`); no read ever returns it, and
`call_setup_webhook_signing_secret_set` says whether one is set.

The request is the `telephony.incoming` payload above plus the agent it
is filling in:

```json
{
  "type": "telephony.incoming",
  "data": {
    "call_id":     987654321,
    "from_number": "+14155550199",
    "to_number":   "+15551234567",
    "variables":   null,
    "agent": {
      "id": 12,
      "name": "Front desk",
      "version": 7,
      "version_pinned": false
    }
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `agent.id` | integer | The agent assigned to the number |
| `agent.name` | string | Its name |
| `agent.version` | integer \| null | The number of the version that will answer: the number's pinned version, else the agent's latest published version (`null` if it has none) |
| `agent.version_pinned` | boolean | Whether the number is pinned to that version |

**Answer with what the call needs.** Any of these fills in the
assigned agent, at the number's version:

- `{"variables": {...}}`, `{"context": "..."}`, or both
- the same with `"agent_id"` set to the assigned agent's id
- `{}`: the agent answers with nothing filled in

`timezone` and `language` are allowed too, as next to an
[`agent_id`](/guides/dynamic-call-config). Variables fill the agent's
`{{placeholders}}`; context is added after the prompt.

**Or decide the call yourself.** An `agent_id` of another agent, or a
full configuration with a `prompt`, answers this one call instead of the
assigned agent (and its pinned version). Call details label each case in
[`call_setup_webhook`](/api-reference/calls): `assigned_agent`,
`other_agent` or `inline_config`. An answer that cannot be used (an
unknown `agent_id`, other keys next to `variables`, a configuration that
fails validation) ends the call as for a number's webhook.

**When the webhook must answer.** An agent *needs* its webhook when its
settings use a `{{variable}}` with no default: its prompt or reusable
instructions, step instructions or lines, acknowledgement prompt,
voicemail message, consent announcement, or a `{{variable}}` transfer
number. The agent's `call_setup_webhook_variables` lists them.

- **It needs the webhook:** when the webhook times out, can't be
  reached, or answers with an error or a body that is not a JSON object,
  the call doesn't start, even when the call already carries a value for
  one of those variables. It is ended and recorded exactly as described
  in [Timeouts and retries](#timeouts-and-retries) (`end_reason`
  `inbound_config_webhook_failed`, unbilled).
- **It needs nothing** (no variables, or each one has a default like
  `{{first_name|there}}`): the webhook still runs, but when it fails the
  agent answers without it, and call details show `webhook_failed` with
  what went wrong.

Call context alone never makes the webhook required: nothing in an
agent's settings says it needs context. Use a variable without a
default if a call must not start without your webhook's answer.

**Assigning and deploying.** An agent that needs its webhook can't be
assigned to a number without one: the assignment is refused with a
message naming the variables. The same check runs when a number's
version changes, including a pinned number moving back to Latest. While it answers a number with its
published settings, a deploy that adds such a variable without a webhook
(or removes the webhook) is refused the same way. Saving the draft is
always allowed, and the agent's `warnings` carry
`call_setup_webhook_needed` until it is fixed.

The agent's webhook runs only for inbound phone calls on numbers it is
assigned to. Outbound calls, web widget sessions, SIP addresses,
simulations and dashboard test conversations don't call it; they take
their variables from the request as before.

**Testing with saved samples.** To test what your agent does with a
given answer (a returning caller, no record found, a Spanish speaker),
save that answer on the agent as a sample: its `variables`, `context`
and optionally `language`, typed in or copied from a past call. Pick it
when you start a dashboard test conversation, a test call to your phone
or a simulation against the agent, and the call runs as if your webhook
had answered with it. Samples are shared by every version of the agent.
Editing one keeps its earlier versions: when an agent change needs a
variable the sample doesn't set, add it to the sample, and older agent
versions keep using the sample as it was. Simulations that dial a phone
number run your real webhook instead.

Numbers without an assigned agent keep using the number's or the
organization's webhook exactly as above.

---

## Callbacks

People often call back a number that called them, for example after
your agent left a voicemail. When a phone call comes in from someone
the same number called in the last 30 days, ThunderPhone finds the
most recent such outbound call (one that rang their phone) and uses it
three ways:

1. **`returning_call` in the request.** The blocking request above,
   and the [endpoint notification](/webhooks/events#telephony-incoming),
   carry it, so your handler can route the caller:

   ```json
   {
     "type": "telephony.incoming",
     "data": {
       "call_id": 987654321,
       "from_number": "+14155550199",
       "to_number": "+15551234567",
       "returning_call": {
         "call_id": 987650001,
         "agent_id": 13,
         "started_at": "2026-10-21T19:05:12.402Z",
         "outcome": "voicemail"
       }
     }
   }
   ```

   | Field | Type | Description |
   |-------|------|-------------|
   | `call_id` | integer | The earlier outbound call |
   | `agent_id` | integer \| null | The agent that placed it; `null` for a call placed with an inline config or whose agent was deleted |
   | `started_at` | string | When it started (ISO 8601, UTC) |
   | `outcome` | string | `no_answer` (it rang out, was busy or was declined), `voicemail` (voicemail answered, or nobody spoke with the agent), `conversation` (someone spoke with the agent) or `answered` (picked up; who answered is not known yet) |

2. **Background for the agent.** Whichever agent answers gets a short
   note at the end of its prompt: when the earlier call was made, by
   which agent, and its outcome. The agent is told not to read it
   aloud, and, because caller ID can be faked, not to share anything
   about that call beyond having called the number earlier.

3. **A fallback agent.** When the number has no inbound agent and no
   configuration arrives because there is no webhook URL or your
   webhook gave no answer (it timed out, could not be reached, or
   answered `5xx`, `408` or `429` on both attempts), the call goes to
   the agent that placed the earlier call instead of ending, as long
   as that agent still exists in your organization. It runs with that
   agent's deployed settings. Any answer your webhook gives still
   decides: another `4xx`, a body that is not a JSON object, `{}`, or
   a config that fails validation ends the call as before. An inbound
   agent on the number always answers.

**Sharing the earlier call's details.** Caller ID can be faked, so by
default nothing from the earlier call's content reaches the new one.
An organization admin can turn on **Share the earlier call's details**
under Organization → General → Callbacks (or set
[`callback_context_details_enabled`](/api-reference/organizations#update-an-organization)).
With it on, the agent's note also quotes the earlier call's summary,
and a call routed to the agent that placed the earlier call runs with
that call's `variables` (such as a contact's name). Only turn it on if
those details are safe to share with anyone who calls from that
number. Even with it on, a call that may contain protected health
information never passes its summary or variables to a call that is
not designated as processing PHI.

**In call details.** An inbound call that matched an earlier call has
a `callback` object in [`GET /v1/calls/{call_id}`](/api-reference/calls):
the `returning_call` above, `routed_as_callback` (whether the fallback
answered it), and `config_webhook_failure` (`{kind, attempts,
http_status, host}` when your webhook gave no answer and the fallback took
the call, else `null`), so a webhook outage stays visible even though
the call was answered.

---

## Response size limit

<Warning>
  Configuration responses are limited to **5 MiB**. If a handler
  returns a larger response, including with a `2xx` status,
  ThunderPhone reports that the response exceeded the limit and
  rejects the call or widget session. Keep the response to the fields
  needed for call setup; host large data behind function tools or
  another service instead of embedding it in the configuration.
</Warning>

---

## Example handler

<CodeGroup>
```python Python (FastAPI)
import hashlib
import hmac
import json
import os

from fastapi import FastAPI, HTTPException, Request

app = FastAPI()
WEBHOOK_SECRET = os.environ["THUNDERPHONE_WEBHOOK_SECRET"]

def verify(body: bytes, signature: str) -> bool:
    expected = hmac.new(WEBHOOK_SECRET.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature or "")

@app.post("/thunderphone-webhook")
async def webhook(request: Request):
    body = await request.body()
    if not verify(body, request.headers.get("X-ThunderPhone-Signature", "")):
        raise HTTPException(status_code=401)

    event = json.loads(body)
    if event["type"] == "telephony.incoming":
        caller = event["data"]["from_number"]
        prompt = (
            "Greet the caller as a San Francisco local…"
            if caller.startswith("+1415")
            else "You are a friendly customer support agent…"
        )
        return {
            "prompt": prompt,
            "voice": "john",
            "product": "spark",
        }
    if event["type"] == "web.incoming":
        return {
            "prompt": "You are the website's helpful voice assistant…",
            "voice": "john",
            "product": "spark",
        }
    return {}
```

```javascript Node.js (Express)
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.THUNDERPHONE_WEBHOOK_SECRET;

function verify(body, signature) {
  const expected = crypto
    .createHmac("sha256", SECRET)
    .update(body)
    .digest("hex");
  return signature &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

app.post(
  "/thunderphone-webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    if (!verify(req.body, req.header("X-ThunderPhone-Signature"))) {
      return res.sendStatus(401);
    }
    const event = JSON.parse(req.body.toString("utf8"));

    if (event.type === "telephony.incoming" || event.type === "web.incoming") {
      const caller = event.data.from_number || "web";
      const prompt = caller.startsWith("+1415")
        ? "Greet the caller as a San Francisco local…"
        : "You are a friendly customer support agent…";
      return res.json({
        prompt,
        voice: "john",
        product: "spark",
      });
    }
    res.json({});
  },
);
```
</CodeGroup>

---

## Response with function tools

Attach tools so the AI can call your APIs mid-conversation:

```json
{
  "prompt":  "You are a booking assistant. Use the available tools to help customers schedule appointments.",
  "voice":   "john",
  "product": "spark",
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "search_appointments",
        "description": "Find available appointment slots",
        "parameters": {
          "type": "object",
          "properties": {
            "date": { "type": "string", "description": "YYYY-MM-DD" },
            "service": { "type": "string" }
          },
          "required": ["date"]
        }
      },
      "endpoint": {
        "url": "https://api.example.com/appointments/search",
        "method": "POST",
        "headers": {
          "X-Api-Key": "your-key"
        }
      }
    }
  ]
}
```

<Tip>
  Tool-endpoint requests are signed with the **same org webhook
  secret** that signed this exchange. See
  [Function Tools](/tools/overview) for the exact shape and the signed
  request format.
</Tip>

---

## Product tier cheat sheet

| Product | Latency | Reasoning | Acknowledgement |
|---------|---------|-----------|-----------------|
| `spark` | Lowest | Basic | — |
| `bolt` | Low | Improved | — |
| `storm-base` | Medium | Strong | — |
| `storm-base-with-ack` | Medium | Strong | Auto filler while thinking |
| `storm-extra` | Higher | Deep | — |
| `storm-extra-with-ack` | Higher | Deep | Auto filler while thinking |

---

## Related

<CardGroup cols={2}>
  <Card title="telephony.complete / web.complete" icon="phone-slash" href="/webhooks/call-complete">
    The non-blocking end-of-call event.
  </Card>
  <Card title="Function Tools" icon="screwdriver-wrench" href="/tools/overview">
    Full JSON schema for `tools[]` and the signed endpoint contract.
  </Card>
  <Card title="Webhook endpoints" icon="bolt" href="/webhooks/endpoints">
    Subscribe multiple URLs to `telephony.incoming` / `web.incoming`.
  </Card>
  <Card title="Dynamic call configuration" icon="wand-magic-sparkles" href="/guides/dynamic-call-config">
    Patterns for per-caller prompts, tools, and A/B tests.
  </Card>
</CardGroup>

<!-- en: webhooks/call-complete -->
---
title: "telephony.complete / web.complete"
description: "Non-blocking webhook delivered when a call ends, with transcript, recording URL, and metrics."
---

A completion event fires after every call ends — inbound telephony,
outbound telephony, web call, or test call (builder mic session). It is
**non-blocking**: respond with any 2xx.

The event is delivered on both paths:

* **[Webhook endpoints](/webhooks/endpoints)** receive
  `telephony.complete` (phone calls) or `web.complete` (web calls and
  builder mic test calls) with the stable payload documented below,
  a per-delivery `event_id`, a 30 s timeout, and
  [retries for up to 24 h](/webhooks/overview#delivery-semantics).
* **The [legacy single-URL webhook](/api-reference/organizations#legacy-single-url-webhook)**
  receives one synchronous attempt (10 s timeout, no retries) with a
  slightly different payload — see
  [Legacy payload differences](#legacy-payload-differences).

## Request payload (endpoint deliveries)

```json
{
  "data": {
    "billable_minutes": 1.25,
    "billing_total_cents": 8,
    "call_id": 987654321,
    "direction": "inbound",
    "duration_seconds": 54,
    "end_reason": "user_hangup",
    "end_time": "2026-04-20T18:25:04.822Z",
    "extracted_data": {
      "status": "completed",
      "fields": {
        "customer_name": "Alex Morgan",
        "appointment_date": "2026-04-23"
      },
      "evidence": {
        "customer_name": {
          "quote": "My name is Alex Morgan",
          "speaker_role": "caller",
          "turn_index": 4
        },
        "appointment_date": {
          "quote": "April 23 works for me",
          "speaker_role": "caller",
          "turn_index": 7
        }
      },
      "verification": "verified",
      "field_reasons": {},
      "schema_version": "92850758e231a3c95a..."
    },
    "from_number": "+14155550199",
    "product": "spark",
    "recording_stopped_at": null,
    "recording_stopped_reason": null,
    "recording_url": "https://storage.example.com/…",
    "start_time": "2026-04-20T18:24:10.113Z",
    "status": "completed",
    "summary": "Alex Morgan called to book a follow-up visit and confirmed Thursday, April 23. The agent read the appointment back and Alex asked for a reminder text the day before.",
    "to_number": "+15551234567",
    "transcripts": [ /* see Transcript format */ ],
    "transfer_number": null,
    "unresolved_variables": ["campaign_owner"],
    "variables": {"campaign_name": "Spring renewals"},
    "voice": "john"
  },
  "event_id": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
  "type": "telephony.complete"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `call_id` | integer | Stable across every event for this call |
| `agent_id` | integer \| null | Agent that handled the call, when one was assigned |
| `agent_name` | string \| null | Agent that handled the call, when one was assigned |
| `direction` | string | `inbound`, `outbound`, `web`, `test`. Historical payloads may contain legacy `mic` or `widget` values |
| `from_number`, `to_number` | string | E.164. `from_number` is the literal `"web"` for web calls and test calls |
| `origin_domain` | string | **Web/test only** — the page origin that hosted the widget (empty for mic sessions) |
| `start_time`, `end_time` | timestamp | ISO 8601 UTC |
| `duration_seconds` | integer \| null | Derived from start/end |
| `status` | string | `completed` or `failed` |
| `end_reason` | string | See table below |
| `answered_by` | string \| null | Outbound phone calls only (absent otherwise): who answered, `human`, `voicemail`, `screener` (a call screening assistant), `ivr` (a phone menu) or `unknown`. `null` when nobody answered, and always `null` in [`migration.call.complete`](/webhooks/events#migration-call-complete) events for outbound calls the platform you are moving from handled. Same values as the [call object](/api-reference/calls#call-object) |
| `product`, `voice` | string | Agent config in effect at call time |
| `variables` | object | Input variables snapshotted when the call started |
| `unresolved_variables` | array | Variable names referenced by the call config but not supplied at call start |
| `transfer_number` | string \| null | Set when the call was transferred |
| `scheduled_send_id` | string | Only on a call placed by a [scheduled send](/api-reference/scheduled-sends): that send's id. Absent on every other call |
| `recording_url` | string \| null | Expiring signed URL; download promptly. `null` when no recording artifact is available |
| `recording_stopped_at` | timestamp \| null | When the recording was stopped before the call ended; nothing after this moment is in the recording. `null` when the recording ran to the end of the call or the call was not recorded |
| `recording_stopped_reason` | string \| null | Why the recording stopped early. `warm_transfer`: it stops just before a [warm transfer](/guides/call-transfers) calls the destination, and stays off even if the transfer fails and the caller returns to the agent. Treat other values as informational; more may be added. `null` when `recording_stopped_at` is `null` |
| `billable_minutes` | number | Minutes billed, rounded to the nearest quarter minute (15-second increments, minimum 0.25). Straight-to-voicemail calls still report their actual metered minutes here, but the charge is capped at one minute at the plan rate. |
| `billing_total_cents` | integer \| null | USD cents. `null` while `billing_pending` is `true` |
| `billing_pending` | boolean | Only present, as `true`, on a metered call whose charge is not settled yet: a metered call is charged a few minutes after it ends, once its usage is in, so `billable_minutes` and `billing_total_cents` are `null` here and the charge arrives in [`call.billed`](/webhooks/events#call-billed). Absent on every other call |
| `transcripts` | array | Per-turn transcript entries; can be empty when a transcript is unavailable |
| `summary` | string \| null | Plain-language post-call summary (two to four sentences of prose, at most 2,000 characters, written in the call's language: the agent's primary language unless the call overrode it) when the agent has **Generate a call summary** turned on under **Data to collect** in the agent builder (`call_summary_enabled` on the [Agent](/api-reference/agents)) and generation succeeded; `null` otherwise, including for calls too short to summarize, calls with no transcript, and agents with recording turned off. The summary is generated in the same post-call step as extraction, so the **Wait for extracted data before sending the call-finished webhook** setting (`extraction_blocks_completion`) decides whether this event waits for it: in a waiting mode the summary is ready before this event is sent (the summary itself gets at most 30 seconds inside the step's 75-second budget); when the event does not wait (`never`, or a transfer or a return to your contact center under `except_transfers`) this field is `null` and the summary is **not** re-sent in `call.data_extracted`, so read it later from `summary` on the [Call object](/api-reference/calls#call-object). Also available on the call page in the dashboard |
| `extracted_data` | object \| null | Structured extraction result with `status`, `fields`, `evidence`, `verification`, `field_reasons`, and `schema_version`. Each non-null field has the exact structurally checked quote (at most 1,000 characters), plus its speaker role and turn index; longer model-returned quotes are rejected instead of truncated. Evidence is `null` when the field is `null`. `verified` means every candidate received exactly one valid independent verdict. `unavailable` also covers malformed or partial verifier output; valid partial verdicts still apply, while candidates without one valid verdict are nulled. `status` is `completed`, `failed`, `exhausted`, `skipped`, or `skipped_recording_disabled`; `null` when the agent had no extraction fields |
| `steps_trace` | array | Only on calls whose agent has steps or handoffs. The order the call moved through them: each entry has `t_ms` (milliseconds since the call started), `agent` (the agent's key, `a` plus its ID), `step` (the step ID, or `null` on a handoff to an agent without steps) and `via` (`start`, `model`, `condition`, `on_enter` or `handoff`). Holds IDs and times only, so it is kept even when recording is off |
| `collected_values` | object | Only on calls whose agent has steps or handoffs. The values the agent collected in its steps, keyed by collect field name, plus `<tool>_result` for each step's `on_enter_tool` result. Omitted when the call's content is not retained (recording turned off) |

### End reasons

| Value | Meaning |
|-------|---------|
| `user_hangup` | Remote party hung up first |
| `ai_hangup` | AI ended the call deliberately |
| `ai_transfer` | AI transferred the call; `transfer_number` is set |
| `ai_warm_transfer` | AI completed a warm (attended) transfer |
| `returned_to_platform` | AI [returned the call to your contact center](/guides/call-transfers#return-the-call-to-your-contact-center): it hung up, with the return entry's headers on the SIP `BYE` when it has any |
| `voicemail_hangup` | Voicemail was detected and the call ended per your `voicemail_action` |
| `max_duration` | Call hit the maximum duration limit: the agent's or the call's own limit, or the 6-hour platform limit. A call the AI or the caller ends after the time limit warning keeps `ai_hangup` or `user_hangup` |
| `superseded` | The session was replaced by a newer one |
| `inbound_config_webhook_failed` | Inbound call to a number in webhook mode: the [configuration webhook](/webhooks/call-incoming#timeouts-and-retries) did not return a usable configuration, so the call was ended before an agent answered. `status` is `failed` and the call is not billed |
| `outbound_queue_timeout` | A [queued call](/api-reference/outbound-calls#queued-calls) waited 10 minutes without room to dial. `status` is `failed`, nothing was dialed, and the call is not billed |
| `outbound_queue_canceled` | You cancelled a [queued call](/api-reference/outbound-calls#queued-calls) before it dialed. `status` is `failed`, and the call is not billed |
| `unknown` | End reason could not be determined |

## Transcript format

Each entry in `transcripts` is one conversational turn. Roles are
`user` (caller speech), `model` (agent speech **and** tool calls),
`tool` (tool results), and `system` (call events such as language
switches).

```json
[
  {
    "role": "user",
    "content_type": "text/plain",
    "content": "Hi, I'm calling about my appointment.",
    "start_ms": 1200,
    "end_ms":   4100,
    "audio_url": "https://storage.example.com/…"
  },
  {
    "role": "model",
    "content_type": "text/plain",
    "content": "Sure, what date works best?",
    "start_ms": 4200,
    "end_ms":   6100
  },
  {
    "role": "model",
    "content_type": "application/json",
    "content": {
      "tool_call": "search_appointments",
      "arguments": { "date": "2026-04-21" }
    }
  },
  {
    "role": "tool",
    "content_type": "application/json",
    "content": {
      "tool_name": "search_appointments",
      "response": { "available_slots": ["9:00 AM", "2:00 PM"] }
    }
  }
]
```

| Field | Type | Description |
|-------|------|-------------|
| `role` | string | `user`, `model`, `tool`, or `system` |
| `content_type` | string | `text/plain` for speech; `application/json` for tool calls, tool results, and system events |
| `content` | string \| object | Speech text, or the structured object shown above. Tool calls: `{"tool_call": name, "arguments": {…}}`. Tool results: `{"tool_name": name, "response": {…}}` |
| `start_ms`, `end_ms` | integer | Offsets from call start, ms. Present when audio timing is known |
| `ttfa_ms` | integer | Time-to-first-audio for a `model` turn, when measured |
| `audio_url`, `audio_urls` | string / array | Expiring signed URLs for the turn's audio, when recorded per-turn |

For the fully structured turn history (with interruption markers,
ack-prompts, and raw positions), use
[`GET /v1/calls/{call_id}/history`](/api-reference/calls#get-history).

## Legacy payload differences

The legacy single-URL webhook envelope is
`{"type": "telephony.complete" | "web.complete", "data": {…}}` with
**no `event_id`**, and its `data` differs from the endpoint payload:

The legacy completion payload also carries `agent_id` and `agent_name`.

* The turn array is under **`history`**, not `transcripts` (same turn
  schema as above).
* The field set is the raw end-of-call report and can include
  additional internal fields beyond the table above — treat unknown
  fields as informational.
* Web calls (`direction: "web"`) **omit** `from_number` / `to_number`
  and add `origin_domain`.
* Builder mic test calls report as `telephony.complete` on the legacy
  path (the endpoint system maps them to `web.complete`).
* **Transfer coordination:** when a call ends in a transfer, the
  legacy webhook is called synchronously and may answer
  `{"transfer_ready": false}` to signal the handoff target isn't
  ready. Any other response (or no legacy webhook) lets the transfer
  proceed. Endpoint deliveries are never consulted for this.

---

## Example handler

<CodeGroup>
```python Python (FastAPI)
import hashlib
import hmac
import json
import os

from fastapi import FastAPI, HTTPException, Request

app = FastAPI()
SECRET = os.environ["THUNDERPHONE_WEBHOOK_SECRET"]

def verify(body: bytes, signature: str) -> bool:
    expected = hmac.new(SECRET.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature or "")

@app.post("/thunderphone-webhook")
async def webhook(request: Request):
    body = await request.body()
    if not verify(body, request.headers.get("X-ThunderPhone-Signature", "")):
        raise HTTPException(status_code=401)

    event = json.loads(body)
    if event["type"] in ("telephony.complete", "web.complete"):
        data = event["data"]
        # Endpoint deliveries use "transcripts"; the legacy webhook uses "history".
        turns = data.get("transcripts") or data.get("history") or []
        await persist_call_record(
            call_id=data["call_id"],
            turns=turns,
            recording_url=data.get("recording_url"),
        )
        if data["end_reason"] in ("ai_transfer", "ai_warm_transfer"):
            await notify_team(data.get("transfer_number"), data["call_id"])
    return {"ok": True}
```

```javascript Node.js (Express)
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.THUNDERPHONE_WEBHOOK_SECRET;

function verify(body, signature) {
  const expected = crypto.createHmac("sha256", SECRET).update(body).digest("hex");
  return signature &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

app.post(
  "/thunderphone-webhook",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    if (!verify(req.body, req.header("X-ThunderPhone-Signature"))) {
      return res.sendStatus(401);
    }
    const event = JSON.parse(req.body.toString("utf8"));
    if (["telephony.complete", "web.complete"].includes(event.type)) {
      const data = event.data;
      // Endpoint deliveries use "transcripts"; the legacy webhook uses "history".
      const turns = data.transcripts ?? data.history ?? [];
      await persistCallRecord({ ...data, turns });
      if (["ai_transfer", "ai_warm_transfer"].includes(data.end_reason)) {
        await notifyTeam(data.transfer_number, data.call_id);
      }
    }
    res.json({ ok: true });
  },
);
```
</CodeGroup>

---

## Common use cases

<CardGroup cols={2}>
  <Card title="CRM integration" icon="database">
    Persist each call's transcript + recording URL alongside your
    customer records.
  </Card>
  <Card title="Analytics" icon="chart-line">
    Stream transcripts to a pipeline for topic modeling, CSAT signal
    extraction, or transfer-rate monitoring.
  </Card>
  <Card title="Quality review" icon="clipboard-check">
    Open calls in a QA tool for human review, or run them through your
    own evaluation model.
  </Card>
  <Card title="Notifications" icon="bell">
    Trigger a human teammate on transfer / failure.
  </Card>
</CardGroup>

---

## Related

<CardGroup cols={2}>
  <Card title="telephony.incoming / web.incoming" icon="phone" href="/webhooks/call-incoming">
    The blocking counterpart that runs at call start.
  </Card>
  <Card title="Events catalog" icon="list" href="/webhooks/events">
    Other event types you can subscribe to.
  </Card>
  <Card title="Call history API" icon="phone" href="/api-reference/calls">
    Same data accessible via REST for backfill / replay.
  </Card>
</CardGroup>

<!-- en: tools/overview -->
---
title: "Function Tools"
description: "Give your AI agents function tools that call external APIs mid-conversation — fetch customer data, book appointments, update records — with typed parameters."
---

Function tools allow your AI agents to invoke external APIs during phone calls. Use them to look up customer data, check availability, book appointments, or perform any action your backend supports.

## How It Works

1. You define tools with a schema (what arguments the tool accepts)
2. You provide an `endpoint` configuration (where ThunderPhone calls your API) — or leave it off to receive tool calls on your org webhook
3. During a call, the AI decides when to use a tool based on the conversation
4. ThunderPhone calls your endpoint with the tool arguments
5. Your API response is fed back to the AI to continue the conversation

| Capability | Where it runs | Setup |
| --- | --- | --- |
| [Built-in tools](/guides/built-in-tools) | ThunderPhone | Prompt instructions; some tools also need an agent setting |
| [App connections](/guides/connect-apps) | ThunderPhone and the connected provider | Connect the account and attach approved actions |
| [API connections](/guides/api-connections) and function tools | Your HTTP API | Define the endpoint and schema, or receive function calls through a webhook |
| [MCP servers](/guides/mcp-servers) | A remote MCP server | Add the server, discover its tools, and attach it to the agent |

---

## Tool Schema

Each tool follows this structure:

```json
{
  "type": "function",
  "function": {
    "name": "search_appointments",
    "description": "Find available appointment slots for a given date",
    "parameters": {
      "type": "object",
      "properties": {
        "date": {
          "type": "string",
          "description": "Date in YYYY-MM-DD format"
        },
        "service": {
          "type": "string",
          "description": "Type of service (e.g., 'consultation', 'follow-up')"
        }
      },
      "required": ["date"]
    }
  },
  "endpoint": {
    "url": "https://api.example.com/appointments/search",
    "method": "POST",
    "headers": {
      "X-Api-Key": "your-api-key"
    }
  },
  "timeout": 120
}
```

### Tool Configuration

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `timeout` | number | No | Maximum execution time in seconds (default: `20`, maximum: `180`) |
| `call_start` | object | No | Also run the tool automatically at the start of every phone call, before the greeting. See [Run a tool at the start of the call](#run-a-tool-at-the-start-of-the-call) |

### Function Definition

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Identifier for the tool, unique among the tools of one call. Different agents may each have their own tool with the same name |
| `description` | string | Yes | Explains to the AI when to use this tool |
| `parameters` | object | Yes | JSON Schema for tool arguments |

### Endpoint Configuration

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Your API endpoint URL |
| `method` | string | No | HTTP method (default: `POST`) |
| `headers` | object | No | Custom headers to include |

<Note>
  The `endpoint` configuration is **not** sent to the AI model—it's only used by ThunderPhone to execute the tool call.
</Note>

---

## Two invocation paths

Which request your server receives depends on whether the tool has an
`endpoint`:

| | Tool **with** `endpoint` | Tool **without** `endpoint` |
|---|---|---|
| Where the request goes | Directly to `endpoint.url` | Your org's [legacy webhook URL](/api-reference/organizations#legacy-single-url-webhook) |
| Body | Selected request format (bare arguments by default) | `telephony.tool` / `web.tool` envelope |
| Headers | Your `endpoint.headers` + `X-ThunderPhone-Call-ID` + `X-ThunderPhone-Signature-V2` + `X-ThunderPhone-Signature`, plus the call's numbers on phone calls | `Content-Type` + `X-ThunderPhone-Signature-V2` + `X-ThunderPhone-Signature` |
| Signing key | Org webhook secret | Org webhook secret |

Both paths are **blocking** — the AI is waiting mid-sentence for the
result. The default timeout is **20 s**; set the tool's top-level
`timeout` to allow a longer execution, up to the **180 s** platform
maximum. Keep handlers fast. A mix is fine:
on a call whose org has a webhook URL, tools with an `endpoint` are
called directly and the rest fall back to the webhook.

## Direct endpoint calls

When the AI invokes a tool that has an `endpoint`, ThunderPhone sends
a request to your URL:

### Request Headers

```http
POST /appointments/search HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-ThunderPhone-Signature-V2: t=1767225600,v1=5f2c...
X-ThunderPhone-Signature: abc123...
X-ThunderPhone-Call-ID: 987654321
X-ThunderPhone-From-Number: +14155550199
X-ThunderPhone-To-Number: +14155550100
X-ThunderPhone-Call-Direction: inbound
X-Api-Key: your-api-key
```

Custom headers from your `endpoint.headers` are always included
verbatim, plus these ThunderPhone-namespaced headers:

- `X-ThunderPhone-Signature-V2` — timestamped HMAC-SHA256 over the
  method, path, query and body, keyed with your **org webhook secret**.
  Verify this one and reject requests more than 5 minutes old; see
  [Verify webhook signatures](/guides/verify-webhook-signatures#signature-v2)
- `X-ThunderPhone-Signature` — legacy HMAC-SHA256 of the exact
  request-body bytes, same key, still sent for existing verifiers
- `X-ThunderPhone-Call-ID` — The current call ID
- `X-ThunderPhone-From-Number` and `X-ThunderPhone-To-Number` — the
  call's From and To numbers in E.164. They mean the same as
  `from_number` and `to_number` in
  [`telephony.complete`](/webhooks/events): on an outbound call, From is
  your agent's number and To is the person called. A number is left out
  when the caller ID is withheld or isn't a phone number
- `X-ThunderPhone-Call-Direction` — `inbound` or `outbound`, so you can
  tell which number is the customer's

The call-number headers are sent on phone calls only. Web, widget,
realtime and browser Talk tests have no phone number and leave them
out. Test calls from the agent editor and AI simulations carry the
simulated caller's number. The signatures do not
cover headers: V2 signs the timestamp, method, path, query and body. If
you need the numbers signed, read them from the body instead: the
`retell` request format carries all three, and `vapi` carries the
customer's number.

`Content-Type: application/json` is set unless your `endpoint.headers`
override it — a custom `Content-Type` wins.

<Note>
  Every tool request is signed with your org's webhook secret, from
  [`GET /v1/webhook`](/api-reference/organizations#legacy-single-url-webhook).
  ThunderPhone creates the secret automatically, even if your org never
  configured the legacy webhook.
</Note>

### Request format

Each API connection has a `request_format` setting. Choose `vapi` or
`retell` when an imported tool should keep calling an endpoint built for
that platform. New and existing connections default to `standard`.

For `POST` / `PUT` / `PATCH`, ThunderPhone serializes the selected
envelope canonically (sorted keys, compact separators). Both signatures
cover these exact bytes.

#### Standard

`standard` sends only the tool arguments, with no wrapper. This is the
default and preserves ThunderPhone's original request body byte for byte:

```json
{"date":"2025-01-02","service":"consultation"}
```

#### Vapi

`vapi` sends Vapi's [`tool-calls` server message](https://docs.vapi.ai/tools/custom-tools)
in the shape Vapi documents. The `call.id` is the ThunderPhone call ID.
On phone calls, `call.customer.number` is the other party's number, as in
Vapi's call object: the caller on an inbound call, the person called on
an outbound one. It is left out when that number is withheld or isn't a
phone number. The tool-call `id` is unique to the invocation and is
reused to match the endpoint's result. The call appears in both `toolCallList` and
`toolWithToolCallList`, with `function.arguments` as a JSON object:

```json
{
  "message": {
    "type": "tool-calls",
    "timestamp": 1725000000123,
    "call": { "id": "987654321" },
    "toolCallList": [
      {
        "id": "call_00112233445566778899aabbccddeeff",
        "type": "function",
        "function": {
          "name": "search_appointments",
          "arguments": { "date": "2025-01-02", "service": "consultation" }
        }
      }
    ],
    "toolWithToolCallList": [
      {
        "type": "function",
        "function": { "name": "search_appointments" },
        "toolCall": {
          "id": "call_00112233445566778899aabbccddeeff",
          "type": "function",
          "function": {
            "name": "search_appointments",
            "arguments": { "date": "2025-01-02", "service": "consultation" }
          }
        }
      }
    ]
  }
}
```

Vapi-only fields such as `assistant`, `artifact` and the full `call` object
are not sent.

Return Vapi's response envelope with the matching tool-call ID:

```json
{
  "results": [
    {
      "toolCallId": "call_00112233445566778899aabbccddeeff",
      "result": "{\"available_slots\":[\"9:00 AM\",\"2:00 PM\"]}"
    }
  ]
}
```

ThunderPhone gives the AI the unwrapped `result` string. It also accepts a
JSON value for compatibility with endpoints that already return one. An
`error` in place of `result` is returned to the AI as a tool error. If the
endpoint returns a malformed or mismatched Vapi envelope, ThunderPhone logs
a warning and falls back to its standard response parsing instead of failing
the call.

#### Retell

`retell` sends the request documented for a [Retell custom
function](https://docs.retellai.com/build/single-multi-prompt/custom-function):

```json
{
  "name": "search_appointments",
  "call": {
    "call_id": "987654321",
    "from_number": "+14155550199",
    "to_number": "+14155550100",
    "direction": "inbound"
  },
  "args": { "date": "2025-01-02", "service": "consultation" }
}
```

On phone calls, the `call` object carries `call_id`, `from_number`,
`to_number` and `direction` (`inbound` or `outbound`), the field names
Retell's phone call object uses. They match the call-number headers,
and unlike the headers they are covered by both signatures. A number
that is withheld or isn't a phone number is left out. On web, widget,
realtime and browser Talk tests it holds only `call_id`. ThunderPhone
does not include
Retell-specific fields it cannot honestly supply at dispatch, such as
`agent_id`, `transcript`, `transcript_object`, `metadata`, or dynamic
variables. Retell accepts any response body; ThunderPhone passes it
through using the standard response handling.

For `GET` / `DELETE`, the arguments are sent as **query parameters**
and the body is empty regardless of `request_format`. The V2 signature
covers the query string as sent; the legacy signature is computed over
the empty byte string. See
[Verify webhook signatures](/guides/verify-webhook-signatures#verifying-tool-calls).

### Response

Return a JSON response with the tool result:

```json
{
  "available_slots": ["9:00 AM", "2:00 PM", "4:30 PM"],
  "timezone": "America/Los_Angeles"
}
```

The response is formatted and provided to the AI to continue the
conversation. Non-JSON responses are wrapped as `{"data": "<text>"}`;
timeouts and connection failures are reported to the AI as errors, so
the agent can apologize and move on rather than stall.

## Webhook-mode dispatch

Tools **without** an `endpoint` are dispatched to your org's legacy
webhook URL as a signed `telephony.tool` (phone calls) or `web.tool`
(web calls) request. Unlike the [audit notifications](/webhooks/events)
delivered to webhook endpoints after execution, this request **is**
the execution — your HTTP response is the tool result.

```json
{
  "type": "telephony.tool",
  "data": {
    "call_id": 987654321,
    "tool_name": "search_appointments",
    "arguments": { "date": "2026-04-21" },
    "from_number": "+14155550199",
    "to_number": "+15551234567"
  }
}
```

`web.tool` carries `origin_domain` instead of `from_number` /
`to_number`. Respond with the tool result as JSON — the same response
contract as direct endpoint calls. The request is signed with the org
webhook secret, with both signature headers, like every other webhook.

<Note>
  Subscribed [webhook endpoints](/webhooks/endpoints) additionally
  receive a non-blocking `telephony.tool` / `web.tool` **notification
  after** each tool executes (whichever path ran it), including the
  tool's response — useful for audit trails. See the
  [events catalog](/webhooks/events#telephony-tool).
</Note>

---

## Signature Verification

Direct tool calls are signed the same way as webhooks, keyed with your
org webhook secret:

- `X-ThunderPhone-Signature-V2` signs the timestamp, method, path and
  query as sent, and the exact body bytes. Reject requests whose
  timestamp is more than 5 minutes from your clock.
- `X-ThunderPhone-Signature` (legacy) signs only the body bytes, the
  empty byte string for `GET` / `DELETE`. It is still sent, unchanged.

The SDK helpers check the V2 header, including the 5-minute window:

<CodeGroup>
```python Python
import json

from fastapi import FastAPI, HTTPException, Request
from thunderphone import verify_signature

app = FastAPI()

@app.post("/appointments/search")
async def search_appointments(request: Request):
    body = await request.body()
    query = request.scope.get("query_string", b"").decode("latin-1")
    path = request.url.path + (f"?{query}" if query else "")

    if not verify_signature(
        request.headers.get("X-ThunderPhone-Signature-V2"),
        secret=WEBHOOK_SECRET,
        method=request.method,
        path=path,
        body=body,
    ):
        raise HTTPException(status_code=401)

    data = json.loads(body)
    date = data["date"]

    # Look up availability
    slots = await get_available_slots(date)

    return {"available_slots": slots}
```

```javascript Node.js
import express from "express";
import { verifySignature } from "@thunderphone/sdk";

app.post('/appointments/search', express.raw({type: 'application/json'}), (req, res) => {
  const ok = verifySignature({
    header: req.header('X-ThunderPhone-Signature-V2'),
    secret: WEBHOOK_SECRET,
    method: req.method,
    path: req.originalUrl,
    body: req.body,
  });
  if (!ok) return res.status(401).send('Invalid signature');

  const { date, service } = JSON.parse(req.body);

  // Look up availability
  const slots = getAvailableSlots(date, service);

  res.json({ available_slots: slots });
});
```
</CodeGroup>

Full recipes — the signed string, a worked example, code without the
SDK, the `GET` / `DELETE` case and the no-secret caveat — are in [Verify webhook signatures](/guides/verify-webhook-signatures#verifying-tool-calls).

---

## Example: Complete Booking Flow

Here's a set of tools for a complete appointment booking system:

```json
{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "search_appointments",
        "description": "Find available appointment slots",
        "parameters": {
          "type": "object",
          "properties": {
            "date": { "type": "string", "description": "YYYY-MM-DD" },
            "service": { "type": "string" }
          },
          "required": ["date"]
        }
      },
      "endpoint": {
        "url": "https://api.example.com/appointments/search",
        "method": "POST",
        "headers": { "X-Api-Key": "key" }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "book_appointment",
        "description": "Book an appointment at a specific time",
        "parameters": {
          "type": "object",
          "properties": {
            "date": { "type": "string", "description": "YYYY-MM-DD" },
            "time": { "type": "string", "description": "HH:MM format" },
            "customer_name": { "type": "string" },
            "customer_phone": { "type": "string" }
          },
          "required": ["date", "time", "customer_name"]
        }
      },
      "endpoint": {
        "url": "https://api.example.com/appointments/book",
        "method": "POST",
        "headers": { "X-Api-Key": "key" }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "cancel_appointment",
        "description": "Cancel an existing appointment",
        "parameters": {
          "type": "object",
          "properties": {
            "confirmation_number": { "type": "string" }
          },
          "required": ["confirmation_number"]
        }
      },
      "endpoint": {
        "url": "https://api.example.com/appointments/cancel",
        "method": "POST",
        "headers": { "X-Api-Key": "key" }
      }
    }
  ]
}
```

---

## Run a tool at the start of the call

A tool can also run automatically at the start of every phone call,
before the agent says its first word, so the greeting can use the result. The usual
case is a CRM lookup by the caller's number: "Welcome back, Arthi! Would
you like your usual order?"

In the dashboard, open the API connection and set **When it runs** to
**At the start of every phone call**, then fill in the value each
parameter gets. Through the API, set the integration's `trigger` to
`call_start` and its `call_start_arguments`
([API connections](/api-reference/integrations)), or add a `call_start`
block to an inline tool:

```json
{
  "type": "function",
  "function": {
    "name": "get_contact_by_phone",
    "description": "Look up a customer by phone number.",
    "parameters": {
      "type": "object",
      "properties": {
        "business_id": {"type": "string"},
        "phone_number": {"type": "string"}
      },
      "required": ["business_id", "phone_number"]
    }
  },
  "endpoint": {"url": "https://crm.example.com/contacts/lookup"},
  "call_start": {
    "arguments": {
      "business_id": "a0a81c23",
      "phone_number": "{{caller_number}}"
    }
  }
}
```

The arguments need a value for every required parameter, since nobody
fills anything in at call start. Values are strings, numbers or booleans.
They are stored and returned as plain text and the agent sees them, so keep
secrets such as API keys in the connection's headers, not here. Strings can
use these placeholders:

| Placeholder | Value |
|-------------|-------|
| `{{caller_number}}` | The other person on the call in E.164 format, e.g. `+61402122887`: the caller on an inbound call, the person called on an outbound call |
| `{{caller_number_national}}` | The same number in its country's national format without spaces, e.g. `0402122887` |
| `{{agent_number}}` | The agent's own number |

How it behaves:

- The request is the same one the agent's own tool calls send (same
  endpoint, headers, request format and signature).
- The tool starts when the call starts, and runs while any connect tone,
  intro or recording notice plays. The greeting waits for it for up to
  about 3 seconds from that point. A slower result is given to the agent
  as soon as it arrives, for the rest of the call. On an outbound call it
  starts when the call is placed, so it runs on every attempt, including
  ones nobody answers.
- On an agent where the caller speaks first there is no greeting to
  wait for; the agent gets the result as soon as it arrives.
- The result is given to the agent as context for the whole call. Tell
  the agent in your prompt how to use it; it is not read out otherwise.
- If the tool fails or times out, the agent greets the caller as it
  normally would and says nothing about it.
- The agent can still call the tool itself later in the call.
- It runs on phone calls, including dashboard test calls to your phone,
  and on AI simulations, which send the simulated caller's number to your
  endpoint. It does not run in browser **Talk** tests or web widget
  sessions, which have no caller number, on calls whose caller ID is
  withheld, or on agents with steps.
- An agent runs at most three call-start tools, all at once.

Mention the result in your prompt so the agent knows how to use it, for
example: "If the call start lookup found the caller, greet them by first
name."

---

## Best Practices

<AccordionGroup>
  <Accordion title="Write clear descriptions">
    The `description` field helps the AI understand **when** to use the tool. Be specific about what it does and when it's appropriate.
  </Accordion>

  <Accordion title="Handle errors gracefully">
    Return error messages the AI can understand: `{"error": "No slots available for that date"}` rather than generic 500 errors.
  </Accordion>

  <Accordion title="Keep responses concise">
    Return only what the AI needs to continue the conversation. A tool result stays in the conversation and is re-read on every later turn, so a large one adds cost and delay for the rest of the call. Results over 100,000 characters are cut down to a preview the AI knows is incomplete, and on a very long call older results may be dropped (the AI can call the tool again). Add a parameter so the AI can look up one item or category at a time, and put large reference content such as menus or catalogs in a [knowledge base](/guides/knowledge-base). **Send Test Request** in the dashboard shows each result's size and warns when it is large.
  </Accordion>

  <Accordion title="Use required fields wisely">
    Mark fields as `required` only when truly necessary. The AI will ask the user for required information before calling the tool.
  </Accordion>
</AccordionGroup>

---

## Related

<CardGroup cols={2}>
  <Card title="Built-in tools" icon="wrench" href="/guides/built-in-tools">
    Prompt platform-managed call actions without defining an endpoint.
  </Card>
  <Card title="App connections" icon="plug" href="/guides/connect-apps">
    Platform-managed tools for HubSpot, Salesforce, Slack, Google
    Calendar, Google Sheets, and Cal.com — no endpoint required.
  </Card>
  <Card title="MCP servers" icon="server" href="/guides/mcp-servers">
    Attach an MCP server and let the agent call its tools.
  </Card>
  <Card title="API connections" icon="code" href="/guides/api-connections">
    Reusable REST integrations you can attach to agents.
  </Card>
  <Card title="Verify webhook signatures" icon="shield-check" href="/guides/verify-webhook-signatures">
    One verification helper for webhooks and tool calls.
  </Card>
</CardGroup>