Zprávy SpeechCall
SpeechCall je typ zprávy interaktivní hlasové odezvy (IVR), který vám umožňuje provádět automatické hlasové hovory s možnostmi nabídky a interakcí DTMF (dual-tone multi-frequency).
Přehled
SpeechCall umožňuje firmám:
- Provádějte automatizované hlasové hovory se zákazníky
- Přehrajte úvodní zvukové zprávy
- Prezentujte možnosti interaktivní nabídky
- Zpracovat odezvy DTMF kláves (0-9, *, #)
- Definujte vlastní chování pro neplatné/časové vstupy
- Spouštět webhooky s vlastními těly a záhlavími na základě uživatelských výběrů
- Dynamická správa toku hovorů (procházení mezi nabídkami)
Případy použití
- Zákaznické průzkumy - Získejte zpětnou vazbu prostřednictvím možností nabídky telefonu
- Připomenutí schůzek - Potvrďte nebo přeplánujte pomocí hlasové interakce
- Sledování objednávek - Poskytujte aktualizace stavu objednávky
- Interaktivní oznámení - Poskytujte důležité informace s možnostmi akcí
- Voice Verification - Vícefaktorové ověřování prostřednictvím hlasových hovorů
Formát požadavku
Základní 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"
}
]
}
}
]
}
]
}
Popis parametru
| Parametr | Typ | Povinné | Popis |
|---|---|---|---|
| ”od” | řetězec | Ano | Identifikátor odesílatele (alfa název nebo ID) |
do | řetězec | Ano | Telefonní číslo příjemce v mezinárodním formátu |
| ”text” | řetězec | Ano | Textová hodnota, obvykle “ivr” pro SpeechCall |
| ”typ” | řetězec | Ano | Musí být "hovorový hovor" |
menu | pole | Ano | Pole konfigurací menu pro volání |
Konfigurace nabídky
Každý objekt nabídky obsahuje:
| Parametr | Typ | Povinné | Popis |
|---|---|---|---|
| ”introUrl” | řetězec | Ano | URL nebo identifikátor úvodního zvukového souboru |
idleTimeoutMsec | celé číslo | Ne | Časový limit v milisekundách pro čekání na stisknutí klávesy (např. „10000“). Pokud uživatel nereaguje, budou provedeny akce nakonfigurované pod špatným klíčem |
dtmfActions | objekt | Ano | Mapa DTMF kláves k akcím |
DTMF akce
Objekt dtmfActions mapuje DTMF klíče nebo speciální podmínky na pole akcí:
| DTMF klíč | Popis |
|---|---|
| ”d0” | Stiskněte 0 |
| ”d1” | Stiskněte 1 |
| ”d2” | Stiskněte 2 |
| … | … |
| “d9” | Stiskněte 9 |
d* | Stiskněte * |
d# | Stiskněte # |
| “špatně” | Spustí se, když je stisknuto neplatné tlačítko nebo když je dosaženo idleTimeoutMsec bez jakéhokoli zadání |
Každý klíč/podmínka DTMF se mapuje na pole akcí, které budou postupně provedeny.
Podporované akce
| Akce | Parametry | Popis |
|---|---|---|
webhook | url (řetězec, povinné)tělo (objekt, volitelné)záhlaví (objekt, volitelné) | Odešle požadavek HTTP POST ve formátu JSON na zadanou adresu URL. Objekt body bude vnořen pod pole action v požadavku webhooku. Vlastní hlavičky jsou zahrnuty jako hlavičky HTTP. |
| ”zavěšení” | Žádné | Ukončí hovor |
gotoMenu | menu (řetězec nebo celé číslo) | Přesune volání do jiné nabídky v poli menu pomocí indexu založeného na 0 (např. "1") |
Detailní akční chování
Akce webhooku (webhook)
Akce webhook odešle požadavek HTTP POST na vaši adresu URL zpětného volání s metadaty volání a volitelnými vlastními daty:
- Pokud je zadáno „tělo“, jeho páry klíč–hodnota se odesílají do pole „akce“ těla užitečného zatížení.
- Pokud jsou zadány
hlavičky, jsou v požadavku odeslány jako vlastní HTTP hlavičky.
Akce zavěšení (zavěšení)
Akce zavěšení okamžitě ukončí aktivní hovor. Po akci „zavěšení“ nebudou zpracovány žádné další akce v sekvenci nebo nabídkách.
Přejít do nabídky Akce (gotoMenu)
Akce gotoMenu přesměruje tok volání do jiné struktury nabídky v poli menu. Vyžaduje jeden parametr menu, který určuje index cílové nabídky založený na 0 (např. "1" pro přechod do druhé nabídky nebo "0" pro restartování první nabídky).
Nečinnost a zpracování chyb (špatné)
špatný klíč v dtmfActions je speciální obslužný program pro případ pádu. Svou řadu akcí provádí ve dvou scénářích:
- Neplatný vstup: Volající stiskne klávesu DTMF, která není definována v
dtmfActions(například stisknou3, ale nabídka definuje pouzed1ad2). - Časový limit nečinnosti: Volající nestiskne žádnou klávesu po dobu určenou parametrem
idleTimeoutMsec.
Pokud není definováno špatně a volající stiskne neplatnou klávesu nebo vyprší časový limit, tok volání se ve výchozím nastavení zavěsí. Definování špatného vám umožní vytvořit cyklické nabídky (např. návrat do stejné nabídky pomocí "action": "gotoMenu", "menu": "0") nebo přesměrování uživatele do nabídky nápovědy.
Webhookový formát doručení
Když je spuštěna akce webhook, systém odešle požadavek HTTP POST na nakonfigurovanou url s Content-Type: application/json.
Záhlaví požadavků webhooku
Pokud je akce nakonfigurována pomocí parametru headers, jsou tyto páry klíč–hodnota zahrnuty jako záhlaví HTTP v požadavku.
Tělo požadavku webhooku
Datový obsah JSON odeslaný na adresu URL vašeho webhooku má následující strukturu:
{
"from": "0443914272",
"to": "50001",
"mid": "7748021",
"action": {
"confirm": true
}
}
| Pole | Typ | Popis |
|---|---|---|
| ”od” | řetězec | Telefonní číslo volajícího / ID odesílatele |
do | řetězec | Telefonní číslo příjemce |
| ”střední” | řetězec | ID zprávy |
| ”akce” | objekt | Vlastní objekt JSON definovaný v poli body akce |
Úplný příklad
Jednoduché IVR s časovým limitem a ověření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 více nabídkami a směrováním DTMF
Tento příklad ukazuje, jak definovat více nabídek a procházet mezi nimi pomocí akce gotoMenu, když uživatel zadá neplatný klíč nebo když vyprší časový limit volání. Zobrazuje také vlastní těla a vlastní záhlaví HTTP odeslaná s aktivačními událostmi 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 odpovědi
Úspěšná odpověď
{
"messages": [
{
"messageId": "unique-message-id",
"recipient": "+380XXXXXXXXX",
"status": "sent"
}
]
}
Zpracování chyb
| Stav HTTP | Popis |
|---|---|
| 200 | Žádost byla úspěšná |
| 400 | Neplatný formát požadavku |
| 401 | Ověření se nezdařilo |
| 429 | Překročen limit sazby |
| 500 | Interní chyba serveru |
Pří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"
}
]
}
}
]
}
]
}'
Nejlepší postupy
- Audio soubory – Ujistěte se, že jsou přístupné úvodní adresy URL a že zvukové soubory jsou v podporovaných formátech
- Spolehlivost webhooku – Navrhněte webhooky tak, aby reagovaly rychle (do 2 sekund)
- Možnosti DTMF – Omezte možnosti nabídky na 4–6 možností pro lepší uživatelskou zkušenost
- Zpracování časového limitu – Pomocí
idleTimeoutMsecspecifikujte vlastní limity nečinnosti (např. 10000 ms) a nakonfigurujte elegantní nouzový režim podnesprávnýmDTMF klíčem (jako je opakování nabídky nebo zavěšení) - Tok hovorů ve více nabídkách – Opatrně používejte „gotoMenu“, abyste předešli nekonečným smyčkám při směrování uživatelů zpět do předchozích nabídek
- Záložní strategie – Použijte záložní zprávy pro uživatele, kteří neodpovídají nebo se neodpojí
Související témata
- Odeslat zprávu - Obecný průvodce odesíláním zpráv – Flash Call – Jednoduché hlasové ověřovací hovory
- Kontrola stavu - Sledovat stav doručení zpráv – Typy zpráv – Přehled všech podporovaných typů zpráv