mirror of
https://gitee.com/270580156/weiyu.git
synced 2026-05-12 18:32:31 +00:00
263 lines
4.1 KiB
Markdown
263 lines
4.1 KiB
Markdown
# 集成接口模块详细设计
|
|
|
|
## 1. REST API接口
|
|
|
|
### 1.1 认证鉴权
|
|
|
|
- 认证方式
|
|
- API Key认证
|
|
- OAuth2认证
|
|
- JWT认证
|
|
- 签名认证
|
|
|
|
- 权限控制
|
|
- 接口权限
|
|
- 数据权限
|
|
- 频率限制
|
|
- IP白名单
|
|
|
|
### 1.2 核心接口
|
|
|
|
- 客服管理接口
|
|
|
|
```http
|
|
POST /api/v1/agents # 创建客服账号
|
|
GET /api/v1/agents/{id} # 获取客服信息
|
|
PUT /api/v1/agents/{id} # 更新客服信息
|
|
DELETE /api/v1/agents/{id} # 删除客服账号
|
|
```
|
|
|
|
- 会话管理接口
|
|
|
|
```http
|
|
POST /api/v1/conversations # 创建会话
|
|
GET /api/v1/conversations/{id} # 获取会话信息
|
|
PUT /api/v1/conversations/{id} # 更新会话状态
|
|
DELETE /api/v1/conversations/{id} # 结束会话
|
|
```
|
|
|
|
- 消息管理接口
|
|
|
|
```http
|
|
POST /api/v1/messages # 发送消息
|
|
GET /api/v1/messages/{id} # 获取消息
|
|
PUT /api/v1/messages/{id} # 更新消息
|
|
DELETE /api/v1/messages/{id} # 删除消息
|
|
```
|
|
|
|
## 2. WebSocket接口
|
|
|
|
### 2.1 连接管理
|
|
|
|
- 连接建立
|
|
|
|
```javascript
|
|
// 建立WebSocket连接
|
|
const ws = new WebSocket('wss://api.bytedesk.com/ws?token=xxx')
|
|
|
|
// 连接事件处理
|
|
ws.onopen = () => {}
|
|
ws.onclose = () => {}
|
|
ws.onerror = () => {}
|
|
```
|
|
|
|
- 心跳机制
|
|
|
|
```javascript
|
|
// 发送心跳
|
|
setInterval(() => {
|
|
ws.send(JSON.stringify({type: 'ping'}))
|
|
}, 30000)
|
|
```
|
|
|
|
### 2.2 消息协议
|
|
|
|
- 消息格式
|
|
|
|
```json
|
|
{
|
|
"type": "message", // 消息类型
|
|
"action": "send", // 动作类型
|
|
"data": { // 消息内容
|
|
"from": "user_id",
|
|
"to": "agent_id",
|
|
"content": "消息内容",
|
|
"timestamp": 1635232823
|
|
}
|
|
}
|
|
```
|
|
|
|
- 事件通知
|
|
|
|
```json
|
|
{
|
|
"type": "event",
|
|
"action": "status_change",
|
|
"data": {
|
|
"agent_id": "xxx",
|
|
"status": "online",
|
|
"timestamp": 1635232823
|
|
}
|
|
}
|
|
```
|
|
|
|
## 3. 事件回调接口
|
|
|
|
### 3.1 回调配置
|
|
|
|
- 回调地址配置
|
|
- 回调验证方式
|
|
- 重试机制
|
|
- 超时设置
|
|
|
|
### 3.2 事件类型
|
|
|
|
- 会话事件
|
|
|
|
```json
|
|
{
|
|
"event": "conversation.created",
|
|
"timestamp": 1635232823,
|
|
"data": {
|
|
"conversation_id": "xxx",
|
|
"visitor_id": "xxx",
|
|
"agent_id": "xxx"
|
|
}
|
|
}
|
|
```
|
|
|
|
- 消息事件
|
|
|
|
```json
|
|
{
|
|
"event": "message.received",
|
|
"timestamp": 1635232823,
|
|
"data": {
|
|
"message_id": "xxx",
|
|
"conversation_id": "xxx",
|
|
"content": "xxx"
|
|
}
|
|
}
|
|
```
|
|
|
|
- 状态事件
|
|
|
|
```json
|
|
{
|
|
"event": "agent.status_changed",
|
|
"timestamp": 1635232823,
|
|
"data": {
|
|
"agent_id": "xxx",
|
|
"status": "online"
|
|
}
|
|
}
|
|
```
|
|
|
|
## 4. 第三方系统集成
|
|
|
|
### 4.1 CRM系统集成
|
|
|
|
- 客户数据同步
|
|
|
|
```json
|
|
{
|
|
"customer_id": "xxx",
|
|
"name": "张三",
|
|
"phone": "13800138000",
|
|
"level": "VIP",
|
|
"tags": ["重要客户"]
|
|
}
|
|
```
|
|
|
|
- 订单数据关联
|
|
|
|
```json
|
|
{
|
|
"order_id": "xxx",
|
|
"customer_id": "xxx",
|
|
"amount": 9999,
|
|
"status": "paid",
|
|
"create_time": "2023-10-26 12:00:00"
|
|
}
|
|
```
|
|
|
|
### 4.2 工单系统集成
|
|
|
|
- 工单创建
|
|
|
|
```json
|
|
{
|
|
"ticket_id": "xxx",
|
|
"title": "产品咨询",
|
|
"content": "详细内容...",
|
|
"priority": "high",
|
|
"category": "产品"
|
|
}
|
|
```
|
|
|
|
- 工单状态同步
|
|
|
|
```json
|
|
{
|
|
"ticket_id": "xxx",
|
|
"status": "processing",
|
|
"handler": "agent_id",
|
|
"update_time": "2023-10-26 12:00:00"
|
|
}
|
|
```
|
|
|
|
### 4.3 统计分析集成
|
|
|
|
- 数据推送接口
|
|
|
|
```http
|
|
POST /api/v1/statistics/push
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"type": "conversation",
|
|
"metrics": {
|
|
"total": 100,
|
|
"success": 90,
|
|
"avg_duration": 300
|
|
},
|
|
"dimension": {
|
|
"date": "2023-10-26",
|
|
"agent_id": "xxx"
|
|
}
|
|
}
|
|
```
|
|
|
|
- 报表获取接口
|
|
|
|
```http
|
|
GET /api/v1/statistics/report?
|
|
type=conversation&
|
|
start_date=2023-10-01&
|
|
end_date=2023-10-31&
|
|
dimensions=agent,category
|
|
```
|
|
|
|
## 关键技术点
|
|
|
|
接口安全性
|
|
加密传输
|
|
身份认证
|
|
权限控制
|
|
防攻击措施
|
|
接口性能
|
|
连接池管理
|
|
缓存策略
|
|
限流措施
|
|
负载均衡
|
|
接口可用性
|
|
故障转移
|
|
服务降级
|
|
熔断机制
|
|
监控告警
|
|
接口扩展性
|
|
版本控制
|
|
协议兼容
|
|
数据格式
|
|
错误处理
|