Интеграция с CRM Битрикс-24
В разделе приведено описание настроек взаимодействия ECSS-10 c системой для ведения проектов, работы с клиентами и настройки бизнес-процессов — CRM Битрикс-24.
Общее описание
Интеграция CRM Битрикс-24 с телефонией ECSS-10 осуществляется с помощью приложения, встраиваемого на веб-страницу CRM Битрикс-24 и сервиса ecss-crm-server. Данное приложение обеспечивает работу таких функций как click to call, управление вызовами (принять/отклонить/отбить), список текущих активных вызовов, всплывающие нотификации, информирующие об активных вызовах и их фазах, а также определение контакта по номеру телефона.
Для того чтобы приложение могло взаимодействовать с системой ECSS-10 посредством ECSS-10 Call API, необходимо:
- активировать CSTA в системе ECSS-10 (без этого приложение не будет отображать вызовы, инициированные не со страницы CRM Битрикс-24);
- настроить сертификат для установки защищенного соединения между приложением и системой ECSS-10 (см. Настройка сертификата);
- добавить в домене интеграцию для аутентификации приложения (см. Добавление интеграции);
- добавить соответствующее разрешение для абонента, номер которого будет использоваться для осуществления вызовов из CRM Битрикс-24 (см. Добавление разрешения абоненту SSW);
- установить и настроить сервис ecss-crm-server;
- инсталлировать приложение и указать настройки подключения к системе ECSS-10.
Активация CSTA
Для того чтобы интеграция могла отображать вызовы, инициированные не со страницы CRM Битрикс-24, нужно убедиться, что в системе активирован функционал CSTA. Это можно сделать командой CoCon:
/api/csta/set enabled true
Настройка сертификата
При инсталляции пакета ecss-node автоматически генерируется самоподписанный сертификат для ecss-call-api. Опции ssl_certificate размещаются в /etc/nginx/sites-available/ecss-call-api.conf:
server {
ssl on;
listen 8088 default_server;
listen [::]:8088 default_server;
resolver 127.0.0.1;
ssl_certificate /etc/ecss/ssl/call_api.crt;
ssl_certificate_key /etc/ecss/ssl/call_api.key;
...Однако, современные браузеры не позволяют по умолчанию устанавливать защищенное соединение с ресурсами, предоставляющими самоподписанные сертификаты. Если в случае обычных страниц это не является серьёзной помехой, так как браузер предлагает добавить исключение безопасности при обращении к ресурсу, то в случае с виджетом ситуация несколько иная. Для работы виджета используются кросс-доменные запросы. В случае кросс-доменного запроса браузер блокирует запрос, не предлагая добавить исключение безопасности.
Для того чтобы можно было добавить исключение безопасности для самоподписанного сертификата, существует страница при переходе на которую браузер предложит добавить исключение безопасности. Страница по умолчанию доступна по адресу, на котором был установлен пакет ecss-node. Порт 8088. Таким образом в адресной строке браузера нужно ввести:
https://<host>:8088/
где <host> — имя или адрес ECSS-10.
После добавления исключения безопасности откроется тестовая страница ECSS Call API:
Управление интеграциями
Интеграция представляет собой пару, состоящую из идентификатора клиента и API ключа. Интеграции используются для аутентификации сторонних сервисов, использующих ECSS Call API. Команды управления интеграциями приведены в разделе "Команды управления ключами внешних интеграций".
1. Добавление интеграции
Для добавления интеграции используется команда:
/domain/<DOMAIN>/integrations/add <CLIENT_ID> --service --numbers {<RANGE>}
Добавить новую интеграцию. API ключ будет сгенерирован автоматически.
<CLIENT_ID> — идентификатор клиента, для которого будет создан ключ интеграции
<RANGE> — номера абонентов ecss-10, обслуживаемых интеграцией.
Пример:
admin@[mycelium1@ecss1#test_davidenko]:/$ domain/mycompany.ru/integrations/add MyCompanyBitrix24 --service --numbers {101,102,103,110-120}
New integration was added.
API key: wQ7iD7nJ2hQiJDY2wkER2qr3lJYaDw2dE24rhl3iHDaQwwwln242rjwHkJPw4DYK
2. Удаление интеграции
Для удаления интеграции используется команда:
/domain/<DOMAIN>/integrations/remove <CLIENT_ID>
Удалить интеграцию
<CLIENT_ID> — идентификатор клиента, для которого будет удалён ключ интеграции
admin@mycelium1@ecss1:/$ domain/biysk.local/integrations/remove tester4 ok [exec at: 22.12.2019 13:20:18, exec time: 16ms, nodes: ds1@ecss1]
3. Просмотр списка интеграций
Для просмотра списка интеграций используется команда:
/domain/<DOMAIN>/integrations/list
Просмотреть список интеграций
Список интеграций показывается в виде таблицы, пример:
admin@[mycelium1@ecss1#test_davidenko]:/$ domain/mycompany.ru/integrations/list ┌─────────────────┬───────┬────────────────────────────────────────────────────────────────┬────────┐ │ Client id │ Type │ API Key │Options │ ├─────────────────┼───────┼────────────────────────────────────────────────────────────────┼────────┤ │MyCompanyBitrix24│service│wQ7iD7nJ2hQiJDY2wkER2qr3lJYaDw2dE24rhl3iHDaQwwwln242rjwHkJPw4DYK│Numbers:│ │ │ │ │101 │ │ │ │ │102 │ │ │ │ │103 │ │ │ │ │110 │ │ │ │ │111 │ │ │ │ │112 │ │ │ │ │113 │ │ │ │ │114 │ │ │ │ │115 │ │ │ │ │116 │ │ │ │ │117 │ │ │ │ │118 │ │ │ │ │119 │ │ │ │ │120 │ └─────────────────┴───────┴────────────────────────────────────────────────────────────────┴────────┘
4. Замена ключа интеграции
Для замены ключа интеграции используется команда:
/domain/<DOMAIN>/integrations/replace <CLIENT_ID>
Заменить ключ интеграции
<CLIENT_ID> — идентификатор клиента, для которого будет заменён ключ интеграции.
Пример работы команды:
admin@mycelium1@ecss1:/$ domain/biysk.local/integrations/replace tester Old key was replaced with new one. New API key: wT5neQJ1hykwvnTQeJ50ywKoFMizeAJcJwhcowFvV5eVe5zf5C1imCvoMFizAKQz [exec at: 22.12.2019 10:15:31, exec time: 28ms, nodes: ds1@ecss1]
5. Изменение списка обслуживаемых номеров
Для изменения списка обслуживаемых интеграцией номеров используется команда:
/domain/<DOMAIN>/integrations/set <CLIENT_ID> --numbers {<RANGE>}
Изменить список обслуживаемых номеров
<CLIENT_ID> — идентификатор клиента, для которого будет изменен список обслуживаемых номеров.
<RANGE> — новый список номеров абонентов ecss-10, обслуживаемых интеграцией.
Пример работы команды:
admin@[mycelium1@ecss1#test_davidenko]:/$ domain/mycompany.ru/integrations/set MyCompanyBitrix24 --numbers {101,102,103,104,105}
Integration properties changed
admin@[mycelium1@ecss1#test_davidenko]:/$ domain/mycompany.ru/integrations/list
┌─────────────────┬───────┬────────────────────────────────────────────────────────────────┬────────┐
│ Client id │ Type │ API Key │Options │
├─────────────────┼───────┼────────────────────────────────────────────────────────────────┼────────┤
│MyCompanyBitrix24│service│wQ7iD7nJ2hQiJDY2wkER2qr3lJYaDw2dE24rhl3iHDaQwwwln242rjwHkJPw4DYK│Numbers:│
│ │ │ │101 │
│ │ │ │102 │
│ │ │ │103 │
│ │ │ │104 │
│ │ │ │105 │
└─────────────────┴───────┴────────────────────────────────────────────────────────────────┴────────┘
Добавление разрешения абоненту SSW
При выполнении логина в ECSS Call API виджет сообщает ECSS-10 номер телефона абонента, который будет закреплён за этим виджетом. Это требует специального разрешения, активированного у абонента.
Для активации разрешения нужно выставить соответствующему алиасу значение true для свойства api\call\enabled. Например:
Пример:
admin@mycelium1@ecss1:/$ domain/biysk.local/alias/set 240473 loc.gr 240473@biysk.local api\call\enabled true There are aliases within domain biysk.local affected by settings property api\call\enabled: 240473 <-> 062743c44271f9e7 Legend: a: Setup alias address i: Setup alias inteface !: Setup broken. Alias allready exists *: Setup broken. Alias not exists L: Setup broken. No free subscriber licences. x: Setup broken. Unexpected error <empty>: Successfull setup [exec at: 20.12.2019 22:42:09, exec time: 101ms, nodes: ds1@ecss2]
В том случае, если данное свойство не будет выставлено, виджет не сможет выполнить логин в ECSS Call API
Установка ecss-crm-server
Для установки пакета выполните в консоли ОС команды:
sudo apt update sudo apt install ecss-crm-server
В конце установки пакета проводится его настройка:
Укажите адрес сервера, на котором будет запущен ecss-crm-server. По умолчанию предлагается 127.0.0.1.
Указание 0.0.0.0 вместо адреса сделает невозможным встраивание карточки вызова в интерфейс Битрикс-24.
Укажите номера tcp-портов HTTP и HTTPS, на которых будет слушать сервер ecss-crm-server. Стандартные порты для HTTP (80) и HTTPS (443) не предлагаются пакетом по умолчанию, так как при установке на один сервер с пакетом ecss-node, они будут конфликтовать с веб-конфигуратором ECSS-10. Администратор может самостоятельно указать данные порты при установке пакета, если они не создадут конфликт с другими сервисами.
Описание конфигурации ecss-crm-server
Настройки, указанные при инсталляции, а также некоторые другие, могут быть изменены после инсталляции пакета в файле /usr/share/ecss/ecss-crm-server/src/settings.js.
Вот его содержимое после инсталляции по умолчанию.
var settings = {
path: '/bitrix',
dist: "/usr/share/ecss/ecss-crm-server/frontend/dist",
serverHost: "127.0.0.1",
httpPort: process.env.HTTP_PORT || 80,
httpsPort: process.env.HTTPS_PORT || 443,
sslKeyFilename: "/etc/ecss/ssl/ecss10.key",
sslCertFilename: "/etc/ecss/ssl/ecss10.crt",
// bitrixClientId: "some client id",
// bitrixClientSecret: "some client secret",
bitrixTokenHost: "https://oauth.bitrix.info",
logLevel: 'warn',
// logLevel: 'debug',
defaultLogFile: '/var/log/ecss/ecss-crm-server/default.log',
errorLogFile: '/var/log/ecss/ecss-crm-server/error.log',
logToConsole: false,
rebindPlacement: false
};
module.exports = settings;
Где:
- path — HTTP-префикс пути, по которому будет доступен Битрикс-24 коннектор. Для примера если указать путь /test-path, то страница настроек компании будет доступна по URL:
https://127.0.0.1:8802/test-path/company/dashboard; - dist — путь, по которому будут доступны страницы и статические файлы сервера;
- serverHost — адрес сервера, указываемый при инсталляции;
- httpPort — HTTP-порт. Игнорируется при работе через proxy gateway;
- httpsPort — HTTPS-порт. Игнорируется при работе через proxy gateway;
- sslKeyFilename, sslCertFilename — при установке на тот же самый сервер, куда установлен пакет ecss-node, данный параметр не требует настройки, однако, если установка осуществляется на другой сервер, нужно указать корректный путь до сертификатов (при необходимости их нужно приобрести или сгенерировать самостоятельно). Некоторую информацию можно получить на этой странице (вставить ссылку на работу с сертификатами);
- bitrixClientId, bitrixClientSecret — если Битрикс-24 коннектор используется для нужд одной компании, то можно можно указать параметры, полученные при регистрации приложения прямо в конфиге. Тогда их не нужно будет указывать при регистрации в браузере (см. Регистрация приложения в Битрикс-24 коннекторе);
- bitrixTokenHost — хост для авторизации OAuth2.0;
- logLevel — уровень логов. По умолчанию 'warn'. Поддерживаются следующие уровни логов, в порядке возрастания подробности: error, warn, info, http, verbose, debug, silly, хотя на текущий момент используются не все. Рекомендуется использовать 'warn' при обычной работе и 'debug' при поиске проблем;
- defaultLogFile — файл, в который пишутся все логи с учетом указанной подробности;
- errorLogFile — файл, в который пишутся только критические ошибки (уровень подробности error);
- logToConsole — выводить логи в stdout;
- rebindPlacement — если из за какой то внутренней ошибки не удалось встроить карточку в интерфейс Битрикс-24 при первом входе в компанию, можно вызвать эту процедуру принудительно, выставив значение параметра rebindPlacement в true. Нужно, однако, помнить, что при каждом повторном встраивании карточки, страница CRM - Битрикс-24 должна быть обновлена, если она открыта в браузере. После успешного встраивания не забудьте выставить значение rebindPlacement обратно в false.
Установка приложения
Интеграция Битрикс-24 не устанавливается из магазина приложений и может быть установлена только вручную.
Ручная установка приложения в облачной версии Битрикс-24
Нам необходимо создать локальное приложение Битрикс-24. Для перехода в меню приложений нужно нажать "Ещё" в меню Битрикс-24 в левой части экрана.
Далее нужно нажать на появившийся пункт меню "Приложения".
В появившемся меню приложений нужно нужно нажать на кнопку "Добавить приложение".
В появившемся меню необходимо выбрать "Другое"
Далее необходимо выбрать "Локальное приложение"
Далее необходимо указать:
- Тип приложения "Серверное"
- Ссылку на ecss-crm-server
- Галочку "Приложение использует только API".
- Во всплывающем меню выбрать следующие разрешения приложения:
- Встраивание приложений (placement);
- Пользователи (user);
- Телефония (telephony);
- Телефония (совершение звонков) (call).
Обратите внимание: Битрикс-24 игнорирует параметр OAuth2.0 redirect_uri и будет отдавать access_code на адрес, указанный вами на этой странице.
Ваше приложение было успешно создано. Обратите внимание на значения "Код приложения (client id)" и "Ключ приложения (client secret)", а так же на "Домен компании". Они понадобятся вам при регистрации компании в ecss-crm-server.
Регистрация приложения в ecss-crm-server
Если ecss-crm-server уже установлен, перейдите в браузере по адресу, указанному вами при изначальной настройке. Обратите внимание, что адрес ecss-crm-server, должен совпадать с адресом, настроенным в интерфейсе Битрикс-24 при создании приложения (см раздел Ручная установка приложения в облачной версии Битрикс-24).
Так как это первый вход, нам нужно указать параметры "Код приложения (client id)", "Ключ приложения (client secret)" и "Домен компании". Для этого необходимо нажать на "дополнительные параметры".
В появившихся полях ввода, указываем "Идентификатор клиента", что соответствует параметру "Код приложения" в интерфейсе Битрикс-24, и "Секретный ключ", что соответствует параметру "Ключ приложения" в интерфейсе Битрикс-24 (см. раздел Ручная установка приложения в облачной версии Битрикс-24). Указание этих дополнительных параметров обязательно только на этапе регистрации. В дальнейшем при входе нужно указывать только домен компании Битрикс-24.
Обратите внимание, что регистрация компании и последующее управление ей должны осуществляться пользователем с правами администратора компании Битрикс-24.
После нажатия кнопки "Вход" браузер будет переадресован на страницу авторизации Битрикс-24. После успешного прохождения авторизации, Вы попадёте в интерфейс настройки компании ecss-crm-server.
Настройка компании в интерфейсе ecss-crm-server
В настройках компании вы можете опционально задать имя компании.
Далее вам нужно указать настройки подключения к ECSS-10, полученные у вашего провайдера телефонии.
Если вы являетесь администратором домена SSW подробнее о настройках подключения к ECSS-10 см. в секции "Настройка интеграции ECSS-10".
После настройки подключения к ECSS-10 перейдите на вкладку "Настройки подключения к Битрикс-24".
На данной вкладке будет виден индикатор жизни OAuth2.0 токена (токен продлевается автоматически). Для настройки номеров телефонов пользователей нажмите на "пользователи".
В появившемся диалоговом окне можно настроить номера телефонов пользователей. Измененный список номеров сохраняется автоматически при закрытии диалогового окна. При поступлении вызова, коннектор, на основании данного списка определяет, какому пользователю необходимо показать карточку звонка в интерфейсе Битрикс-24.
При регистрации компании в ecss-crm-server список пользователей выгружается из аккаунта Битрикс-24. ecss-crm-server использует номера, указанные в профиле пользователя как "внутренний номер".
При добавлении нового пользователя в аккаунте компании Битрикс-24 он будет учтен ecss-crm-server при открытии списка пользователей, либо при перезапуске сервера ecss-crm-server.
После того как пользователь Битрикс-24 учтен в ecss-crm-server, последующие изменения поля "внутренний номер" в аккаунте Битрикс-24, учитываться не будут.
Активация click 2 call
Для включения click 2 call необходимо в интерфейсе компании в Битрикс-24 перейти на страницу настроек телефонии.
Переходим в настройку пользователей телефонии.
Выбираем в поле "номер для исходящего звонка" созданное нами приложение.
Управление вызовами в интерфейсе Битрикс-24
Если всё настроено правильно, то пользователь при входящем или исходящем вызове, должен видеть карточку вызова. Левая часть карточки предоставляется самим Битрикс-24 и содержит интерфейс по управлению контактом. Правая часть карточки принадлежит интеграции с ECSS-10 и содержит номер звонящего (имя, отображаемое на телефонном аппарате) и кнопки управления вызовом: "Отклонить" и, если это входящий вызов, "Принять".
Кнопка "Отклонить" работает для большинства телефонных аппаратов. Кнопка "Принять" работает для телефонных аппаратов, поддерживающих SIP-answer.