Správy SpeechCall
SpeechCall je typ správy interaktívnej hlasovej odpovede (IVR), ktorý vám umožňuje uskutočňovať automatizované hlasové hovory s možnosťami ponuky a DTMF (dvojtónové multifrekvenčné) interakcie.
Prehľad
SpeechCall umožňuje podnikom:
- Uskutočňujte automatizované hlasové hovory so zákazníkmi
- Prehrajte úvodné zvukové správy
- Prezentujte možnosti interaktívneho menu
- Spracovať odpovede na stlačenie klávesov DTMF (0-9, *, #)
- Definujte vlastné správanie pre neplatné / časové limity vstupov
- Spúšťajte webhooky s vlastnými telami a hlavičkami na základe výberu používateľa
- Dynamicky spravujte tok hovorov (prechádzajte medzi ponukami)
Prípady použitia
- Zákaznícke prieskumy - Zhromažďujte spätnú väzbu prostredníctvom možností ponuky telefónu
- Pripomenutia schôdzky - Potvrďte alebo preplánujte pomocou hlasovej interakcie
- Sledovanie objednávok - Poskytujte aktualizácie stavu objednávky
- Interaktívne upozornenia - Poskytujte dôležité informácie s možnosťami akcií
- Voice Verification - Viacfaktorové overenie prostredníctvom hlasových hovorov
Formát žiadosti
Základná štruktú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"
}
]
}
}
]
}
]
}
Popis parametra
| Parameter | Typ | povinné | Popis |
|---|---|---|---|
| ”od” | reťazec | áno | Identifikátor odosielateľa (alfa názov alebo ID) |
| “do” | reťazec | áno | Telefónne číslo príjemcu v medzinárodnom formáte |
| ”text” | reťazec | áno | Textová hodnota, zvyčajne “ivr” pre SpeechCall |
| ”typ” | reťazec | áno | Musí to byť "hovorový hovor" |
| ”menu” | pole | áno | Súbor konfigurácií menu pre hovor |
Konfigurácia ponuky
Každý objekt ponuky obsahuje:
| Parameter | Typ | povinné | Popis |
|---|---|---|---|
| ”introUrl” | reťazec | áno | URL alebo identifikátor úvodného zvukového súboru |
idleTimeoutMsec | celé číslo | Nie | Časový limit v milisekundách na čakanie na stlačenie klávesu (napr. „10000“). Ak používateľ neodpovie, vykonajú sa akcie nakonfigurované pod klávesom nesprávny |
dtmfActions | objekt | áno | Mapa DTMF klávesov k akciám |
DTMF akcie
Objekt dtmfActions mapuje DTMF kľúče alebo špeciálne podmienky na polia akcií:
| DTMF kľúč | Popis |
|---|---|
| ”d0” | Stlačte 0 |
d1 | Stlačte 1 |
| ”d2” | Stlačte 2 |
| … | … |
| “d9” | Stlačte 9 |
d* | Stlačte * |
d# | Stlačte # |
| “nesprávne” | Spustí sa po stlačení neplatného klávesu alebo po dosiahnutí idleTimeoutMsec bez akéhokoľvek vstupu |
Každý kľúč/podmienka DTMF sa mapuje na pole akcií, ktoré sa vykonajú postupne.
Podporované akcie
| Akcia | Parametre | Popis |
|---|---|---|
| ”webhook” | url (reťazec, povinné)body (objekt, voliteľné)hlavičky (objekt, voliteľné) | Odošle požiadavku HTTP POST vo formáte JSON na zadanú adresu URL. Objekt „body“ bude vnorený do poľa „action“ v požiadavke webhooku. Vlastné hlavičky sú zahrnuté ako hlavičky HTTP. |
| ”zavesiť” | Žiadne | Ukončí hovor |
gotoMenu | menu (reťazec alebo celé číslo) | Prejde volanie do inej ponuky v poli menu pomocou indexu založeného na 0 (napr. "1") |
Podrobné akčné správanie
Akcia webhooku („webhook“)
Akcia „webhook“ odošle požiadavku HTTP POST na vašu adresu URL spätného volania s metadátami hovoru a voliteľnými vlastnými údajmi: – Ak je zadané „telo“, jeho páry kľúč – hodnota sa odošlú do poľa „akcia“ tela užitočného zaťaženia.
- Ak sú zadané „hlavičky“, odošlú sa ako vlastné hlavičky HTTP v požiadavke.
Akcia zavesenia (zavesenie)
Akcia zavesiť okamžite ukončí aktívny hovor. Po akcii „zavesiť“ nebudú spracované žiadne ďalšie akcie v poradí alebo ponukách.
Prejsť na akciu ponuky (gotoMenu)
Akcia „gotoMenu“ presmeruje tok hovoru do inej štruktúry ponuky v rámci poľa „menu“. Vyžaduje jeden parameter „menu“, ktorý určuje index cieľovej ponuky na základe 0 (napr. „1“ na prechod do druhej ponuky alebo „0“ na reštartovanie prvej ponuky).
Nečinnosť a riešenie chýb (nesprávne)
nesprávny kľúč v dtmfActions je špeciálna obslužná rutina. Vykoná svoju sekvenciu akcií v dvoch scenároch:
- Neplatný vstup: Volajúci stlačí kláves DTMF, ktorý nie je definovaný v
dtmfActions(napríklad stlačí3, ale ponuka definuje lend1ad2). - Časový limit nečinnosti: Volajúci nestlačí žiadne tlačidlo počas trvania určeného parametrom
idleTimeoutMsec.
Ak nie je definované „nesprávne“ a volajúci stlačí neplatný kláves alebo uplynie časový limit, tok hovoru sa predvolene zavesí. Definovanie „nesprávneho“ vám umožňuje vytvárať ponuky v slučke (napr. návrat do rovnakej ponuky pomocou „akcie“: „gotoMenu“, „menu“: „0“`) alebo presmerovanie používateľa do ponuky pomocníka.
Formát doručenia webhooku
Keď sa spustí akcia webhook, systém odošle požiadavku HTTP POST na nakonfigurovanú url s Content-Type: application/json.
Hlavičky požiadaviek webhooku
Ak je akcia nakonfigurovaná pomocou parametra headers, tieto páry kľúč – hodnota sú zahrnuté ako hlavičky HTTP v požiadavke.
Telo žiadosti o webhook
Dáta JSON odoslaná na vašu webovú adresu webhooku má nasledujúcu štruktúru:
{
"from": "0443914272",
"to": "50001",
"mid": "7748021",
"action": {
"confirm": true
}
}
| Pole | Typ | Popis |
|---|---|---|
| ”od” | reťazec | Telefónne číslo volajúceho / ID odosielateľa |
| ”do” | reťazec | Telefónne číslo príjemcu |
| ”stred” | reťazec | ID správy |
| ”akcia” | objekt | Vlastný objekt JSON definovaný v poli „telo“ akcie |
Úplný príklad
Jednoduché IVR s časovým limitom a overením vstupu
{
"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"
}
]
}
}
]
}
]
}
Komplexné IVR s viacerými ponukami a DTMF smerovaním
Tento príklad ukazuje, ako definovať viacero ponúk a navigovať medzi nimi pomocou akcie gotoMenu, keď používateľ zadá neplatný kľúč alebo keď uplynie časový limit hovoru. Zobrazuje tiež vlastné telá a vlastné hlavičky HTTP odoslané so spúšťačmi webhooku.
{
"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"
}
]
}
}
]
}
]
}
Formát odpovede
Úspešná odpoveď
{
"messages": [
{
"messageId": "unique-message-id",
"recipient": "+380XXXXXXXXX",
"status": "sent"
}
]
}
Spracovanie chýb
| Stav HTTP | Popis |
|---|---|
| 200 | Žiadosť úspešná |
| 400 | Neplatný formát požiadavky |
| 401 | Autentifikácia zlyhala |
| 429 | Prekročený limit sadzby |
| 500 | Interná chyba servera |
príklad cURL
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"
}
]
}
}
]
}
]
}'
Osvedčené postupy
- Zvukové súbory – Uistite sa, že úvodné adresy URL sú prístupné a zvukové súbory sú v podporovaných formátoch
- Spoľahlivosť webhooku – Navrhnite webhooky tak, aby reagovali rýchlo (do 2 sekúnd)
- Možnosti DTMF – Obmedzte možnosti ponuky na 4 až 6 možností pre lepšiu používateľskú skúsenosť
- Spracovanie časového limitu – Použite „idleTimeoutMsec“ na zadanie vlastných limitov nečinnosti (napr. 10 000 ms) a nakonfigurujte plynulý návrat pod „nesprávnym“ DTMF klávesom (napríklad opakovanie ponuky alebo zavesenie)
- Tok hovorov vo viacerých ponukách – Opatrne používajte „gotoMenu“, aby ste predišli nekonečným slučkám pri smerovaní používateľov späť do predchádzajúcich ponúk
- Záložná stratégia – Použite záložné správy pre používateľov, ktorí neodpovedajú alebo sa neodpoja
Súvisiace témy
- Odoslať správu - Všeobecný sprievodca odosielaním správ – Flash Call – Jednoduché hlasové overovacie hovory
- Skontrolovať stav - Sledujte stav doručenia správy – Typy správ – Prehľad všetkých podporovaných typov správ