API 参考 / requirement-rooms

为需求室新建或绑定飞书群

POST /api/v1/rooms/{roomId}/feishu-chat · bindRoomFeishuChat

把一个飞书群关联到该需求室：mode=create 由服务端调飞书开放平台建群并把已完成飞书身份绑定的 项目成员拉进去；mode=bind 绑定一个已存在的群（必须先把机器人加进该群，服务端会校验）。 绑定成功后，该室内对象的交接纪要会被镜像到这个群。

前提是当前项目已配置并启用飞书集成（PUT /projects/{projectId}/integrations/feishu）， 否则 422 feishu_integration_not_configured。

一室至多一条绑定。已处于 active 的室再次调用返 409 room_chat_already_bound—— 换群要先 DELETE 解绑。10 分钟内有进行中的建群返 409 room_chat_binding_in_progress。

本端点不接受 Idempotency-Key：它跨两段事务并在其间调用飞书，与幂等键的单事务 Claim→写→Complete 模型不兼容。幂等由资源本身保证——一室一行，且建群请求携带稳定的 去重键，重试不会在飞书侧建出第二个群。

飞书暂时性故障（超时 / 5xx / 限流）返 502 feishu_api_error，绑定行落 failed，可直接重试。

飞书永久拒绝但没有对应产品语义的情况（群成员已达上限、建群去重键超窗…）返 422 feishu_chat_rejected：重试不会成功，具体的飞书业务码记在绑定行的 error 里。

允许同一个群被多个需求室绑定（小团队常把几个室汇到一个群）。

鉴权：项目 API Token（Authorization: Bearer wfp_…）。详见 Agent 接入。

参数

roomId（必填）
string

请求体

mode（必填）
enum；取值：create / bind
name
string
chatId
string

响应字段 · 201

status（必填）
enum；取值：creating / active / failed
source（必填）
enum；取值：created / bound
chatId（必填）
string
chatName（必填）
string
error（必填）
string
invitedCount
integer
skippedUnboundCount
integer
updatedAt（必填）
string

错误

请求示例（curl）

curl -X POST "https://你的项目.workflow.games/api/v1/rooms/{roomId}/feishu-chat" \
  -H "Authorization: Bearer wfp_…" \
  -H "content-type: application/json" \
  --data '{"mode":"create","name":"示例标题","chatId":"018f3c2e-0000-7000-8000-000000000000"}'

响应示例

HTTP/1.1 201
{
  "status": "creating",
  "source": "created",
  "chatId": "018f3c2e-0000-7000-8000-000000000000",
  "chatName": "示例标题",
  "error": "示例文本",
  "updatedAt": "2026-08-01"
}

合同真值：OpenAPI 3.1（0.1.0）。

相关：Agent 接入指南 · 使用指南 · API 参考索引

Workflow 正在加载…