Telegram¶

概述¶

Telegram Channel通过Bot API接入，支持长轮询或Webhook方式接收消息。

官方文档: https://core.telegram.org/bots/api
接入方式: Bot Token
API版本: Bot API 7.11
支持消息类型: 文本、图片、文档、音频、视频、语音、位置、联系人

配置参数¶

Config 结构体¶

type Config struct {
    Token       string  // Bot Token
    WebhookURL  string  // Webhook地址（可选）
    SecretToken string  // Webhook密钥（可选）
}

参数详细说明¶

参数名	类型	必填	默认值	说明
`token`	string	是	-	Bot Token，格式 `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`
`webhook_url`	string	否	""	Webhook接收地址
`secret_token`	string	否	""	Webhook密钥，用于验证请求

token¶

数据类型: string
格式: {bot_id}:{bot_token}
获取方式:
在Telegram中搜索 @BotFather
发送 /newbot 创建新Bot
按提示设置名称和用户名
复制提供的Token

webhook_url¶

数据类型: string
用途: 接收Telegram推送的更新
要求:
必须使用HTTPS
需要有效的SSL证书
支持自签名证书（但不推荐）
与长轮询关系:
配置Webhook则使用Webhook模式
不配置则使用长轮询(getUpdates)模式

secret_token¶

数据类型: string
用途: 验证Webhook请求来自Telegram
验证方式: 请求头中的 X-Telegram-Bot-Api-Secret-Token

完整配置示例¶

YAML配置（长轮询模式）¶

channels:
  - name: telegram-bot
    type: telegram
    config:
      token: "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"

YAML配置（Webhook模式）¶

channels:
  - name: telegram-bot
    type: telegram
    config:
      token: "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
      webhook_url: "https://your-domain.com/webhook/telegram"
      secret_token: "your-secret-token-here"

Go代码配置¶

import (
    "github.com/example/gort/pkg/channel/telegram"
)

// 长轮询模式
config := telegram.Config{
    Token: "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
}

// Webhook模式
config := telegram.Config{
    Token:       "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
    WebhookURL:  "https://your-domain.com/webhook/telegram",
    SecretToken: "your-secret-token",
}

ch, err := telegram.NewChannel("telegram-bot", config)
if err != nil {
    log.Fatal(err)
}

功能支持¶

消息类型¶

消息类型	支持状态	说明
文本消息	✅	支持Markdown/HTML格式
图片消息	✅	支持URL或file_id
文档消息	✅	任意文件类型
音频消息	✅	音乐文件
视频消息	✅	视频文件
语音消息	✅	语音消息
位置消息	✅	地理位置
联系人	✅	联系人卡片
贴纸	✅	接收贴纸消息

能力矩阵¶

GetCapabilities() 返回:
- TextMessages:     true
- MarkdownMessages: true
- ImageMessages:    true
- FileMessages:     true
- AudioMessages:    true
- VideoMessages:    true
- LocationMessages: true
- TemplateMessages: false
- ReadReceipts:     false
- TypingIndicators: false
- MessageEditing:   true
- MessageDeletion:  true
- ReactionMessages: true

常见配置问题¶

问题1: Bot Token无效¶

现象: API请求返回401 Unauthorized

原因: - Token格式错误 - Token被撤销或Bot被删除

解决:

// 确认Token格式正确
config := telegram.Config{
    Token: "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",  // 注意冒号分隔
}

// 在Telegram中向Bot发送消息测试
// 访问: https://api.telegram.org/bot<token>/getMe

问题2: Webhook设置失败¶

现象: 返回"Failed to set webhook"

原因: - Webhook URL不可访问 - SSL证书无效

解决: 1. 确保URL可公网访问 2. 检查SSL证书有效性 3. 使用浏览器访问Webhook URL测试

问题3: 无法接收消息¶

现象: Bot不响应消息

原因: - 未与Bot开始对话 - Bot隐私模式限制

解决: 1. 在Telegram中搜索Bot并点击Start 2. 检查Bot设置中的Privacy Mode 3. 将Bot添加到群组时赋予读取消息权限

发送消息示例¶

发送文本消息（Markdown）¶

msg := &message.Message{
    ID:        "msg-1",
    ChannelID: "telegram-bot",
    Direction: message.DirectionOutbound,
    To:        message.UserInfo{ID: "123456789"},  // Chat ID
    Content:   "*Bold* and _italic_ text",
    Type:      message.MessageTypeText,
}
msg.SetMetadata("parse_mode", "Markdown")

err := ch.SendMessage(ctx, msg)

发送图片¶

msg := &message.Message{
    ID:        "msg-2",
    ChannelID: "telegram-bot",
    Direction: message.DirectionOutbound,
    To:        message.UserInfo{ID: "123456789"},
    Content:   "https://example.com/image.jpg",  // 图片URL
    Type:      message.MessageTypeImage,
}
msg.SetMetadata("caption", "Image caption")

err := ch.SendMessage(ctx, msg)

安全建议¶

Token保护: 不要将Token提交到版本控制
Webhook验证: 使用SecretToken验证请求来源
HTTPS强制: Webhook必须使用HTTPS
权限控制: 设置Bot命令白名单

错误代码参考¶

错误	说明
`ErrTokenRequired`	缺少Bot Token
`ErrInvalidToken`	Token格式错误
`ErrChatNotFound`	聊天不存在或Bot被移除
`ErrUserBlocked`	用户屏蔽了Bot
`ErrMessageTooLong`	消息超过4096字符
`ErrFileTooLarge`	文件超过大小限制