Повідомлення SpeechCall

SpeechCall — це повідомлення типу інтерактивної голосової відповіді (IVR), яке дозволяє здійснювати автоматичні голосові виклики за допомогою опцій меню та взаємодії DTMF (двотональний багаточастотний).

Огляд

SpeechCall дозволяє компаніям: - Здійснюйте автоматичні голосові дзвінки клієнтам - Відтворення вступних звукових повідомлень - Наявність інтерактивних параметрів меню - Обробляти відповіді на натискання клавіш DTMF (0-9, *, #) — Визначте спеціальну поведінку для недійсних вводів/затримок - Запускайте веб-хуки з власними тілами та заголовками на основі вибору користувача - Динамічне керування потоком викликів (переміщення між меню)

Випадки використання

Опитування клієнтів - Збирайте відгуки за допомогою параметрів меню телефону
Нагадування про зустрічі - підтвердьте або перенесіть за допомогою голосової взаємодії
Відстеження замовлень - Оновлення статусу замовлення
Інтерактивні сповіщення - надайте важливу інформацію за допомогою варіантів дій
Голосова перевірка - багатофакторна автентифікація за допомогою голосових дзвінків

Формат запиту

Базова структура

{
  "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"
              }
            ]
          }
        }
      ]
    }
  ]
}

Опис параметра

Параметр	Тип	Необхідно	Опис
`від`	рядок	Так	Ідентифікатор відправника (альфа-ім’я або ідентифікатор)
`до`	рядок	Так	Номер телефону отримувача в міжнародному форматі
`текст`	рядок	Так	Текстове значення, зазвичай "ivr" для SpeechCall
`тип`	рядок	Так	Має бути `"speechcall"`
`меню`	масив	Так	Масив конфігурацій меню для виклику

Конфігурація меню

Кожен об'єкт меню містить:

Параметр	Тип	Необхідно	Опис
`introUrl`	рядок	Так	URL-адреса або ідентифікатор вступного аудіофайлу
`idleTimeoutMsec`	ціле	Ні	Час очікування в мілісекундах для очікування натискання клавіші (наприклад, `10000`). Якщо користувач не відповідає, дії, налаштовані під ключем `wrong`, будуть виконані
`dtmfActions`	об'єкт	Так	Карта DTMF ключів до дій

Дії DTMF

Об’єкт dtmfActions відображає ключі DTMF або спеціальні умови на масиви дій:

Ключ DTMF	Опис
`d0`	Натисніть 0
`d1`	Натисніть 1
`d2`	Натисніть 2
...	...
`d9`	Натисніть 9
`d*`	Натисніть *
`d#`	Натисніть #
`неправильно`	Спрацьовує, коли натиснуто недійсну клавішу або коли `idleTimeoutMsec` досягнуто без жодного введення

Кожен ключ/умова DTMF відповідає масиву дій, які виконуватимуться послідовно.

Підтримувані дії

Дія	Параметри	Опис
`вебхук`	`url` (рядок, обов’язково) `body` (об’єкт, необов’язково) `headers` (об’єкт, необов’язково)	Надсилає запит HTTP POST у форматі JSON на вказану URL-адресу. Об’єкт `body` буде вкладено під поле `action` у запиті на вебхук. Спеціальні заголовки включені як заголовки HTTP.
`зависання`	Жодного	Завершує дзвінок
`gotoMenu`	`menu` (рядок або ціле число)	Переміщує виклик до іншого меню в масиві `menu`, використовуючи його індекс на основі 0 (наприклад, `"1")

Формат доставки Webhook

Коли активується дія webhook, система надсилає запит HTTP POST на налаштовану url з Content-Type: application/json.

Заголовки запитів на вебхук

Якщо дію налаштовано за допомогою параметра headers, ці пари ключ-значення включено в запит як заголовки HTTP.

Тіло запиту на вебхук

Корисне навантаження JSON, надіслане на вашу URL-адресу webhook, має таку структуру:

{
  "from": "0443914272",
  "to": "50001",
  "mid": "7748021",
  "action": {
    "confirm": true
  }
}

Поле	Тип	Опис
`від`	рядок	Номер телефону абонента / ідентифікатор відправника
`до`	рядок	Номер телефону одержувача
`середина`	рядок	ID повідомлення
`дія`	об'єкт	Спеціальний об’єкт JSON, визначений у полі `body` дії

Повний приклад

Простий IVR із тайм-аутом і перевіркою введених даних

{
  "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"
              }
            ]
          }
        }
      ]
    }
  ]
}

Комплексний IVR з кількома меню та маршрутизацією DTMF

Цей приклад демонструє, як визначити кілька меню та переходити між ними за допомогою дії gotoMenu, коли користувач вводить недійсний ключ або коли час очікування виклику минув. Він також показує спеціальні тіла та спеціальні HTTP-заголовки, надіслані за допомогою тригерів вебхука.

{
  "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"
              }
            ]
          }
        }
      ]
    }
  ]
}

Формат відповіді

Успішна відповідь

{
  "messages": [
    {
      "messageId": "unique-message-id",
      "recipient": "+380936670003",
      "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_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"
                }
              ]
            }
          }
        ]
      }
    ]
  }'

Найкращі практики

Аудіофайли - переконайтеся, що вступні URL-адреси доступні, а аудіофайли мають підтримуваний формат
Надійність веб-перехоплювачів - розробляйте веб-перехоплювачі для швидкого реагування (протягом 2 секунд)
Параметри DTMF - обмежте параметри меню до 4-6 варіантів для кращої взаємодії з користувачем
Обробка часу очікування – використовуйте idleTimeoutMsec, щоб указати користувацькі обмеження бездіяльності (наприклад, 10000 мс), і налаштувати витончений резервний варіант під неправильним ключем DTMF (наприклад, повторення меню або відключення)
Потік викликів кількох меню - обережно використовуйте gotoMenu, щоб запобігти нескінченним циклам під час перенаправлення користувачів назад до попередніх меню
Резервна стратегія - використовуйте резервні повідомлення для користувачів, які не відповідають або відключаються

Схожі теми

Надіслати повідомлення - Загальний посібник із надсилання повідомлень
Флеш-дзвінок - Прості дзвінки з голосовою перевіркою
Перевірити статус - Відстежувати статус доставки повідомлення
Типи повідомлень - Огляд усіх підтримуваних типів повідомлень