Agent 客户端接口

2026/10/28大约 6 分钟

Agent 客户端接口

服务：scrm-bus-server
前缀：/wscrm-bus-api/agent
用途：PC/客户端 Agent、知识库、统计、转人工等（非 OpenAPI）

通用说明

Header	是否必填	说明
accountId	是（管理类接口）	坐席 userId
tenantId	是（管理类接口）	公司 id
version	建议	对应 `t_version_manage.version_code`；未知/停用返回 403
Authorization	视版本	登录返回的 `account.token`；当该版本 `verify_token=1` 时必填

说明：

多数管理接口从 Header 取 accountId / tenantId，缺一不可。
/turn、/messages/sync 另用 Query tenantId。
坐席数据隔离：列表/统计仅本人；知识库可读公司共享；改删需本人创建（或主账号/管理员）。

环境变量（下文 curl 可替换）

HOST=http://192.168.1.6:10003
BASE={HOST}/wscrm-bus-api
accountId=802117
tenantId=533665
version=8510000
Authorization=<登录返回的 account.token>

一、统计 / 看板

1. Agent 统计

URI：GET /wscrm-bus-api/agent/stats
说明：总数 / 已启用 / 已关闭 / 未绑定；坐席仅本人

curl -X GET 'http://192.168.1.6:10003/wscrm-bus-api/agent/stats' \
  -H 'accountId: 802117' \
  -H 'tenantId: 533665' \
  -H 'version: 8510000' \
  -H 'Authorization: 你的token' \
  -H 'Accept: application/json'

2. 知识库统计

URI：GET /wscrm-bus-api/agent/knowledge/stats
说明：总数 / 可用(ready) / 处理中(queued|processing) / 需处理；坐席含本人私有 + 公司共享

curl -X GET 'http://192.168.1.6:10003/wscrm-bus-api/agent/knowledge/stats' \
  -H 'accountId: 802117' \
  -H 'tenantId: 533665' \
  -H 'version: 8510000' \
  -H 'Authorization: 你的token' \
  -H 'Accept: application/json'

3. 配置状态汇总

URI：GET /wscrm-bus-api/agent/config/status
说明：Agent / 客服号绑定 / 公司公共知识 / Core 运行状态

curl -X GET 'http://192.168.1.6:10003/wscrm-bus-api/agent/config/status' \
  -H 'accountId: 802117' \
  -H 'tenantId: 533665' \
  -H 'version: 8510000' \
  -H 'Authorization: 你的token' \
  -H 'Accept: application/json'

4. AI 运营日统计

URI：GET /wscrm-bus-api/agent/ops/daily
Query：userId 可选；坐席强制本人，主账号不传=汇总全部

curl -X GET 'http://192.168.1.6:10003/wscrm-bus-api/agent/ops/daily' \
  -H 'accountId: 802117' \
  -H 'tenantId: 533665' \
  -H 'version: 8510000' \
  -H 'Authorization: 你的token' \
  -H 'Accept: application/json'

curl -X GET 'http://192.168.1.6:10003/wscrm-bus-api/agent/ops/daily?userId=802117' \
  -H 'accountId: 主账号userId' \
  -H 'tenantId: 533665' \
  -H 'version: 8510000' \
  -H 'Authorization: 你的token' \
  -H 'Accept: application/json'

二、Agent 管理

5. Agent 分页列表

URI：GET /wscrm-bus-api/agent/list
Query：current size name autoReplyEnabled userId agentId

curl -X GET 'http://192.168.1.6:10003/wscrm-bus-api/agent/list?current=1&size=10' \
  -H 'accountId: 802117' \
  -H 'tenantId: 533665' \
  -H 'version: 8510000' \
  -H 'Authorization: 你的token' \
  -H 'Accept: application/json'

6. 创建 Agent

URI：POST /wscrm-bus-api/agent/create
Body：name description personaPrompt businessBoundary autoReplyEnabled autoReplyModelMode(economy/smart/quality)

