API REFERENCE

RTCExpress Platform API

Reference for the HTTP endpoints and real-time events used by an RTCExpress integration. Start with the token endpoint, then use the SDK for normal call and chat flows.

Overview

Base URL: https://rtcplatform.duckdns.org

Use HTTPS in production. RTC clients connect to the real-time signaling service through the SDK after your backend gives them a short-lived user token.

Do not send App Secrets to browsers or mobile appsYour backend authenticates your product user, checks room access, and calls the token endpoint. It returns only the resulting RTC user token to the client.

Issue a user token

POST/v1/token

Creates a user token valid for one hour. `roomId` and `role` are optional token scopes.

Auth: No bearer token. Send the App ID and App Secret only from your backend.

Request

POST https://rtcplatform.duckdns.org/v1/token
Content-Type: application/json

{
  "appId": "app_your_project",
  "appSecret": "your-server-only-secret",
  "userId": "user_123",
  "roomId": "support-room-42",
  "role": "host"
}

Response

{
  "token": "eyJ...",
  "expiresIn": 3600
}

Read platform configuration

GET/v1/config

Returns client-safe platform configuration such as ICE/TURN settings, the SFU URL, and enabled feature flags. Your app normally does not call this directly.

Auth: Optional RTC user token. The SDK loads this during initialization.

Request

GET https://rtcplatform.duckdns.org/v1/config?appId=app_your_project
Authorization: Bearer

Read room message history

GET/v1/rooms/:roomId/messages

Retrieves message history for a room. `limit` must be 1–200. Use `before` with a positive message ID to page older messages.

Auth: Bearer RTC user token. The token must be valid for this room if room-scoped, and the user must have joined the room.

Request

GET https://rtcplatform.duckdns.org/v1/rooms/support-room-42/messages?limit=50
Authorization: Bearer

Real-time events

Use @rtc/sdk for WebSocket communication. It connects to /ws?token=<rtc-user-token> and handles the protocol for you.

connectedUser connected to signaling.

roomJoinedUser joined a room and receives its members.

messageRoom message with sender, text, and sent time.

callInviteIncoming call with call ID, sender, recipient, and room.

callStateCall lifecycle update such as ringing, connected, or ended.

errorProtocol or request error.

rtc.on("callInvite", ({ callId, fromUserId, roomId }) => {
  // Show your incoming-call interface.
});

await rtc.joinRoom("support-room-42");
rtc.sendMessage("Hello");

Customer diagnostics

GET/v1/portal/diagnostics

Returns project-scoped recent calls, events, quality reports, push attempts, webhook deliveries, and configuration status. This endpoint is intended for the signed-in customer portal, not an unauthenticated client.

Auth: Bearer portal session token from account login.

Request

GET https://rtcplatform.duckdns.org/v1/portal/diagnostics?callId=call_123
Authorization: Bearer

Errors, limits, and webhook events

HTTP errors use JSON in the form { "error": "message" }. Handle 400 for invalid input, 401 for invalid credentials or expired tokens, 403 for unauthorized room access, 429 for rate limits, and 503 when a dependent service is unavailable.

Token issuance is limited to 30 requests per IP per minute. Diagnostics is limited to 60 requests per project per minute. Design your backend to cache valid user tokens until shortly before expiry and retry only safe, transient failures.

Supported platform event types include user.joined, message.sent, call.ringing, call.connected, call.ended, recording.ready, call.quality.report, and billing.threshold. Webhook registration is managed through the platform administration flow; verify any webhook signature before trusting an event.

Need the integration guide?

Open quickstart Developer hub