Запознайте се с FreePBX и го интегрирайте с Битрикс24 и не само това

Битрикс24 е могъщ инструмент, който съчетава CRM, управление на документи, счетоводство и множество други функции, които харесват на мениджърите, но не толкова на ИТ специалистите. Порталът се използва от много малки и средни företag, включително малки клиники, производители и дори салони за красота. Основната функция, която мениджърите „обичат“, е интеграцията на телефонията с CRM, при която всеки обаждане се записва веднага в CRM, създават се клиентски карти, информацията за клиента се показва при входящо обаждане и веднага се вижда какъв е клиентът, какво може да му се продаде и колко дължи. Но телефонията от Битрикс24 и нейната интеграция с CRM е платена, понякога значително. В статията ще споделя опит за интеграция с открити инструменти и популярна IP АТС FreePBX, както и ще разгледам логиката на работа на различните части

Работя на аутсорс в компания, която се занимава с продажба, настройка и интеграция на IP телефония. Когато ме попитаха, можем ли да предложим нещо за интеграция на Битрикс24 с АТС, които клиентите имат, а също и с виртуални АТС на различни VDS на компании, аз се насочих към Гугъл. И той ми даде линк на статия в Хабр, където имаше описание, GitHub и всичко изглеждаше да работи. Но при опит за ползване на това решение стана ясно, че Битрикс24 вече не е това, което беше, и много неща трябва да се преработят. Освен това, FreePBX не е просто гола Asterisk, тук трябва да се мисли как да се комбинира удобството на употреба с хардкорния диалплан в конфигурационните файлове.

Изучаване на логиката на работа

И така, за начало, как трябва да работи всичко това. Когато получим обаждане от вън на АТС (събитие SIP INVITE от доставчика), започва обработката на диалплана (правила какво и в какъв ред да се прави с обаждането). От първия пакет можем да получим много информация, която след това може да бъде използвана в правилата. Отличен инструмент за изучаване на вътрешностите на SIP е анализаторът sngrep (линк) който лесно се инсталира на популярни дистрибуции чрез apt install/yum install и подобни команди, но може да се компилира и от изходен код. Нека разгледаме лог на обаждане в sngrep.

В простото диалпланът се занимава само с първия пакет, понякога по време на разговора се извършва и пренасочване на повиквания, натискане на бутони (DTMF), различни интересни функции като FollowMe, RingGroup, IVR и други.

Какво има в пакета Invite

По същество повечето прости диалплани работят с първите две полета, а всичката логика е фокусирана около DID и CallerID. DID е номерът, на който звъним, CallerID е номерът, от който звънят.

Но ние сме фирма, а не само един телефон — значи вероятно в АТС има групи за повиквания (паралелно/последователно звъняне на няколко устройства) на градски номера (Ring Group), IVR (Здравейте, звъннахте на… Натиснете едно за…), Автоотговорници (Phrases), Временни условия (Time Conditions), Пренасочване на други номера или на мобилен (FollowMe, Forward). Това означава, че е много трудно да се определи кой точно ще получи повикването и с кого ще разговаря при постъпване на повикването. Ето един пример за начина, по който типично повикване преминава в АТС на нашите клиенти.

След успешното влизане на повикването в АТС, то преминава през диалплана в различни "контексти". Контекстът от гледна точка на Asterisk е номериран набор от команди, всяка от които съдържа филтър по набрания номер (този филтър се нарича exten, за външно повикване в начален етап exten=DID). Командите в реда на диалплана могат да бъдат каквито и да било — вътрешни функции (например да звъни на вътрешен абонат — Dial(), да положи слушалката — Hangup()), условни оператори (IF, ELSE, ExecIF и подобни), преходи към други правила на този контекст (Goto, GotoIF), преход към други контексти под формата на повиквания на функции (Gosub, Macro). Отделно е директивата include име_контекста, която добавя команди от друг контекст в края на текущия контекст. Командите, включени чрез include, се изпълняват винаги след в рамките на текущия контекст.

