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

Сейчас мы основательно обновляем более масштабный блок API — по управлению данными (Data API). Типовой кейс c его использованием — это, например, самостоятельная интеграция телефонии с CRM с расширенными возможностями контроля передаваемых между системами данных.

1. Покажу, как мы сами реализовали готовую интеграцию виртуальной АТС с retailCRM на основе новой версии API. Эта же логика может быть легко перенесена в любую нужную интеграцию с вашей системой (оговорюсь, что это не инструкция, а именно фундамент для реализации интеграций других АТС с retailCRM или других CRM с телефонией UIS).
2. Расскажу о ключевых функциях по управлению данными, которые мы зашиваем в обновленный API и на которые вы можете опираться.

Пример базовой интеграции телефонии с CRM

Давайте посмотрим, как сделать интеграцию телефонии с CRM с поддержкой базового функционала на примере retailCRM. При этом оговоримся, что под базовым функционалом мы понимаем:

• Всплывающую карточку контакта
• Фиксацию потерянных звонков в CRM
• Исходящие звонки из CRM
• Прослушивание записей разговора в CRM-системе

Конкретно в схеме интеграции UIS с retailCRM мы реализовали еще несколько полезных функций (например, синхронизацию статусов сотрудников в сервисах и т.п.). Однако, думается, что они все-таки выходят за рамки базового функционала подобных интеграций, так что подробно на них в этом материале я останавливаться не буду.

Используемые инструменты

• Инструменты UIS: Data API; Call API; блок уведомлений
• API retailCRM

В рамках статьи также подразумевается, что для работы интеграции необходим сервер-коннектор, который обеспечивает взаимодействие облачной АТС и CRM.

Общая схема работы интеграции

Кликайте на схему, чтобы посмотреть в полном размере.

Активация телефонии в retailCRM

Телефония в retailCRM активируется запросом к /api/v4/telephony/setting/{code}/edit. Cреди прочих, в запросе указываются следующие параметры:

• makeCallUrl — URL, на который retailCRM будет отправлять запросы для генерации исходящих звонков.
• changeUserStatusUrl — URL, на который retailCRM будет отправлять оповещения об изменении статуса сотрудника.

Обработка звонка

Всплывающая карточка контакта

Всплывающая карточка контакта в retailCRM осуществляется простым запросом к API /api/v4/telephony/call/event, триггером будет сработавшее уведомление на событие «Ожидание ответа», когда у сотрудника уже звонит телефон.

Пропущенные звонки

Пропущен звонок или успешен, можно определить по параметру is_lost в уведомлении о завершении звонка. И если звонок пропущен, то статус звонка будет загружен запросом API /api/v4/telephony/calls/upload, поля которого можно заполнить параметрами из уведомления.

Успешные звонки и сохранение их записей в CRM

Чтобы загрузить успешный звонок в retailCRM, предварительно нужно получить дополнительную информацию по этому вызову, с чем и поможет справиться Data API.

Немного о компоновке запроса:

• В поле params можно указать интересующие параметры, чтобы в ответе пришли только они
• В поле filter можно указать наименование тех полей, которые вас интересуют

{
  "jsonrpc": "2.0",
  "id": 1122,
  "method": "get.call_legs_report",
  "date_from": "2017-06-01 14:34:00",
  "date_till": "2017-06-01 14:36:52",
  "params": {
    "access_token": "N2dw2Rf33fn23fknkmdfeJmcP",
    "filter": {
        "filters": [
            {
                "field": "call_session_id",
                "operator": "=",
                "value": 31451224
            },
{
                "field": "is_talked",
                "operator": "=",
                "value": true
            }
        ],
        "condition": "and"
    },
    "fields": [
      "id",
    "call_seesion_id",
    "call_records",
    "release_cause_code",
    "direction",
    "start_time",
    "employee_id",
    "called_phone_number",
    "contact_phone_number",
    "total_duration",
    "duration"
    ]
  }
}

Полученную информацию необходимо загрузить в retailCRM запросом API /api/v4/telephony/calls/upload. Если требуется расширить набор загружаемых параметров, их можно взять из параметров уведомления «Завершение звонка».

Исходящий звонок из retailCRM по клику

При попытке сотрудника позвонить по клику на номер контакта из интерфейса CRM, retailCRM будет присылать вам запрос на URL, указанный при активации телефонии. Теперь необходимо этот запрос перенаправить в сервис телефонии для совершения звонка. Для этого можно использовать наш Call API.

{
  "jsonrpc": "2.0",
  "method": "start.employee_call",
  "id": "number",
  "params": {
    "access_token": "N2dw2Rf33fn23fknkmdfeJmcP",
    "first_call": "employee",
    "early_switching": true,
    "switch_at_once": true,
    "show_virtual_phone_number": false,
    "virtual_phone_number": "88002000600",
    "direction": "out",
    "contact": "72131231111",
    "employee": {
      "id": 13421
    }
  }
}

Cинхронизация статусов сотрудников в retailCRM и UIS

При получении уведомления о смене статуса сотрудника от retailCRM, необходимо сгенерировать запрос к Data API, чтобы изменить настройки этого сотрудника в соответствии с новым статусом.

{
  "jsonrpc": "2.0",
  "id": "number",
  "method": "update.employees",
  "params": {
    "access_token": "N2dw2Rf33fn23fknkmdfeJmcP",
    "id": 13421,
    "calls_available": false
  }
}

Нюансы управления данными через API UIS

А сейчас, как обещал, расскажу о ключевых функциях по контролю передаваемых между телефонией и CRM данных, которые мы предусмотрели в обновленном API UIS.

• Контролируемая защита данных. Запросы к API осуществляются по ключам с разграниченными правами доступа. Ключи API создаются под конкретного пользователя и обладают набором прав, аналогичным полномочиям пользователя в Личном кабинете UIS. Например, если у него есть только доступ на просмотр сотрудников, и редактировать их профили в интерфейсе UIS он не может, то не сможет сделать это и через API.
• Журнал-лог запросов в личном кабинете. Еще один важный шаг к повышению прозрачности всего процесса по работе с API.
• Гибкие условия фильтрации для получения данных. Задавать условия можно самостоятельно.
• Передача массивов в запросах для получения списка конкретных сущностей (сотрудников, звонков и пр.). Раньше, чтобы получить, например, профили сотрудников Коли, Васи и Пети, нужно было делать три запроса к API, а теперь это один запрос, в котором указаны ID нужных сотрудников.
• Частичное обновление данных. Отправлять всю простыню свойств обновляемой сущности в запросе на обновление не нужно — достаточно отправить только те поля, которые реально изменились.
• Индивидуальное определение получаемых полей. В запросе на получение данных задаются только интересующие вас параметры. Профит — фильтрация хлама в виде ненужной информации.
• Продуманная система ошибок. Это для того, чтобы упростить диагностику проблем.

Публичный запуск функционала мы запланировали на июль, но я готов рассказать больше, если вы хотите реализовать свою схему интеграции, подобную описанной выше, и нужны детали уже сейчас (писать мне лучше сюда).

P.S. Кстати говоря, если вы представитель CRM-системы, которой не хватает интеграции с телефонией, то тоже буду рад сотрудничать. Вы поможете нам проработать схему готовых партнерских интеграций в один клик из Личного кабинета UIS, а мы вам — сделать интеграцию наших сервисов для ваших пользователей.

https://habrahabr.ru/post/330396/