Разбиране на FreePBX и интегрирането му с Bitrix24 и др

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

Работя като аутсорсър във фирма, която продава и конфигурира, интегрира IP телефония. Когато ме попитаха дали можем да предложим нещо на тази и тази компания за интегриране на Bitrix24 с телефонни централи, които клиентите имат, както и с виртуални телефонни централи на различни VDS компании, отидох в Google. И разбира се, той ми даде линк към статия в хабр, където има описание и github и всичко изглежда работи. Но когато се опитах да използвам това решение, се оказа, че Bitrix24 вече не е същият като преди и много трябва да се преработи. В допълнение, FreePBX не е гола звездичка за вас, тук трябва да помислите как да комбинирате лекота на използване и хардкор диалплан в конфигурационните файлове.

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

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

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

Какво има в пакета с покани

Всъщност повечето прости диалпланове работят с първите две полета и цялата логика се върти около DID и CallerID. DID - къде се обаждаме, CallerID - кой се обажда.

Но в края на краищата имаме компания, а не един телефон - което означава, че PBX най-вероятно има групи за повикване (едновременно / последователно звънене на няколко устройства) на градски номера (Ring Group), IVR (Здравейте, вие се обадихте ... Натиснете един за ...), телефонни секретари (фрази), времеви условия, препращане към други номера или към клетка (FollowMe, Forward). Това означава, че е много трудно да се определи недвусмислено кой всъщност ще получи обаждане и с кого ще проведе разговор, когато пристигне повикване. Ето пример за начало на типичен разговор в телефонната централа на наши клиенти

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

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

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

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

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

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

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

Вътре в Asterisk е:

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

• AMI - текстов TCP сокет, който работи на принципа на абониране за събития и въвеждане на текстови команди, наподобява SMTP отвътре, може да проследява събития и да управлява повиквания, има библиотека ПАМИ - най-популярният за създаване на връзка със звездичка

Пример за AMI изход

Събитие: Нов канал
Привилегия: обадете се на всички
Канал: PJSIP/VMS_pjsip-0000078b
Състояние на канала: 4
ChannelStateDesc: Звънене
ИД на повикващия: 111222
ИД на обаждащия се: 111222
ConnectedLineNum:
свързано име на линия:
Език: en
код на акаунта:
Контекст: от-pstn
Разширение: s
Приоритет: 1
Уникален номер: 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″, «име»:»PJSIP/VMSpjsip-000007b6″, "state":"Позвъняване", "caller":{ "name":"111222″, "number":"111222″ }, "connected":{ "name":"", "number" :"" }, "accountcode":"", "dialplan":{ "context":"from-pstn", "exten":"s", "priority":2, "appиме":"Stasis", "прилdata":"hello-world" }, "creationtime":"2020-09-09T09:38:35.926+0000", "language":"en" }, "asteriskid":"48:5b:aa:aa:aa:aa", "приложение":"здравей-свят"}

Удобството или неудобството, възможността или невъзможността за работа с конкретен 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 събитие за тази линия

Събитие: Нов канал

Привилегия: обадете се на всички

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

Състояние на канала: 4

ChannelStateDesc: Звънене

ИД на повикващия: 111222

ИД на обаждащия се: 111222

ConnectedLineNum:

свързано име на линия:

Език: en

код на акаунта:

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

Разширение: s

Приоритет: 1

Уникален номер: 1599589046.5244

Linkedid: 1599589046.5244

Приложение: Задайте AppData:

CallStart=1599571046

Тъй като FreePBX презаписва файловете extention.conf и extention_Additional.conf, ще използваме файла разширение_обичай.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'
exten =>  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)})

;; Самое главное! Обработчик окончания разговора. 
;; Обычные пути обработки конца через (exten=>h,1,чтототут) в FreePBX не работают - 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

Характеристика и разлика от оригиналния диалплан на авторите на оригиналната статия -

• Dialplan във формат .conf, както го иска FreePBX (да, може .ael, но не всички версии и не винаги е удобно)

• Вместо обработка на края чрез exten=>h, обработката беше въведена чрез hangup_handler, тъй като FreePBX dialplan работеше само с него

• Фиксиран низ за извикване на скрипт, добавени кавички и външен номер за повикване 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, след което прочетете отново конфигурациите (или рестартирайте звездичката)

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

Сега да преминем към PHP

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

Тъй като схемата за работа с Bitrix 24, услуга за AMI, не е съвсем проста и прозрачна, тя трябва да бъде обсъдена отделно. Asterisk при активиран AMI просто отваря порта и това е. Когато клиент се присъедини, той иска оторизация, след което клиентът се абонира за необходимите събития. Събитията идват в обикновен текст, който PAMI преобразува в структурирани обекти и предоставя възможност за задаване на функцията за филтриране само за събития от интерес, полета, числа и т.н.

Веднага щом влезе повикването, събитието NewExten се задейства, като се започне от родителския [from-pstn] контекст, след което всички събития вървят по реда на редовете в контекстите. Когато се получи информация от променливите CallMeCallerIDName и CallStart, посочени в _custom dialplan,

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

2. Функцията за регистриране на разговори в Bitrix24, която връща CallID, който след това е необходим за отчитане на параметрите на разговора и връзка към записа. Изисква или вътрешен номер, или потребителско име

След края на разговора се извиква функцията за изтегляне на запис, която едновременно отчита статуса на приключване на разговора (Зает, Без отговор, Успех), а също така изтегля връзка към 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 или услуга

# systemctl enable callme
# systemctl start callme

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

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

• Иницииране на повикване при получаване на заявка за php скрипт (включително с помощта на бутона "Повикване" в самия Bitrix). Не работи без уеб сървър, заявката се получава чрез HTTP POST, заявката съдържа токен

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

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

уеб сървър

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

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

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

докер

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

Трябва да стартирате файла в изтеглената папка на проекта (след git clone), но първо влезте в конфигурациите на звездичката (папка със звездичка) и запишете там пътищата до записите и 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 в скриптове в същото време, помислихме си. Проучихме няколко други CRM API, особено безплатната вградена PBX - ShugarCRM и Vtiger, и да! да, принципа е същият. Но това е друга история, която по-късно ще качим отделно в github.

Позоваването

• Самият код е в github - https://github.com/CrezZ/bitrix24-freepbx-php

• Изходна статия за семена https://habr.com/ru/post/349316/

Отказ от отговорност: Всяка прилика с реалността е фиктивна и това не съм аз.

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