Цялата логика на работа на FreePBX е изградена на включването един в друг на различни контексти чрез include и повиквания чрез Gosub, Macro и обработчици Handler. Нека разгледаме контекста на входящите повиквания на FreePBX.

Повикването преминава през всички контексти отгоре надолу по реда, в който може да има повиквания на други контексти като макроси (Macro), функции (Gosub) или просто преходи (Goto), затова реалното дърво на това, което се извиква, може да се проследи само в логовете.

Типова схема за настройка на типичен офис AТС е показана по-долу. При входящи обаждания се търси DID, по който се проверяват времевите условия; ако всичко е наред — стартира се гласово меню. От него чрез натискане на бутон 1 или по таймаут се преминава към група оператори. След края на разговора се извиква макрос hangupcall, след който нищо друго в диалплана не може да се изпълни, освен специални обработчици (hangup handler).

Къде в този алгоритъм за обаждане трябва да предоставяме информация за началото на обаждането в CRM, къде да започваме запис, къде да приключваме записа и да го изпращаме заедно с информацията за обаждането на CRM?

Итерация с външни системи

Какво е интеграция между AТС и CRM? Това са настройки и програми, които конвертират данни и събития между двете платформи и ги предават помежду си. Най-разпространеният начин за взаимодействие на независими системи е чрез API, а най-популярният начин за достъп до API е HTTP REST. Но не и за asterisk.

Вътре в Asterisk има:

• AGI — синхронно извикване на външни програми/компоненти, използва се основно в диалплана, има библиотеки като phpagi, PAGI

• AMI — текстов TCP сокет, който работи на принципа на подписване на събития и въвеждане на текстови команди, напомня на SMTP от вътре, може да проследява събития и да управлява повиквания, има библиотека PAMI — най-популярната за създаване на връзки с Asterisk

Примерен изход от AMI

Събитие: Newchannel
Привилегия: call,all
Канал: PJSIP/VMS_pjsip-0000078b
ChannelState: 4
ChannelStateDesc: Ring
CallerIDNum: 111222
CallerIDName: 111222
ConnectedLineNum:
ConnectedLineName:
Език: en
AccountCode:
Контекст: from-pstn
Exten: s
Приоритет: 1
Uniqueid: 1599589046.5244
Linkedid: 1599589046.5244

• ARI — смес от двете, всичко през REST, WebSocket, в JSON формат — но с новите библиотеки и обвивки нещата не са много ясни, на пръв поглед намерихме (phparia, phpari) които в развитието си са около 3 години назад.

Примерен изход от ARI при иницииране на обаждане

{ "variable":"CallMeCallerIDName", "value":"111222", "type":"ChannelVarset", "timestamp":"2020-09-09T09:38:36.269+0000", "channel":{ "id":"1599644315.5334", "name":"PJSIP/VMSpjsip-000007b6", "state":"Ring", "caller":{ "name":"111222", "number":"111222" }, "connected":{ "name":"", "number":"" }, "accountcode":"", "dialplan":{ "context":"from-pstn", "exten":"s", "priority":2, "appname":"Stasis", "appdata":"hello-world" }, "creationtime":"2020-09-09T09:38:35.926+0000", "language":"ru" }, "asteriskid":"48:5b:aa:aa:aa:aa", "application":"hello-world" }

Удобството или неудобството, възможността или невъзможността за работа с дадено API се определя от задачите, които трябва да се решат. Задачите за интеграция с CRM са следните:

• Да се проследи началото на обаждането, къде е пренасочено, да се извлече CallerID, DID, времето на начало и край, може би данни от директорията (за свързване на телефона и потребителя в CRM)

• Да се започне и завърши записа на обаждането, да се запази в необходимия формат, да се съобщи след завършване на записа къде се намира файлът

• Да се инициира обаждане по външно събитие (от програмата), да се позвъни на вътрешен номер, външен и да се свържат

• По избор: интегриране с CRM, групи за обаждане и FollowME за автоматично пренасочване на обаждания, когато не сте на място (по информация от CRM)

