Open in
Izvajanje odhodnih klicev (API)
Iz lastne kode sprožite odhodni klic, ki ga vodi umetna inteligenca — za ankete, nadaljnje stike ali potrditvene poteke.
Odhodno klicanje vam omogoča, da ThunderPhone posredujete ciljno številko in konfiguracijo agenta, AI pa opravi klic v vašem imenu. Običajni primeri uporabe:
- Potrditve terminov
- Povratni klici za ankete
- Nadaljnji klici ob »drugem poskusu« po neodgovorjenem klicu
- Obvestila v slogu dispečerskih obvestil
Predpogoji
- Izberite številko, omogočeno za odhodne klice
Uporabite številko, ki jo imate v lasti prek VoIP-povezave, ali zaprosite za dovoljenje za uporabo svojih številk ThunderPhone za odhodne klice na strani Telefonske številke. Številke ThunderPhone so sprva omogočene samo za dohodne klice. ThunderPhone vsako zahtevo pregleda ročno; po odobritvi lahko te številke opravljajo klice do odobrene dnevne omejitve (ki se ponastavi ob 00:00 UTC) in izvajajo kampanje, vi pa lahko zaprosite za višjo omejitev. VoIP-številke strank nimajo dnevne omejitve, zato jih priporočamo za odhodne klice. Glejte Uporabite svoje številke.
- Ustvarite agenta
Poziv, prilagojen odhodnim klicem, se običajno začne tako, da se agent predstavi in navede svoj namen — "Pozdravljeni, tukaj Acme, kličemo, da potrdimo vaš jutrišnji termin ob 15.00 …" Nastavite
outbound_speak_ordernaagent_first(privzeto). - Ohranite pozitivno stanje
Odhodni klici vrnejo
402 Payment Required, če je stanje ≤$0.00. Dodajte sredstva ali omogočite samodejno ponovno polnjenje v Organizacija → Nastavitve obračunavanja na nadzorni plošči. Z vašim ključemsk_live_lahko preverite stanje zGET /v1/billing, vendar z njim ne morete dodati sredstev ali spremeniti samodejnega ponovnega polnjenja.
Opravite klic s shranjenim agentom
Najpreprostejši način — sklicujte se na agenta po ID-ju:
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
}'Odgovor:
{ "call_id": 987654321, "status": "initiated" }Opravite klic z vdelano konfiguracijo
Če želite enkraten poziv, ki ga ni vredno shraniti kot agenta,
namesto tega posredujte config. Oblika se ujema s shemo odgovora
spletnega kljuka 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"
}
}'Nadzirajte, kaj se zgodi po zadnjem preverjanju tišine
Enake nastavitve končnega dejanja ob tišini lahko podate tudi v vdelani config, ki jo uporabljajo shranjeni agenti:
{
"from_number": "+[REDACTED_PHONE]",
"to_number": "+[REDACTED_PHONE]",
"config": {
"silence_final_action": "hang_up"
}
}Z silence_final_action izberite, kaj se zgodi po zadnjem preverjanju tišine. Podate lahko tudi silence_final_message in, kadar je končno dejanje preusmeritev, silence_transfer_destination.
Dodajte seznam besed v vdelano config
Vdelani odhodni klici lahko vključujejo enak seznam words kot shranjeni agenti.
To uporabite, kadar želite, da klic upošteva prilagojena pravila izgovorjave ali prepoznavanja
brez predhodnega shranjevanja agenta.
{
"from_number": "+[REDACTED_PHONE]",
"to_number": "+[REDACTED_PHONE]",
"config": {
"prompt": "[REDACTED_LITERAL]",
"voice": "john",
"product": "spark",
"words": []
}
}Spremljanje klica
Odgovor s časom queued_at pomeni, da je izhodna zmogljivost ThunderPhonea
v uporabi: klic se vzpostavi, ko je na voljo zmogljivost, v 10 minutah, in se konča z
end_reason outbound_queue_timeout, če zmogljivosti ni. Ni vam treba
ponoviti poskusa. Oglejte si klice v čakalni vrsti.
Vzporedno se naročite na
Webhook telephony.complete —
to je najhitrejši način, da izveste, kdaj se je klic končal. Naročite se lahko tudi na
call.status_changed za sprotne
posodobitve napredka, kot so izbiranje številke, odgovor, glasovna pošta in spremembe zadržanja.
Če ne morete sprejemati dohodnih webhookov, vsakih nekaj
sekund preverite GET /v1/calls/{call_id}; zapis po koncu klica vključuje end_reason, duration_seconds
in URL posnetka.
Če je vaš agent nastavljen za pridobivanje strukturiranih podatkov po klicu, so ti podatki dostavljeni ločeno po zaključku finalizacije.
Posredovanje spremenljivk posameznega klica shranjenemu agentu
Shranjeni agenti lahko v besedilu poziva uporabljajo označbe mesta, kot sta {{name}} ali {{name|there}}.
Ko opravite odhodni klic z agent_id, posredujte
variables z vrednostmi za ta klic:
{
"from_number": "+[REDACTED_PHONE]",
"to_number": "+[REDACTED_PHONE]",
"agent_id": 12,
"variables": {
"name": "Jordan"
}
}Uporabite vrednosti nizov, katerih ključi so imena označb mesta. Te spremenljivke veljajo za
shranjene agente; primer vdelane config v tem vodniku jih ne uporablja.
Primeri napak, ki jih je vredno obravnavati
| Napaka | Rešitev |
|---|---|
402 Payment Required | Napolnite stanje ali omogočite samodejno ponovno polnjenje |
400 z code: destination_not_allowed | ThunderPhone ne kliče te številke: neveljavne številke, številke za klic v sili, številke s posebno tarifo, kratke kode, sankcionirane države ali zvezna država ZDA, ki jo je vaša organizacija blokirala za odhodne klice. Iz številk ThunderPhone so dovoljene običajne številke iz ZDA in Kanade, dovoljene pa so tudi nekatere mednarodne destinacije, ki se zaračunajo po tarifi destinacije. reason pove, katera velja; glejte blokirane destinacije |
409 z retryable: false za številko ThunderPhone | Upoštevajte code: na strani Telefonske številke zahtevajte odhodno klicanje, počakajte na pregled v obdelavi ali uporabite drugo ustrezno številko |
429 z code: platform_outbound_daily_limit_reached | Organizacija je porabila današnjo kvoto odhodnih klicev iz številk ThunderPhone. Počakajte na resets_at (00:00 UTC), na strani Telefonske številke zahtevajte višjo omejitev ali kličite s številke v lastni VoIP-povezavi |
429 z code: concurrent_call_limit_reached | Organizacija ima toliko klicev v teku, kolikor znaša njena omejitev sočasnih klicev (privzeto 20, vključno z dohodnimi, odhodnimi, spletnimi in preskusnimi klici). Poskusite znova po številu sekund, navedenem v glavi Retry-After, ali ko se klic konča; za zvišanje omejitve pišite na support@thunderphone.com |
429 z code: outbound_queue_full | Organizacija ima 50 čakajočih klicev v čakalni vrsti. Poskusite znova po številu sekund, navedenem v glavi Retry-After |
429 z code: same_number_too_soon | Isto to_number ste poklicali pred manj kot 10 sekundami. Poskusite znova po številu sekund, navedenem v glavi Retry-After |
409 z retryable: false za VoIP-številko stranke | Odpravite stanje, navedeno v code; pri neuspešnih preverjanjih zaženite POST /v1/phone-numbers/{id}/verify-voip |
spor idempotentnosti 409 | Ključ znova uporabite samo z izvirno normalizirano zahtevo ali pošljite nov ključ |
404 from_number is not registered to this organization | Potrdite, da se from_number ujema z aktivno telefonsko številko v vaši organizaciji. Ta odgovor vrne tudi številka, ki je že v postopku zagotavljanja, je neuspešna, se sprošča ali je sproščena |
500 samo s poljem detail | Odhodni trunk ni konfiguriran. Obrnite se na podporo; to ni težava stanja številke, ki bi jo lahko odpravili |
502 Bad Gateway | Prehodna napaka SIP / LiveKit; lahko varno poskusite znova |
Za celoten stabilni seznam kod upravičenosti in obe obliki odziva 409 glejte
referenco odhodnih klicev.
Če aktivna številka postane neupravičena po sprejetju zahteve, vendar pred
izvedbo klica, končno preverjanje vrne vsebino 409, pri kateri ponovni poskus ni mogoč.
Nadzor časa čakanja
Odhodne klice, ki trajajo dolgo, ker se klicana oseba počasi odziva
(drevesa IVR, čakalne vrste), lahko omejite z max_hold_seconds pri klicu ali z nastavitvijo te vrednosti pri shranjenem agentu:
{
"from_number": "+15551234567",
"to_number": "+14155552671",
"agent_id": 12,
"max_hold_seconds": 120
}Agent prekine klic, če v zadnjih N sekundah ni prejel človeškega zvoka. Privzeta vrednost je 900 sekund (15 minut).
Če nastavite max_hold_seconds tako pri shranjenem agentu kot v zahtevi za odhodni klic, se za ta klic uporabi vrednost za posamezni klic.
Naslednji koraki
Vsa polja zahtev in kode napak.
Zaključene odhodne klice pretakajte v svoj sistem.
Omogočite samodejno ponovno polnjenje, da odhodni klici nikoli ne odpovejo zaradi stanja.
Pred produkcijo izvedite preizkus brez dejanskega klica za svojega odhodnega agenta.