Создаём отдельную ссылку для каждого размещения
В ссылку на личный чат с ботом добавляется параметр start. После соответствующего запуска в приложение приходит команда /start с меткой. Замените ExampleSchoolBot на username своего бота; ссылки ниже демонстрационные.
https://t.me/ExampleSchoolBot?start=ad_autumn_a https://t.me/ExampleSchoolBot?start=site_header https://t.me/ExampleSchoolBot?start=qr_frontdesk
В QR-код поместите третью ссылку целиком, включая ?start=. Для разных плакатов создавайте разные метки. Одна общая метка qr не позволит отличить стойку в филиале от печатной листовки.
Telegram разрешает в start буквы A–Z и a–z, цифры, подчёркивание и дефис; длина — до 64 символов. Длинный набор UTM-параметров храните в своей таблице кампаний, а в ссылку помещайте короткий код. Правила приведены в документации deep linking.
Словарь кампаний связывает код с каналом, кампанией, размещением и периодом действия. Не меняйте значение уже использованной метки на другую кампанию: исторические заявки станут неоднозначными. Создайте новый код, даже если название рекламы почти не изменилось.
Разбираем команду и проверяем метку
Нужны PHP 8.3+, настроенный webhook и БД. Ниже — чистая функция разбора текста. Вызывайте её после проверки подлинности update и убедившись, что это message из личного чата пользователя. В ней нет сетевых запросов и сохранения состояния.
<?php
declare(strict_types=1);
/** @param array<string, int> $campaigns
* @return array{kind: string, campaign_id: ?int}|null
*/
function startSource(string $text, string $botUsername, array $campaigns): ?array
{
if (!preg_match('/\A\/start(?:@([A-Za-z0-9_]+))?(?: ([A-Za-z0-9_-]{1,64}))?\z/', $text, $match)) {
return null;
}
if (($match[1] ?? '') !== '' && strcasecmp($match[1], $botUsername) !== 0) {
return null;
}
$tag = $match[2] ?? null;
if ($tag === null) {
return ['kind' => 'untagged', 'campaign_id' => null];
}
if (!array_key_exists($tag, $campaigns)) {
return ['kind' => 'unknown_tag', 'campaign_id' => null];
}
return ['kind' => 'tagged', 'campaign_id' => $campaigns[$tag]];
}
Например, передайте словарь ["ad_autumn_a" => 101, "site_header" => 102, "qr_frontdesk" => 103]. Для /start site_header функция вернёт campaign_id=102. Null означает, что текст не соответствует поддерживаемой команде; это не повод завершать webhook с ошибкой. Обычный обработчик может предложить /help или начать диалог без атрибуции.
Метка неизвестной кампании не превращается в новое название источника автоматически. Иначе любой пользователь создаст тысячи «кампаний» произвольными командами. Ограничьте словарь и сохраняйте технический статус unknown_tag без полного непроверенного текста.
Команду можно набрать вручную или переслать ссылку другому человеку. Поэтому метка не служит удостоверением личности, разрешением на скидку или подтверждением оплаты. Для привязки аккаунта нужен отдельный одноразовый токен и проверка, описанная в руководстве о привязке Telegram к сайту.
Разделяем первый контакт и последний переход с меткой
Создайте профиль атрибуции с уникальным ключом (bot_id, telegram_user_id). Сохраняйте first_seen_at, first_source_kind, first_campaign_id, last_tagged_at и last_tagged_campaign_id. Первым контактом считайте первое принятое пользовательское событие, а не первый известный рекламный переход.
Правила этого примера: первый источник записывается один раз; новый известный tagged-переход обновляет последний источник с меткой; /start без метки и unknown_tag его не стирают. Если первый контакт был без метки, поле first_campaign_id остаётся пустым даже после последующей рекламы.
Первый /start → first = untagged, last_tagged = пусто /start ad_autumn_a → first = untagged, last_tagged = 101 Повторный /start → first = untagged, last_tagged = 101 /start site_header → first = untagged, last_tagged = 102
Сохранение события и изменение профиля выполняйте в одной транзакции. У входящего события должен быть уникальный ключ (bot_id, update_id). Повторная доставка одного update не создаёт нового перехода и не меняет время последнего источника. Для конкурентных событий блокируйте профиль и обрабатывайте поток одного пользователя последовательно.
Храните время самого события и серверное время приёма отдельно. Если старый update обрабатывается после нового, он не должен откатывать last_tagged. Для обычных message сравнивайте message.date, а внутри одной непрерывной последовательности — update_id при равных датах. Не используйте один глобальный максимум update_id для всех пользователей и ботов.
Удаление переписки в Telegram не стирает вашу БД. Возврат пользователя с тем же user_id не следует автоматически считать новым человеком. При удалении данных по принятой политике последующее взаимодействие действительно может выглядеть первым известным контактом приложения.
Фиксируем источник в конкретной заявке
В момент подтверждения анкеты скопируйте в заявку снимок атрибуции: first_campaign_id, выбранный last_tagged_campaign_id, его дату и версию правила расчёта. Источник заявки не должен меняться задним числом при следующем /start того же пользователя.
Задайте окно атрибуции, например 30 дней до подтверждения. Это правило вашего отчёта: если последний известный tagged-переход старше окна, у заявки будет source_kind=unknown. Не называйте её автоматически «прямой», поскольку отсутствие метки не доказывает прямой заход.
Сначала сохраните заявку и снимок источника транзакционно, затем передавайте их в CRM или Google Таблицы. Сохраняйте стабильный ID кампании и понятное название на момент заявки, если названия кампаний редактируются.
В отчёте разделите число полученных запусков, уникальных пользователей и подтверждённых заявок. Один человек может запускать бота несколько раз и оставить несколько заявок. При сравнении кампаний указывайте выбранную модель: первый контакт и последний известный переход отвечают на разные вопросы.
Что такая аналитика не показывает
Бот видит пришедшую команду, а не каждое открытие ссылки и не каждый просмотр QR-кода. Если пользователь не дошёл до отправки /start, события в приложении не будет. Нельзя вычислить конверсию из кликов в запуски, имея только данные бота: для знаменателя нужен отдельный источник кликов.
Метка характеризует ссылку. Её могли скопировать, переслать в другой чат или опубликовать на другом сайте. Telegram не передаёт боту браузерный referrer и автоматически не переносит UTM с предыдущей страницы.
Если на сайте выбираете ссылку в зависимости от UTM, задайте контролируемое сопоставление с вашим словарём. Не вставляйте в start телефон, email, произвольный адрес страницы или секрет: ссылка видна пользователю и может попасть в журналы и переписку.
Сбор переходов на сайте, cookies и серверный учёт событий бота — отдельные механизмы. Не считайте нажатие /start согласием на любую последующую аналитику или рассылку. Опишите назначение и срок хранения данных и применяйте выбранные правила доступа; существующее согласие на аналитику сайта само по себе не привязывается к Telegram user_id.
Проверяем путь от ссылки до заявки
Откройте каждую из трёх ссылок и проверьте фактический message.text в тестовом обработчике.
Проверьте первый контакт без метки, повторный запуск и переход из другой кампании.
Передайте неизвестную метку и команду для другого бота: они не должны создавать кампанию.
Повторите один update: число переходов и время источника не меняются.
Подтвердите заявку, затем запустите бота из другой ссылки: источник старой заявки сохраняется.
Проверьте истёкшее окно атрибуции и отчёт по пользователям отдельно от числа запусков.
Если подключён BotGate, разбор /start и таблицы кампаний остаются в вашем приложении. Получайте update через подписанный webhook и не смешивайте Telegram update_id с идентификатором доставки сервиса. Отдельная настройка Метрики для чтения start не требуется.