飞书¶

概述¶

飞书Channel通过自建应用方式接入，支持tenantaccesstoken认证，可发送多种类型消息。

官方文档: https://open.feishu.cn/document/home/introduction-to-feishu-open-platform
接入方式: 自建应用 + Tenant Access Token
支持消息类型: 文本、富文本、图片、文件、卡片、音频、视频

配置参数¶

Config 结构体¶

type Config struct {
    AppID      string  // 应用ID
    AppSecret  string  // 应用密钥
    WebhookURL string  // Webhook地址（可选）
}

参数详细说明¶

参数名	类型	必填	默认值	说明
`app_id`	string	是	-	飞书自建应用的App ID
`app_secret`	string	是	-	飞书自建应用的App Secret
`webhook_url`	string	否	""	Webhook接收地址，用于接收消息

app_id¶

数据类型: string
格式: 如 cli_xxxxxxxxxxxxxxxx
获取方式:
登录飞书开放平台: https://open.feishu.cn
创建企业自建应用
在"凭证与基础信息"中获取App ID

app_secret¶

数据类型: string
格式: 32位字符串
获取方式: 与App ID在同一页面获取
安全提示: 此密钥用于获取access_token，请妥善保管

webhook_url¶

数据类型: string
用途: 接收飞书推送的事件和消息
配置要求:
必须使用HTTPS
需要在飞书后台配置事件订阅URL

完整配置示例¶

YAML配置¶

channels:
  - name: feishu-bot
    type: feishu
    config:
      app_id: "cli_xxxxxxxxxxxxxxxx"
      app_secret: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      webhook_url: "https://your-domain.com/webhook/feishu"

Go代码配置¶

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

config := feishu.Config{
    AppID:      "cli_xxxxxxxxxxxxxxxx",
    AppSecret:  "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    WebhookURL: "https://your-domain.com/webhook/feishu",
}

ch, err := feishu.NewChannel("feishu-bot", 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("Received: %s", msg.Content)
    return nil
})

功能支持¶

消息类型¶

消息类型	支持状态	说明
文本消息	✅	普通文本
图片消息	✅	需要image_key
文件消息	✅	需要file_key
音频消息	✅	需要file_key
视频消息	✅	需要file_key
卡片消息	✅	交互式卡片

能力矩阵¶

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

常见配置问题¶

问题1: 获取token失败¶

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

原因: - AppID或AppSecret错误 - 应用未发布或未被企业启用

解决:

// 确认凭证正确
config := feishu.Config{
    AppID:     "cli_xxxxxxxxxxxxxxxx",  // 确认是App ID不是App Name
    AppSecret: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
}

// 检查应用状态:
// 1. 在飞书后台确认应用已发布
// 2. 确认企业管理员已启用应用

问题2: 发送消息失败¶

现象: 返回"tenantaccesstoken expired"

原因: Token自动刷新机制异常

解决: - Channel会自动刷新token，无需手动处理 - 如持续失败，检查网络连接和时钟同步

问题3: 无法接收Webhook¶

现象: 收不到飞书推送的消息

原因: - Webhook URL未配置或不可访问 - 事件订阅未开启

解决: 1. 在飞书后台"事件与回调"中配置请求地址 2. 确保URL可公网访问且使用HTTPS 3. 配置需要订阅的事件类型

发送消息示例¶

发送文本消息¶

msg := &message.Message{
    ID:        "msg-1",
    ChannelID: "feishu-bot",
    Direction: message.DirectionOutbound,
    To:        message.UserInfo{ID: "ou_xxxxxxxxxxxxxxxx"},
    Content:   "Hello Feishu!",
    Type:      message.MessageTypeText,
}

err := ch.SendMessage(ctx, msg)

发送图片消息¶

msg := &message.Message{
    ID:        "msg-2",
    ChannelID: "feishu-bot",
    Direction: message.DirectionOutbound,
    To:        message.UserInfo{ID: "ou_xxxxxxxxxxxxxxxx"},
    Content:   "image",
    Type:      message.MessageTypeImage,
}
// 需要先上传图片获取image_key
msg.SetMetadata("image_key", "img_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")

err := ch.SendMessage(ctx, msg)

安全建议¶

密钥管理: 使用环境变量存储AppSecret
Webhook验证: 实现签名验证防止伪造请求
权限最小化: 只申请必要的权限范围
IP白名单: 配置服务器IP白名单

错误代码参考¶

错误	说明
`ErrAppIDRequired`	缺少AppID
`ErrAppSecretRequired`	缺少AppSecret
`ErrTokenExpired`	Access token过期