Pexip client REST API

This guide describes the Pexip client REST API. It is designed for use by non-web-based, third-party voice/video applications that want to initiate or connect to conferences hosted on the Pexip Infinity platform.

We strongly recommend that web-based applications use the PexRTC JavaScript client API instead.

This API specification is regularly evolving between versions of the Pexip Infinity platform. While we will attempt to maintain backward compatibility, there may be significant changes between versions.

Using the API

The prefix for all conference-related API calls is:

https://<node_address>/api/client/v2/conferences/<conference_alias>/

where <node_address> is the address of a Conferencing Node and <conference_alias> is an alias of the conference you are connecting to. Under this API path comes a sequence of response API calls, for example:

https://10.0.0.1/api/client/v2/conferences/meet_alice/request_token

All commands in the client API are authenticated with a token, which is presented by the Pexip Conferencing Node. The token has a validity lifetime, before the end of which it must be refreshed. The token is presented in a HTTP header entitled "token" on every HTTP request, except for the initial request_token request.

Unless otherwise specified, all payloads of requests and responses are JSON objects, Content-Type: application/json.

The responses have two fields, status and result:

• status is "success" if the command has been processed by Pexip, or "failure" if the command could not be processed. Note that this does not mean that the end result is success, only that the request has been received and processed.
• the result field indicates if the request was successful.

Summary of API requests and events

This section summarizes the requests and server-sent events that may be used, which are then described in more detail.

Client control requests summary

These REST URIs take the format:

https://<node_address>/api/client/v2/conferences/<conference_alias>/<request>

Conference control functions summary

These REST URIs take the format:

https://<node_address>/api/client/v2/conferences/<conference_alias>/<request>

Participant functions summary

These participant REST URIs take the format:

https://<node_address>/api/client/v2/conferences/<conference_alias>/participants/<participant_uuid>/<request>

Breakout room functions summary

Many breakout room REST URIs take the format:

https://<node_address>/api/client/v2/conferences/<conference_alias>/breakouts/<breakout_uuid>/<request>

See Breakout rooms functions for details.

Call functions summary

These call REST URIs take the format:

https://<node_address>/api/client/v2/conferences/<conference_alias>/participants/<participant_uuid>/calls/<call_uuid>/<request>

Server-sent events summary

To subscribe, open an HTTP connection to:

https://<node_address>/api/client/v2/conferences/<conference_alias>/events?token=<token_id>

Other requests summary

Client control requests

This section describes in detail the requests that may be used to initiate and manage a connection to a Conferencing Node.

These REST URIs take the format:

https://<node_address>/api/client/v2/conferences/<conference_alias>/<request>

request_token

This POST requests a new token from the Pexip Conferencing Node.

Request example:

{"display_name": "Alice", "call_tag": "def456"}

Request fields:

Response example:

{'status': 'success',
 'result': {'token': 'Ohv3IrcV0CJFa ... etc ... de2PvYam0zqT1G8fEA==',
  'expires': '120',
  'display_name': 'pmxep',
  'participant_uuid': '4cb84ae2-3359-4aa6-9e16-b6fa43f8af3a',
  'current_service_type': 'conference',
  'role': 'HOST',
  'call_tag': '',
  'version': {'version_id': '29', 'pseudo_version': '68488.0.0'},
  'conference_name': 'Alice's VMR',
  'chat_enabled': True,
  'fecc_enabled': True,
  'rtmp_enabled': True,
  'analytics_enabled': True,
  'service_type': 'conference',
  'call_type': 'video',
  'guests_can_present': True,
  'vp9_enabled': False,
  'allow_1080p': True,
  'direct_media': False,
  'use_relay_candidates_only': False,
  'turn': [{'urls': ['turn:176.125.235.148:3478?transport=udp'],
    'username': '1660056163:abcdefgh-3359-4aa6-9e16-b6fa43f8af3a',
    'credential': '0BKT1abcdefghvpYMroo8OO8+g='}]
}}

This result contains the token (abridged in the above example) to use to authenticate all future requests, and an expiry time (in seconds) after which this token becomes invalid. The full list of fields in the result is as follows:

PIN protected conferences

