Open in
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
- 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.
- 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_ordernaagent_first(predvolené nastavenie). - 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 pomocouGET /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ť
| Chyba | Oprava |
|---|---|
402 Payment Required | Dobiť zostatok alebo povoliť automatické dobíjanie |
400 s code: destination_not_allowed | ThunderPhone 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 ThunderPhone | Postupovať 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_reached | Organizá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_reached | Organizá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_full | Organizá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_soon | Na 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 VoIP | Opraviť stav uvedený v code; pri zlyhaní overenia spustiť POST /v1/phone-numbers/{id}/verify-voip |
konflikt idempotencie 409 | Kľúč znova použiť iba s pôvodnou normalizovanou požiadavkou alebo odoslať nový kľúč |
404 from_number is not registered to this organization | Overiť, ž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 detail | Nie je nakonfigurovaný žiadny odchádzajúci trunk. Kontaktovať podporu; nejde o problém so stavom čísla, ktorý môžete opraviť |
502 Bad Gateway | Doč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
Každé pole požiadavky a kód chyby.
Odosielajte dokončené odchádzajúce hovory do svojho systému.
Automatické dobíjanie, aby odchádzajúce hovory nikdy nezlyhali pre nedostatok zostatku.
Pred nasadením do produkcie otestujte svojho hlasového agenta pre odchádzajúce hovory nanečisto.