> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Core concepts
> 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), [phone numbers](#phone-numbers),
[web widgets](#web-widgets), [calls](#calls),
[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), [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 General, Keys, Alerts, Billing
Settings, and Billing History.
**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.
***
## Phone numbers
A **phone number** belongs to an org and routes inbound calls to an
agent (and can carry outbound calls). Two sources:
* **Demo numbers** — real U.S. numbers provisioned from ThunderPhone's
pool, live in seconds. Inbound-only, they answer with a short spoken
disclaimer, and the dashboard caps an org at 10 of them. Perfect for
a first test; not for production.
* **VoIP numbers** — brought from your own provider through a
[VoIP connection](#connections). Twilio and Telnyx connect directly
(Telnyx has a guided setup); SignalWire and Vonage are coming soon —
today you reach them via manual SIP configuration, which accepts any
SIP trunk. 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).
***
## 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's origin-locked to your
allowed domains, so it's safe in client-side code.
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 directly or import from
Google Drive, 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).
**In the API:** [`/v1/integrations`](/api-reference/integrations) 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).
***
## 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`). You have up to 10 seconds
to respond; on timeout the statically-assigned agent handles the
call.
* **Non-blocking events** are fire-and-forget notifications, retried
with exponential backoff — see
[delivery semantics](/webhooks/overview).
Every request carries an HMAC-SHA256 signature in
`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
[premium languages](/guides/supported-languages) add 2¢/min). 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).
**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.