Provádění odchozích hovorů (API)

Spusťte ze svého vlastního kódu odchozí hovor řízený umělou inteligencí – pro průzkumy, následné kontaktování nebo potvrzovací postupy.

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

• Potvrzení schůzek
• Zpětná volání v rámci průzkumů
• Následná volání na druhý pokus po zmeškaném hovoru
• Oznámení ve stylu dispečinku

Předpoklady#

1. Vyberte číslo povolené pro odchozí volání

   Použijte číslo, které vlastníte prostřednictvím připojení VoIP, nebo požádejte o povolení používat svá čísla ThunderPhone pro odchozí volání na stránce Telefonní čísla. Čísla ThunderPhone jsou zpočátku pouze pro příchozí volání. ThunderPhone každou žádost posuzuje ručně; po schválení mohou tato čísla uskutečňovat hovory až do schváleného denního limitu (který se resetuje ve 00:00 UTC) a spouštět kampaně. Můžete také požádat o vyšší limit. Zákaznická čísla VoIP nemají denní limit, proto je doporučujeme pro odchozí volání. Viz Použití vlastních čísel.

2. Vytvořte agenta

   Prompt pro odchozí volání obvykle začíná tím, že se agent představí a uvede svůj účel — „Dobrý den, volá Acme, abychom potvrdili vaši schůzku na zítřek v 15:00…“ Nastavte outbound_speak_order na agent_first (výchozí hodnota).

3. Udržujte kladný zůstatek

   Odchozí hovory vrátí 402 Payment Required, pokud je zůstatek ≤ $0.00. Doplňte zůstatek nebo povolte automatické dobíjení v části Organizace → Nastavení fakturace na ovládacím panelu. Váš klíč sk_live_ může zkontrolovat zůstatek pomocí GET /v1/billing, ale nemůže doplnit zůstatek ani změnit automatické dobíjení.

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

Nejjednodušší způsob — 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":   "+14155552671",
    "agent_id":    12
  }'

Odpověď:

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

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

Pokud chcete jednorázový prompt, který nestojí za uložení jako agent, 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":   "+14155552671",
    "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 — nejrychlejšího způsobu, jak zjistit, že hovor skončil. Pokud nemůžete přijímat příchozí webhooky, dotazujte se každých několik sekund na GET /v1/calls/{call_id}; záznam po skončení hovoru obsahuje end_reason, duration_seconds a adresu URL nahrávky.

Pokud je váš agent nastavený na extrakci strukturovaných dat po hovoru, tato data jsou doručena samostatně po dokončení finalizace.

Předání proměnných pro jednotlivý hovor uloženému agentovi#

Uložení agenti mohou v textu promptu používat zástupné symboly jako {{name}} nebo {{name|there}}. Při uskutečnění odchozího hovoru s agent_id předejte variables s hodnotami pro daný hovor:

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

Použijte řetězcové hodnoty s klíči odpovídajícími názvům zástupných symbolů. Tyto proměnné platí pro uložené agenty; příklad vloženého config v této příručce je nepoužívá.

Stavy selhání, které je vhodné ošetřit#

Úplný stabilní seznam kódů způsobilosti a oba tvary odpovědi 409 najdete v referenci odchozích hovorů. Pokud se aktivní číslo stane nezpůsobilým po přijetí požadavku, ale před uskutečněním hovoru, závěrečná kontrola vrátí datovou část 409, kterou nelze opakovat.

Řízení doby čekání#

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

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

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

Další kroky#