If the conference is PIN-protected, the PIN must be specified in a "pin" HTTP header. If the PIN is required but is incorrect or missing, a "403 Forbidden" error is returned. The "pin" field in the response specifies whether a PIN is required for Hosts, and a "guest_pin" field in the response specifies whether a PIN is required for Guests. If a PIN is required for a Host, but not for a Guest, and if you want to join as a Guest, you must still provide a "pin" header, with a value of "none".

SSO protected conferences

If the conference has SSO (Single Sign-On) participant authentication enabled, the response contains a list of Identity Providers (IdPs) that are available for this service, for example:

"idp": [
  {
    "name": "Microsoft Entra ID”,
    "img": "",
    "uuid": "4fe19459-67b4-4e84-abb4-a3765a0a7e09”
  }, {
    "name": "ADFS”,
    "img": "",
    "uuid": "7e43610f-1c82-4726-899a-af801748846c”
  }
]

When using IdP authentication, the next request_token request should contain the chosen_idp, for example:

"chosen_idp":"4fe19459-67b4-4e84-abb4-a3765a0a7e09”,

And the response will contain a URL to redirect to:

"redirect_url": "<IdP's SSO URL>?SAMLRequest=<Base64 encoded SAML AuthNRequest message>”,
"redirect_idp": {
  "name": "Microsoft Entra ID”,
  "uuid": "4fe19459-67b4-4e84-abb4-a3765a0a7e09”
}

Having followed the redirect to the Identity Provider and completed the necessary authentication you will be redirected back to the Infinity API with a SAML Assertion / OpenID Connect JWT for Pexip Infinity to verify. If verification succeeds a token will be received that must be sent in a new request_token call as the sso_token parameter.

Virtual Receptions

If the conference is a Virtual Reception, a "403 Forbidden" error is returned, with a "conference_extension" field. This field is either:

• "standard": for a regular, Microsoft Teams or Google Meet Virtual Reception.
• "mssip": for a Lync / Skype for Business Virtual Reception.

To join the target room, a second request_token request must be made, but with a conference_extension field in the request JSON, which contains the alias of the target conference.

{"status": "success", "result": 
{"token": "SE9TVAltZ...etc...jQ4YTVmMzM3MDMwNDFlNjI%3D", 
"expires": "120"}}

Conference control functions

This section describes in detail the requests that may be used to manage an existing conference.

These REST URIs take the format:

https://<node_address>/api/client/v2/conferences/<conference_alias>/<request>

{"role": "GUEST", "destination": "bob@example.com", "protocol": "sip", "source_display_name": "Alice"}

{"status": "success", "result": ["977fcd1c-8e3c-4dcf-af45-e536b77af088"]}

{"status": "success", "result": {"locked": false, "guests_muted": false, "all_muted": false, "presentation_allowed": true, "started": true, "live_captions_available": true, "direct_media": false, "classification": {"levels": {},"current": null}, "message_text": null, "pinning_config": "basic_backfill", "breakout_rooms": true, "breakout_name": "My Breakout Room", "breakout_description": "Quick discussion about XYZ", "end_action": "transfer", "end_time": 1688688005, "breakout_guests_allowed_to_leave": false}}

{"setting": true}

{"type": "text/plain", "payload": "Hello World"}

participants

This GET request returns the full participant list of the conference. See the description of the participant_create EventSource for more information.

transform_layout

This POST request changes the conference layout, controls streaming content, and enables/disables indicators and overlay text.

Request fields:

Response: the result is true if successful, false otherwise.

Here are some example requests:

