Gestionați apelurile primite (API)

De la început până la final: configurați un agent, atribuiți-l unui număr de telefon, preluați un apel și examinați transcrierea.

Fluxul canonic „răspundeți la telefon cu ajutorul AI”, din terminalul dumneavoastră. Veți:

1. Crea un agent cu un prompt și o voce.
2. Furniza (sau aduce) un număr de telefon și atribui agentul ca gestionarul său pentru apelurile primite.
3. Apela numărul. Consulta jurnalul apelului, transcrierea și înregistrarea.

Număr total de apeluri API: patru. Timp total: sub cinci minute.

1. Creați un agent#

Un agent reunește promptul, vocea și nivelul de produs care vor gestiona apelul. De asemenea, puteți seta limite pentru apel, precum max_call_duration_seconds și ring_duration_seconds, pentru agent. Agenții acceptă și intro_clip și intro_ring_count pentru a reda o introducere preînregistrată și până la două sonerii înainte ca agentul să vorbească. Agenții noi au nevoie și de un fus orar. Dacă agentul dumneavoastră este multilingv, puteți seta language_switching pentru a controla dacă întreabă înainte de a schimba limba sau urmează limba apelantului. Consultați Agenți pentru toate câmpurile de configurare; valoarea minimă este:

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

Salvați id returnat — veți avea nevoie de el la pasul 2.

2. Obțineți un număr de telefon#

Dacă aveți nevoie doar de un număr pe care să îl apelați, obțineți un număr ThunderPhone din grupul de numere ThunderPhone:

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

Răspunsul include un id și un number în format E.164. Numerele ThunderPhone încep cu status="provisioning" și devin active în câteva secunde — interogați GET /v1/phone-numbers/{id} pentru a monitoriza tranziția, dacă este relevant pentru dumneavoastră.

3. Atribuiți agentul#

Asociați agentul de la pasul 1 cu direcția de apeluri primite a numărului:

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

Atât — numărul este activ. După aprobarea apelării inițiate pentru organizația dumneavoastră, puteți seta și outbound_agent_id în același PATCH. Până atunci, API-ul respinge această atribuire cu 400.

Dacă direcționați apelurile primite printr-un webhook de configurare în loc de un inbound_agent_id fix, acel webhook poate returna acum un timezone pentru fiecare apel, împreună cu agent_id și variables.

4. Preluați un apel#

Apelați numărul de pe telefonul dumneavoastră. Agentul răspunde, se prezintă conform promptului dumneavoastră, iar conversația începe.

În timpul apelului, acesta apare în GET /v1/calls cu status="in_progress". Când se încheie, înregistrarea se actualizează cu end_reason, duration_seconds, billable_minutes și, în cele din urmă, un URL pentru înregistrare și un scor AI.

Apelurile primite se iau în calcul pentru limita de apeluri simultane a organizației dumneavoastră (implicit, 20 de apeluri în desfășurare, partajate cu apelurile efectuate, web și de test). Un apel care ajunge când limita este atinsă este refuzat înainte ca agentul să răspundă și este închis, nu este facturat și este înregistrat ca apel eșuat cu motivul de încheiere concurrent_call_limit_reached. Trimiteți un e-mail la support@thunderphone.com dacă aveți nevoie de o limită mai mare.

5. Inspectați rezultatele#

Preluați lista apelurilor recente:

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

Preluați transcrierea:

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

Și URL-ul înregistrării (semnat, cu valabilitate scurtă):

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

Dacă v-ați abonat la webhook-ul telephony.complete, veți primi aceleași date printr-un POST către serverul dumneavoastră — consultați call.complete.

Dacă agentul dumneavoastră are configurate câmpuri de extracție, încărcătura utilă a apelului finalizat poate include și date extrase structurate.

Pașii următori#