dartTelegram

dartTelegram – компонент для отправки сообщений в Telegram. Данный компонент имеет многоуровневую систему уведомлений. То есть можно настроить сообщения так, чтобы, например, критические ошибки или уведомления падали разработчику, заявки менеджеру и так далее. По умолчанию, в компоненте есть следующие уровни уведомлений:

• FATAL — Фатальные ошибки
• ERROR — Ошибки
• WARN — Предупреждения
• INFO — Информационные
• DEBUG — Отладка

Для каждого уровня уведомлений можно задать своего бота и свой набор чатов для отправки сообщений. Уровень уведомления содержит следующие поля:

• ID — Идентификатор
• name- Наименование
• chats — Список чатов через запятую
• token — Токен чат бота
• description — Описание
• active — Активность

В комплекте с компонентом идет плагин dartTelegram, который срабатывает на событие msOnCreateOrder и отправляет данные по заказу в чат, указанный в уровне уведомлений из системноу настройки darttelegram_order_level. Если вам необходимо задействовать дополнительные события, то, во избежание перезаписи кода при обновлении, необходимо создать дополнительный плагин использовав дефолтный, как основу для кода.

Пример сообщения о новом заказе:

Также компонент содержит сниппет dartTelegramHook, который мы можем использовать в вызовах formIt и ajaxForm. Сниппет лучше вызывать до хука email, тогда, если email не отправит письмо, то сообщение в Telegram с вероятностью 99% будет доставлено. Сниппет получает следующие параметры:

• dtLevel — уровень уведомлений (по умолчанию, INFO)
• dtFields — поля для сообщения, если не указано, то в сообщении придет массив POST
• formName — наименование формы

Пример вызова на fenom:

{$_modx->runSnippet("!AjaxForm", [
        	'snippet' => 'FormIt',
        	'form' => '@FILE chunks/form_callback.tpl',
        	'hooks' => 'nospam,FormItSaveForm,dartTelegramHook,email',
        	'emailTpl' => '@FILE chunks/email_email.tpl',
        	'emailSubject' => 'Заказ звонка',
        	'emailTo' => $_modx->getPlaceholder("+conf_to_email"),
        	'emailFrom' => $_modx->config.emailsender,
        	'formName' => 'Заказ звонка',
        	'validate' => 'page:required,name:required,phone:required,username:blank',
        	'dtLevel' => 'FATAL',
        	'dtFields' => [
        		'name' => 'Имя',
        		'phone' => 'Телефон',
        		'text' => 'Комментарий',
        	]
        ])}

Обратите внимание на корректный порядок вызова хуков:

1. Проверка на спам хуком nospam
2. Сохранение формы в панели администратора хуком FormItSaveForm
3. Отправка сообщение в телеграм хуком dartTelegramHook
4. Отправка на почту хуком email

Даже, если сбойнет и телеграм и почта, то форма точно сохранится в панели администратора и лид не пропадет.

Пример сообщения об успешно заполненной форме:

• darttelegram_api_url — URL для запросов к Telegram API
• darttelegram_bot_token — токен бота, который получили у @BotFather
• darttelegram_log — включение/отключение лога запросов
• darttelegram_order_chunk — чанк сообщения о новом заказе. Лучше оставить дефолтный чанк (tpl.dartTelegram.order), как эталонный вариант. Обратите внимание, что символом переноса строки является «FF»
• darttelegram_order_level — уровень уведомлений о заказе (убедитесь, что он создан и активен)
• darttelegram_parse_mode — режим парсинга сообщений (доступны «HTML», «MarkdownV2» и «Markdown»)

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

Для начала находим контакт @BotFather. Обратите внимание, у него справа от имени есть подтверждающая галочка.

Потом нажимаем Start и пишем контакту @BotFather сообщение "/newbot":

Далее нужно будет написать имя бота:

Далее пишем username бота, который обязательно должен заканчиваться на “_bot”:

По итогу нам @BotFather выдаст ключ для API запросов, который мы сможем использовать в нашем компоненте. Пишем сначала нашему боту (можно кликнуть по ссылке в сообщении с API ключом и нажать кнопку “Запустить”) что-нибудь, например, “прием”:

Бот у нас молчаливый, но наша задача стоит в том, чтобы заставить его говорить. Теперь переходим в панель администратора, открываем системные настройки и указываем API ключ нашего бота в настройке darttelegram_bot_token:

Далее идем в Пакеты->dartTelegram и кликаем на кнопку “Проверка обновлений бота”:

Как к нам придет ответ, там будет ID чата, который мы сможем указать для уровня уведомлений. Также можно добавить бота в групповой чат и также после добавления что-то в него написать. Обратите внимание: ID групповых чатов начинается с символа “-”.

Если вдруг, результат пришел пустой, напишите в чат еще что-нибудь и снова нажмите кнопку “Проверить”. Далее, заполнив в нужный уровень уведомлений список чатов мы можем протестировать работу нашего бота с помощью компонента modalConsole, выполнив следующий код (обратите внимание на уровень уведомлений):

<?php
        if(is_dir($modx->getOption('core_path').'components/darttelegram/model/')) {
        	$corePath = $modx->getOption('darttelegram_core_path', array(), $modx->getOption('core_path') . 'components/darttelegram/');
        	$darttelegram = $modx->getService('dartTelegram', 'dartTelegram', $corePath . 'model/', array());
        }
        
        if($darttelegram){
           	$result = $darttelegram->sendMessage("INFO", "Приветики!");
        	print_r($result);
        }

Если все прошло успешно, то увидим вот это: