Developer cookbook

Hantera inkommande samtal (API)

Från början till slut: konfigurera en röstagent, tilldela den ett telefonnummer, ta emot ett samtal och granska transkriptionen.

Det vanliga flödet för att "svara i telefon med AI", från din terminal. Du kommer att:

1. Skapa en agent med en prompt och röst.
2. Tillhandahålla (eller ta med) ett telefonnummer och tilldela agenten som hanterare för inkommande samtal.
3. Ringa numret. Granska samtalsloggen, transkriptionen och inspelningen.

Totalt antal API-anrop: fyra. Total tid: under fem minuter.

1. Skapa en agent#

En agent samlar prompten, rösten och produktnivån som driver samtalet. Se Agenter för alla konfigurations- fält; minimikravet är:

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

Spara det returnerade id — du behöver det i steg 2.

2. Skaffa ett telefonnummer#

Om du bara behöver något att ringa till kan du tillhandahålla ett demonummer från ThunderPhones 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"}'

Svaret innehåller ett id och ett number i E.164-format. Demonummer startar med status="provisioning" och blir active inom några sekunder — hämta GET /v1/phone-numbers/{id} upprepade gånger för att följa övergången om du behöver.

3. Tilldela agenten#

Koppla agenten från steg 1 till numrets inkommande riktning:

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

Klart — numret är aktivt. Du kan även ange outbound_agent_id i samma PATCH så att numret också är redo att ringa ut.

4. Ta emot ett samtal#

Ring numret från din telefon. Agenten svarar, presenterar sig enligt din prompt och samtalet börjar.

Medan samtalet pågår visas det i GET /v1/calls med status="in_progress". När det avslutas uppdateras posten med end_reason, duration_seconds, billable_minutes och (så småningom) en URL till inspelningen och AI-betyg.

5. Granska resultaten#

Hämta listan över senaste samtal:

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

Hämta transkriptionen:

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

Och inspelnings-URL:en (kortlivad, signerad):

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

Om du prenumererar på webhooken telephony.complete webhook får du samma data som en POST till din server — se call.complete.

Nästa steg#