Создание телеграм-бота
В Albireo CMS есть php-класс для быстрого создания собственного telegram-бота. Примеры, приведенные ниже вы можете посмотреть в реальном режиме в демо-боте @MaxSiteOrg_bot.
Основные моменты
Бот создаётся стандартным способом через @BotFather. После регистрации своего бота нужен секретный ключ примерно такого вида 3243211:JsdfjhsdfuejhD-efasdkhJGHg3854. Этот ключ/токен нужно будет использовать в php-боте.
После этого, нужно войти в режим редактирования бота и указать url-адрес через который будет происходить взаимодействие.
Например это может быть адрес https://ваш-сайт/tgbot. Учитывайте, что боты работают только по протоколу https.
Создание страницы бота в Albireo CMS
Tg-бот нужно разместить в отдельном каталоге для удобства. Например это может быть каталог страниц pages/tgbot/tgbot.php:
<?php if (!defined('BASE_DIR')) exit('No direct script access allowed');
/**
title: @tgbot
slug: tgbot
method: all
type: system
layout: empty.php
parser: -
protect-pre: -
compress: -
**/
... дальше будет php-код бота ...
Поле slug задаёт адрес страницы, именно его мы указываем при редактирование через @BotFather.
Поскольку страница будет принимать разные типы http-запросов, то для неё выставляем method: all.
Код бота
Разместите в tgbot.php начальный php-код бота.
// каталог бота
define('BOT_DIR', __DIR__ . '/');
// каталог команд бота
define('COMMAND_DIR', __DIR__ . '/command/');
// создание бота
$bot = new \Telegram\Bot(' ключ бота ');
// каталог где будут храниться присылаемые файлы
// $bot->setDirForFile(BOT_DIR . 'files/');
// или запретить загрузку файлов
$bot->setDirForFile(false);
// задаём лог файл
$bot->setLogFile(BOT_DIR . 'log.txt');
// получаем запрос от telegram, но если нет, то выходим
if ($bot->requestData() === false) return;
// входящий запрос можно сохранить в лог-файл
# $bot->requestToLogFile(true);
// дальше подключаем команды
// если ни одна из команд не сработает, то будет выполнена дефолтная
$bot->addDefaultCommand(function ($text) use ($bot) {
require(COMMAND_DIR . 'default.php');
});
// подключение команд файлами
$bot->addCommandFile('/help', COMMAND_DIR . 'help.php');
$bot->addCommandFile('/start', COMMAND_DIR . 'start.php');
// отправка файлов пользователю
$bot->addCommandFile('/image', COMMAND_DIR . 'image.php');
$bot->addCommandFile('/doc', COMMAND_DIR . 'doc.php');
$bot->addCommandFile('/audio', COMMAND_DIR . 'audio.php');
// параметры команды
$bot->addCommandFile('/sum', COMMAND_DIR . 'sum.php');
// панель кнопок
$bot->addCommandFile('/button', COMMAND_DIR . 'button.php');
// inline-клавиатура с колбеками
$bot->addCommandFile('/key', COMMAND_DIR . 'key.php');
// колбеки к /key
$bot->addCallback('randomtext', function () use ($bot) {
require(COMMAND_DIR . 'callback_randomtext.php');
});
$bot->addCallback('modal', function () use ($bot) {
require(COMMAND_DIR . 'callback_modal.php');
});
$bot->addCallback('close', function () use ($bot) {
require(COMMAND_DIR . 'callback_close.php');
});
// список последних 15 записей сайта — только заголовки
$bot->addCommandFile('/list', COMMAND_DIR . 'list.php');
// взаимодействие с данными пользователя
$bot->addCommandFile('/hello', COMMAND_DIR . 'hello.php');
// запуск бота
$bot->run();
Описание работы бота
Сам бот работает через команды, к которым привязывается php-файл обработчика. Например строчка
$bot->addCommandFile('/help', COMMAND_DIR . 'help.php');
указывает, что если пользователь телеграма введёт в окне чата текст /help, то бот передаст управление файлу /command/help.php. Внутри него будет доступна переменная $text — всё содержимое сообщения и $bot как сам объект бота.
Такой алгоритм позволяет вынести все команды в отдельные php-файлы, что упрощает их поддержку.
Метод addDefaultCommand() позволяет задать команду по умолчанию — она сработает, если команда не будет найдена.
Метод addCallback() позволяет создавать команды через Callback-функции, которая используется для вывода inline-клавиатуры. В этом примере клавиатура появляется если ввести /key, а ответ будет перехвачен через команды randomtext (случайный текст), modal (пример модального окна в чате) и close (закрытие клавиатуры).
Команды пользователя
Все команды — это просто текст, который отправляет пользователь. Но принято команды сопровождать слэшем / для того, чтобы отделять их от обычного текста. Но формально нет никакой разницы на какой именно текст будет реагировать команда.
В командах пользователя автоматически удаляются начальное и конечные пробелы через trim() и приводятся к нижнему регистру. Поэтому команды /hElLo и /hello это одно и тоже.
Команда определяется по начальному слэшу /, если его нет, то команда будет равна всему тексту. Например /search параметры команда будет /search, а если текст пользователя привет, как дела, то команды будет равна всему тексту.
Если команда должна состоять из параметров, то используются символы подчеркивания. Например текст /book_1_234 предполагает команду /book и параметры 1 и 234. Команды с подчеркиваниями регистрируются через метод addCommandUnderFile() или addCommandUnder().
Все команды, которые здесь приведены — просто примеры использования.
Команда /help
За эту команду отвечает файл command/help.php (дальше все пути относительно каталога бота):
<?php if (!defined('BASE_DIR')) exit('No direct script access allowed');
$content = file_get_contents(BOT_DIR . 'text/help.txt');
$bot->sendMessage(
[
'text' => $content,
'parse_mode' => 'Markdown',
'disable_web_page_preview' => true,
]
);
# end of file
В этом файле бот отвечает через метод sendMessage(). В качестве ответа используется текст из файла text/help.txt. Например он может быть такого содержания:
*Список команд* /start - стартовое сообщение /help - эта помощь /key - inline-клавиатура /button - обычная клавиатура /image - получить изображение /doc - получить документ /audio - получить аудио /list - список последних записей сайта `/sum число число` - вычислить сумму чисел
Чтобы изменить текст команды можно просто поправить текстовый файл.
Команда /start
Команда /start похожа на /help, только используется формат HTML в ключе parse_mode.
<?php if (!defined('BASE_DIR')) exit('No direct script access allowed');
$bot->sendMessage(
[
'text' =>'Привет! <b>Это бот сайта</b>
Список доступных команд вы можете посмотреть через /help',
'parse_mode' => 'HTML',
]
);
# end of file
Команда /image
Команда /image это пример отправки пользователю файла изображения. Для этого вы можете разместить изображение в каталоге demo:
<?php if (!defined('BASE_DIR')) exit('No direct script access allowed');
$bot->send(
'sendPhoto',
[
'chat_id' => $bot->chat_id,
'photo' => curl_file_create(BOT_DIR . 'demo/example.jpg', 'image/jpeg', '')
]
);
# end of file
Команда /doc
Команда /doc это пример отправки текстового файла пользователю бота.
<?php if (!defined('BASE_DIR')) exit('No direct script access allowed');
$bot->send(
'sendDocument',
[
'chat_id' => $bot->chat_id,
'document' => curl_file_create(BOT_DIR . 'demo/example.txt', 'text/plain', '')
]
);
# end of file
Команда /audio
Команда /audio это пример отправки mp3-файла пользователю.
<?php if (!defined('BASE_DIR')) exit('No direct script access allowed');
$bot->send(
'sendAudio',
[
'chat_id' => $bot->chat_id,
'audio' => curl_file_create(BOT_DIR . 'demo/example.mp3', 'audio/mpeg', '')
]
);
# end of file
Команда /sum
Это пример команды, которая принимает несколько параметров. Например /sum 2 5 будет означать два параметра «2» и «5», числа, которые бот будет складывать. Логика работы с параметрами может менять в каждом конкретном случае. Здесь лишь примитивный демо-пример.
<?php if (!defined('BASE_DIR')) exit('No direct script access allowed');
// параметры разделяются пробелом
$param = $bot->getParamCommand($text);
if (!$param)
$text = 'Нужно указать параметры, например `/sum 2 5`';
else {
$sum = 0;
$out = '';
foreach ($param as $p) {
$p = (int) $p;
$sum = $sum + $p;
$out .= $p . ' ';
}
$out = str_replace(' ', ' + ', trim($out));
$text = $out . ' = ' . $sum;
}
$bot->sendMessage(
[
'text' => $text,
'parse_mode' => 'Markdown',
]
);
# end of file
Команда /button
Телеграм-чат позволяет выводить кнопки, которые можно привязать к произвольному тексту или командам. Это особенно актуально для пользователей смартфонов, где удобно не набирать текст команды, а просто нажать кнопку. Вот пример файла command/button.php.
<?php if (!defined('BASE_DIR')) exit('No direct script access allowed');
$bot->sendMessage(
[
'text' => 'Это кнопки',
'reply_markup' => json_encode([
'keyboard' => [
[
[
'text' => '/start',
],
[
'text' => '/help',
],
[
'text' => '/info',
],
[
'text' => '/key',
],
]
],
'one_time_keyboard' => true,
'resize_keyboard' => true,
])
]
);
# end of file
Команда /list
Это команда используется как пример взаимодействия с Albireo CMS. В данном случае выводится список последних записей.
<?php if (!defined('BASE_DIR')) exit('No direct script access allowed');
// получение последних записей сайта
$rows = getPages(limit: 15);
$files = $rows['files'];
if ($files) {
$out = '';
foreach ($files as $file) {
$link = $file['page-url'];
$title = $file['title'] ?? 'Not title';
$out .= '• [' . htmlspecialchars($title) . '](' . $link . ')' . "\n";
}
} else {
$out = 'Ошибка получения записей... ;-(';
}
$bot->sendMessage(
[
'text' => trim($out),
'disable_web_page_preview' => true,
'parse_mode' => 'Markdown',
]
);
# end of file
Команда /key
Это команда показывает более сложное взаимодействие через т.н. inline-клавиатуру. Файл command/key.php формирует вывод клавиатуры и прописывает callback-команды через ключ callback_data:
<?php if (!defined('BASE_DIR')) exit('No direct script access allowed');
$bot->sendMessage(
[
'text' => 'Это inline-клавиатура',
'reply_markup' => json_encode([
'inline_keyboard' => [
[
[
'text' => 'Афоризм',
'callback_data' => 'randomtext'
],
[
'text' => 'Всплывающее окно',
'callback_data' => 'modal'
],
[
'text' => '× Закрыть',
'callback_data' => 'close'
],
]
],
'one_time_keyboard' => true,
'resize_keyboard' => true,
])
]
);
# end of file
Файл command/callback_randomtext.php отвечает за команду randomtext: она прописана через колбек-функцию методом addCallback(). В данном примере это считывание текстового файла в массив, его случайное перемешивание и выдачу первого элемента пользователю.
<?php if (!defined('BASE_DIR')) exit('No direct script access allowed');
$randomtext = file(BOT_DIR . 'text/randomtext.txt');
shuffle($randomtext);
$bot->sendMessage(
[
'text' => $randomtext[0],
'parse_mode' => 'Markdown',
]
);
# end of file
Файл command/callback_modal.php — это пример создания всплывающего окна в телеграм.
<?php if (!defined('BASE_DIR')) exit('No direct script access allowed');
$id = $bot->data['id'];
$bot->send(
'answerCallbackQuery',
[
'callback_query_id' => $id,
'text' => 'Это всплывающее окно',
]
);
# end of file
Файл command/callback_close.php показывает как можно закрыть (удалить сообщение) inline-клавиатуру.
<?php if (!defined('BASE_DIR')) exit('No direct script access allowed');
$id = $bot->data['message']['message_id'];
$bot->send(
'deleteMessage',
[
'message_id' => $id,
'chat_id' => $bot->chat_id,
]
);
# end of file
Команда /hello
Это пример получения данных от пользователя чата. Здесь важно понимать, что данные от пользователя не гарантированы, поэтому нужна проверка на их существование. Скажем пользователь может не заполнить в профиле все поля.
<?php if (!defined('BASE_DIR')) exit('No direct script access allowed');
$bot->sendMessage(
[
'text' => 'Привет, '
. ($bot->data['message']['chat']['first_name'] ?? '') . ' '
. ($bot->data['message']['chat']['last_name'] ?? '') . '!'
]
);
# end of file
Under-команды
Такие команды строятся как команда и параметры в разделителем подчеркивание. Например текст /book_1_234 предполагает команду /book и параметры 1 и 234.
Команды с подчеркиваниями регистрируются через метод addCommandUnderFile() или addCommandUnder().
$bot->addCommandUnderFile('/book', COMMAND_DIR . 'book.php');
Файл command/book.php принимает всю команду целиком в виде переменной $text, которую он обрабатывает самостоятельно, например так:
// демо-пример
$a = explode(' ', trim($text));
$a = $a ? trim($a[0]) : $text;
$a = explode('_', $a);
// в $a теперь - параметры команды
...
С помощью addCommandUnder() можно зарегистрировать under-команду как функцию:
$bot->addCommandUnder(function ($text) use ($bot) {
... код команды ...
});
Способы отправки ответа
Наиболее общий способ это метод send(), где можно указать telegram-метод его API.
function send($method, $response)
Метод sendMessage() отправляет ответ методом sendMessage (см. API Telegram). Здесь автоматически добавляется поле chat_id.
function sendMessage(array $param)
Метод sendMessageText() используется для удобной отправки текста. Здесь автоматически добавляется поле chat_id.
# $parse_mode: Markdown or HTML # $disable_web_page_preview: отключает предварительный просмотр web-адресов function sendMessageText(string $text, $parse_mode = '', $disable_web_page_preview = true)
Для формирования клавиатуры чата используется sendKeyboard(), который принимает массив кнопок.
function sendKeyboard(array $buttons, string $text, $one_time_keyboard = false, $remove_keyboard = false, $parse_mode = '', $disable_web_page_preview = true, $resize_keyboard = true) {}
# $buttons = [
# ['text' => '/button1'],
# ['text' => '/button2'],
# ];
#
# $bot->sendKeyboard($buttons, 'Кнопки');
Логирование запросов пользователя
Через метод requestToLogFile() можно сохранять входящие «сырые» данные от пользователя. Это бывает полезно при отладке самого бота. На рабочем сайте такое логирование нужно отключить, поскольку он может хранить персональные данные пользователя.
$bot->requestToLogFile(true);
Параметр метода true сохраняет в лог-файл последовательно все данные, а если установить false, то будет сохранен только последний запрос пользователя.
Для добавления своих данных в лог-файл используется метод addToLogFile(). Данные могут быть произвольными, поскольку обрабатываются через print_r().
bot->addToLogFile($data, $append = true)
При отладке может пригодится метод getData(), который возвращает массив текущих данных.
Получение файлов от пользователя
Пользователь может отправить боту свои файлы. Чтобы включить возможность приёма файлов следует указать путь для сохранения файлов, например так:
$bot->setDirForFile(BOT_DIR . 'files/'); # $bot->setDirForFile(false); // запретить загрузку
Важно понимать, что загруженные файлы не проходят никакой проверки, поэтому в целях безопасности эту возможность лучше отключить.
Отладка бота
Телеграм-бот не имеет гарантированной доставки, поэтому если на стороне сайта возникнет какая-то ошибка, то пользователь об этом не узнает: бот просто перестанет отвечать.
Поэтому при отладке бота, ориентируйтесь на error-log-файл сервера, где можно прочитать о возникшей ошибке.
Интеграция с другими библиотеками
Telegram-бот Albireo CMS предлагает достаточно простую реализацию и не охватывает все возможности API ботов. С другой стороны, его функционала достаточно для решения многих задач.
Если при этом необходима интеграция с другими библиотеками, например с нейросетями, то это делается через создание новых команд бота. Например можно включить ответ нейросети по умолчанию (через команду default).