Customer Service API

The customer service plugin provides a set of RESTful HTTP APIs for managing the creation, assignment, querying, and closing of customer service sessions.

Endpoint Prefix

All endpoint paths are prefixed with:

/customer-service/

Session List

Get all customer service sessions.

GET /customer-service/sessions

Response

{
  "code": 0,
  "data": {
    "sessions": [
      {
        "id": "cs_abc123",
        "title": "After-sales inquiry",
        "customer_id": "cust_001",
        "customer_name": "John",
        "agent_id": "agent_001",
        "agent_name": "Agent Wang",
        "status": "Active",
        "duration": 320,
        "created_at": "2024-01-15T10:30:00Z"
      }
    ],
    "total": 1
  }
}

Session Status

Status	Description
Waiting	Waiting — created but both parties have not yet joined
Active	In call — both parties are connected
Ended	Ended

Session Details

Get detailed information for a specific session.

GET /customer-service/sessions/{id}

Path Parameters

Parameter	Type	Description
id	string	Session ID

Response

{
  "code": 0,
  "data": {
    "id": "cs_abc123",
    "title": "After-sales inquiry",
    "customer_id": "cust_001",
    "customer_name": "John",
    "agent_id": "agent_001",
    "agent_name": "Agent Wang",
    "status": "Active",
    "duration": 320,
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Create Session

Create a new customer service call session.

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

Request Body

{
  "title": "After-sales inquiry",
  "customer_name": "John",
  "description": "Regarding refund for order #12345"
}

Field	Type	Required	Description
title	string	Yes	Session title
customer_name	string	Yes	Customer name
description	string	No	Session description

Response

{
  "code": 0,
  "data": {
    "id": "cs_abc123",
    "title": "After-sales inquiry",
    "customer_id": "cust_001",
    "customer_name": "John",
    "status": "Waiting",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Close Session

Close or delete a specific session. If a call is in progress, it will be forcefully terminated.

DELETE /customer-service/sessions/{id}

Path Parameters

Parameter	Type	Description
id	string	Session ID

Response

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

Assign Agent

Assign a specific customer service agent to a session.

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

Path Parameters

Parameter	Type	Description
id	string	Session ID

Request Body

{
  "agent_id": "agent_001",
  "agent_name": "Agent Wang"
}

Field	Type	Required	Description
agent_id	string	Yes	Agent ID
agent_name	string	Yes	Agent name

Response

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

Statistics

Get overall statistics for customer service calls.

GET /customer-service/stats

Response

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

Field	Type	Description
total_sessions	number	Total number of sessions
active_sessions	number	Number of active call sessions
waiting_sessions	number	Number of sessions waiting for connection
ended_sessions	number	Number of ended sessions

Error Responses

All endpoints return a unified error format on failure:

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

Common Errors

Error Message	Description
session not found	Session ID does not exist
session already ended	Session has ended, cannot be operated on
agent already assigned	Agent has already been assigned
max sessions reached	Maximum concurrent session limit exceeded
invalid request body	Request body format is invalid