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

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

Dzwonisz do całej listy? Funkcja Kampanie 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.

Wymagania wstępne

Dodaj numer VoIP

Połączenia wychodzące wymagają posiadania numeru from_number za pośrednictwem połączenia VoIP. Numery demonstracyjne obsługują wyłącznie połączenia przychodzące. Zobacz Użyj własnych numerów.

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

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 lub włącz automatyczne doładowanie.

Wykonaj połączenie z zapisanym agentem

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

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ź:

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

status: "initiated" oznacza jedynie, że żądanie zostało zaakceptowane — połączenie nie jest jeszcze połączone. Odpytuj GET /v1/calls/{call_id} o bieżący status (in_progress → completed / failed).

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:

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 — 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`
`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:

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

Dokumentacja połączeń wychodzących

Każde pole żądania i kod błędu.

Odbieranie call.complete

Przesyłaj zakończone połączenia wychodzące do swojego systemu.

Rozliczenia

Automatyczne doładowanie, aby połączenia wychodzące nigdy nie kończyły się niepowodzeniem z powodu salda.

Testowanie agentów wychodzących

Przetestuj na sucho agenta wychodzącego przed wdrożeniem produkcyjnym.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

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

Wymagania wstępne

Wykonaj połączenie z zapisanym agentem

Wykonaj połączenie z konfiguracją inline

Monitoruj połączenie

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

Kontrolowanie czasu oczekiwania

Kolejne kroki

Dokumentacja połączeń wychodzących

Odbieranie call.complete

Rozliczenia

Testowanie agentów wychodzących

​Wymagania wstępne

​Wykonaj połączenie z zapisanym agentem

​Wykonaj połączenie z konfiguracją inline

​Monitoruj połączenie

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

​Kontrolowanie czasu oczekiwania

​Kolejne kroki

Dokumentacja połączeń wychodzących

Odbieranie call.complete

Rozliczenia

Testowanie agentów wychodzących

Wymagania wstępne

Wykonaj połączenie z zapisanym agentem

Wykonaj połączenie z konfiguracją inline

Monitoruj połączenie

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

Kontrolowanie czasu oczekiwania

Kolejne kroki