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": "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 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") |
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:
| 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": "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 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_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 odpovědi
Úspěšná odpověď
{
"messages": [
{
"messageId": "unique-message-id",
"recipient": "+380936670003",
"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_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"
}
]
}
}
]
}
]
}'
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ávnouklávesou DTMF (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