Developer cookbook

Handle inbound calls (API)

End-to-end: configure an agent, assign it to a phone number, take a call, and inspect the transcript.

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:

curl -X POST https://api.thunderphone.com/v1/agents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":    "Acme Support",
    "prompt":  "You are a friendly support agent for Acme. Help callers with orders and returns. Keep answers short.",
    "voice":   "john",
    "product": "spark"
  }'

Save the returned id — you'll need it in step 2.

2. Get a phone number#

If you just need something to dial against, provision a demo number from ThunderPhone's pool:

curl -X POST https://api.thunderphone.com/v1/phone-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"area_code": "415"}'

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.

3. Assign the agent#

Associate the agent from step 1 with the number's inbound direction:

curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/{phone_id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbound_agent_id": 12}'

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:

curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Grab the transcript:

curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

And the recording URL (short-lived, signed):

curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

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#