Uskutečňování odchozích hovorů (API)

Odchozí volání vám umožňuje předat ThunderPhone cílové číslo a konfiguraci agenta, aby AI uskutečnila hovor vaším jménem. Typické případy použití:

Potvrzení termínů
Zpětná volání k průzkumům
Následná volání na druhý pokus po zmeškaném hovoru
Oznámení ve stylu dispečinku

Voláte na celý seznam? Funkce Kampaně v dashboardu (/dashboard/campaigns) přijímá CSV kontaktů a za vás zajišťuje časová okna volání s ohledem na časová pásma, souběžnost a zásady opakování. Tento průvodce popisuje jednotlivá programová volání.

Předpoklady

Přidejte VoIP číslo

Pro odchozí volání musíte vlastnit from_number prostřednictvím VoIP připojení. Ukázková čísla jsou pouze pro příchozí hovory. Viz Použijte vlastní čísla.

Vytvořte agenta

Prompt určený pro odchozí hovory obvykle začíná tím, že se agent představí a uvede svůj účel — „Dobrý den, zde Acme, voláme kvůli potvrzení vašeho zítřejšího termínu v 15:00…“ Nastavte outbound_speak_order na agent_first (výchozí nastavení).

Udržujte kladný zůstatek

Odchozí volání vrací 402 Payment Required, pokud je zůstatek ≤ $0.00. Doplňte kredit pomocí POST /v1/billing/top-up nebo povolte automatické dobíjení.

Uskutečněte hovor s uloženým agentem

Nejjednodušší postup — odkažte na agenta podle ID:

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

Odpověď:

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

status: "initiated" pouze znamená, že požadavek byl přijat — hovor ještě není spojen. Aktivní stav zjišťujte pomocí GET /v1/calls/{call_id} (in_progress → completed / failed).

Uskutečněte hovor s vloženou konfigurací

Pokud potřebujete jednorázový prompt, který nemá smysl ukládat jako agenta, předejte místo toho config. Struktura odpovídá schématu odpovědi webhooku 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"
    }
  }'

Sledujte hovor

Souběžně se přihlaste k odběru webhooku telephony.complete — je to nejrychlejší způsob, jak zjistit, že hovor skončil. Pokud nemůžete přijímat příchozí webhooky, dotazujte GET /v1/calls/{call_id} každých několik sekund; záznam po skončení hovoru obsahuje end_reason, duration_seconds a URL nahrávky.

Chybové stavy, které se vyplatí ošetřit

Chyba	Řešení
`402 Payment Required`	Doplňte zůstatek nebo povolte automatické dobíjení
`403` odchozí volání blokováno (ukázkové číslo)	Místo toho přidejte VoIP číslo
`403` odchozí volání blokováno (neověřené VoIP)	Spusťte `POST /v1/phone-numbers/{id}/verify-voip`
`404 from_number is not registered to this organization`	Ověřte, že `from_number` odpovídá telefonnímu číslu, které vlastníte
`502 Bad Gateway`	Dočasné selhání SIP / LiveKit; opakování je bezpečné

Řízení doby čekání

Odchozí hovory, které se protahují, protože volaný reaguje pomalu (stromy IVR, fronty), lze omezit pomocí max_hold_seconds:

{
  "from_number": "+15551234567",
  "to_number":   "+14155550199",
  "agent_id":    12,
  "max_hold_seconds": 120
}

Agent hovor ukončí, pokud během posledních N sekund nepřijal žádný lidský zvuk. Výchozí hodnota je 900 (15 minut).

Další kroky

Referenční dokumentace odchozích hovorů

Každé pole požadavku a chybový kód.

Přijímání call.complete

Odesílejte dokončené odchozí hovory do svého systému.

Fakturace

Automatické dobíjení, aby odchozí hovory nikdy neselhaly kvůli zůstatku.

Testování odchozích agentů

Před nasazením do produkce nasucho otestujte svého odchozího agenta.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

Uskutečňování odchozích hovorů (API)

Předpoklady

Uskutečněte hovor s uloženým agentem

Uskutečněte hovor s vloženou konfigurací

Sledujte hovor

Chybové stavy, které se vyplatí ošetřit

Řízení doby čekání

Další kroky

Referenční dokumentace odchozích hovorů

Přijímání call.complete

Fakturace

Testování odchozích agentů

​Předpoklady

​Uskutečněte hovor s uloženým agentem

​Uskutečněte hovor s vloženou konfigurací

​Sledujte hovor

​Chybové stavy, které se vyplatí ošetřit

​Řízení doby čekání

​Další kroky

Referenční dokumentace odchozích hovorů

Přijímání call.complete

Fakturace

Testování odchozích agentů

Předpoklady

Uskutečněte hovor s uloženým agentem

Uskutečněte hovor s vloženou konfigurací

Sledujte hovor

Chybové stavy, které se vyplatí ošetřit

Řízení doby čekání

Další kroky