Конструктор Telegram-ботов

Конструктор собирает сценарий Telegram-бота из блоков на доске. Сценарий начинает работу после /start, команды или другого события, а дальше выполняет блоки по связям. После изменений нажмите «Опубликовать»: черновик сохраняется автоматически, но бот выполняет опубликованную версию.

Как читать доску

• Событие /start — системный вход в сценарий. Его нельзя удалить, чтобы бот всегда мог начать диалог.
• Команда — вход после /help, /subscribe, /unsubscribe и других команд. Команды работают после первого /start.
• Обычная связь default выполняет следующий блок сразу после текущего.
• Кнопки «Переход по сценарию» создают отдельный выход справа и переводят пользователя по выбранной ветке.
• URL, Web App, Copy Text и Deep link выполняются в Telegram и сами по себе не двигают сценарий дальше.
• ПКМ по свободному месту открывает меню добавления блоков; блоки можно выделять группой и переносить вместе.

Сообщение и Rich Message

Обычный блок «Текст + кнопки» подходит для короткого текста, одного или нескольких вложений и инлайн-кнопок. Это быстрый режим для меню, уведомлений и простых сообщений.

Rich Message — отдельный блок с визуальным редактором. Используйте его, когда нужны форматирование, ссылки, rich-документ, фото из медиатеки внутри сообщения и более аккуратная верстка. Не смешивайте его с обычным текстовым блоком, если сообщение должно быть визуально сложным.

• Текст поддерживает переменные вида {{vars.name}}, {{chat_id}}, {{user_id}}, {{start_payload}}.
• HTML parse mode подходит для жирного, ссылок и базового форматирования.
• MarkdownV2 выбирайте только если точно знаете правила экранирования Telegram.

Медиатека и file_id

Для фото и обычных медиа удобнее выбирать файлы из медиатеки. Так пользователь видит свои файлы в интерфейсе, а сервис сам хранит связь с ботом и Telegram file_id.

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

• Фото — можно отправлять из медиатеки или по file_id.
• Альбом — 2-10 совместимых медиа; если есть кнопки или несовместимые элементы, отправка станет последовательной.
• Стикер и кружок не поддерживают подпись в Telegram; текст отправляйте отдельным блоком.
• Для edit media используется первый файл из вложений блока.

Инлайн-кнопки

• Переход по сценарию — callback-кнопка. Она создает выход у блока и ждёт нажатия пользователя.
• Ссылка — открывает внешний URL. Цвет в интерфейсе нужен для визуального дизайна кнопки в конструкторе и предпросмотре.
• Web App — открывает Telegram Mini App по HTTPS URL.
• Copy Text — копирует заданный текст в Telegram-клиенте, если клиент поддерживает эту кнопку.
• Deep link — открывает вашего бота с payload для /start, например promo_{{user_id}}.

Переменные

Переменные подставляются перед выполнением блока. Системные значения доступны почти везде: {{chat_id}}, {{user_id}}, {{message_id}}, {{start_payload}}. Пользовательские значения хранятся в vars.

• Блок «Ввод» сохраняет ответ пользователя в переменную, например name. После этого используйте {{vars.name}}.
• Блок «Запросить контакт» сохраняет подтвержденный телефон в vars.phone, vars.contact_phone, vars.contact_verified.
• HTTP-блок может сохранить поля ответа в vars через JSON mapping.
• Оплаты пишут vars.payment_status, vars.payment_amount, vars.payment_currency, vars.payment_invoice_uid и другие payment_* поля.

Привет, {{vars.name}}!
Ваш chat_id: {{chat_id}}
Стартовый payload: {{start_payload}}

HTTP и JSON

HTTP-блок нужен для интеграции с внешними сервисами: CRM, таблицами, складом, собственной API. Укажите URL, метод, заголовки, авторизацию и body. В body можно использовать переменные сценария.

{
  "chat_id": "{{chat_id}}",
  "name": "{{vars.name}}",
  "phone": "{{vars.phone}}"
}

Если включить сохранение JSON ответа, тело ответа попадет в http_json. Через mapping можно положить нужные поля в vars и использовать дальше в условиях или сообщениях.

• Path user.name можно сохранить в vars.name.
• Path order.id можно сохранить в vars.order_id.
• После HTTP используйте ветки OK/Ошибка: например, при ошибке показать пользователю запасной текст.
• Для условий по числам используйте операторы «число больше» и «число меньше».

Оплаты и Telegram Stars

Блок «Оплата» отправляет Telegram invoice. Для Stars используйте валюту XTR и оставьте provider token пустым. Для обычных валют нужен provider token платежного провайдера.

• UID события создается автоматически и должен быть уникальным внутри сценария.
• После успешной оплаты сценарий продолжится по ветке paid.
• Ошибки, отмены и возвраты идут по веткам failed, canceled, refunded.
• Журнал оплат доступен кнопкой «Оплаты» в верхней панели конструктора.
• В payload можно добавлять переменные, например order_{{user_id}}.

Редактирование и действия Telegram

• «Изменить сообщение» может менять текст, подпись, кнопки или медиа текущего сообщения.
• «Удалить сообщение» обычно ставят после нажатия кнопки, чтобы убрать старое меню.
• «Ответ на кнопку» показывает toast или alert после callback-кнопки.
• «Закрепить» и «Открепить» требуют прав бота в чате.
• «Чеклист» работает только через Telegram Business connection и требует business_connection_id.

История версий

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

Практический шаблон сценария

• /start → согласие на обработку данных → согласие на рассылки.
• После согласий → «Ввод» имени и «Запросить контакт».
• После контакта → HTTP-запрос в CRM и условие по результату.
• Если OK → Rich Message с персональным текстом и кнопками.
• Если нужна оплата → блок «Оплата» и ветка paid с выдачей файла, ссылки или сообщения.
• В конце → блок «Конец», если диалог больше не должен ждать ответа.