Telegram Client API: Триггеры И Действия

Этот документ описывает отдельный продуктовый слой для работы через Telegram Client API, а не через обычный Bot API.

Client API подходит для сценариев, где система должна не только отвечать пользователю как бот, но и читать историю чатов, наблюдать за событиями, анализировать участников, собирать сообщения, выполнять синхронизацию и строить парсер поверх реальных чатов, групп и каналов.

Чем Client API Отличается От Bot API

Bot API лучше подходит для:

• ответа пользователям от имени бота
• кнопок, меню и сценариев диалога
• простых webhook-driven интеграций

Client API лучше подходит для:

• чтения истории чатов
• мониторинга групп и каналов
• извлечения участников
• анализа сообщений и медиа
• парсинга переписок
• синхронизации состояния чата

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

• Bot API сценарии
• Client API сценарии
• гибридные сценарии, где чтение идёт через Client API, а действия ответа или уведомления через Bot API

Продуктовые Категории

Для Client API узлы удобно группировать так:

• События
• Чаты
• Сообщения
• Участники
• Парсинг
• Синхронизация
• Аналитика
• Интеграции
• Модерация
• Управление ботом

Возможные Триггеры

Базовые Триггеры

• Ручной запуск
• Webhook
• По расписанию
• По таймеру
• При синхронизации чата
• При обновлении индекса

Триггеры По Новым Сообщениям

• Новое сообщение в чате
• Новое сообщение в личке
• Новое сообщение в группе
• Новое сообщение в супергруппе
• Новое сообщение в канале
• Новое исходящее сообщение
• Новое входящее сообщение

Триггеры По Типу Контента

• Новое текстовое сообщение
• Новое сообщение с фото
• Новое сообщение с видео
• Новое сообщение с документом
• Новое сообщение с голосовым
• Новое сообщение с аудио
• Новое сообщение с GIF
• Новое сообщение со ссылкой
• Новое сообщение с упоминанием
• Новое пересланное сообщение
• Новое сообщение с подписью

Триггеры По Изменениям Сообщений

• Сообщение отредактировано
• Сообщение удалено
• Сообщение закреплено
• Сообщение откреплено
• Появилась реакция
• Изменился счётчик реакций
• Появился ответ на сообщение

Триггеры По Событиям Участников

• Новый участник
• Участник вышел
• Участник был удалён
• Изменился статус участника
• Пользователь стал администратором
• Пользователь перестал быть администратором
• Изменились права участника

Триггеры По Изменениям Чата

• Изменилось название чата
• Изменилась аватарка чата
• Изменилась информация о чате
• Изменился закреп
• Изменился список администраторов

Триггеры По Состоянию И Управлению Ботом

• Бот запущен
• Бот остановлен
• Бот перезапущен
• Бот подключен
• Бот отключен
• Сессия авторизована
• Сессия истекла
• Ошибка авторизации
• Ошибка подключения
• Webhook установлен
• Webhook удалён
• Polling запущен
• Polling остановлен
• Получена команда управления

Возможные Действия

Действия С Чатом

• Получить информацию о чате
• Получить список диалогов
• Получить тип чата
• Получить ссылку / username чата
• Считать метаданные чата
• Синхронизировать чат
• Сравнить состояние чата

Действия С Сообщениями

• Получить последние N сообщений
• Получить сообщения за период
• Получить историю сообщений
• Получить сообщение по ID
• Получить ответы на сообщение
• Получить тред / обсуждение
• Получить пересланные сообщения
• Получить закреплённые сообщения
• Получить сообщения пользователя
• Получить сообщения с медиа
• Получить сообщения со ссылками
• Получить сообщения с упоминаниями

Действия С Участниками

• Получить участников группы
• Получить администраторов
• Получить профиль участника
• Получить статус участника
• Проверить наличие пользователя в чате
• Получить участников по роли
• Синхронизировать участников чата
• Сравнить состав группы
• Определить новых участников
• Определить выбывших участников

Примечание: Определить выбывших участников обычно означает сравнение текущего состава с предыдущим сохранённым снимком, а не мгновенное получение "всех ушедших" из Telegram по одному запросу.

Действия Парсинга Текста

• Извлечь сущности из текста
• Извлечь ссылки
• Извлечь email
• Извлечь телефон
• Извлечь username / mention
• Извлечь хэштеги
• Извлечь дату и время
• Извлечь цену / сумму
• Извлечь адрес
• Извлечь код / номер / идентификатор
• Выделить ключевые слова
• Определить язык
• Классифицировать сообщение
• Определить тему
• Определить тональность
• Определить спам / рекламу

Действия Нормализации И Подготовки

• Очистить текст
• Нормализовать текст
• Удалить служебные символы
• Привести текст к единому виду
• Убрать дубликаты
• Разбить текст на блоки
• Склеить сообщения
• Обрезать до лимита
• Преобразовать форматирование в plain text

Действия С Медиа

