消息集成 API

飞书与微信 iLink 的 HTTP 契约分两层：管理端配置共享应用、能力开关、目录/知识同步与通知测试；个人端只操作调用者自己的连接、用途与 Agent 偏好。两层都使用 JWT 会话，API Key 不能替代。

端点总览

飞书（管理端）

飞书（个人端）与回调

微信 iLink（个人端）

飞书管理端

应用凭据

GET  /api/v1/admin/integrations/feishu/config
PUT  /api/v1/admin/integrations/feishu/config

PUT 请求体：

响应字段：app_id、app_secret_configured、is_enabled、department_ids。App Secret 永不明文返回。

POST /connection-check 使用应用凭据获取 tenant token，成功返回 {"status": "ok"}；失败按飞书返回的错误码映射，应用密钥不会出现在日志或响应中。

通讯录同步

• GET /departments 返回应用可见的部门树（含子部门）。
• PUT /department-scope 请求体 {"department_ids": ["0", "od-xxx"]}，1–500 项且必须属于可见部门；根部门 ID 为 0。
• POST /sync 使用已保存范围同步成员，返回新建/更新/跳过账号数与新建团队数。未保存范围时返回校验错误。

通知测试

• GET /test-recipients?search= 需要通知能力已开启；返回最多 20 条 {id, username, email}，id 即用户 ID。
• POST /test-message 请求体 {"user_id": "...", "title": "...", "content": "..."}，标题 1–200、正文 1–2000；接收人必须已绑定飞书且账号启用，否则返回 feishu_test_recipient_unavailable。

Agent 会话接收方式

GET  /api/v1/admin/integrations/feishu/agent-chat/config
PUT  /api/v1/admin/integrations/feishu/agent-chat/config

PUT 请求体（字段均可省略，省略表示保持不变）：

非空的密钥必须至少 8 个字符。响应字段：connection_mode、event_verification_token_configured、event_encrypt_key_configured、is_enabled、capability_enabled、receiver_status。

receiver_status.state 取值：

managed 表示连接是否由平台后台托管。选择长连接后由消费 agent 队列的 worker 维护单例接收器，无需额外服务；关闭能力或切回回调会停止接收。

回调端点

POST /api/v1/integrations/feishu/callback

公开端点，由飞书签名保护，不接受 API Key 或 JWT 调用。要求 X-Lark-Request-Timestamp、X-Lark-Request-Nonce、X-Lark-Signature；时间戳与服务端相差超过 300 秒即拒绝，请求体上限 64 KiB。connection_mode 为 long_connection 时该端点不生效。URL 校验挑战仅在 Verification Token 匹配时返回签名结果。

飞书知识同步

全部端点仅超级管理员可调用，使用应用凭据而非登录用户 token。

创建请求体：

来源输出包含 status、last_synced_at、last_error、last_result、created_at、updated_at。已有同步进行中时，更新、同步或删除返回 409（feishu_knowledge_source_busy）；空间不可用返回 feishu_knowledge_space_unavailable。

curl -X POST "https://your-domain.com/api/v1/admin/integrations/feishu/knowledge/sources" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"knowledge_base_id":"KB_UUID","space_id":"SPACE_ID","name":"产品文档","interval_minutes":60}'

飞书个人偏好

GET  /api/v1/feishu-agent/config
GET  /api/v1/feishu-agent/agents
PUT  /api/v1/feishu-agent/config

GET /config 返回 {enabled, is_enabled, linked, agent_id, agent_name, agent_available}：enabled 是平台通道是否可用，is_enabled 是用户自己的开关，linked 表示是否已绑定飞书身份。不可用的 Agent 名称不会返回。

GET /agents 返回当前用户在有权限团队内可用的已发布 Agent {id, name, description, team_name}；通道不可用或未绑定身份时返回空数组。

PUT /config 请求体字段均可选：

关闭开关或清除选择在通道暂停时也允许。变更只影响之后接收的消息，不影响已接收的回执、运行中的任务或其会话。

微信 iLink 个人端

所有端点要求当前用户 JWT，不提供管理端代操作。平台能力关闭时，对应端点返回 403（integration_feature_disabled）。

能力与连接

GET /api/v1/wechat-knowledge/features
GET /api/v1/wechat-knowledge/bindings

features 返回 {"agent_chat": boolean, "knowledge_collection": boolean}。bindings 返回当前用户的所有连接，每项包含 id、bot_id、purpose（none / knowledge_collection / agent）、agent_config、collection、status、last_error、last_received_at、created_at。

二维码授权

POST /api/v1/wechat-knowledge/logins
POST /api/v1/wechat-knowledge/logins/{identifier}/poll

logins 返回 {id, status, qrcode_content, expires_at}；同一用户最多同时有 3 个未完成授权，超出返回 429（wechat_login_limit）。poll 请求体 {"verify_code": "123456"}（可省略，纯数字，≤32 位）。授权确认后返回连接摘要；身份已绑定其他账号返回 409（wechat_identity_in_use）。

用途切换

PUT /api/v1/wechat-knowledge/bindings/{identifier}/purpose

请求体：

用途互斥：提交 agent 时不能同时带知识库字段，提交 knowledge_collection 时不能带 Agent 字段，否则返回校验错误。未提交的可选字段沿用已保存配置。目标知识库必须有写权限；不可用或只读返回 400。存在未完成工作时切换被拒绝。

DELETE /bindings/{identifier} 断开连接并写入审计，返回 {"id": "..."}；已采集文档保留。

采集与 Agent 回执

• GET /receipts?binding_id= 返回最近 50 条采集回执：id、binding_id、knowledge_base_id、status、results[]（逐附件结果，错误已本地化）、last_error、reply_status、created_at。
• GET /agent-receipts?binding_id= 返回最近 50 条 Agent 回执：id、binding_id、status、agent_name、agent_id、conversation_id、run_id、run_status、error、delivery_status[]、created_at。
• 传 binding_id 时会先校验归属；不属于当前用户返回 404（wechat_binding_not_found）。

GET /items/{identifier}/original 下载采集原件，返回文件流（application/octet-stream）而非统一信封。调用者仍需对原目标知识库有访问权；记录缺失、原件路径异常或文件不存在均返回 404（file_not_found）。

采集目标与模型

GET /api/v1/wechat-knowledge/targets
GET /api/v1/wechat-knowledge/models?knowledge_base_id=UUID
GET /api/v1/wechat-knowledge/agents
GET /api/v1/wechat-knowledge/agent-models?agent_id=UUID

targets 只返回当前用户有写权限的活跃知识库 {id, name, team_name}；models 返回该库可用的视觉与语音识别模型。agents 返回 {id, name, team_name, variables, enable_attachments, attachment_config}；agent-models 返回 {"stt": [...]}。

权限与错误

投递记录的查询端点见 管理 API；配置与使用步骤见消息集成。