Инструкция рассчитана на технических специалистов, которые настраивают интеграцию. Полное описание методов API с параметрами, примерами запросов и ответов находится в технической документации.
| Термин | Что это |
|---|---|
| API | Программный интерфейс Robovoice. Через него ваши системы обмениваются данными с платформой. |
| ЛК | Личный кабинет Robovoice. |
| Сценарий | Алгоритм диалога робота с контактом. В запросах определяется параметром scriptId. |
| Кампания | Массовый обзвон группы контактов с индивидуальными настройками запуска. |
| Группа контактов | Список контактов, который загружается в кампанию. |
| Контакт | Абонент, которому звонит робот. Определяется номером телефона (account) или идентификатором в Robovoice (id). |
| Callback | Обратный вызов: так Robovoice передаёт данные о звонке в вашу систему. |
| Часовой пояс контакта | Платформа определяет его по номеру телефона контакта. |
| Timestamp | Дата и время в формате Unix-времени: количество секунд, прошедших с 01.01.1970 (UTC). |
Через API обзвон можно организовать двумя способами: запускать его со своей стороны или поручить запуск стороне Robovoice.
В этом варианте создаётся интеграционный шлюз — промежуточное звено между вашей системой и Robovoice. Шлюз получает из вашей системы базу контактов для обзвона и отправляет туда результаты, а звонки совершает через методы API Robovoice по алгоритму, описанному ниже.
Этот вариант требует больше трудозатрат: состав работ и условия их выполнения фиксируются договором. Для него в вашей системе должны быть методы API, которые позволяют:
Ваша система сама отправляет контакты в Robovoice и забирает результаты. Этот вариант мы рекомендуем: он позволяет заранее отфильтровать контакты для обзвона, а результаты сразу попадают в вашу систему, где хранятся исходные данные. Обращаться к API вашей системы при этом не нужно. Способы запуска и получения результатов описаны ниже.
Если обзвон запускаете вы, звонки можно запускать двумя способами: единичными звонками без кампании (метод /scripts/invoke) или массовым обзвоном с созданием кампании. Сравнение способов:
| Критерий | Способ 1: метод /scripts/invoke | Способ 2: кампания |
|---|---|---|
| Часовой пояс контакта | Не учитывается. Значение startDate нужно указывать уже с учётом часового пояса контакта. | Учитывается платформой при загрузке контактов в кампанию. |
| Дата и время начала обзвона | Задаются параметром startDate (по UTC+00:00). Если параметр не заполнен, звонок выполняется сразу после запроса. | Задаются в настройках кампании, звонки выполняются с учётом часового пояса контакта. |
| Автоматический перезвон, если соединение не установлено | Не поддерживается. Перезвоны организуются на вашей стороне по результатам обзвона. | Перезвоны организуются на вашей стороне по результатам обзвона. |
| Количество одновременных звонков, звонки в выходные и праздничные дни | Не регулируется. | Настраивается в кампании. |
| Аналитика в ЛК | Звонки в ЛК не отображаются. Аналитику нужно собирать на своей стороне или через отдельный сервис кастомизированных отчётов. | Кампании сохраняются в ЛК. Доступны гибкая настройка аналитики и просмотр диалогов в режиме онлайн. |
| Сложность реализации | Минимальная: нужен один метод. | Выше: используется последовательность методов. |
Метод POST /scripts/invoke совершает единичные звонки. Это самый быстрый в реализации способ: нужен всего один метод. Учтите его ограничения:
| Шаг | Метод | Что делает |
|---|---|---|
| 1 | POST /groups | Создаёт группу контактов. |
| 2 | POST /groups/{id}/contacts | Создаёт контакты и добавляет их в существующую группу. |
| 3 | POST /campaign/ | Создаёт кампанию. |
| 4 | POST /campaigns/{id}/groups | Добавляет группу контактов в существующую кампанию. |
| 5 | GET /campaign/start/{id} | Запускает кампанию. |
После первого создания кампании запуск следующих можно ускорить: метод POST /campaigns/{id}/copy копирует созданную ранее кампанию вместе с настроенными целями аналитики. Подробное описание методов, их параметров и примеров запросов и ответов — в технической документации API.
Полное описание методов API Robovoice, включая параметры, примеры запросов и ответов, находится в технической документации. Вернуться к разделу — Интеграция (API).
Этот способ удобен, если обзвон запускается методом /scripts/invoke. Алгоритм тот же, что и для результатов за период, только первый шаг другой. Вместо метода GET /calls используйте GET /call/info/{id} («Получить информацию о звонке»): по значению callId он возвращает dialogId. Дальше вызовите GET /dialog/{id}: по значению dialogId метод вернёт список заполненных параметров.
{
"callId": "d577f284-7e39-4ce4-8d4a-26bcc1bb0cb1",
"source": "79000000000",
"destination": "1785",
"campaignId": "8988eb4b-be56-439a-bf4e-f09cbc5cabf2",
"scriptId": "0ae6cfe7-6af6-425c-a8dd-630f5899edc1",
"contactId": "358f9df2-ad43-41b2-8fff-4ed83cecc5f1",
"startCall": "2023-08-03 07:24:40 +0000 UTC",
"endCall": "2023-08-03 07:26:16 +0000 UTC",
"talkTime": 68,
"dialogId": "7c21976e-aea4-4bdc-a2e7-2f91c5f75d66",
"status": "COMPLETED",
"isHuman": true,
"isdnCode": 16,
"mfc_r2": "OR2_CAUSE_NORMAL_CLEARING",
"isdnMessage": "Normal Clearing",
"sip": "",
"sipStatus": "SIP 200 OK",
"age_recognize": 0,
"gender_recognize": 0,
"callRequestId": "",
"audioFileName": "79000000000_1785_03-08-2023_prod-19-1691047479.69141"
}Этот способ подходит, если нужно получить информацию по множеству звонков, например за сутки.
Идентификатор профиля определения автоответчиков можно найти так:
Идентификаторы SIP-аккаунта и контакта в адресной книге определяются так же.
{
"dialogs": [
{
"isBot": true,
"timeStamp": 1716798491,
"message": "Привет. Строка: Апельсин\nЧисло: 10 \nДата: 11 мая 2024 года, 12 часов 0 минут 0 сек. \nФИО: Иванов Иван Иванович ",
"NodeId": "fcc8fb77-64c3-4bd5-8fac-622aa79b8d70"
}
],
"parameters": {
"api_date": "2024-05-11 12:00:00",
"api_fio": "Иванов Иван Иванович",
"api_number": "10",
"api_string": "Апельсин"
}
}Значение callRequestId из ответа передайте в метод GET /call/state/{id}. В ответе возьмите значение conversationId и передайте его в метод GET /dialog/{id}. В результате вернётся диалог по этому звонку. Другие способы получить результаты описаны в разделе «Как получить результаты обзвона» ниже.
{
"success": true,
"callRequestId": "5bad1e92-0000-0000-0000-87e6b5c7690a"
}{
"answeringMachineId": "39954fb5-1761-49ff-b635-f9eabfcbe747",
"channel": {
"id": "9999",
"type": 2
},
"contact": {
"account": "79999999999"
},
"parameters": {
"api_string": "Апельсин",
"api_number": "10",
"api_date": "2024-05-11 12:00:00",
"api_fio": "Иванов Иван Иванович"
},
"recordCallFromDial": false,
"scriptId": "06cd9e40-0e95-476b-8be1-ab10f734a3fa",
"waitingTime": 60
}Чтобы передать данные, которые робот должен произнести в диалоге, заполните параметр parameters. Тело запроса и ответ приведены ниже.
| Параметр | Описание |
|---|---|
answeringMachineId | Идентификатор профиля определения автоответчиков. |
callback | Параметры обратного вызова, через который данные о звонке передаются в вашу систему. |
callback.auth | Логин и пароль (username, password) для авторизации при вызове callback. |
callback.headers | Дополнительные заголовки запроса. |
callback.requestType | Тип запроса. |
callback.timeout | Время ожидания ответа. |
callback.url | Адрес, по которому передаются данные о звонке. |
channel | Канал, с которого выполняется звонок. |
channel.id | Номер телефона или идентификатор SIP-аккаунта. |
channel.type | Тип средства связи. Обязательное поле. Значения: 1 — телефонный звонок (Phone call); 2 — телефонный звонок по SIP (Phone call by SIP). |
contact | Данные контакта, которому выполняется звонок. |
contact.account | Номер телефона контакта. Обязательное поле, если не заполнено contact.id. |
contact.id | Идентификатор контакта в Robovoice. Если его нет, платформа ищет контакт по полю account. Если такого контакта нет, создаётся новый со значением account. |
crmId | Идентификатор CRM. |
parameters | Входящие параметры сценария в виде пар «ключ: значение», например {"id": "00000000-0000-0000-0000-000000000000", "name": "Иван"}. Возвращаются в функции callback. |
password | Пароль для авторизации в CRM. |
recordCallFromDial | Режим записи разговора: true — запись с начала звонка, false — с момента, когда контакт ответил. |
robovoiceConnectorInvokeId | Уникальный идентификатор записи звонка в BPM. |
scriptId | Идентификатор сценария Robovoice, по которому выполняется звонок. Обязательное поле. |
serviceURL | URL сервиса-коннектора для запросов из сценария и callback. Вызывается при смене статуса звонка: например, началась попытка звонка или звонок завершён. Значения поля parameters передаются в функцию callback. |
startDate | Дата и время первой обработки сценария в формате timestamp. Часовой пояс контакта не учитывается. Если параметр не указан, звонок выполняется сразу. |
waitingTime | Время ожидания ответа контакта. |
{
"answeringMachineId": "39954fb5-1761-49ff-b635-f9eabfcbe747",
"callback": {
"auth": {
"password": "пароль",
"username": "логин"
},
"headers": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"requestType": "POST",
"timeout": 30000,
"url": "https://my-crm.com/callback"
},
"channel": {
"id": "78002002020",
"type": 1
},
"contact": {
"account": "78002000000",
"id": "00000000-0000-0000-0000-000000000000"
},
"crmId": "00000000-0000-0000-0000-000000000000",
"parameters": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"password": "пароль",
"recordCallFromDial": false,
"robovoiceConnectorInvokeId": "00000000-0000-0000-0000-000000000000",
"scriptId": "00000000-0000-0000-0000-000000000000",
"serviceURL": "https://my-crm.com/callback",
"startDate": 1565568000,
"waitingTime": 60
}scriptId, channel.type и contact.account. Остальные заполняются по потребностям вашего процесса. Тип запроса — POST.Этот способ запускает массовый обзвон: создаётся группа контактов, которая загружается в кампанию с индивидуальными настройками. Настроить его сложнее, так как нужно выполнить несколько методов подряд. Зато у него есть преимущества перед способом 1:
Вызывайте методы в таком порядке:
Результаты можно получить за период или сразу после звонка. Выберите способ в зависимости от того, как запускается обзвон.