Документация по функциям платформы Telegram

TelegramAdapter — это адаптер, построенный на основе Telegram Bot API, поддерживающий различные типы сообщений и обработку событий.

Информация о документации

• Соответствующая версия модуля: 4.2.0
• Поддерживается: ErisPulse

Основная информация

• Краткое описание платформы: Telegram - это мультиплатформенный мессенджер
• Имя адаптера: TelegramAdapter
• Поддерживаемый протокол/API-версия: Telegram Bot API
• Сопоставление типов сессий: private → при отправке используется user, group/supergroup → group, channel → channel

Стандартные действия API (DSL API)

Адаптер сопоставляет стандартные действия OB12 с Telegram Bot API и стандартизирует поле data:

Расширенные действия: get_group_admin_list(group_id) (список администраторов), get_chat_member_count(chat_id) (количество участников).

from ErisPulse import sdk
telegram = sdk.adapter.get("telegram")

result = await telegram.Api.get_self_info()
result = await telegram.Api.get_group_info(group_id=-100123)
result = await telegram.Api.get_group_admin_list(-100123)
await telegram.Api.delete_message(message_id=55)   # chat_id автоматически заполняется
result = await telegram.Api.Using("main").get_self_info()

Telegram Bot API не имеет интерфейса для получения списка друзей/групп, get_friend_list/get_group_list возвращает errorcode=10002.

Операции с запросами (Request DSL)

Обработка запросов на добавление в группу (событие chat_join_request), на основе approveChatJoinRequest / declineChatJoinRequest:

from ErisPulse.Core.Event import request

@request.on_request()
async def handle_join_request(event):
    if event.get("platform") != "telegram":
        return
    # event["request_id"] - это синтетический идентификатор (tjr_{chat_id}_{user_id}_{date})
    if event.get("user_nickname"):
        await event.approve()          # Подтвердить
    # await event.reject()             # Отклонить

# Вызов вручную (требуется предварительное получение соответствующего события запроса для регистрации контекста)
await telegram.Request(event["request_id"]).accept()
await telegram.Request(event["request_id"]).reject()
await telegram.Request(event["request_id"]).Using("main").accept()

Типы поддерживаемых сообщений

Все методы отправки реализованы с использованием цепочечного синтаксиса, например:

from ErisPulse.Core import adapter
telegram = adapter.get("telegram")

await telegram.Send.To("user", user_id).Text("Hello World!")

Основные методы отправки

Методы отправки медиа

Все методы медиа поддерживают два типа входных данных: bytes (загрузка) и str (file_id / URL):

Методы управления сообщениями

Отправка сообщений в исходном виде

• .Raw_ob12(message: List[Dict]): Отправка сообщения в формате OneBot12
• .Raw_json(json_str: str): Отправка сообщения в формате JSON

Методы цепочечного изменения

Примеры отправки сообщений

# Базовая отправка текста
await telegram.Send.To("user", user_id).Text("Hello World!")

# Сообщение с инлайн-клавиатурой
from ErisPulse import sdk
telegram = sdk.adapter.get("telegram")
keyboard = [
    [{"text": "Кнопка 1", "callback_data": "btn1"}, {"text": "Кнопка 2", "callback_data": "btn2"}],
    [{"text": "Перейти на сайт", "url": "https://example.com"}],
]
await telegram.Send.To("group", group_id).Keyboard(keyboard).Text("Выберите:")

# Отправка медиа (по URL)
await telegram.Send.To("group", group_id).Image("https://example.com/image.jpg", caption="Изображение")

# Упоминание пользователя
await telegram.Send.To("group", group_id).At("6117725680").Text("Привет!")

# Ответ + защита контента
await telegram.Send.To("group", group_id).Reply("12345").ProtectContent().Text("Секретное сообщение")

# Отправка в тихом режиме
await telegram.Send.To("group", group_id).Silent().Text("Тихое уведомление")

# Ответ на запрос обратной связи
await telegram.Send.AnswerCallback(callback_query_id, text="Обработано", show_alert=False)

# Сложное сообщение в формате OneBot12
ob12_message = [
    {"type": "text", "data": {"text": "Сложное сообщение: "}},
    {"type": "mention", "data": {"user_id": "6117725680", "user_name": "Имя пользователя"}},
    {"type": "reply", "data": {"message_id": "12345"}},
    {"type": "image", "data": {"file": "https://http.cat/200"}}
]
await telegram.Send.To("group", group_id).Raw_ob12(ob12_message)

# Отправка стикера
await telegram.Send.To("user", user_id).Sticker("CAACAgIAAxkBAA...")  # file_id

# Отправка геолокации
await telegram.Send.To("user", user_id).Location(39.9042, 116.4074)

Типы специфических событий

Преобразование событий Telegram следует стандарту OneBot12, а также предоставляет расширения платформы с префиксом telegram_.

Сопоставление detail_type для событий сообщений

Специфические типы событий

Стандартные типы сообщений

