Core concepts

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:

---

​

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, /v1/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.
• Attached capabilities: connected apps, API connections, knowledge bases, MCP servers, and inline 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. In the API: /v1/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. 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. In the API: /v1/phone-numbers, /v1/voip-connections, /v1/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. In the API: /v1/calls — list, transcript, history, audio, grading, export; /v1/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). 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. In the API: /v1/publishable-key, /v1/mic-session, and the Widget SDK docs.

---

​

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.

---

​

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.
• 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 — the dashboard face of /v1/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.
• VoIP (/dashboard/voip-connections) — provider credentials for bringing your own phone numbers. See Connect a VoIP provider.

In the API: /v1/integrations and /v1/voip-connections; see also Build a 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. For one-off programmatic calls: the outbound calls API.

---

​

Live monitoring

Live shows every call in progress across the org, and lets you open any of them to listen in and whisper 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.

---

​

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. In the API: /v1/test-calls and the suite runner — see Test an agent end-to-end.

---

​

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

---

​

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. In the API: /v1/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.

---

​

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.

---

​

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. In the dashboard: Organization → Alerts. See 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 with per-endpoint secrets and per-endpoint event subscriptions.
• Legacy single-URL webhook: one URL per org. Managed at /v1/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 (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.

Every request carries an HMAC-SHA256 signature in X-ThunderPhone-Signature. See 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). In the API: /v1/integrations and the Function Tools spec.

---

​

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. In the dashboard: Organization → General. See Invite your team. In the API: /v1/members, /v1/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 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. In the API: /v1/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.

---

​

Putting it together