Developer cookbook

Gestionați apelurile primite (API)

De la început până la sfârșit: configurați un agent, alocați-l unui număr de telefon, preluați un apel și inspectați transcrierea.

Fluxul canonic „răspunde la telefon cu un 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 gestionar pentru apelurile primite.
3. Apela numărul. Observa jurnalul apelului, transcrierea și înregistrarea.

Total 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. Consultați Agenți pentru toate câmpurile de configurare; minimul 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 ceva pe care să îl apelați, furnizați un număr demo 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 demo pornesc cu status="provisioning" și devin active în câteva secunde — interogați GET /v1/phone-numbers/{id} pentru a urmări tranziția, dacă vă interesează.

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. Puteți seta și outbound_agent_id în același PATCH, astfel încât numărul să fie pregătit și pentru apeluri efectuate.

4. Preluați un apel#

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

În timp ce apelul este în desfășurare, 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 de înregistrare și evaluarea AI.

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 (cu durată scurtă de viață, semnat):

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

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

Pașii următori#