客服通话

客服通话插件（Customer Service）为 Monibuca V6 提供 1v1 实时音视频客服 能力。适用于在线客服、远程咨询、售后支持等场景。

核心特性

• 1v1 通话：每个会话固定 2 人（客服 + 用户），基于 Room 服务的 max_users: 2 限制
• 免登录用户端：用户无需注册账号，通过链接直接进入通话
• 客服坐席管理：支持会话分配、转接、统计
• 音频混音：客服端可将本地音频文件混入推流（如背景音乐、提示音）
• 满意度评价：通话结束后用户可进行星级评价
• Admin 管理后台：完整的会话管理界面，支持创建会话、生成用户链接/二维码

启用方式

Cargo.toml

features = ["customer-service"]

# 客服通话依赖 Room 服务
# room feature 会自动启用

架构设计

graph TB
    subgraph CS["CustomerService Plugin"]
        SM["SessionManager<br/>会话管理（DashMap）"]
        HTTP["HTTP API<br/>/customer-service/*"]
        Signal["WebSocket 信令<br/>AcceptCall / EndCall / Transfer"]
    end

    subgraph RS["Room Service (引擎内置)"]
        Room["房间管理<br/>max_users: 2"]
        WS["WebSocket<br/>信令通信"]
    end

    subgraph Client["客户端"]
        Agent["客服端<br/>账号登录"]
        Customer["用户端<br/>免登录"]
    end

    CS -->|"register_callbacks<br/>RoomType::CustomerService"| RS
    HTTP --> SM
    Agent -->|"WebRTC (WHIP)"| Room
    Customer -->|"WebRTC (WHIP)"| Room
    Agent <-->|"WebSocket"| WS
    Customer <-->|"WebSocket"| WS

会话生命周期

Waiting → Active → Ended

状态	说明
Waiting	会话已创建，等待客服/用户加入
Active	双方均已加入，通话进行中
Ended	通话已结束

HTTP API

所有接口前缀为 /customer-service/。

会话管理

方法	路径	说明
GET	/sessions	获取会话列表
GET	/sessions/{id}	获取会话详情
POST	/sessions	创建新会话
DELETE	/sessions/{id}	关闭/删除会话
POST	/sessions/{id}/assign	分配客服坐席
GET	/stats	获取统计信息

创建会话

curl -X POST http://localhost:8080/customer-service/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "title": "售后咨询",
    "customer_name": "张三"
  }'

响应：

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

分配客服坐席

curl -X POST http://localhost:8080/customer-service/sessions/cs_abc123/assign \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_001",
    "agent_name": "客服小王"
  }'

获取统计信息

curl http://localhost:8080/customer-service/stats

响应：

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

WebSocket 信令

客服通话使用专用的 WebSocket 信令，通过 Room 服务的 on_message 回调透传到插件处理。

信令类型

Action	方向	说明
accept_call	C→S	客服接受通话
end_call	C→S	任一方挂断通话
transfer_call	C→S	客服转接至其他坐席
hold_call	C→S	保持通话
resume_call	C→S	恢复通话
call_accepted	S→C	通知对方已接听
call_ended	S→C	通知通话已结束
call_transferred	S→C	通知通话已转接

信令示例

{
  "action": "accept_call",
  "room_id": "customer-service/cs_abc123",
  "user_id": "agent_001"
}

配置

customer_service:
  max_sessions: 1000          # 最大并发会话数
  session_timeout: 3600       # 会话超时时间（秒），默认 1 小时
  enable_recording: false     # 是否启用通话录制

WebSocket 连接

客户端通过标准的 Room WebSocket 连接加入客服通话：

ws://host:port/room?type=customer_service

房间 ID 格式为 customer-service/{session_id}，通过前缀区分不同的房间类型。

---

Web-SDK 集成

Web Components

客服通话 Demo 基于 Monibuca Web-SDK 的 Web Components 构建：

