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:

Parameters	Type	Description
type	String	Message type, as defined below.
client_id	String	Client identity.
session_id	String	ID of this session.
data	Dictonary	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

Parameters	Type	Description
sdp	RTCSessionDescription	Session Description of the stream as returned from webrtc js api.
webhook_url	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

Parameters	Type	Description
sdp	RTCSessionDescription	Session Description of the stream as returned from webrtc js api.
session_id_to_monitor	String	SessionID of the client which will be monitored.
webhook_url	String (optional)	Webhook which will be called on different kind of events.

sdp_update

Delivers SDP updates in both directions.

Direction: client ↔ server

Parameters	Type	Description
sdp	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

Parameters	Type	Description
candidate	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

Parameters	Type	Description
upload_url	String	Upload URL. The Upload will be performed via PUT-method.
webhook_url	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

Parameters	Type	Description
recording_id	String	Identitiy of this recording.
state	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.

Parameters	Type	Description
state	String	State of this session.
termination_cause	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.