Как сделать модуль для битрикс 24
Обновлено: 08.07.2024
В данном посте я расскажу о том, как мы реализовали кастомный коннектор для интеграции WhatsApp в открытые линии Битрикс24, используя API сервиса Chat2desk.
Существует официальный курс
по разработке кастомных коннекторов для Битрикс24. Однако не все технические моменты освещены в нем подробно.
Начинаем писать код с создания нового модуля под Битрикс Маркетплейс.
Рис 1. Модуль в списке Доступных решений.
Создаем библиотеку модуля, в котором будет храниться логика его работы. Данный класс будет подключаться каждый раз при вызове модуля. Для отображения коннектора в списке доступных конекторов открытых линий – необходимо подписаться на событие OnImConnectorBuildList модуля imconnector, и по нему вернуть информацию о нашем новом коннекторе.
В библиотеке модуля реализовываем обработчик события OnImConnectorBuildList. Привязку обработчика к событию производим при установке модуля. Соответственно при удалении модуля – привязку снимаем.
Рис 2. Коннектор с списке подключенных каналов открытой линии
В массиве информации о коннекторе, мы должны указать компонент, который будет отображаться в качестве формы настроек коннектора. Этот компонент создаем на основе стандартного компонента imconnector.baseconnector и помещаем в состав нашего модуля.
Рис 3. Форма настроек коннектора
В нашем случае нам необходимо хранить токен для доступа к агрегатору. Здесь сталкиваемся с первой проблемой. Стандартный механизм не предлагает нам способа хранения настроек. Вернее, компонент imconnector.baseconnector нам предлагает хранить настройки в именованном кэше. У нас этот кэш очищался раз в сутки, соответственно настройки сбрасывались. Поэтому мы таким способом не воспользовались и сохранили настройки, воспользовавшись COption::SetOptionString().
Таким образом мы получили коннектор для открытых линий, теперь перейдем к реализации логики его работы.
Здесь всплывает следующий подводный камень. Как видно – в массиве message_data в поле user можно задать name (имя, с которым пользователь мессенджера будет добавлен в чат). При его задании – Битрикс будет проводить поиск по базе CRM и пытаться привязать диалог к сущностям CRM. Вроде бы все ничего, но делает он это по имени, которое может быть совсем не уникально. Соответственно диалог может прикрепиться не туда, куда вы можете ожидать. В тоже время он не ищет по номерам телефонов, email и значениям полей мессенджеров, что странно. Обычно внешняя система может прислать вам номер телефона, или id мессенджера, который зачастую является email. Намного больше смысла искать по ним.
Собственно сама привязка заключается в том, что Битрикс добавляет открытую линию в контакты сущности, и создает дела у этой сущности.
В нашем случае, было необходимо привязывать диалог к сделкe в CRM по номеру телефона. Для этого мы написали функцию, которая ищет номера телефонов в CRM сущностях (контактах, лидах, компаниях) и возвращает список сделок связанных с найденными сущностями, к которым нужно осуществить привязку. Тут важно учитывать то, что телефоны могут храниться в разных форматах, поэтому поиск нужно вести с помощью Bitrix\Crm\Integrity\DuplicateCommunicationCriterion
Однако дело не привязывается напрямую к чату, а привязывается к его сессии. То есть у одного диалога (чата) может быть несколько сессий.
Получить идентификатор сессии можно таким образом:
Рис 4. Диалог в карточке CRM
Для добавления ссылки на чат в контакт или лид можно воспользоваться таким кодом:
Рис 5. Ссылка на чат в карточке CRM
Далее, выясняется, что \Bitrix\ImConnector\CustomConnectors::sendMessages не запускает триггеры автоматизации. Запустить их принудительно можно с помощью Bitrix\ImOpenLines\Crm ->executeAutomationTrigger();
Пример данных, приходящих в обработчик:
Как видно, Битрикс отдает ссылку. Но это не ссылка на файл, а ссылка на html страницу, с которой файл можно скачать. Естественно, внешняя система не может этого сделать. Поэтому нам нужна прямая ссылка на файл. Чтобы ее получить – нужно знать ид файла. Но этой информации у нас нет. Поэтому будем в очередной раз изобретать велосипед:
Имея короткую ссылку, можно найти информацию о полной ссылке на файл:
Полная ссылка на файл содержит в себе хэш, по которому можно найти файл:
То есть, помимо ид файла, нам еще нужен и токен загрузки. Формируется он следующим образом:
Так мы получим прямую ссылку на файл. Однако как видно – токен хранится в сессии
И доступ к файлу по этой ссылке, скорее всего, будет только у пользователя, отправившего файл. Такое решение нам не подходит , нам нужно иметь возможность отдавать файл всегда, вне зависимости от сессии. Для этого можно создать собственный скрипт, который по короткой ссылке будет вычислять id файла, и отдавать его содержимое с помощью:
Теперь мы можем отдавать файл без проверки токена (со всеми вытекающими предосторожностями) . Это уже что-то, но все таки, хочется иметь возможность не только отправлять прямую ссылку на файл (всегда доступную), но и отправлять сам файл. И здесь мы сталкиваемся с неожиданной проблемой: Дело в том, что во время отработки события OnSendMessageCustom пересылаемый файл еще не занял своего положения на Битрикс.Диске, а до окончания выполнения обработчика функции OnSendMessageCustom существует как запись в бд вида:
Как видите размер у него равен нулю, content-type равен application/octet-stream. При попытке в обработчике найти файл /upload/disk/a8a/a8a71448e3092e5af419e9fb853d5ea5 с помощью Bitrix\Main\IO\File — сообщает что файл не существует. На самом деле — сразу после выполнения обработчика события OnSendMessageCustom — файл перемещается на Диск в другое хранилище (что-то вроде хранилища файлов открытых линий). И тогда становится нормальным, доступным. Но, это все происходит уже после окончания работы обработчика OnSendMessageCustom. Соответственно, внешняя система не сможет скачать файл пока мы находимся в обработчике.
Для решения этой проблемы нужно не отправлять информацию о пересылаемом файле внешней системе в обработчике OnSendMessageCustom, а делать это позже, когда файл уже будет перемещен.
Вот такие интересные особенности разработки кастомного коннектора мы открыли для себя, когда писали интеграцию коробочной версии Битрикс24 с WhatsApp.
Битрикс24 позволяет публиковать в ленту Новостей отчёты и печатные формы из 1С. Для этого существует специальный модуль.
Как установить модуль?
Для начала необходимо скачать файл установки.
Модуль работает как расширение - файл установки сам определит конфигурацию 1С и скачает нужную версию модуля.
Теперь зайдём в 1С и откроем загруженный файл.
Окно установки содержит основную информацию о модуле - текущую версию и изменения, а также требования к системе.
Выбираем Установить модуль, после установки клиент необходимо перезапустить.
Теперь в разделе Компания есть пункт Подключить экспорт печатных форм в Битрикс24.
Готово! Модуль установлен.
Как создать подключение к Битрикс24?
Для связи портала Битрикс24 и базы 1С используется специальный ключ. В Битрикс24 откроем приложение 1С + CRM Битрикс24 и скопируем код.
Следующий этап - подключение модуля к Битрикс24. Выберем пункт Компания - Подключить экспорт печатных форм.
Нам необходимо создать новое подключение.
В новом окне укажем название настройки и ключ подключения - модуль сам определит адрес портала.
При желании, можно указать формат для сохранения отчётов. По умолчанию это PDF.
Инструктаж о том, как правильно сделать копию боевого портала Битрикс24 для тестирования разработок.
Пошагово пробежимся, что вам необходимо выполнить, для создания копии коробочного портала Битрикс24 для тестирования разработок.
Когда машина готова, на неё нужно перенести резервную копию портала.
Перед тем, как делать резервную копию, отключите модуль проактивной защиты. При переносе на тестовый сервер и изменении адресов его настройки могут не позволить вам даже авторизоваться.
Через браузер обращаемся к виртуальной машине, выбираем в меню пункт восстановления копии и восстанавливаем (можно даже по ссылке с удалённого сайта, чтобы не перекачивать копию на сервер самостоятельно).
Эти пункты подробно не расписываем, они нужны больше для полноты описания процесса. Уверены, что с ними у вас проблем не будет.
Дело в том, что на одном лицензионном ключе Битрикс24, согласно лицензионному соглашению, можно одновременно использовать две копии. Но одна из них - для работы, а вторая - для тестов. И эта галочка говорит системе обновлений, что копия тестовая и нарушения лицензионного соглашения нет, ключ блокировать не нужно.
2. Прописываем тестовый адрес портала в настройках сайтов, главном модуле, настройках модуля чат-ботов.
У вас были подключены открытые линии к CRM? Так вот они могут быть подключены одновременно только к одному порталу. Поэтому быстренько их отключаем. Да так, чтобы никакие ключи подключения не уцелели. Чтобы по отдельности не отключать и ничего не забыть, быстрее всего переустановить модуль.
4. Ломаем отправку почтовых уведомлений или работу модуля почты, чтобы пользователи не получали уведомления с тестового портала (в настройках виртуальной машины отключаем подключение к SMTP).
Как правило, никакие письма с тестового портала отправляться не должны: ни уведомления, ни маркетинговые рассылки. Так что на всякий случай просто делаем так, чтобы почта не отправлялась. Если на боевом портале для отправки писем используются сторонние модули - удаляем и эти настройки.
5. Деактивируем все почтовые шаблоны и почтовые события. Переходим в Настройки - Настройки продукта.
Чтобы наверняка ничего никуда с портала не ушло. Уведомления (в том числе и СМС) работают с использованием шаблонов. Значит, нужно сделать так, чтобы Битрикс24 не знал, как это сделать.
6. Деактивируем все почтовые ящики. Заходим в Сервисы - Почта - Почтовые ящики.
Если вы и ваши коллеги подключали почтовые ящики, чтобы получать и отправлять почту, то на тестовом портале это уже не будет нужно. И, более того, может навредить (мало ли, вы заходите письма удалить, а они и с почтового сервера удалятся). Нужен будет ящик для тестов - подключите потом.
От старых ключей подключения мы избавились, теперь нужно получить новые. Переустановка это решит.
9. Если были установленные или созданные локальные приложения/вебхуки, которые нужны на копии, то их придется вычищать из базы и ставить заново.
Всё потому, что мы переустанавливали модуль rest. Но так было нужно.
10. Если были настроены обмены через дополнительные модули или серверные скрипты - отключаем их или меняем адрес сервера обмена на тестовые.
Тут уже вам виднее конечно, что у вас на портале с чем обменивалось не стандартными методами. Но лучше, конечно всё поотключать, потому что мы развернули точную копию боевого портала. И пусть к этому моменту она уже не совсем точная, но ваши скрипты обмена всё ещё обращаются к боевым системам.
11. Выполнить полную очистку кэша.
Всё сделали? Супер! Теперь можно спокойно дорабатывать, экспериментировать, ломать тестовую копию и не бояться, что об этом пользователи узнают раньше времени!
Не хотите экспериментов? Вы всегда можете обратиться к нашим специалистам службы клиентского счастья.
Покажу как сделать в 1С-Битрикс форму обратной связи, как её настроить, чтобы принимать лиды.
Будет использоваться модуль bitrix webforms.
Создание и настройка формы в административном разделе
Прежде, чем приступать, рекомендую выключить упрощенный режим редактирования форм в настройках модуля Вебформы. И сохранить настройку, соответственно.
Теперь идем в Сервисы -> Веб формы -> Настройка форм и жмем там Создать, чтобы создать форму.
Во вкладке Свойства заполняем все необходимые поля. Во вкладке "Доступ" проверьте, чтобы для группы "Все пользователи" было право "Заполнение формы".
Капчу на данном этапе включать не будем.
Жмем Применить, чтобы создать форму.
Переходим во вкладку Вопросы и добавляем их.
Настройка полей для формы:
Так же создаем статус по умолчанию для результатов, если он не создался.
Заголовок: Default. Во вкладке Доступ для всех операций поставьте "Создатель результата".
В панели администратора всё добавили и сохранили, молодцы!
Вывод формы в публичном разделе сайта
Если вы хотите разместить форму на отдельной странице, создайте страницу для формы.
А если хотите разместить в шаблоне, например в шапке, тогда создайте временную страницу, чтобы настраивать форму там. После скопируете вызов компонента формы с временной страницы. Я создам файл test.php.
Открываем редактирование страницы в визуальном редакторе, в компонентах ищем form.result.new, перетягиваем в окно правки.
Если нет поиска компонентов, то нажмите на кнопку у правой границы редактора.
Через несколько секунд появится окно настройки компонента.
Там нам надо заполнить:
После сохранения компонента, на странице появится форма. Она не очень красивая, поэтому установим свой шаблон.
Включим режим правки, наведем курсор на форму, там скопируем шаблон, как показано на картинке.
Укажем новое название шаблона, шаблон сайта - текущий.
В шаблоне компонента сразу удалим все лишние файлы. Если их не удалить, в будущем они будут создавать путаницу при доработке шаблона, потому что будем иметь полно файлов не понятного назначения. А еще сайт будет тяжелый, так как пользователь будет получать много не нужных скриптов и стилей.
Оставим только файл template.php
Приступим к редактированию шаблона.
В template.php доступны следующие переменные:
$arResult["F_RIGHT"] - код права на доступ к текущей форме (вкладка Доступ формы)
$arResult["WEB_FORM_NAME"] - символьный код формы
$arResult["arrVALUES"] - значения полей введенные пользователем
$arResult["CAPTCHACode"] - уникальный код капчи. Требуется для вывода картинки.
$arResult["arForm"]["STAT_EVENT1"] - event1 с вкладки Статистика формы
$arResult["arForm"]["STAT_EVENT2"] - event2 с вкладки Статистика формы
$arResult["arForm"]["STAT_EVENT3"] - event3 с вкладки Статистика формы
Для вывода полей надо брать вопросы из $arResult["QUESTIONS"] по символьному коду.
- CAPTION - имя поля
- IS_HTML_CAPTION - имя поля в формате HTML, Y/N.
- REQUIRED - обязательно к заполнению, Y/N.
- IS_INPUT_CAPTION_IMAGE - есть ли изображение вопроса
- HTML_CODE - HTML код поля
- STRUCTURE - детальное описание поля
- IMAGE - описание изображения вопроса, если IS_INPUT_CAPTION_IMAGE равен Y.
Например, чтобы вывести инпут поля с символьным кодом NAME надо сделать в шаблоне так:
На основе переменных выше соберем шаблон
Логика его такая:
Вначале проверяем, подключает ли файл Битрикс или его открыл пользователь введя в браузере адрес шаблона. Если не битрикс - блокируем генерацию шаблона.
- выводит открытие формы со служебными скрытыми полями.
Поле web_form_submit в значении Y - триггер для Битрикс, говорящее о том, что форма отправлена и надо бы проверить, что там ввел пользователь.
Если есть ошибки - выводим их в диве с классом errors.
Далее выводим три поля, у каждого: Имя, если обязательное - галочка, HTML код инпута для ввода.
На этом можно закончить, форма уже будет работать.
Ajax отправка
Еще не забыли про ajax? Сейчас покажу вариант, который работает даже без JQuery.
Создайте в папке шаблона компонента файл script.js с контентом:
В шаблон (наш template.php) после добавьте строку
Выше мы привязали через функцию ajaxForm() ajax к форме. В $templateFolder хранится ссылка на папку текущего шаблона, в ней мы создадим файл ajax.php. Путь файла, например, может получиться такой: /bitrix/templates/books/components/bitrix/form.result.new/request_form/ajax.php.
Последний штрих - создать файл обработчик ajax запросов.
Создайте в папке шаблона компонента файл ajax.php с контентом:
В этом файле мы принимаем запрос от пользователя, если есть ошибки, выводим их в JSON, если всё успешно, так же через JSON говорим об успешности.
Аналогично компоненту веб формы, запускаем обработчики событий.
В этом варианте нет минусов, как в варианте с битриксовым аякс, потому что битрикс подменяет каждый раз HTML в нашей форме, а в текущем варианте DOM страницы не трогается.
Ajax. Битриксовый вариант.
Чтобы форма отправлялась без перезагрузки страницы, надо добавить в параметры вызова компонента следующее:
"AJAX_MODE" => "Y",
"AJAX_OPTION_SHADOW" => "N",
"AJAX_OPTION_JUMP" => "N",
"AJAX_OPTION_STYLE" => "Y",
"AJAX_OPTION_HISTORY" => "N",
Кстати, с помощью этих параметров добавить AJAX можно в любой компонент. Эти параметры - не особенность вебформ, реализована работа с ajax в базовом классе компонентов.
Теперь Битрикс сам добавит нужные скрипты.
Алгоритм работы Ajax формы:
Из этой логики мы получаем некоторые нюансы. Поля формы, обработанные на джаваскрипте при загрузке страницы, снова будут не обработанные, так как они заменились, а события загрузки страницы заново не было.
Особенность 1
Если в форме в поле телефона на JS ставится маска, например $('.my_phone_input').mask('9 (999) 999 9999'), то маска пропадет после замены битриксом формы. Поэтому маску придется накладывать в файле template.php, чтобы она накладывалась каждый раз заново.
Особенность 2
Если мы форму используем в попапе, а при открытии окна верстка копируется в отдельный блок (так работает fancybox) ajax режим работать не будет.
Представим ситуацию: верстку всего попапа мы убрали в шаблон формы. Имеем структуру на странице, как показано ниже.
Настройка капчи
Чтобы в форме появилась капча:
Добавьте в шаблон формы следующий код:
В настройках формы включите показ капчи.
На этом капча уже будет работать.
Обновление капчи пользователем.
Теперь, если пользователь не может прочитать код, он может обновить картинку.
Настройка формата изображения капчи
Вид капчи можно настроить в панели администратора в разделе Настройки > Настройки продукта > CAPTCHA.
Своя верстка полей ввода в форме
До этого момента поля в форму мы вставляли HTML_CODE вопроса, в котором уже содержится код инпута. Давайте и его сами генерировать, ведь бывает и такая необходимость.
Функцию генерации поля ввода объявим как анонимную, чтобы можно было копировать шаблон компонента и не было ошибок на странице, что одна функция объявлена 2 раза.
Читайте также: