Room Signaling

Room uses TiRTC command channel 0x2200 to carry JSON-RPC 2.0 room signaling. Signaling synchronizes room state and does not carry audio data.

Message Format

After the device calls TiRtcWhipConnect(peer_id, token) and the connection is ready, it should listen for room signaling sent by Room service.

Room service sends room events as JSON-RPC Notification messages without id. The device does not need to reply to these events:

{
  "jsonrpc": "2.0",
  "method": "room_snapshot",
  "params": {
    "room_id": "myapp:order-20260611-001",
    "participant_id": "device_device-001",
    "self": {
      "participant_id": "device_device-001",
      "device_id": "device-001"
    },
    "participants": [
      {
        "participant_id": "device_device-001",
        "device_id": "device-001",
        "state": "active",
        "mic_state": "on"
      }
    ]
  }
}

The device can send JSON-RPC Requests or Notifications to synchronize room state. A Request must include id, and Room service returns a Response with the same id. A Notification does not include id, and Room service does not return a response.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "set_mic_state",
  "params": {
    "mic_state": "off"
  }
}

Common fields:

Field	Type	Required	Meaning
jsonrpc	string	Yes	Fixed value: 2.0.
method	string	Required for Notification / Request	Signaling method name.
params	object	Method-specific	Method parameters. Methods without parameters can omit this field.
id	number	Required for Request, forbidden for Notification	Request identifier. Events sent by Room service do not include this field.
result	object	Method-specific for successful Response	Successful request result.
error	object	Required for failed Response	JSON-RPC error object.

Methods

Method	Direction	Type	Description
join_room	Device → Room service	Request	Validates identity and audio formats, then joins the room.
leave_room	Device → Room service	Notification	Actively leaves the current session.
get_room_snapshot	Device → Room service	Request / Notification	Actively requests the current room snapshot.
set_mic_state	Device → Room service	Request / Notification	Reports the local microphone state.
room_snapshot	Room service → Device	Notification	Sent with the current room snapshot after join_room succeeds.
participant_joined	Room service → Device	Notification	Sent to other online devices after a new participant joins.
participant_left	Room service → Device	Notification	Sent to other online devices after a participant leaves.
participant_mic_state_changed	Room service → Device	Notification	Sent to other online devices after a participant's microphone state changes.
room_closed	Device → Room service / Room service → Device	Notification	Device requests closing the whole room; Room service broadcasts it to room members when the room is closed.

join_room

Direction: Device → Room service. Type: Request. Send it within 10 seconds after TiRTC connects. It can succeed only once per connection.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "join_room",
  "params": {
    "room_id": "room-001",
    "device_id": "device-001",
    "input_audio": {"codec": "pcm", "sample_rate": 16000, "channels": 1},
    "output_audio": {"codec": "g711a", "sample_rate": 16000, "channels": 1}
  }
}

room_id and device_id must match the signed WHIP Token parameters. The codec and sample rate for input_audio and output_audio can be specified independently. Both directions support opus, pcm, g711a, and amr at sample rates of 8000 and 16000, with one channel. amr/8000/1 corresponds to AMR-NB, while amr/16000/1 corresponds to AMR-WB. A successful response contains session_id and the normalized input_audio and output_audio; the device must use the actual formats returned in the response.

The legacy start_session method is no longer supported. If the first business Request with an id after TiRTC connects is not join_room, Room service returns method_not_found and closes the connection. It also closes the connection if the device does not complete the join within 10 seconds.

leave_room

Direction: Device → Room service. Type: Notification. When actively leaving, send it before closing the media connection.

{
  "jsonrpc": "2.0",
  "method": "leave_room"
}

leave_room takes no parameters and must not include id. Room service immediately removes the current participant, closes the current session, and sends participant_left to other online devices. If id is present, Room service returns invalid_request and does not leave the room.

Room service also performs fallback cleanup when the device disconnects or calls DELETE session. Normal leave flows should send leave_room first.

get_room_snapshot

Direction: Device → Room service.

Type: Request or Notification.

Trigger: sent when the device needs to refresh its local participant list. Common cases include command-channel open, a missed initial snapshot, or local state realignment.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "get_room_snapshot",
  "params": {}
}

Fields:

Field	Type	Required	Meaning
jsonrpc	string	Yes	Fixed value: 2.0.
id	number	Required for Request; forbidden for Notification	Request identifier. Omit it when sending a Notification.
method	string	Yes	Fixed value: get_room_snapshot.
params	object	No	No parameters currently. Omit it or pass an empty object.

After successful processing, Room service sends a room_snapshot Notification to the current device. If the device sends a Request with id, Room service also returns a JSON-RPC success or error Response.

set_mic_state

Direction: Device → Room service.

Type: Request or Notification.

Trigger: sent when the local microphone switch or speaking state changes. This signaling only synchronizes state. It does not directly control audio mixing; the device still controls local capture and uplink audio.

{
  "jsonrpc": "2.0",
  "method": "set_mic_state",
  "params": {
    "mic_state": "speaking"
  }
}

Fields:

Field	Type	Required	Meaning
jsonrpc	string	Yes	Fixed value: 2.0.
id	number	Required for Request; forbidden for Notification	Request identifier. Omit it when sending a Notification.
method	string	Yes	Fixed value: set_mic_state.
params	object	Yes	Microphone state parameters.
params.mic_state	string	Yes	on means on, speaking means on and currently speaking, and off means off.

After recording the state, Room service sends participant_mic_state_changed to other online devices. If the device sends a Request with id, the success response is:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "ok": true
  }
}

room_snapshot

Direction: Room service → Device.

Type: Notification.

Trigger: sent to the device after it connects and joins the room, carrying the current room snapshot.

{
  "jsonrpc": "2.0",
  "method": "room_snapshot",
  "params": {
    "room_id": "myapp:order-20260611-001",
    "participant_id": "device_device-001",
    "self": {
      "participant_id": "device_device-001",
      "device_id": "device-001"
    },
    "participants": [
      {
        "participant_id": "device_device-002",
        "device_id": "device-002",
        "state": "active",
        "mic_state": "on"
      }
    ]
  }
}

Fields:

Field	Type	Required	Meaning
jsonrpc	string	Yes	Fixed value: 2.0.
method	string	Yes	Fixed value: room_snapshot.
params	object	Yes	Current room snapshot parameters.
id	number	No	Notification messages do not include id.
params.room_id	string	Yes	Room ID.
params.participant_id	string	Yes	Participant ID of the device receiving this snapshot.
params.self	object	Yes	Information about the current device.
params.self.participant_id	string	Yes	Participant ID of the current device.
params.self.device_id	string	Yes	Current device ID.
params.participants	array	Yes	Current participant list in the room.
params.participants[].participant_id	string	Yes	Participant ID.
params.participants[].device_id	string	Yes	Device ID for this participant.
params.participants[].state	string	Yes	Participant state. Online participants currently use active.
params.participants[].mic_state	string	Yes	Participant microphone state: on, speaking, or off.

participant_joined

Direction: Room service → Device.

Type: Notification.

Trigger: sent to other online devices after a new participant has connected and joined the room.

{
  "jsonrpc": "2.0",
  "method": "participant_joined",
  "params": {
    "room_id": "myapp:order-20260611-001",
    "participant": {
      "participant_id": "device_device-002",
      "device_id": "device-002",
      "state": "active",
      "mic_state": "on"
    }
  }
}

Fields:

Field	Type	Required	Meaning
jsonrpc	string	Yes	Fixed value: 2.0.
method	string	Yes	Fixed value: participant_joined.
params	object	Yes	Parameters for the newly joined participant.
id	number	No	Notification messages do not include id.
params.room_id	string	Yes	Room ID.
params.participant	object	Yes	Information about the newly joined participant.
params.participant.participant_id	string	Yes	Participant ID of the newly joined member.
params.participant.device_id	string	Yes	Device ID of the newly joined member.
params.participant.state	string	Yes	Participant state. Online participants currently use active.
params.participant.mic_state	string	Yes	Microphone state of the newly joined member: on, speaking, or off.

participant_left

Direction: Room service → Device.

Type: Notification.

Trigger: sent to other online devices after a participant disconnects or leaves the room.

{
  "jsonrpc": "2.0",
  "method": "participant_left",
  "params": {
    "room_id": "myapp:order-20260611-001",
    "participant_id": "device_device-002"
  }
}

Fields:

