Håndter innkommende samtaler (API)

Fra start til slutt: konfigurer en stemmeagent, tildel den til et telefonnummer, motta en samtale og se gjennom transkripsjonen.

Den kanoniske flyten for å «svare på en telefon med KI», fra terminalen din. Du skal:

1. Opprette en agent med en prompt og stemme.
2. Klargjøre (eller ta med) et telefonnummer og tilordne agenten som innkommende behandler.
3. Ringe nummeret. Se anropsloggen, transkripsjonen og opptaket.

Totalt antall API-kall: fire. Total tid: under fem minutter.

1. Opprett en agent#

En agent samler prompten, stemmen og produktnivået som skal håndtere samtalen. Du kan også angi samtalegrenser som max_call_duration_seconds og ring_duration_seconds på agenten. Agenter støtter også intro_clip og intro_ring_count for å spille av en forhåndsinnspilt introduksjon og opptil to ring før agenten snakker. Nye agenter trenger også en tidssone. Se Agenter for alle konfigurasjonsfeltene; det minste som kreves, 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"
  }'

Lagre den returnerte id-en — du trenger den i trinn 2.

2. Skaff et telefonnummer#

Hvis du bare trenger noe å ringe til, kan du få et ThunderPhone-nummer fra ThunderPhone-poolen:

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

Responsen inneholder en id og et number i E.164-format. ThunderPhone- numre starter med status="provisioning" og blir active i løpet av noen få sekunder — hent GET /v1/phone-numbers/{id} for å følge overgangen hvis du trenger det.

3. Tilordne agenten#

Knytt agenten fra trinn 1 til nummerets innkommende 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 var det — nummeret er aktivt. Etter at utgående oppringing er godkjent for organisasjonen din, kan du også angi outbound_agent_id i samme PATCH. Inntil da avviser API-et denne tilordningen med 400.

Hvis du ruter innkommende anrop gjennom en konfigurasjonswebhook i stedet for en fast inbound_agent_id, kan denne webhooken nå returnere en timezone per samtale sammen med agent_id og variables.

4. Ta imot et anrop#

Ring nummeret fra telefonen din. Agenten svarer, introduserer seg i henhold til prompten din, og samtalen begynner.

Mens anropet pågår, vises det i GET /v1/calls med status="in_progress". Når det avsluttes, oppdateres posten med end_reason, duration_seconds, billable_minutes og etter hvert en opptaks-URL og en KI-vurdering.

Innkommende samtaler teller mot organisasjonens grense for samtidige samtaler (20 samtaler pågår som standard, delt med utgående samtaler, nett- og test- samtaler). En samtale som kommer inn når grensen er nådd, avvises før agenten svarer og legges på, faktureres ikke og registreres som en mislykket samtale med avslutningsårsaken concurrent_call_limit_reached. Send e-post til support@thunderphone.com hvis du trenger en høyere grense.

5. Se gjennom resultatene#

Hent listen over nylige samtaler:

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

Hent transkripsjonen:

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

Og URL-en til opptaket (kortvarig, signert):

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

Hvis du abonnerte på telephony.complete-webhooken, mottar du de samme dataene som en POST til serveren din — se call.complete.

Hvis agenten din har konfigurert utvinningsfelt, kan nyttelasten for den fullførte samtalen også inneholde strukturerte utvunnede data.

Neste steg#