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 has been 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 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 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

  • eventsink_started
  • eventsink_updated
  • 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, had its configuration updated, or was 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_ended
  • conference_updated

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 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": 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 contains 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.
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)
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.
uuid string Pexip Infinity's unique identifier for this participant.
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
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.
disconnect_reason string The disconnect reason for this call.

Example:

{
	"data": {
		"call_direction": "in",
		"call_id": "ac58a572-33e5-4b19-ac1c-f0b1d22215e6",
		"call_tag": "def456",
		"conference": "meet.webapp",
		"connect_time": 1559897886.593371,
		"service_tag": "",
		"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_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"
			}
		],
		"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
}