UTM-метки в Telegram боте: как добавить реферальную систему за 2 минуты

Реферальная программа — это когда пользователи приводят вам новых пользователей, а вы им за это платите. Звучит просто. Обычно заканчивается тем, что разработчик две недели пишет генерацию кодов, таблицу балансов, защиту от накруток и админку для выплат, а потом ещё месяц это всё чинит.

В Graspil всё это уже есть. Реально нужно сделать две вещи: подключить бота и включить реферальную программу. По минуте на каждую — читать эту статью вы будете дольше, чем настраивать.

Зачем вообще реферальная система

Коротко: это самый дешёвый канал привлечения из существующих.

Реферал приходит с рекомендацией от знакомого — доверие уже есть, конверсия в оплату у таких выше.
Вы платите за результат, а не за показы. Никаких «слили бюджет на РСЯ, получили ботов».
Реферер остаётся дольше: у человека, который привёл пятерых друзей, порог выхода из бота заметно выше.
Растёт само. Один довольный пользователь → трое новых → каждый из них тоже с ссылкой.

В общем, очевидно. Идём дальше.

Что уже есть из коробки

Чтобы вы понимали масштаб бедствия, которое вам не придётся кодить:

Фича	Что делает
Коды и ссылки	Уникальный код и готовая ссылка `t.me/bot?start=...` для каждого пользователя — генерирует платформа
Учёт «кто кого привёл»	Связь реферер → реферал пишется автоматически при `/start` по ссылке
Боты и Mini App	Работает и с обычными ботами, и с Telegram Mini App — метки обрабатываются по одним правилам
Правила начислений	Процент от оплаты, фикс за приведённого, внешняя награда — с условиями по сумме события
Мультивалютность	Баланс ведётся отдельно по каждой валюте, без принудительной конвертации
Период выдержки (hold)	Начисление «замораживается» на N дней — на случай возвратов
Выплаты	Вручную, по вебхуку, через популярные платёжные системы или автоматом по расписанию
Готовая автоматизация	Кабинет реферера в боте — из каталога, без единой строчки кода
Статистика	Воронка, топ рефереров, динамика начислений и выплат
Отчёты по рефералам	Реферальные данные доступны в конструкторе отчётов: можно построить отчёт только по тем, кто пришёл из реф-программы, и сравнить их с остальными
Гибкое API	Если наши сценарии не подходят — коды, начисления, балансы и выплаты доступны через API, и логику можно собрать свою

И главное: реф-систему Graspil можно подключить, даже если у вас уже есть своя. Тогда она работает в режиме наблюдения и просто даёт аналитику, не трогая вашу логику.

Подключаем бота

Если бот уже в Graspil — пропускайте раздел.

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

Авто-подключение (MtProto). Вставляете токен бота — и всё, система дальше сама. Работает с любыми ботами и конструкторами, ничего в коде менять не нужно, данных собирает даже чуть больше остальных методов.

Не хотите отдавать токен — есть API-подключение: один HTTP-запрос из вашего бота, который шлёт нам апдейты. Тоже минут на пять работы разработчика, но токен остаётся у вас.

Сначала разбираемся со start-параметром

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

Что такое параметр start

В Telegram есть ровно один способ передать данные в бот при запуске — deep link:

https://t.me/YourBot?start=ЗДЕСЬ_ВАШИ_ДАННЫЕ

Одна строка, максимум 64 символа. Всё. Больше Telegram вам ничего не даст. И через эту же строку должны пролезть и UTM-метки, и реферальный код.

Упрощённый режим — выключаем

По умолчанию у всех новых ботов включён упрощённый режим обработки start. Он берёт содержимое параметра как есть, целиком, одним куском:

start=	Параметр	Значение
`docs`	none	`docs`

Для реферальной системы это значит: весь start считается реферальным кодом. Ни UTM, ни источника, ни кампании — только код. Пришёл человек по ссылке ?start=kT7xQm2p из телеграм-канала — вы узнаете, кто его привёл, но не узнаете, откуда он вообще взялся.

Поэтому: идём в «Мои боты» → нужный бот → «UTM-метки» (правила обработки start) и выключаем упрощённый режим.

Придумываем формат ссылок заранее

Полный режим разбирает строку по двум разделителям: разделитель параметров (делит строку на пары) и разделитель значения (делит пару на ключ и значение).

Например, при разделителе параметров _ и разделителе значения - строка

?start=ref-kT7xQm2p_source-tgchannel

разбирается в нормальную таблицу:

Параметр	Значение
ref	kT7xQm2p
source	tgchannel

То есть в одной ссылке едут и реферальный код, и UTM-метка источника. Дальше в отчётах вы сможете сказать не просто «Вася привёл 40 человек», а «Вася привёл 40 человек, из них 30 из его канала и 10 из личных сообщений».

Три вещи, которые стоит решить до запуска программы, а не после:

Какой параметр отвечает за реф-код. По умолчанию ref — оставьте, если нет причин менять. Допустимы латиница, цифры и _.
Какие разделители. Помните про лимит в 64 символа: длинные красивые разделители съедают место под данные.
Какие UTM-метки поедут вместе с реф-кодом. Обычно хватает source.

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

Если упрощённый режим всё же остался включён — Graspil предупредит об этом прямо на экране активации реферальной программы. Мы старались.

Включаем реферальную систему

Раздел «Реф. программа» в личном кабинете. По умолчанию она выключена — жмём активацию.

Выбираем режим

Manage — управление. Платформа сама генерирует коды и ссылки, считает начисления, ведёт балансы и проводит выплаты. Берите этот режим, если реферальной программы у вас ещё нет — он даёт весь функционал и не требует ничего писать на своей стороне.

Observe — наблюдение. Мы просто смотрим, какие коды приходят в ?start=, фиксируем переходы и связь «кто кого привёл». Коды генерирует ваш бот, начислений нет. Берите, если у вас уже своя реферальная система и нужна только аналитика поверх неё.

Режим меняется в настройках в любой момент, накопленная история переходов при этом сохраняется. Так что если сомневаетесь — начните с наблюдения и переключитесь позже.

Один нюанс: чтобы система умела начислять, ей нужно знать владельца кода. В режиме manage это происходит само. В режиме observe — тремя путями:

включить опцию «Значение параметра — это Telegram-id реферера» и класть в ссылку не код, а сам Telegram-id реферера — тогда владелец перехода известен сразу, без отдельного слоя маппинга «код → пользователь»;
сообщить владельцев кодов пачкой через API POST /v1/referral/set-code-owners — работает и заранее, и задним числом (тогда все прошлые переходы по коду пересчитаются на реферера);
напрямую пометить пользователя рефералом через POST /v1/referral/mark-referral.

Остальные настройки активации

Имя start-параметра — то самое, про которое мы думали выше. Тут же есть превью реферальной ссылки.
Когда регистрировать реферала — при первом запуске бота (основной случай) и/или при повторном запуске и возврате после блокировки.

Жмём «Активировать программу» — в меню разворачиваются подразделы: Обзор, Настройки, Рефереры, Рефералы, Начисления, Выплаты, Статистика.

Бонус: кабинет реферера без единой строчки кода

Реферальная система умеет считать деньги, но пользователю их надо ещё как-то показать. И вот тут обычно начинается «а давайте напишем команду /me».

Не надо. Откройте Каталог автоматизаций и возьмите готовый шаблон «Кабинет реферера».

Что он делает из коробки:

Срабатывает на выбранное вами событие — например, команду /me или /balance.
Получает код реферера и его ссылку («Получить код и ссылку») — если кода ещё нет, создаст.
Тянет баланс («Получить баланс») — доступно, на выдержке, выплачено.
Отправляет пользователю сообщение примерно такого вида:

🎁 Ваш реферальный кабинет

🔗 Код: kT7xQm2p
Ссылка: https://t.me/YourBot?start=kT7xQm2p

👥 Приведено: 12
💰 Доступно к выплате: 1400

Под сообщением — кнопка «Получить выплату», которая продолжает сценарий и вызывает «Запросить выплату», а потом отвечает подтверждением.

После импорта нужно сделать ровно одно: выбрать событие-триггер и опубликовать. Кнопка выплаты подцепится к вашему боту автоматически.

Дальше шаблон можно докрутить как обычную автоматизацию: добавить операцию «Зарегистрировать реферера» в приветственное сообщение, поставить условие «показывать кнопку выплаты только если баланс больше нуля», прикрутить многоязычные тексты — переключатель языков в блоке сообщения работает и здесь.

За что платить и как платить

Это самая содержательная часть, но и она делается кликами.

Правила вознаграждений

Настройки → Правила вознаграждений. Есть пресеты — % от оплат, Фикс за приведённого, Продление сервиса, В кастомное поле — можно взять готовый и подправить.

Логика правила читается как предложение: за какое событие → сколько начислить → что ещё сделать.

За какое событие. Любое событие вашего бота, которое платформа уже знает: оплата, регистрация, прохождение шага. Тот же список, что в отчётах.

Доп. условия по значению. Фильтр по числовому значению события: начислять, только если value ≥ value_min, ≤ value_max или = value_eq. Классика: «10% с оплат, но только с чеков от 1000».

Сколько начислить — три типа награды:

Тип	Как считается
Фикс	Конкретная сумма в выбранной валюте — 100 монет за каждую оплату реферала
Процент	Процент от суммы события. Валюта наследуется из самого события, выбирать отдельно не нужно
Внешняя	Платформа не считает сумму, а просто дёргает ваш вебхук. Для случаев вроде «продлить подписку на 7 дней» — деньгами это не измеряется

Окно выдержки (hold), дней. Сколько начисление висит в статусе «на выдержке», прежде чем станет доступным к выплате. Если у вас 14 дней на возврат — ставьте 14 и спите спокойно.

Эффекты — что ещё сделать при начислении:

