Feishu Thread Forward
Forward a Feishu thread (话题) to a user, group, or another topic using the Feishu Open API.
When to Use
- - User asks to forward/share a thread or topic to another group or user
- You need to cross-post a topic post from one group to another
- The built-in
message tool cannot do thread-level forwarding
API
CODEBLOCK0
Parameters
| Param | Location | Required | Description |
|---|
| INLINECODE1 | path | yes | Thread ID to forward (format: omt_xxxxx) |
| INLINECODE3 |
query | yes | Target ID type:
open_id,
chat_id,
user_id,
union_id,
email,
thread_id |
|
receive_id | body | yes | Target ID matching the
receive_id_type |
|
uuid | query | no | Idempotency key (max 50 chars, dedup within 1 hour) |
Headers
CODEBLOCK1
How to Get thread_id
A message in a topic group has a thread_id field. Retrieve it via:
CODEBLOCK2
The response data.items[0].thread_id contains the thread ID (e.g., omt_1accc5a75c0f9b93).
Script
Use scripts/forward_thread.py for the complete implementation.
CODEBLOCK3
Typical Flow
- 1. Get
thread_id — from the message's metadata, or by calling GET message API - Call forward API — INLINECODE19
- Result — a
merge_forward type message appears in the target chat as a clickable topic card
Forward vs Merge Forward vs Message Forward
| Method | API | Result |
|---|
| Thread forward (this skill) | INLINECODE21 | Topic card (clickable, shows thread context) ✅ |
| Merge forward |
POST /messages/merge_forward | "群聊会话记录" bundle (expandable message list) |
| Message forward |
POST /messages/{message_id}/forward | Single message copied to target (loses thread context) |
Thread forward is what users see when they click "转发话题" in Feishu client.
Prerequisites
- - Bot must be in the source group (and can see the thread)
- Bot must be in the target group (or target user must be in bot's availability scope)
- Bot needs
im:message or im:message:send_as_bot permission
Credentials
Read from /root/.openclaw/openclaw.json → channels.feishu.appId / channels.feishu.appSecret to obtain tenant_access_token.
Error Codes
| Code | Meaning |
|---|
| 230002 | Bot not in target group |
| 230013 |
Target user not in bot's availability scope |
| 230064 | Invalid thread_id |
| 230066 | Thread is in a secret group (no forwarding) |
| 230070 | Thread's group has anti-leak mode enabled |
| 230073 | Thread invisible to bot (joined after thread creation + history hidden) |
飞书话题转发
使用飞书开放API将飞书话题转发给用户、群组或其他话题。
使用场景
- - 用户要求将话题转发/分享到其他群组或用户
- 需要将一个群组的话题帖子跨群转发到另一个群组
- 内置的message工具无法实现话题级别的转发
API
POST https://open.feishu.cn/open-apis/im/v1/threads/{threadid}/forward?receiveid_type={type}
参数
| 参数 | 位置 | 必填 | 说明 |
|---|
| threadid | 路径 | 是 | 要转发的话题ID（格式：omtxxxxx） |
| receiveidtype |
查询参数 | 是 | 目标ID类型：open
id、chatid、user
id、unionid、email、thread_id |
| receive
id | 请求体 | 是 | 与receiveid_type匹配的目标ID |
| uuid | 查询参数 | 否 | 幂等键（最多50个字符，1小时内去重） |
请求头
Authorization: Bearer {tenantaccesstoken}
Content-Type: application/json
如何获取thread_id
话题群中的消息包含thread_id字段。通过以下方式获取：
GET https://open.feishu.cn/open-apis/im/v1/messages/{message_id}
响应中的data.items[0].threadid包含话题ID（例如：omt1accc5a75c0f9b93）。
脚本
使用scripts/forward_thread.py获取完整实现。
bash
python3 skills/feishu-thread-forward/scripts/forward_thread.py \
--thread-id omt_xxxxx \
--receive-id oc_xxxxx \
--receive-id-type chat_id
典型流程
- 1. 获取threadid — 从消息的元数据中获取，或通过调用GET消息API获取
- 调用转发API — POST /im/v1/threads/{threadid}/forward
- 结果 — 目标聊天中会出现一个merge_forward类型的消息，显示为可点击的话题卡片
转发 vs 合并转发 vs 消息转发
| 方式 | API | 结果 |
|---|
| 话题转发（本技能） | POST /threads/{threadid}/forward | 话题卡片（可点击，显示话题上下文） ✅ |
| 合并转发 |
POST /messages/mergeforward | 群聊会话记录合集（可展开的消息列表） |
| 消息转发 | POST /messages/{message_id}/forward | 单条消息复制到目标（丢失话题上下文） |
话题转发即用户在飞书客户端点击转发话题时的操作。
前置条件
- - 机器人必须在源群组中（且能查看该话题）
- 机器人必须在目标群组中（或目标用户在机器人的可用范围内）
- 机器人需要im:message或im:message:sendasbot权限
凭证信息
从/root/.openclaw/openclaw.json读取 → channels.feishu.appId / channels.feishu.appSecret 获取tenantaccesstoken。
错误码
| 错误码 | 含义 |
|---|
| 230002 | 机器人不在目标群组中 |
| 230013 |
目标用户不在机器人的可用范围内 |
| 230064 | 无效的thread_id |
| 230066 | 话题位于私密群组中（无法转发） |
| 230070 | 话题所在群组已开启防泄露模式 |
| 230073 | 机器人无法查看该话题（话题创建后加入且历史消息隐藏） |