curl -X POST 'http://192.168.1.6:10003/wscrm-bus-api/agent/create' \
  -H 'accountId: 802117' \
  -H 'tenantId: 533665' \
  -H 'version: 8510000' \
  -H 'Authorization: 你的token' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "测试Agent",
    "description": "desc",
    "personaPrompt": "你是客服助手",
    "businessBoundary": "仅回答产品相关",
    "autoReplyEnabled": true,
    "autoReplyModelMode": "economy"
  }'

7. 修改 Agent

URI：PUT /wscrm-bus-api/agent/update
Body：需 id 或 agentId

curl -X PUT 'http://192.168.1.6:10003/wscrm-bus-api/agent/update' \
  -H 'accountId: 802117' \
  -H 'tenantId: 533665' \
  -H 'version: 8510000' \
  -H 'Authorization: 你的token' \
  -H 'Content-Type: application/json' \
  -d '{
    "agentId": "agt_xxx",
    "name": "测试Agent-改",
    "autoReplyEnabled": true,
    "autoReplyModelMode": "smart"
  }'

8. 修改自动回复开关

URI：PUT /wscrm-bus-api/agent/autoReply

curl -X PUT 'http://192.168.1.6:10003/wscrm-bus-api/agent/autoReply' \
  -H 'accountId: 802117' \
  -H 'tenantId: 533665' \
  -H 'version: 8510000' \
  -H 'Authorization: 你的token' \
  -H 'Content-Type: application/json' \
  -d '{
    "agentId": "agt_xxx",
    "autoReplyEnabled": false
  }'

9. 删除 Agent

URI：DELETE /wscrm-bus-api/agent/delete

curl -X DELETE 'http://192.168.1.6:10003/wscrm-bus-api/agent/delete?agentId=agt_xxx' \
  -H 'accountId: 802117' \
  -H 'tenantId: 533665' \
  -H 'version: 8510000' \
  -H 'Authorization: 你的token' \
  -H 'Accept: application/json'

三、客服号绑定

10. 绑定客服号

URI：POST /wscrm-bus-api/agent/account/bind

curl -X POST 'http://192.168.1.6:10003/wscrm-bus-api/agent/account/bind' \
  -H 'accountId: 802117' \
  -H 'tenantId: 533665' \
  -H 'version: 8510000' \
  -H 'Authorization: 你的token' \
  -H 'Content-Type: application/json' \
  -d '{
    "agentId": "agt_xxx",
    "accountId": "客服号whatsId"
  }'

11. 解绑客服号

URI：POST /wscrm-bus-api/agent/account/unbind

curl -X POST 'http://192.168.1.6:10003/wscrm-bus-api/agent/account/unbind' \
  -H 'accountId: 802117' \
  -H 'tenantId: 533665' \
  -H 'version: 8510000' \
  -H 'Authorization: 你的token' \
  -H 'Content-Type: application/json' \
  -d '{
    "agentId": "agt_xxx",
    "accountId": "客服号whatsId"
  }'

12. 查询已绑定客服号

URI：GET /wscrm-bus-api/agent/account/list

curl -X GET 'http://192.168.1.6:10003/wscrm-bus-api/agent/account/list?agentId=agt_xxx' \
  -H 'accountId: 802117' \
  -H 'tenantId: 533665' \
  -H 'version: 8510000' \
  -H 'Authorization: 你的token' \
  -H 'Accept: application/json'

四、知识库

13. 知识库分页列表

URI：GET /wscrm-bus-api/agent/knowledge/list
Query：current size agentId title sharedWithinTenant parseStatus userId
parseStatus：queued / processing / ready / partial / failed / cancelled

curl -X GET 'http://192.168.1.6:10003/wscrm-bus-api/agent/knowledge/list?current=1&size=10' \
  -H 'accountId: 802117' \
  -H 'tenantId: 533665' \
  -H 'version: 8510000' \
  -H 'Authorization: 你的token' \
  -H 'Accept: application/json'

