Интеграция с Telegram Bot¶

Эта интеграция подходит компаниям, которые используют Telegram-бота как точку входа для клиентов - например, размещают кнопку/ссылку на сайте, в рекламе, соцсетях или письмах. Клиент начинает диалог через бота, а система автоматически регистрирует обращение в CRM. Это помогает не терять лиды и сохранять данные о визите Roistat (roistat_visit) для определения источника в аналитике.

Возможности интеграции¶

Автоматическое создание сделки в CRM при первом сообщении клиента в Telegram-бот
Передача номера визита Roistat (roistat_visit) в CRM
Добавление данных о пользователе: username, user_id, ссылка на чат
Сохранение текста первого сообщения в комментарии к сделке
Автоматическое заполнение номера клиента, если он предоставлен
Генерация псевдо-номера телефона, если Telegram не передал реальный номер

Как это работает¶

Клиент пишет сообщение в ваш Telegram-бот
Если в сообщении присутствует start={roistat_visit}, система создаёт сделку в CRM и записывает номер визита Roistat. Если пользователь напишет напрямую в бота без start={roistat_visit}, сделка всё равно создаётся, но без номера визита
Если клиент уже есть в базе, сообщение фиксируется в карточке существующего клиента
При отсутствии телефона система генерирует псевдо-номер, проходящий проверку формата в CRM системах для создания сделки

Формирование псевдо-номера¶

Если Telegram не передал номер телефона, система создаёт псевдо-номер в корректном формате российского номера: +7(940)xxx-xx-xx

Как формируется номер?

Номер телефона = "+7940" + (hash(bot_id + ":" + user_id) mod 10^7), где

+7940 — префикс, который не принадлежит операторам
hash — детерминированная функция
bot_id — ID Telegram-бота
user_id — ID пользователя Telegram
mod 10^7 — остаток для получения 7-значного хвоста

Таким образом формируется стабильный и уникальный номер, проходящий проверку формата в CRM.

Какие данные передаются в CRM¶

При создании сделки из Telegram передаются:

Поле	Значение
Канал	Telegram Bot
Ссылка на чат	`https://t.me/имя_бота`
username	Никнейм клиента в Telegram
user_id	Уникальный идентификатор пользователя в Telegram
Номер клиента	Реальный или псевдо-номер
roistat_visit	Из параметра `start={roistat_visit}` (если есть)
Текст сообщения	Добавляется в комментарий к сделке

Настройка¶

В проекте Roistat раскройте главное меню в левом верхнем углу и перейдите в раздел Интеграции. Нажмите Добавить интеграцию. В появившемся окне найдите Telegram Bot, кликните по карточке и нажмите Добавить:

Затем откройте настройки интеграции Telegram Bot

Перед настройкой убедитесь

У вас есть Telegram-бот и его токен из @BotFather.
На сайте установлен счётчик Roistat

Шаг 1. Подключите Telegram-бота в Roistat¶

Перейдите в Roistat → Интеграции → Telegram Bot
Заполните поля на первом этапе:
- Токен бота — скопируйте токен из @BotFather
- Имя бота без “@” — например, my_shop_bot
- Текст сообщения — опционально, используется для приветственного сообщения
Нажмите Сохранить / Save Roistat автоматически зарегистрирует вебхук в Telegram
Если токен введён неверно, появится уведомление:
Неверный токен. Пожалуйста, проверьте и попробуйте снова

Шаг 2. Установка кода на сайт¶

Этот шаг нужен, чтобы Roistat сохранял номер визита (roistat_visit) при первом обращении клиента с сайта в Telegram-бота.

На этапе «Установка кода на сайт» скопируйте готовый скрипт
Вставьте скрипт сразу после кода счётчика Roistat на всех страницах сайта, где есть ссылка на бота
Скрипт автоматически найдёт ссылки вида https://t.me/<имя_бота> и добавит к ним параметр ?start={roistat_visit}

Пример ссылки на сайте

html <a href="https://t.me/my_shop_bot">Напишите нам в Telegram</a>

Частые вопросы¶

Нужно ли что-то настраивать в Telegram кроме токена?

Нет. Достаточно токена из @BotFather. Остальное Roistat делает автоматически.

Что если пользователь пишет в бота напрямую, а не через сайт?

Сделка всё равно создаётся, но без номера визита (roistat_visit).