Автоматизация исходящих обзвонов

Инструкция рассчитана на технических специалистов, которые настраивают интеграцию. Полное описание методов API с параметрами, примерами запросов и ответов находится в технической документации.

Получение идентификатора профиля определения автоответчиков

Основные понятия

ТерминЧто это
APIПрограммный интерфейс Robovoice. Через него ваши системы обмениваются данными с платформой.
ЛКЛичный кабинет Robovoice.
СценарийАлгоритм диалога робота с контактом. В запросах определяется параметром scriptId.
КампанияМассовый обзвон группы контактов с индивидуальными настройками запуска.
Группа контактовСписок контактов, который загружается в кампанию.
КонтактАбонент, которому звонит робот. Определяется номером телефона (account) или идентификатором в Robovoice (id).
CallbackОбратный вызов: так Robovoice передаёт данные о звонке в вашу систему.
Часовой пояс контактаПлатформа определяет его по номеру телефона контакта.
TimestampДата и время в формате Unix-времени: количество секунд, прошедших с 01.01.1970 (UTC).

Как организовать обзвон

Через API обзвон можно организовать двумя способами: запускать его со своей стороны или поручить запуск стороне Robovoice.

Запуск обзвона на стороне Robovoice

В этом варианте создаётся интеграционный шлюз — промежуточное звено между вашей системой и Robovoice. Шлюз получает из вашей системы базу контактов для обзвона и отправляет туда результаты, а звонки совершает через методы API Robovoice по алгоритму, описанному ниже.

Этот вариант требует больше трудозатрат: состав работ и условия их выполнения фиксируются договором. Для него в вашей системе должны быть методы API, которые позволяют:

  • получать базу контактов на обзвон по согласованным параметрам (маркерам);
  • принимать результаты обзвона обратно в вашу систему: результат звонка, транскрипцию диалога и другие нужные параметры.
Запуск обзвона на вашей стороне

Ваша система сама отправляет контакты в Robovoice и забирает результаты. Этот вариант мы рекомендуем: он позволяет заранее отфильтровать контакты для обзвона, а результаты сразу попадают в вашу систему, где хранятся исходные данные. Обращаться к API вашей системы при этом не нужно. Способы запуска и получения результатов описаны ниже.

Два способа запуска обзвона

Если обзвон запускаете вы, звонки можно запускать двумя способами: единичными звонками без кампании (метод /scripts/invoke) или массовым обзвоном с созданием кампании. Сравнение способов:

КритерийСпособ 1: метод /scripts/invokeСпособ 2: кампания
Часовой пояс контактаНе учитывается. Значение startDate нужно указывать уже с учётом часового пояса контакта.Учитывается платформой при загрузке контактов в кампанию.
Дата и время начала обзвонаЗадаются параметром startDate (по UTC+00:00). Если параметр не заполнен, звонок выполняется сразу после запроса.Задаются в настройках кампании, звонки выполняются с учётом часового пояса контакта.
Автоматический перезвон, если соединение не установленоНе поддерживается. Перезвоны организуются на вашей стороне по результатам обзвона.Перезвоны организуются на вашей стороне по результатам обзвона.
Количество одновременных звонков, звонки в выходные и праздничные дниНе регулируется.Настраивается в кампании.
Аналитика в ЛКЗвонки в ЛК не отображаются. Аналитику нужно собирать на своей стороне или через отдельный сервис кастомизированных отчётов.Кампании сохраняются в ЛК. Доступны гибкая настройка аналитики и просмотр диалогов в режиме онлайн.
Сложность реализацииМинимальная: нужен один метод.Выше: используется последовательность методов.

Способ 1. Единичные звонки

Метод POST /scripts/invoke совершает единичные звонки. Это самый быстрый в реализации способ: нужен всего один метод. Учтите его ограничения:

  • Часовой пояс контакта не учитывается. Звонок выполняется в момент, указанный в параметре startDate, по UTC+00:00. Если параметр не заполнен, звонок выполняется сразу после запроса. Работу с часовыми поясами нужно выполнять на вашей стороне: указывайте startDate уже с учётом часового пояса контакта.
  • Автоматического перезвона нет. Если контакт не ответил (соединение не установлено), перезвонить нужно самостоятельно, получив результаты обзвона.
  • Звонков нет в ЛК. Звонки, выполненные методом /scripts/invoke, в личном кабинете не отображаются, поэтому аналитику по ним нужно собирать на своей стороне. Со стороны Robovoice сбор аналитики возможен через отдельный сервис кастомизированных отчётов. Это дополнительная функциональность, её условия фиксируются в коммерческом предложении.
ШагМетодЧто делает
1POST /groupsСоздаёт группу контактов.
2POST /groups/{id}/contactsСоздаёт контакты и добавляет их в существующую группу.
3POST /campaign/Создаёт кампанию.
4POST /campaigns/{id}/groupsДобавляет группу контактов в существующую кампанию.
5GET /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"
}
Результаты за период

Этот способ подходит, если нужно получить информацию по множеству звонков, например за сутки.

  1. Вызовите метод GET /calls. В параметрах from и to укажите нужный интервал в формате timestamp, а в параметре where — идентификатор сценария scriptId. Пример запроса: https://agent.robovoice.ru/api/v1/calls?from=1690874716&to=1691101516&where=scriptId:0ae6cfe7-6af6-425c-a8dd-630f5899edc1 (значение scriptId в примере условное). В ответе вернётся массив объектов. Из каждого объекта возьмите значение dialogId. Пример объекта приведён ниже.
  2. По каждому dialogId вызовите метод GET /dialog/{id} («Получить текст указанного диалога»). В ответе вернётся список заполненных параметров. Пример запроса: https://agent.robovoice.ru/api/v1/dialog/7c21976e-aea4-4bdc-a2e7-2f91c5f75d66. В свойстве parameters содержатся все заполненные переменные.
  3. Отсортируйте и отберите диалоги в соответствии с вашими процессами и задачами.
Как найти идентификаторы профиля автоответчика, контакта и SIP-аккаунта

Идентификатор профиля определения автоответчиков можно найти так:

  1. Откройте в браузере инструменты разработчика (DevTools) и перейдите на вкладку Network.
  2. В личном кабинете откройте нужный профиль автоответчика.
  3. В запросе, который появится на вкладке Network, найдите идентификатор профиля в адресе запроса и скопируйте его.

Идентификаторы 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, по которому выполняется звонок. Обязательное поле.
serviceURLURL сервиса-коннектора для запросов из сценария и callback. Вызывается при смене статуса звонка: например, началась попытка звонка или звонок завершён. Значения поля parameters передаются в функцию callback.
startDateДата и время первой обработки сценария в формате timestamp. Часовой пояс контакта не учитывается. Если параметр не указан, звонок выполняется сразу.
waitingTimeВремя ожидания ответа контакта.
Параметры запроса
The lives of two mob hitmen, a boxer, a gangster’s wife, and a pair of diner bandits intertwine in four tales of violence and redemption.
{
  "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
}
Структура запроса
The lives of two mob hitmen, a boxer, a gangster’s wife, and a pair of diner bandits intertwine in four tales of violence and redemption.
ВажноОбязательные поля: scriptId, channel.type и contact.account. Остальные заполняются по потребностям вашего процесса. Тип запроса — POST.

Способ 2. Массовый обзвон через кампанию

Этот способ запускает массовый обзвон: создаётся группа контактов, которая загружается в кампанию с индивидуальными настройками. Настроить его сложнее, так как нужно выполнить несколько методов подряд. Зато у него есть преимущества перед способом 1:

  • при загрузке контактов в кампанию платформа сама определяет часовой пояс каждого контакта. В кампании задаются дата и время начала обзвона, а звонки выполняются с учётом часового пояса контакта;
  • можно регулировать количество одновременных звонков и звонки в выходные и праздничные дни. Перезвоны, если они нужны, организуются на вашей стороне по результатам обзвона;
  • созданные кампании сохраняются в ЛК: можно гибко настроить аналитику и смотреть диалоги в режиме онлайн.

Вызывайте методы в таком порядке:

Как получить результаты обзвона

Результаты можно получить за период или сразу после звонка. Выберите способ в зависимости от того, как запускается обзвон.

Желаем удачи!
Команда Robovoice.
Остались вопросы?
Посмотрите Наши видео-инструкции или отправьте Ваш вопрос менеджеру Robovoice

Общие частые вопросы