<!-- 房间容器 -->
<mb-room id="room"></mb-room>

<!-- 本地推流 -->
<mb-publisher id="publisher"></mb-publisher>

<!-- 远端订阅 -->
<mb-subscriber id="subscriber"></mb-subscriber>

初始化连接

const room = document.getElementById('room') as MbRoom;
const publisher = document.getElementById('publisher') as MbPublisher;

// 设置 WebSocket 连接
room.setAttribute('ws-url', 'ws://localhost:8080/room?type=customer_service');
room.setAttribute('room-id', 'customer-service/session_001');

// 开始推流
await publisher.startCapture({ audio: true, video: true });
await publisher.startPublish();

音频混音

客服端支持将本地音频文件混入推流，例如背景音乐、等待提示音：

const publisher = document.getElementById('publisher') as MbPublisher;

// 混入本地音频文件
publisher.mixAudio('bgm', '/audio/background-music.mp3', 0.3);

// 调整混音音量（0.0 ~ 1.0）
publisher.setMixVolume('bgm', 0.5);

// 移除混音源
publisher.unmixAudio('bgm');

混音原理：

graph LR
    Mic["麦克风<br/>MediaStream"] --> GainA["GainNode<br/>麦克风音量"]
    BGM["音频文件<br/>MediaElement"] --> GainB["GainNode<br/>混音音量"]
    GainA --> Dest["Destination<br/>合成输出"]
    GainB --> Dest
    Dest --> WHIP["WHIPClient<br/>WebRTC 推流"]

SDK 内部使用 Web Audio API 的 AudioContext 将多个音源（麦克风 + 混音文件）通过 GainNode 混合到同一个 MediaStreamAudioDestinationNode，最终输出到 WebRTC 推流。

通话状态管理

推荐使用状态机管理通话流程：

type CallStage = 'waiting' | 'connecting' | 'connected' | 'ended';

// waiting    → 等待对方加入（显示等待界面、脉冲动画）
// connecting → WebRTC 连接建立中
// connected  → 通话进行中（显示视频画面、计时器、控制栏）
// ended      → 通话结束（显示通话时长、满意度评价）

---

Admin 管理后台

客服通话在 Admin 后台提供完整的管理功能。

会话管理

• 统计卡片：总会话数、通话中、等待接入
• 会话列表：支持状态筛选、搜索、批量操作
• 创建会话：填写标题和描述，自动分配坐席
• 分配坐席：手动将会话分配给指定客服
• 生成链接：为用户/客服生成专属入口链接和二维码

通话测试

Admin 内嵌了 1v1 通话页面，管理员可直接进行通话测试：

• 左右分屏视频布局
• 麦克风/摄像头控制
• 文字聊天面板
• 通话统计信息

房间上报统计

客服通话的房间数据通过 Room 服务的上报系统采集，在 Admin 中按 customer-service/ 前缀自动筛选展示。

---

Demo 项目

完整的客服通话 Demo 位于 web-sdk/packages/demo/customer-service/：

customer-service/
├── src/
│   ├── pages/
│   │   ├── Lobby/index.tsx      # 入口：角色选择、会话输入
│   │   └── CallRoom/index.tsx   # 通话：1v1 视频、控制栏、聊天
│   ├── services/api.ts          # API 封装
│   └── types/index.ts           # 类型定义
├── package.json                 # port: 5476
└── vite.config.ts

启动 Demo

cd web-sdk/packages/demo/customer-service
pnpm install
pnpm dev
# 访问 http://localhost:5476

用户端入口

用户通过带参数的链接直接进入通话，无需登录：

http://localhost:5476?session=cs_abc123&role=customer

客服端入口

客服需要账号密码登录后进入：

http://localhost:5476?session=cs_abc123&role=agent

移动端适配

Demo 自动检测设备类型，移动端采用：

• 上下分屏视频布局
• 底部固定控制栏（适配安全区域）
• 触摸优化的交互