客服云 API 文档

开放接口 v1 · 供前端 SDK / 小程序 / 租户服务端集成。所有 JSON 请求均携带 Content-Type: application/json。

简介

客服云提供三类接口：

Base URL 与鉴权

Host: https://你的域名
鉴权头(管理接口):  Authorization: Bearer <登录返回的 access_token>
鉴权头(开放接口):  Authorization: Bearer <企业后台「接入配置」重新生成的 api_token>

一、公开接口（无需鉴权）

GET/api/public/{slug}/brand
获取租户品牌配置（悬浮窗 / 小程序样式动态渲染，支持主题色、Logo、欢迎语、客服信息等）。
参数说明
slug路径参数，企业标识，如 your-brand
curl https://你的域名/api/public/demo/brand
// =>
{"brand_name":"演示企业","brand_color":"#2962ff","brand_logo":"","welcome_title":"您好，欢迎咨询演示企业","welcome_text":"我们在线，很高兴为您服务。请描述您的问题。","enable_file_upload":true,"enable_rating":true,...}
POST/api/public/{slug}/ticket
访客创建会话凭证，换取 conversation_id / customer_id / ws_url，随后建立 WebSocket 连接。
参数类型说明
external_idstring访客外部唯一标识（业务侧带来，可选）
nicknamestring访客昵称，默认“访客”
channelstringweb / miniprogram / app，默认 web
curl -X POST https://你的域名/api/public/demo/ticket \
  -H "Content-Type: application/json" -d '{"external_id":"u_10086","nickname":"张三","channel":"web"}'
// => {"conversation_id":12,"customer_id":34,"tenant_id":5,"ws_url":"/ws/customer/demo?external_id=u_10086&nickname=张三"}
GET/api/public/{slug}/history?conversation_id={id}
按会话拉取历史消息（接入前展示历史）。
POST/api/public/{slug}/upload?kind=image|file
访客图片 / 文件真实上传，返回可访问 URL（租户隔离，带魔数校验）。
参数说明
filemultipart/form-data 文件字段
kindimage / file
// 表单二进制上传
POST /api/public/demo/upload?kind=image  (multipart: file=@photo.jpg)
// => {"url":"/uploads/tenants/1/2026/09/uuid.jpg","name":"photo.jpg","size":10240,"ext":"jpg"}
GET/api/plans
查询在售套餐（公开），用于价格展示。
curl https://你的域名/api/plans
// => [{"slug":"trial","name":"体验版","agent_quota":1,"bot_enabled":false,"price_cents":0,"billing_cycle":"month",...}]
POST/api/auth/register
申请接入：注册即自动创建租户 + 管理员座席，返回 JWT。
curl -X POST https://你的域名/api/auth/register -H "Content-Type: application/json" \
  -d '{"email":"a@x.com","password":"pass123456","tenant_name":"我的公司","tenant_slug":"mybrand","nickname":"管理员"}'
// => {"access_token":"eyJ...","token_type":"bearer"}
POST/api/auth/login
登录，返回 JWT，用于后续管理接口。account 可为邮箱或手机号。
curl -X POST https://你的域名/api/auth/login -H "Content-Type: application/json" \
  -d '{"account":"a@x.com","password":"pass123456"}'
// => {"access_token":"eyJ...","token_type":"bearer"}

二、租户开放接口（服务端集成）

使用企业后台「接入配置」中生成的 api_token，攻击面隔离于租户，用于你自有系统对接，例如工单系统把处理结果推回会话。

GET/api/openapi/me
校验 token 并读取当前租户信息与品牌。
GET/api/openapi/conversations?status=&page=&page_size=
列出本租户会话。status 可取 open / pending / closed。
GET/api/openapi/conversations/{cid}/messages
读取某会话全部消息。
POST/api/openapi/conversations/messages
以 system 身份向会话推送消息，可直接展示给访客（适合机器人 / 工单同步）。
curl -X POST https://你的域名/api/openapi/conversations/messages \
  -H "Authorization: Bearer kf_xxxx" -H "Content-Type: application/json" \
  -d '{"conversation_id":12,"content":"您的工单已处理完成，感谢耐心等待。","msg_type":"text"}'
// => {"id":88}

三、管理接口（企业后台 / 座席）

GET/api/auth/me
当前登录用户信息，含 is_staff 与 tenant。
GET / PUT/api/tenant/settings
读取 / 更新租户配置（品牌、欢迎语、开关）。GET 返回 defs(每项 key/label/type/value) 与 brand。
POST/api/tenant/apikey/regenerate
重新生成开放接口 api_token。
POST/api/upload?kind=image|file|avatar|doc
鉴权上传：品牌 Logo、头像、知识库文档等后台资源。

会话

GET/api/agent/conversations?status=&agent_id=&keyword=&page=&page_size=
会话列表（含状态/客户名/最后消息/更新时间）。
GET/api/agent/conversations/{cid}/messages?before=&limit=
读取会话消息（cursor 分页）。
POST/api/agent/conversations/{cid}/transfer
转接会话。{"target_agent_id":2}
POST/api/agent/conversations/{cid}/close
关闭会话。

坐席团队

GET/api/agent/team
团队坐席列表。
POST / PUT / DELETE/api/agent/team[/{id}]
新增 / 编辑 / 删除坐席。

知识库与 AI

GET / POST / PUT / DELETE/api/agent/kb
知识库文档 CRUD。
POST/api/agent/kb/upload
上传文档（multipart）。
POST/api/agent/kb/{id}/embed
将文档向量化（用于检索）。
POST/api/agent/kb/search
语义检索。{"query":"退换货流程","top_k":5}
GET/api/agent/usage/ai
AI 用量统计。

套餐/订单

POST/api/agent/order
下单。{"plan_slug":"pro"} 返回 order_no。
GET/api/agent/orders
我的订单。
GET/api/pay/channels
真实支付渠道及配置状态（支付宝/微信/易支付/Stripe）。
POST/api/pay/create/{order_no}
调用支付网关真实下单，返回二维码/支付链接/收银台。渠道未配置返回真实错误。
POST/api/pay/notify/{channel}
支付网关异步回调，验签成功后幂等激活订单（到账/开通套餐）。
GET/api/pay/return
付款完成后的返回落地页。

四、WebSocket 实时协议

wss://你的域名/ws/customer/{slug}?external_id=&nickname=&
访客连接。Client→Server：{type:"message",content,msg_type:"text|image|file",meta}、{type:"read",conversation_id,last_message_id}、{type:"ping"}。Server→Client：{type:"message",data:{id,sender_role,msg_type,content,meta_json,created_at}}。
wss://你的域名/ws/agent?token={JWT}
座席连接。连接即收 {type:"conversations",data:[...]}；可发 message / take / close / ping；收 message / read / taken / closed。

五、前端接入（js SDK）

<!-- 在官网任意位置粘贴即可，样式自动跟随品牌 -->
<script src="https://你的域名/sdk/widget.js" data-slug="your-brand"></script>
全屏聊天页：/chat.html?slug=your-brand。uni-app 组件见工程 c-sdk/kefuChat.vue。