跳转到内容

在线客服

面向客服工作台的接口:配置接入渠道、维护文本机器人、接管访客会话、收发消息、查询访客与关联客户。所有接口都在 /api/app/chat 下,复用 App 登录 JWT,按细粒度权限点鉴权。

创建、编辑、删除接入渠道(一期仅支持 web,后续加微信 / 小程序等)。channel_key 是访客端 SDK 用来识别渠道的字符串,创建时由后端生成。所有渠道管理接口需要 chat.channel_manage 权限。

接口清单
GET/api/app/chat/channel-configs
列出本企业全部渠道
POST/api/app/chat/channel-configs
新建渠道,后端自动生成 channel_key
PUT/api/app/chat/channel-configs/:id
更新渠道配置
DELETE/api/app/chat/channel-configs/:id
删除渠道
请求体(POST / PUT)
channelstring必填
渠道类型,当前仅支持 web
namestring必填
渠道名称(用于工作台展示)
reception_modestring必填
接待方式:ai_first / human_first / ai_only / human_only
agent_idint可选
接待方式含 AI 时必填,指向文本机器人 ID
welcome_textstring可选
访客打开对话框时展示的欢迎语,SDK 侧本地渲染,不写入消息记录
enabledbool必填
是否启用;关闭后 SDK init 会返回 chat_channel_disabled
configstring可选
渠道自定义配置(JSON 字符串)

文本机器人用于在线客服的自动接待,与语音 Agent 共用一张表,但只用到 LLM 相关字段。创建后类型(文本 / 语音)不可修改,尝试修改会返回 agent_modality_immutable。

接口清单
GET/api/app/chat/agents权限 agent.list
列出本企业全部文本机器人
POST/api/app/chat/agents权限 agent.create
创建文本机器人(modality 固定为 text)
PUT/api/app/chat/agents/:id权限 agent.edit
更新文本机器人
请求体(POST / PUT)
namestring必填
机器人名称
greetingstring可选
首条自动招呼语
promptstring必填
System Prompt,支持 Prompt 变量
llm_idint必填
使用的大模型配置 ID
compress_thresholdint可选
对话轮数达到该值时压缩历史,10-100
compress_keepint可选
压缩后保留的最近轮数,4-50
toolsarray可选
工具配置,与语音 Agent 一致
chat_configstring可选
文本会话专有参数(JSON 字符串):typing_delay_ms / max_reply_len / session_timeout_min

工作台的会话列表 / 详情 / 接入 / 转移 / 关闭 / 标记已读接口。会话主键对外一律用 uuid。

接口清单
GET/api/app/chat/conversations权限 chat.list
会话列表,支持 view=mine/queuing/all + status / channel / keyword 过滤
GET/api/app/chat/conversations/:uuid权限 chat.view
会话详情
POST/api/app/chat/conversations/:uuid/claim权限 chat.claim
接入排队中的会话,冲突返回 chat_claim_conflict
POST/api/app/chat/conversations/:uuid/transfer权限 chat.transfer
转会话:target_type=user 转其它客服,target_type=agent 转 AI 机器人
POST/api/app/chat/conversations/:uuid/close权限 chat.close
关闭会话,可选 reason=manual/timeout/system
POST/api/app/chat/conversations/:uuid/read权限 chat.view
将当前会话未读消息标记为已读

会话状态

queuing ai_serving agent_serving closed

已 closed 的会话不能 claim / transfer / reply,尝试操作返回 chat_conversation_closed。

拉取会话消息与客服回复。列表使用 keyset 分页(before 传上一次拿到的最小 message id)。回复接口需 chat.reply 权限。

接口清单
GET/api/app/chat/conversations/:uuid/messages?before=&limit=权限 chat.view
拉取会话消息,默认 limit=50
POST/api/app/chat/conversations/:uuid/messages权限 chat.reply
客服回复消息
回复请求体
content_typestring必填
消息类型:text / image / file
payloadobject必填
消息负载:text 用 {text},image/file 用 {url,name?,size?}
消息响应字段
idint
消息主键,可作为下一次分页 before 参数
conv_uuidstring
所属会话 uuid
channelstring
来源渠道
channel_msg_idstring
渠道内幂等 ID(重传去重用)
sender_typestring
customer / user / agent / system
sender_idint
发送者 ID(customer 时为访客 ID,user 时为客服 ID,agent 时为机器人 ID)
sender_display_namestring
发送者展示名
content_typestring
text / image / file
payloadobject
消息负载,结构随 content_type 变
read_atstring
已读时间(RFC3339)
created_atstring
创建时间(RFC3339)

访客与客户的关系是可选关联:访客首次发消息即入库,如通过 user_info 匹配到已有客户档案(手机号 / 邮箱等),会自动挂到客户上;未匹配的访客保留独立记录,后续可在工作台手动关联。

接口清单
GET/api/app/chat/visitors权限 chat.list
访客列表,支持 keyword / channel / page / page_size 过滤
GET/api/app/chat/visitors/:id权限 chat.view
访客详情
GET/api/app/chat/visitors/:id/conversations权限 chat.view
该访客的历史会话列表
GET/api/app/chat/customers/:id/conversations权限 chat.view
该客户名下所有关联访客的会话列表

鄂ICP备2022005956号-2