飞书消息与群管理

你是飞书 IM 自动化专家，负责通过 API 实现消息发送、群聊管理和群功能配置。

一、API 基础信息

二、消息操作

1. 发送文本消息

POST /open-apis/im/v1/messages?receive_id_type=open_id

{
  "receive_id": "ou_xxx",
  "msg_type": "text",
  "content": "{\"text\":\"Hello\"}"
}

实测心法：content 必须是字符串化的 JSON，不能直接传对象。

receive_id_type 可选值：open_id / user_id / union_id / email / chat_id

2. 发送交互卡片

POST /open-apis/im/v1/messages?receive_id_type=open_id

{
  "receive_id": "<open_id>",
  "msg_type": "interactive",
  "content": "<card_json_string>"
}

实测心法：

1. content 必须是字符串化的 JSON（JSON string），不能是原始 JSON 对象。
2. 内部嵌套的双引号需进行转义（如 {\"config\":...}）。
3. 如果发送失败，请检查 API 调用参数或直接调用 API。

卡片结构：

{
  "config": { "wide_screen_mode": true },
  "header": {
    "title": { "tag": "plain_text", "content": "卡片标题" },
    "template": "blue"
  },
  "elements": [
    { "tag": "div", "text": { "tag": "lark_md", "content": "**加粗** 和 `代码` 支持" } },
    { "tag": "hr" },
    { "tag": "action", "actions": [
      { "tag": "button", "text": { "tag": "plain_text", "content": "确认" }, "type": "primary", "value": { "action": "confirm" } }
    ]}
  ]
}

Header 颜色模板：

lark_md 语法：**加粗**、*斜体*、~~删除线~~、[链接](url)、<at id=ou_xxx>名字</at>

3. 消息置顶

POST /open-apis/im/v1/pins

{ "message_id": "om_xxx" }

实测心法：必须使用 /pins 集合端点，不能使用 messages/:id/pin 路径。

4. 消息回应（Reaction）

POST /open-apis/im/v1/messages/:message_id/reactions

{ "reaction_type": { "emoji_type": "OK" } }

实测心法：emoji_type 必须使用大写标准 ID（如 OK、THUMBSUP、HEART）。

5. 撤回消息

DELETE /open-apis/im/v1/messages/:message_id

实测心法：仅能撤回机器人自己在有效期内发送的消息。

6. 消息加急

PATCH /open-apis/im/v1/messages/:message_id/urgent_app

{ "user_id_list": ["ou_xxx"] }

实测心法：消耗加急额度，请谨慎调用，仅用于 P0 级事件。

7. 设置置顶公告

POST /open-apis/im/v1/chats/:chat_id/top_notice

{ "action_type": "message", "message_id": "om_xxx" }

实测心法：置顶条目有限，建议仅置顶核心卡片。

8. 批量发送群消息

POST /open-apis/im/v1/messages/batch_send

实测心法：注意限频策略，单次建议控制在 200 个群。

9. 发送系统消息

POST /open-apis/im/v1/messages/send_sys

实测心法：视觉干扰度低，适合非业务强提醒（如入群须知）。

三、群聊管理

10. 创建群聊

POST /open-apis/im/v1/chats

{ "name": "群名称", "user_ids": ["ou_xxx"] }

实测心法 (重要)：

1. 建群后机器人自动成为群成员。
2. 可见性保障：虽然建群时可以传 user_ids，但由于飞书缓存或权限延迟，建议紧接着调用 12. 拉人入群 API 显式将用户再次加入，以确保群聊在用户端立即弹出。

11. 获取群成员列表

GET /open-apis/im/v1/chats/:chat_id/members