Open in
Upućujte odlazne pozive (API)
Pokrenite odlazni poziv koji vodi AI iz vlastitog koda — ankete, naknadne kontakte ili tijekove potvrde.
Odlazno pozivanje omogućuje vam da ThunderPhoneu predate odredišni broj i konfiguraciju agenta te da AI uputi poziv u vaše ime. Uobičajeni slučajevi upotrebe:
- Potvrde termina
- Povratni pozivi za ankete
- Naknadni kontakt pri „drugom pokušaju” nakon propuštenog poziva
- Obavijesti u stilu dispečerskih poruka
Preduvjeti
- Odaberite broj omogućen za odlazne pozive
Upotrijebite broj koji posjedujete putem VoIP veze ili zatražite dopuštenje za upotrebu svojih ThunderPhone brojeva za odlazne pozive na stranici Phone Numbers. ThunderPhone brojevi u početku su samo za dolazne pozive. ThunderPhone ručno pregledava svaki zahtjev; nakon odobrenja ti brojevi mogu upućivati pozive do odobrenog dnevnog ograničenja (koje se ponovno postavlja u 00:00 UTC) i pokretati kampanje, a Vi možete zatražiti veće ograničenje. VoIP brojevi korisnika nemaju dnevno ograničenje, stoga ih preporučujemo za odlazne pozive. Pogledajte Upotrijebite vlastite brojeve.
- Izradite agenta
Uputa prilagođena odlaznim pozivima obično počinje tako da se agent predstavi i navede svoju svrhu — "Pozdrav, ovdje Acme, zovemo kako bismo potvrdili Vaš termin za sutra u 15 h…" Postavite
outbound_speak_ordernaagent_first(zadana vrijednost). - Održavajte pozitivan saldo
Odlazni pozivi vraćaju
402 Payment Requiredako je saldo ≤$0.00. Nadoplatite saldo ili omogućite automatsku nadoplatu u odjeljku Organization → Billing Settings na nadzornoj ploči. Vaš ključsk_live_može provjeriti saldo pomoćuGET /v1/billing, ali ne može nadoplatiti saldo ni promijeniti automatsku nadoplatu.
Uputite poziv sa spremljenim agentom
Najjednostavniji način — navedite agenta prema identifikatoru:
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" }Uputite poziv s ugrađenom konfiguracijom
Ako želite jednokratni prompt koji ne vrijedi spremati kao agenta,
umjesto toga proslijedite config. Struktura odgovara shemi odgovora
web-dojavnika 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"
}
}'Kontrolirajte što se događa nakon posljednje provjere tišine
Iste postavke završne radnje za tišinu možete proslijediti i u umetnutom config koji koriste spremljeni agenti:
{
"from_number": "+[REDACTED_PHONE]",
"to_number": "+[REDACTED_PHONE]",
"config": {
"silence_final_action": "hang_up"
}
}Upotrijebite silence_final_action za odabir onoga što se događa nakon posljednje provjere tišine. Možete proslijediti i silence_final_message te, kada je završna radnja prijenos, silence_transfer_destination.
Dodajte popis riječi u umetnuti config
Umetnuti odlazni pozivi mogu sadržavati isti popis words kao i spremljeni agenti.
Upotrijebite ovo kada želite da poziv slijedi prilagođena pravila izgovora ili
prepoznavanja bez prethodnog spremanja agenta.
{
"from_number": "+[REDACTED_PHONE]",
"to_number": "+[REDACTED_PHONE]",
"config": {
"prompt": "[REDACTED_LITERAL]",
"voice": "john",
"product": "spark",
"words": []
}
}Pratite poziv
Odgovor s vremenom queued_at znači da je ThunderPhoneov odlazni kapacitet
zauzet: poziv se bira kada se oslobodi kapacitet, unutar 10 minuta, i završava s
end_reason outbound_queue_timeout ako se kapacitet ne oslobodi. Ne morate
ponavljati pokušaj. Pogledajte pozive u redu čekanja.
Istodobno se pretplatite na
webhook telephony.complete —
najbrži način da saznate da je poziv završio. Možete se pretplatiti i na
call.status_changed za ažuriranja
napretka uživo, kao što su biranje broja, odgovoreni poziv, govorna pošta i promjene zadržavanja.
Ako ne možete primati dolazne webhookove, svakih nekoliko sekundi provjeravajte GET /v1/calls/{call_id};
zapis uključuje end_reason, duration_seconds i URL snimke nakon završetka poziva.
Ako je vaš agent postavljen za izdvajanje strukturiranih podataka nakon poziva, ti se podaci isporučuju zasebno nakon dovršetka finalizacije.
Proslijedite varijable po pozivu spremljenom agentu
Spremljeni agenti mogu upotrebljavati rezervirana mjesta kao što su {{name}} ili {{name|there}} u
tekstu upute. Kada upućujete odlazni poziv s agent_id, proslijedite
variables s vrijednostima za taj poziv:
{
"from_number": "+[REDACTED_PHONE]",
"to_number": "+[REDACTED_PHONE]",
"agent_id": 12,
"variables": {
"name": "Jordan"
}
}Upotrijebite vrijednosti niza označene nazivom rezerviranog mjesta. Te se varijable primjenjuju na
spremljene agente; primjer umetnutog config u ovom vodiču ne upotrebljava ih.
Načini neuspjeha koje vrijedi obraditi
| Pogreška | Rješenje |
|---|---|
402 Payment Required | Dopunite stanje ili omogućite automatsku nadoplatu |
400 s code: destination_not_allowed | ThunderPhone ne poziva taj broj: nevaljane brojeve, brojeve za hitne službe, brojeve s posebnom tarifom, kratke kodove, sankcionirane zemlje ili saveznu državu SAD-a za koju je vaša organizacija blokirala odlazno pozivanje. S brojeva ThunderPhone dopušteni su uobičajeni brojevi u SAD-u i Kanadi, a dopuštena su i neka međunarodna odredišta koja se naplaćuju prema tarifi odredišta. reason navodi koji; pogledajte blokirana odredišta |
409 s retryable: false za broj ThunderPhone | Slijedite code: zatražite odlazno pozivanje na stranici Telefonski brojevi, pričekajte provjeru na čekanju ili upotrijebite drugi prihvatljivi broj |
429 s code: platform_outbound_daily_limit_reached | Organizacija je iskoristila današnje odlazne pozive s brojeva ThunderPhone. Pričekajte resets_at (00:00 UTC), zatražite viši limit na stranici Telefonski brojevi ili pozovite s broja na vlastitoj VoIP vezi |
429 s code: concurrent_call_limit_reached | Organizacija ima onoliko poziva u tijeku koliko iznosi njezino ograničenje istodobnih poziva (zadano 20, uključujući dolazne, odlazne, web i testne pozive). Ponovite pokušaj nakon broja sekundi iz zaglavlja Retry-After ili kada poziv završi; pošaljite e-poruku na support@thunderphone.com kako biste povećali limit |
429 s code: outbound_queue_full | Organizacija ima 50 poziva u redu na čekanju. Ponovite pokušaj nakon broja sekundi iz zaglavlja Retry-After |
429 s code: same_number_too_soon | Isti to_number pozvali ste prije manje od 10 sekundi. Ponovite pokušaj nakon broja sekundi iz zaglavlja Retry-After |
409 s retryable: false za korisnički VoIP broj | Ispravite stanje navedeno u code; za neuspjele provjere pokrenite POST /v1/phone-numbers/{id}/verify-voip |
409 sukob idempotentnosti | Ponovno upotrijebite ključ samo s izvornim normaliziranim zahtjevom ili pošaljite novi ključ |
404 from_number is not registered to this organization | Potvrdite da from_number odgovara aktivnom telefonskom broju u vašoj organizaciji. Broj koji se već aktivira, nije uspio, otpušta se ili je otpušten također vraća ovaj odgovor |
500 samo s poljem detail | Nije konfiguriran odlazni trunk. Obratite se podršci; ovo nije problem stanja broja koji možete ispraviti |
502 Bad Gateway | Privremeni kvar SIP-a / LiveKit-a; sigurno je ponoviti pokušaj |
Pogledajte referencu za odlazne pozive
za potpuni stabilni popis kodova prihvatljivosti i oba oblika odgovora 409.
Ako aktivni broj postane neprihvatljiv nakon prihvaćanja zahtjeva, ali prije
upućivanja poziva, završna provjera vraća sadržaj odgovora 409 koji nije moguće ponovno pokušati.
Upravljanje vremenom čekanja
Odlazni pozivi koji dugo traju jer pozvana strana sporo odgovara
(IVR stabla, redovi čekanja) mogu se ograničiti pomoću max_hold_seconds na pozivu ili postavljanjem te vrijednosti na spremljenom agentu:
{
"from_number": "+15551234567",
"to_number": "+14155552671",
"agent_id": 12,
"max_hold_seconds": 120
}Agent prekida poziv ako u posljednjih N sekundi nije primljen ljudski zvuk. Zadana vrijednost je 900 sekundi (15 minuta).
Ako postavite max_hold_seconds i na spremljenom agentu i u zahtjevu za odlazni poziv, za taj se poziv koristi vrijednost po pozivu.
Sljedeći koraci
Svako polje zahtjeva i svaki kod pogreške.
Prosljeđujte dovršene odlazne pozive u svoj sustav.
Automatska nadopuna kako odlazni pozivi nikada ne bi bili neuspješni zbog salda.
Probno pokrenite svoj odlazni agent prije produkcije.