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.

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"
  }
}

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.

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

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.

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.