ThunderPhone v3 je tu.Začnite sami, už od 2 ¢/min.Prečítať oznámenie

Developer cookbook

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

Ovládajte, čo sa stane po poslednej kontrole ticha

Rovnaké nastavenia konečnej akcie pri tichu môžete odovzdať aj v riadkovej konfigurácii config, ktorú používajú uložené agenty:

{
  "from_number": "+[REDACTED_PHONE]",
  "to_number": "+[REDACTED_PHONE]",
  "config": {
    "silence_final_action": "hang_up"
  }
}

Pomocou silence_final_action vyberte, čo sa stane po poslednej kontrole ticha. Môžete tiež odovzdať silence_final_message a pri prenose ako konečnej akcii aj silence_transfer_destination.

Pridajte zoznam slov do riadkovej konfigurácie config

Riadkové odchádzajúce hovory môžu obsahovať rovnaký zoznam words ako uložené agenty. Použite ho, keď chcete, aby hovor dodržiaval vlastné pravidlá výslovnosti alebo rozpoznávania bez toho, aby ste najprv uložili agenta.

{
  "from_number": "+[REDACTED_PHONE]",
  "to_number": "+[REDACTED_PHONE]",
  "config": {
    "prompt": "[REDACTED_LITERAL]",
    "voice": "john",
    "product": "spark",
    "words": []
  }
}

Sledujte hovor

Odpoveď s časom queued_at znamená, že sa používa odchádzajúca kapacita ThunderPhone: hovor sa vytočí, keď bude k dispozícii miesto, do 10 minút, a ak sa miesto neuvoľní, skončí s hodnotou end_reason outbound_queue_timeout. Nemusíte ho opakovať. Pozrite si hovory vo fronte.

Súbežne sa prihláste na odber webhooku telephony.complete — ide o najrýchlejší spôsob, ako zistiť, že sa hovor skončil. Môžete sa tiež prihlásiť na odber call.status_changed, aby ste dostávali priebežné aktualizácie stavu, napríklad vytáčanie, prijatie hovoru, hlasovú schránku a zmeny podržania hovoru. Ak nemôžete prijímať prichádzajúce webhooky, dotazujte sa na GET /v1/calls/{call_id} každých niekoľko sekúnd; 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ť

ChybaOprava
402 Payment RequiredDobiť zostatok alebo povoliť automatické dobíjanie
400 s code: destination_not_allowedThunderPhone na toto číslo nevolá: neplatné čísla, tiesňové čísla, čísla so zvýšenou sadzbou, krátke kódy, sankcionované krajiny alebo štát USA, ktorý vaša organizácia zablokovala pre odchádzajúce hovory. Z čísel ThunderPhone sú povolené bežné čísla v USA a Kanade a niektoré medzinárodné destinácie, ktoré sa účtujú sadzbou danej destinácie. reason uvádza ktoré; pozrite si blokované destinácie
409 s retryable: false pre číslo ThunderPhonePostupovať podľa code: požiadať o odchádzajúce hovory na stránke Telefónne čísla, počkať na prebiehajúce posúdenie alebo použiť iné oprávnené číslo
429 s code: platform_outbound_daily_limit_reachedOrganizácia už využila dnešný limit odchádzajúcich hovorov z čísel ThunderPhone. Počkať do resets_at (00:00 UTC), požiadať o vyšší limit na stránke Telefónne čísla alebo volať z čísla vo vlastnom pripojení VoIP
429 s code: concurrent_call_limit_reachedOrganizácia má práve toľko prebiehajúcich hovorov, koľko umožňuje jej limit súbežných hovorov (predvolene 20, vrátane prichádzajúcich, odchádzajúcich, webových a testovacích hovorov). Skúsiť znova po uplynutí počtu sekúnd uvedeného v hlavičke Retry-After alebo po skončení hovoru; limit zvýšite e-mailom na support@thunderphone.com
429 s code: outbound_queue_fullOrganizácia má 50 čakajúcich hovorov vo fronte. Skúsiť znova po uplynutí počtu sekúnd uvedeného v hlavičke Retry-After
429 s code: same_number_too_soonNa rovnaké to_number ste volali pred menej ako 10 sekundami. Skúsiť znova po uplynutí počtu sekúnd uvedeného v hlavičke Retry-After
409 s retryable: false pre zákaznícke číslo VoIPOpraviť stav uvedený v code; pri zlyhaní overenia spustiť POST /v1/phone-numbers/{id}/verify-voip
konflikt idempotencie 409Kľúč znova použiť iba s pôvodnou normalizovanou požiadavkou alebo odoslať nový kľúč
404 from_number is not registered to this organizationOveriť, že from_number zodpovedá aktívnemu telefónnemu číslu vo vašej organizácii. Túto odpoveď vráti aj číslo, ktoré sa už zriaďuje, ktorého zriadenie zlyhalo, ktoré sa uvoľňuje alebo bolo uvoľnené
500 iba s poľom detailNie je nakonfigurovaný žiadny odchádzajúci trunk. Kontaktovať podporu; nejde o problém so stavom čísla, ktorý môžete opraviť
502 Bad GatewayDočasné zlyhanie SIP / LiveKit; možno bezpečne skúsiť znova

Ú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é trvajú dlho, pretože volaný reaguje pomaly (stromy IVR, fronty), môžete obmedziť pomocou max_hold_seconds pri hovore alebo jeho nastavením pri uloženom agentovi:

{
  "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).

Ak nastavíte max_hold_seconds pri uloženom agentovi aj v požiadavke na odchádzajúci hovor, pre daný hovor sa použije hodnota pre jednotlivý hovor.


Ďalšie kroky