Developer cookbook

Håndter indgående opkald (API)

Fra start til slut: Konfigurer en agent, tildel den til et telefonnummer, modtag et opkald, og gennemgå transskriptionen.

Det kanoniske "besvar en telefon med AI"-flow fra din terminal. Du skal:

1. Oprette en agent med en prompt og en stemme.
2. Klargøre (eller medbringe) et telefonnummer og tildele agenten som håndtering af indgående opkald.
3. Ringe til nummeret. Se opkaldsloggen, transskriptionen og optagelsen.

Samlet antal API-kald: fire. Samlet tid: under fem minutter.

1. Opret en agent#

En agent samler prompten, stemmen og produktniveauet, der driver opkaldet. Se Agenter for alle konfigurationsfelter; minimumskravet er:

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

Gem det returnerede id — du skal bruge det i trin 2.

2. Få et telefonnummer#

Hvis du blot har brug for noget, du kan ringe til, kan du klargøre et demonummer fra ThunderPhones pulje:

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 indeholder et id og et number i E.164. Demonumre starter med status="provisioning" og bliver active inden for få sekunder — foretag gentagne forespørgsler til GET /v1/phone-numbers/{id} for at følge overgangen, hvis du har brug for det.

3. Tildel agenten#

Tilknyt agenten fra trin 1 til nummerets indgående trafik:

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

Det var det — nummeret er aktivt. Du kan også angive outbound_agent_id i samme PATCH, så nummeret også er klar til at foretage udgående opkald.

4. Tag et opkald#

Ring til nummeret fra din telefon. Agenten besvarer opkaldet, præsenterer sig selv i henhold til din prompt, og samtalen begynder.

Mens opkaldet er i gang, vises det i GET /v1/calls med status="in_progress". Når det slutter, opdateres posten med end_reason, duration_seconds, billable_minutes og (efterhånden) en optagelses-URL og AI-bedømmelse.

5. Gennemgå resultaterne#

Hent listen over seneste opkald:

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

Hent transskriptionen:

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

Og optagelses-URL'en (kortvarig, signeret):

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

Hvis du abonnerer på telephony.complete webhook, modtager du de samme data som en POST-anmodning til din server — se call.complete.

Næste trin#