curl -X GET 'http://192.168.1.6:10003/wscrm-bus-api/agent/knowledge/list?current=1&size=10&parseStatus=queued' \
  -H 'accountId: 802117' \
  -H 'tenantId: 533665' \
  -H 'version: 8510000' \
  -H 'Authorization: 你的token' \
  -H 'Accept: application/json'

14. 导入知识库（文本 / QA / 网站 / fileUrls）

URI：POST /wscrm-bus-api/agent/knowledge/import
私有知识必传 agentId；公司共享 sharedWithinTenant=true 且不要传 agentId

curl -X POST 'http://192.168.1.6:10003/wscrm-bus-api/agent/knowledge/import' \
  -H 'accountId: 802117' \
  -H 'tenantId: 533665' \
  -H 'version: 8510000' \
  -H 'Authorization: 你的token' \
  -H 'Content-Type: application/json' \
  -d '{
    "agentId": "agt_xxx",
    "sharedWithinTenant": false,
    "name": "QA导入",
    "qaList": [
      { "question": "你们几点上班？", "answer": "周一到周五 9:00-18:00" }
    ],
    "aiEnhanced": false
  }'

15. 上传知识文件到 Core

URI：POST /wscrm-bus-api/agent/knowledge/upload
Content-Type：multipart/form-data
表单字段：file 必填；agentId / sharedWithinTenant / aiEnhanced 可选

curl -X POST 'http://192.168.1.6:10003/wscrm-bus-api/agent/knowledge/upload' \
  -H 'accountId: 802117' \
  -H 'tenantId: 533665' \
  -H 'version: 8510000' \
  -H 'Authorization: 你的token' \
  -F 'file=@/path/to/doc.pdf' \
  -F 'agentId=agt_xxx' \
  -F 'sharedWithinTenant=false' \
  -F 'aiEnhanced=false'

16. 上传知识文件到 OSS（不调 Core）

URI：POST /wscrm-bus-api/agent/knowledge/file/upload
返回 fileUrl，再用于 /knowledge/import 的 fileUrls

curl -X POST 'http://192.168.1.6:10003/wscrm-bus-api/agent/knowledge/file/upload' \
  -H 'accountId: 802117' \
  -H 'tenantId: 533665' \
  -H 'version: 8510000' \
  -H 'Authorization: 你的token' \
  -F 'file=@/path/to/doc.pdf' \
  -F 'agentId=agt_xxx'

17. 修改知识库

URI：PUT /wscrm-bus-api/agent/knowledge/update
Body：id 或 sourceId；可改 title / 内容差分字段

curl -X PUT 'http://192.168.1.6:10003/wscrm-bus-api/agent/knowledge/update' \
  -H 'accountId: 802117' \
  -H 'tenantId: 533665' \
  -H 'version: 8510000' \
  -H 'Authorization: 你的token' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": 142,
    "title": "QA导入-改"
  }'

18. 删除知识库

URI：DELETE /wscrm-bus-api/agent/knowledge/delete
说明：被 Agent 使用中可能无法删除

curl -X DELETE 'http://192.168.1.6:10003/wscrm-bus-api/agent/knowledge/delete?id=142' \
  -H 'accountId: 802117' \
  -H 'tenantId: 533665' \
  -H 'version: 8510000' \
  -H 'Authorization: 你的token' \
  -H 'Accept: application/json'

五、转人工

19. 转人工记录分页

URI：GET /wscrm-bus-api/agent/handoff/list
Query：current size userId accountId contactId status(0未处理/1已处理/2超时) action(handoff/review)

curl -X GET 'http://192.168.1.6:10003/wscrm-bus-api/agent/handoff/list?current=1&size=10' \
  -H 'accountId: 802117' \
  -H 'tenantId: 533665' \
  -H 'version: 8510000' \
  -H 'Authorization: 你的token' \
  -H 'Accept: application/json'

