Event sink API
This topic describes the content of the event messages which are sent from Conferencing Nodes to an event sink server when an event sink is configured for the node's location.
Performance considerations
Events are sent from Pexip Infinity to the event sink in order, one-by-one. Thus it is important that your event sink server is capable of consuming events as quickly as they are generated.
If events are not consumed quickly enough, or if there is a temporary network connectivity glitch, a queue may build up and delivery of subsequent events may become increasingly delayed until the backlog is cleared. There could, for example, be a significant burst of events following a network connectivity issue.
Therefore, we recommend that you pursue an event sink server design that enables rapid receipt of events and avoids any lengthy or blocking "in line" processing of events as they arrive.
This could be achieved, for example, by immediately offloading processing of received events to a local queue for handling by another thread (or by using other mechanisms appropriate for your chosen technology stack). We also recommend that you build in suitable diagnostics that allow you to measure and diagnose any performance issues should your server not be able to keep pace with the events that are arriving.
Message structure
All messages are JSON objects and contain the following common fields:
| Field | Type | Description |
|---|---|---|
| node | string | The originating Conferencing Node's primary IP address. |
| seq | integer |
The sequence number of this event on this Conferencing Node, from the point at which the event sink was started on this node. If an event sink is started, stopped, and started again, the sequence number will begin again at 1. Note that if you have more than one event sink configured, each event is sent within its own consecutively numbered series per event sink. This means that if the event sinks are started at different times, the same event will have a different sequence number on each event sink. |
| version | integer | The internal Pexip protocol version supported by this event sink (currently 2). |
| time | float | The timestamp of this message, in Unix time. |
| event | string | The name of the event. |
| data | array | A list of event-specific data fields and their values. The content depends on the type of event and is described further in the following sections. |
Events
Events can be grouped into three types:
A description of each group, and the content of the data fields for each, is described in the following sections.
Event sink events
There are the following event sink events:
| Event | Occurs when... |
|---|---|
| eventsink_started | An event sink starts. |
| eventsink_updated | A property of the event sink changes. |
| eventsink_ended | A event sink stops. |
These messages do not include any further information in the data field; they just confirm the time at which an event sink was configured, had its configuration updated, or was removed from configuration.
Example
{ "node": "10.44.99.2",
"seq": 1,
"version": 2,
"time": 1559897774.520606,
"data": {},
"event": "eventsink_started"
}
Conference events
There are the following conference events:
| Event | Occurs when... |
|---|---|
| conference_started | A conference starts. |
| conference_updated | A property of the conference changes. |
| conference_ended | A conference stops. |
These events are from the perspective of a Conferencing Node. This means you will see multiple conference_started and conference_ended events for the same conference, but from different nodes, as participants join and leave.
The data field for these events contains the following properties about the conference:
| Field | Type | Description |
|---|---|---|
| In all conference events | ||
| guests_muted | Boolean | Whether all Guests are muted. |
| is_locked | Boolean | Whether the conference is locked. |
| is_started | Boolean | Whether the conference has been started (i.e. a Host participant has joined with audio or video, or a presentation-only Host has selected ). |
| name | string | The name of this conference. This can be used to correlate conference events for the same conference across multiple Conferencing Nodes. |
| service_type | string |
The service type of the conference. This is one of the following:
|
| start_time | float | The time this conference started on this Conferencing Node, in Unix time. |
| tag | string |
A unique identifier used to track usage of this service. |
| In conference_ended events only | ||
| end_time | float | The time this conference ended on this Conferencing Node, in Unix time. |
Example:
{
"data": {
"guests_muted": false,
"is_locked": false,
"is_started": false,
"name": "meet.webapp",
"service_type": "conference",
"start_time": 1559897886.582629,
"tag": ""
},
"event": "conference_started",
"node": "10.47.2.21",
"seq": 2,
"time": 1559897886.582799,
"version": 2
}
Participant events
There are the following participant events:
| Event | Occurs when... |
|---|---|
| participant_connected | A participant joins a conference. |
| participant_updated | A property of the participant changes. |
| participant_media_stream_window |
There is a change in the participant's perceived call quality e.g. from "good" to "bad". |
| participant_disconnected | A participant disconnects (call signaling). |
| participant_media_streams_destroyed |
A participant disconnects (media stream). |
|
|
|
The data field for these events contains the following properties about the participant:
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| In all participant events | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| uuid | string | Pexip Infinity's unique identifier for this participant. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| In all participant_connected, participant_updated and participant_disconnected events | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| call_direction | string |
Either:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| call_id | string | An identifier that allows correlation of messages from the same call. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| call_tag | string | An optional call tag assigned to this participant. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| conference | string | The name of the conference. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| connect_time | float | The time this participant connected, in Unix time. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| conversation_id | string | An identifier that allows correlation of messages across separate "calls" for video+audio, RDP, or chat. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| destination_alias | string | The alias that was dialed in order to connect to the service. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| display_name | string | The display name of the participant. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| encryption | string |
"On" or "Off" as to whether this participant is connected via encrypted media. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| has_media | Boolean | Whether this participant is using media. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| is_muted | Boolean | Whether this participant is administratively muted. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| is_presenting | Boolean | Whether this participant is sending a presentation. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| is_streaming | Boolean | Whether this participant has the streaming flag set. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| media_node | string | The IP address of the Conferencing Node handling the media processing for the call. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| protocol | string |
The protocol used for the call:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| proxy_node | string |
The address of the Proxying Edge Node that is handling the call, if applicable. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| related_uuids | array | A list of related participant events. To get all of the data for a participant you must gather all participant events whose uuid is in the related_uuids array. These could be for a related presentation or audio/video stream for the same logical participant. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| remote_address | string | The source IP address for the signaling for this call. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| role | string |
The role of this participant:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| rx_bandwidth | integer | Receive bandwidth in kbps. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| service_tag | string | The unique identifier for the service, if configured. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| service_type | string |
The service type of the conference
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| signalling_node | string | The IP address of the Conferencing Node handling the signaling for the call. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| source_alias | string | The source alias of this call. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| system_location | string | The name of the Pexip Infinity location handling the signaling for this call. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| tx_bandwidth | integer | Transmit bandwidth in kbps. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| vendor | string | System details about the endpoint of the participant, such as manufacturer name and version number for hard endpoints, or browser and operating system details for soft clients. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| In participant_media_stream_window only | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| packet_loss_history | array |
A list of packet loss statistics, since the previous window's list, made up of objects containing the following fields:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| recent_quality | array |
A list of call quality statistics for the current call quality window, made up of objects containing the following fields:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| call_quality_was | string | The previous call quality ("0_unknown", "1_good", "2_ok", "3_bad", or "4_terrible"). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| call_quality_now | string | The current call quality ("0_unknown", "1_good", "2_ok", "3_bad", or "4_terrible"). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| In participant_media_streams_destroyed only | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| media_streams | array |
A list of end-of-call media statistics, made up of objects containing the following fields:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| In participant_disconnected only | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| disconnect_reason | string | The disconnect reason for this call. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| duration | float | The call duration in seconds. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| end_time | float | The time the participant disconnected, in Unix time. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| media_streams |
array |
A list of end-of-call media statistics, made up of objects containing the following fields:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Example "participant_disconnected" event (version 2 API):
{
"node": "10.44.34.11",
"seq": 688,
"version": 2,
"time": 1606392917.976155,
"data": {
"protocol": "WebRTC",
"disconnect_reason": "Timer expired awaiting token refresh",
"is_presenting": false,
"connect_time": 1606392757.777584,
"service_tag": "",
"call_tag": "",
"license_count": 1,
"duration": 160.19991468900116,
"media_node": "10.44.34.11",
"conference": "Alice's VMR",
"source_alias": "Alice",
"display_name": "Alice",
"uuid": "a0ed2c58-f45b-4d96-a1cb-89812ec938ea",
"signalling_node": "10.44.34.15",
"call_id": "a0ed2c58-f45b-4d96-a1cb-89812ec938ea",
"vendor": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.1 Safari/605.1.15",
"role": "chair",
"conversation_id": "a0ed2c58-f45b-4d96-a1cb-89812ec938ea",
"rx_bandwidth": 1722,
"tx_bandwidth": 868,
"destination_alias": "meet.alice",
"is_streaming": false,
"is_muted": false,
"related_uuids": [
"0b8eb723-cf9d-4540-b12d-0f28149a7560"
],
"remote_address": "10.44.250.22",
"proxy_node": "10.44.34.15",
"service_type": "conference",
"has_media": true,
"system_location": "Ruscombe",
"call_direction": "in",
"end_time": 1606392917.976151
},
"event": "participant_disconnected"
}
Example "participant_media_stream_window" event:
{
"node": "10.0.1.52",
"seq": 29,
"version": 2,
"time": 1603188859.437286,
"data": {
"packet_loss_history": [
{
"tx_packets_lost": 0,
"stream_id": "0",
"time_delta": -19.79547445800017,
"tx_packets_sent": 1227,
"rx_packets_received": 1120,
"rx_packets_lost": 58,
"time": 1603188839.639175,
"stream_type": "audio"
},
{
"tx_packets_lost": 0,
"stream_id": "1.0",
"time_delta": -17.901532250999935,
"tx_packets_sent": 2552,
"rx_packets_received": 1901,
"rx_packets_lost": 104,
"time": 1603188841.533143,
"stream_type": "video"
},
{
"tx_packets_lost": 0,
"stream_id": "1.1",
"time_delta": -2.8826062080001975,
"tx_packets_sent": 3958,
"rx_packets_received": 3324,
"rx_packets_lost": 169,
"time": 1603188856.552285,
"stream_type": "video"
},
{
"tx_packets_lost": 0,
"stream_id": "0",
"time_delta": 0,
"tx_packets_sent": 2217,
"rx_packets_received": 2049,
"rx_packets_lost": 117,
"time": 1603188859.434931,
"stream_type": "audio"
}
],
"recent_quality": [
{
"applicationsharing": null,
"quality": 1,
"video": 0,
"time_delta": -42.044601973000226,
"time": 1603188817.38981,
"audio": 1,
"presentation": null
},
{
"applicationsharing": null,
"quality": 3,
"video": 3,
"time_delta": 0,
"time": 1603188859.435012,
"audio": 3,
"presentation": null
}
],
"call_quality_was": "1_good",
"uuid": "c0548ea2-6ba5-4726-a022-019c0cad75b6",
"call_quality_now": "3_bad"
},
"event": "participant_media_stream_window"
}
Example "participant_media_streams_destroyed" event
{
"node": "10.44.34.11",
"seq": 687,
"version": 2,
"time": 1606392917.869103,
"data": {
"uuid": "0b8eb723-cf9d-4540-b12d-0f28149a7560",
"media_streams": [
{
"end_time": 1559902945.767812,
"node": "10.47.2.21",
"rx_bitrate": 32,
"rx_codec": "opus",
"rx_fps": 0.0,
"rx_packet_loss": 0.0,
"rx_packets_lost": 0,
"rx_packets_received": 1977,
"rx_resolution": "",
"start_time": 1559902904.1698,
"stream_id": "0",
"stream_type": "audio",
"tx_bitrate": 1,
"tx_codec": "opus",
"tx_fps": 0.0,
"tx_packet_loss": 0.0,
"tx_packets_lost": 0,
"tx_packets_sent": 2020,
"tx_resolution": ""
},
{
"end_time": 1559902945.768668,
"node": "10.47.2.21",
"rx_bitrate": 1405,
"rx_codec": "VP8",
"rx_fps": 30.0,
"rx_packet_loss": 0.0,
"rx_packets_lost": 0,
"rx_packets_received": 4493,
"rx_resolution": "1280x720",
"start_time": 1559902904.318265,
"stream_id": "1.2",
"stream_type": "video",
"tx_bitrate": 1545,
"tx_codec": "VP8",
"tx_fps": 30.0,
"tx_packet_loss": 0.0,
"tx_packets_lost": 0,
"tx_packets_sent": 6883,
"tx_resolution": "1280x720"
}
]
},
"event": "participant_media_streams_destroyed"
}