在线客服
面向客服工作台的接口:配置接入渠道、维护文本机器人、接管访客会话、收发消息、查询访客与关联客户。所有接口都在 /api/app/chat 下,复用 App 登录 JWT,按细粒度权限点鉴权。
接入渠道管理
Section titled “接入渠道管理”创建、编辑、删除接入渠道(一期仅支持 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_typestringcustomer / user / agent / system
sender_idint发送者 ID(customer 时为访客 ID,user 时为客服 ID,agent 时为机器人 ID)
sender_display_namestring发送者展示名
content_typestringtext / 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该客户名下所有关联访客的会话列表