Telegram Checklists — чеклисты в Bot API от имени business account

Чеклисты в Telegram Bot API — нативные интерактивные списки задач. Подключённый business-бот может отправлять и редактировать их от имени аккаунта, а участники чата — отмечать пункты и добавлять новые, если это разрешено настройками списка.

Как устроены чеклисты в Bot API

Чеклист — отдельный тип сообщения Telegram, а не имитация списка с inline-кнопками. Для работы с ним используются объекты InputChecklist, InputChecklistTask, Checklist и ChecklistTask, а также специальные методы sendChecklist и editMessageChecklist.

Бот не отправляет такой список от собственного имени. Нужна действующая бизнес-связь (Business Connection) с аккаунтом пользователя и её идентификатор business_connection_id.

Возможности и ограничения

Один чеклист содержит от 1 до 30 задач. Заголовок после разбора форматирования должен занимать от 1 до 255 символов. Текст каждой задачи — от 1 до 100 символов. Идентификатор задачи должен быть уникальным в пределах списка и находиться в диапазоне от 1 до 100.

Поля others_can_add_tasks и others_can_mark_tasks_as_done необязательны. Если совместная работа нужна, передавайте соответствующие значения явно.

Что подготовить перед интеграцией

1. Включите для бота режим работы с аккаунтами в @BotFather. В актуальной документации он называется Secretary Mode.
2. Подключите бота к нужному аккаунту и выберите чаты, которыми он сможет управлять.
3. Обрабатывайте обновления business_connection и сохраняйте актуальный business_connection_id вместе с правами подключения.
4. Проверьте право can_reply. Оно определяет возможность отправлять и редактировать сообщения в доступных личных чатах, где были входящие сообщения за последние 24 часа.
5. Подпишитесь на business_message, edited_business_message и deleted_business_messages, если автоматизация должна учитывать переписку управляемого аккаунта.

Telegram Premium больше не является обязательным условием для подключения business-бота. Это изменилось в Bot API 10.0 от 8 мая 2026 года. Требование Premium в старых инструкциях по интеграции устарело.

Отправка чеклиста через sendChecklist

Минимальный запрос выглядит так:

{
  "business_connection_id": "BUSINESS_CONNECTION_ID",
  "chat_id": 123456789,
  "checklist": {
    "title": "Бриф на статью",
    "tasks": [
      { "id": 1, "text": "Согласовать тему" },
      { "id": 2, "text": "Подготовить план" },
      { "id": 3, "text": "Написать черновик" }
    ],
    "others_can_add_tasks": true,
    "others_can_mark_tasks_as_done": true
  }
}

Проверьте перед отправкой:

• business_connection_id относится к действующему подключению;
• chat_id передан как числовой идентификатор целевого чата;
• в tasks находится от 1 до 30 элементов;
• все id уникальны и входят в диапазон 1–100;
• заголовок и тексты задач укладываются в ограничения после разбора сущностей форматирования;
• у подключения есть нужное право, а чат входит в область доступа business-бота.

Не генерируйте идентификаторы задач случайно при каждом запросе. Стабильные значения нужны для редактирования списка, обработки событий и ответов на конкретные пункты.

Редактирование через editMessageChecklist

editMessageChecklist заменяет содержимое чеклиста в уже отправленном сообщении. Запрос включает:

• business_connection_id;
• числовой chat_id;
• message_id исходного сообщения;
• новый объект InputChecklist.

Метод позволяет изменить заголовок, состав задач и настройки совместной работы без удаления сообщения. На бэкенде полезно хранить соответствие между вашим процессом, chat_id, message_id и стабильными идентификаторами задач.

События и ответы на отдельные задачи

Пользовательские изменения чеклиста отражаются в служебных сообщениях:

• checklist_tasks_added сообщает о добавлении новых пунктов;
• checklist_tasks_done сообщает, какие задачи отметили выполненными или вернули в незавершённое состояние.

Эти сообщения можно использовать как триггеры автоматизации: обновлять состояние заявки, уведомлять ответственного или запускать следующий этап процесса. Обработчик должен быть идемпотентным, чтобы повторная доставка обновления не запускала действие второй раз.

