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

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

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

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

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

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

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

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

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

📝 Для начала важно понимать разницу между двумя понятиями:

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

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

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

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

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

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

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

Если вы хотите отдельно сохранять количество приглашённых пользователей и использовать это значение в логике сценария, создайте ещё одно поле:
• название: Количество рефералов ;
• тип: Число.

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

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

Почему важно правильно задать код поля

Код поля используется в формулах Botman, например count_field  и top_field 

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

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

Важно для настройки ссылки

Формат реферальной ссылки зависит от канала, в котором работает бот:

• Telegram: https://t.me/имя_бота?start={{user_id}} 
• ВКонтакте:https://vk.me/id_вашего_сообщества?ref={{user_id}} 
• MAX: https://max.ru/ИМЯ_БОТА?start={{user_id}}

Для ВКонтакте в ссылке нужно указать адрес вашего сообщества. Это может быть стандартный идентификатор, например club123456789, или короткое имя сообщества, если вы задали его в настройках и оно отображается в адресе страницы.

2. ⚙️ Как работает реферальная логика

Реферальная ссылка зависит от канала, в котором работает бот:

• Telegram:https://t.me/ИМЯ_БОТА?start={{user_id}} 
• ВКонтакте:https://vk.me/id_вашего_сообщества?ref={{user_id}} 
• MAX: https://max.ru/ИМЯ_БОТА?start={{user_id}} 

Где:

• ИМЯ_БОТА - имя вашего бота в канале;
• id_вашего_сообщества - адрес сообщества ВКонтакте;
• {{user_id}} - системная переменная Botman с ID текущего пользователя.

Для ВКонтакте в ссылке нужно указать адрес вашего сообщества. Это может быть стандартный идентификатор, например club123456789, или короткое имя сообщества, если вы задали его в настройках и оно отображается в адресе страницы.

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

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

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

Создайте отдельный сценарий, например «Обработка реферального старта».

➡️ Шаг 1. Создайте новый сценарий
➡️ Шаг 2. В триггере выберите запуск по кнопке «Старт». Ключевые слова сюда добавлять не нужно.
➡️ Шаг 3. Первым шагом добавьте блок «Условие». 

В нём проверьте пользовательское поле «Реферал»:
- Тип Условия «Проверка поля»
- Раздел «Пользовательские поля»
- поле referal
- условие сравнения «Неизвестно».

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

➡️ Шаг 4. Если поле ещё не заполнено, сохраните стартовую команду в поле referal через шаг «Действие» в  {{start_command}}
➡️ Шаг 5. После этого можно показать приветственное сообщение.
➡️ Шаг 6. В ветке «Не соответствует условиям» тоже добавьте сообщение, чтобы пользователь не оставался без ответа.

Почему это важно

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

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

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

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

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

Пример текста для Telegram:

Если бот работает в другом канале, замените ссылку на подходящий формат:

• ВКонтакте: https://vk.me/id_вашего_сообщества?ref={{user_id}} 
• MAX:  https://max.ru/ИМЯ_БОТА?start={{user_id}} 

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

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

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

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

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

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

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

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

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

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

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

После этого проверьте:

✅ У аккаунта B в поле referal сохранилось значение стартовой команды. Проверить это можно в разделе Диалоги или в карточке подписчика в разделе Подписчики.
✅ В аккаунте A корректно отображается количество приглашённых пользователей.
✅ Если вы проверяете топ рефереров, повторите тест с несколькими новыми аккаунтами.
✅ Если вы проверяете бонусную механику, убедитесь, что значение записывается в числовое поле и условие срабатывает по нему.

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

• поле referal создано;
• поле «Количество рефералов» создано, если используется бонусная логика;
• стартовая команда сохраняется в поле referal;
• формулы count_field и top_field используют именно код поля;
• ветка «Не соответствует условиям» подключена;
• бонусная проверка идёт через числовое поле.

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