# ThunderPhone Documentation

> Build, test, monitor, and improve AI phone agents.

OpenAPI: https://thunderphone.com/docs/openapi.json

## Docs

- [Introduction](https://thunderphone.com/docs/index.md): Documentation for running production voice agents over real phone calls and embeddable web widgets: quickstarts, guides, and the full ThunderPhone API reference.
- [Quickstart (dashboard)](https://thunderphone.com/docs/quickstart-dashboard.md): 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.
- [Quickstart (API)](https://thunderphone.com/docs/quickstart.md): 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.
- [Build with Claude Code, Codex or Cursor](https://thunderphone.com/docs/guides/coding-agents.md): Install ThunderPhone Agent Skills, connect the ThunderPhone MCP server, and give a coding agent current product documentation.
- [Core concepts](https://thunderphone.com/docs/guides/concepts.md): A map of everything in the platform — what each object does, where it lives in the dashboard, and which API touches it.
- [Ask the copilot](https://thunderphone.com/docs/guides/ask-the-copilot.md): The in-app assistant answers product questions, shows you where things are, and can drive the dashboard for you — by text or voice.
- [Supported languages](https://thunderphone.com/docs/guides/supported-languages.md): Every language ThunderPhone agents can speak, which voices support each one, and how per-minute pricing differs between included and premium languages.
- [ThunderPhone pricing and usage charges](https://thunderphone.com/docs/guides/pricing.md): Complete ThunderPhone pricing for Spark, Bolt, Storm, voices, languages, prompts, supervision, acknowledgements, calls, hold time, simulations, and phone numbers.
- [Dashboard home: calls, success, issues, and live activity](https://thunderphone.com/docs/guides/dashboard-overview.md): Use the ThunderPhone dashboard home to track call volume, success rate, duration, issues, and live or queued calls by agent or phone number.
- [Build your first voice agent](https://thunderphone.com/docs/guides/build-an-agent.md): 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.
- [Import agents from another platform](https://thunderphone.com/docs/guides/import-agents.md): 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.
- [Prompting guide](https://thunderphone.com/docs/guides/prompting.md): Tactics and copy-paste templates for prompts that sound natural on the phone and hold up under real callers.
- [Voice agent settings reference](https://thunderphone.com/docs/guides/agent-settings.md): Every ThunderPhone voice agent setting explained: tiers, voices, languages, acknowledgements, tools, speak order, voicemail, consent announcements, silence handling, testing, and deployment.
- [Voice library, previews, and custom voices](https://thunderphone.com/docs/guides/voice-library.md): Search and preview ThunderPhone voices, generate spoken samples, request custom voice access, create a voice from audio, and manage voice pricing and status.
- [Add funds and turn on auto top-up](https://thunderphone.com/docs/guides/billing-and-topups.md): Pay-as-you-go billing: add a card, load your balance, and set auto top-up so a call never dies mid-sentence.
- [Get a phone number (from ThunderPhone or your own)](https://thunderphone.com/docs/guides/get-a-phone-number.md): Get a ThunderPhone number in seconds, or connect your VoIP provider to use numbers you already own.
- [Simulate a call before you ship](https://thunderphone.com/docs/guides/simulate-a-call.md): An AI caller has a real conversation with your agent — same telephony path, real transcript, real grading.
- [Validation sets: replay real call turns before deployment](https://thunderphone.com/docs/guides/validation-sets.md): Turn real ThunderPhone call moments into reusable validation examples, review expected behavior, replay them against an agent draft, and catch regressions before deploy.
- [Review, listen to, and coach your calls](https://thunderphone.com/docs/guides/review-calls.md): Call History end-to-end: transcripts, recordings, live listen-in, and whispering instructions to your agent mid-call.
- [Knowledge base](https://thunderphone.com/docs/guides/knowledge-base.md): Upload your docs once — FAQs, policies, product sheets — and let agents search them mid-call.
- [Outbound campaigns](https://thunderphone.com/docs/guides/outbound-campaigns.md): Upload a contact list and let an agent work through it — with calling windows, retries, and live progress.
- [Monitor live calls](https://thunderphone.com/docs/guides/monitor-live-calls.md): See every call in progress, listen in silently, and whisper guidance the caller never hears.
- [Create a web widget in the dashboard](https://thunderphone.com/docs/guides/embed-a-web-widget-dashboard.md): Set up a click-to-talk widget for your site from the Web Widgets page — no API calls required.
- [Client portals: branded read-only call reporting](https://thunderphone.com/docs/guides/client-portals.md): Create a ThunderPhone client portal, choose visible agents, add viewers, brand the experience, connect a custom domain, and share read-only call history.
- [Connect apps (Google, Slack, HubSpot & more)](https://thunderphone.com/docs/guides/connect-apps.md): 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.
- [API connections](https://thunderphone.com/docs/guides/api-connections.md): 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.
- [MCP servers](https://thunderphone.com/docs/guides/mcp-servers.md): Connect a remote MCP server and every tool it exposes becomes available to your agents mid-conversation, without defining each tool by hand.
- [Connect your coding agent to ThunderPhone docs](https://thunderphone.com/docs/guides/docs-mcp.md): Add ThunderPhone
- [Use ThunderPhone as an MCP server](https://thunderphone.com/docs/guides/thunderphone-mcp-server.md): Build, test, validate, and operate ThunderPhone voice agents from Claude Code, Codex, Cursor, Claude Desktop, VS Code, or another Streamable HTTP MCP client.
- [Use ThunderPhone from Pipecat](https://thunderphone.com/docs/guides/use-with-pipecat.md): Run a ThunderPhone voice agent as the speech-to-speech service inside a Pipecat pipeline, with your own transport and telephony.
- [Use ThunderPhone from LiveKit Agents](https://thunderphone.com/docs/guides/use-with-livekit.md): 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.
- [Connect a VoIP provider](https://thunderphone.com/docs/guides/voip-providers.md): Bring numbers you already own: guided Telnyx setup, direct Twilio/Telnyx credentials, or any SIP trunk via manual configuration.
- [AI reports](https://thunderphone.com/docs/guides/reports.md): Ask questions in plain English and get a report built from your actual call transcripts — funnels, drop-offs, and answers.
- [Observability](https://thunderphone.com/docs/guides/observability.md): Runtime metrics for your agents — volume, success rate, failures, and the calls behind every number.
- [Experiments (A/B testing)](https://thunderphone.com/docs/guides/experiments-ab-testing.md): Run two agent configurations side by side on real calls and let the success rates pick the winner.
- [Issues](https://thunderphone.com/docs/guides/issues.md): Recurring call problems, grouped into patterns you can triage — and fix with AI help.
- [Alerts](https://thunderphone.com/docs/guides/alerts.md): Threshold rules on your call metrics — delivered to email, Slack, or your webhooks the moment something slips.
- [Organization settings reference](https://thunderphone.com/docs/guides/organization-settings.md): Manage a ThunderPhone organization: profile, dashboard language, members, outbound confirmation, webhooks, SSO, API keys, alerts, billing, spending limits, and history.
- [Invite your team](https://thunderphone.com/docs/guides/invite-your-team.md): Add teammates to your ThunderPhone organization, choose the role that controls what each member can see and do, and manage invitations and existing members.
- [Create a server API key](https://thunderphone.com/docs/guides/api-keys.md): 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.
- [Account & security](https://thunderphone.com/docs/guides/account-and-security.md): Your profile, profile picture, passkeys, and the macOS desktop app — everything on the My account page.
- [Enterprise SSO](https://thunderphone.com/docs/guides/sso.md): 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.
- [Call recording consent laws](https://thunderphone.com/docs/guides/recording-consent-laws.md): Why the recording announcement exists, what the law requires in different places, and what your organization takes on if you turn the announcement off.
- [Outbound calling compliance](https://thunderphone.com/docs/guides/outbound-calling-laws.md): What the TCPA and similar laws require before your agents place outbound calls, and what the one-time confirmation in the dashboard means.
- [Handle inbound calls (API)](https://thunderphone.com/docs/guides/handle-inbound-calls.md): End-to-end: configure an agent, assign it to a phone number, take a call, and inspect the transcript.
- [Place outbound calls (API)](https://thunderphone.com/docs/guides/place-outbound-calls.md): Trigger an AI-driven outbound call from your own code — survey, follow-up, or confirmation flows.
- [Embed the web widget](https://thunderphone.com/docs/guides/embed-web-widget.md): 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.
- [Bring your own numbers (VoIP, API)](https://thunderphone.com/docs/guides/bring-your-own-numbers.md): Connect Twilio or Telnyx — or any SIP trunk — import the phone numbers you already own, and let ThunderPhone agents answer and place calls on them.
- [Dynamic per-call configuration](https://thunderphone.com/docs/guides/dynamic-call-config.md): Pick the answering agent — or rewrite its prompt and settings — separately for every incoming call, driven by custom logic in a webhook you control.
- [Per-call variables](https://thunderphone.com/docs/guides/call-variables.md): Personalize a saved agent for each call without changing its deployed prompt, tools, or settings.
- [Build a tool integration (API)](https://thunderphone.com/docs/guides/build-tool-integration.md): Let your agent call your APIs mid-conversation — search a database, create a ticket, look up an order.
- [Test an agent end-to-end (API)](https://thunderphone.com/docs/guides/test-agents.md): Run one-shot simulations, parallel scenario batches, and release-gate suites through the ThunderPhone API so agent regressions are caught before customers hear them.
- [Verify webhook signatures](https://thunderphone.com/docs/guides/verify-webhook-signatures.md): Every webhook and tool request ThunderPhone sends is signed. Verify the signature once with the recipe here, then reuse the same check on every endpoint you run.
- [Authentication](https://thunderphone.com/docs/api-reference/introduction.md): 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.
- [Organizations](https://thunderphone.com/docs/api-reference/organizations.md): List, create, update, and delete the organizations that own your agents, phone numbers, and billing, including the legacy single-URL webhook configuration.
- [Members](https://thunderphone.com/docs/api-reference/members.md): List members, update roles, transfer ownership, and leave an organization.
- [Invites](https://thunderphone.com/docs/api-reference/invites.md): 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.
- [Onboarding](https://thunderphone.com/docs/api-reference/onboarding.md): Read and manage your organization
- [Client Portals](https://thunderphone.com/docs/api-reference/client-portals.md): Create and administer branded client portals over the ThunderPhone API, including agent scope, viewers, logos, custom domains, and DNS verification.
- [Agents](https://thunderphone.com/docs/api-reference/agents.md): Create and manage voice agents over REST: configure prompts, engines, voices, languages, tools, and knowledge, then deploy, duplicate, transfer, or version them.
- [Agent imports](https://thunderphone.com/docs/api-reference/agent-imports.md): Bring agents, tools, and knowledge bases over from Vapi, Retell, ElevenLabs Agents, or Bland with an API key or a pasted JSON export.
- [Voices](https://thunderphone.com/docs/api-reference/voices.md): Every ThunderPhone voice, with a playable sample.
- [Custom voices](https://thunderphone.com/docs/api-reference/custom-voices.md): Request access, clone a voice, track its lifecycle, and use it on an agent.
- [Voice samples](https://thunderphone.com/docs/api-reference/voice-samples.md): Generate a spoken sample of any voice from your own text.
- [Split Testing](https://thunderphone.com/docs/api-reference/split-testing.md): A/B test agent variants on live traffic and compare per-variant outcomes.
- [Knowledge](https://thunderphone.com/docs/api-reference/knowledge-bases.md): Upload documents, search them semantically, and ground your agents in your own content.
- [App Connections](https://thunderphone.com/docs/api-reference/provider-connections.md): Connect Google Calendar, Sheets, Slack, HubSpot, Salesforce, and Cal.com, and control which tools each agent may use.
- [MCP Servers](https://thunderphone.com/docs/api-reference/mcp-servers.md): Attach remote MCP tool servers to your agents, and use ThunderPhone itself as an MCP server.
- [Phone Numbers](https://thunderphone.com/docs/api-reference/phone-numbers.md): Provision, assign agents to, transfer, and verify phone numbers.
- [Phone Number Labels](https://thunderphone.com/docs/api-reference/phone-number-labels.md): Attach human-readable labels to external phone numbers so call history, transcripts, and exports show meaningful names instead of raw digits everywhere.
- [Calls](https://thunderphone.com/docs/api-reference/calls.md): 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.
- [Outbound Calls](https://thunderphone.com/docs/api-reference/outbound-calls.md): Trigger an outbound voice call from one of your VoIP numbers.
- [Realtime WebSocket](https://thunderphone.com/docs/api-reference/realtime.md): Exchange live call audio, transcripts, and call-control events over one WebSocket.
- [Mic Sessions](https://thunderphone.com/docs/api-reference/mic-sessions.md): 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.
- [Campaigns](https://thunderphone.com/docs/api-reference/campaigns.md): Run outbound calling campaigns: upload contacts, set calling windows, and track outcomes.
- [Issue Reports](https://thunderphone.com/docs/api-reference/issue-reports.md): Org-wide feed of issue reports filed against calls.
- [Investigations](https://thunderphone.com/docs/api-reference/investigations.md): AI-assisted root-cause analysis: generate hypotheses and prompt fixes for recurring call issues, test them, and apply the winner.
- [Simulations](https://thunderphone.com/docs/api-reference/test-calls.md): 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.
- [Test Scenarios & Suites](https://thunderphone.com/docs/api-reference/test-scenarios.md): Saved regression scenarios, AI scenario generation, condition-matrix runs, and release-gate suites.
- [Validation Sets](https://thunderphone.com/docs/api-reference/validation-sets.md): Frozen real-call turns replayed against your draft configuration, graded automatically before you deploy.
- [Billing](https://thunderphone.com/docs/api-reference/billing.md): Inspect your prepaid balance, top up by card, configure auto-reload thresholds and amounts, and list every transaction behind your organization
- [API Keys](https://thunderphone.com/docs/api-reference/developer-api-keys.md): 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.
- [Publishable Keys](https://thunderphone.com/docs/api-reference/publishable-keys.md): 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.
- [VoIP Connections](https://thunderphone.com/docs/api-reference/voip-connections.md): Bring your own phone numbers into ThunderPhone from Twilio, Telnyx, SignalWire, or Vonage: create VoIP connections, verify credentials, and manage imported numbers.
- [Integrations](https://thunderphone.com/docs/api-reference/integrations.md): Define reusable HTTP tool integrations with endpoint, auth, and parameter schemas that any of your agents can call mid-conversation to reach external systems.
- [Embeddable Voice Widget](https://thunderphone.com/docs/widget/overview.md): Add a voice AI agent to any website with a few lines of code
- [React Component](https://thunderphone.com/docs/widget/react.md): Embed the ThunderPhone voice widget in a React application
- [Headless Hook](https://thunderphone.com/docs/widget/headless-hook.md): Build a fully custom voice UI with the useThunderPhone React hook
- [CDN / Script Tag](https://thunderphone.com/docs/widget/cdn-script-tag.md): Add the ThunderPhone voice widget to any website without a bundler
- [Styling](https://thunderphone.com/docs/widget/styling.md): Customize the appearance of the ThunderPhone voice widget with CSS
- [Webhooks Overview](https://thunderphone.com/docs/webhooks/overview.md): How ThunderPhone delivers real-time events, how to verify signatures, and how the legacy and endpoint-based delivery models compare.
- [Webhook Endpoints](https://thunderphone.com/docs/webhooks/endpoints.md): Manage multiple webhook URLs with per-endpoint secrets and event filters.
- [Events Catalog](https://thunderphone.com/docs/webhooks/events.md): All webhook event types ThunderPhone emits.
- [telephony.incoming / web.incoming](https://thunderphone.com/docs/webhooks/call-incoming.md): Blocking webhook that shapes an inbound call
- [telephony.complete / web.complete](https://thunderphone.com/docs/webhooks/call-complete.md): Non-blocking webhook delivered when a call ends, with transcript, recording URL, and metrics.
- [Function Tools](https://thunderphone.com/docs/tools/overview.md): Give your AI agents function tools that call external APIs mid-conversation — fetch customer data, book appointments, update records — with typed parameters.

## Other languages

- [ar](https://thunderphone.com/ar/docs)
- [bg](https://thunderphone.com/bg/docs)
- [bn](https://thunderphone.com/bn/docs)
- [cs](https://thunderphone.com/cs/docs)
- [da](https://thunderphone.com/da/docs)
- [de](https://thunderphone.com/de/docs)
- [el](https://thunderphone.com/el/docs)
- [es](https://thunderphone.com/es/docs)
- [et](https://thunderphone.com/et/docs)
- [fi](https://thunderphone.com/fi/docs)
- [fr](https://thunderphone.com/fr/docs)
- [gu](https://thunderphone.com/gu/docs)
- [he](https://thunderphone.com/he/docs)
- [hi](https://thunderphone.com/hi/docs)
- [hr](https://thunderphone.com/hr/docs)
- [hu](https://thunderphone.com/hu/docs)
- [id](https://thunderphone.com/id/docs)
- [it](https://thunderphone.com/it/docs)
- [ja](https://thunderphone.com/ja/docs)
- [kn](https://thunderphone.com/kn/docs)
- [ko](https://thunderphone.com/ko/docs)
- [lt](https://thunderphone.com/lt/docs)
- [lv](https://thunderphone.com/lv/docs)
- [ml](https://thunderphone.com/ml/docs)
- [mr](https://thunderphone.com/mr/docs)
- [nb](https://thunderphone.com/nb/docs)
- [nl](https://thunderphone.com/nl/docs)
- [pa](https://thunderphone.com/pa/docs)
- [pl](https://thunderphone.com/pl/docs)
- [pt](https://thunderphone.com/pt/docs)
- [ro](https://thunderphone.com/ro/docs)
- [ru](https://thunderphone.com/ru/docs)
- [sk](https://thunderphone.com/sk/docs)
- [sl](https://thunderphone.com/sl/docs)
- [sr](https://thunderphone.com/sr/docs)
- [sv](https://thunderphone.com/sv/docs)
- [sw](https://thunderphone.com/sw/docs)
- [ta](https://thunderphone.com/ta/docs)
- [te](https://thunderphone.com/te/docs)
- [th](https://thunderphone.com/th/docs)
- [tr](https://thunderphone.com/tr/docs)
- [uk](https://thunderphone.com/uk/docs)
- [ur](https://thunderphone.com/ur/docs)
- [vi](https://thunderphone.com/vi/docs)
- [yue](https://thunderphone.com/yue/docs)
- [zh](https://thunderphone.com/zh/docs)
- [zh-Hant](https://thunderphone.com/zh-Hant/docs)