Uskutočňovanie odchádzajúcich hovorov (API)

Odchádzajúce volanie vám umožňuje odovzdať cieľové číslo a konfiguráciu agenta službe ThunderPhone, aby AI uskutočnila hovor vo vašom mene. Typické prípady použitia:

• Potvrdenia termínov
• Spätné volania v rámci prieskumov
• Následné volania na druhý pokus po zmeškanom hovore
• Oznámenia v štýle dispečingu

Predpoklady

1. Pripravte si číslo VoIP

   Odchádzajúce volanie vyžaduje, aby ste vlastnili from_number prostredníctvom pripojenia VoIP. Demo čísla sú určené iba na prichádzajúce hovory. Pozrite si Pridajte vlastné čísla.

2. Vytvorte agenta

   Výzva určená pre odchádzajúce hovory zvyčajne začína tým, že sa agent predstaví a uvedie svoj účel — „Dobrý deň, tu je Acme, voláme vám, aby sme potvrdili váš zajtrajší termín o 15:00…“ Nastavte outbound_speak_order na agent_first (predvolené nastavenie).

3. Udržujte kladný zostatok

   Odchádzajúce hovory vrátia 402 Payment Required, ak je zostatok ≤ $0.00. Doplňte zostatok prostredníctvom POST /v1/billing/top-up alebo povoľte automatické dobíjanie.

Uskutočnite hovor s uloženým agentom

Najjednoduchší spôsob — odkážte na agenta podľa 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
  }'

Odpoveď:

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

Uskutočnite hovor s vloženou konfiguráciou

Ak chcete jednorazovú výzvu, ktorú sa neoplatí ukladať ako agenta, namiesto toho odošlite config. Štruktúra zodpovedá schéme odpovede 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

Súbežne sa prihláste na odber webhooku telephony.complete — je to najrýchlejší spôsob, ako zistiť, že hovor skončil. Ak nemôžete prijímať prichádzajúce webhooky, každých niekoľko sekúnd kontrolujte GET /v1/calls/{call_id}; záznam po skončení hovoru obsahuje end_reason, duration_seconds a URL nahrávky.

Chybové stavy, ktoré sa oplatí ošetriť

Riadenie času čakania

Odchádzajúce hovory, ktoré trvajú dlho, pretože volaná strana reaguje pomaly (stromy IVR, fronty), môžete obmedziť pomocou max_hold_seconds:

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

Agent hovor ukončí, ak za posledných N sekúnd neprijal žiadny ľudský zvukový vstup. Predvolená hodnota je 900 (15 minút).

Ďalšie kroky