客服通话 API

客服通话插件提供一组 RESTful HTTP API，用于管理客服会话的创建、分配、查询和关闭。

接口前缀

所有接口路径前缀为：

/customer-service/

会话列表

获取所有客服会话。

GET /customer-service/sessions

响应

{
  "code": 0,
  "data": {
    "sessions": [
      {
        "id": "cs_abc123",
        "title": "售后咨询",
        "customer_id": "cust_001",
        "customer_name": "张三",
        "agent_id": "agent_001",
        "agent_name": "客服小王",
        "status": "Active",
        "duration": 320,
        "created_at": "2024-01-15T10:30:00Z"
      }
    ],
    "total": 1
  }
}

会话状态

状态	说明
Waiting	等待中，已创建但双方未全部加入
Active	通话中，双方已连接
Ended	已结束

会话详情

获取指定会话的详细信息。

GET /customer-service/sessions/{id}

路径参数

参数	类型	说明
id	string	会话 ID

响应

{
  "code": 0,
  "data": {
    "id": "cs_abc123",
    "title": "售后咨询",
    "customer_id": "cust_001",
    "customer_name": "张三",
    "agent_id": "agent_001",
    "agent_name": "客服小王",
    "status": "Active",
    "duration": 320,
    "created_at": "2024-01-15T10:30:00Z"
  }
}

创建会话

创建一个新的客服通话会话。

POST /customer-service/sessions
Content-Type: application/json

请求体

{
  "title": "售后咨询",
  "customer_name": "张三",
  "description": "关于订单 #12345 的退款问题"
}

字段	类型	必填	说明
title	string	是	会话标题
customer_name	string	是	用户名称
description	string	否	会话描述

响应

{
  "code": 0,
  "data": {
    "id": "cs_abc123",
    "title": "售后咨询",
    "customer_id": "cust_001",
    "customer_name": "张三",
    "status": "Waiting",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

关闭会话

关闭或删除指定会话。如果通话正在进行，将强制结束通话。

DELETE /customer-service/sessions/{id}

路径参数

参数	类型	说明
id	string	会话 ID

响应

{
  "code": 0,
  "message": "session closed"
}

分配坐席

将指定客服坐席分配到会话中。

POST /customer-service/sessions/{id}/assign
Content-Type: application/json

路径参数

参数	类型	说明
id	string	会话 ID

请求体

{
  "agent_id": "agent_001",
  "agent_name": "客服小王"
}

字段	类型	必填	说明
agent_id	string	是	客服 ID
agent_name	string	是	客服名称

响应

{
  "code": 0,
  "message": "agent assigned"
}

统计信息

获取客服通话的整体统计数据。

GET /customer-service/stats

响应

{
  "code": 0,
  "data": {
    "total_sessions": 156,
    "active_sessions": 3,
    "waiting_sessions": 2,
    "ended_sessions": 151
  }
}

字段	类型	说明
total_sessions	number	总会话数
active_sessions	number	通话中的会话数
waiting_sessions	number	等待接入的会话数
ended_sessions	number	已结束的会话数

错误响应

所有接口在出错时返回统一的错误格式：

{
  "code": -1,
  "message": "session not found"
}

常见错误

错误信息	说明
session not found	会话 ID 不存在
session already ended	会话已结束，无法操作
agent already assigned	坐席已分配
max sessions reached	超过最大并发会话数限制
invalid request body	请求体格式错误