微信公众号¶

概述¶

微信Channel通过公众号API接入，支持access_token认证和消息加解密。

官方文档: https://developers.weixin.qq.com/doc/offiaccount/Getting_Started/Overview.html
接入方式: 公众号 + Access Token
支持消息类型: 文本、图片、语音、视频、文件、模板消息

配置参数¶

Config 结构体¶

type Config struct {
    AppID     string  // 公众号AppID
    AppSecret string  // 公众号AppSecret
    Token     string  // 消息加密密钥
    AESKey    string  // 消息加解密密钥（可选）
}

参数详细说明¶

参数名	类型	必填	默认值	说明
`app_id`	string	是	-	微信公众号AppID
`app_secret`	string	是	-	微信公众号AppSecret
`token`	string	是	-	服务器配置中的Token，用于签名验证
`aes_key`	string	否	""	消息加解密密钥，启用加密时必填

app_id¶

数据类型: string
格式: 如 wx1234567890abcdef
获取方式:
登录微信公众平台: https://mp.weixin.qq.com
进入"开发" → "基本配置"
复制AppID

app_secret¶

数据类型: string
格式: 32位字符串
获取方式: 与AppID在同一页面，需要管理员扫码查看
安全提示: 此密钥非常重要，请妥善保管

token¶

数据类型: string
用途: 用于验证服务器地址的有效性
获取方式: 在"基本配置" → "服务器配置"中设置
要求: 3-32位字符，建议随机生成

aes_key¶

数据类型: string
格式: 43位Base64编码字符串
用途: 消息体加解密密钥
获取方式: 在"基本配置" → "服务器配置"中设置消息加密
注意: 启用后所有消息将加密传输

完整配置示例¶

YAML配置¶

channels:
  - name: wechat-official
    type: wechat
    config:
      app_id: "wx1234567890abcdef"
      app_secret: "1234567890abcdef1234567890abcdef"
      token: "your-verification-token"
      aes_key: "your-aes-key-43-chars-long-base64-encoded"

Go代码配置¶

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

config := wechat.Config{
    AppID:     "wx1234567890abcdef",
    AppSecret: "1234567890abcdef1234567890abcdef",
    Token:     "your-verification-token",
    AESKey:    "your-aes-key-43-chars-long-base64-encoded",
}

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

// 启动Channel
ctx := context.Background()
err = ch.Start(ctx, func(ctx context.Context, msg *message.Message) error {
    // 处理收到的消息
    log.Printf("From %s: %s", msg.From.ID, msg.Content)
    return nil
})

功能支持¶

消息类型¶

消息类型	支持状态	说明
文本消息	✅	普通文本
图片消息	✅	需要media_id
语音消息	✅	需要media_id
视频消息	✅	需要media_id
文件消息	✅	需要media_id
模板消息	✅	需要模板ID

能力矩阵¶

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

服务器配置¶

微信后台配置步骤¶

登录微信公众平台
访问 https://mp.weixin.qq.com
使用公众号管理员账号登录
配置服务器URL
进入"开发" → "基本配置" → "服务器配置"
填写服务器URL: https://your-domain.com/webhook/wechat
填写Token（与配置中的token一致）
选择消息加密方式（推荐"安全模式"）
填写EncodingAESKey
启用服务器配置
点击"提交"完成验证
启用服务器配置
配置IP白名单
在"基本配置"中添加服务器公网IP

常见配置问题¶

问题1: Token验证失败¶

现象: 微信后台提示"请求URL超时"或"Token验证失败"

原因: - Token配置不一致 - 服务器无法公网访问 - 签名算法错误

解决:

// 确保Token与微信后台一致
config := wechat.Config{
    Token: "your-verification-token",  // 必须与微信后台完全一致
}

// 检查服务器是否可公网访问
// 微信会发送GET请求到配置的URL进行验证

问题2: 获取access_token失败¶

现象: 启动时返回"failed to get initial access token"

原因: - AppID或AppSecret错误 - IP不在白名单

解决: 1. 确认AppID和AppSecret正确 2. 在微信后台添加服务器IP到白名单 3. 检查公众号是否已认证（部分接口需要认证）

问题3: 无法发送客服消息¶

现象: 返回"message outside 48-hour window"

原因: 用户48小时内未与公众号互动

解决: - 使用模板消息（需用户关注且通过模板ID） - 引导用户先发送消息激活会话

发送消息示例¶

发送文本消息¶

msg := &message.Message{
    ID:        "msg-1",
    ChannelID: "wechat-official",
    Direction: message.DirectionOutbound,
    To:        message.UserInfo{ID: "openid_xxxxxxxx"},
    Content:   "Hello WeChat!",
    Type:      message.MessageTypeText,
}

err := ch.SendMessage(ctx, msg)

发送图片消息¶

msg := &message.Message{
    ID:        "msg-2",
    ChannelID: "wechat-official",
    Direction: message.DirectionOutbound,
    To:        message.UserInfo{ID: "openid_xxxxxxxx"},
    Content:   "image",
    Type:      message.MessageTypeImage,
}
// 需要先上传图片获取media_id
msg.SetMetadata("media_id", "media_id_xxxxxxxx")

err := ch.SendMessage(ctx, msg)

安全建议¶

启用消息加密: 生产环境务必启用AES加密
IP白名单: 配置服务器IP白名单
HTTPS强制: 服务器URL必须使用HTTPS
定期轮换: 定期更换AppSecret
签名验证: 始终验证消息签名

错误代码参考¶

错误	说明
`ErrAppIDRequired`	缺少AppID
`ErrAppSecretRequired`	缺少AppSecret
`ErrTokenRequired`	缺少Token
`ErrInvalidSignature`	签名验证失败
`ErrTokenExpired`	Access token过期
`ErrUserNotSubscribed`	用户未关注公众号
`ErrMessageOutsideWindow`	超出48小时客服消息窗口