飞书机器人实战：5分钟搞定图片消息发送（含token获取避坑指南）

飞书机器人图片消息发送全流程实战指南

作为企业级协作平台，飞书机器人的消息推送能力正被越来越多的开发者关注。与直接发送文本消息不同，图片消息的发送流程存在几个关键的技术卡点——特别是临时凭证获取和图片上传环节。本文将用真实项目经验，带你避开这些"暗礁"。

1. 前期准备：创建具备图片权限的机器人

很多开发者第一步就会踩坑：创建了普通机器人后才发现无法发送图片。实际上飞书机器人需要单独开启图片上传权限，这个设置在开发者后台并不显眼。

1.1 创建应用与机器人

1. 登录飞书开放平台，进入「开发者后台」
2. 选择「创建企业自建应用」，填写基础信息
3. 在应用功能中开启「机器人」能力

注意：应用名称建议包含"bot"或"机器人"等标识，方便后续权限管理

1.2 配置关键权限

在「权限管理」页面，需要添加以下两个核心权限：

# 权限配置检查命令（需安装飞书CLI） feishu-cli app get-permissions --app-id YOUR_APP_ID

2. 获取临时访问凭证：tenant_access_token

飞书API的安全设计要求所有请求都必须携带临时token。这个设计虽然安全，但给开发者带来了两个挑战：有效期短（2小时）和自动续期复杂。

2.1 手动获取token

使用应用的app_id和app_secret获取token：

import requests url = "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" headers = {"Content-Type": "application/json"} data = { "app_id": "YOUR_APP_ID", "app_secret": "YOUR_APP_SECRET" } response = requests.post(url, headers=headers, json=data) token = response.json()["tenant_access_token"]

关键响应字段说明：

• expire: 7200秒（2小时）
• tenant_access_token: 以"t-"开头的前缀

2.2 生产环境中的token管理

在实际项目中，建议采用以下方案：

1. 缓存机制：使用Redis存储token并设置自动过期
2. 提前刷新：在token到期前30分钟触发更新
3. 错误重试：当API返回401时自动重新获取token

# 使用Redis缓存的示例 import redis r = redis.Redis(host='localhost', port=6379) def get_token(): cached_token = r.get('feishu_token') if cached_token: return cached_token.decode() # 获取新token并缓存 new_token = fetch_new_token() r.setex('feishu_token', 7000, new_token) return new_token

3. 图片上传：获取image_key的关键步骤

飞书要求所有发送的图片必须先上传到其服务器，这与钉钉等平台直接使用URL的方案不同。上传过程需要注意三个技术细节：

3.1 文件准备规范

• 格式支持：JPG/JPEG/PNG/GIF
• 大小限制：单个文件≤10MB
• 分辨率建议：不超过4096x4096

3.2 上传API调用

curl -X POST 'https://open.feishu.cn/open-apis/im/v1/images' \ -H 'Authorization: Bearer YOUR_TOKEN' \ -F 'image_type=message' \ -F 'image=@/path/to/your/image.jpg'

常见错误及解决方案：

3.3 处理响应数据

成功响应会返回image_key，这是发送图片消息的唯一标识：

{ "code": 0, "data": { "image_key": "img_v2_8adc397a-9950-44ea-9302-e1d8fe00858g" } }

重要提示：image_key的有效期与tenant_access_token无关，上传后永久有效

4. 发送图片消息：Webhook与API双方案

根据使用场景不同，飞书提供两种发送图片的方式：

4.1 Webhook方案（适合简单通知）

配置群机器人Webhook地址后：

webhook_url = "https://open.feishu.cn/open-apis/bot/v2/hook/YOUR_WEBHOOK_KEY" payload = { "msg_type": "image", "content": { "image_key": "img_v2_8adc397a-9950-44ea-9302-e1d8fe00858g" } } requests.post(webhook_url, json=payload)

4.2 API方案（适合复杂场景）

api_url = "https://open.feishu.cn/open-apis/im/v1/messages" headers = { "Authorization": "Bearer YOUR_TOKEN", "Content-Type": "application/json" } data = { "receive_id": "oc_123456", # 会话ID "msg_type": "image", "content": json.dumps({ "image_key": "img_v2_8adc397a-9950-44ea-9302-e1d8fe00858g" }) } requests.post(api_url, headers=headers, json=data)

两种方案的对比：

5. 实战中的性能优化技巧

在日均发送量超过1万条的项目中，我们总结了这些优化经验：

1. 批量上传：先上传所有图片获取image_key列表
2. 异步发送：使用消息队列处理发送请求
3. 错误隔离：对429状态码实现自动退避重试
4. 监控指标：
   • token获取失败率
   • 图片上传耗时P99值
   • 消息送达延迟

# 异步发送示例（使用Celery） @app.task def async_send_image(receive_id, image_path): try: # 上传图片 image_key = upload_image(image_path) # 发送消息 send_message(receive_id, image_key) except Exception as e: logger.error(f"发送失败: {str(e)}") self.retry(exc=e)

6. 企业级安全实践

对于金融、医疗等敏感行业，还需要注意：

• 图片内容审核：在上传前进行涉敏检测
• 访问日志留存：记录所有API调用日志
• 权限最小化：仅授予必要的API权限
• IP白名单：限制调用来源IP范围

在最近的一个医疗项目中，我们通过以下配置将安全事件降为零：

# 安全策略示例 security: content_moderation: enabled: true provider: "aliyun" access_control: ip_whitelist: ["192.168.1.0/24"] audit_log: retention_days: 180

7. 调试工具链推荐

工欲善其事，必先利其器。这些工具能极大提升开发效率：

1. Postman集合：导入飞书官方API集合
2. Charles Proxy：抓包分析API请求
3. 飞书开发者工具：实时调试机器人
4. Sentry监控：捕获运行时异常

特别是飞书提供的消息卡片调试工具，可以实时预览图片消息效果。