ZF/weiyu

Fork 0

mirror of https://gitee.com/270580156/weiyu.git synced 2026-02-07 13:50:15 +00:00

Files

jack ning b0d0f67004 Sync from source repo: 2024-12-12 10:57:29

2024-12-12 10:57:29 +08:00

4.1 KiB

Raw Blame History

集成接口模块详细设计

1. REST API接口

1.1 认证鉴权

认证方式
- API Key认证
- OAuth2认证
- JWT认证
- 签名认证
权限控制
- 接口权限
- 数据权限
- 频率限制
- IP白名单

1.2 核心接口

客服管理接口

POST /api/v1/agents              # 创建客服账号
GET /api/v1/agents/{id}         # 获取客服信息
PUT /api/v1/agents/{id}         # 更新客服信息
DELETE /api/v1/agents/{id}      # 删除客服账号

会话管理接口

POST /api/v1/conversations      # 创建会话
GET /api/v1/conversations/{id}  # 获取会话信息
PUT /api/v1/conversations/{id}  # 更新会话状态
DELETE /api/v1/conversations/{id} # 结束会话

消息管理接口

POST /api/v1/messages          # 发送消息
GET /api/v1/messages/{id}      # 获取消息
PUT /api/v1/messages/{id}      # 更新消息
DELETE /api/v1/messages/{id}   # 删除消息

2. WebSocket接口

2.1 连接管理

连接建立

// 建立WebSocket连接
const ws = new WebSocket('wss://api.bytedesk.com/ws?token=xxx')

// 连接事件处理
ws.onopen = () => {}
ws.onclose = () => {}
ws.onerror = () => {}

心跳机制

// 发送心跳
setInterval(() => {
  ws.send(JSON.stringify({type: 'ping'}))
}, 30000)

2.2 消息协议

消息格式

{
  "type": "message",      // 消息类型
  "action": "send",       // 动作类型
  "data": {              // 消息内容
    "from": "user_id",
    "to": "agent_id",
    "content": "消息内容",
    "timestamp": 1635232823
  }
}

事件通知

{
  "type": "event",
  "action": "status_change",
  "data": {
    "agent_id": "xxx",
    "status": "online",
    "timestamp": 1635232823
  }
}

3. 事件回调接口

3.1 回调配置

回调地址配置
回调验证方式
重试机制
超时设置

3.2 事件类型

会话事件

{
  "event": "conversation.created",
  "timestamp": 1635232823,
  "data": {
    "conversation_id": "xxx",
    "visitor_id": "xxx",
    "agent_id": "xxx"
  }
}

消息事件

{
  "event": "message.received",
  "timestamp": 1635232823,
  "data": {
    "message_id": "xxx",
    "conversation_id": "xxx",
    "content": "xxx"
  }
}

状态事件

{
  "event": "agent.status_changed",
  "timestamp": 1635232823,
  "data": {
    "agent_id": "xxx",
    "status": "online"
  }
}

4. 第三方系统集成

4.1 CRM系统集成

客户数据同步

{
  "customer_id": "xxx",
  "name": "张三",
  "phone": "13800138000",
  "level": "VIP",
  "tags": ["重要客户"]
}

订单数据关联

{
  "order_id": "xxx",
  "customer_id": "xxx",
  "amount": 9999,
  "status": "paid",
  "create_time": "2023-10-26 12:00:00"
}

4.2 工单系统集成

工单创建

{
  "ticket_id": "xxx",
  "title": "产品咨询",
  "content": "详细内容...",
  "priority": "high",
  "category": "产品"
}

工单状态同步

{
  "ticket_id": "xxx",
  "status": "processing",
  "handler": "agent_id",
  "update_time": "2023-10-26 12:00:00"
}

4.3 统计分析集成

数据推送接口

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"
  }
}

报表获取接口

GET /api/v1/statistics/report?
    type=conversation&
    start_date=2023-10-01&
    end_date=2023-10-31&
    dimensions=agent,category

关键技术点

接口安全性加密传输身份认证权限控制防攻击措施接口性能连接池管理缓存策略限流措施负载均衡接口可用性故障转移服务降级熔断机制监控告警接口扩展性版本控制协议兼容数据格式错误处理

4.1 KiB Raw Blame History