# ✨ Как настроить реферальную систему в BotMan

Source: https://docs.botman.pro/a/89-kak-nastroit-referalnuyu-sistemu-v-botman

По этой инструкции вы настроите реферальную механику для ваших ботов:\
пользователь получит персональную ссылку-приглашение, новый подписчик перейдёт по ней, бот сохранит 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.** В ветке «Не соответствует условиям» тоже добавьте сообщение, чтобы пользователь не оставался без ответа.

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

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

![](https://storage.yandexcloud.net/botman-knowledge-prod/kb/6aec5304d3ac9dc31d82ccf6/099539af0e0af9f8cae7ad744257cc9838b32275103853269188fe872b7cc6b5.png)

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

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

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

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

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

💫Твоя реферальная ссылка:`https://t.me/ИМЯ_БОТА?start={{user_id}}`\
\
🫂Ты пригласил(а): `{{count_field("referal")}}` человек\
\
⭐️Топ рефереров: `{{top_field("referal", 10)}}`

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

- **ВКонтакте:** `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 можно получить, если вставить поле, например, в блок «Сообщение» через значок &lt;/>. Скопируется id поля (тот самый `user_field_xxx` )

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

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

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

![](https://storage.yandexcloud.net/botman-knowledge-prod/kb/6aec5304d3ac9dc31d82ccf6/bf1589bc7312f368f1d06179ece6dae292f8201f202c88aa44aab3fbd537ec57.png)

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

---

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

| Ошибка | Почему не работает | Как правильно |
| --- | --- | --- |
| Смешивают всё в одном сценарии | Старт, статистика и бонусная логика смешиваются между собой. | Сделать отдельно: сценарий старта, сценарий «Моя рефка», бонусную ветку. |
| Используют название поля вместо кода | Формулы не понимают красивое название поля. | Использовать код поля, например {{count\_field("referal")}}. |
| Нет ветки «Не соответствует условиям» | Повторный пользователь может остаться без ответа. | Подключить сообщение к обеим веткам. |
| Проверяют бонус напрямую через текстовую формулу | Условие получается непонятным и неудобным в поддержке. | Сначала записать количество в числовое поле, потом проверять его в блоке «Условие». |

---

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

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

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

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

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

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

---

🚀 Готово. Теперь у вас есть рабочая логика реферальной системы. Если появятся вопросы по настройке, напишите в [чат поддержки](https://t.me/BotManSupport_bot).