企业微信配置指南¶

概述¶

企业微信Channel通过Webhook机器人方式接入，支持向企业微信群组发送多种类型消息。

官方文档: https://developer.work.weixin.qq.com/document/path/91770
接入方式: Webhook机器人
支持消息类型: 文本、Markdown、图片、图文、文件、语音、模板卡片

配置参数¶

Config 结构体¶

type Config struct {
    WebhookURL  string        // Webhook地址
    Key         string        // Webhook密钥
    HTTPTimeout time.Duration // HTTP超时时间
}

参数详细说明¶

参数名	类型	必填	默认值	说明
`webhook_url`	string	是	-	企业微信机器人Webhook完整地址
`key`	string	是	-	Webhook密钥，用于签名验证
`http_timeout`	duration	否	30s	HTTP请求超时时间

webhook_url¶

数据类型: string
格式: https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxxxxx
获取方式:
登录企业微信管理后台: https://work.weixin.qq.com/wework_admin
进入目标群组 → 群设置 → 添加群机器人
选择"新建机器人"
复制Webhook地址

key¶

数据类型: string
格式: UUID格式，如 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
获取方式: 创建机器人时自动生成
用途: 用于HMAC-SHA256消息签名验证

http_timeout¶

数据类型: time.Duration
默认值: 30s
取值范围: 5s - 5m
说明: HTTP请求超时时间，包含连接和读写超时

完整配置示例¶

YAML配置¶

channels:
  - name: wecom-bot
    type: wecom
    config:
      webhook_url: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      key: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      http_timeout: 30s

Go代码配置¶

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

config := wecom.Config{
    WebhookURL:  "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    Key:         "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    HTTPTimeout: 30 * time.Second,
}

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

功能支持¶

消息类型¶

消息类型	支持状态	说明
文本消息	✅	普通文本，支持@成员
Markdown	✅	Markdown格式消息
图片消息	✅	Base64编码图片
图文消息	✅	新闻类型消息
文件消息	✅	文件上传后发送
语音消息	✅	语音文件
模板卡片	✅	交互式卡片消息

能力矩阵¶

GetCapabilities() 返回:
- TextMessages:     true
- MarkdownMessages: true
- ImageMessages:    true
- FileMessages:     true
- VoiceMessages:    true
- NewsMessages:     true
- TemplateCard:     true
- LocationMessages: false
- ReadReceipts:     false
- TypingIndicators: false
- MessageEditing:   false
- MessageDeletion:  false
- ReactionMessages: false

常见配置问题¶

问题1: Webhook URL无效¶

现象: 返回"invalid webhook url"

原因: - URL格式错误 - Key无效或过期

解决:

// 确保URL完整且Key正确
config := wecom.Config{
    WebhookURL: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    Key:        "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
}

问题2: 消息发送失败¶

现象: 返回"errcode": 93000

原因: 消息格式错误或内容违规

解决: - 检查消息内容是否符合企业微信规范 - 确保图片大小不超过限制（2MB） - 确保Markdown格式正确

问题3: 触发限流¶

现象: 返回"rate limit exceeded"

原因: 发送频率过高

解决: - 降低发送频率 - 实现消息队列和重试机制 - 联系企业微信提高限额

发送消息示例¶

发送文本消息¶

msg := &message.Message{
    ID:        "msg-1",
    ChannelID: "wecom-bot",
    Direction: message.DirectionOutbound,
    To:        message.UserInfo{ID: "group-id"},
    Content:   "Hello WeCom!",
    Type:      message.MessageTypeText,
}

err := ch.SendMessage(ctx, msg)

发送Markdown消息¶

msg := &message.Message{
    ID:        "msg-2",
    ChannelID: "wecom-bot",
    Direction: message.DirectionOutbound,
    To:        message.UserInfo{ID: "group-id"},
    Content:   "**Bold** and *italic* text",
    Type:      message.MessageTypeMarkdown,
}

err := ch.SendMessage(ctx, msg)

发送模板卡片¶

msg := &message.Message{
    ID:        "msg-3",
    ChannelID: "wecom-bot",
    Direction: message.DirectionOutbound,
    To:        message.UserInfo{ID: "group-id"},
    Content:   "Card message",
    Type:      message.MessageTypeTemplateCard,
}
msg.SetMetadata("card_type", "text_notice")
msg.SetMetadata("source_desc", "企业微信")
msg.SetMetadata("main_title", "通知标题")
msg.SetMetadata("sub_title", "通知副标题")

err := ch.SendMessage(ctx, msg)

安全建议¶

保护Key: Webhook Key相当于密码，请妥善保管
IP白名单: 在企业微信后台配置服务器IP白名单
HTTPS强制: 确保使用HTTPS协议
定期轮换: 定期更换机器人Key

错误代码参考¶

错误	说明
`ErrWebhookNotFound`	Webhook URL无效
`ErrInvalidSignature`	签名验证失败
`ErrRateLimited`	触发限流
`ErrMessageTooLong`	消息长度超过限制