API Reference

The TgoRTC server comes with built-in Swagger API documentation. This document provides detailed API interface specifications based on swagger.json.

Access Swagger UI

By default, you can directly access the Swagger UI through your browser after deployment: http://<SERVER_IP>:8080/swagger/index.html

---

1. Room Management API

Create Room

POST /api/v1/rooms

Creates a new audio/video room.

Request Parameters

Request Body (JSON):

Parameter	Type	Required	Description	Example
creator	string	Yes	Room creator ID	"user_001"
device_type	string	Yes	Device type (e.g. app, web, pc)	"app"
room_id	string	No	Room ID (auto-generated if empty)	"room_abc123"
rtc_type	integer	No	Call type (0: Audio, 1: Video)	1
invite_on	integer	No	Enable invitations (0: No, 1: Yes)	1
max_participants	integer	No	Max participants (default 2)	2
uids	string[]	No	List of invited user IDs	["user_002"]

Request Example

{
  "creator": "user_001",
  "device_type": "app",
  "rtc_type": 1,
  "invite_on": 1,
  "max_participants": 2,
  "uids": ["user_002"]
}

Success Response (200 OK)

{
  "room_id": "room_abc123",
  "creator": "user_001",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6Ik...",
  "url": "wss://your-livekit-server",
  "status": 0,
  "created_at": "1704096500",
  "max_participants": 2,
  "timeout": 30,
  "rtc_type": 1,
  "uids": ["user_001", "user_002"]
}

---

Invite Participants

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

Invite other users to an existing room.

Request Parameters

Path Parameters:

• room_id (string) - Required, Room ID

Request Body (JSON):

Parameter	Type	Required	Description
uids	string[]	Yes	List of user IDs to invite

Request Example

{
  "uids": ["user_003"]
}

Success Response (200 OK)

{}

(Note: Returning an empty object indicates success)

---

Join Room

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

Join a specific room. Returns the Token needed for connection upon success.

Request Parameters

Path Parameters:

• room_id (string) - Required, Room ID

Request Body (JSON):

Parameter	Type	Required	Description
uid	string	Yes	User ID
device_type	string	No	Device type

Request Example

{
  "uid": "user_002",
  "device_type": "web"
}

Success Response (200 OK)

{
  "room_id": "room_abc123",
  "creator": "user_001",
  "token": "eyJhbGciOiJIUzI1NiIsInR5...",
  "url": "wss://your-livekit-server",
  "status": 1,
  "created_at": "1704096500",
  "max_participants": 2,
  "timeout": 30,
  "rtc_type": 1,
  "uids": ["user_001", "user_002"]
}

---

Leave Room

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

Participant proactively leaves the room.

Request Parameters

Path Parameters:

• room_id (string) - Required, Room ID

Request Body (JSON):

Parameter	Type	Required	Description
uid	string	Yes	User ID

Request Example

{
  "uid": "user_002"
}

Success Response (200 OK)

{}

---

Sync Active Rooms

GET /api/v1/rooms/sync

Synchronize the list of active rooms that a specific user has been invited to or joined. Commonly used for restoring room states during client reconnection or initialization.

Request Parameters (Query)

Parameter	Type	Required	Description	Example
uid	string	Yes	User ID	user_001
device_type	string	Yes	Device type	app

Request Example

GET /api/v1/rooms/sync?uid=user_001&device_type=app

Success Response (200 OK)

[
  {
    "room_id": "room_abc123",
    "creator": "user_001",
    "token": "eyJhbGciOiJI...",
    "url": "wss://your-livekit-server",
    "status": 1,
    "created_at": "1704096500",
    "max_participants": 2,
    "timeout": 30,
    "uids": ["user_001", "user_002"]
  }
]

---

2. Business Webhook Callbacks

POST /tgortc/webhook

The TgoRTC server will send event notifications to the Webhook URL configured by your business system. You need to implement this endpoint in your application to receive room and participant status changes.

Webhook Request Structure

The request format received by the business system is as follows:

• Query Parameters:
  • event_type (string): Event type
  • event_id (string): Unique event ID (for deduplication)
• Body: JSON event data

Event Types (event_type)

Category	Event Type	Description
Room	room.started	Room started (first participant joined)
	room.finished	Room finished (all left or timeout)
Participant	participant.invited	Important: Participant invited. The business system should push an incoming call notification to the invitee upon receiving this event.
	participant.joined	Participant successfully joined
	participant.left	Participant left normally
	participant.rejected	Participant rejected the call
	participant.missed	Participant missed the call (timeout)
	participant.cancelled	Caller actively cancelled the invitation

Request Body Data Examples

Room Event Data (RoomEventData)

Applicable to room.started and room.finished.

{
  "room_id": "room_abc123",
  "creator": "user_001",
  "rtc_type": 1,
  "invite_on": 0,
  "status": 1,
  "max_participants": 2,
  "duration": 300,        // Contains actual call duration (seconds) only in finished events
  "uids": ["user_001", "user_002"],
  "created_at": 1704096500,
  "updated_at": 1704096600
}

Participant Event Data (ParticipantEventData)

Applicable to all participant.* events. Extends RoomEventData by adding operator information that triggered the event.

{
  "room_id": "room_abc123",
  "creator": "user_001",
  "rtc_type": 1,
  "status": 1,
  "max_participants": 2,
  "duration": 0,
  "uids": ["user_001", "user_002"],
  "created_at": 1704096500,
  "updated_at": 1704096600,
  // ⬇️ Additional participant event fields
  "uid": "user_002",         // Operator triggering the event (e.g., Invitee/Joiner/Leaver)
  "device_type": "app"       // Present only in joined events
}

---

3. Internal Management API (Webhook)

These APIs are mainly used for internal system operation and maintenance:

• POST /api/v1/webhooks/livekit - Receive low-level LiveKit event callbacks
• GET /api/v1/webhooks/logs/stats - Get Webhook processing stats
• POST /api/v1/webhooks/logs/cleanup - Clean up historical logs

Request Parameters

Request Body (JSON):

Parameter	Type	Required	Description
retention_days	integer	Yes	Number of days to retain

Request Example

{
  "retention_days": 7
}

Success Response (200 OK)

{}

---

Error Codes

When an API request fails, it uniformly follows this JSON error response format:

{
  "code": 400,
  "message": "Parameter error"
}