Efectuați apeluri de ieșire (API)

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

Apelați o listă întreagă? Funcționalitatea Campanii din tabloul de bord (/dashboard/campaigns) preia un CSV cu contacte și gestionează pentru dumneavoastră ferestrele de apelare adaptate la fusul orar, concurența și politica de reîncercare. Acest ghid acoperă apelurile programatice individuale.

Cerințe preliminare

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.

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ă).

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

status: "initiated" înseamnă doar că solicitarea a fost acceptată — apelul nu este încă conectat. Interogați GET /v1/calls/{call_id} pentru starea în timp real (in_progress → completed / failed).

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

Eroare	Remediere
`402 Payment Required`	Alimentați soldul sau activați reîncărcarea automată
apelare de ieșire `403` blocată (număr demo)	Aduceți în schimb un număr VoIP
apelare de ieșire `403` blocată (VoIP neverificat)	Rulați `POST /v1/phone-numbers/{id}/verify-voip`
`404 from_number is not registered to this organization`	Confirmați că `from_number` corespunde unui număr de telefon pe care îl dețineți
`502 Bad Gateway`	Eroare SIP / LiveKit temporară; puteți reîncerca în siguranță

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

Referință pentru apeluri outbound

Fiecare câmp din solicitare și fiecare cod de eroare.

Primiți call.complete

Transmiteți apelurile outbound finalizate către sistemul dumneavoastră.

Facturare

Reîncărcare automată, astfel încât apelurile outbound să nu eșueze din cauza soldului.

Testați agenții outbound

Testați agentul outbound înainte de producție.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

Efectuați apeluri de ieșire (API)

Cerințe preliminare

Plasați un apel cu un agent salvat

Plasați un apel cu configurație inline

Urmăriți apelul

Moduri de eșec care merită gestionate

Controlul timpului de așteptare

Pașii următori

Referință pentru apeluri outbound

Primiți call.complete

Facturare

Testați agenții outbound

​Cerințe preliminare

​Plasați un apel cu un agent salvat

​Plasați un apel cu configurație inline

​Urmăriți apelul

​Moduri de eșec care merită gestionate

​Controlul timpului de așteptare

​Pașii următori

Referință pentru apeluri outbound

Primiți call.complete

Facturare

Testați agenții outbound

Cerințe preliminare

Plasați un apel cu un agent salvat

Plasați un apel cu configurație inline

Urmăriți apelul

Moduri de eșec care merită gestionate

Controlul timpului de așteptare

Pașii următori