ErisPulse-TelegramAdapter 4.0.0

ErisPulse的Telegram协议适配模块

ErisPulse Telegram 适配器

基于 ErisPulse 框架的 Telegram Bot API 适配器，支持多账号、多种消息类型收发和平台特有事件处理。

安装

epsdk install TelegramAdapter

配置

在 config/config.toml 中添加：

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

# 多账号示例
[Telegram_Adapter.accounts.bot2]
token = "ANOTHER_BOT_TOKEN"
enabled = true

配置字段

字段	类型	必填	说明
token	string	是	Telegram Bot Token
bot_id	string	否	自动从 Token 提取，无需手动填写
enabled	bool	否	是否启用（默认 true）

旧版配置兼容

旧版单 token 格式仍可使用：

[Telegram_Adapter]
token = "YOUR_BOT_TOKEN"

建议迁移到新格式以支持多账号。

代理

如需通过代理连接 Telegram API，请设置系统级代理环境变量（如 ALL_PROXY、HTTPS_PROXY）。

快速开始

from ErisPulse import sdk
from ErisPulse.Core.Event import command, message

@command("hello")
async def hello_handler(event):
    await event.reply("Hello from Telegram!")

async def main():
    await sdk.run(keep_running=True)

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

消息发送

所有发送方法通过链式 DSL 调用：

telegram = sdk.adapter.get("telegram")

# 文本消息
await telegram.Send.To("user", "123456789").Text("Hello World!")

# Markdown / HTML 格式
await telegram.Send.To("group", "-1001234567890").Markdown("*粗体*")
await telegram.Send.To("user", "123456789").Html("<b>粗体</b>")

# 媒体消息（支持 URL、file_id、bytes）
await telegram.Send.To("user", "123456789").Image("https://example.com/photo.jpg")
await telegram.Send.To("user", "123456789").Image(image_bytes, caption="图片说明")

# 贴纸
await telegram.Send.To("user", "123456789").Sticker("CAACAgIAAxkBAA...")

# 位置
await telegram.Send.To("user", "123456789").Location(39.9042, 116.4074)

链式修饰

# @用户（通过 Telegram entities 实现）
await telegram.Send.To("group", "-1001234567890").At("6117725680").Text("你好！")

# 回复消息
await telegram.Send.To("group", "-1001234567890").Reply("12345").Text("回复内容")

# 内联键盘
keyboard = [[{"text": "按钮1", "callback_data": "btn1"}]]
await telegram.Send.To("group", "-1001234567890").Keyboard(keyboard).Text("请选择：")

# 保护内容 + 静默发送
await telegram.Send.To("group", "-1001234567890").ProtectContent().Silent().Text("机密消息")

消息操作

# 编辑消息
await telegram.Send.To("user", "123456789").Edit(123, "新内容")

# 撤回消息
await telegram.Send.To("user", "123456789").Recall(123)

# 转发消息
await telegram.Send.To("user", "123456789").Forward(from_chat_id="-1001234567890", message_id=456)

# 复制消息（不带来源）
await telegram.Send.To("user", "123456789").CopyMessage(from_chat_id="-1001234567890", message_id=456)

# 应答回调查询
await telegram.Send.AnswerCallback("callback_query_id", text="已处理")

事件类型

Telegram 事件转换遵循 OneBot12 标准，平台扩展使用 telegram_ 前缀。

消息事件

Telegram 类型	OB12 detail_type	说明
message / edited_message	private / group / channel	私聊/群聊/频道消息
channel_post / edited_channel_post	channel	频道消息

通知事件

detail_type	说明
telegram_callback_query	回调查询（按钮点击）
telegram_poll	投票事件
telegram_poll_answer	投票答案
telegram_my_chat_member	Bot 自身成员状态变更
telegram_chat_member	聊天成员变更

请求事件

detail_type	说明
telegram_inline_query	内联查询
telegram_chat_join_request	加入聊天请求
telegram_shipping_query	运费查询
telegram_pre_checkout_query	预付款查询

消息段类型

类型	说明
text	纯文本
mention	@用户（user_id, user_name）
reply	回复引用
image	图片
video	视频
voice	语音
audio	音频
file	文件
location	位置
telegram_sticker	贴纸（扩展）
telegram_animation	GIF 动画（扩展）
telegram_contact	联系人（扩展）
telegram_inline_keyboard	内联键盘（扩展）

Event Mixin 方法

适配器注册了以下平台专有方法（platform == "telegram" 时可用）：

from ErisPulse.Core.Event import message

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

    # 消息属性
    event.is_bot_message()        # 是否来自机器人
    event.is_edited_message()     # 是否编辑过的消息
    event.is_topic_message()      # 是否话题消息

    # 聊天信息
    event.get_chat_title()        # 聊天标题
    event.get_chat_username()     # 聊天用户名
    event.get_forward_from()      # 转发来源
    event.get_topic_id()          # 话题 ID

    # 回调查询
    event.get_callback_data()     # callback_data
    event.get_callback_id()       # callback_query_id

    # 消息段数据
    event.get_sticker_info()      # 贴纸信息
    event.get_contact_info()      # 联系人信息
    event.get_location()          # 位置信息
    event.get_inline_keyboard()   # 内联键盘

运行模式

仅支持 Polling（长轮询） 模式。每个账号独立轮询，支持多 Bot 并行运行。

注意事项

• 媒体内容支持 URL、file_id、bytes 三种输入方式
• HTML 格式消息会自动清洗不支持的标签
• 所有发送方法返回 asyncio.Task 对象，可选择是否 await
• 会话类型映射：private → 发送时用 user，group/supergroup → group，channel → channel

参考链接

• ErisPulse 主库
• Telegram Bot API 官方文档