Wykonuj połączenia wychodzące (API)

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

Wymagania wstępne#

1. Wybierz numer z obsługą połączeń wychodzących

   Użyj numeru, którego jesteś właścicielem, przez połączenie VoIP 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.

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

3. 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, ale nie może doładowywać konta ani zmieniać automatycznego doładowania.

Wykonaj połączenie z zapisanym agentem#

Najprostsza metoda — 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":   "+14155552671",
    "agent_id":    12
  }'

Odpowiedź:

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

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:

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

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

Zobacz dokumentację połączeń wychodzących, 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:

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