Signaling Protocol

Read this page if you are:

• Writing a client in a language Livqeno has no SDK for, or
• Reading WebSocket messages in your browser's devtools.

What signaling is: before audio and video can flow, the device and the media server must agree on how to connect: which formats to use and which network path works. They agree by exchanging small JSON messages over a WebSocket. That exchange is signaling. The audio and video themselves travel separately, over WebRTC, not over this socket.

Words used on this page:

Endpoint

wss://api.livqeno.com/v1/rtc?token=<rtc token>

• Use the endpoint from the token grant as the address. It already points at the right host and ends in /v1/rtc. Don't hard-code it.
• The token goes in the URL, because browsers can't set headers on a WebSocket connection.
• Always use wss:// in production. Over plain ws://, anyone could read the token.

You talk to the server, not to other users

An older version of this protocol sent messages between browsers, with a targetParticipantId field. Some message names are the same, but their meaning changed. If a document says the server forwards sdp.offer from another browser, it's out of date.

Messages

Every message is a JSON object with a type field. All fields sit at the top level.

Client → server

Why track.publish? WebRTC itself can't say whether a track is a camera or a screen. Without this message, the server has to guess.

Server → client

speakers.changed and quality.changed are about the whole room. subscription.state and publisher.layers are about you alone. After a resumed session, you get anything you missed after room.joined, in order. Older servers never send these four; that's fine, nothing else depends on them.

The connection flow

Here's a full join, as messages. → is you sending, ← is the server.

→  (upgrade with ?token=…)
→  {"type":"room.join"}
←  {"type":"sdp.offer","sdp":"v=0…"}
←  {"type":"ice.candidate","candidate":"candidate:… typ host …","sdpMid":"0","sdpMLineIndex":0}
←  {"type":"room.joined","roomId":"…","participants":[…],"rtcServer":"sfu-01","region":"ap-south"}
→  {"type":"sdp.answer","sdp":"v=0…"}
→  {"type":"ice.candidate","candidate":"candidate:…","sdpMid":"0","sdpMLineIndex":0}
←  {"type":"connection.state","state":"connected"}

Heartbeat

A WebSocket can look open even after the network is gone. Pings let both sides notice a dead connection quickly.

Errors

The error message can have one of 20 codes:

INVALID_TOKEN, TOKEN_EXPIRED, TOKEN_REVOKED, TOKEN_INVALID, UNAUTHORIZED, ROOM_NOT_FOUND, ROOM_FULL, ROOM_CLOSED, INVALID_MESSAGE, INVALID_MESSAGE_TYPE, PARTICIPANT_NOT_FOUND, NOT_IN_ROOM, PERMISSION_DENIED, ORIGIN_NOT_ALLOWED, RATE_LIMITED, USAGE_LIMIT_EXCEEDED, NO_RTC_CAPACITY, RTC_SERVER_UNREACHABLE, NEGOTIATION_FAILED, NEGOTIATION_GLARE.

When the server closes the socket, it uses a 4xxx close code:

More detail: Close codes. Which errors you can retry: Errors.

These codes are separate from the RAVEN_* HTTP error codes. The socket protocol has its own versions and its own codes.

Limits

• The message limit is per connection.
• The connection limit is per IP address. It's checked before the token is checked.

You never get a media server address

room.joined tells you the server's name and region, so you can share them with support. But you always connect to the same endpoint, and Livqeno picks the media server for you. There's no server address to set up.

Next steps

• Events: the SDK events built on these messages.
• Errors
• Chat WebSocket protocol: the chat socket, which is a different protocol.