Интеграция EnvyCRM и Asterisk: инструкция по настройке

Интеграция EnvyCRM и Asterisk. Фото: из архива компании

Рассмотрим интеграцию EnvyCRM и телефонии с помощью Call API на примере IP-PBX Asterisk.

Для этого нам потребуется CRM, веб-приложение или скрипт для обработки GET-запросов (настраивается Вашими специалистами), и сам Asterisk.

Логика связки очень проста: CRM при помощи отправки GET-запроса отправляет информацию на Ваше веб-приложение или скрипт, он передает ее в Asterisk, который в свою очередь отправляет информацию о звонке в CRM, посредством POST-запроса.

Веб-сервер, в данном случае, выступает в роли посредника, принимающего запросы из CRM, и передающего информацию в Asterisk. Обработчиком запросов от CRM может быть, как полноценное приложение (сайт), так и несколько простых скриптов, написанных, к примеру, на PHP.

Важно! Для работы этой связки Ваш веб-сервер должен принимать запросы на «внешний» IP-адрес. Также, если веб-сервер будет принимать запросы по протоколу HTTPS, то сертификат шифрования должен быть выдан валидным центом сертификации.

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

Рассмотрим принцип работы связки для разных типов звонков:

Входящий звонок на Asterisk

1. В самом начале звонка Asterisk отправляет информацию о нем в CRM

2. Информация о нем моментально появляется в карточке лида в разделе «Входящие»

3. По окончании звонка Asterisk отправляет в CRM уточняющую информацию о поступившем звонке

4. Полная информация о звонке появляется в карточке лида

Исходящий звонок из CRM

1. CRM отправляет на Ваш веб-сервер GET запрос для создания звонка

2. Веб-сервер принимает и передает информацию в Asterisk

3. Asterisk генерирует исходящий звонок соединяя абонентов

4. В начале звонка и при его окончании Asterisk отправляет информацию о звонке в CRM

Исходящий звонок из Asterisk

1. В самом начале звонка Asterisk отправляет информацию о нем в CRM

2. Информация о нем появляется в карточке лида или сделки с таким номером

3. По окончании звонка Asterisk отправляет в CRM уточняющую информацию о поступившем звонке

4. Полная информация о звонке появляется в карточке лида.

Настройка интеграции в EnvyCRM

Перейдите в CRM, откройте “Настройки”, далее “Интеграция” и перейдите в раздел “Телефония”.

В блоке Call API нажмите “Подключить”.

В настройках Call API необходимо заполнить следующие поля:

Адрес запроса для проверки соединения:

В этом поле необходимо указать URL адрес страницы на Вашем WEB-сервере, которая при ответе будет содержать текcт «200 OK». Эта страница будет использоваться для проверки доступности WEB-сервера.

Адрес запроса для создания звонка:

URL страницы на Вашем сервере на которую будет отправляться запрос на создание звонка. GET-запрос с параметрами «FROM» — внутренний номер менеджера и «TO» — номер клиента, на который пойдет звонок.

Адрес для получения списка абонентов:

URL страницы на Вашем сервере, на которую будет отправляться запрос на получение списка внутренних и внешних номеров Asterisk. Страница ответа должна содержать JSON массив с перечислением номеров.

Пример:

{

"Внутренние номера":[

"1234",

"4321"

],

"Внешние номера":[

"79*********",

"74*********"

]

}

Параметры запроса:

В этот раздел Вы можете добавить собственные переменные, передаваемые на WEB-сервер при создании нового звонка. Например, имя диалплана Asterisk, через который необходимо совершить звонок, или имя CRM для идентификации источника на стороне Asterisk.

В таком случае URL с GET-запросом будет иметь следующий вид:

https://[адрес вашего сервера]/[адрес страницы-обработчика]?from=1234&to=71234567890&dialplan=dialplan_name&crmname=test

Важно! Номера телефонов передаются из CRM в международном формате. Например, маска номера Российской Федерации будет иметь вид 7XXXXXXXXXX.

Настройка приема звонков

После добавления адреса страницы со списком абонентов в настройках появится возможность выбрать номера, звонки на которые будут передаваться в CRM.

После этого останется указать внутренние номера напротив списка сотрудников CRM.

Настройка Вашего сервера:

Веб-сервером на сервере c Asterisk необходимо принимать GET-запрос с параметрами:

«from» — внутренний номер менеджера,

«to» — номер клиента, на который пойдет звонок.

Затем эти данные необходимо передать в Asterisk.

Важно! Мы протестировали в работе простой метод создания звонка с помощью CALL-файлов. Это встроенный инструмент Asterisk, подробнее о нем можно узнать в официальной wiki:

https://wiki.asterisk.org/wiki/display/AST/Asterisk+Call+Files

Но Вы можете использовать любой удобный способ создания звонка, например Asterisk Manager Interface (AMI):

https://wiki.asterisk.org/wiki/pages/viewpage.action?pageId=4817239

Отправка информации о звонке в CRM

Далее нужно отправить информацию в CRM о входящих и исходящих звонках.

Для этого в диалплане в самом начале звонка и при его завершении необходимо отправить POST-запрос на адрес вашей CRM https://[имя_вашей_CRM].envycrm.com/hook/callapi/.

Пример диалплана входящего звонка:

...

exten => _X!,1,System(/usr/bin/php /var/lib/asterisk/agi-bin/envycrm_api.php incoming_start ${STRFTIME(${EPOCH},,%s)} ${CALLERID(num)} ${UNIQUEID} test.envycrm.com)

exten => _X!,n,Answer()

exten => _X!,n,Queue(incoming_queue)

...

exten => h,n,System(/usr/bin/php /var/lib/asterisk/agi-bin/envycrm_api.php incoming_stop ${STRFTIME(${EPOCH},,%s)} ${CALLERID(num)} ${MEMBERINTERFACE:4} ${CDR(billsec)} ANSWER ${UNIQUEID} test.envycrm.com)

...

В первой строке диалплана используется команда System, позволяющая выполнить внешний скрипт и передать в него переменные из канала звонка.

В команде мы вызываем интерпретатор «/usr/bin/php» для выполнения скрипта «envycrm_api.php», его листинг представлен ниже. Данный скрипт используется для формирования POST-запроса, и отправки его в CRM.

Рассмотрим переменные, которые мы передаем скрипту в начале звонка:

incoming_start — условный идентификатор действия в скрипте

${STRFTIME(${EPOCH},,%s)}  — текущая дата и время в формате Unixtime

${CALLERID(num)} — номер абонента во входящем звонке

${UNIQUEID} — уникальный идентификатор звонка в Asterisk

test.envycrm.com — адрес CRM в которую скрипт отправит информацию о звонке

Также описан extension «h», в котором выполняются команды после завершения звонка. Рассмотрим передаваемые скрипту параметры:

incoming_stop — условный идентификатор действия в скрипте

${STRFTIME(${EPOCH},,%s)}  — текущая дата и время в формате Unixtime

${CALLERID(num)} — номер абонента во входящем звонке

${MEMBERINTERFACE:4} — внутренний номер сотрудника, поднявшего трубку (при использовании очереди вызова «Queue» https://wiki.asterisk.org/wiki/display/AST/Asterisk+Queues)

${CDR(billsec)} — время после соединения оператора и абонента до разъединения

ANSWER — статус входящего звонка

${UNIQUEID} — уникальный идентификатор звонка в Asterisk

test.envycrm.com — адрес CRM в которую скрипт отправит информацию о звонке

Важно! Для работы данного скрипта в системе должен быть установлен пакет CURL и расширение для PHP (php-curl).

Пример отрывка из php-скрипта для отправки POST-запроса

В этом отрывке обрабатывается информация о начале входящего звонка:

...

if ($argv['1'] == "incoming_start") {

$data = array(

"calldate" => $argv['2'],

"direction" => "incoming",

"source" => $argv['3'],

"destination" => 'null',

"duration" => 'null',

"status" => 'null',

"record_url" => 'null',

"event" => "START",

"uid" => $argv['4']

);

$crm_domain = $argv['5'];

...

В этом отрывке обрабатывается информация о завершении входящего звонка.

Важно! Обратите внимание на переменную $record_url. Она содержит ссылку для получения записи разговора с Вашего веб-сервера, чтобы прослушать ее прямо в CRM. При этом запись не будет сохраняться на наших серверах, а каждый раз при прослушивании будет загружаться с Вашего сервера.

...

} else if ($argv['1'] == "incoming_stop") {

$record_url = "https://calls.yourserver.local/gertrecord?callid=".$argv['7']."";

$data = array(

"calldate" => $argv['2'],

"direction" => "incoming",

"source" => $argv['3'],

"destination" => $argv['4'],

"duration" => $argv['5'],

"status" => $argv['6'],

"record_url" => $record_url,

"event" => "END",

"uid" => $argv['7'],

);

$crm_domain = $argv['8'];

}

...

В этом отрывке созданный массив данных преобразуется в POST-запрос, и отправляется в CRM:

...

$url = 'https://'.$crm_domain.'/hook/callapi/';

$data_string = http_build_query($data);

$ch = curl_init();

curl_setopt($ch,CURLOPT_URL, $url);

curl_setopt($ch,CURLOPT_POST, true);

curl_setopt($ch,CURLOPT_POSTFIELDS, $data_string);

$result = curl_exec($ch);

curl_close($ch);

...

Запрос должен содержать массив со следующими переменными:

uid — уникальный идентификатор звонка. Для Asterisk рекомендуется использовать переменную канала ${UNIQUEID};

event — обозначает состояние звонка «START» во время начала звонка, или «END» при его завершении;

direction — обозначение типа звонка «incoming» для входящего, или «outgoing» для исходящего;

source — Номер звонящего (при исходящем звонке — внутренний номер оператора, при входящем — номер абонента);

destination — Номер абонента, которому идет звонок (при исходящем звонке — номер абонента, при входящем — внутренний номер оператора, поднявшего трубку);

lineNumber — внешний номер на который пришел входящий звонок. Например на Asterisk несколько внешних номеров для приема входящих звонков, тогда эта переменная содержит внешний номер, на который поступил звонок.

duration — Длительность соединения после поднятия трубки в секундах;

status — Статус звонка в момент завершения соединения, поддерживаются следующие статусы: ANSWER, BUSY, NOANSWER, CANCEL, CONGESTION, CHANUNAVAIL, DONTCALL, TORTURE, INVALIDARGS;

record_url — Прямая ссылка на запись разговора,

Важно! Если значения переменных еще не определены, то переменным необходимо присвоить значение NULL. Например в начале соединения не известны значения переменных «duration», «status» и «record_url».

После отправки первого запроса в CRM системе появится новая карточка в разделе «Входящие», в ней сразу отобразится звонок, но без подробной информации (например, кто взял трубку, и ссылка на запись разговора). Эта информация появится только после завершения звонка, то есть после отправки второго POST-запроса с уточняющей информацией от Asterisk.

Теперь интеграция Asterisk и CRM настроена!

Чтобы Вы могли звонить прямо из CRM, настройте программу для приема звонков на компьютере или телефоне.