По этой инструкции вы настроите реферальную механику для Telegram-бота:
пользователь получит персональную ссылку-приглашение, новый подписчик перейдёт по ней, бот сохранит ID пригласившего, а вы сможете считать количество приглашённых и выдавать бонусы за нужное число рефералов 🎯

Подходит для Telegram-ботов, где реферальная логика строится через параметр /start  и стартовую команду.

🎯 Что получится в итоге:

• пользователь получает уникальную реферальную ссылку;

• при переходе нового пользователя (реферала) по этой ссылке бот сохраняет пригласившего;

• владелец ссылки может видеть количество приглашённых пользователей и топ рефереров;

• при необходимости для него можно настроить автоматическую выдачу бонуса по заданным условиям.

1. 🛠 Что нужно сделать заранее

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

📝 Сначала важно разобраться в двух понятиях.

Код поля - это внутреннее название поля на латинице, которое вы задаёте сами при создании. Именно код поля чаще всего используется в формулах, условиях и других настройках. Поэтому рекомендуем сразу указывать его просто и понятно, например referal

ID поля - это технический идентификатор поля в системе. Его можно получить через значок </>, если вставить поле в текст, например в блоке «Сообщение». После вставки вы увидите конструкцию вида {{user_field_123456}} 

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

Поле 1. Кто пригласил пользователя

Создайте пользовательское поле со следующими параметрами:
• название: referal;
• тип: Текст;
• код поля: например referal .

Это поле нужно для того, чтобы сохранять ID пользователя, который пригласил нового подписчика.

Почему это важно: именно код этого поля потом используется в формулах count_field  и top_field- это формулы Botman, которые работают с кодом поля.

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

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

Поле 2. Сколько людей пригласил пользователь

Создайте ещё одно пользовательское поле:
• название: Количество рефералов;
• тип: Число.

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

Если вам нужен только подсчёт через формулу и отдельная запись этого значения не требуется, второе поле можно не создавать.

2. ⚙️ Как работает логика

Реферальная ссылка выглядит так:  https://t.me/ИМЯ_БОТА?start={{user_id}} 

Где:
ИМЯ_ВАШЕГО_БОТА - username вашего Telegram-бота,
{{user_id}}  - системная переменная Botman с ID текущего пользователя.

Когда другой человек перейдёт по такой ссылке и запустит бота, в стартовую команду передастся ID пригласившего.

• Если пользователь пришёл по чужой ссылке впервые, он становится чьим-то рефералом
• Если пользователь запустил обычный /start, он идёт по стандартной ветке.
• Если пользователь уже чей-то реферал, поле не перезаписывается новым значением.

3. 📊 Сценарий 1. Сохраняем, кто пригласил пользователя

➡️ Шаг 1. Создайте новый сценарий, например «Обработка реферального старта».
➡️ Шаг 2. В триггере выберите запуск по кнопке «Старт». Ключевые слова сюда добавлять не нужно.
➡️ Шаг 3. Первым шагом добавьте блок «Условие». В нём проверьте пользовательское поле «Реферал». Тип Условия «Проверка поля», нужно выбрать «Пользовательские поля», выбрать текстовое поле referal. Условие сравнения «Неизвестно».
➡️ Шаг 4. После действия можно показать приветственное сообщение.
➡️ Шаг 5. В ветке «Не соответствует условиям» тоже добавьте сообщение, чтобы пользователь не зависал без ответа.

Зачем нужна проверка «Нет значения в поле»: без неё человек сможет повторно запустить бота по другой ссылке и случайно перезаписать себе пригласившего.

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

4. 📊 Сценарий 2. Показываем пользователю его реферальную ссылку и статистику

Создайте отдельный сценарий. Не надо смешивать его со сценарием старта, иначе потом начинается весёлый бардак.
➡️ Шаг 1. Создайте новый сценарий, например «Моя рефка».
➡️ Шаг 2. В триггере выберите ключевое слово «рефка» или кнопку в меню.
➡️ Шаг 3. Первым шагом добавьте блок «Сообщение» и вставьте в него текст ниже.
➡️ Шаг 4. Сохраните и включите сценарий.

Что означает каждая формула:

•{{user_id}} подставляет ID текущего пользователя в ссылку.
• {{count_field("referal")}}  считает, сколько людей пришли именно по ссылке этого пользователя.
• {{top_field("referal", 10)}}  показывает топ рефереров, максимум 10 человек.

Лучше использовать именно код поля, например referal. Варианты с user_field_xxx могут работать, но они менее понятны и чаще путают. user_field_xxx можно получить скопировав, например, из блока Сообщение вставленное поле. Скопируется id поля (тот самый user_field_xxx)

5. 📊 Сценарий 3. Выдаём бонус за нужное количество рефералов

Рабочая схема такая:
• сначала показываем или получаем количество рефералов;
• потом записываем это значение в числовое поле;
• после этого проверяем числовое поле в блоке «Условие»;
• если значение подходит, выдаём бонус.

➡️ Шаг 1. В блоке «Сообщение» можно вывести пользователю текущую статистику.
➡️ Шаг 2. После сообщения добавьте блок «Действие» и запишите количество рефералов в числовое поле «Количество рефералов».
➡️ Шаг 3. Далее добавьте блок «Условие» и проверьте поле «Количество рефералов». Например: больше чем 4, если бонус должен выдаваться от 5 приглашённых.
➡️ Шаг 4. На положительной ветке покажите сообщение с бонусом «Сообщение 3». На отрицательной ветке — сообщение, что приглашённых пока недостаточно.

📌ВАЖНО: В стартовом блоке отключите галочку на Запуск на кнопку "Старт", иначе два сценария будут запускаться одновременно по команде /start.

Не надо вручную увеличивать счётчик через +1, если вам нужно просто показать статистику. count_field уже сам считает количество рефералов. Отдельное числовое поле нужно только для проверки условий и бонусной логики.

Частые ошибки

Как тестировать

• Telegram аккаунт A запускает бота и получает свою реферальную ссылку.
• Telegram аккаунт B, который раньше не запускал бота, переходит по этой ссылке.

 ✅ Проверьте, что у аккаунта B в поле «Реферал» сохранилось значение стартовой команды. Значение поля можно посмотреть в разделе Диалоги или в карточке подписчика в разделе Подписчики.
✅ Вернитесь в Telegram аккаунт A, перезапустите сценарий через команду /start. Счётчик должен показать 1.
✅ Если нужна проверка топа, повторите тест с несколькими новыми аккаунтами.
✅ Если нужна проверка бонуса, убедитесь, что значение записывается в числовое поле и условие срабатывает по нему.

Короткий чек-лист перед запуском

🚀 Готово. Теперь у тебя рабочий кейс с реферальной системой! Если, что пишите нам, поможем все настроить: чат поддержки