Developer cookbook

Inkomende oproepen afhandelen (API)

Van begin tot eind: configureer een agent, koppel deze aan een telefoonnummer, neem een oproep aan en bekijk het transcript.

De standaardflow voor "een telefoon opnemen met AI", vanuit je terminal. Je gaat:

1. Een agent maken met een prompt en stem.
2. Een telefoonnummer provisionen (of meenemen) en de agent toewijzen als inkomende afhandelaar.
3. Het nummer bellen. Bekijk het oproeplogboek, transcript en de opname.

Totaal aantal API-aanroepen: vier. Totale tijd: minder dan vijf minuten.

1. Maak een agent#

Een agent bundelt de prompt, stem en het productpakket die het gesprek aansturen. Zie Agents voor elk configuratieveld; het 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"
  }'

Sla de geretourneerde id op — je hebt die nodig in stap 2.

2. Vraag een telefoonnummer aan#

Als je alleen een nummer nodig hebt om naartoe te bellen, provision dan een demonummer uit de pool van ThunderPhone:

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"}'

Het antwoord bevat een id en een number in E.164. Demonummers starten met status="provisioning" en worden binnen enkele seconden active — poll GET /v1/phone-numbers/{id} om de overgang te volgen als dat belangrijk voor je is.

3. Wijs de agent toe#

Koppel de agent uit stap 1 aan de inkomende afhandeling van het nummer:

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}'

Dat is alles — het nummer is actief. Je kunt ook outbound_agent_id instellen in dezelfde PATCH, zodat het nummer ook klaar is om uitgaande oproepen te doen.

4. Neem een oproep aan#

Bel het nummer vanaf je telefoon. De agent neemt op, stelt zich voor volgens je prompt en het gesprek begint.

Terwijl het gesprek bezig is, verschijnt het in GET /v1/calls met status="in_progress". Wanneer het eindigt, wordt het record bijgewerkt met end_reason, duration_seconds, billable_minutes en (uiteindelijk) een opname-URL en AI-beoordeling.

5. Controleer de resultaten#

Haal de lijst met recente oproepen op:

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

Haal het transcript op:

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

En de opname-URL (tijdelijk, ondertekend):

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

Als je geabonneerd bent op de telephony.complete webhook, ontvang je dezelfde gegevens als een POST naar je server — zie call.complete.

Volgende stappen#