{ "module": "inbox-callback", "description": "站内信模块出站回调定义。WMS 处理入站消息后,通过 HTTP POST 将回复推送到仓库 ApiApp 配置的 callback_url(interface_type_id=3),供外部适配器消费并投递到实际聊天通道。回调体统一包裹:{ method, code, data }。", "version": "1.1.0", "updatedAt": "2026-08-07", "http": { "path": "{ApiApp.callback_url}", "method": "POST" }, "headers": [ { "name": "Content-Type", "type": "string", "required": true, "description": "application/json" } ], "methods": { "groups": [ { "groupName": "AI 自动回复", "module": "ai_reply", "list": [ { "method": "inbox.callback.ai_reply", "description": "AI 自动回复回调。用户发送消息后,DeepSeek 推理给出回复内容,WMS 推送到外部聊天通道。", "params": [], "response": [], "errors": [], "notes": [ "content 为 AI 生成的纯文本(含 \\n 换行,禁止 Markdown)", "ext_id 与入站消息相同,外部系统可据此关联对话", "若 AI 判定无需回复(silent),不会触发此回调", "ai_thoughts 字段记录整个推理链(仅限出站记录查询,不入回调)" ], "example": { "method": "inbox.callback.ai_reply", "code": 200, "data": { "source": "ai_reply", "content": "条码6900000000016查到2款商品:\n1. 披肩-消退 可用0\n2. 披肩 可用0(总量95已锁定)\n均无可用库存,建议更换商品。", "ext_id": "api:AK001:req-123", "ext_data": { "request_id": "req-123" }, "group_id": "wrchat-xxx", "user_id": "user-001", "group_name": "售后沟通群", "user_name": "张三", "timestamp": 1786100000 } } } ] }, { "groupName": "绑群确认", "module": "bind_confirm", "list": [ { "method": "inbox.callback.bind_confirm", "description": "绑群确认回调。用户发送「授权:CODE」后,WMS 校验成功/失败/已绑定,推送绑群结果。", "params": [], "response": [], "errors": [], "notes": [ "成功 content:绑定「{货主备注名}」成功", "失败 content:绑群码无效或已过期,请重新生成", "已绑定 content:已在绑定状态,无需重复操作", "绑定成功后自动追加 inbox.callback.balance 返回面单余额" ], "example": { "method": "inbox.callback.bind_confirm", "code": 200, "data": { "source": "bind_confirm", "content": "绑定「测试货主1111」成功", "ext_id": "api:AK001:req-456", "ext_data": null, "group_id": "wrchat-xxx", "user_id": "user-001", "group_name": "售后沟通群", "user_name": "张三", "timestamp": 1786100000 } } } ] }, { "groupName": "面单余额", "module": "balance", "list": [ { "method": "inbox.callback.balance", "description": "面单余额回调。绑群成功后自动查询,或用户主动查询时推送面单余额。", "params": [], "response": [], "errors": [], "notes": [ "content 格式:面单余额:总量 {print_quantity},已锁定 {print_quantity_locked},可用 {available}", "ext_id 为 {原ext_id}:balance 后缀,避免与绑群确认回执冲突", "余额查询失败时 content:面单余额查询失败:{错误原因}" ], "example": { "method": "inbox.callback.balance", "code": 200, "data": { "source": "balance", "content": "面单余额:总量 5000,已锁定 200,可用 4800", "ext_id": "api:AK001:req-456:balance", "ext_data": null, "group_id": "wrchat-xxx", "user_id": "user-001", "group_name": "售后沟通群", "user_name": "张三", "timestamp": 1786100000 } } } ] }, { "groupName": "异常兜底", "module": "error", "list": [ { "method": "inbox.callback.error", "description": "异常兜底回调。AI 5轮推理均失败或系统异常时的兜底回复。", "params": [], "response": [], "errors": [], "notes": [ "content 为固定兜底文案:抱歉,暂时无法处理您的请求,请稍后重试", "出站前仍写入 wms_inbox_message.outbound 记录" ], "example": { "method": "inbox.callback.error", "code": 200, "data": { "source": "error", "content": "抱歉,暂时无法处理您的请求,请稍后重试", "ext_id": "api:AK001:req-789", "ext_data": null, "group_id": "wrchat-xxx", "user_id": "user-001", "group_name": "售后沟通群", "user_name": "张三", "timestamp": 1786100000 } } } ] }, { "groupName": "通用说明", "module": "common", "list": [ { "method": "inbox.callback.common", "description": "所有回调类型共有字段说明及路由指引。外部适配器根据 method 字段路由到不同处理逻辑。", "params": [ { "name": "method", "type": "string", "required": true, "source": "body", "description": "回调方法名,固定格式 inbox.callback.{source},外部适配器据此路由" }, { "name": "code", "type": "number", "required": true, "source": "body", "description": "状态码,正常回调固定 200" }, { "name": "data.source", "type": "string", "required": true, "source": "body", "description": "消息来源:ai_reply / bind_confirm / balance / error" }, { "name": "data.content", "type": "string", "required": true, "source": "body", "description": "回复正文(纯文本,含 \\n 换行)" }, { "name": "data.ext_id", "type": "string", "required": true, "source": "body", "description": "原始入站消息ID,关联对话链" }, { "name": "data.ext_data", "type": "object", "required": false, "source": "body", "description": "入站透传数据,原路带回" }, { "name": "data.group_id", "type": "string", "required": true, "source": "body", "description": "外部群ID" }, { "name": "data.user_id", "type": "string", "required": true, "source": "body", "description": "外部用户ID" }, { "name": "data.group_name", "type": "string", "required": true, "source": "body", "description": "群名称" }, { "name": "data.user_name", "type": "string", "required": true, "source": "body", "description": "用户名称" }, { "name": "data.timestamp", "type": "number", "required": true, "source": "body", "description": "出站 Unix 时间戳(秒)" } ], "response": [ { "name": "http_status", "type": "number", "required": true, "description": "HTTP 200 表示回调成功,WMS 更新 push_status=2" } ], "errors": [], "notes": [ "回调由 app/service/inbox/processor.js → writeOutboundReply() / handleApiMessage 发起", "callback_url 配置:wms_api_app.interface_type_id=3 AND is_enabled=1", "超时 10 秒,失败不影响消息记录写入", "HTTP 200 → 更新出站+入站 push_status=2(已送达)" ] } ] } ] } }