• Получить file_id / media reference
• Считать метаданные файла
• Определить MIME-тип
• Скачать вложение
• Извлечь подпись к медиа
• Распознать текст из изображения
• Распознать текст из документа
• Транскрибировать голосовое
• Извлечь превью

Действия Аналитики

• Подсчитать сообщения по пользователям
• Найти активных участников
• Найти неактивных участников
• Построить топ авторов
• Подсчитать сообщения за период
• Построить статистику по типам контента
• Собрать популярные ссылки
• Собрать популярные темы
• Суммаризировать переписку

Действия Синхронизации

• Синхронизировать историю сообщений
• Синхронизировать только новые сообщения
• Синхронизировать медиа
• Обновить локальный индекс чата
• Сохранить снимок состава группы
• Сравнить текущий и прошлый снимок
• Восстановить пропущенные сообщения
• Пересчитать агрегаты

Интеграции И Хранение

• Записать в базу
• Записать в Google Sheets
• Сохранить JSON
• Сохранить сырой payload
• Отправить в Webhook
• Отправить в CRM
• Создать лид / заявку
• Отправить уведомление админу
• Поставить задачу во внешнюю систему

Действия Управления И Модерации

• Отправить сообщение
• Ответить на сообщение
• Редактировать сообщение
• Удалить сообщение
• Переслать сообщение
• Закрепить сообщение
• Открепить сообщение
• Поставить реакцию
• Ограничить пользователя
• Снять ограничения
• Заблокировать пользователя
• Разблокировать пользователя
• Удалить участника
• Назначить администратором
• Снять администратора

Действия Управления Ботом

• Запустить бота
• Остановить бота
• Перезапустить бота
• Включить обработку обновлений
• Отключить обработку обновлений
• Переключить режим polling / webhook
• Установить webhook
• Удалить webhook
• Проверить статус webhook
• Проверить статус бота
• Проверить статус клиентской сессии
• Авторизовать сессию
• Переавторизовать сессию
• Обновить токен / ключ
• Выбрать рабочий аккаунт
• Сменить рабочий чат / источник
• Загрузить конфиг бота
• Обновить конфиг бота
• Включить сценарий
• Отключить сценарий
• Перезапустить сценарий
• Остановить все сценарии
• Проверить healthcheck
• Очистить очередь обновлений
• Логировать состояние бота

Разделение На Реалистичные И Осторожные Возможности

Обычно Реалистично

• Получить историю сообщений
• Получить последние N сообщений
• Получить участников группы
• Получить администраторов
• Получить профиль участника
• Синхронизировать участников чата
• Сравнить состав группы
• Распознать текст из изображения
• Транскрибировать голосовое
• Записать в базу
• Отправить в Webhook

Требует Осторожной Формулировки

• Получить всех пользователей группы
• Получить всех ушедших участников
• Получить всю историю без ограничений
• Мгновенно синхронизировать большой канал
• Гарантированно извлечь все медиа и весь контент

Такие формулировки лучше заменять на более точные:

• Получить доступных участников
• Определить выбывших участников по сравнению со снимком
• Синхронизировать доступную историю
• Загрузить последние сообщения

Рекомендуемый MVP Для Product-слоя Client API

Триггеры

• Ручной запуск
• По расписанию
• Новое сообщение в чате
• Новое сообщение с медиа
• Сообщение отредактировано
• Новый участник

Действия

• Получить информацию о чате
• Получить последние N сообщений
• Получить историю сообщений
• Получить участников группы
• Получить администраторов
• Извлечь сущности из текста
• Классифицировать сообщение
• Распознать текст из изображения
• Транскрибировать голосовое
• Синхронизировать участников чата
• Сравнить состав группы
• Записать в базу
• Отправить в Webhook
• Отправить уведомление админу
• Проверить статус бота
• Переключить режим polling / webhook

Рекомендуемый Extended Набор

Триггеры

• Новое сообщение в канале
• Новое пересланное сообщение
• Сообщение удалено
• Появилась реакция
• Участник вышел
• Изменился статус участника
• Изменилась информация о чате

Действия

• Получить тред / обсуждение
• Получить сообщения пользователя
• Получить сообщения со ссылками
• Получить сообщения с упоминаниями
• Определить язык
• Определить тему
• Определить тональность
• Определить спам / рекламу
• Суммаризировать переписку
• Подсчитать сообщения по пользователям
• Найти активных участников
• Сохранить снимок состава группы
• Синхронизировать медиа
• Сохранить JSON
• Поставить задачу во внешнюю систему
• Перезапустить бота
• Включить сценарий
• Отключить сценарий

Рекомендация По UI

В интерфейсе лучше не смешивать узлы Client API и Bot API в одну плоскую кучу.

Практичный вариант:

• отдельная категория Telegram Bot API
• отдельная категория Telegram Client API
• отдельная категория Парсинг и аналитика

Так пользователю будет понятнее, что:

• один набор узлов работает как бот
• другой набор читает и анализирует чаты
• а parser-слой может использовать данные из обоих источников