Всички тези задачи могат да се решат чрез AMI или ARI, но ARI предоставя значително по-малко информация, няма много събития, много променливи не се проследяват, които в AMI все пак съществуват (например извиквания на макроси, задаване на променливи в рамките на макроси, включително запис на обаждания). Затова, за правилно и точно проследяване — засега ще изберем AMI (но не окончателно). Освен това (как иначе, ние сме мързеливи) — в основната работа (статия в хабр) използват PAMI. *След това трябва да пробваме да го пренапишем на ARI, но не е сигурно, че ще се получи.

Придумваме интеграцията отново

За да може нашият FreePBX да съобщава на AMI по прост начин за началото на обаждането, времето на края, номерата, имената на записаните файлове, най-лесно е да използваме същия трик, който използваха и оригиналните автори — да въведем свои променливи и да анализираме изхода за тяхното присъствие. PAMI предлага да се прави това просто чрез функция-филтър.

Ето пример за задаване на собствена променлива за времето на начало на обаждането (s — това е специален номер в диалплана, който се изпълнява ПРЕДИ началото на търсенето по DID)

[ext-did-custom]

exten => s,1,Set(CallStart=${STRFTIME(epoch,,%s)})

Пример на AMI събитие по тази линия

Събитие: Newchannel

Привилегия: call,all

Канал: PJSIP/VMS_pjsip-0000078b

ChannelState: 4

ChannelStateDesc: Ring

CallerIDNum: 111222

CallerIDName: 111222

ConnectedLineNum:

ConnectedLineName:

Език: en

AccountCode:

Контекст: from-pstn

Exten: s

Приоритет: 1

Uniqueid: 1599589046.5244

Linkedid: 1599589046.5244

Application: Set AppData:

CallStart=1599571046

Понеже FreePBX презаписва файловете extention.conf и extention_additional.conf, ще използваме файла extention_custom.conf

Пълен код extention_custom.conf

[globals]
;; Проверете пътищата и правата на папките - потребителят asterisk трябва да има права за запис
;; Тук ще се записват разговорите
WAV=\/var\/www\/html\/callme\/records\/wav 
MP3=\/var\/www\/html\/callme\/records\/mp3

;; По тези пътища ще се възпроизвеждат и свалят записите
URLRECORDS=https:\/\/www.host.ru\/callmeplus\/records\/mp3

;; Адрес за обратен повик на изходящо обаждане
URLPHP=https:\/\/www.host.ru\/callmeplus

;; Да, записваме разговорите
RECORDING=1

;; Това е макрос за запис на разговори в нашата папка.
;; Може да се използва и системен запис, но засега нека да е този - 
;; той работи
[recording]
exten => ~~s~~,1,Set(LOCAL(calling)=${ARG1})
exten => ~~s~~,2,Set(LOCAL(called)=${ARG2})
exten => ~~s~~,3,GotoIf($["${RECORDING}" = "1"]?4:14)
exten => ~~s~~,4,Set(fname=${UNIQUEID}-${STRFTIME(${EPOCH},,%Y-%m-%d-%H_%M)}-${calling}-${called})
exten => ~~s~~,5,Set(datedir=${STRFTIME(${EPOCH},,%Y\/%m\/%d)})
exten => ~~s~~,6,System(mkdir -p ${MP3}\/${datedir})
exten => ~~s~~,7,System(mkdir -p ${WAV}\/${datedir})
exten => ~~s~~,8,Set(monopt=nice -n 19 \/usr\/bin\/lame -b 32  --silent "${WAV}\/${datedir}\/${fname}.wav"  "${MP3}\/${datedir}\/${fname}.mp3" && rm -f "${WAV}\/${fname}.wav" && chmod o+r "${MP3}\/${datedir}\/${fname}.mp3")
exten => ~~s~~,9,Set(FullFname=${URLRECORDS}\/${datedir}\/${fname}.mp3)
exten => ~~s~~,10,Set(CDR(filename)=${fname}.mp3)
exten => ~~s~~,11,Set(CDR(recordingfile)=${fname}.wav)
exten => ~~s~~,12,Set(CDR(realdst)=${called})
exten => ~~s~~,13,MixMonitor(${WAV}\/${datedir}\/${fname}.wav,b,${monopt})
exten => ~~s~~,14,NoOp(Finish if_recording_1)
exten => ~~s~~,15,Return()


