В разделе приведено описание настроек взаимодействия ECSS-10 c системой учета базы клиентов и сделок — amoCRM.

Общее описание

Интеграция amoCRM с телефонией ECSS-10 осуществляется с помощью виджета, встраиваемого на веб-страницу amoCRM. Данный виджет обеспечивает работу таких функций как click to call, управление вызовами (принять/отклонить/отбить), список текущих активных вызовов, всплывающие нотификации, информирующие об активных вызовах и их фазах, а также определение контакта по номеру телефона и переход в детали контакта по клику на нотификации.

Для того чтобы виджет мог взаимодействовать с системой ECSS-10 посредством ECSS-10 Call API, необходимо:

активировать CSTA в системе ECSS-10 (без этого виджет не будет отображать вызовы, инициированные не со страницы amoCRM);
настроить сертификат для того чтобы виджет мог устанавливать с системой ECSS-10 защищенное соединение (см. Настройка сертификата);
добавить в домене интеграцию для аутентификации виджета (см. Добавление интеграции);
добавить соответствующее разрешение для абонента, номер которого будет использоваться для осуществления вызовов из amoCRM (см. Добавление разрешения абоненту SSW);
инсталлировать виджет и указать настройки подключения к системе ECSS-10 (см. Установка виджета).

Активация CSTA

Для того чтобы виджет мог отображать вызовы, инициированные не со страницы amoCRM, нужно убедиться, что в системе активирован функционал 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;
...

JAVA

Однако современные браузеры не позволяют по умолчанию устанавливать защищенное соединение с ресурсами, предоставляющими самоподписанные сертификаты. Если в случае обычных страниц это не является серьёзной помехой, так как браузер предлагает добавить исключение безопасности при обращении к ресурсу, то в случае с виджетом ситуация несколько иная. Для работы виджета используются кросс-доменные запросы. В случае кросс-доменного запроса браузер блокирует запрос, не предлагая добавить исключение безопасности. В случае, если браузер блокирует кросс-доменный запрос, виджет отобразит следующую ошибку:

Для того чтобы можно было добавить исключение безопасности для самоподписанного сертификата, существует страница при переходе на которую браузер предложит добавить исключение безопасности. Страница по умолчанию доступна по адресу, на котором был установлен пакет ecss-node. Порт 8088. Таким образом в адресной строке браузера нужно ввести:

https://<host>:8088/

где <host> — имя или адрес ECSS-10.

После добавления исключения безопасности откроется тестовая страница ECSS Call API:

Замечание:

В текущей версии работа через proxy-сервер amoCRM не реализована. При работе через proxy-сервер amoCRM нет проблем с самоподписанными сертификатами, но в этом случае ECSS Call API необходимо сделать доступным в Internet. Кроме того такая схема работы может вносить заметные задержки.

Управление интеграциями

Интеграция представляет собой пару, состоящую из идентификатора клиента и API ключа. Интеграции используются для аутентификации сторонних сервисов, использующих ECSS Call API. Команды управления интеграциями приведены в разделе "Команды управления ключами внешних интеграций".

1. Добавление интеграции

Для добавления интеграции используется команда:

/domain/<DOMAIN>/integrations/add <CLIENT_ID>

Добавить новую интеграцию. API ключ будет сгенерирован автоматически. Для одного клиента, представленного параметром <CLIENT_ID> может быть добавлена только одна интеграция

<CLIENT_ID> — идентификатор клиента, для которого будет создан ключ интеграции

Пример:

admin@mycelium1@ecss1:/$ domain/biysk.local/integrations/add tester       
New integration was added.
API key: 2hBqT4acTLhcvFq29qW429TF26cfv9Wqkzn4Ga4chYC2hyhT2WkdknnWC94dFTKC

[exec at: 22.12.2019 10:12:38, exec time: 28ms, nodes: ds1@ecss1]

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:/$ domain/biysk.local/integrations/list                   
┌─────────┬────────────────────────────────────────────────────────────────┐
│Client id│                            API Key                             │
├─────────┼────────────────────────────────────────────────────────────────┤
│asz      │2uKwuT5qxKB21uzPuTb518oxDB2qzuKLebfT17orDOG21zuuLL0efu1D06rrKcBZ│
│sveta    │4lCyTODH1wfcG41yCytsUDCcfffvWANlyCUL4xcDH4cfyfcWvPNylyCUM1ycOD1H│
│tester   │2hBqT4acTLhcvFq29qW429TF26cfv9Wqkzn4Ga4chYC2hyhT2WkdknnWC94dFTKC│
└─────────┴────────────────────────────────────────────────────────────────┘

[exec at: 22.12.2019 10:14:13, exec time: 12ms, nodes: ds1@ecss1]

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]

Добавление разрешения абоненту SSW

При выполнении логина в ECSS Call API виджет сообщает ECSS-10 номер телефона абонента, который будет закреплён за этим виджетом. Это требует специального разрешения, активированного у абонента.
Для активации разрешения нужно выставить соответствующему алиасу свойству api\call\enabled значение true. Например:

Пример:

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:

Установка виджета

Установка из магазина amoCRM

Каждому пользователю, который планирует использовать виджет телефонии ECSS-10, необходимо указать номер телефона абонента ECSS-10 в профиле пользователя amoCRM. Настройки профиля можно изменить, кликнув на рисунок в левом верхнем углу интерфейса amoCRM:

Данный номер телефона будет использоваться для осуществления звонков со страницы amoCRM, а также для управления вызовами со страницы amoCRM (принять/отклонить).

