> ## 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.

# Wykonywanie połączeń wychodzących (API)

> Uruchamiaj połączenia wychodzące obsługiwane przez AI z własnego kodu — ankiety, działania następcze lub procesy potwierdzania.

Połączenia wychodzące pozwalają przekazać ThunderPhone numer docelowy i konfigurację agenta, aby AI wykonała połączenie w Twoim imieniu. Typowe przypadki użycia:

* Potwierdzenia wizyt
* Oddzwonienia w ramach ankiet
* Działania następcze „druga próba” po nieodebranym połączeniu
* Powiadomienia w stylu dyspozytorskim

<Note>
  Dzwonisz do całej listy? Funkcja
  [**Kampanie**](/pl/guides/outbound-campaigns) w panelu
  (`/dashboard/campaigns`) przyjmuje plik CSV z kontaktami i obsługuje
  okna połączeń uwzględniające strefy czasowe, współbieżność oraz zasady
  ponawiania prób. Ten przewodnik dotyczy pojedynczych połączeń programistycznych.
</Note>

## Wymagania wstępne

<Steps>
  <Step title="Dodaj numer VoIP">
    Połączenia wychodzące wymagają posiadania numeru `from_number` za pośrednictwem
    [połączenia VoIP](/api-reference/voip-connections). Numery demonstracyjne
    obsługują wyłącznie połączenia przychodzące. Zobacz
    [Użyj własnych numerów](/pl/guides/bring-your-own-numbers).
  </Step>

  <Step title="Utwórz agenta">
    Prompt dla połączeń wychodzących zwykle zaczyna się od przedstawienia się
    agenta i określenia celu — „Cześć, tu Acme. Dzwonimy, aby
    potwierdzić Twoją jutrzejszą wizytę o 15:00…” Ustaw
    `outbound_speak_order` na `agent_first` (wartość domyślna).
  </Step>

  <Step title="Utrzymuj dodatnie saldo">
    Połączenia wychodzące zwracają `402 Payment Required`, jeśli saldo wynosi ≤
    `$0.00`. Doładuj saldo przez
    [`POST /v1/billing/top-up`](/api-reference/billing#top-up-balance)
    lub włącz [automatyczne doładowanie](/api-reference/billing#update-auto-reload).
  </Step>
</Steps>

## Wykonaj połączenie z zapisanym agentem

Najprostsze rozwiązanie — odwołaj się do agenta według identyfikatora:

```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
  }'
```

Odpowiedź:

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

<Warning>
  `status: "initiated"` oznacza jedynie, że żądanie zostało zaakceptowane —
  połączenie **nie jest jeszcze połączone**. Odpytuj
  [`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)
  o bieżący status (`in_progress` → `completed` / `failed`).
</Warning>

## Wykonaj połączenie z konfiguracją inline

Jeśli potrzebujesz jednorazowego promptu, którego nie warto zapisywać jako agenta,
przekaż zamiast tego `config`. Struktura odpowiada schematowi odpowiedzi webhooka
[`call.incoming`](/pl/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"
    }
  }'
```

## Monitoruj połączenie

Równolegle zasubskrybuj webhook
[`telephony.complete`](/pl/webhooks/events) —
to najszybszy sposób, aby dowiedzieć się, że połączenie zostało zakończone. Jeśli nie możesz przyjmować
przychodzących webhooków, odpytywanie `GET /v1/calls/{call_id}` wykonuj co kilka sekund; rekord
zawiera `end_reason`, `duration_seconds` oraz adres URL nagrania
po zakończeniu połączenia.

## Błędy, które warto obsłużyć

| Błąd                                                            | Rozwiązanie                                                                                                    |
| --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `402 Payment Required`                                          | Doładuj saldo lub włącz automatyczne doładowanie                                                               |
| `403` zablokowane połączenia wychodzące (numer demonstracyjny)  | Zamiast tego dodaj numer VoIP                                                                                  |
| `403` zablokowane połączenia wychodzące (niezweryfikowany VoIP) | Uruchom [`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`        | Potwierdź, że `from_number` odpowiada posiadanemu przez Ciebie numerowi telefonu                               |
| `502 Bad Gateway`                                               | Przejściowy błąd SIP / LiveKit; można bezpiecznie ponowić próbę                                                |

## Kontrolowanie czasu oczekiwania

Połączenia wychodzące, które trwają długo, ponieważ odbiorca wolno odpowiada
(dr zewa IVR, kolejki), można ograniczyć za pomocą `max_hold_seconds`:

```json theme={null}
{
  "from_number": "+15551234567",
  "to_number":   "+14155550199",
  "agent_id":    12,
  "max_hold_seconds": 120
}
```

Agent rozłącza się, jeśli w ciągu ostatnich N sekund nie odebrano dźwięku ludzkiego głosu. Wartość domyślna to 900 (15 minut).

***

## Kolejne kroki

<CardGroup cols={2}>
  <Card title="Dokumentacja połączeń wychodzących" icon="phone-arrow-up-right" href="/api-reference/outbound-calls">
    Każde pole żądania i kod błędu.
  </Card>

  <Card title="Odbieranie call.complete" icon="bolt" href="/pl/webhooks/call-complete">
    Przesyłaj zakończone połączenia wychodzące do swojego systemu.
  </Card>

  <Card title="Rozliczenia" icon="credit-card" href="/api-reference/billing">
    Automatyczne doładowanie, aby połączenia wychodzące nigdy nie kończyły się niepowodzeniem z powodu salda.
  </Card>

  <Card title="Testowanie agentów wychodzących" icon="flask" href="/pl/guides/test-agents">
    Przetestuj na sucho agenta wychodzącego przed wdrożeniem produkcyjnym.
  </Card>
</CardGroup>