Developer cookbook

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

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

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

Předpoklady#

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

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

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

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#

Ří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#