SpeechCall съобщения
SpeechCall е тип съобщение с интерактивен гласов отговор (IVR), което ви позволява да извършвате автоматизирани гласови повиквания с опции от менюто и DTMF (двутонални многочестотни) взаимодействия.
Преглед
SpeechCall позволява на бизнеса да:
- Правете автоматизирани гласови повиквания към клиенти
- Възпроизвеждане на уводни аудио съобщения
- Представяне на интерактивни опции на менюто
- Обработка на DTMF отговори при натискане на клавиши (0-9, *, #)
- Определете персонализирано поведение за невалидни входове/изчакване
- Задействайте уеб кукички с персонализирани тела и заглавки въз основа на потребителски избор
- Динамично управление на потока на обажданията (придвижване между менютата)
Случаи на употреба
- Проучвания на клиенти - Събирайте отзиви чрез опциите на менюто на телефона
- Напомняния за срещи - Потвърдете или пренасрочете с гласово взаимодействие
- Проследяване на поръчки - Предоставяне на актуализации на състоянието на поръчката
- Интерактивни известия - Предоставяне на важна информация с опции за действие
- Гласова проверка - Многофакторно удостоверяване чрез гласови повиквания
Формат на заявката
Основна структура
{
"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"
}
]
}
}
]
}
]
}
Описание на параметъра
| Параметър | Тип | Задължително | Описание |
|---|---|---|---|
from | низ | Да | Идентификатор на изпращача (алфа име или ID) |
to | низ | Да | Телефонен номер на получателя в международен формат |
text | низ | Да | Текстова стойност, обикновено “ivr” за SpeechCall |
type | низ | Да | Трябва да е "speechcall" |
menu | масив | Да | Масив от конфигурации на менюто за разговор |
Конфигурация на менюто
Всеки обект от менюто съдържа:
| Параметър | Тип | Задължително | Описание |
|---|---|---|---|
introUrl | низ | Да | URL или идентификатор на уводния аудио файл |
idleTimeoutMsec | цяло число | Не | Време за изчакване в милисекунди за изчакване на натискане на клавиш (напр. 10000). Ако потребителят не отговори, ще бъдат изпълнени действията, конфигурирани под клавиша wrong |
dtmfActions | обект | Да | Карта на DTMF ключове за действия |
DTMF действия
Обектът dtmfActions картографира DTMF ключове или специални условия към масиви от действия:
| DTMF ключ | Описание |
|---|---|
d0 | Натиснете 0 |
d1 | Натиснете 1 |
d2 | Натиснете 2 |
| … | … |
d9 | Натиснете 9 |
d* | Натиснете * |
d# | Натиснете # |
wrong | Задейства се при натискане на невалиден клавиш или при достигане на idleTimeoutMsec без никакво въвеждане |
Всеки DTMF ключ/условие се свързва с масив от действия, които ще бъдат изпълнени последователно.
Поддържани действия
| Действие | Параметри | Описание |
|---|---|---|
webhook | url (низ, задължително)body (обект, по избор)headers (обект, по избор) | Изпраща HTTP POST заявка във формат JSON до посочения URL адрес. Обектът body ще бъде вложен под полето action в заявката за webhook. Персонализираните заглавки са включени като HTTP заглавки. |
hangup | Няма | Прекратява разговора |
gotoMenu | menu (низ или цяло число) | Навигира извикването към друго меню в масива menu, използвайки неговия базиран на 0 индекс (напр. "1") |
Подробно поведение на действието
Действие на Webhook (webhook)
Действието webhook изпраща HTTP POST заявка до вашия URL адрес за обратно извикване с метаданни за повикване и незадължителни персонализирани данни:
- Ако е предоставен
body, неговите двойки ключ-стойност се изпращат вътре в полетоactionна тялото на полезния товар. - Ако са предоставени
headers, те се изпращат като персонализирани HTTP заглавки в заявката.
Действие при прекъсване (hangup)
Действието hangup незабавно прекратява активното повикване. Никакви други действия в последователността или менютата няма да бъдат обработени след действие hangup.
Отидете в менюто Действие (gotoMenu)
Действието gotoMenu пренасочва потока на повикването към различна структура на менюто в рамките на масива menu. Необходим е един параметър menu, който определя базирания на 0 индекс на целевото меню (напр. "1" за преминаване към второто меню или "0" за рестартиране на първото меню).
Бездействие и обработка на грешки (wrong)
Ключът wrong вътре в dtmfActions е специален манипулатор на падане. Той изпълнява своя масив от последователност от действия в два сценария:
- Невалидно въвеждане: Повикващият натиска DTMF клавиш, който не е дефиниран в
dtmfActions(например, те натискат3, но менюто дефинира самоd1иd2). - Idle Timeout: Повикващият не натиска нито един клавиш в рамките на продължителността, определена от
idleTimeoutMsec.
Ако wrong не е дефиниран и повикващият натисне невалиден клавиш или изтече времето, потокът на повикванията ще затвори по подразбиране. Дефинирането на wrong ви позволява да създавате циклични менюта (напр. връщане към същото меню с "action": "gotoMenu", "menu": "0") или пренасочване на потребителя към помощно меню.
Формат за доставка на Webhook
Когато се задейства действието webhook, системата изпраща HTTP POST заявка към конфигурирания url с Content-Type: application/json.
Заглавки на заявка за уеб кукичка
Ако действието е конфигурирано с параметъра headers, тези двойки ключ-стойност са включени като HTTP заглавки в заявката.
Тяло на заявката за уеб кукичка
JSON полезният товар, изпратен до вашия URL адрес на уеб кукичка, има следната структура:
{
"from": "0443914272",
"to": "50001",
"mid": "7748021",
"action": {
"confirm": true
}
}
| Поле | Тип | Описание |
|---|---|---|
from | низ | Телефонен номер на обаждащия се / ID на изпращача |
to | низ | Телефонен номер на получателя |
mid | низ | ID на съобщение |
action | обект | Персонализираният JSON обект, дефиниран в полето body на действието |
Пълен пример
Обикновено IVR с изчакване и проверка на входа
{
"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"
}
]
}
}
]
}
]
}
Комплексен IVR с множество менюта и DTMF маршрутизиране
Този пример демонстрира как да дефинирате множество менюта и да навигирате между тях, като използвате действието gotoMenu, когато потребителят въведе невалиден ключ или когато времето за извикване изтече. Той също така показва персонализирани тела и персонализирани HTTP заглавки, изпратени с тригерите на webhook.
{
"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"
}
]
}
}
]
}
]
}
Формат на отговора
Успешен отговор
{
"messages": [
{
"messageId": "unique-message-id",
"recipient": "+380XXXXXXXXX",
"status": "sent"
}
]
}
Обработка на грешки
| Състояние на HTTP | Описание |
|---|---|
| 200 | Успешна заявка |
| 400 | Невалиден формат на заявката |
| 401 | Неуспешно удостоверяване |
| 429 | Лимитът на скоростта е надвишен |
| 500 | Вътрешна грешка в сървъра |
пример за 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"
}
]
}
}
]
}
]
}'
Най-добри практики
- Аудио файлове - Уверете се, че въвеждащите URL адреси са достъпни и аудио файловете са в поддържани формати
- Надеждност на уебкукичките - Проектирайте уебкукичките, за да реагират бързо (в рамките на 2 секунди)
- DTMF Опции - Ограничете опциите на менюто до 4-6 избора за по-добро потребителско изживяване
- Обработка на изчакване - Използвайте
idleTimeoutMsec, за да зададете персонализирани лимити на неактивност (напр. 10000 ms) и конфигурирайте грациозно резервно връщане подwrongDTMF клавиша (като повтаряне на менюто или затваряне) - Поток на повикване с множество менюта - Използвайте
gotoMenuвнимателно, за да предотвратите безкрайни цикли, когато пренасочвате потребителите обратно към предишни менюта - Резервна стратегия - Използвайте резервни съобщения за потребители, които не отговарят или прекъсват връзката
Свързани теми
- Изпращане на съобщение - Общо ръководство за изпращане на съобщения
- Бързо обаждане - Лесни обаждания за гласово потвърждение
- Проверете състоянието - Проследете състоянието на доставката на съобщението
- Типове съобщения - Преглед на всички поддържани типове съобщения