Developer cookbook

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

Wymagania wstępne#

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

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

3. 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" }

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

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#