• To change a Virtual Meeting Room layout: {"transforms": {"layout": "2:21"}}
• To change a Virtual Auditorium layout: {"transforms": {"guest_layout": "2:21", "host_layout": "4:0"}}
• To enable streaming and recording indicators: {"transforms": {"streaming_indicator": true, "recording_indicator": true}}
• To enable overlay text: {"transforms": {"enable_overlay_text": true}}
• To set Adaptive Composition layout with active speaker indication only: {"transforms": {"layout": "ac","enable_overlay_text": false,"enable_active_speaker_indication": true}}
• To set Adaptive Composition layout with active speaker indication and to also display all other participant names: {"transforms": {"layout": "ac","enable_overlay_text": true,"enable_active_speaker_indication": true}}
• To set custom overlay text for a 4:0 layout: {"transforms": {"layout": "4:0", "free_form_overlay_text": ["Top left", "top right", "bottom left", "bottom right"]}}
• To set 2:21 layout for normal participants, and 1:0 for streaming participants: {"transforms": {"layout": "2:21", "streaming": {"layout": "1:0"}}}
• To enable the holding screen for streaming participants: {"transforms": {"streaming": {"waiting_screen_enabled": true}}}

clearallbuzz

This POST request lowers all raised hands.

Request: empty.

Response: the result is true if successful, false otherwise.

clearspotlights

This POST request disables spotlighting on all participants.

Request: empty.

Response: the result is true if successful, false otherwise.

silent_video_detection

This POST request configures the parameters for silent video detection in an Adaptive Composition layout.

Request fields:

Request example:

{"config": {"enable": true,"silent_after": 15,"require_no_faces": true,"reactivate_after": 2}}

Response: the result is true if successful, false otherwise.

set_classification_level

This POST request sets the classification level to use from the theme assigned to the conference.

Request example:

{"level": 4}

Request fields:

Response: the result is true if successful, false otherwise.

get_classification_level

This GET request obtains the set of available classification levels and the currently active level. For example:

{
    "status": "success",
    "result": {
        "levels": {
            "0": "Unclassified",
            "1": "Official",
            "2": "Official Sensitive",
            "3": "RESTRICTED",
            "4": "Confidential",
            "5": "Secret",
            "6": "Top Secret"
        },
        "current": 1
    }
}

theme

Provides the theme resources of the conference (direct media only). Used in conjunction with the splash_screen server event, the relevant theme resources can be used to locally render a particular splash screen on the client.

The theme metadata for a given conference is requested with a GET request to /theme

Example response:

{
  "status": "success",
  "result": {
    "direct_media_welcome": {
    "layout_type": "direct_media",
    "background": {
    "path": "background.jpg"
  	 },
  	 "elements": [
    {
    "type": "text",
    "color": 4294967295,
    "text": "Welcome"
    }
  	]
	},
    …
  }
}

To fetch a particular resource such as an image. A GET request is made to /theme/<resource path>

Example request:

GET /api/client/v2/conferences/<conference_alias>/theme/background.jpg

See Rules and requirements for customized themes for more information about custom themes.

available_layouts

This returns a list of all available layouts for the given conference. This includes the inbuilt layouts plus any custom layouts available on this conference.

Example request:

GET /api/client/v2/conferences/<conference_alias>/available_layouts

An example response to the default theme is:

{
    "status": "success",
    "result": [
   	 "5:7",
   	 "1:7",
   	 "2:21",
   	 "1:21",
   	 "4:0",
   	 "9:0",
   	 "16:0",
   	 "25:0",
   	 "1:0",
   	 "1:33",
   	 "teams",
   	 "one_main_twelve_around",
   	 "two_mains_eight_around"
    ]
}

You can obtain richer information if you add ?annotate=true to the end of the URI. You can also filter the available layouts list based on the dtmf_allowed_layouts list in themeconfig.json.

Example annotated response:

{
    "status": "success",
    "result": [
        {
            "name": "2x2",
            "tags": [
                "equal",
                "has-native-multiscreen"
            ]
        },
        {
            "name": "1:7",
            "tags": [
                "speaker-focus",
                "has-native-multiscreen"
            ]
        },
		...

layout_svgs

This provides a list of SVG string representations of the layouts that are active on the given conference.

Example request:

GET: https://{worker}/api/client/v2/conferences/{conference_alias}/layout_svgs

An example response (only the 1:7 layout is shown here) could contain:

{
	"status": "success",
	"result": {
		"1:7": "<svg width='140' height='88' viewBox='0 0 140 88' fill='none' xmlns='http://www.w3.org/2000/svg'>\n<rect x='0.5' y='0.5' width='139' height='87' rx='3.5' fill='currentColor' stroke='#BBBFC3'></rect>\n<rect x='33' y='12.1044' width='74' height='45.3913' rx='2' fill='#BBBFC3'></rect>\n<rect x='4' y='66' width='18' height='14' rx='2' fill='#BBBFC3'></rect>\n<rect x='23' y='66' width='18' height='14' rx='2' fill='#BBBFC3'></rect>\n<rect x='42' y='66' width='18' height='14' rx='2' fill='#BBBFC3'></rect>\n<rect x='61' y='66' width='18' height='14' rx='2' fill='#BBBFC3'></rect>\n<rect x='80' y='66' width='18' height='14' rx='2' fill='#BBBFC3'></rect>\n<rect x='99' y='66' width='18' height='14' rx='2' fill='#BBBFC3'></rect>\n<rect x='118' y='66' width='18' height='14' rx='2' fill='#BBBFC3'></rect></svg>"
  }
}

breakouts

Creates a breakout room, and optionally transfers participants into that room.

Example request:

POST /api/client/v2/conferences/<conference_alias>/breakouts

Request fields:

Response example:

{
    "breakout_uuid": "00000000-0000-0000-0000-000000000001"
}

The response contains the uuid of the new breakout room.

set_message_text

Sets the conference message banner text.

There is one request field:

Request example:

{"text": "Hello World!"}

get_message_text

This retrieves the current conference message banner text.

It returns:

{ "text": "Message that was set", "set_time" "UTC+00:00 - time" }

set_pinning_config

Sets the pinning configuration for the conference.

There is one request field:

Request example:

{"pinning_config": "basic_backfill"}

get_pinning_config

Retrieves the pinning configuration for the conference.

Response example:

"result": {"pinning_config": "basic_backfill"}

Participant functions

Within a conference, operations can be performed on participants, if the client has Host privileges.

These participant REST URIs take the format:

https://<node_address>/api/client/v2/conferences/<conference_alias>/participants/<participant_uuid>/<request>

where <node_address> is the Conferencing Node, <conference_alias> is an alias of the conference, and <participant_uuid> is the uuid of the participant you are controlling. Under this path comes the request, for example:

https://10.0.0.1/api/client/v2/conferences/meet_alice/participants/7f8bdd7f-2d39-4c3f-9236-3e95b21f21a8/disconnect

{"digits": "1234"}

{"type": "text/plain", "payload": "Hello World"}

calls

This POST request upgrades this connection to have an audio/video/presentation call element.

Pexip expects the call to contain three media sections for three streams: audio, video, and presentation. The presentation section should contain an additional attribute "a=content:slides", to indicate this is the presentation stream.

Request example:

{"call_type": "WEBRTC", "sdp": "..."}

Request fields:

Response example:

{"status": "success", "result": {
"call_uuid": "50ed679d-c622-4c0e-b251-e217f2aa030b",
"sdp": "..."}}

The response contains the SDP of the Pexip node, and a call_uuid. This call_uuid is used to control the call. The ack function must be called on this call_uuid in order to start media after the SDP has been exchanged and ICE has been completed.

The response may also contain a "turn" array of additional TURN servers to use, if the Enable media relay on TCP port 443 feature is enabled. A client wanting to use this would need to trigger an ICE restart and send an update message to update the SDP.

{'status': 'success', 'result': null}

{"text": "The Dude"}

{"state": true}

{"role": "chair"}

{"action": "start", "movement": [{"axis": "pan", "direction": "left"}, {"axis": "zoom", "direction": "in"}], "timeout": 1000};

{"role": "guest", "conference_alias": "meet@example.com", "pin": “1234"}

avatar.jpg

This GET request obtains the image to display to represent a conference participant or directory contact.

statistics

Report participant media statistics to Pexip Infinity (direct media only). The client should notify at the period specified by the client_stats_update_interval in the request_token response.

Example request:

{
  "audio": {
    "rx_bitrate": 64.4,
    "rx_codec": "opus",
    "rx_jitter": 2,
    "rx_packets_lost": 0,
    "rx_packets_received": 914,
    "tx_bitrate": 63.728,
    "tx_codec": "opus",
    "tx_packets_sent": 914,
    "tx_rb_jitter": 2,
    "tx_rb_packetslost": 0
  },
  "video": {
    "rx_bitrate": 2215.744,
    "rx_codec": "VP8",
    "rx_fps": 21,
    "rx_packets_lost": 0,
    "rx_packets_received": 4206,
    "rx_resolution": "1280x720",
    "tx_bitrate": 2089.296,
    "tx_codec": "VP8",
    "tx_packets_sent": 3633,
    "tx_rb_packetslost": 0,
    "tx_resolution": "1280x720"
  },
  "presentation": {
    "rx_packets_lost": 0,
    "rx_packets_received": 0,
    "tx_bitrate": 989.304,
    "tx_codec": "VP8",
    "tx_packets_sent": 1714,
    "tx_rb_packetslost": 0,
	"tx_resolution": "1792x1120"
  }
}

layout_group

Assigns a participant to a layout group.

Request fields:

Response: the result is true if successful, false otherwise.

Ducking functions

The following requests (send_to_audio_mixes, receive_from_audio_mix) relate to ducking functions. Ducking reduces the volume of certain participants when another participant is speaking. If a participant is set to prominent, the audio of all non-prominent participants will be ducked when the prominent participant is speaking.

send_to_audio_mixes

POST request. The audio mixes this participant is sending to.

	{
	  "mixes": [
	    {
 	     "mix_name": "main",
 	     "prominent": true|false
	    },
	  ...
 	 ]
	}

Each mix is given a mix_name. Each call overwrites the current list of mixes with the given list. For example, send_to_audio_mixes([A]) followed by send_to_audio_mixes([B]) will mean that the participant is sending to B only. To send to A and B, call send_to_audio_mixes([A,B]). Similarly, to remove a mix, send_to_audio_mixes([A,B,C]) followed by send_to_audio_mixes([A,C]) will remove B from the sending list. Calling with mixes as an empty list will reset the participant to sending to main only.

receive_from_audio_mix

POST request. The audio mix this participant is receiving e.g. "main".

	{
      "mix_name": "main"
	}

This participant will hear audio from the mix called main. Even if no senders are present, requesting to receive from a mix_name will create that mix.

mix_name can also be set to None which results in the participant receiving no audio.

Mix descriptions

main is a pre-defined mix name which all participants are configured to send and receive from by default prior to any API or policy overrides. Mixes can be hierarchical with a mix configured to inherit the participants from a parent mix, this can be specified by using dots in the mix name with parent mix names coming first in the name.

For example, main.french is a valid mix name which would create a new mix which inherits from main. This means that anyone receiving audio from main.french would hear anyone sending to main and also anyone sending to main.french. They would not hear participants sending to a mix called french as that is a different mix name. To receive from that mix you would call receive_from_audio_mix with mix name french.

The number of inherited mixes is limited to 3, so a mix name with more than three dots in it will only use the first three as delimiters. A mix name with no characters in between the dots will be marked as invalid in the API response. If main is specified in the mix name, then it must be the first word before the first dot. main does not have to be the root of the mix name and up to three hierarchies are supported. Some examples of valid mix names are:

Breakout rooms functions

These breakout room REST URIs typically take the format:

https://<node_address>/api/client/v2/conferences/<conference_alias>/breakouts/<breakout_uuid>/<request>

Breakout room controls

Each breakout room can be controlled by hosts like a normal VMR e.g. to mute all guests, transform_layout etc.

For example:

POST /api/client/v2/conferences/meet.alice/breakouts/00000000-0000-0000-0000-000000000001/transform_layout

POST /api/client/v2/conferences/meet.alice/breakouts/00000000-0000-0000-0000-000000000001/muteguests

POST /api/client/v2/conferences/meet.alice/breakouts/00000000-0000-0000-0000-000000000001/set_classification_level

Closing a breakout room

To disconnect/close a breakout room:

POST /api/client/v2/conferences/<conference_alias>/breakouts/<breakout_uuid>/disconnect

Depending on the end_action specified on creation, participants will be transferred back to the main room or disconnected.

Emptying all breakout rooms

To empty all breakout rooms:

POST /api/client/v2/conferences/<conference_alias>/breakouts/empty

This moves all participants in all rooms back to the main room, and leaves the rooms open (i.e. it leaves the Host API control participants present).

Ask for help / dismiss help request

The breakoutbuzz POST request requests help for the breakout room:

POST /api/client/v2/conferences/<conference_alias>/breakoutbuzz

The resulting conference_update event contains a breakoutbuzz field with a value (true/false) and a time which shows when it was set.

Anyone in the breakout room, or a Host, can use the clearbreakoutbuzz POST request to cancel the request for help:

POST /api/client/v2/conferences/<conference_alias>/clearbreakoutbuzz

or

POST /api/client/v2/conferences/<conference_alias>/breakouts/<breakout_uuid>/clearbreakoutbuzz

Transfer participants back to the main room

To transfer participants from a breakout room back to the main room:

POST /api/client/v2/conferences/<conference_alias>/breakouts/<breakout_uuid>/participants/breakout

For example:

POST /api/client/v2/conferences/meet.alice/breakouts/00000000-0000-0000-0000-000000000001/participants/breakout
{
    "breakout_uuid": "main",
    "participants": ["uuid1", "uuid2", "uuid3"]
}

where uuid1, uuid2, uuid3 are valid participant uuids in breakout room 00000000-0000-0000-0000-000000000001.

• If the participants list is empty then all participants are moved.
• You can transfer between breakout rooms by specifying the breakout room uuid instead of "main" in the above request.

• You can transfer participants back to their previous room by specifying a breakout room uuid of "previous". For example:

  {
      "breakout_uuid": "previous",
      "participants": []
  }

  would move all participants back to their previous rooms.

  (If a participant does not have a previous room, then the transfer will just fail.)

Move participant back to the main room

If guests are allowed to leave the breakout room, a participant can use leavebreakout to transfer back to the main room:

POST /api/client/v2/conferences/<conference_alias>/leavebreakout

Other participant actions

You can also perform actions on specific participants in the breakout room, for example:

POST /api/client/v2/conferences/meet.alice/breakouts/<breakout_uuid>/participants/<participant_uuid>/mute

POST /api/client/v2/conferences/meet.alice/breakouts/<breakout_uuid>/participants/<participant_uuid>/overlaytext

Note that disconnecting a participant from a breakout room will disconnect them entirely and not move them back to the main room.

Call functions

Using the call_uuid, further operations can be undertaken on the calls as part of the nominated participant.

These call REST URIs take the format:

https://<node_address>/api/client/v2/conferences/<conference_alias>/participants/<participant_uuid>/calls/<call_uuid>/<request>

where <node_address> is the Conferencing Node, <conference_alias> is an alias of the conference, <participant_uuid> is the uuid of the participant, and <call_uuid> is the uuid of the call you are controlling. Under this path comes the request, for example:

https://10.0.0.1/api/client/v2/conferences/meet_alice/participants/7f8bdd7f-2d39-4c3f-9236-3e95b21f21a8/calls/c34f35f-1060-438c-9e87-6c2dffbc9980/disconnect

{"digits": "1234"}

{"candidate": "candidate:1732786348 1 udp 2124262783 2a02:c7f:615…eration 0 ufrag YAeD network-id 2 network-cost 10", "mid": "0", "ufrag": "YAeD", "pwd": "IfZniTlYHipJXEg4quoI00ek"}

{"sdp": "..."}

{"status": "success", "result": "..."}

{"action": "start", "movement": [{"axis": "pan", "direction": "left"}, {"axis": "zoom", "direction": "in"}], "timeout": 1000};

Server-sent events

Clients can subscribe to an HTTP EventSource which feeds events from the conference as they occur.

To subscribe, open an HTTP connection to:

https://<node_address>/api/client/v2/conferences/<conference_alias>/events?token=<token_id>

where <node_address> is the Conferencing Node, <conference_alias> is an alias of the conference, and <token_id> is the session token, for example:

https://10.0.0.1/api/client/v2/conferences/meet_alice/events?token=123456

This allows the token to be specified on the URI, since custom headers cannot be added to Event Sources in browsers today. However, if headers can be added this will be accepted too, and the query parameter will not be required.

Each event contains an event name, and some events may contain a payload of data, which is a JSON object.

{"presenter_name": "Bob", "presenter_uri": "bob@example.com", "source": "video"}

{
"buzz_time": 0,
"call_direction": "in",
"call_tag": "def456",
"disconnect_supported": "YES",
"display_name": "Alice",
"encryption": "On",
"external_node_uuid": "",
"fecc_supported": "NO",
"has_media": false,
"is_audio_only_call": "NO",
"is_client_muted": false,
"is_external": false,
"is_idp_authenticated": false,
"is_conjoined": false,
"is_muted": "NO",
"is_presenting": "NO",
"is_streaming_conference": false,
"is_video_call": "YES",
"is_video_muted": false,
"layout_group": "",
"local_alias": "meet.alice",
"mute_supported": "YES",
"needs_presentation_in_mix": true,
"overlay_text": "Alice",
"presentation_supported": "NO",
"protocol": "api",
"receive_from_audio_mix": "main",
"role": "chair",
"rx_presentation_policy": "ALLOW",
"send_to_audio_mixes": [{"mix_name": "main", "prominent": false}],
"service_type": "conference",
"show_live_captions": false,
"spotlight": 0,
"start_time": 1441720992,
"transfer_supported": "YES",
"uri": "Infinity_Connect_10.44.21.35",
"uuid": "50b956c8-9a63-4711-8630-3810f8666b04",
"vendor": "Pexip Infinity Connect/2.0.0-25227.0.0 (Windows NT 6.1; WOW64) nwjs/0.12.2 Chrome/41.0.2272.76"
}

{"uuid": "65b4af2f-657a-4081-98a8-b17667628ce3"}

{"locked": false, "guests_muted": false, "all_muted": false, "presentation_allowed": true, "started": true, "live_captions_available": true, "direct_media": false, "classification": {"levels": {},"current": null}, "message_text": null, "pinning_config": "basic_backfill", "breakout_rooms": true, "breakout_name": "My Breakout Room", "breakout_description": "Quick discussion about XYZ", "end_action": "transfer", "end_time": 1688688005, "breakout_guests_allowed_to_leave": false}

{"view": "1:7",
"participants": ["a0196175-b462-48a1-b95c-f322c3af57c1", "65b4af2f-657a-4081-98a8-b17667628ce3”], "requested_layout": {"primary_screen": {"chair_layout": "2:21", "guest_layout": "2x2"}}, "overlay_text_enabled": false}

{"data": "hi my name is ", "is_final": false}

{"data": "Hi my name is Alice", "is_final": true}

{"origin": "Alice",
"uuid": "eca55900-274d-498c-beba-2169aad9ce1f",
"type": "text/plain",
"direct": false,
"payload": "Hello World"}

[
{"stage_index": 0, 
"participant_uuid": "a0196175-b462-48a1-b95c-f322c3af57c1", 
"vad": 0}, 
{"stage_index": 1, 
"participant_uuid": "65b4af2f-657a-4081-98a8-b17667628ce3", 
"vad": 0}
]

{"call_uuid": "50ed679d-c622-4c0e-b251-e217f2aa030b", 
"reason": "API initiated participant disconnect"}

{"reason": "API initiated participant disconnect"}

splash_screen

The client should display a splash screen. For VMRs with direct media enabled, it is the clients’ responsibility to render local screens. The screen_key uniquely identifies the type of screen the client should display. On receiving the event with no data, the splash screen should be cleared.

Optionally the client can implement these local splash screens by fetching the theme resources from Pexip Infinity. See theme for more information.

Example data:

{"screen_key": "direct_media_welcome"} | None

The screen keys may be direct_media_welcome, direct_media_waiting_for_host, direct_media_other_participants_audio_only, direct_media_escalate, or direct_media_deescalate.

new_offer

Received a SDP offer from the far-end participant (direct media only). The far-end has sent an updated SDP via /calls for the client to consider. The /ack function must be called in order to start media after the SDP has been exchanged and ICE has been completed.

Example data:

{"sdp": "..."}

update_sdp

Received a SDP update from the far-end participant (direct media only). The far-end has sent an updated SDP via /update for the client to consider. Typically received for purposes of an ICE restart.

Example data:

{"sdp": "..."}

new_candidate

Received a new ICE candidate from the far-end participant (direct media only). The far-end has sent a new ICE candidate if doing trickle ICE via /new_candidate for the client to consider.

Example data:

{"candidate": "candidate:1732786348 1 udp 2124262783 2a02:c7f:615…eration 0 ufrag YAeD network-id 2 network-cost 10", "mid": "0", "ufrag": "YAeD", "pwd": "IfZniTlYHipJXEg4quoI00ek"}

peer_disconnect

Indicates that the far-end participant has disconnected (direct media only).

Example data: None

refer

The client should connect to a different conference (alias).

Example data:

{"alias": "meet.bob", "breakout_name": "Room 1"}

breakout_begin

Hosts (including the creator) receive a breakout_begin event which contains information about a new breakout room, plus the participant uuid that they have been allocated inside the breakout as a control participant.

Example data:

{"breakout_uuid": "00000000-0000-0000-0000-000000000001", "participant_uuid": "participantxyz"}

Hosts (including the creator) will now receive breakout events on the main room EventSource.

breakout_event

Hosts (including the creator) receive breakout events on the main room EventSource. These are normal events that are occurring within the breakout VMR — so you can build a roster list, see the state of the conference etc.

Example data:

{"breakout_uuid": "00000000-0000-0000-0000-000000000001", "event": "participant_sync_begin", "data": null}

{"breakout_uuid": "00000000-0000-0000-0000-000000000001", "event": "participant_create", "data": {"uuid": "1234", "uri": "user@domain.com", ...}

breakout_end

Hosts receive a breakout_end event to tell them when a breakout room is no longer available.

Example data:

{" breakout_uuid": "00000000-0000-0000-0000-000000000001", "participant_uuid": "participantxyz" }

where the participant_uuid represents that host's participant in the breakout room.

breakout_refer

Sent when a participant specified in the participant lists is currently a host (and hence has an API participant in the breakout). This tells them to move their media to the breakout room specified by the uuid in the event.

Example data:

{"breakout_uuid": "main"}

{"breakout_uuid": "00000000-0000-0000-0000-000000000001", "breakout_name": "Room 2"}

Other miscellaneous requests

Conferencing Node status (maintenance mode)

Load balancers can use the https://<node_address>/api/client/v2/status REST API command to check whether a Conferencing Node is in maintenance mode, for example:

https://10.0.0.1/api/client/v2/status

If the node is not in maintenance mode, it returns a 200 OK with the following JSON:

{
  "status": "success",
  "result": "OK"
}

If the node is in maintenance mode, it returns a 503 with the following JSON:

{
  "status": "failed",
  "result": "Maintenance mode"
}

Changelog

Changes in version 36:

• New conference control function set_guests_can_unmute, and participant functions client_mute and client_unmute, for showing whether a participant's local microphone is muted. This sets the is_client_muted property in the participant list.
• New conference control function clearspotlights that disables spotlighting on all participants.
• New last_spoken_time parameter in the participant list / roster object.

Changes in version 35:

• New set_message_text and get_message_text conference control functions for message overlay.
• New set_pinning_config and get_pinning_config conference control functions, and layout_group participant function for participant pinning.
• New send_to_audio_mixes and receive_from_audio_mix participant functions for ducking.
• The ac_presentation_in_mix parameter in the streaming section of transform_layout has been renamed as presentation_in_mix. Note that ac_presentation_in_mix still works but is now deprecated.

Changes in version 34:

• New layout_svgs conference control function.
• New breakouts functions: breakoutbuzz, clearbreakoutbuzz and leavebreakout.

Changes in version 33:

• New available_layouts conference control function.
• New preferred_aspect_ratio participant function.

• New functions and events to support breakout rooms:

  • New breakouts conference control function.
  • New server events: breakout_begin, breakout_event, breakout_end and breakout_refer.
  • New breakout room related parameters in conference_status function and conference_update event.

More information

For more information about using this API, contact your Pexip authorized support representative.