20. 上报转人工已处理

URI：POST /wscrm-bus-api/agent/handoff/process

curl -X POST 'http://192.168.1.6:10003/wscrm-bus-api/agent/handoff/process' \
  -H 'accountId: 802117' \
  -H 'tenantId: 533665' \
  -H 'version: 8510000' \
  -H 'Authorization: 你的token' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountId": "客服号whatsId",
    "contactId": "联系人id"
  }'

六、对话 / 反馈（运行时）

21. AI 回复 turn

URI：POST /wscrm-bus-api/agent/turn?tenantId={tenantId}
说明：传了 agentId 直接用；未传按客服号绑定查；employeeId 空时用 Header accountId 回填

curl -X POST 'http://192.168.1.6:10003/wscrm-bus-api/agent/turn?tenantId=533665' \
  -H 'accountId: 802117' \
  -H 'tenantId: 533665' \
  -H 'version: 8510000' \
  -H 'Authorization: 你的token' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountId": "客服号whatsId",
    "contactId": "联系人id",
    "text": "你好"
  }'

22. 同步历史消息

URI：POST /wscrm-bus-api/agent/messages/sync?tenantId={tenantId}

curl -X POST 'http://192.168.1.6:10003/wscrm-bus-api/agent/messages/sync?tenantId=533665' \
  -H 'accountId: 802117' \
  -H 'tenantId: 533665' \
  -H 'version: 8510000' \
  -H 'Authorization: 你的token' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountId": "客服号whatsId",
    "contactId": "联系人id",
    "messages": []
  }'

23. 反馈纠错

URI：POST /wscrm-bus-api/agent/feedback

curl -X POST 'http://192.168.1.6:10003/wscrm-bus-api/agent/feedback' \
  -H 'accountId: 802117' \
  -H 'tenantId: 533665' \
  -H 'version: 8510000' \
  -H 'Authorization: 你的token' \
  -H 'Content-Type: application/json' \
  -d '{
    "agentId": "agt_xxx",
    "decisionId": "dec_xxx",
    "conversationId": "conv_xxx",
    "contactId": "联系人id",
    "feedbackType": "revise",
    "comment": "答错了",
    "revisedText": "正确回复内容"
  }'

接口一览

#	方法	路径	说明
1	GET	/agent/stats	Agent 统计
2	GET	/agent/knowledge/stats	知识库统计
3	GET	/agent/config/status	配置状态汇总
4	GET	/agent/ops/daily	运营日统计
5	GET	/agent/list	Agent 分页
6	POST	/agent/create	创建 Agent
7	PUT	/agent/update	修改 Agent
8	PUT	/agent/autoReply	自动回复开关
9	DELETE	/agent/delete	删除 Agent
10	POST	/agent/account/bind	绑定客服号
11	POST	/agent/account/unbind	解绑客服号
12	GET	/agent/account/list	绑定列表
13	GET	/agent/knowledge/list	知识库分页
14	POST	/agent/knowledge/import	导入知识
15	POST	/agent/knowledge/upload	上传文件到 Core
16	POST	/agent/knowledge/file/upload	上传文件到 OSS
17	PUT	/agent/knowledge/update	改知识库
18	DELETE	/agent/knowledge/delete	删知识库
19	GET	/agent/handoff/list	转人工列表
20	POST	/agent/handoff/process	转人工已处理
21	POST	/agent/turn	AI 回复
22	POST	/agent/messages/sync	同步历史消息
23	POST	/agent/feedback	反馈纠错

常见错误

HTTP/业务	原因
403 Forbidden	`version` 不在 `t_version_manage` 或 `active_status=0`
401	版本 `verify_token=1` 且未带有效 `Authorization`；或网关/OAuth 要求登录
AGENT_HEADER_ACCOUNT_TENANT_REQUIRED	缺 `accountId` 或 `tenantId`
AGENT_NO_PERMISSION (2090)	坐席改删他人 Agent/知识库