Очень полезная возможность, которая упрощает взаимодействие пользователя с ботом. Рассмотрим этот объект пользовательской клавиатуры с опциями ответа, какие типы нам доступны на текущую версию API.
Еще раз про кнопки и клавиатуру
id — уникальный идентификатор пользователя в Telegram
last_name — значение поля фамилия, может быть пустым
first_name — значение поля имя, может быть пустым
username — уникальное значение текстовый идентификатор, может быть пустым
language_code — кодовое обозначение выбранного языка интерфейса приложения (en, ru . )
is_bot — флаг, определяющий пользователя как бота, в случае с ботом равен 1, в случае с пользователем пустое значение
Полезный инструмент
У каждого бота есть ссылка, которая открывает диалог с ним в Telegram — https://telegram.me/ИМЯ_БОТА . К этой ссылке можно добавить параметры start или startgroup со значениями. Значение может быть длиной от 1 до 64 символов и состоять из букв латинского алфавита (больших — A-Z и маленьких — a-z), цифр — 0-9, нижнего подчеркивания _ и тире -.
Menu Builder [RU] — 013 — Команды для Кнопок — [Создать Бот Телеграм]
https://telegram.me/ИМЯ_БОТА?start=ВАШЕ_ЗНАЧЕНИЕ
Telegram Bot API рекомендует использовать base64url для кодирования параметров с двоичным и другими типами контента.
По ссылке с параметром start будет открыт диалог с ботом, с кнопкой Старт в месте поля ввода. Если используется параметр startgroup, пользователю будет предложено выбрать группу для добавления бота.
Как только пользователь подтвердит действие (нажмет кнопку Пуск в своем приложении или выберет группу для добавления бота), ваш бот получит сообщение от этого пользователя в таком формате:
/start ВАШЕ_ЗНАЧЕНИЕ
/invoice Выписать счет
Клавиатуры и их возможности
Для управления ботом вы как создатель бота предполагаете какой-то сценарий. Пользователю чтобы получить от бота желаемый результат нужно отправить команду. Бот, когда получит команду обработает ее и отреагирует по установленному вами сценарию. Но представьте, что пользователь написал команду с ошибкой, бот в этом случае должен предупредить что команда не распознана и попросить попробовать еще раз. Это не совсем удобно пользователю, и он может пойти искать другого бота с аналогичными возможностями. Вы можете потерять потенциального клиента, это не совсем хорошо.
В этом случае нам помогут клавиатуры. Ее нужно просто после старта диалога с ботом вывести на экран пользователю, и когда тот нажмет на нужную ему кнопку, боту отправиться заложенная вами правильная команда. В этом случае уходим от возможных ошибок, интерфейс бота выглядит более приветливо и профессионально. Качество бота повышается.
С каждым сообщением бот может отправлять разный набор кнопок как по количеству, так и по назначению. Кнопки можно расположить непосредственно под сообщением (InlineKeyboardButton), или зафиксировать под тестовым полем для ввода сообщения (KeyboardButton). Различия в них очень существенные на мой взгляд. Давайте рассмотрим некоторые их возможности.
KeyboardButton
Этот объект представляет одну кнопку клавиатуры, располагающуюся под текстовым полем для отправки сообщения. Поставляется она в интерфейс приложения в наборе с другими аналогичными кнопками через объект ReplyKeyboardMarkup. В качестве параметров с ним можно передать:
text — текст который будет на отображен на кнопке, обязательный параметр, поддерживает текст и смайлики (эмодзи)
request_contact — если параметр установлен в true, пользователь отправит в бот свой номер телефона на который зарегистрирован аккаунт
request_location — если параметр установлен в true, пользователь отправит в бот свое текущее местоположение
Помимо набора кнопок в объект ReplyKeyboardMarkup можно передать еще ряд параметров:
keyboard — массив кнопок (объекты KeyboardButton)
resize_keyboard — если предать true, то клавиатура подгонится по высоте до возможного минимума.
one_time_keyboard — возможность скрывать клавиатуру после ее использования
selective — если надо показать клавиатуру только определенным пользователям
При необходимости удалить клавиатуру используйте объект ReplyKeyboardRemove.
InlineKeyboardButton
Это объект одной кнопки встроенной клавиатуры. Располагается набор таких кнопок сразу под сообщением. С помощью этого объекта можно передать кнопке url , или использовать его для голосования как одним из вариантов. В любом случае можно сделать много интересного и полезного. Рассмотрим его возможности на практике чуть ниже. Передается в наборе с другими аналогичными кнопками через объект InlineKeyboardMarkup. Принимает параметры:
text — текст который будет на отображен на кнопке, обязательный параметр, поддерживает текст и смайлики (эмодзи)
url — адрес на который будет направлен пользователь
callback_data — строка 1-64 символа будет передан боту через объект CallbackQuery
switch_inline_query_current_chat — после нажатия вставит команду для использования бота во встроенном режиме в текущем чате
callback_game — описание игры, которая будет запущена при нажатии пользователем кнопки.
pay — кнопка будет использована как кнопка оплаты
Теперь немного практики
Предлагаю рассмотреть поближе возможности клавиатур. Для примера я сделаю 4 кнопки: 2 KeyboardButton и 2 InlineKeyboardButton. Для этого будем работать с теми же инструментами, которые были в предыдущей статье. Добавим только несколько новых методов.
Логика скрипта будет простая, при старте бот будет выводить сообщение о готовности и 2 кнопки Голосовать и Помощь. При нажатии на кнопку Помощь — выведется сообщение с небольшой инструкцией, а при нажатии на кнопку Голосовать на экране появиться сообщение и под ним 2 кнопки, при нажатии на которые произойдет увеличения счетчика.
Чтобы обрабатывать команды от всех типов кнопок нам надо составить условия проверки. В моем примере от кнопки KeyboardButton команда приходит в виде обычного текстового сообщения вместе с объектом Message под ключом text, а от кнопки InlineKeyboardButton в объекте CallbackQuery под ключом data.
elseif (array_key_exists(‘callback_query’, $arrData)) < $chat_id = $arrData[‘callback_query’][‘message’][‘chat’][‘id’]; $message = $arrData[‘callback_query’][‘data’]; >?>
Кнопки будем отправлять в параметре reply_markup в методе sendMessage. Набор кнопок идет в таком формате:
Массив данных ( ‘Тип клавиатуры’ => Массив строк кнопок ( Массив кнопок строки ( Массив параметров кнопки ( ) ) ), // если предусмотрено ‘Дополнительный параметр’, )
Создадим два метода для разных клавиатур, на входе принимают массив строк кнопок, на выходе строку в формате JSON.
$data, ); return json_encode($inlineKeyboard); > private function getKeyBoard($data) < $keyboard = array( «keyboard» =>$data, «one_time_keyboard» => false, «resize_keyboard» => true ); return json_encode($keyboard); > ?>
Сам набор кнопок будет выглядеть вот так.
getKeyBoard([[[«text» => «Голосовать»], [«text» => «Помощь»]]]); $inlineKeyboard = $this->getInlineKeyBoard([[ [‘text’ => hex2bin(‘F09F918D’) . ‘ 0’, ‘callback_data’ => ‘vote_1_0_0’], [‘text’ => hex2bin(‘F09F918E’) . ‘ 0’, ‘callback_data’ => ‘vote_0_0_0’] ]]); ?>
Во встроенных кнопках (inlineKeyboardButton) в качестве значения параметра callback_data будем передавать служебную информацию в виде action_type_count1_count2 , где
action — действие, в нашем случае это vote
type — тип кнопки: 1 — левая, 0 — правая
count1 — текущее значение левой кнопки
count2 — текущее состояние правой кнопки
В значении параметра text передаем бинарный код эмодзи в кодировке UTF-8 (список эмодзи), которые преобразуются из шестнадцатеричных данных в двоичные данные функцией hex2bin, и еще выведем текущее числовое значение счетчика кнопки.
Теперь нам остается только описать механизм определения команды и механизм ее обработки. Поэтому в методе init() создадим конструкцию оператора switch
«Приветствую, давайте начнем нашу практику. Нажмите на кнопку Голосовать.», ‘chat_id’ => $chat_id, // отправляем клавиатуру ‘reply_markup’ => $justKeyboard, ); $this->requestToTelegram($dataSend, «sendMessage»); break; // если пришла команда Голосовать case ‘Голосовать’: $dataSend = array( ‘text’ => «Выберите один из вариантов», ‘chat_id’ => $chat_id, // отправляем встроенную клавиатуру ‘reply_markup’ => $inlineKeyboard, ); $this->requestToTelegram($dataSend, «sendMessage»); break; // если запросили Помощь case ‘Помощь’: $dataSend = array( ‘text’ => «Просто нажмите на кнопку Голосовать.», ‘chat_id’ => $chat_id, ); $this->requestToTelegram($dataSend, «sendMessage»); break; // если вызвана встроенная кнопка case (preg_match(‘/^vote/’, $message) ? true : false): // получаем новую клавиатуру $params = $this->setParams($message); $dataSend = array( ‘reply_markup’ => $params[0], ‘message_id’ => $arrData[‘callback_query’][‘message’][‘message_id’], ‘chat_id’ => $chat_id, ); // изменяем клавиатуру под выбранным сообщением $this->changeVote($dataSend, $params[1], $arrData[‘callback_query’][‘id’]); break; // незапланированное действие обрабатываем как поумолчанию default: $dataSend = array( ‘text’ => «Не запланированная реакция, может просто нажмете на кнопку Голосовать.», ‘chat_id’ => $chat_id, ); $this->requestToTelegram($dataSend, «sendMessage»); break; > ?>
Давайте разберемся, что в этом коде происходит. Оператор switch принимает значение $message , которое может быть, как просто текст сообщения (в том числе команды), так и значение объекта callbackQuery .
При получении команды /start — мы выводим приветственное слово и набор кнопок: Голосовать, Помощь.
При получении команды Помощь, выводим простое текстовое сообщение.
При получении команды Голосовать, выводим текстовое сообщение и набор встроенных кнопок с параметром callback_data .
При получении не запланированного значения, выводим текстовое сообщение.
И самое интересное это когда принимаем значение в начале которого стоит action , в нашем случае это vote . Мы формируем новую клавиатуру изменяем в ней текстовое значение, увеличиваем счетчик у нажатой кнопки и подставляем новую служебную информацию в параметрах callback_data .
Для создания новой клавиатуры мы используем метод setParams() , а для отправки изменений мы используем метод changeVote(). Здесь остановим внимание на методах Bot API
editMessageReplyMarkup — меняем клавиатуру у заданного сообщения
answerCallbackQuery — позволяет выводить уведомление о проделанной работе CallbackQuery, мы его используем, уведомляя пользователя что он удачно проголосовал.
requestToTelegram($data, «editMessageReplyMarkup») ? «Вы проголосовали » . hex2bin($emoji) : «Непредвиденная ошибка, попробуйте позже.»; // отправляем уведомление при любом результате $this->requestToTelegram([ ‘callback_query_id’ => $callback_query_id, ‘text’ => $text, ‘cache_time’ => 3, ], «answerCallbackQuery»); > private function setParams($data) < // разбиваем в массив по знаку _ $params = explode(«_», $data); // увеличиваем значение или левой или правой кнопки $params[1] ? $params[2]++ : $params[3]++; // готови клавиатуру с новыми значениями callback_data $arr[] = $this->getInlineKeyBoard([[ [ ‘text’ => hex2bin(‘F09F918D’) . ‘ ‘ . $params[2], ‘callback_data’ => ‘vote_1_’ . $params[2] . ‘_’ . $params[3] ], [ ‘text’ => hex2bin(‘F09F918E’) . ‘ ‘ . $params[3], ‘callback_data’ => ‘vote_0_’ . $params[2] . ‘_’ . $params[3] ] ]]); // готовим эмодзи для уведомления $arr[] = $params[1] ? ‘F09F918D’ : ‘F09F918E’; return $arr; > ?>
Подводим итоги
Простой инфо-бот с многоуровневым меню на InlineKeyboardButton
Привожу простой пример инфо-бота с практически неограниченной вложенностью. Вывод на экран текстового и медиа (картинка, видео, аудио, документ) сообщения. Многоуровневое меню включено.
Хотел привести пример как отобразить в Телеграм многоуровневое меню, но получился простой в создании информационный бот с вложенностью, ограниченной только возможной длинной значения в параметре callback_data inline-кнопки (1-64 bytes). Еще интересный момент это — в одном боте можно создать неограниченное количество сценариев, для этого достаточно просто стартовать бота по html-ссылке со специальными параметрами. При обычном старте бота — запускается первый сценарий. Об этом чуть ниже.
Настройки
В настройках бота нужно указать токен бота, id админа бота и заполнить массив с информацией о «шагах».
steps |__ |__ |__ |__ |__ |__ |__ |__ |__
Каждый шаг имеет простой набор параметров:
[ «name» => «», // string «line» => 0, // int «type» => «text|photo|video|audio|document», // string «text» => «», // string «media» => «» // string | null, «steps» => [] // array ]
name* — Название шага, будет отображено на кнопке
line* — уровень ряда в наборе кнопок
type*- тип сообщения (text|photo|video|audio|document)
text — текстовое сообщение, обязательно для type=»text»
media — ссылка или file_id медиа файла, при type=»text» должно быть значение null
steps — это массив вложенных шагов,
Для ускорения отрисовки экранов желательно в параметре media указывать file_id файла, он для каждого бота уникальный, поэтому из моего примера медиа у вас не будут подгружаться — их надо будет заменить.
Чтобы вам получить file_id я добавил небольшой функционал (только если указана настройка bot_admin), нужно просто отправить в бот файл: документ, картинку, видео или аудио файлы.
В ответ бот пришлет строку — она же и будет file_id , просто скопируйте ее и подставьте в параметр media в нужном шаге (массива $steps).
Что из интересного?
Весь контент бота упакован в массив steps он же $content . Важным моментом является конечно же валидность массива.
При старте бота настроен выбор сценария под индексом 0 массива (можно указать любой).
/** 1 параметр это индекс элемента массива 2 параметр это индексы родительских элементов массива steps, разделены тире (-), если null то выводим из верхнего уровня вложенности 3 параметр это id чата пользователя */ $printUpdate(0, null, $chat_id);
Если старт по HTML-ссылке то сценарий будет выбран из параметров ссылки
tg://resolve?domain=iMakeBot // в раскрытом виде $content = [ ‘steps’ => [ [ ‘name’ => ‘Название элемента 0’, // . ‘steps’ => [ [ ‘name’ => ‘Название элемента 0-0’ // . ], [ ‘name’ => ‘Название элемента 0-1’, // . ‘steps’ => [ [ ‘name’ => ‘Название элемента 0-1-0’ // . ], [ ‘name’ => ‘Название элемента 0-1-1’ // . ], [ ‘name’ => ‘Название элемента 0-1-2’ // . ], [ ‘name’ => ‘Название элемента 0-1-3’ // . Вот этот элемент будет отработан для вывода на экран ], ] ] ] ] ] ]
Чтобы получить из массива нужный элемент, пропускаем запрос через рекурсивную (самовызывающуюся) функцию
Отрисовка экрана
Простой роутер для бота
/** * Простой роутер бота */ if (isset($data->message)) < // получим id чата $chat_id = $data->message->from->id; // если это текстовое сообщение if (isset($data->message->text)) < // проверим что это старт бота if ($data->message->text == «/start») < // выводим сообщение $printUpdate(0, null, $chat_id); >// если это старт по ссылке elseif (preg_match(«~/start s_([d]+)_?([d-]*)~», $data->message->text, $matches)) < // выведем сообщение по ссылке $printUpdate($matches[1], $matches[2], $chat_id); >> // другие типы сообщений else < // если это админ бота направляет сообщение if ($chat_id === $bot_admin) < // по умолчанию $file_id = null; // если это картинка if (isset($data->message->photo)) < // file_id последней картикни $file_id = end($data->message->photo)->file_id; > // если это видео-файл elseif (isset($data->message->video)) < // file_id видео-файла $file_id = $data->message->video->file_id; > // если это аудио-файл elseif (isset($data->message->audio)) < // file_id аудио-файла $file_id = $data->message->audio->file_id; > // если это документ elseif (isset($data->message->document)) < // file_id документа $file_id = $data->message->document->file_id; > // проверим необходимость отправки if (!is_null($file_id)) < // отправим file_id $query(«sendMessage», [ «chat_id» =>$chat_id, «text» => $file_id ]); > > > // если это нажатие по кнопке > elseif (isset($data->callback_query)) < // получим id чата $chat_id = $data->callback_query->from->id; // получим callBackQuery_id $cbq_id = $data->callback_query->id; // получим переданное значение в кнопке $c_data = $data->callback_query->data; // спарсим значения $params = explode(«_», $c_data); // если это переход по шагам if ($params[0] == «s») < // выводим сообщение $printUpdate( $params[1], ($params[2] !== «») ? $params[2] : null, $chat_id, $cbq_id, $data->callback_query->message->message_id ); > // если это другие кнопки else < // заглушим просто запрос $notice($cbq_id, «This is notice for bot»); >>
Исходный код бота
Бот настроен под работу с Webhook
Источник: imakebots.ru
Интерактивность: создание inline-кнопок в телеграм-ботах с помощью Aiogram
В этом видеоуроке мы расскажем о том, как использовать inline-кнопки в телеграм-ботах, и научимся формировать их при помощи фреймворка Aiogram. Вы узнаете, как сделать взаимодействие с ботом более интерактивным и удобным для пользователей, а также как использовать inline-кнопки для решения различных задач. Не откладывайте, начните изучение прямо сейчас и улучшите функциональность своего телеграм-бота!
Создание ботов с Aiogram 3: отправка текстовых кнопок, запрос номера телефона, геолокации и создание викторин.
Источник: nztcoder.com