895 lines
24 KiB
YAML
895 lines
24 KiB
YAML
openapi: 3.0.3
|
||
info:
|
||
title: Multi-Channel Customer Service API
|
||
description: |
|
||
多渠道客服主框架对外提供的 API 契约。
|
||
|
||
本文件定义主框架对外提供的能力（Provider）：
|
||
- 渠道消息回调接口（微信、抖音、京东等）
|
||
- 人工客服工作台 REST API
|
||
- WebSocket 实时通信协议说明
|
||
version: 1.0.0
|
||
x-contract-level: L2
|
||
x-consumer: "frontend, wechat-server, douyin-server, jd-server"
|
||
x-provider: "java-main-framework"
|
||
|
||
servers:
|
||
- url: http://{host}:{port}
|
||
description: |
|
||
服务地址占位符，根据环境替换：
|
||
- 开发环境: http://localhost:8080
|
||
- 测试环境: http://ai-robot-test:8080
|
||
- 生产环境: http://ai-robot:8080
|
||
variables:
|
||
host:
|
||
default: localhost
|
||
description: 服务主机名
|
||
port:
|
||
default: "8080"
|
||
description: 服务端口
|
||
|
||
tags:
|
||
- name: Channel Callback
|
||
description: 渠道消息回调接口
|
||
- name: Session Management
|
||
description: 会话管理接口
|
||
- name: WebSocket
|
||
description: WebSocket 实时通信
|
||
|
||
paths:
|
||
/wecom/callback:
|
||
get:
|
||
operationId: verifyWecomUrl
|
||
summary: 微信回调 URL 验证
|
||
description: |
|
||
企业微信回调 URL 验证接口。
|
||
|
||
用于验证回调 URL 的有效性，企业微信在配置回调时会发送 GET 请求。
|
||
tags:
|
||
- Channel Callback
|
||
parameters:
|
||
- name: msg_signature
|
||
in: query
|
||
required: true
|
||
schema:
|
||
type: string
|
||
minLength: 1
|
||
maxLength: 128
|
||
description: 消息签名，用于验证请求来源
|
||
- name: timestamp
|
||
in: query
|
||
required: true
|
||
schema:
|
||
type: string
|
||
pattern: '^\d+$'
|
||
description: 时间戳（秒级），用于防重放攻击
|
||
- name: nonce
|
||
in: query
|
||
required: true
|
||
schema:
|
||
type: string
|
||
minLength: 1
|
||
maxLength: 64
|
||
description: 随机字符串，用于防重放攻击
|
||
- name: echostr
|
||
in: query
|
||
required: true
|
||
schema:
|
||
type: string
|
||
minLength: 1
|
||
description: 加密的随机字符串，验证成功后需解密返回
|
||
responses:
|
||
'200':
|
||
description: 验证成功，返回解密后的 echostr
|
||
content:
|
||
text/plain:
|
||
schema:
|
||
type: string
|
||
example: "1234567890"
|
||
'400':
|
||
description: 请求参数错误
|
||
content:
|
||
text/plain:
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- error
|
||
'401':
|
||
description: 签名验证失败
|
||
content:
|
||
text/plain:
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- error
|
||
'500':
|
||
description: 服务器内部错误
|
||
content:
|
||
text/plain:
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- error
|
||
|
||
post:
|
||
operationId: handleWecomCallback
|
||
summary: 微信回调消息处理
|
||
description: |
|
||
企业微信回调消息处理入口。
|
||
|
||
覆盖验收标准：
|
||
- AC-MCA-08: 根据渠道类型路由到对应的渠道适配器
|
||
|
||
消息处理流程：
|
||
1. 接收加密的 XML 消息
|
||
2. 解密并解析消息内容
|
||
3. 根据消息类型路由处理
|
||
4. 返回 success 确认
|
||
tags:
|
||
- Channel Callback
|
||
x-requirements:
|
||
- AC-MCA-08
|
||
parameters:
|
||
- name: msg_signature
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: string
|
||
maxLength: 128
|
||
description: 消息签名（用于验签）
|
||
- name: timestamp
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: string
|
||
pattern: '^\d+$'
|
||
description: 时间戳（用于防重放）
|
||
- name: nonce
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: string
|
||
maxLength: 64
|
||
description: 随机数（用于防重放）
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/xml:
|
||
schema:
|
||
type: string
|
||
description: 加密的 XML 消息
|
||
example: "<xml><Encrypt>...</Encrypt></xml>"
|
||
responses:
|
||
'200':
|
||
description: 处理成功
|
||
content:
|
||
text/plain:
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- success
|
||
'400':
|
||
description: 请求格式错误
|
||
content:
|
||
text/plain:
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- success
|
||
'401':
|
||
description: 签名验证失败
|
||
content:
|
||
text/plain:
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- success
|
||
'500':
|
||
description: 服务器内部错误（仍返回 success 以避免微信重试）
|
||
content:
|
||
text/plain:
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- success
|
||
|
||
/channel/{channelType}/callback:
|
||
post:
|
||
operationId: handleChannelCallback
|
||
summary: 通用渠道回调接口（预留）
|
||
description: |
|
||
通用渠道消息回调接口，用于接入新渠道。
|
||
|
||
当前为预留接口，后续实现抖音、京东等渠道时使用。
|
||
|
||
### 鉴权/签名机制（各渠道实现时需补充）
|
||
不同渠道需要不同的验签方式，建议通过以下方式传递：
|
||
|
||
**方式一：Header 传递**
|
||
- `X-Signature`: 消息签名
|
||
- `X-Timestamp`: 时间戳（防重放）
|
||
- `X-Nonce`: 随机数（防重放）
|
||
|
||
**方式二：Query 参数传递**
|
||
- `signature`: 消息签名
|
||
- `timestamp`: 时间戳
|
||
- `nonce`: 随机数
|
||
|
||
**方式三：Body 内嵌**
|
||
- requestBody 中包含 `rawPayload` + `signature` 字段
|
||
|
||
具体签名算法（HMAC-SHA256、RSA 等）由各渠道适配器实现时确定。
|
||
tags:
|
||
- Channel Callback
|
||
parameters:
|
||
- name: channelType
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- wechat
|
||
- douyin
|
||
- jd
|
||
description: 渠道类型
|
||
- name: X-Signature
|
||
in: header
|
||
required: false
|
||
schema:
|
||
type: string
|
||
maxLength: 256
|
||
description: 消息签名（可选，具体由渠道决定）
|
||
- name: X-Timestamp
|
||
in: header
|
||
required: false
|
||
schema:
|
||
type: string
|
||
pattern: '^\d+$'
|
||
description: 时间戳（可选，用于防重放）
|
||
- name: X-Nonce
|
||
in: header
|
||
required: false
|
||
schema:
|
||
type: string
|
||
maxLength: 64
|
||
description: 随机数（可选，用于防重放）
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
description: 渠道消息体（格式由各渠道定义）
|
||
responses:
|
||
'200':
|
||
description: 处理成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ApiResponse'
|
||
'400':
|
||
description: 请求格式错误
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ApiResponse'
|
||
'401':
|
||
description: 签名验证失败
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ApiResponse'
|
||
'404':
|
||
description: 不支持的渠道类型
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ApiResponse'
|
||
'500':
|
||
description: 服务器内部错误
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ApiResponse'
|
||
|
||
/api/sessions:
|
||
get:
|
||
operationId: getSessions
|
||
summary: 获取会话列表
|
||
description: |
|
||
获取客服工作台的会话列表。
|
||
|
||
覆盖验收标准：
|
||
- AC-MCA-12: 支持按渠道类型筛选
|
||
tags:
|
||
- Session Management
|
||
x-requirements:
|
||
- AC-MCA-12
|
||
parameters:
|
||
- name: status
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- ai
|
||
- pending
|
||
- manual
|
||
- closed
|
||
description: 会话状态筛选
|
||
- name: csId
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: string
|
||
maxLength: 64
|
||
description: 客服ID筛选
|
||
- name: channelType
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- wechat
|
||
- douyin
|
||
- jd
|
||
description: 渠道类型筛选
|
||
responses:
|
||
'200':
|
||
description: 成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/SessionListResponse'
|
||
'400':
|
||
description: 请求参数错误
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ApiResponse'
|
||
'500':
|
||
description: 服务器内部错误
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ApiResponse'
|
||
|
||
/api/sessions/{sessionId}:
|
||
get:
|
||
operationId: getSession
|
||
summary: 获取会话详情
|
||
description: |
|
||
获取指定会话的详细信息。
|
||
tags:
|
||
- Session Management
|
||
parameters:
|
||
- name: sessionId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
minLength: 1
|
||
maxLength: 64
|
||
description: 会话ID
|
||
responses:
|
||
'200':
|
||
description: 成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/SessionResponse'
|
||
'400':
|
||
description: 请求参数错误
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ApiResponse'
|
||
'404':
|
||
description: 会话不存在
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ApiResponse'
|
||
'500':
|
||
description: 服务器内部错误
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ApiResponse'
|
||
|
||
/api/sessions/{sessionId}/history:
|
||
get:
|
||
operationId: getSessionHistory
|
||
summary: 获取会话消息历史
|
||
description: |
|
||
获取指定会话的消息历史记录。
|
||
tags:
|
||
- Session Management
|
||
parameters:
|
||
- name: sessionId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
minLength: 1
|
||
maxLength: 64
|
||
description: 会话ID
|
||
responses:
|
||
'200':
|
||
description: 成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/MessageListResponse'
|
||
'400':
|
||
description: 请求参数错误
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ApiResponse'
|
||
'404':
|
||
description: 会话不存在
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ApiResponse'
|
||
'500':
|
||
description: 服务器内部错误
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ApiResponse'
|
||
|
||
/api/sessions/{sessionId}/accept:
|
||
post:
|
||
operationId: acceptSession
|
||
summary: 接入会话
|
||
description: |
|
||
客服接入待处理的会话。
|
||
|
||
仅状态为 `pending` 的会话可被接入。
|
||
tags:
|
||
- Session Management
|
||
parameters:
|
||
- name: sessionId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
minLength: 1
|
||
maxLength: 64
|
||
description: 会话ID
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required:
|
||
- csId
|
||
properties:
|
||
csId:
|
||
type: string
|
||
minLength: 1
|
||
maxLength: 64
|
||
description: 客服ID
|
||
example:
|
||
csId: "cs_001"
|
||
responses:
|
||
'200':
|
||
description: 接入成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ApiResponse'
|
||
'400':
|
||
description: 会话状态不正确或参数错误
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ApiResponse'
|
||
examples:
|
||
invalid_status:
|
||
value:
|
||
code: 400
|
||
message: "会话状态不正确"
|
||
missing_csId:
|
||
value:
|
||
code: 400
|
||
message: "客服ID不能为空"
|
||
'404':
|
||
description: 会话不存在
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ApiResponse'
|
||
example:
|
||
code: 404
|
||
message: "会话不存在"
|
||
'500':
|
||
description: 服务器内部错误
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ApiResponse'
|
||
|
||
/api/sessions/{sessionId}/message:
|
||
post:
|
||
operationId: sendSessionMessage
|
||
summary: 发送消息
|
||
description: |
|
||
客服向会话发送消息。
|
||
|
||
仅状态为 `manual` 的会话可发送消息。
|
||
tags:
|
||
- Session Management
|
||
parameters:
|
||
- name: sessionId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
minLength: 1
|
||
maxLength: 64
|
||
description: 会话ID
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required:
|
||
- content
|
||
properties:
|
||
content:
|
||
type: string
|
||
minLength: 1
|
||
maxLength: 4096
|
||
description: 消息内容
|
||
msgType:
|
||
type: string
|
||
enum:
|
||
- text
|
||
- image
|
||
- file
|
||
default: text
|
||
description: 消息类型
|
||
example:
|
||
content: "您好，请问有什么可以帮助您的？"
|
||
msgType: "text"
|
||
responses:
|
||
'200':
|
||
description: 发送成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ApiResponse'
|
||
'400':
|
||
description: 会话状态不正确或参数错误
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ApiResponse'
|
||
examples:
|
||
invalid_status:
|
||
value:
|
||
code: 400
|
||
message: "会话状态不正确"
|
||
missing_content:
|
||
value:
|
||
code: 400
|
||
message: "消息内容不能为空"
|
||
'404':
|
||
description: 会话不存在
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ApiResponse'
|
||
'500':
|
||
description: 服务器内部错误或消息发送失败
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ApiResponse'
|
||
|
||
/api/sessions/{sessionId}/close:
|
||
post:
|
||
operationId: closeSession
|
||
summary: 关闭会话
|
||
description: |
|
||
关闭指定的会话。
|
||
tags:
|
||
- Session Management
|
||
parameters:
|
||
- name: sessionId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
minLength: 1
|
||
maxLength: 64
|
||
description: 会话ID
|
||
responses:
|
||
'200':
|
||
description: 关闭成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ApiResponse'
|
||
'400':
|
||
description: 请求参数错误
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ApiResponse'
|
||
'404':
|
||
description: 会话不存在
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ApiResponse'
|
||
'500':
|
||
description: 服务器内部错误
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ApiResponse'
|
||
|
||
components:
|
||
schemas:
|
||
ApiResponse:
|
||
type: object
|
||
required:
|
||
- code
|
||
- message
|
||
properties:
|
||
code:
|
||
type: integer
|
||
description: 响应码（0=成功，非0=失败）
|
||
enum:
|
||
- 0
|
||
- 400
|
||
- 404
|
||
- 500
|
||
message:
|
||
type: string
|
||
minLength: 1
|
||
maxLength: 256
|
||
description: 响应消息
|
||
data:
|
||
type: object
|
||
description: 响应数据（可选）
|
||
example:
|
||
code: 0
|
||
message: "success"
|
||
|
||
SessionListResponse:
|
||
allOf:
|
||
- $ref: '#/components/schemas/ApiResponse'
|
||
- type: object
|
||
required:
|
||
- code
|
||
- message
|
||
- data
|
||
properties:
|
||
code:
|
||
type: integer
|
||
enum:
|
||
- 0
|
||
message:
|
||
type: string
|
||
data:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/SessionInfo'
|
||
example:
|
||
code: 0
|
||
message: "success"
|
||
data:
|
||
- sessionId: "session_001"
|
||
customerId: "customer_001"
|
||
status: "manual"
|
||
channelType: "wechat"
|
||
|
||
SessionResponse:
|
||
allOf:
|
||
- $ref: '#/components/schemas/ApiResponse'
|
||
- type: object
|
||
required:
|
||
- code
|
||
- message
|
||
- data
|
||
properties:
|
||
code:
|
||
type: integer
|
||
enum:
|
||
- 0
|
||
message:
|
||
type: string
|
||
data:
|
||
$ref: '#/components/schemas/SessionInfo'
|
||
|
||
SessionInfo:
|
||
type: object
|
||
required:
|
||
- sessionId
|
||
- customerId
|
||
- status
|
||
properties:
|
||
sessionId:
|
||
type: string
|
||
minLength: 1
|
||
maxLength: 64
|
||
description: 会话ID
|
||
customerId:
|
||
type: string
|
||
minLength: 1
|
||
maxLength: 64
|
||
description: 客户ID
|
||
kfId:
|
||
type: string
|
||
maxLength: 64
|
||
description: 客服账号ID
|
||
channelType:
|
||
type: string
|
||
description: 渠道类型
|
||
enum:
|
||
- wechat
|
||
- douyin
|
||
- jd
|
||
status:
|
||
type: string
|
||
description: 会话状态
|
||
enum:
|
||
- ai
|
||
- pending
|
||
- manual
|
||
- closed
|
||
manualCsId:
|
||
type: string
|
||
maxLength: 64
|
||
description: 接待客服ID
|
||
lastMessage:
|
||
type: string
|
||
maxLength: 4096
|
||
description: 最后一条消息
|
||
lastMessageTime:
|
||
type: string
|
||
format: date-time
|
||
description: 最后消息时间
|
||
messageCount:
|
||
type: integer
|
||
minimum: 0
|
||
description: 消息数量
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
description: 创建时间
|
||
updatedAt:
|
||
type: string
|
||
format: date-time
|
||
description: 更新时间
|
||
metadata:
|
||
type: object
|
||
description: 扩展元数据
|
||
|
||
MessageListResponse:
|
||
allOf:
|
||
- $ref: '#/components/schemas/ApiResponse'
|
||
- type: object
|
||
required:
|
||
- code
|
||
- message
|
||
- data
|
||
properties:
|
||
code:
|
||
type: integer
|
||
enum:
|
||
- 0
|
||
message:
|
||
type: string
|
||
data:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/MessageInfo'
|
||
|
||
MessageInfo:
|
||
type: object
|
||
required:
|
||
- msgId
|
||
- sessionId
|
||
- senderType
|
||
- content
|
||
properties:
|
||
msgId:
|
||
type: string
|
||
minLength: 1
|
||
maxLength: 128
|
||
description: 消息ID
|
||
sessionId:
|
||
type: string
|
||
minLength: 1
|
||
maxLength: 64
|
||
description: 会话ID
|
||
senderType:
|
||
type: string
|
||
description: 发送者类型
|
||
enum:
|
||
- customer
|
||
- ai
|
||
- manual
|
||
senderId:
|
||
type: string
|
||
maxLength: 64
|
||
description: 发送者ID
|
||
content:
|
||
type: string
|
||
minLength: 1
|
||
maxLength: 4096
|
||
description: 消息内容
|
||
msgType:
|
||
type: string
|
||
description: 消息类型
|
||
enum:
|
||
- text
|
||
- image
|
||
- file
|
||
- event
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
description: 创建时间
|
||
|
||
x-websocket:
|
||
path: /ws/cs/{csId}
|
||
description: |
|
||
## WebSocket 实时通信协议
|
||
|
||
客服工作台通过 WebSocket 接收实时消息推送。
|
||
|
||
覆盖验收标准：
|
||
- AC-MCA-10: 会话状态为 MANUAL 时推送消息到人工客服工作台
|
||
|
||
### 连接地址
|
||
```
|
||
ws://{host}:{port}/ws/cs/{csId}
|
||
```
|
||
|
||
### 认证/鉴权方式
|
||
- **路径参数**: `{csId}` 客服ID，用于标识连接身份
|
||
- **可选增强**: 后续可增加 Token 验证（Query 参数或 Header）
|
||
- Query: `?token=xxx`
|
||
- Header: `Authorization: Bearer xxx`
|
||
|
||
### 客户端发送消息格式
|
||
```json
|
||
{
|
||
"type": "bind_session",
|
||
"sessionId": "会话ID"
|
||
}
|
||
```
|
||
|
||
### 服务端推送消息格式
|
||
```json
|
||
{
|
||
"type": "new_message",
|
||
"sessionId": "会话ID",
|
||
"data": {
|
||
"msgId": "消息ID",
|
||
"content": "消息内容",
|
||
"senderType": "customer",
|
||
"senderId": "客户ID",
|
||
"msgType": "text",
|
||
"createdAt": "2026-02-24T10:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 推送事件类型
|
||
| type | 说明 |
|
||
|------|------|
|
||
| new_message | 新消息通知 |
|
||
| new_pending_session | 新待接入会话 |
|
||
| session_accepted | 会话被接入 |
|
||
| session_closed | 会话已关闭 |
|