Инструкция

🔹 Введение

Telesend — это инструмент для создания кастомных рассылок в Telegram-ботах, который:

• Позволяет отправлять сообщения не только всем подряд, но и определённым сегментам пользователей.
• Работает через Telegram-бота с интеграцией SDK по API.

🟦 Шаг 1. Создание проекта

1. Перейдите на сайт Telesend и зарегистрируйтесь или войдите в аккаунт.
2. Нажмите кнопку “Создать проект”.
3. Укажите:
   • Название проекта (например: “Мой обучающий бот”)

🟦 Шаг 2. Подключение SDK к проекту

🟦 Шаг 2.1. Установка SDK и получения API ключа

1. Найдите кнопку “Редактировать” и скопируйте ваш API ключ в открытом проекте
2. Открываем консоль и переходим в директорию с проектом
3. Установка SDK: Пишем команду ниже в консоли директории с проектом

NodeJS

npm

npm i telesend-server-sdk

pnpm

pnpm add telesend-server-sdk

yarn

yarn add telesend-server-sdk

Python

pip install telesend-server-sdk

4. Инициализируйте SDK:

NodeJS

import { TelesendClient, composeMessage } from 'telesend-server-sdk';

const client = new TelesendClient({
  apiKey: 'your-api-key',          // Ваш API ключ
  callbackHookSendMessage: async () => {
    // TODO: Расскажем позднее
  }
});

Python

from telesend.client import TelesendClient, compose_message
from telesend.types import TelesendClientConfig, MessageQueueItem

# Функция для отправки сообщения в Telegram
async def send_telegram_message(message_data: MessageQueueItem):
    print('TODO: Расскажем позднее')

# Создаем конфигурацию клиента
config = TelesendClientConfig(
    api_key="ваш_api_ключ",
    callback_hook_send_message=send_telegram_message
)

# Инициализируем клиент
client = TelesendClient(config)

🟦 Шаг 2.2. Идентификация пользователей

1. Идентификация новых пользователей Если в вашем сервисе появляется новый пользователь или нужно обновить его данные (например, изменился язык или имя), система Telesend должна об этом узнать. Для этого в вашем коде используется команда client.identify().

NodeJS

await client.identify({
  id: '123456789',
  username: 'username',
  firstName: 'Имя',
  lastName: 'Фамилия',
  isPremium: false
});

Python

from telesend.types import UserDetails

# Идентификация пользователя
client.identify(UserDetails(
    id="123456789",
    username="username",
    first_name="Имя",
    last_name="Фамилия",
    is_premium=False
))

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

1. Вы передаете в client.identify() информацию о пользователе:
   • Идентификатор (уникальный номер/логин из вашей системы)
   • Имя, контакты, другие данные (например, подписки)
2. Telesend запоминает эти данные и связывает их с вашим ботом.

Зачем это нужно:

• Чтобы отправлять сообщения конкретному человеку.
• Чтобы обновлять информацию, если пользователь сменил данные.

Подробнее: Документация по идентификации

2. Миграция пользователей

   Telesend не знает про пользователей которые проявили активность до интеграции сервиса, поэтому существует механизм миграции пользователей через выгрузку пользователей в CSV-файлы.

   Формат CSV:

   — Это таблица, где каждая строка — это данные одного пользователя, а колонки — поля (например, имя, ID и т.д.).

   — Обязательная колонка: telegramId (уникальный ID пользователя в Telegram).

   — Дополнительные колонки: username, firstName, lastName, isPremium, createdAt.

   Пример CSV-файла:

telegramId,username,firstName,lastName,isPremium,createdAt
1234567890,testuser,Test,User,true,2025-06-01
1234567891,testuser2,Test,User2,false,2025-06-02

Пояснение:

• isPremium — указывает, есть ли у пользователя подписка Telegram Premium (true/false).
• createdAt — дата регистрации пользователя в вашей системе (в формате ГГГГ-ММ-ДД).

Что можно делать с CSV:

• Импорт: Загрузить файл в Telesend, чтобы добавить или обновить данные пользователей.
• Экспорт: Скачать CSV-файл с текущими данными пользователей для резервного копирования или анализа.

🟦 Шаг 2.3. Механизм рассылки (Интеграция с Telegram)

Чтобы ваш бот мог рассылать сообщения через Telegram, нужно добавить в код специальную инструкцию — функцию callbackHookSendMessage.

Как это сделать:

1. В вашем коде есть объект (набор настроек) для работы с Telesend — его называют «клиент».
2. В этот объект нужно добавить метод callbackHookSendMessage, который будет отправлять сообщения через Telegram.

Что это значит:

• Telesend не отправляет сообщения сам. Он передает их вашему боту, а бот — пользователям.
• callbackHookSendMessage — это «мост» между TeleSend и Telegram. В нем вы прописываете, как именно бот должен отправлять сообщения (например, через API Telegram).

Пример реализации колбэка для отправки сообщений:

NodeJS

async function sendTelegramMessage(payload: MessageQueueItem) {
  const { type, body } = composeMessage(payload)

  const response = await fetch(`https://api.telegram.org/bot${BOT_TOKEN}/${type}`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(body)
  })

  if (!response.ok) {
    const errorData = await response.json()
    throw new Error(JSON.stringify(errorData))
  }
}

Python

import requests
import json
from telesend.client import TelesendClient, compose_message
from telesend.types import TelesendClientConfig, MessageQueueItem

# Функция для отправки сообщения в Telegram
def send_telegram_message(message_data: MessageQueueItem):
    message_format = compose_message(message_data)

    method = message_format["type"]
    body = message_format["body"]

    response = requests.post(
        f"https://api.telegram.org/bot{BOT_TOKEN}/{method}",
        json=body
    )

    if not response.ok:
        error_data = response.json()
        raise Exception(json.dumps(error_data))

🟦 Шаг 3. Базовая рассылка на всех пользователей

Если вы хотите быстро сделать рассылку без настройки сегментов:

1. Перейдите в проект.
2. Нажмите “Создать рассылку”.
3. Укажите:
   • Заголовок (например: “Добро пожаловать!”)
   • Текст сообщения
   • (По желанию) Добавьте кнопки
4. Настройте время отправки:
   • Сразу (Также можно указать время отправки рассылки, задать её повторяемость или установить триггер, например, для отправки новым пользователям.)
5. Нажмите “Запустить рассылку”.

✅ Готово! Сообщение получат все пользователи, у которых активен бот.

🟦 Шаг 4. Сегментация пользователей

Если вам нужно более точное таргетирование:

1. Перейдите в проект.
2. Нажмите “Создать рассылку”.
3. Укажите:
   • Заголовок (например: “Сегментация пользователей!”)
   • Текст сообщения
   • (По желанию) Добавьте кнопки
   • Название (например: “Хорошо”)
   • Ссылка (например: “https://t.me/telesend_bot”)
4. Настройте время отправки:
   • Сразу (Также можно указать время отправки рассылки, задать её повторяемость или установить триггер, например, для отправки новым пользователям.)
5. Напишите в поле “настройка фильтров”:

Отправь рассылку всем пользователям с first name “Maksim” , у которых нету telegram premium

6. Нажмите “Запустить рассылку”.

✅ Готово! Сообщение получат все пользователи которые вошли в сегмент и у которых активен бот.

🟦 Шаг 4.1 Сегментация пользователей по поведению через кастомные аналитические события

🧩 Пункт 1: Создание аналитического события

1. Перейдите на сайт: https://app.telesend.io/
2. Откройте ваш проект.
3. Нажмите справа на вкладку “Аналитические события”.
4. Нажмите кнопку “Создать событие”.
5. Заполните нужное поле - “Имя события”
6. Нажмите кнопку “Создать”.
7. Найдите созданное событие в списке.
8. Нажмите “Редактировать” напротив события.
9. Заполните описание события.
10. Нажмите кнопку “Сохранить”.

Зачем это нужно?

Это нужно для использования этого события в фильтрах, а также автоматического генерирования фильтров (сегментов пользователей) с помощью ИИ, описывая все обычным языком.

Когда вы собираете данные о пользователях (через импорт CSV или события track), Telesend может автоматически создавать фильтры — это “умные” группы пользователей, объединённые по общим признакам. А с помощью ИИ это работает ещё проще — вы описываете, кого хотите найти, обычными словами.

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

1. Фильтры = группы пользователей по правилам

Примеры правил:

• «Пользователи, которые нажали кнопку “Купить”» → фильтр по событию button_click
• «Подписчики с Telegram Premium» → фильтр по полю isPremium: true
• «Активные за последний месяц» → фильтр по дате createdAt

2. Автоматическое создание фильтров через ИИ

Просто опишите, кого ищете:

«Покажи пользователей из Москвы, которые открывали страницу /sale и не покупали»

ИИ Telesend:

• Поймёт запрос на обычном языке.
• Проверит ваши данные (события, поля из CSV).
• Создаст фильтр и группу пользователей.

---

📬 Пункт 2: Отправка события через track()

Чтобы ваш бот мог присылать анилитические события вам нужно вызывать у клиента соответствующий метод track .

Что нужно передать в метод track():

• ID пользователя в Telegram — уникальный номер, который Telegram присваивает каждому пользователю.
• Название события — придумайте короткое название, например, button_click (нажатие кнопки).
• Данные события — дополнительная информация о действии.

Обязательные данные:

• startParameter — параметр, с которого началось взаимодействие (если его нет, укажите пустую строку '').
• params — любые данные в формате «ключ: значение» (например, buttonId: 'start').

Необязательные данные (можно не указывать):

• path — страница, где произошло событие (например, /start).
• language — язык пользователя (например, ru).
• device — устройство пользователя (например, mobile).

Пример:

NodeJS

await client.track('123456789', 'button_click', {
  startParameter: '',
  path: '/start',
  params: {
    buttonId: 'start',
  },
  language: 'ru',
  device: 'mobile',
})

Python

from telesend.types import Event

# Отправка аналитического события
client.track(
    "123456789",
    "button_click",
    Event(
        start_parameter="",
        path="/start",
        params={
            "buttonId": "start"
        },
        language="ru",
        device="mobile"
    )
)

Пояснение:

• 123456789 — ID пользователя в Telegram.
• button_click — название события.
• params: { buttonId: 'start' } — какая именно кнопка была нажата.