Govorne poruke
SpeechCall je vrsta poruke interaktivnog glasovnog odgovora (IVR) koja vam omogućuje upućivanje automatiziranih glasovnih poziva s opcijama izbornika i DTMF (dual-tone multi-frequency) interakcijama.
Pregled
SpeechCall tvrtkama omogućuje:
- Upućujte automatizirane glasovne pozive korisnicima
- Reproducirajte uvodne audio poruke
- Predstavite interaktivne opcije izbornika
- Rukovanje DTMF odgovorima na pritisak tipke (0-9, *, #)
- Definirajte prilagođeno ponašanje za nevažeće/istek vremena
- Pokreni webdojavnike s prilagođenim tijelima i zaglavljima na temelju korisničkih odabira
- Dinamički upravljajte protokom poziva (krećite se između izbornika)
Slučajevi upotrebe
- Ankete kupaca - Prikupite povratne informacije putem opcija izbornika telefona
- Podsjetnici za sastanke - Potvrdite ili promijenite termin glasovnom interakcijom
- Praćenje narudžbi - Omogućite ažuriranje statusa narudžbe
- Interaktivne obavijesti - Dostavite važne informacije s opcijama radnji
- Glasovna potvrda - Višefaktorska provjera autentičnosti putem glasovnih poziva
Format zahtjeva
Osnovna struktura
{
"messages": [
{
"from": "YourSender",
"to": "+380XXXXXXXXX",
"text": "ivr",
"type": "speechcall",
"menu": [
{
"introUrl": "ivr_XXXXX",
"idleTimeoutMsec": 10000,
"dtmfActions": {
"d1": [
{
"action": "webhook",
"url": "https://YourWebhookURL/0",
"body": {
"confirm": true
},
"headers": {
"test-header": "test"
}
},
{
"action": "hangup"
}
],
"d2": [
{
"action": "webhook",
"url": "https://YourWebhookURL/1",
"body": {
"confirm": false
}
},
{
"action": "hangup"
}
],
"wrong": [
{
"action": "gotoMenu",
"menu": "1"
}
]
}
}
]
}
]
}
Opis parametra
| Parametar | Upišite | Obavezno | Opis |
|---|---|---|---|
od | niz | Da | Identifikator pošiljatelja (alfa ime ili ID) |
za | niz | Da | Telefonski broj primatelja u međunarodnom formatu |
tekst | niz | Da | Tekstualna vrijednost, obično “ivr” za SpeechCall |
tip | niz | Da | Mora biti "speechcall" |
izbornik | niz | Da | Niz konfiguracija izbornika za poziv |
Konfiguracija izbornika
Svaki objekt izbornika sadrži:
| Parametar | Upišite | Obavezno | Opis |
|---|---|---|---|
introUrl | niz | Da | URL ili identifikator uvodne audio datoteke |
IdleTimeoutMsec | cijeli broj | Ne | Istek vremena u milisekundama za čekanje pritiska tipke (npr. 10000). Ako korisnik ne odgovori, izvršit će se radnje konfigurirane pod tipkom wrong |
dtmfAkcije | objekt | Da | Karta DTMF tipki za akcije |
DTMF radnje
Objekt dtmfActions preslikava DTMF ključeve ili posebne uvjete u nizove radnji:
| DTMF ključ | Opis |
|---|---|
d0 | Pritisnite 0 |
d1 | Pritisnite 1 |
d2 | Pritisnite 2 |
| … | … |
d9 | Pritisnite 9 |
d* | Pritisnite * |
d# | Pritisnite # |
pogrešno | Aktivira se kada se pritisne nevažeća tipka ili kada se dosegne idleTimeoutMsec bez ikakvog unosa |
Svaki DTMF ključ/uvjet preslikava se u niz radnji koje će se izvršavati u nizu.
Podržane radnje
| Radnja | Parametri | Opis |
|---|---|---|
webhook | url (niz, obavezno)tijelo (objekt, izborno)zaglavlja (objekt, izborno) | Šalje HTTP POST zahtjev u JSON formatu na navedeni URL. Objekt body bit će ugniježđen ispod polja action u zahtjevu web-dojavnika. Prilagođena zaglavlja uključena su kao HTTP zaglavlja. |
prekidanje | Ništa | Završava poziv |
gotoMenu | izbornik (string ili cijeli broj) | Usmjerava poziv do drugog izbornika u nizu izbornik koristeći njegov indeks temeljen na 0 (npr. "1") |
Detaljno ponašanje akcije
Webhook radnja (webhook)
Akcija webhook šalje HTTP POST zahtjev na vaš URL povratnog poziva s metapodacima poziva i neobaveznim prilagođenim podacima:
- Ako je navedeno
tijelo, njegovi parovi ključ-vrijednost šalju se unutar poljaakcijatijela korisnog sadržaja. - Ako su navedena
zaglavlja, ona se šalju kao prilagođena HTTP zaglavlja u zahtjevu.
Radnja prekida veze (prekid veze)
Akcija prekid veze trenutno prekida aktivni poziv. Nikakve daljnje radnje u nizu ili izbornicima neće biti obrađene nakon radnje prekida veze.
Idi na radnju izbornika (gotoMenu)
Radnja gotoMenu preusmjerava tok poziva na drugu strukturu izbornika unutar polja izbornik. Potreban je jedan parametar izbornik koji navodi indeks ciljnog izbornika temeljen na 0 (npr. "1" za odlazak na drugi izbornik ili "0" za ponovno pokretanje prvog izbornika).
Neaktivnost i rukovanje pogreškama (‘pogrešno’)
Pogrešan ključ unutar dtmfActions poseban je rukovatelj pada. Izvršava svoj niz radnji u dva scenarija:
- Nevažeći unos: Pozivatelj pritišće DTMF tipku koja nije definirana u
dtmfActions(na primjer, pritisnuo je3, ali izbornik definira samod1id2). - Idle Timeout: Pozivatelj ne pritisne nijednu tipku unutar vremena navedenog u
idleTimeoutMsec.
Ako pogrešno nije definirano i pozivatelj pritisne nevažeću tipku ili mu istekne vrijeme, tijek poziva će prekinuti vezu prema zadanim postavkama. Definiranje wrong omogućuje vam izradu izbornika petlje (npr. povratak na isti izbornik s "action": "gotoMenu", "menu": "0") ili preusmjeravanje korisnika na izbornik za pomoć.
Webhook format isporuke
Kada se pokrene radnja webhook, sustav šalje HTTP POST zahtjev na konfigurirani url s Content-Type: application/json.
Webhook zaglavlja zahtjeva
Ako je radnja konfigurirana s parametrom headers, ti parovi ključ-vrijednost uključeni su kao HTTP zaglavlja u zahtjev.
Webhook tijelo zahtjeva
JSON sadržaj poslan na vaš URL web-dojavnika ima sljedeću strukturu:
{
"from": "0443914272",
"to": "50001",
"mid": "7748021",
"action": {
"confirm": true
}
}
| Polje | Upišite | Opis |
|---|---|---|
od | niz | Telefonski broj pozivatelja / ID pošiljatelja |
za | niz | Broj telefona primatelja |
sredina | niz | ID poruke |
akcija | objekt | Prilagođeni JSON objekt definiran u polju tijelo akcije |
Kompletan primjer
Jednostavan IVR s vremenskim ograničenjem i provjerom valjanosti unosa
{
"messages": [
{
"from": "YourSender",
"to": "+380XXXXXXXXX",
"text": "ivr",
"type": "speechcall",
"menu": [
{
"introUrl": "ivr_651854",
"idleTimeoutMsec": 10000,
"dtmfActions": {
"d1": [
{
"action": "webhook",
"url": "https://YourWebhookURL/0",
"body": {
"confirm": true
}
},
{
"action": "hangup"
}
],
"d2": [
{
"action": "webhook",
"url": "https://YourWebhookURL/1",
"body": {
"confirm": false
}
},
{
"action": "hangup"
}
],
"wrong": [
{
"action": "hangup"
}
]
}
}
]
}
]
}
Složeni IVR s više izbornika i DTMF usmjeravanjem
Ovaj primjer pokazuje kako definirati više izbornika i kretati se između njih pomoću radnje gotoMenu kada korisnik unese nevažeću tipku ili kada poziv istekne. Također prikazuje prilagođena tijela i prilagođena HTTP zaglavlja poslana s okidačima web-dojavnika.
{
"messages": [
{
"from": "YourSender",
"to": "+380XXXXXXXXX",
"text": "ivr",
"type": "speechcall",
"menu": [
{
"introUrl": "ivr_XXXXX",
"idleTimeoutMsec": 10000,
"dtmfActions": {
"d1": [
{
"action": "webhook",
"url": "https://YourWebhookURL/0",
"body": {
"confirm": true
},
"headers": {
"test-header": "test"
}
},
{
"action": "hangup"
}
],
"d2": [
{
"action": "webhook",
"url": "https://YourWebhookURL/1",
"body": {
"confirm": false
}
},
{
"action": "hangup"
}
],
"wrong": [
{
"action": "gotoMenu",
"menu": "1"
}
]
}
},
{
"introUrl": "ivr_651854",
"idleTimeoutMsec": 10000,
"dtmfActions": {
"d1": [
{
"action": "webhook",
"url": "https://YourWebhookURL/0",
"body": {
"confirm": true
}
},
{
"action": "hangup"
}
],
"d2": [
{
"action": "webhook",
"url": "https://YourWebhookURL/1",
"body": {
"confirm": false
}
},
{
"action": "hangup"
}
],
"wrong": [
{
"action": "hangup"
}
]
}
}
]
}
]
}
Format odgovora
Uspješan odgovor
{
"messages": [
{
"messageId": "unique-message-id",
"recipient": "+380XXXXXXXXX",
"status": "sent"
}
]
}
Rješavanje grešaka
| HTTP status | Opis |
|---|---|
| 200 | Zahtjev uspješan |
| 400 | Nevažeći format zahtjeva |
| 401 | Autentifikacija nije uspjela |
| 429 | Ograničenje brzine premašeno |
| 500 | Interna greška poslužitelja |
Primjer cURL-a
curl -X POST https://restapi.smsbat.com/bat/messagelist \
-u "username:password" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{
"from": "YourSender",
"to": "+380XXXXXXXXX",
"text": "ivr",
"type": "speechcall",
"menu": [
{
"introUrl": "ivr_XXXXX",
"idleTimeoutMsec": 10000,
"dtmfActions": {
"d1": [
{
"action": "webhook",
"url": "https://YourWebhookURL/0",
"body": {
"confirm": true
},
"headers": {
"test-header": "test"
}
},
{
"action": "hangup"
}
],
"d2": [
{
"action": "webhook",
"url": "https://YourWebhookURL/1",
"body": {
"confirm": false
}
},
{
"action": "hangup"
}
],
"wrong": [
{
"action": "gotoMenu",
"menu": "1"
}
]
}
},
{
"introUrl": "ivr_651854",
"idleTimeoutMsec": 10000,
"dtmfActions": {
"d1": [
{
"action": "webhook",
"url": "https://YourWebhookURL/0",
"body": {
"confirm": true
}
},
{
"action": "hangup"
}
],
"d2": [
{
"action": "webhook",
"url": "https://YourWebhookURL/1",
"body": {
"confirm": false
}
},
{
"action": "hangup"
}
],
"wrong": [
{
"action": "hangup"
}
]
}
}
]
}
]
}'
Najbolji primjeri iz prakse
- Audio datoteke - Provjerite jesu li uvodni URL-ovi dostupni i audio datoteke u podržanim formatima
- Pouzdanost web-dojavnika - Dizajnirajte web-dojavnike za brzi odgovor (unutar 2 sekunde)
- DTMF opcije - Ograničite opcije izbornika na 4-6 izbora za bolje korisničko iskustvo
- Upravljanje timeoutom - Koristite
idleTimeoutMsecza određivanje prilagođenih ograničenja neaktivnosti (npr. 10000 ms) i konfigurirajte elegantnu zamjenu podpogrešnomDTMF tipkom (poput ponavljanja izbornika ili prekidanja veze) - Tijek poziva s više izbornika - Pažljivo koristite
gotoMenukako biste spriječili beskonačne petlje prilikom preusmjeravanja korisnika natrag na prethodne izbornike - Rezervna strategija - Koristite rezervne poruke za korisnike koji ne odgovore ili prekinu vezu
Povezane teme
- Pošalji poruku - Opći vodič za slanje poruka
- Flash Call - Jednostavni pozivi za glasovnu provjeru
- Provjeri status - Pratite status isporuke poruke
- Vrste poruka - Pregled svih podržanih vrsta poruka