--- title: "Efectuați apeluri efectuate (API)" description: "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 Apelați o listă întreagă? Funcționalitatea [**Campanii**](/ro/guides/outbound-campaigns) din tabloul de bord (`/dashboard/campaigns`) preia un CSV cu contacte și gestionează pentru dumneavoastră ferestrele de apelare adaptate fusului orar, apelurile simultane și politica de reîncercare. Acest ghid acoperă apelurile programatice individuale. ## Cerințe preliminare Folosiți un număr pe care îl dețineți printr-o [conexiune VoIP](/api-reference/voip-connections) 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](/ro/guides/bring-your-own-numbers). 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ă). 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`](/api-reference/billing#get-billing-account), 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: ```bash 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: ```json { "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}`](/api-reference/calls#retrieve-a-call) pentru starea în timp real (`in_progress` → `completed` / `failed`). ## 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`](/ro/webhooks/call-incoming): ```bash 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`](/ro/webhooks/events) — 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: ```json { "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 | Eroare | Remediere | |-------|-----| | `402 Payment Required` | Alimentați soldul sau activați reîncărcarea automată | | `400` cu `code: destination_not_allowed` | ThunderPhone nu apelează acel număr: numere nevalide, numere de urgență, numere cu tarif premium, coduri scurte sau țări sancționate. De la numerele ThunderPhone, sunt permise numai numere obișnuite din SUA și Canada (fără tarif premium). `reason` indică motivul; consultați [destinațiile blocate](/api-reference/outbound-calls#blocked-destinations) | | `409` cu `retryable: false` pentru un număr ThunderPhone | Urmați indicația din `code`: solicitați apeluri efectuate pe pagina Numere de telefon, așteptați o verificare în curs sau utilizați un alt număr eligibil | | `429` cu `code: platform_outbound_daily_limit_reached` | Organizația a utilizat apelurile efectuate de astăzi de la numere ThunderPhone. Așteptați până la `resets_at` (00:00 UTC), solicitați o limită mai mare pe pagina Numere de telefon sau apelați de la un număr din propria conexiune VoIP | | `429` cu `code: concurrent_call_limit_reached` | Organizația are în desfășurare tot atâtea apeluri cât permite [limita de apeluri simultane](/api-reference/introduction#call-limits) (20 în mod implicit, incluzând apelurile primite, efectuate, web și de test). Reîncercați după numărul de secunde din antetul `Retry-After` sau când se încheie un apel; trimiteți un e-mail la support@thunderphone.com pentru a mări limita | | `429` cu `code: same_number_too_soon` | Ați apelat același `to_number` cu mai puțin de 10 secunde în urmă. Reîncercați după numărul de secunde din antetul `Retry-After` | | `409` cu `retryable: false` pentru un număr VoIP al clientului | Corectați starea indicată de `code`; pentru eșecurile de verificare, rulați [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) | | Conflict de idempotență `409` | Reutilizați cheia numai cu cererea normalizată originală sau trimiteți o cheie nouă | | `404 from_number is not registered to this organization` | Confirmați că `from_number` corespunde unui număr de telefon activ din organizația dumneavoastră. Un număr care este deja în curs de configurare, a eșuat, este în curs de eliberare sau a fost eliberat returnează, de asemenea, acest răspuns | | `500` doar cu un câmp `detail` | Nu este configurat niciun trunk de apeluri efectuate. Contactați asistența; aceasta nu este o problemă de stare a numărului pe care o puteți corecta | | `502 Bad Gateway` | Eroare tranzitorie SIP / LiveKit; puteți reîncerca în siguranță | Consultați [referința pentru apeluri de ieșire](/api-reference/outbound-calls#error-responses) 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`: ```json { "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 Fiecare câmp de solicitare și fiecare cod de eroare. Transmiteți apelurile de ieșire finalizate către sistemul dumneavoastră. Reîncărcare automată pentru ca apelurile de ieșire să nu eșueze din cauza soldului. Executați un test fără plasarea apelului pentru agentul vocal de ieșire înainte de producție.