Как передать UTM-метки из Telegram в amoCRM через Salesbot

Если вы используете amoCRM и Telegram-бота, созданного на базе Salesbot Именно Salesbot от amoCRM: https://www.amocrm.ru/developers/content/digital_pipeline/salesbot, то, возможно, задавались вопросом: а как понять, из какого источника пришёл лид в бота? По умолчанию Telegram-бот на базе Salesbot не записывает в amoCRM UTM-метки или другие параметры аналитики. Из-за этого источники лидов теряются, и связать заявку с рекламной кампанией становится сложно.

Я нашёл способ решить эту задачу.

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

Здесь важно различать roistat_visit и UTM-метки: roistat_visit — идентификатор визита Roistat, а не сама UTM-метка. Он позволяет связать сделку с источником визита, который система аналитики определила на сайте.

Принцип работы

1. На моём сайте установлен скрипт, который получает значение roistat_visit Идентификатор визита в системе сквозной аналитики Roistat и автоматически добавляет его к ссылкам на Telegram-бота через параметр start. Например, ссылка https://t.me/your_bot превращается в https://t.me/your_bot?start=111111, где 111111 — идентификатор визита в Roistat.
2. Когда пользователь переходит по ссылке и запускает бота, обработчик meta считывает переданное значение и записывает его в указанное поле сделки в amoCRM.
3. После этого бот функционирует в обычном режиме, а вы получаете недостающие данные для аналитики. При этом пользователь не заметит никаких изменений в работе бота.

Как передать параметры в Telegram-бота

Всё зависит от того, откуда пользователь переходит в бота.

Если переход идёт с сайта, можно автоматически подставлять нужный параметр в ссылку. В моём случае это roistat_visit, который Roistat сохраняет в cookie посетителя.

Вот небольшой пример JavaScript для сайта:

<script>
(() => {
  const BOT_URL = 'https://t.me/your_bot';
  const RETRY_DELAY = 200;
  const LINK_SELECTOR = `a[href^="${BOT_URL}"]`;

  function readVisitId() {
    const match = document.cookie.match(/(?:^|;\s*)roistat_visit=([^;]+)/);
    if (!match) return '';

    const value = match[1].replace(/^["']|["']$/g, '');
    try {
      return decodeURIComponent(value);
    } catch {
      return '';
    }
  }

  function updateLinks(visitId, root = document) {
    const destination = `${BOT_URL}?start=${encodeURIComponent(visitId)}`;

    if (root instanceof Element && root.matches(LINK_SELECTOR)) {
      root.href = destination;
    }

    root.querySelectorAll(LINK_SELECTOR).forEach(link => {
      link.href = destination;
    });
  }

  function start() {
    const visitId = readVisitId();
    if (!visitId) {
      setTimeout(start, RETRY_DELAY);
      return;
    }

    updateLinks(visitId);

    const observer = new MutationObserver(records => {
      for (const record of records) {
        for (const node of record.addedNodes) {
          if (node instanceof Element) updateLinks(visitId, node);
        }
      }
    });

    observer.observe(document.body, { childList: true, subtree: true });
  }

  if (document.readyState === 'loading') {
    document.addEventListener('DOMContentLoaded', start, { once: true });
  } else {
    start();
  }
})();
</script>

Замените your_bot на имя своего Telegram-бота и вставьте блок целиком в HTML-код сайта. Скрипт ждёт появления roistat_visit, добавляет номер визита в существующие ссылки и обрабатывает новые элементы страницы. Для работы на сайте должен быть установлен счётчик Roistat.

Если реклама ведёт сразу в Telegram-бота, без промежуточного перехода на сайт, всё проще. Можно заранее добавить метку в рекламную ссылку:

https://t.me/your_bot?start=tgads-campaign1

Здесь tgads — источник, а campaign1 — кампания. Скрипт на сайте не нужен. В примере используется дефис, потому что именно он указан в delimiter обработчика meta. Чтобы записать источник и кампанию отдельно, укажите в массиве values два поля сделки в том же порядке. JSON ниже рассчитан на одно значение, например roistat_visit.

Правда, есть нюанс: roistat_visit так не получить, если пользователь не посещал сайт с установленным Roistat: визит на сайте не был создан. Зато можно сохранить источник и рекламную кампанию.

Как настроить обработчик в Salesbot

В конструкторе Salesbot добавляем блок «Свой обработчик (код)» и вставляем следующий JSON:

{
  "params": {
    "values": [
      "lead.custom_fields.123456"
    ],
    "delimiter": "-"
  },
  "handler": "meta"
}

Здесь всё достаточно просто:

• handler — встроенный обработчик meta, который получает данные при запуске чата.
• values — поля сделки, в которые записываются полученные значения.
• delimiter — разделитель параметров. В моём случае передаётся только один параметр, поэтому он фактически не используется.

Вместо 123456 нужно указать ID своего дополнительного поля сделки в amoCRM.

Как узнать ID поля? Откройте любую сделку, нажмите «Настроить» и выберите нужное поле. В настройках поля будет указан его ID. Если подходящего поля нет, создайте новое с типом «Текст».

После этого можно продолжить обычный сценарий Salesbot. Никаких дополнительных действий от пользователя не требуется.

Что ещё важно учитывать

У Telegram есть ограничение: через параметр start можно передать не более 64 символов. Допускаются латинские буквы, цифры, дефис и нижнее подчёркивание.

Поэтому передавать обычную строку с UTM-метками через & и = напрямую не получится.

Если нужно передать несколько параметров, можно разделить их дефисом. Например:

https://t.me/your_bot?start=telegram-cpc-campaign1

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

Также рекомендую проверять работу на новом диалоге с ботом. При повторных переходах пользователя параметры не всегда будут записываться повторно, поскольку обработчик meta работает только на этапе «Неразобранное».

На этом всё. Надеюсь, статья была полезной!