SpeechCall žinutės
SpeechCall yra interaktyvaus balso atsako (IVR) pranešimo tipas, leidžiantis atlikti automatinius balso skambučius naudojant meniu parinktis ir DTMF (dviejų tonų kelių dažnių) sąveiką.
Apžvalga
„SpeechCall“ leidžia įmonėms:
- Atlikite automatinius balso skambučius klientams
- Leiskite įvadinius garso pranešimus
- Pateikite interaktyvias meniu parinktis
- Tvarkyti DTMF klavišų paspaudimo atsakymus (0–9, *, #)
- Nustatykite pasirinktinį netinkamų / skirtojo laiko įvesties elgesį
- Suaktyvinkite žiniatinklio kabliukus su pasirinktiniais turiniais ir antraštėmis pagal naudotojo pasirinkimus
- Tvarkykite skambučių srautą dinamiškai (naršykite tarp meniu)
Naudojimo atvejai
- Klientų apklausos - Rinkti atsiliepimus naudodami telefono meniu parinktis – Priminimai apie susitikimą – Patvirtinkite arba pakeiskite tvarkaraštį bendraujant balsu – Užsakymų stebėjimas – Pateikite užsakymo būsenos atnaujinimus – Interaktyvūs pranešimai – pateikite svarbią informaciją naudodami veiksmų parinktis – Patvirtinimas balsu – kelių veiksnių autentifikavimas balso skambučiais
Užklausos formatas
Pagrindinė struktūra
{
"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"
}
]
}
}
]
}
]
}
Parametrų aprašymas
| Parametras | Tipas | Reikalingas | Aprašymas |
|---|---|---|---|
| ”nuo” | styga | Taip | Siuntėjo identifikatorius (raidinis vardas arba ID) |
| “į” | styga | Taip | Gavėjo telefono numeris tarptautiniu formatu |
| ”tekstas” | styga | Taip | Teksto reikšmė, paprastai „ivr“, skirta SpeechCall |
| ”tipas” | styga | Taip | Turi būti "speechcall" |
| ”meniu” | masyvas | Taip | Skambučio meniu konfigūracijų rinkinys |
Meniu konfigūracija
Kiekviename meniu objekte yra:
| Parametras | Tipas | Reikalingas | Aprašymas |
|---|---|---|---|
| ”introUrl” | styga | Taip | Įvadinio garso failo URL arba identifikatorius |
idleTimeoutMsec | sveikasis skaičius | Ne | Laukimo klavišo paspaudimo laikas milisekundėmis (pvz., „10 000“). Jei vartotojas neatsako, veiksmai, sukonfigūruoti naudojant „neteisingą“ klavišą, bus atlikti |
| ”dtmfActions” | objektas | Taip | DTMF veiksmų klavišų žemėlapis |
DTMF veiksmai
Objektas „dtmfActions“ susieja DTMF raktus arba specialias sąlygas su veiksmų masyvais:
| DTMF raktas | Aprašymas |
|---|---|
| ”d0” | Paspauskite 0 |
| ”d1” | Paspauskite 1 |
| ”d2” | Paspauskite 2 |
| … | … |
| “d9” | Paspauskite 9 |
d* | Paspauskite * |
d# | Paspauskite # |
neteisingai | Suveikia, kai paspaudžiamas netinkamas klavišas arba kai pasiekiamas „idleTimeoutMsec“ be jokios įvesties |
Kiekvienas DTMF raktas / sąlyga susiejama su veiksmų, kurie bus vykdomi iš eilės, masyvas.
Palaikomi veiksmai
| Veiksmas | Parametrai | Aprašymas |
|---|---|---|
| ”webhook” | „url“ (eilutė, būtina) „body“ (objektas, neprivaloma) „antraštės“ (objektas, neprivaloma) | Siunčia HTTP POST užklausą JSON formatu nurodytu URL. Objektas „body“ bus įdėtas į „Webhook“ užklausos lauką „veiksmas“. Pasirinktinės antraštės įtraukiamos kaip HTTP antraštės. |
pakabinti | Nėra | Baigia skambutį |
gotoMenu | ”meniu” (eilutė arba sveikasis skaičius) | Perkelia iškvietimą į kitą meniu „meniu“ masyve, naudodamas indeksą 0 (pvz., „1“) |
Išsamus veiksmų elgesys
Webhook veiksmas (“webhook”)
Veiksmas „Webhook“ siunčia HTTP POST užklausą atgalinio skambučio URL su skambučio metaduomenimis ir pasirinktiniais tinkintais duomenimis: – Jei pateikiamas „body“, jo raktų ir reikšmių poros siunčiamos naudingojo krovinio turinio lauke „action“. – Jei pateikiamos antraštės, jos užklausoje siunčiamos kaip tinkintos HTTP antraštės.
Pakabinimo veiksmas (“pakabinimas”)
Veiksmas „pakabinimas“ nedelsiant nutraukia aktyvų skambutį. Po „pakabinimo“ veiksmo jokie tolesni veiksmai sekoje ar meniu nebus atliekami.
Eiti į meniu veiksmą („gotoMenu“)
Veiksmas „gotoMenu“ nukreipia skambučio srautą į kitą meniu struktūrą „meniu“ masyve. Reikia vieno parametro „menu“, kuris nurodo 0 pagrįstą tikslinio meniu indeksą (pvz., „1“, kad pereitumėte į antrąjį meniu, arba „0“, kad iš naujo paleistumėte pirmąjį meniu).
Neaktyvumas ir klaidų tvarkymas (“neteisingas”)
„dtmfActions“ esantis raktas „neteisingas“ yra speciali kritimo tvarkyklė. Jis vykdo savo veiksmų seką dviem scenarijais:
- Netinkama įvestis: skambinantysis paspaudžia DTMF klavišą, kuris nėra apibrėžtas „dtmfActions“ (pavyzdžiui, jis paspaudžia „3“, bet meniu apibrėžia tik „d1“ ir „d2“).
- Nenaudojimo laikas: skambinantysis nepaspaudžia jokio klavišo per „idleTimeoutMsec“ nurodytą trukmę.
Jei „neteisinga“ neapibrėžta ir skambinantysis paspaudžia netinkamą klavišą arba baigiasi skirtasis laikas, skambučio srautas nutraukiamas pagal numatytuosius nustatymus. Apibrėžus „neteisingai“ galima kurti ciklo meniu (pvz., grįžti į tą patį meniu su „action“: „gotoMenu“, „menu“: „0“) arba nukreipti naudotoją į pagalbos meniu.
Webhook pristatymo formatas
Kai suaktyvinamas „webhook“ veiksmas, sistema siunčia HTTP POST užklausą į sukonfigūruotą „url“ su „Content-Type: application/json“.
Webhook užklausų antraštės
Jei veiksmas sukonfigūruotas naudojant parametrą „antraštės“, tos raktų ir reikšmių poros įtraukiamos kaip HTTP antraštės į užklausą.
Webhook užklausos dalis
JSON naudingoji apkrova, išsiųsta į jūsų „webhook“ URL, turi tokią struktūrą:
{
"from": "0443914272",
"to": "50001",
"mid": "7748021",
"action": {
"confirm": true
}
}
| Laukas | Tipas | Aprašymas |
|---|---|---|
| ”nuo” | styga | Skambinančiojo telefono numeris / Siuntėjo ID |
| ”į” | styga | Gavėjo telefono numeris |
vidutinis | styga | Pranešimo ID |
| ”veiksmas” | objektas | Tinkintas JSON objektas, apibrėžtas veiksmo lauke „body“ |
Pilnas pavyzdys
Paprastas IVR su skirtuoju laiku ir įvesties patvirtinimu
{
"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"
}
]
}
}
]
}
]
}
Sudėtingas IVR su keliais meniu ir DTMF maršruto parinkimu
Šiame pavyzdyje parodyta, kaip apibrėžti kelis meniu ir naršyti tarp jų naudojant veiksmą „gotoMenu“, kai vartotojas įveda netinkamą klavišą arba kai baigiasi skambučio laikas. Jame taip pat rodomi pasirinktiniai elementai ir tinkintos HTTP antraštės, siunčiamos su „webhook“ aktyvikliais.
{
"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"
}
]
}
}
]
}
]
}
Atsakymo formatas
Sėkmės atsakas
{
"messages": [
{
"messageId": "unique-message-id",
"recipient": "+380XXXXXXXXX",
"status": "sent"
}
]
}
Klaidų tvarkymas
| HTTP būsena | Aprašymas |
|---|---|
| 200 | Užklausa sėkminga |
| 400 | Neteisingas užklausos formatas |
| 401 | Autentifikavimas nepavyko |
| 429 | Viršytas normos limitas |
| 500 | Vidinė serverio klaida |
cURL pavyzdys
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"
}
]
}
}
]
}
]
}'
Geriausia praktika
- Garso failai – įsitikinkite, kad įvado URL yra pasiekiami, o garso failų formatai palaikomi
- Webhook patikimumas – sukurkite žiniatinklio kabliukus, kad jie greitai reaguotų (per 2 sekundes)
- DTMF parinktys – apribokite meniu parinktis iki 4–6 pasirinkimų, kad būtų geresnė vartotojo patirtis
- Laiko tvarkymas – naudokite „idleTimeoutMsec“, kad nurodytumėte tinkintus neveiklumo apribojimus (pvz., 10 000 ms), ir sukonfigūruokite grakštų atsarginį režimą naudodami „neteisingą“ DTMF klavišą (pvz., kartokite meniu arba padėkite ragelį).
- Kelių meniu skambučių srautas – atsargiai naudokite „gotoMenu“, kad išvengtumėte begalinių kilpų nukreipdami naudotojus atgal į ankstesnius meniu
- Atsarginė strategija – naudokite atsarginius pranešimus naudotojams, kurie neatsiliepia arba neatsijungia
Susijusios temos
- Siųsti pranešimą - Bendras pranešimų siuntimo vadovas – Flash Call – Paprasti balso patvirtinimo skambučiai
- Patikrinti būseną - Stebėkite pranešimo pristatymo būseną – Pranešimų tipai – Visų palaikomų pranešimų tipų apžvalga