Магазин виджетов amoCRM можно найти в разделе Настройки -> Интеграции.
Чтобы облегчить поиск виджета в магазине amoCRM можно воспользоваться поиском. Поле поиска расположено в самом верху страницы интеграций:

Необходимо ввести в поле поиска ecss-10, или отыскать виджет вручную.
Для инсталляции виджета необходимо кликнуть на его изображении в магазине.

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

В настройках виджета необходимо указать:

сгенерированные ранее идентификатор клиента и ключ API
ip-адрес и порт ECSS Call API. Адрес и порт определяется конкретной инсталляцией ECSS-10, однако по умолчанию ECSS Call API устанавливается вместе с пакетом ecss-node и доступно по 0.0.0.0 и порту 8088 на том же самом хосте.
Имя домена (виртуальной АТС) ECSS-10

Необходимо заполнить предложенные поля и нажать сохранить:

Теперь можно перезагрузить страницу. Если условия указанные выше в данной документации соблюдены и параметры виджета заполнены верно, то виджет будет готов к работе.

Для работы с виджетом ТА пользователя должен быть зарегистрирован.

Интеграция с историей звонков amoCRM с использованием IVR

AmoCRM предоставляет API, с помощью которого можно помещать вызовы в историю звонков (см. https://www.amocrm.ru/developers/content/telephony/calls_add).
На момент интеграции осуществлять это можно с помощью 2-х API методов:

POST /api/v2/calls/ — Добавляет вызов в историю имеющегося контакта. Контакт определяется по номеру телефона. Если такого контакта ещё нет, вызов будет отброшен. Контакт может быть добавлен либо вручную средствами amoCRM, либо с использованием API метода amoCRM /api/v2/contacts (см. https://www.amocrm.ru/developers/content/api/contacts). Ниже воспользуемся данным способом. Нужно, однако, отметить, что на момент написания данного документа, минимальная разрешенная длина номера телефона — 5 символов.
POST /api/calls/add/ — Добавляет вызов в неразобранное (см. https://www.amocrm.ru/developers/content/telephony/calls_add). Данный метод удобен, так как предварительное наличие контакта не требуется, но требуется специальный ключ сервиса, который можно получить, написав в техническую поддержку amoCRM.

Интеграцию SSW c историей вызовов amoCRM можно осуществить с помощью IVR блока HTTP RPC. В самой простой схеме делается это посредством блока Dial и двух расположенных последовательно блоков RPC, один из которых выполняет логин, а второй помещает информацию о вызове в amoCRM.

Для начала необходимо настроить маршрутизацию на IVR сценарий обычным образом. Назовём это правило to_amocrm.

Блок Dial должен быть настроен следующим образом:

Как видно, в качестве номера, на который делается вызов используется CDPN. В чистом виде данный блок Dial приведёт к зацикливанию, так как вызов снова попадёт на тот же самый IVR сценарий. Чтобы этого не происходило, необходимо добавить ещё одно правило маршрутизации, в котором в условиях в разделе доступ указан интерфейс system:ivr. Маршрутизировать данное правило должно на локального абонента. Назовём это правило prevent_amocrm_cycle.

Это правило нужно расположить выше правила, выполняющего маршрутизацию на наш IVR сценарий, чтобы защититься от зацикливания.

Внимание! Чтобы это работало, галочка "Звонок от имени абонента А" должна быть выключена. Также исходный вызов не должен быть осуществлён с интерфейса system:ivr, иначе правило to_amocrm никогда не сработает.

Существуют и другие варианты настройки маршрутизации, зависящие от конкретных бизнес-сценариев.

Также, должен быть активирован флаг "постобработка", что позволит сценарию выполняться даже если вызов был завершен по инициативе одного из абонентов. Ветка Post-Processing позволит нам выполнять HTTP запросы после завершения разговора с абонентом. Ветки Busy/No answer и Error соединяются с веткой Post-Processing с помощью блока Goto.

Далее добавляем блок для логина:

Указанный на скриншоте блок HTTP RPC осуществит логин в amoCRM.
Доменное имя, входящее в параметр URL, должно включать в себя имя аккаунта amoCRM. Параметр USER_LOGIN должен содержать email-адрес пользователя. Параметр USER_HASH должен содержать API-ключ, который можно посмотреть в профиле пользователя amoCRM.

URL: https://<ВАШ АККАУНТ>.amocrm.ru/private/api/auth.php
Метод запроса: POST
Тело запроса: USER_LOGIN=<EMAIL>&USER_HASH=<API КЛЮЧ ПОЛЬЗОВАТЕЛЯ AMOCRM>&json=true.
Тип в теле запроса: application/x-www-form-urlencoded

IVR блоки HTTP RPC поддерживают Cookie, поэтому следующий запрос к amoCRM в рамках данного IVR сценария будет авторизованным.

Ниже добавляем блок для помещения вызова в историю с помощью метода POST /api/v2/calls/

Вам нужно только указать свой аккаунт. Также обратите внимание на тип в теле запроса.

URL: https://<ВАШ АККАУНТ>.amocrm.ru/api/v2/calls/
Метод запроса: POST
Тело запроса: {"add":[{"phone_number":"%CGPN%","direction":"inbound", "link":"%RECORD_URL%"}]}
В теле запроса используются стандартные переменные IVR: CGPN и RECORD_URL. CGPN содержит в себе номер телефона позвонившего абонента, а RECORD_URL — ссылку на запись разговора, если она активирована у абонента принимающего вызов.
Данный пример добавляет новый входящий вызов.
Тип в теле запроса: application/json

Таким образом, мы получаем возможность в интерфейсе amoCRM видеть историю вызовов: