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": "BazarCOM",
"to": "+380936670003",
"text": "ivr",
"type": "speechcall",
"menu": [
{
"introUrl": "ivr_651854",
"idleTimeoutMsec": 10000,
"dtmfActions": {
"d1": [
{
"action": "webhook",
"url": "https://api.example.com/callback/option1",
"body": {
"confirm": true
},
"headers": {
"X-Custom-Header": "value"
}
},
{
"action": "hangup"
}
],
"d2": [
{
"action": "webhook",
"url": "https://api.example.com/callback/option2",
"body": {
"confirm": false
}
},
{
"action": "hangup"
}
],
"wrong": [
{
"action": "hangup"
}
]
}
}
]
}
]
}
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") |
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:
| 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": "BazarCOM",
"to": "+380936670003",
"text": "ivr",
"type": "speechcall",
"menu": [
{
"introUrl": "ivr_651854",
"idleTimeoutMsec": 10000,
"dtmfActions": {
"d1": [
{
"action": "webhook",
"url": "https://api.example.com/callback/option1",
"body": {
"confirm": true
}
},
{
"action": "hangup"
}
],
"d2": [
{
"action": "webhook",
"url": "https://api.example.com/callback/option2",
"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_651854",
"idleTimeoutMsec": 10000,
"dtmfActions": {
"d1": [
{
"action": "webhook",
"url": "http://api.smsbat.local/gatereq/temp/hook",
"body": {
"confirm": true
},
"headers": {
"test-header": "test"
}
},
{
"action": "hangup"
}
],
"d2": [
{
"action": "webhook",
"url": "http://api.smsbat.local/gatereq/temp/hook",
"body": {
"confirm": false
}
},
{
"action": "hangup"
}
],
"wrong": [
{
"action": "gotoMenu",
"menu": "1"
}
]
}
},
{
"introUrl": "ivr_651854",
"idleTimeoutMsec": 10000,
"dtmfActions": {
"d1": [
{
"action": "webhook",
"url": "http://localhost/1"
}
],
"d2": [
{
"action": "webhook",
"url": "http://localhost/1"
}
],
"wrong": [
{
"action": "hangup"
}
]
}
}
]
}
]
}
Formát odpovede
Úspešná odpoveď
{
"messages": [
{
"messageId": "unique-message-id",
"recipient": "+380936670003",
"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_651854",
"idleTimeoutMsec": 10000,
"dtmfActions": {
"d1": [
{
"action": "webhook",
"url": "http://api.smsbat.local/gatereq/temp/hook",
"body": {
"confirm": true
},
"headers": {
"test-header": "test"
}
},
{
"action": "hangup"
}
],
"d2": [
{
"action": "webhook",
"url": "http://api.smsbat.local/gatereq/temp/hook",
"body": {
"confirm": false
}
},
{
"action": "hangup"
}
],
"wrong": [
{
"action": "gotoMenu",
"menu": "1"
}
]
}
},
{
"introUrl": "ivr_651854",
"idleTimeoutMsec": 10000,
"dtmfActions": {
"d1": [
{
"action": "webhook",
"url": "http://localhost/1"
}
],
"d2": [
{
"action": "webhook",
"url": "http://localhost/1"
}
],
"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