Модуль для интеграции с Telegram
Обсуждение: http://majordomo.smartliving.ru/forum/viewtopic.php?f=5&t=2768
На данный момент умеет
- Регистрировать пользователей
- Отправлять сообщения системы (определенного уровня важности)
- Принимать команды
- Создает в приложении Telegram клавиатуру с шаблонами команд
- Прием файлов
- Проигрывание голосовых сообщений
- Обработчики событий
- Сортировка команд
- webhook
Регистрация бота
Для работы модуля необходимо зарегистрировать бота и получить его уникальный id, являющийся одновременно и токеном. Для этого в Telegram существует специальный бот — @BotFather.
Пишем ему /start и получаем список всех его команд. Первая и главная — /newbot — отправляем ему и бот просит придумать имя нашему новому боту. Единственное ограничение на имя — в конце оно должно оканчиваться на «bot». В случае успеха BotFather возвращает токен бота и ссылку для быстрого добавления бота в контакты, иначе придется поломать голову над именем.
В настройки модуля вносится токен бота вида "123456780:AAHeВ7UcDWvEovvcFaMfUrUVPupNORHWD_k"
Регистрация и настройка пользователя
Регистрация При первом добавлении бота в список контактов, для регистрации нужно нажать в клиенте кнопку "Начать". Либо отправить команду /start. От бота должно прийти в ответ "Вы зарегистрированы! Обратитесь к администратору для получения доступа к функциям."
Настройка
Для правильной работы модуля для каждого пользователя необходима привязка к пользователю системы. Данная настройка влияет на то, как будут отображаться в системном чате отправленные пользователем сообщения, и какие сообщения из чата будут отправляться пользователю. Остальные параметры настраиваются в соответствии с тем, какие функции разрешаются данному пользователю.
Команды
Команды используются для построения клавиатуры в клиенте, содержащей шаблоны сообщений. Одним нажатием кнопки из этой клавиатуры осуществляется отправка команды. У каждой команды есть настройка контроля доступа, где можно задать пользователей которым данная команда доступна. Если у команды поле код пусто, то команда передается дальше на обработку в сценарии и в processCommand. Если поле кода не пустое, то выполняется только код. Для отправки ответа на команду в конце кода должен быть return с текстовым сообщением. Текст может содержать HTML разметку.
События
Данный функционал позволяет навесить на события, такие как получение текстового сообщения, файла, стикера, местоположения и др, свой обработчик. Например, при получении аудиофайла, добавить его в плейлист и выполнить его воспроизведение. Для каждого из типов событий в выполняемый код передаются определенные параметры, такие как например $chat_id. Более подробно о параметрах расписано в подсказке, которая появляется при выборе типа события.
Webhook
Для чего? Для того, что бы исключить постоянный опрос серверов на наличие новых сообщений. Сервера Telegram сами уведомят о поступлении нового сообщения.
Как включить?
- Ваш сервер должен быть доступен из интернет, а именно страница https://ваш_сервер/webhook_telegram.php
- Доступен только по протоколу HTTPS с подписанным сертификатом
- В поле Webhook URL задается имя вашего сервера или ip
- Нажатием кнопки "Set Webhook" отправляется запрос на установку вашего адреса для webhook. Результат отобразится ниже кнопки.
Плюсы
- Быстрый ответ на команду
- Нет постоянных запросов на наличие новых сообщений
- Работает независимо от того, запущен основной цикл или нет.
Минусы
- Нужен HTTPS с подписанным сертификатом
- При подписке на webhook перестает работать запрос сообщений с сервера. Поэтому прежде чем снять галочку "Use webhook" обязательно надо отписаться от webhook. Для этого надо нажать кнопку "Clean webhook".
- При долгой обработке сообщения, сервер телеграмм будет повторно высылать вам это сообщение.
Текущий статус использования webhook можно узнать нажав кнопку "Status webhook"
Примеры использования модуля в скриптах
Для отправки текстовых сообщений
|
1 2 3 4 5 |
include_once(DIR_MODULES . 'telegram/telegram.class.php'); $telegram_module = new telegram(); $telegram_module->sendMessageToUser(139809588, "test message"); $telegram_module->sendMessageToAdmin("test message to admin"); $telegram_module->sendMessageToAll("test message to all"); |
Для отправки изображений
|
1 2 3 4 5 |
include_once(DIR_MODULES . 'telegram/telegram.class.php'); $telegram_module = new telegram(); $telegram_module->sendImageToUser(139809588, '/var/www/images/trees.jpg', 'Description'); $telegram_module->sendImageToAdmin('/var/www/images/htc_hero_wallpaper_01.jpg'); $telegram_module->sendImageToAll('/var/www/images/htc_hero_wallpaper_01.jpg'); |
К изображению можно добавить текстовое описание
Для отправки файлов
|
1 2 3 4 5 |
include_once(DIR_MODULES . 'telegram/telegram.class.php'); $telegram_module = new telegram(); $telegram_module->sendFileToUser(139809588, '/var/www/file.txt'); $telegram_module->sendFileToAdmin('/var/www/file.txt'); $telegram_module->sendFileToAll('/var/www/file.txt'); |
Для отправки голосового сообщения
|
1 2 3 4 5 |
include_once(DIR_MODULES . 'telegram/telegram.class.php'); $telegram_module = new telegram(); $telegram_module->sendVoiceToUser(139809588, $file_path); $telegram_module->sendVoiceToAdmin($file_path); $telegram_module->sendVoiceToAll($file_path); |
Для отправки стикеров
|
1 2 3 4 5 |
include_once(DIR_MODULES . 'telegram/telegram.class.php'); $telegram_module = new telegram(); $telegram_module->sendStickerToUser(139809588 ,"BQADAgAD2gADeVziCaKoJ-z5_rAfAg"); $telegram_module->sendStickerToAdmin("BQADAgAD2gADeVziCaKoJ-z5_rAfAg"); $telegram_module->sendStickerToAll("BQADAgAD2gADeVziCaKoJ-z5_rAfAg"); |
Для получения кода стикера (вида "BQADAgAD2gADeVziCaKoJ-z5_rAfAg") нужно отправить боту стикер и посмотреть код в "Истории событий" модуля.
Для отправки местоположения
|
1 2 3 4 5 |
include(DIR_MODULES . 'telegram/telegram.class.php'); $telegram_module = new telegram(); $telegram_module->sendLocationToUser(139809588, 58.5876084, 49.6533398); $telegram_module->sendLocationToAdmin(58.5876084, 49.6533398); $telegram_module->sendLocationToAll(58.5876084, 49.6533398); |
Для отправки места (местоположение с описанием)
|
1 2 3 4 5 |
include(DIR_MODULES . 'telegram/telegram.class.php'); $telegram_module = new telegram(); $telegram_module->sendVenueToUser(139809588, 58.5876084, 49.6533398,'Venue', 'Address'); $telegram_module->sendVenueToAdmin(58.5876084, 49.6533398, 'Venue', ''); $telegram_module->sendVenueToAll(58.5876084, 49.6533398, 'Venue', 'Address'); |
Для отправки статуса действия Применяется для отображения действия, которое выполняется на стороне бота(для долго выполняемых скриптов) Параметры функции sendAction($chat_id,$action) - $chat_id - идентификатор чата, $action - действие
- typing - печатает...
- upload_photo - загрузка фото
- record_video or upload_video - загрузка видео
- record_audio or upload_audio - загрузка аудио
- upload_document - загрузка документа
- find_location - поиск местоположения
|
1 2 3 4 5 6 7 |
include_once(DIR_MODULES . 'telegram/telegram.class.php'); $telegram_module = new telegram(); $telegram_module->sendAction($chat_id,"typing"); /// ........... /// $telegram_module->sendMessage($chat_id,$message); |
Получение имени пользователя по его chat_id (только для зарегистрированных пользователей в модуле)
|
1 2 3 |
include(DIR_MODULES . 'telegram/telegram.class.php'); $telegram_module = new telegram(); $telegram_module->getUserName(139809588); |