Воркшоп · wearecrm.ru

Вайбкодим программу лояльности

Всё, что понадобится, — на этой странице. Она ваша и после конференции.

За полтора часа у вас будет свой бот в Telegram. Внутри — карта гостя с баллами и уровнями, а бот сам пишет человеку, когда баллы меняются. Код мини-аппа пишете не вы, а модель: ваше дело — правильно её попросить.

Опубликовать мини-апп

Отдайте файл — получите адрес, который вставляется в BotFather. Публикуя под тем же именем, вы обновляете свой мини-апп, и адрес не меняется. Сюда вы вернётесь ещё пару раз за воркшоп.

Опубликовали заново, а в телефоне старое — это кэш Telegram, а не ошибка. Закройте мини-апп и откройте заново или допишите ?v=2 в конец адреса в BotFather.

VPN

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

Проверьте, что получилось: откройте чат с моделью и отправьте любое сообщение.

Шаги

0 из 13

Подключитесь к инструменту Раздел «Подключение» выше. Задача — открывающийся чат с моделью. Уже есть — пропускайте
Создайте бота В Telegram откройте @BotFather → /newbot → имя → адрес, заканчивающийся на bot
Сохраните токен Длинная строка с двоеточием. Это пароль от бота — сегодня он ляжет в файл, и в конце разберём, почему так нельзя в проде
Возьмите шаблон Кнопка «Скопировать шаблон» ниже, либо «Скачать файл»
Сохраните как index.html Если копировали код — вставьте в любой текстовый редактор и сохраните файлом
Опубликуйте Форма в самом верху страницы: пароль, короткое имя, файл. В ответ придёт готовый адрес. Имя запишите: публикация под тем же именем обновляет страницу, а ссылка остаётся прежней
Привяжите к боту @BotFather → /mybots → выберите своего бота → Bot Settings → Menu Button → вставьте адрес, затем название кнопки. Не видите Menu Button — вы на экране Edit Bot, вернитесь назад и войдите в Bot Settings
Откройте своего бота Должна открыться карта с баллами. Открылась — вы прошли самое сложное
Сделайте его своим Промпт «Свой бренд» ниже: название, цвет, уровни, проценты. Дальше — сколько успеете
Включите уведомления Вставьте токен в botToken и опубликуйте снова под тем же именем — адрес не изменится, заново привязывать бота не нужно
Проверьте: телефон жужжит Нажмите /start у своего бота — он не может написать первым, — потом кнопку начисления в мини-аппе

Шаблон

Один HTML-файл. Ни сервера, ни базы, ни сборки. Баллы хранятся в CloudStorage — это key-value прямо на серверах Telegram, свой у каждого гостя, поэтому бэкенд и не нужен.

Скачать файл

Менять нужно только блок CONFIG в начале файла — он подписан по-русски. Всё остальное можно не трогать.

Как разговаривать с моделью

Промпт — это ТЗ, а не пожелание. Разница ровно в пяти пунктах:

КонтекстВесь файл целиком, в каждом запросе

ЭкранГде именно это находится

ДействиеЧто должно произойти

ОграничениеЧего делать нельзя

ПроверкаКак вы поймёте, что вышло

Три правила, которые спасают

Файл целиком в каждом запросе. Модель не помнит ваш код между сообщениями.
Один запрос — одно изменение. Большой запрос ломает то, что работало.
Сохраняйте рабочую копию перед каждым запросом. Это ваша кнопка «отменить».

Где модель врёт

придумывает методы Telegram, которых не существует;
подключает библиотеки, которые не загрузятся;
«чинит» то, о чём не просили, и ломает соседнее;
уверенно рапортует о готовности, ничего не проверив.

Поэтому в каждом промпте и нужен пункт «проверка».

Промпт-карточки

Где написано [ВЕСЬ ФАЙЛ] — вставляйте свой HTML целиком. В угловых скобках — то, что заменяете на своё.

Не работает

Сверху то, что случается чаще всего.

Изменил файл, а ничего не поменялось

Telegram кэширует мини-аппы. Добавьте ?v=2 в конец адреса в BotFather (в следующий раз ?v=3) или закройте мини-апп и откройте заново. Это причина номер один.

Опубликовал, а BotFather не принимает адрес

Копируйте адрес кнопкой после публикации, а не набирайте руками. Он должен начинаться с https:// и заканчиваться косой чертой.

Белый экран

Откройте адрес мини-аппа в обычном браузере, добавив ?debug в конец, — внизу появится консоль с ошибкой. Скопируйте её в чат с моделью вместе с карточкой «Когда сломалось».

По адресу 404

Опечатка в имени. Опубликуйте заново и скопируйте адрес кнопкой.

Уведомление не приходит

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

Уведомления были и пропали после правки

Скорее всего модель переписала отправку на JSON.stringify. Так не работает: Telegram отвечает на предварительный запрос браузера кодом 501, и сообщение молча не уходит. Тело должно быть URLSearchParams, без своих заголовков. Верните как было в шаблоне.

Кнопки меню в боте нет

