UTM-источники

UTM в боте работает не так, как в вебе — там нет URL с query-параметрами. В Telegram параметр передаётся в /start:

https://t.me/your_bot?start=instagram

Telegram вставит этот параметр в первое сообщение пользователя:

/start instagram

MaxBotStat умеет это парсить и сохранять как источник контакта.

Настройка utm_key

По умолчанию utm_key = utm_source, но это можно изменить. Зайдите в Настройки бота → Источники:

utm_key = source         # тогда /start source=instagram
utm_key = utm_source     # тогда /start utm_source=instagram

Допустимые форматы стартового параметра:

Формат	Пример	Распарсится как
просто значение	/start instagram	source_value=instagram
key=value	/start utm_source=instagram	source_value=instagram (если utm_key=utm_source)
несколько ключей	/start utm_source=ig|utm_campaign=spring	source_value=ig, campaign_name=spring

TIP

Поддерживаются разделители | и & для нескольких пар. Регистр значений сохраняется как есть.

Сопоставления (mappings)

Можно «нормализовать» источники: например, превратить ig, Instagram, instagram_main в одно значение Instagram.

В разделе Источники добавьте маппинг:

Сырой source_value: ig
Каноническое имя:   Instagram
Кампания:           Spring sale

После этого в отчётах все три варианта схлопываются в Instagram / Spring sale.

Где смотреть

• Раздел «Источники» — таблица: источник, кол-во контактов, сумма «касаний» (touches), последний контакт.
• Карточка контакта — индивидуальный источник и кампания.
• REST API — GET /api/v1/bots/<botId>/sources.

Через REST API

curl "https://capybara.maxbotstat.ru/api/v1/bots/<botId>/sources" \
     -H "X-API-Key: mbs_..."

{
  "utm_key": "utm_source",
  "data": [
    { "source_value": "instagram", "campaign_name": "spring", "contacts_count": 412, "touches": 1024 },
    { "source_value": "ads",       "campaign_name": null,     "contacts_count": 88,  "touches": 162 },
    { "source_value": "— unmapped","campaign_name": null,     "contacts_count": 5,   "touches": 12 }
  ]
}

— unmapped — это контакты, у которых не было /start с параметром (зашли напрямую через диалог).

Полезные ссылки

• Telegram Bot Payments → Deep Linking
• Воронки — анализ конверсии по этапам пути.