---
title: "Wykonuj połączenia wychodzące (API)"
description: "Uruchamiaj wychodzące połączenia realizowane 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 zastosowania:

- Potwierdzanie wizyt
- Oddzwanianie w sprawie ankiet
- Kontakty „drugiej próby” 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. Ten przewodnik dotyczy pojedynczych połączeń programowych.
</Note>

## Wymagania wstępne

<Steps>
  <Step title="Wybierz numer z obsługą połączeń wychodzących">
    Użyj numeru, którego jesteś właścicielem, przez
    [połączenie VoIP](/api-reference/voip-connections) albo poproś o zgodę
    na używanie swoich numerów ThunderPhone do połączeń wychodzących na stronie
    Numery telefonów. Numery ThunderPhone początkowo obsługują tylko połączenia przychodzące. ThunderPhone ręcznie weryfikuje każde
    zgłoszenie; po zatwierdzeniu numery te mogą wykonywać połączenia do
    zatwierdzonego dziennego limitu (resetowanego o 00:00 UTC) i uruchamiać kampanie, a Ty
    możesz poprosić o wyższy limit. Numery VoIP klienta nie mają dziennego limitu, dlatego zalecamy
    je do połączeń wychodzących. Zobacz
    [Użyj własnych numerów](/pl/guides/bring-your-own-numbers).
  </Step>
  <Step title="Utwórz agenta">
    Prompt ukierunkowany na połączenia wychodzące zwykle zaczyna się od
    przedstawienia się przez agenta i określenia celu — „Dzień dobry, dzwoni Acme, aby
    potwierdzić wizytę na jutro na 15:00…” Ustaw
    `outbound_speak_order` na `agent_first` (domyślne ustawienie).
  </Step>
  <Step title="Utrzymuj dodatnie saldo">
    Połączenia wychodzące zwracają `402 Payment Required`, jeśli saldo wynosi ≤
    `$0.00`. Doładuj konto lub włącz automatyczne doładowanie w sekcji
    **Organizacja → Ustawienia rozliczeń** w panelu. Twój klucz `sk_live_`
    może sprawdzać saldo za pomocą
    [`GET /v1/billing`](/api-reference/billing#get-billing-account), ale
    nie może doładowywać konta ani zmieniać automatycznego doładowania.
  </Step>
</Steps>

## Wykonaj połączenie z zapisanym agentem

Najprostsza metoda — odwołaj się do agenta według identyfikatora:

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

Odpowiedź:

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

<Warning>
  `status: "initiated"` oznacza jedynie, że żądanie zostało zaakceptowane —
  połączenie **nie jest jeszcze zestawione**. 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ą wbudowaną

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

## Śledź połączenie

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

Jeśli Twój agent jest skonfigurowany do wyodrębniania danych strukturalnych po połączeniu,
dane te są dostarczane osobno po zakończeniu finalizacji.

### Przekazywanie zmiennych dla połączenia do zapisanego agenta

Zapisani agenci mogą używać symboli zastępczych, takich jak `{{name}}` lub `{{name|there}}`, w
tekście promptu. Gdy wykonujesz połączenie wychodzące z użyciem `agent_id`, przekaż
`variables` z wartościami dla tego połączenia:

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

Używaj wartości tekstowych z kluczami odpowiadającymi nazwom symboli zastępczych. Te zmienne dotyczą
zapisanych agentów; przykład wbudowanego `config` w tym przewodniku ich nie używa.

## Obsługiwane tryby awarii

| Błąd | Rozwiązanie |
|-------|-----|
| `402 Payment Required` | Doładuj saldo lub włącz automatyczne doładowanie |
| `400` z `code: destination_not_allowed` | ThunderPhone nie dzwoni na ten numer: nieprawidłowe numery, numery alarmowe, numery o podwyższonej opłacie, krótkie kody lub kraje objęte sankcjami. Z numerów ThunderPhone można dzwonić tylko na zwykłe numery w USA i Kanadzie (bez numerów o podwyższonej opłacie). `reason` wskazuje który przypadek; zobacz [zablokowane numery docelowe](/api-reference/outbound-calls#blocked-destinations) |
| `409` z `retryable: false` dla numeru ThunderPhone | Postępuj zgodnie z `code`: poproś o możliwość wykonywania połączeń wychodzących na stronie Numery telefonów, poczekaj na trwającą weryfikację lub użyj innego kwalifikującego się numeru |
| `429` z `code: platform_outbound_daily_limit_reached` | Organizacja wykorzystała dzisiejszy limit połączeń wychodzących z numerów ThunderPhone. Poczekaj na `resets_at` (00:00 UTC), poproś o wyższy limit na stronie Numery telefonów lub dzwoń z numeru we własnym połączeniu VoIP |
| `429` z `code: concurrent_call_limit_reached` | Organizacja ma tyle połączeń w toku, ile wynosi jej [limit równoczesnych połączeń](/api-reference/introduction#call-limits) (domyślnie 20, z uwzględnieniem połączeń przychodzących, wychodzących, internetowych i testowych). Spróbuj ponownie po liczbie sekund wskazanej w nagłówku `Retry-After` lub po zakończeniu połączenia; wyślij e-mail na support@thunderphone.com, aby zwiększyć limit |
| `429` z `code: same_number_too_soon` | Dzwoniono na ten sam `to_number` mniej niż 10 sekund temu. Spróbuj ponownie po liczbie sekund wskazanej w nagłówku `Retry-After` |
| `409` z `retryable: false` dla numeru VoIP klienta | Skoryguj stan wskazany przez `code`; w przypadku niepowodzenia weryfikacji uruchom [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) |
| konflikt idempotencji `409` | Użyj ponownie klucza tylko z oryginalnym znormalizowanym żądaniem lub wyślij nowy klucz |
| `404 from_number is not registered to this organization` | Potwierdź, że `from_number` odpowiada aktywnemu numerowi telefonu w organizacji. Ten sam komunikat jest zwracany także dla numeru, który jest już w trakcie aktywacji, którego aktywacja się nie powiodła, który jest zwalniany lub został zwolniony |
| `500` zawierający tylko pole `detail` | Nie skonfigurowano żadnego trunku wychodzącego. Skontaktuj się z pomocą techniczną; nie jest to problem ze stanem numeru, który możesz naprawić |
| `502 Bad Gateway` | Przejściowy błąd SIP / LiveKit; można bezpiecznie spróbować ponownie |

Zobacz [dokumentację połączeń wychodzących](/api-reference/outbound-calls#error-responses),
aby poznać pełną stabilną listę kodów kwalifikowalności i oba formaty odpowiedzi `409`.
Jeśli aktywny numer przestanie kwalifikować się po zaakceptowaniu żądania, ale przed
wykonaniem połączenia, końcowa kontrola zwróci ładunek `409`, którego nie można ponowić.

## Kontrolowanie czasu oczekiwania

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

```json
{
  "from_number": "+15551234567",
  "to_number":   "+14155552671",
  "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 sekund (15 minut).

---

## Dalsze 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="Odbieraj 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">
    Przeprowadź próbne uruchomienie agenta wychodzącego przed wdrożeniem produkcyjnym.
  </Card>
</CardGroup>