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

Spustite odchádzajúci hovor riadený AI z vlastného kódu — pre prieskumy, následné kontaktovanie alebo potvrdzovacie procesy.

Odchádzajúce volania vám umožňujú odovzdať ThunderPhone cieľové číslo a konfiguráciu agenta, 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é kontaktovanie na druhý pokus po zmeškanom hovore
• Oznámenia v štýle dispečingu

Predpoklady#

1. Vyberte číslo s povolenými odchádzajúcimi hovormi

   Použite číslo, ktoré vlastníte prostredníctvom pripojenia VoIP, alebo požiadajte o povolenie používať svoje čísla ThunderPhone na odchádzajúce hovory na stránke Telefónne čísla. Čísla ThunderPhone sú spočiatku určené iba pre prichádzajúce hovory. ThunderPhone každú žiadosť posudzuje manuálne; po schválení môžu tieto čísla uskutočňovať hovory do schváleného denného limitu (ktorý sa obnovuje o 00:00 UTC) a spúšťať kampane. Môžete tiež požiadať o vyšší limit. Zákaznícke čísla VoIP nemajú denný limit, preto ich odporúčame na odchádzajúce hovory. Pozrite si Použitie vlastných čísel.

2. Vytvorte agenta

   Výzva zameraná na odchádzajúce hovory zvyčajne začína tým, že sa hlasový 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žiavajte kladný zostatok

   Odchádzajúce hovory vrátia 402 Payment Required, ak je zostatok ≤ $0.00. Doplňte zostatok alebo povoľte automatické dobíjanie v sekcii Organizácia → Nastavenia fakturácie na paneli. Váš kľúč sk_live_ môže skontrolovať zostatok pomocou GET /v1/billing, ale nemôže doplniť zostatok ani zmeniť 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":   "+14155552671",
    "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 odovzdajte 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":   "+14155552671",
    "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 sa dotazujte na GET /v1/calls/{call_id}; záznam po skončení hovoru obsahuje end_reason, duration_seconds a adresu URL nahrávky.

Ak je váš hlasový agent nastavený na extrakciu štruktúrovaných údajov po hovore, tieto údaje sa doručia samostatne po dokončení finalizácie.

Odovzdávanie premenných pre jednotlivé hovory uloženému agentovi#

Uložení agenti môžu v texte promptu používať zástupné symboly ako {{name}} alebo {{name|there}}. Keď uskutočňujete odchádzajúci hovor s agent_id, odovzdajte variables s hodnotami pre daný hovor:

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

Použite reťazcové hodnoty s kľúčmi podľa názvu zástupného symbolu. Tieto premenné platia pre uložených agentov; vložený príklad config v tejto príručke ich nepoužíva.

Stavy zlyhania, ktoré sa oplatí ošetriť#

Úplný stabilný zoznam kódov oprávnenosti a oba formáty odpovede 409 nájdete v referencii odchádzajúcich hovorov. Ak aktívne číslo prestane spĺňať podmienky po prijatí požiadavky, ale pred uskutočnením hovoru, finálna kontrola vráti neopakovateľný obsah odpovede 409.

Riadenie času čakania#

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

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

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

Ďalšie kroky#