Перейти к основному содержимому

Что видит человек и что получает бот

Один и тот же бот «Клуб XL» (его код — во вкладке «Пример бота» на странице Подключение кода) глазами человека, который с ним переписывается, и запросы, которые бот в этот момент получил или отправил.

к сведению

Скриншоты сняты на тестовом сервере (адреса …:liza.local), имена людей скрыты. Меню «/» и кнопки без цифры «1» в чате работают в новой версии приложения Liza. В старых версиях человек отвечает на кнопку цифрой, но бот всё равно получает обычный callback_query, так что код менять не нужно.

Глазами клиента​

Человек вводит «/» — видит меню команд​

Меню берётся из setMyCommands: команда и описание. Человек выбирает пункт, и команда отправляется боту. Меню есть в личном чате с ботом.

Подсказки команд бота по «/»

Что вызвал бот — POST https://bot.tech.liza.ru/bot<ТОКЕН>/setMyCommands:

{
  "commands": [
    { "command": "start", "description": "Главное меню клуба" },
    { "command": "shop",  "description": "Каталог курсов" },
    { "command": "help",  "description": "Помощь" }
  ]
}

/start → бот отвечает меню с кнопками​

Команда приходит с entities типа bot_command, поэтому CommandHandler("start") срабатывает как в Telegram. В ответе бот показал логин человека из from.liza_user_id (на скриншоте скрыт) — тот самый, по которому позже можно написать первым. Под сообщением — две кнопки: с callback_data и со ссылкой (url).

Ответ бота на /start: текст и две кнопки

Что получил бот:

{
  "update_id": 2,
  "message": {
    "message_id": 1,
    "from": { "id": 1419716922, "is_bot": false, "first_name": "Анна",
              "username": "anna", "liza_user_id": "@anna:liza.local" },
    "chat": { "id": 1419716922, "type": "private" },
    "date": 1790946248,
    "text": "/start",
    "entities": [{ "type": "bot_command", "offset": 0, "length": 6 }]
  }
}

Нажал «Каталог курсов» → бот поменял сообщение​

Нажатие пришло как callback_query. Бот ответил editMessageText с новыми кнопками: сообщение поменялось на месте, значок ✎ показывает, что оно отредактировано. Цифры «1» в чате нет.

Сообщение бота отредактировано: каталог курсов и новые кнопки

Что получил бот:

{
  "update_id": 3,
  "callback_query": {
    "id": "1419716922_1005452822",
    "from": { "id": 1419716922, "is_bot": false, "first_name": "Анна",
              "username": "anna", "liza_user_id": "@anna:liza.local" },
    "message": { "message_id": 2, "chat": { "id": 1419716922, "type": "private" } },
    "chat_instance": "1419716922",
    "data": "catalog"
  }
}

Голосовое → бот получает voice с file_id​

Голосовое приходит в message.voice с длительностью и file_id. Скачать его можно через getFile — библиотеки делают это сами. На том же скриншоте выше бот ответил с цитатой голосового.

{
  "update_id": 4,
  "message": {
    "message_id": 3,
    "from": { "id": 1419716922, "is_bot": false, "first_name": "Анна",
              "username": "anna", "liza_user_id": "@anna:liza.local" },
    "chat": { "id": 1419716922, "type": "private" },
    "voice": { "file_id": "mxc://liza.local/EHSSyNbuKiU…", "duration": 4,
               "mime_type": "audio/ogg" }
  }
}

Нажатая кнопка отмечена галочкой​

Человек нажал «Курс «Продажи»». На кнопке появилась ✓, в чат ничего лишнего не ушло, а бот ответил новым сообщением с цитатой (reply_to_message_id).

Галочка на нажатой кнопке и ответ бота с цитатой

{
  "update_id": 5,
  "callback_query": {
    "id": "1419716922_1668151358",
    "from": { "id": 1419716922, "is_bot": false, "first_name": "Анна",
              "username": "anna", "liza_user_id": "@anna:liza.local" },
    "message": { "message_id": 2, "chat": { "id": 1419716922, "type": "private" } },
    "data": "course_sales"
  }
}

Что получает бот — по действиям​

Выберите, что делает человек в Лизе, и посмотрите, какой апдейт придёт в getUpdates или на вебхук. Пример реакции — на python-telegram-bot.