;; Това е основният контекст за началото на разговора
[ext-did-custom]

;; Това е нередност, да се прави така тук, но работи - добавяме '8' към номера
nexten =>  s,1,Set(CALLERID(num)=8${CALLERID(num)})

;; Тук всякакви променливи за скрипта
exten =>  s,n,Gosub(recording,~~s~~,1(${CALLERID(number)},${EXTEN}))
exten =>  s,n,ExecIF(${CallMeCallerIDName}?Set(CALLERID(name)=${CallMeCallerIDName}):NoOp())
exten =>  s,n,Set(CallStart=${STRFTIME(epoch,,%s)})
exten =>  s,n,Set(CallMeDISPOSITION=${CDR(disposition)})

;; Най-важното! Обработчик на края на разговора.
;; Обикновените пътища за обработка на края не работят - Macro(hangupcall,) всичко разваля.
;; Затова задаваме Hangup_Handler на края на обаждането
exten => s,n,Set(CHANNEL(hangup_handler_push)=sub-call-from-cid-ended,s,1(${CALLERID(num)},${EXTEN}))

;; Обработчик на края на входящо обаждане
[sub-call-from-cid-ended]

;; Докладваме стойностите при края на обаждането
exten => s,1,Set(CDR_PROP(disable)=true)
exten => s,n,Set(CallStop=${STRFTIME(epoch,,%s)})
exten => s,n,Set(CallMeDURATION=${MATH(${CallStop}-${CallStart},int)})

;; Статус на обаждането - Отговор, неотговорено...
exten => s,n,Set(CallMeDISPOSITION=${CDR(disposition)})
exten => s,n,Return


;; Обработчик на изходящи обаждания - всичко аналогично
[outbound-allroutes-custom]

;; Запис
exten => _.,1,Gosub(recording,~~s~~,1(${CALLERID(number)},${EXTEN}))
;; Променливи
exten => _.,n,Set(__CallIntNum=${CALLERID(num)})
exten => _.,n,Set(CallExtNum=${EXTEN})
exten => _.,n,Set(CallStart=${STRFTIME(epoch,,%s)})
exten => _.,n,Set(CallmeCALLID=${SIPCALLID})

;; Задаваме Hangup_Handler на края на обаждането
exten => _.,n,Set(CHANNEL(hangup_handler_push)=sub-call-internal-ended,s,1(${CALLERID(num)},${EXTEN}))

;; Обработчик на края на изходящо обаждане
[sub-call-internal-ended]

;; променливи
exten => s,1,Set(CDR_PROP(disable)=true)
exten => s,n,Set(CallStop=${STRFTIME(epoch,,%s)})
exten => s,n,Set(CallMeDURATION=${MATH(${CallStop}-${CallStart},int)})
exten => s,n,Set(CallMeDISPOSITION=${CDR(disposition)})

;; Извикваме скрипта, който ще съобщи за обаждането в CRM - това е изходящо,
;; така че по факти на края
exten => s,n,System(curl -s ${URLPHP}\/CallMeOut.php --data action=sendcall2b24 --data ExtNum=${CallExtNum} --data call_id=${SIPCALLID} --data-urlencode FullFname='${FullFname}' --data CallIntNum=${CallIntNum} --data CallDuration=${CallMeDURATION} --data-urlencode CallDisposition='${CallMeDISPOSITION}')
exten => s,n,Return

Характеристика и отличие от оригинального диалплана авторов исходной статьи —

• Диалплан в формате .conf, потому что FreePBX этого требует (да, он поддерживает .ael, но не все версии и не всегда это удобно)

• Вместо обработки окончания через exten=>h введена обработка через hangup_handler, так как диалплан FreePBX заработал только с ним

• Исправлена строка вызова скрипта, добавлены кавычки и внешний номер звонка ExtNum

• Обработки вынесены в _custom контексты и позволяют не трогать и не править конфиги FreePBX — входящие через [ext-did-custom], исходящие через [outbound-allroutes-custom]

