Pexip client REST API v2

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

These REST URIs take the format:

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

Conference control functions

These REST URIs take the format:

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

Participant functions

These participant REST URIs take the format:

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

Call functions

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

To subscribe, open an HTTP connection to:

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

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

Request fields:

Response example:

{"status": "success", "result": 
{"token": "SE9TVAltZ...etc...zNiZjlmNjFhMTlmMTJiYTE%3D", 
"expires": "120", 
"participant_uuid": "2c34f35f-1060-438c-9e87-6c2dffbc9980",
"display_name": "Alice", 
"stun": [{"url": "stun:stun.l.google.com:19302"}], 
"analytics_enabled": true, 
"version": {"pseudo_version": "25010.0.0", "version_id": "10"},
"role": "HOST", 
"service_type": "conference", 
"chat_enabled": true, 
"current_service_type": "conference"}}

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.

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 standard Virtual Reception, or "mssip" for a Virtual Reception towards Microsoft Lync / Skype for Business conferences. 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": 
{"guests_muted": false, "locked": false}}

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

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

calls

This POST request upgrades this connection to have an audio/video call element. There are two variants of this request, depending upon whether a WebRTC or RTMP call is to be established.

WebRTC

Request example to add a WebRTC element:

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

Request fields:

Response example (WebRTC):

{"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.

RTMP

Request example to add an RTMP element:

{"call_type": "RTMP"}

Request fields:

Response example (RTMP):

{"status": "success", "result": {
"call_uuid": "50ed679d-c622-4c0e-b251-e217f2aa030b", 
"url": "rtmp://10.0.0.1:40002/pexip/50ed679d-c622-4c0e-b251-e217f2aa030b", 
"secure_url": "rtmps://hostname.domain:40003/pexip/50ed679d-c622-4c0e-b251-e217f2aa030b"}}

The response contains RTMP URLs that can be connected to by the client – both an insecure (rtmp://) and secure (rtmps://) variant. The RTMPS URL is only returned if a SIP TLS FQDN is configured for the Conferencing Node, and requires a valid TLS certificate to be installed on the Conferencing Node.

{"role": "chair"}

{"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.

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

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

{"api_url": "/participants/50b956c8-9a63-4711-8630-3810f8666b04"
"call_direction": "in"
"display_name": "Alice"
"encryption": "On"
"has_media": false
"is_audio_only_call": "NO"
"is_external": false
"is_muted": "NO"
"is_presenting": "NO"
"is_streaming_conference": false
"is_video_call": "YES"
"local_alias": "meet.alice"
"overlay_text": "Alice"
"presentation_supported": "NO"
"protocol": "api"
"role": "chair"
"rx_presentation_policy": "ALLOW"
"service_type": "conference"
"spotlight": 0
"start_time": 1441720992
"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}

{"view": "1:7",
"participants": ["a0196175-b462-48a1-b95c-f322c3af57c1", "65b4af2f-657a-4081-98a8-b17667628ce3”]}

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

[
{"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"}

Changelog

Changes in version 14:

• New service_type of “test_call”.
• The dial command has a new text parameter.
• New avatar.jpg participant GET request.

Changes in version 13:

None.

Changes in version 12:

• New start_conference conference control function that allows you to start a conference and allow Guests in the "waiting room" into the meeting.
• New transfer participant function.
• The dial command has two new parameters: keep_conference_alive and remote_display_name; the protocol parameter can be "auto".

Changes in version 11:

• New role participant function.
• New layout event.
• The dial command has new dtmf_sequence, source_display_name, source and call_type fields.
• The participant_create event has new is_audio_only_call, is_external and is_video_call parameters.

Changes in version 10:

• WebRTC and Lync / Skype for Business multiple participant records for the same participant are no longer seen; you now receive a single record per participant, so there is longer a participant_id value.
• DTMF tones can be sent to a specific participant.
• The request_token can be used to access a Pexip Virtual Reception.
• The dial out command now returns an array of UUIDs.
• The dial out command includes a streaming participant indicator.

More information

Questions about this API should be directed to your Pexip authorized support representative.