@BotFather → /mybots → ваш бот → Bot Settings → Menu Button. Если в списке нет Menu Button — вы зашли в Edit Bot, а нужно в Bot Settings: это две разные кнопки на одном экране. Затем перезапустите Telegram.

Баланс сбросился

Скорее всего вы открыли мини-апп в другом боте: данные хранятся отдельно для каждого бота.

Не помню, под каким именем публиковал

Опубликуйте под новым и заново вставьте адрес в BotFather. Старое останется висеть и никому не помешает.

Конфигуратор

Страховка для тех, кто отстал или сломал файл. Заполните форму — получите готовый файл, который остаётся опубликовать и привязать к боту. Без кода и без ИИ.

Название Подзаголовок Фирменный цвет

Уровни

НазваниеПорогПроцент

Порог — сколько баллов гость накопил за всё время. Процент — сколько возвращается с покупки. Баллы сгорают через, дней 0 — сгорание выключено Суммы демо-кнопок, ₽ Три типичных чека вашего бизнеса Токен бота Без него всё работает, кроме уведомлений

Дальше — форма публикации наверху страницы.

Как это выглядит

VK и MAX

Сегодня в зале доводим до результата Telegram — он единственный, который проходится за девяносто минут всеми. Но архитектура у всех трёх одна: страница + мост к мессенджеру + бот. Ваш HTML не меняется, меняется мост.

Важное различие. Бота можно завести за минуту во всех трёх. А вот подключить к нему мини-апп: в Telegram — сразу и кому угодно, в VK — сразу себе, чужим после модерации, в MAX — только при статусе ИП, юрлица или самозанятого.

VK — сообщество, бот и мини-приложение

Создайте сообщество: vk.com/groups → «Создать сообщество».
Управление → Работа с API → создайте ключ доступа с правами на сообщения. Это аналог токена из BotFather.
Мини-приложение: vk.com/editapp?act=create → тип «Мини-приложение» → укажите адрес вашей страницы (обязательно https).
У вас оно откроется сразу — тестировать можно немедленно.
Чтобы показать чужим, отправьте на модерацию из панели приложения. Заявленный срок — около недели.
В коде: вместо Telegram.WebApp подключается VK Bridge. Он тоже отдаёт данные о том, кто открыл приложение.

Отдельно проверьте хранилище: аналога CloudStorage там нет, так что баллы придётся держать на своём сервере.

MAX — бот за минуту, мини-апп по статусу

В MAX найдите @MasterBot → команда /create.
Придумайте никнейм: латиница и цифры, окончание на bot или _bot, минимум 11 символов.
MasterBot выдаст токен — это пароль от бота, как в Telegram.
Мини-приложение подключается на платформе для партнёров dev.max.ru: Чат-боты → Расширенные настройки → адрес мини-приложения и тип кнопки открытия.
Требования к адресу: только https, до 1024 символов.
В коде: MAX Bridge, глобальный объект window.WebApp, данные о пользователе — в initData.

Ограничение, о котором лучше знать заранее. Доступ к платформе для партнёров открыт юрлицам, ИП и самозанятым — резидентам РФ. Сам бот заработает и без этого, а вот мини-апп к нему подключить не получится.

Куда переехать

Адрес на w.mtrntv.com — площадка воркшопа, а не хостинг: он гасится 22 августа. Файл при переезде не меняется вообще. Меняется только адрес в BotFather.

GitHub Pages — бесплатно и бессрочно

Заведите репозиторий и положите туда свой index.html.
Settings → Pages → источник: ветка main, папка /root.
Через минуту получите адрес вида имя.github.io/репозиторий/ — с сертификатом.
Вставьте его в BotFather вместо старого.

Подходит лучше всего: бесплатно, не истекает, правки — обычным коммитом.

Объектное хранилище облака — копейки в месяц

Yandex Object Storage, VK Cloud, Selectel: создаётся бакет, включается раздача статики, файл загружается через веб-интерфейс. Стоит несколько рублей в месяц, зато можно повесить свой домен.

Тот же путь рекомендует и документация MAX для своих мини-приложений.

Обычный хостинг или свой сервер

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

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

Что дальше

Что вы унесли

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

Что сломается на настоящих гостях

баллы лежат у гостя в телефоне: накрутить их можно из консоли браузера;
посмотреть, у кого сколько баллов, вам нечем;
начисление нажимает сам гость — связи с реальными покупками нет;
токен бота лежит в файле, открытом всему интернету;
нет кассы, нет выгрузки в CDP, нет контура 152-ФЗ.

Всё перечисленное — сознательные упрощения ради девяноста минут. Пилот они выдержат, боевую программу лояльности нет.

Что добавляется для прода

проверка подписи initData на сервере при каждом запросе;
токен бота переезжает на сервер и исчезает из файла;
начисление по событию из кассы или CRM, а не по нажатию гостя;
антифрод на начислениях и обменах;
согласие на обработку данных и политика.

Адрес живёт до конца конференции. Это площадка воркшопа, а не хостинг. Чтобы мини-апп остался у вас, перенесите файл на свой хостинг и поменяйте адрес в BotFather — файл самодостаточный, больше ничего не нужно.