跳到主要内容

API 说明

TgoRTC 服务器内置了完整的 Swagger API 文档。本文档基于 swagger.json 提供详细的 API 接口说明。

访问 Swagger UI

默认情况下，您可以在部署完成后直接通过浏览器访问在线接口文档： http://<服务器IP>:8080/swagger/index.html

1. 房间管理 API​

创建房间​

POST /api/v1/rooms

创建一个新的音视频房间。

请求参数

请求体 (Body):

参数名类型必填说明示例
creatorstring是房间创建者 ID"user_001"
device_typestring是设备类型（如 app, web, pc 等）"app"
room_idstring否房间 ID（可选，不传则自动生成）"room_abc123"
rtc_typeinteger否呼叫类型（0: 语音, 1: 视频）1
invite_oninteger否是否开启邀请（0: 否, 1: 是）1
max_participantsinteger否最大参与者数（默认 2）2
uidsstring[]否邀请的用户 ID 列表["user_002"]
{
  "creator": "user_001",
  "device_type": "app",
  "rtc_type": 1,
  "invite_on": 1,
  "max_participants": 2,
  "uids": ["user_002"]
}

邀请参与者​

POST /api/v1/rooms/{room_id}/invite

向已有房间邀请其他用户。

请求参数

路径参数 (Path):

  • room_id (string) - 必填，房间 ID

请求体 (Body):

参数名类型必填说明
uidsstring[]是要邀请的用户 ID 列表
{
  "uids": ["user_003"]
}

加入房间​

POST /api/v1/rooms/{room_id}/join

加入指定房间，成功后返回连接所需的 Token。

请求参数

路径参数 (Path):

  • room_id (string) - 必填，房间 ID

请求体 (Body):

参数名类型必填说明
uidstring是用户 ID
device_typestring否设备类型
{
  "uid": "user_002",
  "device_type": "web"
}

离开房间​

POST /api/v1/rooms/{room_id}/leave

参与者主动离开房间。

请求参数

路径参数 (Path):

  • room_id (string) - 必填，房间 ID

请求体 (Body):

参数名类型必填说明
uidstring是用户 ID
{
  "uid": "user_002"
}

同步房间列表​

GET /api/v1/rooms/sync

同步指定用户被邀请或已加入的所有活跃房间列表。常用于客户端断线重连或初始化时恢复房间状态。

请求参数

Query 参数:

参数名类型必填说明示例
uidstring是用户 IDuser_001
device_typestring是设备类型app
GET /api/v1/rooms/sync?uid=user_001&device_type=app

2. 业务 Webhook 回调​

POST /tgortc/webhook

TgoRTC 服务器会向您的业务系统配置的 Webhook URL 发送事件通知。您需要在业务系统中实现此接口来接收房间与参与者的状态变更。

Webhook 请求结构​

业务系统接收到的请求格式如下：

  • Query 参数:
    • event_type (string): 事件类型
    • event_id (string): 事件唯一 ID（用于去重）
  • Body: JSON 事件数据

事件类型 (event_type) 分类​

事件分类事件类型说明
房间事件room.started房间已开始（首个参与者加入）
room.finished房间已结束（所有人离开或超时）
参与者事件participant.invited重要: 参与者被邀请。业务系统收到此事件后应向被邀请者推送来电通知。
participant.joined参与者已成功加入
participant.left参与者正常离开
participant.rejected参与者拒绝加入
participant.missed参与者超时未加入（漏接）
participant.cancelled发起者主动取消了邀请

请求体数据示例​

适用于 room.started 和 room.finished。

{
  "room_id": "room_abc123",
  "creator": "user_001",
  "rtc_type": 1,
  "invite_on": 0,
  "status": 1,
  "max_participants": 2,
  "duration": 300,        // 仅在 finished 事件中有实际通话时长(秒)
  "uids": ["user_001", "user_002"],
  "created_at": 1704096500,
  "updated_at": 1704096600
}

3. 内部管理 API (Webhook)​

这些 API 主要用于系统内部运行与维护：

  • POST /api/v1/webhooks/livekit - 接收 LiveKit 的底层事件回调
  • GET /api/v1/webhooks/logs/stats - 获取 Webhook 处理统计
  • POST /api/v1/webhooks/logs/cleanup - 清理历史日志
请求参数

请求体 (Body):

参数名类型必填说明
retention_daysinteger是保留天数
{
  "retention_days": 7
}

错误码说明​

所有 API 请求失败时，均遵循以下统一的 JSON 错误响应格式：

{
  "code": 400,
  "message": "参数错误"
}