Skip to main content
ThunderPhone is built around six primitives. Everything the API lets you do is some combination of these. Skim the list, then drill into whichever one is relevant to what you’re building.

Organizations

Top-level tenant. Owns every other resource.

Agents

The configuration that drives each call — prompt, voice, tier.

Phone numbers

Inbound / outbound endpoints tied to an agent.

Calls

One real conversation. Has a transcript, recording, grade, and bill.

Web widget

Browser-mic version of a call, keyed to a publishable key.

Webhooks

Real-time events ThunderPhone sends to your server.

​
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 from the dashboard 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. You’ll use:

​
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.
  • A voice for text-to-speech output.
  • A product tier (spark, bolt, storm-*) that trades latency for reasoning quality — see the product tier table.
  • Optional tool integrations — reusable HTTP calls the agent can make mid-conversation.
  • Optional behavior knobs: speak order, acknowledgement-prompt mode, background track, hold timeout.
One agent can be reused across many phone numbers and widget instances. Updates are versioned: every PATCH records a snapshot under GET /v1/agents/{id}/versions. You’ll use:

​
Phone numbers

A phone number belongs to an org and has an inbound agent and/or an outbound agent assigned. Inbound calls to the number are routed to the inbound agent; outbound calls placed from the number use the outbound agent by default. Two sources exist:
  • Demo numbers — provisioned by ThunderPhone for inbound use only. Good for smoke tests and trials. Demo numbers can’t place outbound calls.
  • VoIP numbers — brought from your own provider (Twilio, Telnyx, SignalWire, Vonage, or any SIP trunk) via a VoIP connection. Once imported and verified, they support inbound and outbound.
Assignments are versioned in the same way as agents — see GET /v1/phone-numbers/{id}/versions. You’ll use:

​
Calls

Every inbound call, outbound call, mic session, and widget session becomes a call log record. A call log carries:
  • call_id — stable across every event for this call.
  • direction — inbound, outbound, mic, or widget.
  • The snapshotted agent config (prompt, voice, product).
  • Full transcript (role-tagged), full structured turn history (including function calls and interruption markers), and a time- limited signed URL to the MP3 recording.
  • Billing total in cents and billable minutes.
  • Optional AI quality grade (score, call_outcome, detected_issues).
  • Optional issue reports filed by humans or by grading.
Calls transition through in_progress → completed or failed. On completion, ThunderPhone can optionally fire a call.complete webhook. You’ll use:

​
Web widget

The web widget is an embeddable JavaScript / React component that gives your site visitors a mic-based conversation with an agent — no phone number needed. It authenticates to ThunderPhone with a publishable key (pk_live_...) that’s origin-locked via an allowed-domain list, so it’s safe to ship in client-side code. Publishable keys run in one of two modes:
  • mode="agent" — the key is statically bound to one agent. Easiest setup.
  • mode="webhook" — the widget calls your call.incoming webhook per visitor to dynamically choose an agent. Use this for customer-specific or session-aware routing.
Everything else about the widget session (transcript, recording, grading, billing) flows through the exact same call infrastructure as a phone call — just with direction="widget" or direction="mic" on the call log. You’ll use:

​
Webhooks

ThunderPhone sends HTTP POST webhooks to your server when things happen during and after a call. There are 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 receives every event. Managed at /v1/webhook. Kept for backward compatibility.
Events split into two classes:
  • Blocking events expect your server to respond with configuration that shapes the in-flight call. Only call.incoming is blocking; you have ~2 seconds to respond.
  • Non-blocking events are fire-and-forget. We retry on non-2xx with exponential backoff for 24 hours.
Every request carries an HMAC-SHA256 signature in X-ThunderPhone-Signature. See Signature verification. You’ll use:

​
Tool integrations

A tool integration is a reusable HTTP endpoint an agent can call during a conversation. You give ThunderPhone:
  1. An OpenAI-style function schema ({type: "function", function: {...}}).
  2. An endpoint URL + method + headers to call when the agent invokes it.
At runtime the agent decides when to call the tool based on the schema; ThunderPhone performs the HTTP request from its servers (signed with the webhook secret), waits for the response, and hands the result back to the agent. You can either attach tools inline to an agent’s tools field (for one-off use) or save reusable ones as /v1/integrations and link them to multiple agents via integration_ids. You’ll use:

​
Billing

ThunderPhone is prepaid. Each org carries a USD balance; every call debits the balance at the product tier’s per-minute rate. When balance reaches $0.00, inbound calls are rejected and outbound calls return 402 Payment Required. You can top up manually via POST /v1/billing/top-up or configure automatic reloads at a balance threshold. You’ll use:
  • /v1/billing — balance, auto-reload, transaction history.

​
Putting it together

Handle inbound calls

The canonical “answer a phone call with an AI” flow.

Place outbound calls

Programmatic outbound calling from your own code.

Embed the web widget

Drop an agent onto your marketing or support site.

Bring your own numbers (VoIP)

Connect Twilio / Telnyx / SignalWire / Vonage and import numbers.

Dynamic per-call config

Pick an agent or rewrite a prompt per incoming call via webhook.

Build a tool integration

Give your agent an HTTP superpower.

Test an agent end-to-end

Use the test-calls API to run batches of canned scenarios.

Verify webhook signatures

Get the HMAC check right once and reuse everywhere.