> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Handle inbound calls (API)

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

<Note>
  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](/quickstart-dashboard).
</Note>

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](/api-reference/agents) for every configuration
field; the minimum is:

```bash theme={null}
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.

<Tip>
  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](/api-reference/agents#product-tiers-at-a-glance).
</Tip>

## 2. Get a phone number

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

```bash theme={null}
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}`](/api-reference/phone-numbers#retrieve-a-phone-number)
to watch the transition if you care.

<Note>
  For production, skip demo numbers and
  [bring your own numbers via VoIP](/guides/bring-your-own-numbers).
  Demo numbers are inbound-only and capped in volume.
</Note>

## 3. Assign the agent

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

```bash theme={null}
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`](/api-reference/calls#list-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:

```bash theme={null}
curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

Grab the transcript:

```bash theme={null}
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):

```bash theme={null}
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](/webhooks/events#telephony-complete)
you'll receive the same data as a POST to your server — see
[call.complete](/webhooks/call-complete).

***

## Next steps

<CardGroup cols={2}>
  <Card title="Dynamic per-call config" icon="bolt" href="/guides/dynamic-call-config">
    Pick a different agent per caller based on the phone number or
    custom logic in a webhook.
  </Card>

  <Card title="Add tool integrations" icon="screwdriver-wrench" href="/guides/build-tool-integration">
    Let the agent call your APIs mid-conversation.
  </Card>

  <Card title="Receive call.complete webhooks" icon="bolt" href="/webhooks/call-complete">
    Stream each finished call to your CRM / analytics pipeline.
  </Card>

  <Card title="AI grading and issue reports" icon="chart-line" href="/api-reference/calls#ai-call-grading">
    Score every call automatically and route flagged ones for review.
  </Card>
</CardGroup>