Developer cookbook

Efectuați apeluri de ieșire (API)

Declanșați un apel de ieșire gestionat de IA din propriul cod — pentru fluxuri de sondaj, urmărire sau confirmare.

Apelarea de ieșire vă permite să transmiteți către ThunderPhone un număr de destinație și o configurație de agent, iar AI-ul plasează apelul în numele dumneavoastră. Cazuri de utilizare tipice:

• Confirmări de programări
• Apeluri de revenire pentru sondaje
• Urmăriri „la a doua încercare” după un apel pierdut
• Notificări de tip dispecerat

Cerințe preliminare#

1. Aduceți un număr VoIP

   Apelarea de ieșire necesită să dețineți from_number printr-o conexiune VoIP. Numerele demo sunt disponibile doar pentru apeluri de intrare. Consultați Aduceți propriile numere.

2. Creați un agent

   Un prompt orientat către apeluri de ieșire începe, de regulă, cu agentul care se identifică și își precizează scopul — „Bună, sunt Acme și vă sun pentru a confirma programarea de mâine la ora 15:00…” Setați outbound_speak_order la agent_first (valoarea implicită).

3. Păstrați un sold pozitiv

   Apelurile de ieșire returnează 402 Payment Required dacă soldul este ≤ $0.00. Alimentați soldul prin POST /v1/billing/top-up sau activați reîncărcarea automată.

Plasați un apel cu un agent salvat#

Cea mai simplă metodă — faceți referire la un agent prin ID:

curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155550199",
    "agent_id":    12
  }'

Răspuns:

{ "call_id": 987654321, "status": "initiated" }

Plasați un apel cu configurație inline#

Dacă doriți un prompt unic care nu merită salvat ca agent, transmiteți în schimb config. Structura corespunde schemei de răspuns a webhookului call.incoming:

curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155550199",
    "config": {
      "prompt":  "You are confirming Jane Doe appointment for 3pm tomorrow…",
      "voice":   "john",
      "product": "spark"
    }
  }'

Urmăriți apelul#

În paralel, abonați-vă la webhookul telephony.complete — cea mai rapidă modalitate de a afla că un apel s-a încheiat. Dacă nu puteți accepta webhookuri de intrare, interogați GET /v1/calls/{call_id} la fiecare câteva secunde; înregistrarea include end_reason, duration_seconds și URL-ul înregistrării după încheierea apelului.

Moduri de eșec care merită gestionate#

Controlul timpului de așteptare#

Apelurile outbound care durează mult deoarece persoana apelată răspunde lent (arbori IVR, cozi) pot fi limitate cu max_hold_seconds:

{
  "from_number": "+15551234567",
  "to_number":   "+14155550199",
  "agent_id":    12,
  "max_hold_seconds": 120
}

Agentul închide apelul dacă nu a fost primit niciun semnal audio uman în ultimele N secunde. Valoarea implicită este 900 (15 minute).

Pașii următori#