Skip to main content

Realtime Messaging

The realtime messaging interface (RTM) allows to:

  • setup the stream connection
  • configure the recording upload destination
  • retrieve state information
  • controls the lifetime of the stream

Base message structure:

type​

Type: STRING
Message type, as defined below.

client_id​

Type: STRING
Client identity.

session_id​

Type: STRING
ID of this session.

data​

Type: DICTIONARY
Data of that message. Specific for each message type. As defined below.

Example for the base message:

{
    "type": "session_start",
    "client_id": "c-0",
    "session_id": "s-1",
    "data": { ... }
}

session_start​

Starts a client session with an SDP offer and a webhook-URL.

Direction: client → server

sdp​

Type: RTCSessionDescription
Session Description of the stream as returned from webrtc js api.

webhook_url​

Type: STRING (optional)
Webhook which will be called on different kind of events.

version​

Type: STRING (optional)
Provide the version of the client.

Example:

{
  "type": "session_start",
  "client_id": "client-3987830",
  "session_id": "2633650b-9e24-4872-aec5-b39cdfc65ebf",
  "data": {
    "sdp": {
      "type": "offer",
      "sdp": "..."
    },
    "webhook_url": "https://yourserver.com/streamrec",
    "version": "v1.2.3"
  }
}

supervisor_join_session​

Starts a supervisor session with sdp and session-id to be monitored.

Direction: client → server

sdp​

Type:RTCSessionDescription
Session Description of the stream as returned from webrtc js api.

session_id_to_monitor​

Type: STRING
SessionID of the client which will be monitored.

webhook_url​

Type: STRING (optional)
Webhook which will be called on different kind of events.

sdp_update​

Delivers SDP updates in both directions.

Direction: client ↔ server

sdp​

Type: RTCSessionDescription
Session Description of the stream as returned from webrtc js api.

{
  "type": "sdp_update",
  "client_id": "client-3987830",
  "session_id": "2633650b-9e24-4872-aec5-b39cdfc65ebf",
  "data": {
    "sdp": {
      "type": "answer",
      "sdp": "..."
    }
  }
}

candidate​

Delivers webrtc candidates in both directions. This is called the trickle features of webrtc.

Direction: client ↔ server

candidate​

Type:RTCIceCandidate
Webrtc sdp candidate.

{
  "client_id": "client-3987830",
  "session_id": "2633650b-9e24-4872-aec5-b39cdfc65ebf",
  "type": "candidate",
  "data": {
    "candidate": {
      "candidate": "candidate:170793244 1 udp 2122194687 192.168.0.188 44360 typ host generation 0 ufrag AwAs network-id 1",
      "sdpMid": "0",
      "sdpMLineIndex": 0,
      "usernameFragment": "AwAs"
    }
  }
}

recording_start​

Start recording while providing an upload-url.

Direction: client → server

upload_url​

Type: STRING
Upload URL. The Upload will be performed via PUT-method.

webhook_url​

Type: STRING (optional)
Set webhook URL for events for this recording.

stream_id​

Type: STRING
The stream-id itentifying the track to be recorded.

info

Any response status code other than 200 that is received from the upload URL, will be considered as upload failed.

recording_stop​

Stops the active recording.

Direction: client → server

stream_id​

Type: STRING
The stream-id of the track whose recording is to be stopped.

recording_state​

Informs client of new recording-id, and its state.

Direction: server → client

recording_id​

Type: STRING
Identitiy of this recording.

state​

Type: STRING
State of this recording.

stream_id​

Type: STRING
The stream-id of the recording.

Possible states are:

  • STARTED
  • STOPPED
  • FAILED

session_stop​

Direction: client → server

Note: A session can be stopped via disconnecting the WS channel as well. If a recording is still ongoing, it will be finished and uploaded properly.

session_state​

Deliver state info for a session.

Direction: server → client Purpose: Give state info of the session.

state​

Type: STRING
State of this session.

termination_cause​

Type: STRING (optional)
Cause of termination.

For possible states jump to the lifecycle section.

{
  "type": "session_state",
  "client_id": "client-3987830",
  "session_id": "2633650b-9e24-4872-aec5-b39cdfc65ebf",
  "data": {
    "state": "TERMINATED",
    "termination_cause": "TERM_BY_CLIENT"
  }
}

msg ping​

Sends a ping message to the server.

Direction: client → server

Note, that this is an application ping and does not use the websockets ping/pong mechanism.

msg pong​

Reply to a ping.

Direction: server → client

Note, that this is an application ping and does not use the websockets ping/pong mechanism.