Event sink API

This topic describes the content of the event messages which will be sent from Conferencing Nodes to an event sink server when an event sink has been configured for the node's location.

Common fields

All messages are JSON objects and contain the following common fields:

Field Type Descripiton
node string The originating Conferencing Node's primary IP address.
seq integer The sequence number of this event on this Conferencing Node, from the time at which the event sink was configured on this node.
version integer The internal Pexip protocol version supported by this event sink (currently 1).
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 will depend 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

  • eventsink_started
  • eventsink_stopped

These messages do not include any further information in the data field; they just confirm the time at which an event sink was configured, or removed from configuration.

Example

{	"node": "10.44.99.2", 
	"seq": 1, 
	"version": 1, 
	"time": 1559897774.520606, 
	"data": {}, 
	"event": "eventsink_started"
}

Conference events

  • conference_started
  • conference_updated
  • conference_ended

These events declare the start, stop, and change in properties of a conference 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 will contain 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
  • gateway: a Pexip Distributed 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": 1
}

Participant events

  • participant_connected
  • participant_updated
  • participant_disconnected

These events declare when a participant joins a conference, when a property of the participant changes, and when the participant disconnects.

The data field for these events will contain the following properties about the participant:

Field Type Description
In all participant 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.
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_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.
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 Waiting for Host screen, or at the PIN entry screen.
service_type string

The service type of the conference to which the participant is connected. This can be:

  • conference: a Virtual Meeting Room or a Virtual Auditorium
  • two_stage_dialing: a Virtual Reception
  • waiting_room: the participant is at the Waiting for Host screen.
signalling_node string TThe 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.
uuid string Pexip Infinity's unique identifier 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_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:

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_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 integer 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_packet_loss float the sending packet loss percentage
tx_packets_lost integer count of sent packets lost as reported by far end
tx_packets_received integer count of packets sent
tx_resolution string resolution of video sent

Example:

{
	"data": {
		"call_direction": "in",
		"call_id": "ac58a572-33e5-4b19-ac1c-f0b1d22215e6",
		"conference": "meet.webapp",
		"connect_time": 1559897886.593371,
		"conversation_id": "ac58a572-33e5-4b19-ac1c-f0b1d22215e6",
		"destination_alias": "meet.webapp",
		"disconnect_reason": "Call disconnected",
		"display_name": "Alice",
		"has_media": false,
		"is_muted": false,
		"is_presenting": false,
		"is_streaming": false,
		"media_node": "10.47.2.21",
		"media_streams": [
			{
			"end_time": 1559902945.767812,
			"node": "10.47.2.21",
			"rx_bitrate": 32,
			"rx_codec": "opus",
			"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_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_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_packet_loss": 0.0,
			"tx_packets_lost": 0,
			"tx_packets_sent": 6883,
			"tx_resolution": "1280x720"
			}
		],	"protocol": "WebRTC",
		"remote_address": "10.47.2.200",
		"role": "chair",
		"service_type": "conference",
		"signalling_node": "10.47.2.21",
		"source_alias": "Alice",
		"system_location": "Oslo",
		"uuid": "ac58a572-33e5-4b19-ac1c-f0b1d22215e6",
		"vendor": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.110 Safari/537.36"
	},
	"event": "participant_disconnected",
	"node": "10.47.2.21",
	"seq": 4,
	"time": 1559897888.526124,
	"version": 1
}