• Нет привязки к номерам — файл универсален и требует настройки только пути и ссылки на сервер

Для начала работы нужно также запустить скрипты в AMI по логину и паролю — для этого в FreePBX тоже есть _custom файл

Файл manager_custom.conf

;; это логин
[callmeplus]
;; это пароль
secret = trampampamturlala
deny = 0.0.0.0/0.0.0.0

;; я работаю с локальной машиной - но если нужно, можно прописать и другие
permit = 127.0.0.1/255.255.255.255
read = system,call,log,verbose,agent,user,config,dtmf,reporting,cdr,dialplan
write = system,call,agent,log,verbose,user,config,command,reporting,originate

Оба этих файла нужно поместить в /etc/asterisk, затем перечитать конфиги (или перезапустить Asterisk)

# astrisk -rv
  Connected to Asterisk 16.6.2 currently running on freepbx (pid = 31629)
#freepbx*CLI> dialplan reload
     Dialplan reloaded.
#freepbx*CLI> exit

Теперь перейдем к PHP

Инициализация скриптов и создание сервиса

Поскольку схема работы с Битрикс 24, сервисом для AMI, не совсем проста и прозрачна, ей следует уделить отдельное внимание. Asterisk при активации AMI просто открывает порт и все. При подключении клиента он запрашивает авторизацию, затем клиент подписывается на нужные события. События приходят в простом текстовом формате, который PAMI преобразует в структурированные объекты и предоставляет возможность задания функции фильтрации только по интересующим событиям, полям, номерам и т.д.

Как только поступает звонок, возникает событие NewExten, начиная с родительского контекста [from-pstn], затем идут все события в порядке следования строк в контекстах. При получении информации из заданных в диалплане _custom переменных CallMeCallerIDName и CallStart вызывается.

1. Функцията за запитване UserID, съответстваща на вътрешния номер, към който е постъпило обаждането. А ако това е група повиквания? Въпросът е политически, трябва ли да се направи обаждане до всички наведнъж (когато звънят всички едновременно) или да се извършва поетапно, при едно след друго обаждане? При повечето клиенти е зададена стратегията First Available, затова нямаме проблеми, звъни само един човек. Но въпросът трябва да се реши.

2. Функцията за регистрация на обаждане в Битрикс24, която връща CallID, необходим по-късно за докладване на параметрите на обаждането и линка към записа. Изисква или вътрешен номер, или UserID.

След приключването на обаждането се извиква функцията за зареждане на записа, която едновременно съобщава статуса на приключване на обаждането (Зает, Няма отговор, Успех), а също така зарежда линк към mp3 файла с записа (ако има такъв).

Тъй като модулът CallMeIn.php трябва да работи непрекъснато, за него беше създаден файл за стартиране на SystemD. callme.service, който трябва да бъде поставен в /etc/systemd/system/callme.service

[Unit]
Description=CallMe

[Service]
WorkingDirectory=/var/www/html/callmeplus
ExecStart=/usr/bin/php /var/www/html/callmeplus/CallMeIn.php 2>&1 >>/var/log/callmeplus.log
ExecStop=/bin/kill -WINCH ${MAINPID}
KillSignal=SIGKILL

Restart=on-failure
RestartSec=10s

#тук трябва да се проверят правата на папките
#User=www-data  #Ubuntu - debian
#User=nginx #Centos

[Install]
WantedBy=multi-user.target

инициализацията и стартирането на скрипта се извършва чрез systemctl или service.

# systemctl enable callme
# systemctl start callme

Сервисът ще се перезапуска по необходимост (при падания). Сервизът за наблюдение на входящи обаждания не изисква инсталиране на уеб сървър, необходим е само PHP (който със сигурност е наличен на сървъра FeePBX). Но при липса на достъп до записите на обажданията чрез уеб сървър (още и с https) няма да има възможност за прослушване на записите на разговорите.

Сега да поговорим за изходящите обаждания. Скриптът CallMeOut.php има две функции:

