> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Note>
  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 la fusul orar, concurența și
  politica de reîncercare. Acest ghid acoperă apelurile programatice individuale.
</Note>

## Cerințe preliminare

<Steps>
  <Step title="Aduceți un număr VoIP">
    Apelarea de ieșire necesită să dețineți `from_number` printr-o
    [conexiune VoIP](/api-reference/voip-connections). Numerele demo
    sunt disponibile doar pentru apeluri de intrare. Consultați
    [Aduceți propriile numere](/ro/guides/bring-your-own-numbers).
  </Step>

  <Step title="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ă).
  </Step>

  <Step title="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`](/api-reference/billing#top-up-balance)
    sau activați [reîncărcarea automată](/api-reference/billing#update-auto-reload).
  </Step>
</Steps>

## Plasați un apel cu un agent salvat

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

```bash theme={null}
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:

```json theme={null}
{ "call_id": 987654321, "status": "initiated" }
```

<Warning>
  `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`).
</Warning>

## 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`](/ro/webhooks/call-incoming):

```bash theme={null}
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`](/ro/webhooks/events) —
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`](/api-reference/phone-numbers#verify-a-voip-sourced-number) |
| `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`:

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Referință pentru apeluri outbound" icon="phone-arrow-up-right" href="/api-reference/outbound-calls">
    Fiecare câmp din solicitare și fiecare cod de eroare.
  </Card>

  <Card title="Primiți call.complete" icon="bolt" href="/ro/webhooks/call-complete">
    Transmiteți apelurile outbound finalizate către sistemul dumneavoastră.
  </Card>

  <Card title="Facturare" icon="credit-card" href="/api-reference/billing">
    Reîncărcare automată, astfel încât apelurile outbound să nu eșueze din cauza soldului.
  </Card>

  <Card title="Testați agenții outbound" icon="flask" href="/ro/guides/test-agents">
    Testați agentul outbound înainte de producție.
  </Card>
</CardGroup>