Telegram Platform Features Documentation

TelegramAdapter is an adapter built on top of the Telegram Bot API, supporting various message types and event handling.

Documentation Information

• Corresponding Module Version: 4.2.0
• Maintainer: ErisPulse

Basic Information

• Platform Introduction: Telegram is a cross-platform instant messaging software
• Adapter Name: TelegramAdapter
• Supported Protocol/API Version: Telegram Bot API
• Session Type Mapping: private → use user when sending, group/supergroup → group, channel → channel

Standard API Actions (API DSL)

Adapters map OB12 standard actions to the Telegram Bot API and standardize the data field:

Extended actions: get_group_admin_list(group_id) (admin list), get_chat_member_count(chat_id) (member count).

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 is automatically completed
result = await telegram.Api.Using("main").get_self_info()

The Telegram Bot API does not provide an interface to retrieve friend/group lists; get_friend_list/get_group_list return errorcode=10002.

Request Operations (Request DSL)

Handle group join requests (chat_join_request event), based on 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"] is a synthetic identifier (tjr_{chat_id}_{user_id}_{date})
    if event.get("user_nickname"):
        await event.approve()          # Approve
    # await event.reject()             # Reject

# Manual invocation (requires prior receipt of the corresponding request event to register context)
await telegram.Request(event["request_id"]).accept()
await telegram.Request(event["request_id"]).reject()
await telegram.Request(event["request_id"]).Using("main").accept()

Supported Message Sending Types

All sending methods are implemented using a fluent (chained) syntax, for example:

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

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

Basic Sending Methods

Media Sending Methods

All media methods support both bytes (upload) and str (file_id / URL) input:

Message Management Methods

Raw Message Sending

• .Raw_ob12(message: List[Dict]): Send a OneBot12 standard format message
• .Raw_json(json_str: str): Send a raw JSON format message

Fluent Modifier Methods

Sending Examples

# Basic text sending
await telegram.Send.To("user", user_id).Text("Hello World!")

# Message with inline keyboard
from ErisPulse import sdk
telegram = sdk.adapter.get("telegram")
keyboard = [
    [{"text": "Button 1", "callback_data": "btn1"}, {"text": "Button 2", "callback_data": "btn2"}],
    [{"text": "Visit Website", "url": "https://example.com"}],
]
await telegram.Send.To("group", group_id).Keyboard(keyboard).Text("Please select:")

# Media sending (using URL)
await telegram.Send.To("group", group_id).Image("https://example.com/image.jpg", caption="Image")

# @ user
await telegram.Send.To("group", group_id).At("6117725680").Text("Hello!")

# Reply + protected content
await telegram.Send.To("group", group_id).Reply("12345").ProtectContent().Text("Confidential message")

# Silent sending
await telegram.Send.To("group", group_id).Silent().Text("Silent notification")

# Answer callback query
await telegram.Send.AnswerCallback(callback_query_id, text="Processed", show_alert=False)

# OneBot12 composite message
ob12_message = [
    {"type": "text", "data": {"text": "Complex message:"}},
    {"type": "mention", "data": {"user_id": "6117725680", "user_name": "Username"}},
    {"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)

# Send sticker
await telegram.Send.To("user", user_id).Sticker("CAACAgIAAxkBAA...")  # file_id

# Send location
await telegram.Send.To("user", user_id).Location(39.9042, 116.4074)

Unique Event Types

Telegram event conversion follows the OneBot12 standard, while providing platform extensions through the telegram_ prefix.

Message Event detail_type Mapping

Unique Event Types

Standard Message Segment Types

Converted message segments use the OneBot12 standard format:

Platform Extension Message Segments

Extension message segments identified by the telegram_ prefix:

Event Examples

Group Chat Message (with @mention)

{
  "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"
  }
}

Callback Query Event

{
  "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"
}

Inline Query Event

{
  "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"
}

Message with Inline Keyboard

{
  "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 Extension Methods

The adapter registers the following platform-specific methods, available only when platform == "telegram":

Message-related

Callback Query-related

Message Segment Data Extraction

Usage Example

from ErisPulse.Core.Event import message, notice

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

    # Message properties
    if event.is_bot_message():
        return  # Ignore bot messages

    if event.is_edited_message():
        print("This is an edited message")

    # Chat information
    title = event.get_chat_title()
    username = event.get_chat_username()

    # Forwarding source
    forward = event.get_forward_from()

    # Message segment data
    sticker = event.get_sticker_info()
    contact = event.get_contact_info()
    location = event.get_location()
    keyboard = event.get_inline_keyboard()

    # Topic
    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()

        # Respond to the callback query
        telegram = sdk.adapter.get("telegram")
        await telegram.Send.AnswerCallback(callback_id, text="Clicked")

        # Reply to the message
        await event.reply(f"You clicked: {callback_data}")

Extension Field Description

• All unique fields are prefixed with telegram_
• Original data is preserved in the telegram_raw field
• Original event type is preserved in the telegram_raw_type field
• Channel messages use detail_type="channel"
• Private chat messages use detail_type="private" (must be converted to user when sending)
• Thread messages include the thread_id field
• @ mentions use the standard mention message segment type (type: "mention"), with no @username in the text

Configuration Options

The Telegram adapter supports multi-account configuration:

Configuration Example

[Telegram_Adapter.accounts.default]
token = "YOUR_BOT_TOKEN"
enabled = true

[Telegram_Adapter.accounts.bot2]
token = "ANOTHER_BOT_TOKEN"
enabled = true

Running Mode

The Telegram adapter only supports Polling (polling) mode; the Webhook mode has been removed.

Proxy Configuration

If you need to connect to the Telegram API through a proxy, use a system-level proxy (environment variables ALL_PROXY / HTTPS_PROXY).

Migration from Old Configuration

The old single-token configuration is automatically compatible:

# Old format (still usable, but migration is recommended)
[Telegram_Adapter]
token = "YOUR_BOT_TOKEN"

It is recommended to migrate to the new format:

[Telegram_Adapter.accounts.default]
token = "YOUR_BOT_TOKEN"
enabled = true