SpeechCall sõnumid
SpeechCall on interaktiivne häälvastuse (IVR) sõnumitüüp, mis võimaldab teha automaatseid häälkõnesid menüüvalikute ja DTMF-i (kahetoonilise mitme sagedusega) interaktsiooniga.
Ülevaade
SpeechCall võimaldab ettevõtetel:
- Tehke klientidele automaatseid häälkõnesid
- Esitage tutvustavaid helisõnumeid
- Esitage interaktiivseid menüüvalikuid
- Käsitsege DTMF-klahvivajutuse vastuseid (0-9, *, #)
- Määratlege kehtetute/ajalõpu sisendite jaoks kohandatud käitumine
- Käivitage kohandatud kehade ja päistega veebihaagid kasutajate valikute põhjal
- Hallake kõnevoogu dünaamiliselt (menüüdes navigeerimine)
Kasutusjuhtumid
- Kliendiküsitlused - Koguge tagasisidet telefoni menüüvalikute kaudu
- Kohtumiste meeldetuletused - kinnitage või muutke ajakava häälsuhtluse abil
- Tellimuste jälgimine - Tellimuse oleku värskenduste pakkumine
- Interaktiivsed märguanded - edastage tegevusvalikutega olulist teavet
- Häälkinnitus - Mitmefaktoriline autentimine häälkõnede kaudu
Taotle vormingut
Põhistruktuur
{
"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"
}
]
}
}
]
}
]
}
Parameetri kirjeldus
| Parameeter | Tüüp | Nõutav | Kirjeldus |
|---|---|---|---|
| ”alates” | string | Jah | Saatja identifikaator (alfa nimi või ID) |
kuni | string | Jah | Saaja telefoninumber rahvusvahelises vormingus |
tekst | string | Jah | Teksti väärtus, SpeechCall |
| “tüüp” | string | Jah | Peab olema “kõnekõne” |
menüü | massiiv | Jah | Kõne menüükonfiguratsioonide hulk |
Menüü konfiguratsioon
Iga menüüobjekt sisaldab:
| Parameeter | Tüüp | Nõutav | Kirjeldus |
|---|---|---|---|
| ”introUrl” | string | Jah | Sissejuhatava helifaili URL või identifikaator |
idleTimeoutMsec | täisarv | Ei | Klahvivajutuse ootamise aeg millisekundites (nt „10000”). Kui kasutaja ei vasta, käivitatakse klahvi “vale” all konfigureeritud toimingud |
| ”dtmfActions” | objekt | Jah | Toimingute DTMF-klahvide kaart |
DTMF toimingud
Objekt `dtmfActions’ vastendab DTMF-võtmed või eritingimused toimingute massiividega:
| DTMF-võti | Kirjeldus |
|---|---|
| ”d0” | Vajutage 0 |
| ”d1” | Vajutage 1 |
| ”d2” | Vajutage 2 |
| … | … |
| “d9” | Vajutage 9 |
d* | Vajutage * |
d# | Vajutage # |
vale | Käivitub, kui vajutatakse kehtetut klahvi või kui jõutakse väärtuseni „idleTimeoutMsec” ilma igasuguse sisendita |
Iga DTMF-võti/-tingimus vastendub tegevuste massiiviga, mis täidetakse järjestikku.
Toetatud toimingud
| Tegevus | Parameetrid | Kirjeldus |
|---|---|---|
veebihaak | ”url” (string, kohustuslik) body” (objekt, valikuline) päised (objekt, valikuline) | Saadab määratud URL-ile HTTP POST-i päringu JSON-vormingus. Objekt „body” pesastatakse veebihaagi päringu välja „action” alla. Kohandatud päised on kaasatud HTTP-päistena. |
hanup | Puudub | Lõpetab kõne |
gotoMenu | ”menüü” (string või täisarv) | Navigeerib kõne massiivi “menüü” teise menüüsse, kasutades selle 0-põhist indeksit (nt “1”) |
Üksikasjalik tegevuskäitumine
Veebihaagi toiming (“veebihaak”)
Toiming „Webhaok” saadab teie tagasihelistamise URL-ile HTTP POST-päringu koos kõne metaandmete ja valikuliste kohandatud andmetega:
- Kui on esitatud “keha”, saadetakse selle võtme-väärtuste paarid kasuliku koormuse keha väljale “tegevus”.
- Kui päised on esitatud, saadetakse need päringus kohandatud HTTP-päistena.
Hangup Action (“kõne katkestamine”)
Toiming “Hangup” lõpetab aktiivse kõne kohe. Pärast kõne katkestamist järjestuses ega menüüdes enam toiminguid ei töödelda.
Ava menüü Toiming (gotoMenu)
Toiming „gotoMenu” suunab kõne voo ümber massiivi „menüü” erinevasse menüüstruktuuri. Selleks on vaja ühte parameetrit “menu”, mis määrab sihtmenüü 0-põhise indeksi (nt teise menüüsse minemiseks “1” või esimese menüü taaskäivitamiseks “0”).
Mitteaktiivsus ja vigade käsitlemine (“vale”)
Vale klahv üksuses ‘dtmfActions’ on spetsiaalne allakäigukäsitleja. See täidab oma tegevuste järjestust kahes stsenaariumis:
- Vigane sisend: helistaja vajutab DTMF-klahvi, mis pole jaotises „dtmfActions” määratletud (näiteks nad vajutavad klahvi „3”, kuid menüüs on määratletud ainult „d1” ja „d2”).
- Idle Timeout: helistaja ei vajuta ‘idleTimeoutMsec’ määratud kestuse jooksul ühtegi klahvi.
Kui “vale” pole määratletud ja helistaja vajutab kehtetut klahvi või aegub, katkestab kõne vaikimisi kõne. Väärtuse „vale” defineerimine võimaldab luua tsüklimenüüsid (nt minna tagasi samasse menüüsse „action”: „gotoMenu”, „menu”: „0”) või suunata kasutaja abimenüüsse.
Veebihaagi kohaletoimetamise vorming
Kui toiming „Webhaok” käivitatakse, saadab süsteem HTTP POST-i päringu konfigureeritud URL-ile „Content-Type: application/json”.
Veebihaagi päringu päised
Kui toiming on konfigureeritud parameetriga „headers”, kaasatakse need võtme-väärtuse paarid päringusse HTTP-päistena.
Veebihaagi päringu sisu
Teie veebihaagi URL-ile saadetud JSON-i koormusel on järgmine struktuur.
{
"from": "0443914272",
"to": "50001",
"mid": "7748021",
"action": {
"confirm": true
}
}
| Väli | Tüüp | Kirjeldus |
|---|---|---|
| ”alates” | string | Helistaja telefoninumber / saatja ID |
kuni | string | Saaja telefoninumber |
keskel | string | Sõnumi ID |
| ”tegevus” | objekt | Kohandatud JSON-objekt, mis on määratletud toimingu kehaväljal |
Täielik näide
Lihtne IVR koos ajalõpu ja sisendi kontrollimisega
{
"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"
}
]
}
}
]
}
]
}
Kompleksne IVR mitme menüü ja DTMF-marsruutimisega
See näide näitab, kuidas määratleda mitu menüüd ja navigeerida nende vahel, kasutades toimingut „gotoMenu”, kui kasutaja sisestab kehtetu klahvi või kui kõne aegub. Samuti kuvatakse veebihaagi päästikutega saadetud kohandatud kehad ja kohandatud HTTP-päised.
{
"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"
}
]
}
}
]
}
]
}
Vastusevorming
Edukas vastus
{
"messages": [
{
"messageId": "unique-message-id",
"recipient": "+380XXXXXXXXX",
"status": "sent"
}
]
}
Vigade käsitlemine
| HTTP olek | Kirjeldus |
|---|---|
| 200 | Taotlus õnnestus |
| 400 | Kehtetu päringu vorming |
| 401 | Autentimine ebaõnnestus |
| 429 | Maksumäär ületatud |
| 500 | Siseserveri viga |
cURL-i näide
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"
}
]
}
}
]
}
]
}'
Parimad tavad
- Helifailid – veenduge, et sissejuhatavad URL-id on juurdepääsetavad ja helifailid toetatud vormingus
- Veebihaagi töökindlus – looge veebihaagid kiiresti (2 sekundi jooksul) reageerimiseks
- DTMF-i valikud – parema kasutuskogemuse saavutamiseks piirake menüüvalikuid 4–6 valikuga
- Ajalõpu käsitlemine – kasutage kohandatud passiivsuse piirangute (nt 10000 ms) määramiseks käsku „idleTimeoutMsec” ja konfigureerige vale DTMF-klahvi all graatsiline tagavara (nt menüü kordamine või kõne katkestamine).
- Mitme menüüga kõnevoog – kasutage käsku “gotoMenu” ettevaatlikult, et vältida lõpmatuid silmuseid, kui suunate kasutajad tagasi eelmistesse menüüdesse
- Varustrateegia – kasutage varusõnumeid kasutajatele, kes ei vasta ega katkesta ühendust
Seotud teemad
- Saada sõnum - Üldine sõnumi saatmise juhend
- Flash Call - lihtsad häälkinnituskõned
- Kontrolli olekut - Jälgige sõnumi edastamise olekut
- Sõnumitüübid - Ülevaade kõigist toetatud sõnumitüüpidest