Skip to main content
Building your first agent by hand? The dashboard walks this exact flow — build the agent, add a number, simulate, review — with a guided wizard. Start at the dashboard quickstart.
The canonical “answer a phone with an AI” flow, from your terminal. You’ll:
  1. Create an agent with a prompt and voice.
  2. Provision (or bring) a phone number and assign the agent as its inbound handler.
  3. Call the number. Observe the call log, transcript, and recording.
Total API calls: four. Total time: under five minutes.

​
1. Create an agent

An agent bundles the prompt, voice, and product tier that will drive the call. See Agents for every configuration field; the minimum is:
Save the returned id — you’ll need it in step 2.
Pick spark for simple Q&A at the lowest cost, bolt when speed matters most. Upgrade to storm-base-with-ack when your prompt needs deeper reasoning and can tolerate a half-second filler while the model thinks. See product tiers.

​
2. Get a phone number

If you just need something to dial against, provision a demo number from ThunderPhone’s pool:
The response includes an id and a number in E.164. Demo numbers start in status="provisioning" and become active within a few seconds — poll GET /v1/phone-numbers/{id} to watch the transition if you care.
For production, skip demo numbers and bring your own numbers via VoIP. Demo numbers are inbound-only and capped in volume.

​
3. Assign the agent

Associate the agent from step 1 with the number’s inbound direction:
That’s it — the number is live. You can also set outbound_agent_id in the same PATCH so the number is ready to call outbound too.

​
4. Take a call

Dial the number from your phone. The agent picks up, introduces itself per your prompt, and the conversation begins. While the call is in flight, it appears in GET /v1/calls with status="in_progress". When it ends, the record updates with end_reason, duration_seconds, billable_minutes, and (eventually) a recording URL and AI grade.

​
5. Inspect the results

Fetch the list of recent calls:
Grab the transcript:
And the recording URL (short-lived, signed):
If you subscribed to the telephony.complete webhook you’ll receive the same data as a POST to your server — see call.complete.

​
Next steps

Dynamic per-call config

Pick a different agent per caller based on the phone number or custom logic in a webhook.

Add tool integrations

Let the agent call your APIs mid-conversation.

Receive call.complete webhooks

Stream each finished call to your CRM / analytics pipeline.

AI grading and issue reports

Score every call automatically and route flagged ones for review.