Field	Type	Required	Meaning
jsonrpc	string	Yes	Fixed value: 2.0.
method	string	Yes	Fixed value: participant_left.
params	object	Yes	Parameters for the participant that left.
id	number	No	Notification messages do not include id.
params.room_id	string	Yes	Room ID.
params.participant_id	string	Yes	Participant ID of the member that left.

participant_mic_state_changed

Direction: Room service → Device.

Type: Notification.

Trigger: sent to other online devices after a participant reports a microphone state change through set_mic_state.

{
  "jsonrpc": "2.0",
  "method": "participant_mic_state_changed",
  "params": {
    "room_id": "myapp:order-20260611-001",
    "participant_id": "device_device-002",
    "mic_state": "off"
  }
}

Fields:

Field	Type	Required	Meaning
jsonrpc	string	Yes	Fixed value: 2.0.
method	string	Yes	Fixed value: participant_mic_state_changed.
params	object	Yes	Participant microphone state change parameters.
id	number	No	Notification messages do not include id.
params.room_id	string	Yes	Room ID.
params.participant_id	string	Yes	Participant ID of the member whose state changed.
params.mic_state	string	Yes	on means on, speaking means on and currently speaking, and off means off.

room_closed

Direction: Device → Room service; Room service → Device.

Type: Notification.

Trigger: A device can send this notification to request closing the whole room when allowed by your business rules. Room service sends this notification to room members when the room is closed.

{
  "jsonrpc": "2.0",
  "method": "room_closed",
  "params": {
    "room_id": "myapp:order-20260611-001",
    "reason": "closed_by_service"
  }
}

Fields:

Field	Type	Required	Meaning
jsonrpc	string	Yes	Fixed value: 2.0.
method	string	Yes	Fixed value: room_closed.
params	object	Yes	Room close parameters.
id	number	No	Notification messages do not include id.
params.room_id	string	Yes	Room ID.
params.reason	string	No	Close reason. If omitted, the device should only treat the room as closed.

Request And Response

The device must send join_room as a Request and can also send get_room_snapshot and set_mic_state as Requests. A Request with id receives a success or error Response. leave_room must be sent as a Notification without id and receives no response.

Request example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "set_mic_state",
  "params": {
    "mic_state": "off"
  }
}

Request fields:

Field	Type	Required	Meaning
jsonrpc	string	Yes	Fixed value: 2.0.
id	number	Yes	Request identifier. Room service returns the same value in the response.
method	string	Yes	Request method name. The public device Request methods are join_room, get_room_snapshot, and set_mic_state.
params	object	No	Request parameters. Omit it or pass an empty object when there are no parameters.

Error Response example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "method not found"
  }
}

Error Response fields:

Field	Type	Required	Meaning
jsonrpc	string	Yes	Fixed value: 2.0.
id	number	Yes	The matching Request id.
error	object	Yes	Error object.
error.code	number	Yes	Error code.
error.message	string	Yes	Error message.
result	object	No	Successful response result. Error responses do not include this field.

Error Codes

Room service follows the JSON-RPC 2.0 error response format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "method not found"
  }
}

Room service defines these standard error codes:

Code	Name	Description
-32700	parse_error	JSON parsing failed.
-32600	invalid_request	The request is invalid.
-32601	method_not_found	The method does not exist or is not publicly available.
-32602	invalid_params	The parameters are invalid.
-32603	internal_error	An internal error occurred.

Room service also defines these business error codes:

Code	Name	Description
-32001	room_not_ready	The room session is not ready.
-32002	participant_mismatch	The participant in signaling does not match the token.
-32003	room_full	The room participant limit was reached.
-32004	permission_denied	The operation is not allowed.

Handling Recommendations

• After TiRTC TiRtcWhipConnect reports that the connection is ready, send join_room first. After it succeeds, listen for room_snapshot to initialize the local participant list. Send get_room_snapshot if the device needs to actively realign state.
• Update local participant state after receiving participant_joined, participant_left, or participant_mic_state_changed.
• Send set_mic_state when the local microphone switch or speaking state changes. This method only synchronizes state and does not replace local capture or uplink control.
• When actively leaving, send a leave_room Notification before entering resource cleanup.
• After receiving room_closed, stop playback and release local media resources immediately.