Webhook — POST на ваш URL с телом-шаблоном и подстановкой переменных: {{referrer_id}}, {{amount}}, {{event_value}} и другие.
Кастомное поле — увеличить (inc) или установить (set) доп. поле пользователя-реферера. Удобно, если хотите хранить накопленный баланс прямо в профиле и использовать его в сегментах рассылок.

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

Выплаты

Настройки → Выплаты.

Ручной (manual). Вы переводите деньги как вам удобно, а в системе отмечаете выплату как «Оплачена» или «Неуспешная» с комментарием. Платформа ведёт учёт, вы ведёте кошелёк.

Webhook. При выплате мы шлём POST на ваш URL в духе «зачисли X в валюте Y пользователю Z». Ваш сервер зачисляет и возвращает 2xx — выплата помечается оплаченной. Если вернёте external_ref — сохраним как ваш ID транзакции для сверки. Подходит, если у вас внутренний кошелёк или своя платёжка.

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

🛠 Не нашли нужную платёжку — напишите в поддержку. Добавим в течение суток.

Авто-выплаты — отдельный механизм, включается галочкой: расписание (ежемесячно или каждые N дней), метод по умолчанию и пороги по валютам («выплачивать, только если доступно ≥ 5000 ₽»). Ручные выплаты и выплаты через API работают всегда, независимо от расписания.

Инициировать выплату можно из карточки реферера, из раздела «Выплаты», через API POST /v1/referral/payout или кнопкой в самой автоматизации.

Жизненный цикл:

Запрошена → В обработке → Выполнена
                        ↘ Неуспешная (сумма возвращается в баланс)

Что происходит с балансом

Баланс ведётся по каждой валюте отдельно и складывается из четырёх кусков:

Что	Значит
Доступно	Подтверждённые начисления, не привязанные к выплате. Можно выплатить прямо сейчас
Зарезервировано	Уже включено в текущую выплату, она в процессе
На выдержке	Hold ещё не прошёл
Выплачено	Итог по всем успешным выплатам

Начисление живёт по маршруту: На выдержке → Подтверждено → В выплате → Выплачено, с ветками Возвращено (компенсирующее начисление) и Отменено.

Смотрим, что получилось

Обзор — сводка за 30 дней: всего рефереров, приведено рефералов, активных правил, начислений; балансы по валютам; воронка «новые пользователи → триггер-событие → начисления → выплаты»; динамика по дням; топ-5 по заработку и по числу рефералов.

Рефереры — список с фильтрами (период, валюта, «есть доступный баланс», минимум рефералов), сортировкой по заработку и экспортом. Из карточки реферера — его ссылка и кнопка выплаты.

Начисления и Выплаты — полный леджер со статусами. Каждая копейка на месте, если что-то пошло не так — видно, что именно.

Но самое интересное начинается дальше. Каждое начисление пишется в аналитику отдельным событием, а реферальные данные и UTM-метки из start-параметра доступны в конструкторе отчётов. Это значит, что можно строить не только «сколько мы раздали», а нормальные продуктовые отчёты:

Когорты рефералов против обычных пользователей — ретеншен приглашённых почти всегда выше, и это приятно видеть цифрами.
Воронка по источнику реф-ссылки — если вы разложили ref и source по разным параметрам (мы про это говорили в первой части), видно, из каких каналов ваши рефереры приводят платящих, а из каких — просто трафик.
Экономика программы — сколько выручки принесли рефералы против того, сколько вы начислили рефереру за их привлечение. Ставку по правилу можно поднять или опустить на основании этого, а не интуиции.
Тренды по правилам — какое правило реально работает, а какое просто раздаёт деньги.

А если мы захотим переехать в свою или другую систему?

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

Всё, что накопила система, доступно через API:

Коды и их владельцы — какому пользователю какой код принадлежит.
Рефералы — кто кого привёл, полным списком.
Начисления — весь леджер с суммами, валютами, статусами и правилами, по которым они сработали.
Балансы — доступно, на выдержке, выплачено, по каждой валюте.
История выплат — что, когда, каким способом и с каким внешним ID транзакции.

Плюс экспорт рефереров прямо из интерфейса.

То есть выгрузить всё и залить в свою базу — это скрипт на вечер, а не переговоры с поддержкой. Никакого замка на ваших данных мы не ставим: если Graspil перестанет быть удобным, вы уйдёте вместе со всей историей программы. Так, в общем-то, и должно быть.

Итого

Весь чек-лист умещается в шесть пунктов:

Подключили бота по токену.
Выключили упрощённый режим обработки start и определились с форматом ссылок.
Активировали реферальную программу в режиме manage.
Создали правило начисления.
Выбрали способ выплат.
Импортировали «Кабинет реферера» из каталога автоматизаций.

Единственный пункт, на который стоит потратить больше времени, — второй. Формат ссылок переделывать больно, всё остальное меняется в настройках в любой момент.

Остались вопросы по настройке или нужен способ выплат, которого пока нет — напишите нам в поддержку.

Как добавить реферальную систему в бот за 2 минуты