Используемый формат сообщений OneBot12:

Расширенные сообщения платформы

Расширенные сообщения с префиксом telegram_:

Примеры событий

Сообщение в группе (с упоминанием)

{
  "type": "message",
  "detail_type": "group",
  "platform": "telegram",
  "user_id": "6117725680",
  "user_nickname": "WSu2059",
  "group_id": "-1002850921906",
  "message_id": "172",
  "message": [
    {"type": "text", "data": {"text": "/it.echo "}},
    {"type": "mention", "data": {"user_id": "", "user_name": "@nm123_91178"}}
  ],
  "alt_message": "/it.echo @nm123_91178",
  "telegram_chat": {
    "id": -1002850921906,
    "title": "ErisPulse",
    "username": "erispulse",
    "type": "supergroup"
  }
}

Событие запроса обратной связи

{
  "type": "notice",
  "detail_type": "telegram_callback_query",
  "user_id": "123456",
  "user_nickname": "YingXinche",
  "telegram_callback_id": "cb_123",
  "telegram_callback_data": "callback_data",
  "message_id": "msg_456"
}

Событие встроенного запроса

{
  "type": "request",
  "detail_type": "telegram_inline_query",
  "user_id": "789012",
  "user_nickname": "YingXinche",
  "telegram_query_id": "iq_789",
  "telegram_query_text": "search_text",
  "telegram_query_offset": "0"
}

Сообщение с встроенной клавиатурой

{
  "type": "message",
  "detail_type": "group",
  "message": [
    {"type": "text", "data": {"text": "Выберите: "}},
    {
      "type": "telegram_inline_keyboard",
      "data": {
        "inline_keyboard": [
          [{"text": "Кнопка1", "callback_data": "btn1"}],
          [{"text": "Перейти", "url": "https://example.com"}]
        ]
      }
    }
  ]
}

Event Mixin расширения методов

Адаптер зарегистрировал следующие методы, специфичные для платформы, доступные только при platform == "telegram":

Связанные с сообщениями

Связанные с обратными запросами

Извлечение данных сегментов сообщений

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

from ErisPulse.Core.Event import message, notice

@message.on_message()
async def handle_message(event):
    if event.get("platform") != "telegram":
        return

    # Свойства сообщения
    if event.is_bot_message():
        return  # Пропустить сообщения от бота

    if event.is_edited_message():
        print("Это отредактированное сообщение")

    # Информация о чате
    title = event.get_chat_title()
    username = event.get_chat_username()

    # Источник пересылки
    forward = event.get_forward_from()

    # Данные сегментов сообщения
    sticker = event.get_sticker_info()
    contact = event.get_contact_info()
    location = event.get_location()
    keyboard = event.get_inline_keyboard()

    # Тема
    if event.is_topic_message():
        topic_id = event.get_topic_id()

@notice.on_notice()
async def handle_notice(event):
    if event.get("platform") != "telegram":
        return

    if event.get("detail_type") == "telegram_callback_query":
        callback_data = event.get_callback_data()
        callback_id = event.get_callback_id()

        # Ответить на обратный запрос
        telegram = sdk.adapter.get("telegram")
        await telegram.Send.AnswerCallback(callback_id, text="Нажато")

        # Ответить на сообщение
        await event.reply(f"Вы нажали: {callback_data}")

Описание расширенных полей

• Все специфические поля идентифицируются с префиксом telegram_
• Исходные данные сохраняются в поле telegram_raw
• Тип исходного события сохраняется в поле telegram_raw_type
• Сообщения в каналах используют detail_type="channel"
• Личные сообщения используют detail_type="private" (при отправке необходимо преобразовать в user)
• Сообщения в темах содержат поле thread_id
• Упоминания с помощью @ используют стандартный тип сообщения упоминания (type: "mention"), текст не содержит @имени пользователя

Параметры конфигурации

Адаптер Telegram поддерживает конфигурацию нескольких аккаунтов:

Пример конфигурации

[Telegram_Adapter.accounts.default]
token = "ВАШ_ТОКЕН_БОТА"
enabled = true

[Telegram_Adapter.accounts.bot2]
token = "ДРУГОЙ_ТОКЕН_БОТА"
enabled = true

Режимы работы

Адаптер Telegram поддерживает только режим опроса (Polling), режим вебхуков (Webhook) был удален.

Конфигурация прокси

Если необходимо подключиться к Telegram API через прокси, используйте системные прокси-настройки (переменные окружения ALL_PROXY / HTTPS_PROXY).

Перенос старой конфигурации

Старый формат конфигурации с одним токеном будет автоматически поддерживаться:

# Старый формат (все еще может использоваться, но рекомендуется перейти на новый)
[Telegram_Adapter]
token = "ВАШ_ТОКЕН_БОТА"

Рекомендуется перейти на новый формат:

[Telegram_Adapter.accounts.default]
token = "ВАШ_ТОКЕН_БОТА"
enabled = true