Hantera inkommande samtal (API)

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

Det kanoniska flödet för att "svara i telefon med en 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 dess inkommande hanterare.
3. Ringa numret. Granska samtalsloggen, transkriberingen 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 ska hantera samtalet. Du kan också ange samtalsgränser som max_call_duration_seconds och ring_duration_seconds för agenten. Agenter har även stöd för intro_clip och intro_ring_count för att spela upp en förinspelad introduktion och upp till två signaler innan agenten talar. Nya agenter behöver också en tidszon. Om din agent är flerspråkig kan du ange language_switching för att styra om den frågar innan den byter språk eller följer uppringarens språk. Se Agenter för alla konfigurationsfält; det minsta som krävs ä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, skaffa ett ThunderPhone-nummer 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. ThunderPhone- nummer börjar med status="provisioning" och blir active inom några sekunder — polla GET /v1/phone-numbers/{id} 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. När utgående samtal har godkänts för din organisation kan du även ange outbound_agent_id i samma PATCH. Fram till dess avvisar API:et tilldelningen med 400.

Om du dirigerar inkommande samtal via en konfigurationswebhook i stället för ett fast inbound_agent_id, kan den webhooken nu returnera en timezone per samtal tillsammans med agent_id och variables.

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 inspelnings-URL och AI-betyg.

Inkommande samtal räknas mot organisationens gräns för samtidiga samtal (20 pågående samtal som standard, delat med utgående samtal, webb- och test- samtal). Ett samtal som kommer in när gränsen har nåtts nekas innan agenten svarar och kopplas ned, debiteras inte och registreras som ett misslyckat samtal med avslutsorsaken concurrent_call_limit_reached. Mejla support@thunderphone.com om du behöver en högre gräns.

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 (kortvarig, signerad):

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

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

Om din agent har extraheringsfält konfigurerade kan den slutförda samtalsnyttolasten också innehålla strukturerade extraherade data.

Nästa steg#