---
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:
[Agents](#agents), [voices](#voices), [phone numbers](#phone-numbers),
[web widgets](#web-widgets), [calls](#calls),
[client portals](#client-portals), [knowledge](#knowledge-bases).
[Live monitoring](#live-monitoring) and outbound
[campaigns](#campaigns).
[Apps, APIs, MCP servers, and VoIP providers](#connections) your
agents can use.
[Simulations](#simulations), [validation sets](#validation-sets),
[experiments](#experiments),
[issues](#issues), [reports](#reports),
[observability](#observability).
[Team & roles](#team-and-roles), [API keys](#organizations),
[alerts](#alerts), [billing](#billing).
[Webhooks](#webhooks) and [function tools](#function-tools) for
your own code.
---
## 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 any premium
voice/language surcharge. 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 plus a 1¢/minute{/* /rate */}
surcharge. 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; calls
debit it at the agent's per-minute rate (engine tier plus surcharges —
the builder shows the all-in rate live as you change settings, and
[selected additional languages](/guides/supported-languages) add {/* rate:language */}3¢/min{/* /rate */}). 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
The five-step wizard: agent → billing → number → simulation → review.
The same first call in four REST calls.
Build an agent, fund it, get a number, simulate, and review calls.
OAuth apps, custom APIs, MCP servers, and VoIP providers.
Reports, observability, experiments, issues, and alerts.
Invites and roles, API keys, security, and SSO.
The API recipes: inbound, outbound, dynamic config, tools, testing.
Get the HMAC check right once and reuse everywhere.