Bot API 9.2 добавил checklist_task_id в ReplyParameters. Благодаря этому бот может отправить обычное сообщение в ответ на конкретную задачу, а не на весь чеклист. В полученном сообщении соответствующая связь доступна через reply_to_checklist_task_id.

Последующие версии расширили модель:

• Bot API 9.3 добавил в ChecklistTask поле completed_by_chat;
• Bot API 9.6 разрешил сущности date_time в заголовках чеклистов и текстах задач.

Полезные сценарии

Согласование брифа с клиентом

Бот отправляет в доступный личный чат список вопросов или этапов согласования. Если клиент должен менять статусы, для списка включают others_can_mark_tasks_as_done. Клиент отмечает подтверждённые пункты, а обработчик фиксирует изменения по checklist_tasks_done. Наблюдаемый результат — состояние брифа видно в одном сообщении без отдельного кабинета.

Сценарий подходит для короткого процесса. При большом количестве полей и версиях документов понадобится внешняя система учёта.

Контроль редакционного процесса

Каждой публикации соответствует чеклист со стабильными идентификаторами этапов. После служебного сообщения о завершении задачи интеграция обновляет связанную карточку на бэкенде. Результат проверяется по совпадению статуса задачи в Telegram и состояния записи во внешней системе.

Нужно заранее определить, какая система считается источником истины, иначе параллельные правки могут перезаписывать друг друга.

Поддержка и клиентские заявки

Для обращения создаётся список шагов решения. При разрешённом изменении статусов сотрудник или клиент отмечает выполненное, а бот отвечает на отдельные пункты через checklist_task_id. В чате остаётся понятный текущий статус заявки.

Чеклист не заменяет полноценную CRM, если требуются сроки обслуживания, сложные зависимости, аналитика и подробная история изменений.

Релизные и командные процедуры

Короткий список проверок можно разместить в доступном для бизнес-аккаунта чате и разрешить участникам менять статусы. Это удобно для повторяемых процедур, если каждый запуск получает отдельное сообщение и не превышает лимит в 30 задач. Наблюдаемый результат — участники видят актуальный статус проверок в одном сообщении.

Как проверить результат

После тестового вызова sendChecklist убедитесь, что:

1. API вернул успешный ответ с объектом Message.
2. В сообщении присутствует поле checklist с ожидаемым заголовком и задачами.
3. В интерфейсе Telegram отображается нативный список с галочками.
4. Другой участник чата может добавить или отметить задачу только при включённом соответствующем разрешении.
5. После пользовательского добавления или изменения статуса приходит соответствующее служебное сообщение с checklist_tasks_added или checklist_tasks_done.
6. Вызов editMessageChecklist меняет то же сообщение, а не создаёт новое.
7. Ответ с ReplyParameters.checklist_task_id привязывается к выбранному пункту.

Материал основан на официальной документации и не заявляет о самостоятельном тестировании описанного сценария.

Типичные ошибки

• Отправка sendChecklist без действующего business_connection_id.
• Использование старого идентификатора после изменения настроек подключения.
• Попытка передать @username вместо числового chat_id.
• Отсутствие права can_reply или попытка работать с чатом вне области доступа.
• Пустой список, больше 30 задач или повторяющиеся идентификаторы.
• Значение id вне диапазона 1–100.
• Ожидание, что другие пользователи смогут добавлять задачи или менять их статус при выключенных others_can_add_tasks и others_can_mark_tasks_as_done.
• Повторный sendChecklist там, где требуется изменить существующее сообщение через editMessageChecklist.
• Использование чеклиста как долгоживущего таск-трекера со сложными зависимостями и подробной историей.

Чеклист перед запуском

Официальные источники

• Telegram Bot API
• Bot API changelog
• Telegram Bot Features
• Connected business bots
• Анонс чеклистов Telegram

Следующий шаг

Telegram Business Bots — как боты управляют бизнес-аккаунтом в Telegram

Связанные материалы

• База знаний: Возможности Telegram-ботов — справочник по Bot Features
• База знаний: Что может Telegram-бот для бизнеса без сложной разработки
• База знаний: Telegram как рабочий интерфейс, а не просто мессенджер

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

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov