ТЗ на Telegram-бота: как описать сценарии, кнопки и интеграции — шаблон и чек-лист для заказчика

Короткий ответ: ТЗ на Telegram-бота — это не описание «бота вообще», а карта диалога: какие шаги проходит человек, какие кнопки видит на каждом, что бот делает при ошибке и куда отправляет результат. К ней добавьте роли, список сохраняемых данных, интеграции, уведомления и сценарии приёмки. Для кнопочного бота заявок хватает двух-трёх страниц и одной схемы — ниже шаблон, пример сценария и чек-лист из 20 пунктов.

Что должно быть в ТЗ на Telegram-бота?

Десять разделов: цель, роли, карта диалога, тексты и кнопки, данные, интеграции, уведомления и рассылки, админка, приёмка и список того, что не входит. Если хотя бы один пропущен, его заполнит разработчик по своему разумению — и это станет предметом спора на сдаче.

Бот отличается от сайта тем, что у него нет страниц, которые можно показать на макете. Всё поведение — это последовательность сообщений и реакций на них. Поэтому общий шаблон ТЗ на сайт здесь подходит плохо: его разделы про структуру страниц и дизайн почти пусты, а главное — логика переходов и обработка «неправильных» ответов — в нём не предусмотрено. В типовом договоре студии ТЗ идёт первым приложением, и бот принимается именно по нему, так что каждая строка ниже потом станет пунктом проверки.

Раздел	Что написать	Пример
Цель и метрика	Одна главная задача бота и как вы поймёте, что он работает	«Принимать заявки на замер; считаем заявки в неделю»
Роли	Кто пользуется ботом и что каждому разрешено	Клиент, оператор, администратор
Карта диалога	Шаги, кнопки, переходы, ветки ошибок и выхода	Схема ниже в статье
Тексты и кнопки	Готовые формулировки или кто их пишет и когда	Таблица «шаг — текст — кнопки»
Данные	Какие поля бот сохраняет, где и сколько хранит	Имя, телефон, адрес, фото; 12 месяцев
Интеграции	Куда уходят данные и что приходит обратно	Сделка в CRM, строка в таблице
Уведомления и рассылки	Кому, по какому событию, с какой частотой	Оператору — сразу; клиенту — статус
Админка	Что администратор меняет сам без программиста	Тексты, прайс, список операторов
Приёмка	Сценарии проверки и ожидаемый результат	15 тестовых прогонов по карте
Что не входит	Явный список того, чего бот не делает	Ответы на свободные вопросы, оплата

Как описать роли: клиент, оператор, администратор?

Перечислите всех, кто будет нажимать кнопки в боте, и для каждого — что он видит и что ему разрешено. У типового бота три роли: клиент оставляет заявку, оператор её получает и меняет статус, администратор правит тексты, прайс и список операторов.

• Клиент — любой, кто запустил бота. Опишите, нужна ли ему регистрация или достаточно имени и телефона, видит ли он историю своих заявок.
• Оператор — сотрудник, который принимает обращения. Определите, как бот узнаёт, что человек — оператор: по списку аккаунтов, по паролю-приглашению или по участию в рабочей группе.
• Администратор — тот, кто управляет ботом. Решите, может ли он назначать операторов сам или это делает разработчик.

Отдельно ответьте на вопрос «что будет, если оператор уволился». Если доступ выдаётся по списку аккаунтов, кто-то должен удалить человека из списка — это строка в админке, а не просьба к программисту.

Как нарисовать карту диалога?

Запишите бота как набор шагов: на каждом шаге — сообщение, варианты ответа и куда ведёт каждый вариант. Для каждого шага добавьте три обязательные ветки: человек ответил не так, нажал «назад», пропал на середине. Рисовать можно в любой программе для схем или просто нумерованным списком.

Удобный формат строки: номер шага — что бот пишет — что принимает — куда дальше — что при ошибке. Например: «Шаг 3 — Укажите телефон — кнопка “Отправить номер” или ввод цифр — шаг 4 — если меньше 10 цифр, повторить вопрос с подсказкой». Такая запись понятна и вам, и разработчику, и тестировщику, а при приёмке её можно пройти пункт за пунктом. Подробнее о том, как описывать требования через сценарии пользователя, — в статье «User story и сценарии».

Не забудьте точки входа. Человек может прийти в бота по обычной ссылке, по ссылке с меткой из рекламы или с сайта — Telegram поддерживает передачу параметра при запуске (deep linking). Если источник заявки вам важен, впишите в ТЗ, какие метки будут и куда их записывать.

Пример: сценарий заявки на замер со всеми ветками

Ниже — сценарий бота компании, которая ставит окна. Он короткий, но в нём уже есть всё, что обычно забывают: проверка ввода, выход из сценария, брошенная заявка и нерабочее время.

1. Старт. Приветствие в одну-две строки и кнопки: «Вызвать замерщика», «Узнать цену», «Задать вопрос». Если человек пришёл по ссылке с меткой — метка сохраняется.
2. Тип работ. Кнопки: «Окна», «Балкон», «Ремонт окон», «Другое». На «Другое» бот просит описать задачу текстом.
3. Адрес. Свободный ввод. Если ответ короче пяти символов — повторить вопрос с примером «ул. Ленина, 5, кв. 12».
4. Фото. Необязательно: кнопки «Прикрепить фото» и «Пропустить». Если вместо фото пришёл текст — бот предлагает снова.
5. Телефон. Кнопка «Отправить номер» (бот получает контакт, который человек сам подтвердил) или ввод вручную. Проверка: не меньше 10 цифр.
6. Удобное время. Кнопки «Сегодня», «Завтра», «Выберу с менеджером».
7. Проверка. Бот показывает собранные ответы и кнопки «Отправить» и «Исправить» (возврат к нужному шагу без потери остального).
8. Отправка. Заявка уходит в рабочую группу и в CRM, клиент получает номер заявки и срок ответа. В нерабочее время текст другой: «Перезвоним завтра с 9:00».

Обязательные ветки для любого шага:

• кнопка «Отмена» или команда /start возвращают в главное меню, черновик заявки удаляется или сохраняется — решите заранее;
• человек пропал на шаге 4 и вернулся через день — бот продолжает с того же места или начинает заново;
• человек пишет текст там, где ждут кнопку, — бот не молчит, а повторяет вопрос;
• CRM недоступна — заявка всё равно доходит в рабочую группу, а в CRM дописывается позже.

Как устроен сам путь заявки от клиента до менеджера и что бот должен спрашивать — разобрано в статье «Telegram-бот для приёма заявок»; здесь важна именно форма записи.

Как описать тексты и кнопки?

Удобнее всего — таблицей «шаг — текст сообщения — кнопки». Если текстов пока нет, напишите, кто их готовит и к какому сроку: бот без утверждённых текстов собрать можно, а сдать — нет, потому что приёмка упирается в формулировки.

Что важно знать про ограничения Telegram, чтобы ТЗ было реалистичным (по документации Bot API):

• одно сообщение — до 4096 символов, подпись к фото или файлу — до 1024. Длинный прайс придётся делить на части или давать файлом;
• кнопки бывают двух видов: под сообщением (inline) и вместо клавиатуры телефона. Кнопка запроса телефона работает только во втором виде — отметьте в ТЗ, где какие нужны;
• бот может удалить своё сообщение только в течение 48 часов после отправки — «убрать старое меню у всех» через неделю не получится;
• файлы от пользователя бот скачивает размером до 20 МБ. Если клиенты присылают видео или тяжёлые сметы, нужен другой путь — например, ссылка на загрузку.

Telegram просит поддерживать стандартные команды /start и /help, а при наличии настроек — /settings. Впишите их в ТЗ с текстами ответов. Если бот двуязычный, укажите, откуда берётся язык: в кейсе BanRadar язык интерфейса бота берётся из настроек Telegram и переключается командой — такое поведение нужно описать заранее, иначе каждый текст придётся согласовывать дважды.

Что бот хранит и где?

Перечислите каждое поле, которое бот сохраняет, где оно лежит и сколько хранится. На историю переписки в самом Telegram опираться нельзя: по описанию платформы сервер может удалить старые сообщения вскоре после обработки, поэтому всё нужное бот должен записывать в свою базу, таблицу или CRM.

Минимальный список для бота заявок: идентификатор пользователя в Telegram, имя, телефон, ответы по шагам, вложения, метка источника, дата, статус и кто из операторов взял заявку. Отдельной строкой — срок хранения и что происходит после него. Телефон и имя — персональные данные, поэтому в ТЗ должно быть место, где бот берёт согласие и даёт ссылку на политику; как это оформить, разобрано в статье «Персональные данные в Telegram-боте».

Куда	Что указать	Частый пробел
Чат или группа сотрудников	Какой чат, формат карточки заявки, кто отмечает «взял в работу»	Бот не добавлен в группу как участник, заявки не доходят
Таблица	Название листа, порядок колонок, кто владелец файла	Кто-то переименовал колонку — запись сломалась
CRM	Сущность (лид или сделка), воронка, этап, ответственный, поля	Не сказано, что делать с повторным обращением того же клиента
1С	Что читаем (остатки, статусы, счета) и что пишем, как часто	Нет доступа к базе или к веб-сервису 1С на старте
Оплата	Платёжный сервис, товары и суммы, что бот делает после оплаты	Не описан возврат и сообщение при неуспешном платеже

Как описать интеграции: CRM, 1С, таблица, оплата?

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

В тариф Telegram-бота от 16 000 ₽ входит связка с одной системой — CRM или Google Sheets — и приём оплаты через Telegram Payments или ЮKassa; нестандартные интеграции под ваш API считаются отдельно, а комиссии платёжных систем и стоимость эквайринга в цену не входят. Если боту нужно сразу несколько систем и обмен в обе стороны, это ближе к задаче интеграции (от 32 000 ₽) — честнее понять это на этапе ТЗ, чем на сдаче.

Для оплаты в ТЗ опишите: какие товары или услуги, где хранится прайс, что бот присылает после успешного платежа, что — после неуспешного, и кто делает возврат.

Уведомления, рассылки и админка: что прописать?

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

Два ограничения Telegram, которые влияют на ТЗ. Первое: бот не может начать разговор — писать можно только тем, кто сам запустил бота. Второе — скорость: по FAQ Telegram не стоит отправлять больше одного сообщения в секунду в один чат, в группу — не больше 20 в минуту, а массовая рассылка без платного режима идёт со скоростью около 30 сообщений в секунду. Рассылка по нескольким тысячам подписчиков займёт минуты, а не секунду — для акций «ровно в 12:00» это нужно учесть. Правила и автоворонки подробно — в статье «Рассылки и автоворонки в Telegram-боте».

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

Как принимать бота по ТЗ?

Возьмите карту диалога и пройдите каждую ветку руками: и правильный путь, и все ошибки. Сценарии приёмки удобно записать прямо в ТЗ — «действие — ожидаемый результат», тогда сдача превращается в проверку списка, а не в спор о вкусе.

По типовому договору студии у заказчика есть 5 рабочих дней, чтобы подписать акт или направить мотивированный отказ с перечнем замечаний; если ни того ни другого нет, работы считаются принятыми. Правок — до 2 раундов: на карте сценариев и после сборки бота. После запуска 7 дней идёт бесплатная поддержка с мелкими правками, гарантия по договору — 30 календарных дней с даты акта, дальше — абонентская поддержка от 7 900 ₽/мес. Хорошее ТЗ отделяет ошибку (бот ведёт себя не так, как записано) от доработки (вы решили, что он должен вести себя иначе).

Чек-лист ТЗ на Telegram-бота: 20 пунктов

Пройдитесь по списку перед отправкой разработчику. Если на пункт нет ответа, напишите «решим на брифе» — это честнее пустого места.

1. Одна главная цель бота и как вы её измеряете.
2. Список ролей и права каждой.
3. Как бот отличает оператора и администратора от клиента.
4. Точки входа: ссылка, метки рекламы, кнопка на сайте.
5. Карта диалога с нумерованными шагами.
6. Ветка ошибки ввода на каждом шаге.
7. Выход и возврат: «Отмена», «Назад», команда /start.
8. Поведение при брошенном сценарии и возвращении.
9. Тексты сообщений или кто и когда их пишет.
10. Тексты для /start и /help.
11. Где нужна кнопка «Отправить номер», где inline-кнопки.
12. Работа в нерабочее время и в праздники.
13. Список сохраняемых полей и срок хранения.
14. Согласие на обработку данных и ссылка на политику.
15. Каждая интеграция: что уходит, что приходит, что при сбое.
16. Кто выдаёт доступы к CRM, таблице, платёжному сервису и когда.
17. Оплата: товары, суммы, успешный и неуспешный платёж, возврат.
18. Таблица уведомлений и правила рассылок.
19. Что администратор меняет сам без разработчика.
20. Сценарии приёмки и явный список того, что не входит.

Какие пробелы в ТЗ на ботов встречаются чаще всего?

Почти всегда это не забытая функция, а забытая ситуация: что делает бот, когда человек повёл себя не по сценарию, когда сотрудник не ответил или когда внешняя система недоступна.

• Описан только «счастливый путь». Человек вводит телефон буквами, присылает голосовое вместо адреса — и бот молчит.
• Нет ответа на свободный текст. Кнопочный бот не понимает вопросов «а сколько стоит?». Нужна реакция по умолчанию: «Выберите вариант кнопкой или напишите оператору». Если нужны ответы по смыслу, это уже ИИ-ассистент — отдельный продукт с тарифом от 72 000 ₽.
• Никто не отвечает за заявку. Бот отправил её в группу, все увидели, никто не взял. Пропишите отметку «взял в работу» и напоминание, если заявку не взяли.
• Аккаунт бота оформлен на сотрудника или подрядчика. Бот создаётся в Telegram и привязан к аккаунту создателя. Запишите в ТЗ, на чей аккаунт он заводится и кому передаются доступы.
• Рассылки «всем сразу». Ожидание мгновенной доставки тысячам людей разбивается об ограничения скорости.
• Тексты «потом». Бот собран, а сдать нельзя: формулировки не утверждены.

Когда подробное ТЗ не нужно?

Если бот делает одно действие — принимает заявку из трёх-четырёх полей и отправляет её в один чат или таблицу, — отдельный документ избыточен. Достаточно ответить на вопросы брифа: дальше разработчик сам составит карту сценариев и согласует её с вами до сборки.

Именно так устроена работа над ботом под ключ: бриф, карта сценариев, сборка, тестирование и запуск на вашем аккаунте, обычно за 1–2 дня. Карта сценариев в этом случае и есть ТЗ — вы получаете её вместе с ботом и краткой инструкцией по управлению. Подробный документ стоит писать самим, если бот обслуживает несколько отделов, работает с оплатой и несколькими системами или вы выбираете подрядчика и хотите сравнить предложения на одинаковых условиях. А если в голове не бот, а экраны с каталогом и личным кабинетом внутри Telegram, сначала проверьте, не нужен ли вам Mini App: у него ТЗ ближе к веб-приложению.

Короткие ответы на частые вопросы

Можно ли заказать Telegram-бота без ТЗ?

Можно, если бот простой: одна цель, один сценарий, одна система для заявок. Тогда ТЗ заменяет бриф и карта сценариев, которую разработчик составляет и согласует с вами до сборки.

Кто пишет тексты сообщений бота?

Решите это в ТЗ заранее. Если тексты ваши, назовите срок, когда вы их пришлёте; если тексты пишет разработчик, укажите, кто их утверждает и до какого шага работ.

Сколько страниц должно быть в ТЗ на бота?

Для кнопочного бота заявок обычно хватает двух-трёх страниц и схемы сценария. Объём важен меньше, чем ответы на вопросы: что бот спрашивает, куда отправляет и что делает при ошибке.

Может ли бот сам написать клиенту, который его не запускал?

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

Что делать, если по ходу работ сценарий нужно поменять?

Мелкие правки в рамках согласованного сценария вносятся в раундах правок. Новая ветка, новая роль или ещё одна интеграция — это изменение объёма: его оценивают и оформляют отдельно.

Услуги и кейсы по теме: Telegram-боты под ключ · кейс BanRadar · цены и сроки