• Иницииране на обаждане при постъпване на запитване към PHP скрипта (включително по бутона „Позвъни“ в самия Битрикс). Без уеб сървър не работи, запитването постъпва чрез HTTP POST, в запитването се съдържа токен.

• Съобщение за обаждането, неговите параметри и записи в Битрикс. Става по инициатива на Asterisk в диалплана [sub-call-internal-ended] при приключване на обаждането.

Уеб сървър е необходим само за две неща — зареждане на файлове с записи от Битрикс (по HTTPS) и извикване на скрипта CallMeOut.php. Може да се използва вграден сървър FreePBX, файловете за който се намират в /var/www/html, може да се инсталира друг сървър или да се зададе друг път.

Уеб сървър

Оставяме настройката на уеб сървъра за самостоятелно изучаване (цък, цък, цък). Ако нямате домейн, можете да опитате FreeDomain( https://www.freenom.com/ru/index.html), които безплатно ще ви предоставят име за вашия бял IP (не забравяйте да пренасочите портовете 80, 443 през рутера, ако външният адрес е само на него). Ако току-що сте създали DNS домейн, трябва да изчакате (от 15 минути до 48 часа), докато всички сървъри се заредят. Според опитите с местни доставчици - от 1 час до 24 часа.

Автоматизация на инсталацията

В GitHub е започнато разработването на инсталатор, за да може да се инсталира още по-лесно. Но гладко беше само на хартия — за момента инсталираме всичко ръчно, но след работа с всичко това стана кристално ясно, кой с кого дружи, кой накъде ходи и как да го дебъгваме. Все още няма инсталатор (

Docker

Ако искате бързо да тествате решението — има опция с Docker — бързо създайте контейнер, дайте му портове навън, подайте файлове с настройки и опитайте (това е вариант с контейнера на LetsEncrypt, ако сертификатът вече е наличен, просто трябва да пренасочите обратния прокси към уеб сървъра FreePBX (на него сме дали друг порт — 88), LetsEncrypt в Docker по мотиви тази статия

Файлът трябва да се стартира в изтеглената папка на проекта (след git clone), но предварително трябва да се промени в конфигурациите на Asterisk (папка asterisk) и да се зададат пътища към записите и URL адреса на вашия сайт.

version: '3.3'
services:
  nginx:
    image: nginx:1.15-alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - .\/nginx\/ssl_docker.conf:\/etc\/nginx\/conf.d\/ssl_docker.conf
  certbot:
    image: certbot\/certbot
  freepbx:
    image: flaviostutz\/freepbx
    ports:
      - 88:80 # за настройка
      - 5060:5060\/udp
      - 5160:5160\/udp
      - 127.0.0.1:5038:5038 # за CallMeOut.php
#      - 3306:3306
      - 18000-18100:18000-18100\/udp
    restart: always
    environment:
      - ADMIN_PASSWORD=admin123
    volumes:
      - backup:\/backup
      - recordings:\/var\/spool\/asterisk\/monitor
      - .\/callme:\/var\/www\/html\/callme
      - .\/systemd\/callme.service:\/etc\/systemd\/system\/callme.conf
      - .\/asterisk\/manager_custom.conf:\/etc\/asterisk\/manager_custom.conf
      - .\/asterisk\/extensions_custom.conf:\/etc\/asterisk\/extensions_custom.conf
#      - .\/conf\/startup.sh:\/startup.sh

volumes:
  backup:
  recordings:

Този файл docker-compose.yaml се стартира чрез

docker-compose up -d

Ако nginx не се стартира, значи нещо не е наред с конфигурацията в папката nginx\/ssl_docker.conf

Други интеграции

А защо да не включим и няколко CRM в скриптовете, помислихме. Изучихме няколко API на други CRM, особено безплатната, вградена в някои АТС — ShugarCRM и Vtiger, и да! може, принципът е същият. Но това е друга история, която после ще качим на GitHub отделно.

Връзки

• Кодът е на GitHub — https://github.com/CrezZ/bitrix24-freepbx-php

• Статия за вдъхновение https://habr.com/ru/post/349316/

Дисклеймер: всякакви съвпадения с реалността са измислени и аз не съм бил там,

Източник: habr.com