Server SDK

Установка

Требования

Для использования SDK Telesend вам понадобится:

• Node.js версии 18 или выше
• Проект на JavaScript или TypeScript
• API ключ

Установка пакета

npm

npm i telesend-server-sdk

pnpm

pnpm add telesend-server-sdk

yarn

yarn add telesend-server-sdk

Получение API ключа

API ключ необходим для аутентификации вашего приложения при взаимодействии с Telesend. Для получения API ключа:

1. Войдите в свой аккаунт на сайте Telesend
2. Перейдите к своему проекту:
   • Если у вас уже есть проект - выберите его в личном кабинете.
   • Если у вас еще нет проекта - создайте новый:
     1. Нажмите на кнопку “Создать проект”.
     2. Заполните все поля и нажмите на кнопку “Создать”.
3. Найдите кнопку “Редактировать” и скопируйте ваш API ключ

Храните ваш API ключ в безопасном месте и не публикуйте его в открытом доступе.

Инициализация клиента

Для начала работы с SDK необходимо создать экземпляр класса TelesendClient:

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

const client = new TelesendClient({
  apiKey: 'your-api-key',          // Ваш API ключ
  // Обязательный колбэк для отправки сообщений
  callbackHookSendMessage: async (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));
    }
  }
});

Отправка аналитических событий

Идентификация пользователя

Прежде чем отправлять аналитические события, рекомендуется идентифицировать пользователя:

// Идентификация пользователя
await client.identify({
  id: '123456789',
  username: 'username',
  firstName: 'Имя',
  lastName: 'Фамилия',
  isPremium: false
});

Подробнее о методе client.identify

Отправка события

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

Подробнее о методе client.track

Обработка событий

SDK Telesend использует систему событий для отслеживания состояния подключения и отправки сообщений:

// Отслеживание отправки сообщений
client.on('messageSent', (userId: string, success: boolean) => {
  if (success) {
    console.log(`Сообщение успешно отправлено пользователю ${userId}`);
  } else {
    console.log(`Ошибка при отправке сообщения пользователю ${userId}`);
  }
});

// Отслеживание ошибок
client.on('error', (error: Error) => {
  console.error('Произошла ошибка:', error.message);
});

Примеры использования

Отправка аналитического события

Пример отправки события о нажатии на кнопку:

await client.identify({
    id: '123456789',
    username: 'username',
    firstName: 'Имя',
    lastName: 'Фамилия',
    isPremium: true
})
await client.track('123456789', 'button_click', {
  startParameter: '',
  path: '/start',
  params: {
      buttonId: 'start_button',
      buttonText: 'Начать'
  },
  language: 'ru',
  device: 'mobile'
});

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

SDK Telesend не взаимодействует напрямую с Telegram API. Вместо этого он использует переданную в конструкторе функцию callbackHookSendMessage для отправки сообщений. Это позволяет разработчикам иметь полный контроль над процессом отправки сообщений.

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

const sendTelegramMessage = async (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));
  }
};

API и типы данных

Класс TelesendClient

Основной класс для работы с SDK Telesend.

Конструктор

new TelesendClient(config: TelesendClientConfig)

interface TelesendClientConfig {
  apiKey: string;               // API ключ проекта
  callbackHookSendMessage: (payload: MessageQueueItem) => Promise<void>; // Функция для отправки сообщений
}

Методы

track

Отправляет аналитическое событие на сервер.

track(userId: string | number, type: string, payload: Event): Promise<void>

identify

Идентифицирует пользователя.

identify(userDetails: UserDetails): Promise<void>

isConnected

Проверяет, установлено ли соединение с сервисом.

isConnected(): boolean

close

Закрывает соединение с сервисом при завершении работы с SDK.

close(): Promise<void>

События

messageSent

Событие вызывается при отправке сообщения пользователю.

on('messageSent', (userId: string, success: boolean) => void)

error

Событие вызывается при возникновении ошибки.

on('error', (error: Error) => void)

Вспомогательные функции

composeMessage

Формирует данные для запроса к Telegram API на основе сообщения.

composeMessage(messageData: MessageQueueItem): { type: string; body: any }

Типы данных

UserDetails и Event

interface UserDetails {
  id: string;           // Уникальный идентификатор пользователя
  username?: string;    // Имя пользователя в Telegram (без @)
  firstName?: string;   // Имя пользователя
  lastName?: string;    // Фамилия пользователя
  isPremium?: boolean;  // Статус премиум-подписки пользователя
  timeZone?: number;    // Часовой пояс пользователя (от -12 до +12)
}

interface Event {
  startParameter: string; // Начальный параметр события
  path: string;           // Путь, на котором произошло событие
  params: { [key: string]: unknown }; // Дополнительные параметры события
  language?: string;      // Язык пользователя
  device?: string;        // Устройство пользователя
}

TelegramMessage

Типы сообщений для отправки через Telegram API.

// Базовые типы
interface Button {
  text: string;        // Текст кнопки
  url?: string;        // URL для перехода
  callback_data?: string; // Данные для обратного вызова
}

interface MediaItem {
  type: 'audio' | 'document' | 'photo' | 'video'; // Тип медиа
  url: string;        // URL медиафайла
  caption?: string;   // Подпись к медиафайлу
}

interface BaseMessage {
  disable_notification: boolean; // Отключить уведомление
  parse_mode?: string;          // Режим парсинга (Markdown, HTML)
}

// Типы сообщений
type TelegramMessage =
  | MessageText
  | MessageMediaGroup
  | MessagePhoto
  | MessageVideoNote
  | MessageVoice
  | MessagePoll;

// Текстовое сообщение
interface MessageText extends BaseMessage {
  type: 'message';
  text: string;       // Текст сообщения
  buttons?: Button[]; // Кнопки
}

// Группа медиафайлов
interface MessageMediaGroup extends BaseMessage {
  type: 'mediaGroup';
  items: MediaItem[]; // Медиафайлы
}

// Фото
interface MessagePhoto extends BaseMessage {
  type: 'photo';
  photo: string;      // URL фото
  caption?: string;   // Подпись к фото
  buttons?: Button[]; // Кнопки
}

// Видео-заметка
interface MessageVideoNote extends BaseMessage {
  type: 'videoNote';
  video_note: string; // URL видео-заметки
  buttons?: Button[]; // Кнопки
}

// Голосовое сообщение
interface MessageVoice extends BaseMessage {
  type: 'voice';
  voice: string;      // URL голосового сообщения
  caption?: string;   // Подпись
  buttons?: Button[]; // Кнопки
}

// Опрос
interface MessagePoll extends BaseMessage {
  type: 'poll';
  question: string;   // Вопрос
  options: string[];  // Варианты ответов
  is_anonymous: boolean; // Анонимный опрос
  allows_multiple_answers: boolean; // Множественный выбор
}

Прочие типы

// Данные пользователя
interface UserData {
  tg: string | number; // Telegram ID пользователя
}

// Элемент очереди сообщений
interface MessageQueueItem {
  userId: string;           // ID пользователя
  message: TelegramMessage; // Сообщение
}