Интеграция с CRM Битрикс-24
В разделе приведено описание настроек взаимодействия ECSS-10 c системой для ведения проектов, работы с клиентами и настройки бизнес-процессов — CRM Битрикс-24.
Общее описание
Интеграция CRM Битрикс-24 с телефонией ECSS-10 осуществляется с помощью приложения, встраиваемого на веб-страницу CRM Битрикс-24 и сервиса ecss-crm-server. Данное приложение обеспечивает работу таких функций как click to call, управление вызовами (принять/отклонить/отбить), список текущих активных вызовов, всплывающие нотификации, информирующие об активных вызовах и их фазах, а также определение контакта по номеру телефона.
Для того чтобы приложение могло взаимодействовать с системой ECSS-10 посредством ECSS-CRM-SERVER, необходимо:
- активировать CSTA в системе ECSS-10 (без этого приложение не будет отображать вызовы, инициированные не со страницы CRM Битрикс-24);
- добавить в домене интеграцию для аутентификации приложения (см. Добавление интеграции);
- добавить соответствующее разрешение для абонента, номер которого будет использоваться для осуществления вызовов из CRM Битрикс-24 (см. Добавление разрешения абоненту SSW);
- установить и настроить сервис ecss-crm-server;
- инсталлировать приложение и указать настройки подключения к системе ECSS-10.
Активация CSTA
Для того чтобы интеграция могла отображать вызовы, инициированные не со страницы CRM Битрикс-24, нужно убедиться, что в системе активирован функционал CSTA. Это можно сделать командой CoCon:
/api/csta/set enabled true
И в свойствах домена параметр vats_type должен быть выставлен в private:
admin@mycelium1@ecss1:/$ domain/nick/properties/info ┌───────────────────────────────────────┬───────────┬───────────────────────────────────────┐ │ Property │ Domain │ Value │ ├───────────────────────────────────────┼───────────┼───────────────────────────────────────┤ ... │vats_type │nick │private │
Управление интеграциями
Интеграция представляет собой пару, состоящую из идентификатора клиента и API ключа. Интеграции используются для аутентификации сторонних сервисов, использующих ECSS CRM SERVER. Команды управления интеграциями приведены в разделе "Команды управления ключами внешних интеграций".
1. Добавление интеграции
Для добавления интеграции используется команда:
/domain/<DOMAIN>/integrations/add <CLIENT_ID> --service --numbers {<RANGE>}
Добавить новую интеграцию, API-ключ будет сгенерирован автоматически.
<CLIENT_ID> — идентификатор клиента, для которого будет создан ключ интеграции.
<RANGE> — номера абонентов ECSS-10, обслуживаемых интеграцией.
Пример:
admin@[mycelium1@ecss1#test_davidenko]:/$ domain/nick/integrations/add MyCompanyBitrix24 --service --numbers {101,102,103,110-120}
New integration was added.
API key: wQ7iD7nJ2hQiJDY2wkER2qr3lJYaDw2dE24rhl3iHDaQwwwln242rjwHkJPw4DYK
Созданная интеграция должна использоваться строго для одной crm-системы.
2. Удаление интеграции
Для удаления интеграции используется команда:
/domain/<DOMAIN>/integrations/remove <CLIENT_ID>
Удалить интеграцию.
<CLIENT_ID> — идентификатор клиента, для которого будет удалён ключ интеграции.
admin@mycelium1@ecss1:/$ domain/nick/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/nick/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/nick/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/nick/integrations/set MyCompanyBitrix24 --numbers {101,102,103,104,105}
Integration properties changed
admin@[mycelium1@ecss1#test_davidenko]:/$ domain/nick/integrations/list
┌─────────────────┬───────┬────────────────────────────────────────────────────────────────┬────────┐
│ Client id │ Type │ API Key │Options │
├─────────────────┼───────┼────────────────────────────────────────────────────────────────┼────────┤
│MyCompanyBitrix24│service│wQ7iD7nJ2hQiJDY2wkER2qr3lJYaDw2dE24rhl3iHDaQwwwln242rjwHkJPw4DYK│Numbers:│
│ │ │ │101 │
│ │ │ │102 │
│ │ │ │103 │
│ │ │ │104 │
│ │ │ │105 │
└─────────────────┴───────┴────────────────────────────────────────────────────────────────┴────────┘
Добавление разрешения абоненту SSW
При выполнении логина в ECSS CRM виджет сообщает ECSS-10 номер телефона абонента, который будет закреплён за этим виджетом. Это требует специального разрешения, активированного у абонента.
Для активации разрешения нужно выставить соответствующему alias значение true для свойства api\call\enabled. Например:
Пример:
admin@mycelium1@ecss1:/$ domain/nick/alias/set 101 loc.gr 101@nick api\call\enabled true There are aliases within domain nick 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 CRM.
Установка 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: '/',
dist: "/usr/share/ecss/ecss-crm-server/frontend/dist",
// Если указан proxyGatewayURL, то при монтировании карточки звонка, а также
// в redirect_uri будет использоваться данный URL.
// Если proxyGatewayURL указан, то адрес встроенной карточки звонка будет
// сконструирован следующим образом:
// ${settings.proxyGatewayURL}/call/call.html
// Если proxyGatewayURL НЕ указан, то адрес redirect_uri, и адрес встраиваемой
// карточки звонка, будет сконструирован следующим образом:
// https://${settings.host}:${settings.proxyPort}/call/call.html
// proxyGatewayURL: "https://<proxy-origin>:<proxy-port>/bitrix",
// Если опция активна, то вместо http/https портов будут использованы
// Unix-сокеты. Используется для работы через проксирующий веб-сервер
useUnixSockets: false,
// httpUnixSocket: "/var/lib/ecss/ecss-crm-server/http",
// httpsUnixSocket: "/var/lib/ecss/ecss-crm-server/https",
// Запросы на сервер проксируются с помощью nginx.
host: '127.0.0.1',
// Адрес SSW задаётся снаружи.
sswHost: '192.168.116.130',
hostPort: 8801,
proxyPort: 8802,
// Серверу необходимо знать адрес прокси-сервера.
proxyHost: '192.168.116.130',
// В случае работы через proxy gateway, т.е по умолчанию, данные сертификаты
// будут использованы для связи с прокси веб-сервером по https
sslKeyFilename: "/usr/share/ecss/ecss-crm-server/key.pem",
sslCertFilename: "/usr/share/ecss/ecss-crm-server/cert.pem",
// 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 коннектор;
- dist — путь, по которому будут доступны страницы и статические файлы сервера;
- serverHost — адрес сервера, указываемый при инсталляции;
- httpPort — HTTP-порт. Игнорируется при работе через proxy gateway;
- httpsPort — HTTPS-порт. Игнорируется при работе через proxy gateway;
- sslKeyFilename, sslCertFilename — сертификаты, которые при установке генерирует пакет ecss-crm;
- 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:
1. Для перехода в меню откройте вкладку Приложение в меню Битрикс-24, располагающимся в левой части экрана, и выберите пункт Маркет в выпадающем списке.
2. В открывшемся меню «Маркет» нажмите кнопку Добавить приложение.
3. В меню «Готовые сценарии» нажмите на вкладку Другое.
4. В следующем окне нажмите на вкладку Локальное приложение.
5. В настройках локального приложения необходимо указать следующие параметры:
- Название интеграции (по умолчанию «Локальное приложение»).
- Тип приложения «Серверное».
- Ссылку на ecss-crm-server(<IP>:8802/bitrix).
- Галочку «Приложение использует только API».
- В графе «Настройка прав» выбрать:
- Встраивание приложений (placement);
- Пользователи (user);
- Телефония (telephony);
- Телефония (совершение звонков) (call).
Ниже представлено окно выбора настроек прав.
Обратите внимание: Битрикс-24 игнорирует параметр OAuth2.0 redirect_uri и будет отдавать access_code на адрес, указанный вами на этой странице.
Приложение успешно создано.
6. Вернитесь к предыдущей странице и выберите вкладку «Интеграции».
7. Двойным кликом по строке выберите созданное приложение из предложенного списка.
8. Обратите внимание на значения «Код приложения (client id)» и «Ключ приложения (client secret)», а также на домен компании. Они понадобятся при регистрации компании в ecss-crm-server.
Регистрация приложения в ecss-crm-server
Если ecss-crm-server уже установлен, перейдите в браузере по адресу, указанному вами при изначальной настройке. Обратите внимание, что адрес ecss-crm-server, должен совпадать с адресом, настроенным в интерфейсе Битрикс-24 при создании приложения (см. раздел Ручная установка приложения в облачной версии Битрикс-24).
1. Для первого входа в приложение необходимо указать параметры «Код приложения (client id)», «Ключ приложения (client secret)» и домен компании (см. раздел Ручная установка приложения в облачной версии Битрикс-24). Для этого необходимо нажать на кнопку дополнительные параметры.
2. В полях ввода укажите «Идентификатор клиента», что соответствует параметру «Код приложения» в интерфейсе Битрикс-24, и «Секретный ключ», что соответствует параметру «Ключ приложения» в интерфейсе Битрикс-24 (см. раздел Ручная установка приложения в облачной версии Битрикс-24). Указание этих дополнительных параметров обязательно только на этапе регистрации. В дальнейшем при входе нужно указывать только домен компании Битрикс-24.
Регистрация компании и последующее управление ей должны осуществляться пользователем с правами администратора компании Битрикс-24.
3. Нажмите кнопку Вход, браузер будет переадресован на страницу авторизации Битрикс-24.
После успешного прохождения авторизации, вы попадёте в интерфейс настройки компании ecss-crm-server.
Настройка компании в интерфейсе ecss-crm-server
1. В настройках компании присутствует возможность опционально задать имя компании.
2. Укажите настройки подключения к ECSS-10, полученные у вашего провайдера телефонии.
3. Если вы являетесь администратором домена SSW, то вам необходимо выполнить команду:
domain<DOMAIN>integrations/list
Пример:
admin@[mycelium1@ecss1#ECSS 010145]:/$ domain/nick/integrations/list ┌──────────┬───────┬────────────────────────────────────────────────────────────────┬────────┐ │Client id │ Type │ API Key │Options │ ├──────────┼───────┼────────────────────────────────────────────────────────────────┼────────┤ │testbitrix│service│8SGuXEJUMs8SGqn6iAVqkMAuSqGlFM6JGkkUS2Ssg7vVuMrGUVqqku22iukqGvuX│Numbers:│ │ │ │ │107 │ │ │ │ │108 │ └──────────┴───────┴────────────────────────────────────────────────────────────────┴────────┘
4. Введите необходимые значения «API Key» и «Client id». Каждому значению соответствует указанное значение в приложении Битрикс-24:
- «Идентификатор клиента» --> «Client id»;
- «Ключ API» --> «API Key»;
- «Адрес Call API» --> «https://<IP>:8802»;
- «Домен» --> Используемый домен с интеграцией.
5. Перейдите на вкладку «Настройки подключения к Битрикс-24».
6. На данной вкладке отображается индикатор жизни OAuth2.0 токена (токен продлевается автоматически). Для настройки номеров телефонов пользователей нажмите на кнопку пользователи.
7. В появившемся диалоговом окне можно настроить номера телефонов пользователей. Измененный список номеров сохраняется автоматически при закрытии диалогового окна. При поступлении вызова коннектор на основании данного списка определяет, какому пользователю необходимо показать карточку звонка в интерфейсе Битрикс-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 необходимо:
1. В интерфейсе компании в Битрикс-24 в поиске наберите «Телефония» и нажмите на пункт меню Телефония.
2. В открывшемся меню нажмите на вкладку Настройка телефонии и выберите пункт Пользователи телефонии.
3. Перейдите в настройке пользователя телефонии.
4. Выберите в поле «номер для исходящего звонка» созданное приложение.
Управление вызовами в интерфейсе Битрикс-24
Если всё настроено правильно, то пользователь при входящем или исходящем вызове должен видеть карточку вызова. Левая часть карточки предоставляется самим Битрикс-24 и содержит интерфейс по управлению контактом. Правая часть карточки принадлежит интеграции с ECSS-10 и содержит номер звонящего (имя, отображаемое на телефонном аппарате) и кнопки управления вызовом: Отклонить и, если это входящий вызов, Принять.
Кнопка Отклонить работает для большинства телефонных аппаратов. Кнопка Принять работает для телефонных аппаратов, поддерживающих SIP-answer.