Håndter indgående opkald (API)

End-to-end: konfigurer en agent, tildel den til et telefonnummer, tag imod et opkald, og gennemse transskriptionen.

Det kanoniske forløb til at "besvare en telefon med en AI", 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 den prompt, stemme og det produktniveau, der skal håndtere opkaldet. Du kan også angive opkaldsgrænser som max_call_duration_seconds og ring_duration_seconds på agenten. Agenter understøtter også intro_clip og intro_ring_count til at afspille en forudindspillet introduktion og op til to ringninger, før agenten taler. Nye agenter skal også have en tidszone. Hvis din agent er flersproget, kan du angive language_switching for at styre, om den spørger, før den skifter sprog, eller følger opkalderens sprog. Se Agenter for alle konfigurationsfelter; det mindste nødvendige 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 at ringe til, kan du få et ThunderPhone-nummer 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-format. ThunderPhone- numre starter med status="provisioning" og bliver active inden for få sekunder — forespørg GET /v1/phone-numbers/{id} for at følge overgangen, hvis det er relevant.

3. Tildel agenten#

Knyt agenten fra trin 1 til nummerets indgående retning:

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 er det — nummeret er aktivt. Når udgående opkald er godkendt for din organisation, kan du også angive outbound_agent_id i samme PATCH. Indtil da afviser API'et denne tildeling med 400.

Hvis du dirigerer indgående opkald via en konfigurationswebhook i stedet for et fast inbound_agent_id, kan webhooken nu returnere en timezone pr. opkald sammen med agent_id og variables.

4. Tag imod et opkald#

Ring til nummeret fra din telefon. Agenten tager telefonen, præsenterer sig 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 (med tiden) en optagelses-URL og AI-bedømmelse.

Indgående opkald tæller med i din organisations samtidige opkaldsgrænse (20 opkald i gang som standard, delt med udgående opkald, web- og test- opkald). Et opkald, der ankommer ved grænsen, afvises og lægges på, før agenten svarer, faktureres ikke og registreres som et mislykket opkald med afslutningsårsagen concurrent_call_limit_reached. Send en e-mail til support@thunderphone.com, hvis du har brug for en højere grænse.

5. Gennemse 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 har abonneret på telephony.complete-webhooken, modtager du de samme data som en POST til din server — se call.complete.

Hvis din agent har konfigurerede udtræksfelter, kan payloaden for det afsluttede opkald også indeholde strukturerede udtrukne data.

Næste trin#