Inkomende oproepen afhandelen (API)

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

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

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

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

1. Een agent maken#

Een agent bundelt de prompt, stem en het productpakket die het gesprek aansturen. Je kunt op de agent ook oproeplimieten instellen, zoals max_call_duration_seconds en ring_duration_seconds. Agents ondersteunen ook een intro_clip en intro_ring_count om een vooraf opgenomen intro en maximaal twee beltonen af te spelen voordat de agent spreekt. Nieuwe agents hebben ook een tijdzone nodig. 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. Een telefoonnummer krijgen#

Als je alleen iets nodig hebt om naartoe te bellen, haal dan een ThunderPhone-nummer 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. ThunderPhone- nummers beginnen met status="provisioning" en worden binnen enkele seconden active — voer periodiek GET /v1/phone-numbers/{id} uit om de overgang te volgen als dat relevant is.

3. De agent toewijzen#

Koppel de agent uit stap 1 aan de inkomende richting 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. Nadat uitgaand bellen is goedgekeurd voor je organisatie, kun je ook outbound_agent_id instellen in dezelfde PATCH. Tot die tijd wijst de API die toewijzing af met 400.

Als je inkomende oproepen via een configuratiewebhook routeert in plaats van via een vaste inbound_agent_id, kan die webhook nu per oproep een timezone retourneren, samen met agent_id en variables.

4. Een oproep aannemen#

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.

Inkomende oproepen tellen mee voor de limiet voor gelijktijdige oproepen van je organisatie (standaard 20 oproepen tegelijk, gedeeld met uitgaande, web- en testoproepen). Een oproep die binnenkomt wanneer de limiet is bereikt, wordt geweigerd en opgehangen voordat de agent antwoordt, wordt niet gefactureerd en wordt geregistreerd als een mislukte oproep met als eindreden concurrent_call_limit_reached. Stuur een e-mail naar support@thunderphone.com als je een hogere limiet nodig hebt.

5. Inspecteer 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 geldig, ondertekend):

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

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

Als voor je agent extractievelden zijn geconfigureerd, kan de payload van de voltooide oproep ook gestructureerde geëxtraheerde gegevens bevatten.

Volgende stappen#