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.

Common fields

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 Start Conference).
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:

  • conference: a Virtual Meeting Room
  • lecture : a Virtual Auditorium
  • two_stage_dialing: a Virtual Reception
  • test_call: a Test Call Service call
  • gateway: an Infinity Gateway call.
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.
participant_media_streams_destroyed * A participant disconnects.

* Version 2 of the event sink API only.

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:

  • in: a call into Pexip Infinity
  • out: a call dialed out from Pexip Infinity.
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, chat for Skype for Business / Lync connections.
destination_alias string The alias that was dialed in order to connect to the service.
display_name string The display name of the participant.
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:

  • WebRTC
  • SIP
  • H323
  • TEAMS (for Microsoft Teams)
  • MSSIP (for Skype for Business / Lync)
  • GHM (for Google Meet)
  • RTMP
  • API (for presentation and control-only)
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:

  • chair: the participant is a Host
  • guest: the participant is a Guest
  • unknown: the participant is in a Virtual Reception, at the PIN entry screen, or at the Waiting for Host screen but their role has not yet been determined
service_tag string The unique identifier for the service, if configured.
service_type string

The service type of the conference to which the participant is connected. This is one of the following:

  • connecting: the participant is joining, or a call is being placed to the participant
  • conference: a Virtual Meeting Room or Virtual Auditorium
  • two_stage_dialing: a Virtual Reception
  • test_call: a Test Call Service call
  • ivr: the participant is at the PIN entry or Waiting for Host screen.
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.
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:

Field Type Description
tx_packets_lost integer Count of sent packets lost as reported by far end.
stream_id string A numeric identifier for this stream.
time_delta float The time difference from when the previous statistics were created, in Unix time.
tx_packets_sent integer Count of packets sent.
rx_packets_received integer Count of packets received.
rx_packets_lost integer Count of packets lost.
time float The time these statistics were created, in Unix time.
stream_type string The media type for this stream (“audio”, “video”, or “presentation”).
recent_quality array

A list of call quality statistics for the current call quality window, made up of objects containing the following fields:

Field Type Description
applicationsharing integer Latest quality for Skype for Business RDP presentation / application sharing (null = not in use, 0 = Unknown, 1 = Good).
quality integer Aggregate (audio and video) quality (null = not in use, 0 = Unknown, 1 = Good, 2 = OK, 3 = Bad, 4 = Terrible).
video integer Latest video quality (null = not in use, 0 = Unknown, 1 = Good, 2 = OK, 3 = Bad, 4 = Terrible).
time_delta float The time difference from when the previous statistics were created, in Unix time.
time float The time these statistics were created, in Unix time.
audio integer Latest audio quality (null = not in use, 0 = Unknown, 1 = Good, 2 = OK, 3 = Bad, 4 = Terrible).
presentation integer Latest presentation stream quality (null = not in use, 0 = Unknown, 1 = Good, 2 = OK, 3 = Bad, 4 = Terrible).
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:

Field Type Description
end_time float The time this stream ended, in Unix time.
node string The media node handling this stream.
rx_bitrate integer The receive bitrate for this stream, in kbps.
rx_codec string The codec being received for this media stream.
rx_fps float The received frames per second.
rx_packet_loss float The receive packet loss percentage.
rx_packets_lost integer Count of packets lost.
rx_packets_received integer Count of packets received.
rx_resolution string Resolution of video received.
start_time float The start time of this stream, in Unix time.
stream_id string A numeric identifier for this stream.
stream_type string The media type for this stream (“audio”, “video”, or “presentation”).
tx_bitrate integer The sending bitrate for this stream, in kbps.
tx_codec string The codec being sent for this media stream.
tx_fps float The sent frames per second.
tx_packet_loss float The sending packet loss percentage.
tx_packets_lost integer Count of sent packets lost as reported by far end.
tx_packets_sent integer Count of packets sent.
tx_resolution string Resolution of video sent.
In participant_disconnected only
disconnect_reason string The disconnect reason for this call.
media_streams array

A list of end-of-call media statistics, made up of objects containing the following fields:

Field Type Description
end_time float The time this stream ended, in Unix time.
node string The media node handling this stream.
rx_bitrate integer The receive bitrate for this stream, in kbps.
rx_codec string The codec being received for this media stream.
rx_fps float The received frames per second.
rx_packet_loss float The receive packet loss percentage.
rx_packets_lost integer Count of packets lost.
rx_packets_received integer Count of packets received.
rx_resolution string Resolution of video received.
start_time float The start time of this stream, in Unix time.
stream_id string A numeric identifier for this stream.
stream_type string The media type for this stream (“audio”, “video”, or “presentation”).
tx_bitrate integer The sending bitrate for this stream, in kbps.
tx_codec string The codec being sent for this media stream.
tx_fps float The sent frames per second.
tx_packet_loss float The sending packet loss percentage.
tx_packets_lost integer Count of sent packets lost as reported by far end.
tx_packets_sent integer Count of packets sent.
tx_resolution string Resolution of video sent.

† Version 1 of the event sink API only.

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