Efectuați apeluri efectuate (API)

Declanșați un apel efectuat de un agent vocal AI din propriul cod — fluxuri de sondaj, urmărire sau confirmare.

Apelarea outbound vă permite să furnizați ThunderPhone un număr de destinație și o configurație de agent, iar AI-ul efectuează apelul în numele dumneavoastră. Cazuri de utilizare frecvente:

• 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. Alegeți un număr activat pentru apeluri outbound

   Folosiți un număr pe care îl dețineți printr-o conexiune VoIP sau solicitați permisiunea de a utiliza numerele ThunderPhone pentru apeluri outbound din pagina Phone Numbers. Numerele ThunderPhone sunt inițial doar pentru apeluri inbound. ThunderPhone examinează manual fiecare solicitare; după aprobare, aceste numere pot efectua apeluri până la limita zilnică aprobată (care se resetează la 00:00 UTC) și pot rula campanii, iar dumneavoastră puteți solicita o limită mai mare. Numerele VoIP ale clienților nu au limită zilnică, așadar le recomandăm pentru apeluri outbound. Consultați Folosiți propriile numere.

2. Creați un agent

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

3. Mențineți un sold pozitiv

   Apelurile outbound returnează 402 Payment Required dacă soldul este ≤ $0.00. Alimentați contul sau activați reîncărcarea automată în Organizație → Setări de facturare din tabloul de bord. Cheia dumneavoastră sk_live_ poate verifica soldul cu GET /v1/billing, dar nu poate alimenta contul și nu poate modifica reîncărcarea automată.

Efectuați un apel cu un agent salvat#

Cea mai simplă opțiune — faceți referire la un agent după 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":   "+14155552671",
    "agent_id":    12
  }'

Răspuns:

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

Efectuaț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":   "+14155552671",
    "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 webhook-ul telephony.complete — cea mai rapidă modalitate de a afla că un apel s-a încheiat. Dacă nu puteți accepta webhook-uri de intrare, interogați GET /v1/calls/{call_id} la fiecare câteva secunde; înregistrarea include end_reason, duration_seconds și adresa URL a înregistrării după încheierea apelului.

Dacă agentul vocal este configurat să extragă date structurate după apel, aceste date sunt livrate separat după finalizarea procesului.

Transmiteți variabile pentru fiecare apel unui agent salvat#

Agenții salvați pot utiliza substituenți precum {{name}} sau {{name|there}} în textul promptului. Când plasați un apel de ieșire cu agent_id, transmiteți variables cu valorile pentru acel apel:

{
  "from_number": "+[REDACTED_PHONE]",
  "to_number": "+[REDACTED_PHONE]",
  "agent_id": 12,
  "variables": {
    "name": "Jordan"
  }
}

Utilizați valori șir indexate după numele substituentului. Aceste variabile se aplică agenților salvați; exemplul config inclus în acest ghid nu le utilizează.

Moduri de eșec care merită gestionate#

Consultați referința pentru apeluri de ieșire pentru lista completă și stabilă de coduri de eligibilitate, precum și pentru ambele forme de răspuns 409. Dacă un număr activ devine neeligibil după ce solicitarea este acceptată, dar înainte ca apelul să fie plasat, verificarea finală returnează încărcătura utilă 409 care nu poate fi reîncercată.

Controlarea timpului de așteptare#

Apelurile de ieșire care durează mult deoarece destinatarul răspunde lent (arbori IVR, cozi) pot fi limitate cu max_hold_seconds:

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

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

Pașii următori#