{
  "update_id": 2,
  "message": {
    "message_id": 1,
    "from": { "id": 1419716922, "is_bot": false, "first_name": "Анна",
              "username": "anna", "liza_user_id": "@anna:liza.local" },
    "chat": { "id": 1419716922, "type": "private" },
    "date": 1790946248,
    "text": "/start",
    "entities": [{ "type": "bot_command", "offset": 0, "length": 6 }]
  }
}

entities с типом bot_command — по ним библиотеки запускают CommandHandler. Работает и форма /cmd@логин_бота.

await update.message.reply_text("Добро пожаловать!", reply_markup=menu)

Сообщения​

  • Тип чата и отправитель: chat.type — private для чата бота с одним человеком, group для трёх участников и больше. from.is_bot = true, если пишет другой бот. from.liza_user_id — полный Matrix ID человека (его принимает startChat).
  • Входящие: текст, фото (photo), голосовые (voice), аудио (audio), файлы (document), видео (video) с подписью caption; ответы приходят с reply_to_message, правки пользователя — отдельным обновлением edited_message.
  • Отправка: sendMessage — до 4096 символов, parse_mode HTML или Markdown.
  • message_id стабилен и растёт в пределах чата. По нему работают editMessage*, deleteMessage, reply_to_message_id и reply_parameters. Значения, сохранённые до 1 октября 2026 года, недействительны.
  • Ответы с цитатой: если сообщения для reply_to_message_id / reply_parameters нет (неизвестное или старше 30 дней), сообщение уходит без цитаты; 400 — только при явном allow_sending_without_reply=false. При цитате ответ send* содержит reply_to_message.
  • Правка: медиа правкой не заменяется — editMessageCaption меняет только подпись. Правка без изменений — 400 message is not modified.
  • «Печатает…»: sendChatAction показывает статус на 5 секунд для любого из действий Telegram; неизвестный action — 400.
  • file_id — адрес mxc://…. По нему работает getFile, и его можно передать в sendPhoto / sendDocument / … для отправки без повторной загрузки. Для файлов, которые бот получил или отправил начиная с версии 1.3, сохраняются имя, mimetype, размер и размеры; file_id, выданные раньше, работают как прежде (без метаданных); file_id неверного формата — 400. Ответ send* содержит file_size, mime_type, file_name (у фото — width / height).

Кнопки и меню «/»​

  • Обычная клавиатура (keyboard): нажатие приходит сообщением с текстом кнопки, как в Telegram.
  • Inline-кнопки с callback_data приходят боту как callback_query, когда человек нажимает кнопку в приложении Liza (в старых версиях приложения он отвечает номером или названием кнопки — бот получает тот же callback_query). callback_query.message — сообщение бота с этой кнопкой. Кнопки с url открывают ссылку прямо в Лизе.
  • answerCallbackQuery отвечает только нажавшему: text (до 200 символов) — всплывающее уведомление, с show_alert=true — диалог, url открывается как у url-кнопки. В чат ничего не пишется. callback_query_id обязателен и принимается только выданный этому боту, один раз и не позже 15 минут после нажатия — иначе 400. Показ ответа у человека — в следующей версии приложения.
  • Кнопки к медиа показываются под ним; правка (editMessageReplyMarkup) и удаление (deleteMessage) по message_id медиа затрагивают и их.
  • Несколько ботов в чате: ответ номером кнопки (старые версии приложения) получает только тот бот, чьи кнопки показаны последними.
  • Меню «/» задаёт setMyCommands: команды появляются подсказками при вводе «/» в личном чате с ботом (в новой версии приложения), а в следующей версии — ещё и кнопкой меню у поля ввода. Команда — от 1 до 32 символов: латиница в нижнем регистре, цифры и подчёркивание, без «/» и пробелов; описание — от 1 до 256 символов; иначе 400. После setMyCommands меню у человека обновляется не сразу: API отдаёт его с кэшем до 1 минуты, а приложение перечитывает при повторном открытии чата.
  • Команды бота важнее встроенных. Если бот задал команду, совпадающую со встроенной командой приложения (например, /leave или /logout), в чате с этим ботом она уходит боту текстом, а не выполняется приложением (в новой версии приложения).