Policy server responses
The external policy server response to a request should be a 200 OK message. The response header must include the Content-Type, and the message body must include the requested content.
The policy server can return an error code e.g. 404 if it wants Pexip Infinity to fall back to its own default behavior for a specific request.
The following table summarizes the response expected for each request type. Further details are explained below.
Policy request type | Response |
---|---|
Service configuration | JSON dictionary of key value pairs that contains the service configuration data. |
Media location | JSON dictionary of key value pairs that contains the primary location and optional overflow location data. |
Participant avatar | JPEG file of the requested size. |
Service configuration response
The response for a service configuration request must return a Content-Type of application/json where the message body is a JSON dictionary of key value pairs as follows:
{ "status" : "success", "action" : "reject|continue" "result" : { <service_configuration_data> }, "<other_keys>" : "<other_values>" }
where:
- if "status" is anything other than "success", the response is deemed to have failed and Pexip Infinity will do as specified in the "action" field.
-
"action" is an optional value to include in the response. When present, it instructs Pexip Infinity how to proceed in failure scenarios.
The "action" field is ignored if "status" is "success" and "result" contains valid service configuration data (and it is a 200 OK message). In all other cases:
- "reject" instructs Pexip Infinity to reject the call immediately (i.e. return "conference not found")
-
"continue" instructs Pexip Infinity to fall back to its default behavior (which is to attempt to retrieve the service configuration data from its own internal database)
For any other value of "action" (or if no "action" is specified), Pexip Infinity will also fall back to its default behavior.
- "result" contains the service configuration data object as described below.
- "<other_keys>" and "<other_values>" can be zero, one or more optional key value pairs. If included, they do not affect how Pexip Infinity processes the response but they will be included in any relevant log messages. They could, for example, indicate the version number of the software running on the policy server, or contain "reason" information for failure responses.
See the response examples for more information on formatting the message body.
Service configuration data
The "result" in a service configuration response contains a service configuration data object. This is a JSON object containing multiple key value pairs that describe the service.
Some data fields are required, and some are optional. The fields expected by Pexip Infinity in the response depend upon the returned service_type — either "conference" or "lecture" for a Virtual Meeting Room or Virtual Auditorium, "gateway" for a Pexip Distributed Gateway call or "two_stage_dialing" for a Virtual Reception. The fields in the JSON object can be supplied in any order.
Virtual Meeting Room / Virtual Auditorium service types response fields
Pexip Infinity expects the following fields to be returned for a service_type of "conference" (VMR) or "lecture" (Virtual Auditorium):
Field name | Required | Type | Description |
---|---|---|---|
service_type | Yes | String |
The type of service, in this case:
|
name | Yes | String |
The name of the service. The policy server will typically determine the service name according to the local_alias received in the configuration request. Pexip Infinity will subsequently use this name — as the service_name parameter — in subsequent requests. |
description | No | String |
A description of the service. |
service_tag | Yes | String |
A unique identifier used to track usage of this service. |
pin | No | String |
Host PIN — the secure access code for Host participants. |
allow_guests | No | Boolean |
Whether to distinguish between Host and guest participants:
Default: false |
guest_pin | No | String |
Guest PIN — the secure access code for Guest participants. |
max_callrate_in | No | Integer |
The maximum media bandwidth in bps that Pexip Infinity will receive from each individual participant dialed in to the service. Range 384000 to 4096000 bps. |
max_callrate_out | No | Integer |
The maximum media bandwidth in bps that Pexip Infinity will send to each individual participant dialed in to the service. Range 384000 to 4096000 bps. |
participant_limit | No | Integer |
The maximum number of participants allowed to join the service. |
ivr_theme_name | No | String |
The name of the theme to use with the service. If no theme is specified, the default Pexip theme is used. |
automatic_participants | No | List |
A list of participants to dial automatically when the conference starts. Each participant in the list contains a number of fields as described in Automatically dialed participants (ADP) fields. |
view (applies to service_type of "conference" only) |
No | String |
The layout seen by all participants:
Default: "one_main_seven_pips" |
host_view (applies to service_type of "lecture" only) |
No | String |
The layout seen by Hosts:
Default: "one_main_seven_pips" |
guest_view (applies to service_type of "lecture" only) |
No | String |
The layout seen by Guests:
Default: "one_main_seven_pips" Only Hosts are displayed. Guests can hear but not see any of the other Guests. |
locked | No | Boolean |
Whether to lock the conference on creation:
Note that this field has no effect on the conference if it is already running. Default: false |
call_type | No | String |
The call capability of the conference. It can be limited to:
Default: "video" |
force_presenter_into_main (applies to service_type of "lecture" only) |
No | Boolean |
Controls whether the Host who is presenting is locked into the main video position:
Default: false |
mute_all_guests (applies to service_type of "lecture" only) |
No | Boolean |
Controls whether to mute guests when they first join the conference:
Default: false |
Pexip Distributed Gateway service type response fields
Pexip Infinity expects the following fields to be returned for a service_type of "gateway":
Field name | Required | Type | Description |
---|---|---|---|
service_type | Yes | String |
The type of service, in this case:
|
name | Yes | String |
The name of the service. The policy server will typically determine the service name according to the local_alias received in the configuration request. Pexip Infinity will subsequently use this name — as the service_name parameter — in subsequent requests. |
description | No | String |
A description of the service. |
service_tag | Yes | String |
A unique identifier used to track usage of this service. |
max_callrate_in | No | Integer |
The maximum media bandwidth in bps that Pexip Infinity will receive from each individual participant dialed in to the service. Range 384000 to 4096000 bps. |
max_callrate_out | No | Integer |
The maximum media bandwidth in bps that Pexip Infinity will send to each individual participant dialed in to the service. Range 384000 to 4096000 bps. |
ivr_theme_name | No | String |
The name of the theme to use with the service. If no theme is specified, the default Pexip theme is used. |
remote_alias | Yes | String |
The alias of the endpoint to call. The alias can include scheme information, for example sip:alice@example.com, but the call will always be made using the specified outgoing_protocol. |
local_alias | Yes | String | The calling or "from" alias. This is the alias that the recipient would use to return the call. |
local_display_name | No | String | The display name of the calling alias. |
outgoing_protocol | Yes | String |
The protocol to use to place the outgoing call:
|
outgoing_location_name | No | String | The name* of the location of a Conferencing Node from which to place the call. |
h323_gatekeeper_name | No | String | The name* of the H.323 gatekeeper to use to place the outgoing call. DNS is used if no gatekeeper is specified. |
sip_proxy_name | No | String | The name* of the SIP proxy to use to place the outgoing call. DNS is used if no proxy is specified. |
mssip_proxy_name | No | String | The name* of the Lync / Skype for Business server to use to place the outgoing call. DNS is used if no server is specified. |
turn_server_name | No | String | The name* of the TURN server to offer to external SIP and WebRTC endpoints that are ICE-enabled (such as Lync / Skype for Business clients and Infinity Connect WebRTC clients). |
stun_server_name | No | String | The name* of the STUN server to use when placing calls to external SIP and WebRTC endpoints that are ICE-enabled (such as Lync / Skype for Business clients and Infinity Connect WebRTC clients). |
call_type | No | String |
The call capability of the outbound call:
Default: "video" |
called_device_type | No | String |
The device or system to which to route the call:
Default: "external" |
* The returned "name" must match the name of the location, H.323 gatekeeper, SIP proxy etc configured within Pexip Infinity. |
Virtual Reception service type response fields
Pexip Infinity expects the following fields to be returned for a service_type of "two_stage_dialing" (Virtual Reception):
Field name | Required | Type | Description |
---|---|---|---|
service_type | Yes | String |
The type of service, in this case:
|
name | Yes | String |
The name of the service. The policy server will typically determine the service name according to the local_alias received in the configuration request. Pexip Infinity will subsequently use this name — as the service_name parameter — in subsequent requests. |
description | No | String |
A description of the service. |
service_tag | Yes | String |
A unique identifier used to track usage of this service. |
max_callrate_in | No | Integer |
The maximum media bandwidth in bps that Pexip Infinity will receive from each individual participant dialed in to the service. Range 384000 to 4096000 bps. |
max_callrate_out | No | Integer |
The maximum media bandwidth in bps that Pexip Infinity will send to each individual participant dialed in to the service. Range 384000 to 4096000 bps. |
ivr_theme_name | No | String |
The name of the theme to use with the service. If no theme is specified, the default Pexip theme is used. |
call_type | No | String |
The call capability of the reception. It can be limited to:
Default: "video" |
Automatically dialed participants (ADP) fields
The automatic_participants list field, which may be included in the service configuration response for a service_type of "conference" (VMR) or "lecture" (Virtual Auditorium), contains the following fields per participant:
Field name | Required | Type | Description |
---|---|---|---|
remote_alias | Yes | String | The alias of the endpoint to call. |
local_alias | Yes | String | The calling or "from" alias. This is the alias that the recipient would use to return the call. |
local_display_name | No | String | The display name of the calling or "from" alias. |
description | No | String | The display name of the called participant. This may be used in participant lists and as a text overlay in some layout configurations. |
protocol | Yes | String |
The protocol to use to place the outgoing call:
Calls are routed to externally-located participants based on the configuration of the system location used to place the call. |
role | Yes | String |
The level of privileges the participant has in the conference:
|
dtmf_sequence | No | String | The DTMF sequence to be transmitted after the call to the Automatically Dialed Participant starts. |
system_location_name | No | String | The location of the Conferencing Node from which to place the call. |
streaming | No | Boolean |
Identifies the dialed participant as a streaming or recording device.
Default: false |
keep_conference_alive | No | String |
Specifies whether a Host ADP may or may not keep a conference alive after the last Host disconnects:
Default: "keep_conference_alive_if_multiple" For more information, see Automatically ending a conference. |
call_type | No | String |
The call capability of the participant. It can be limited to:
Default: "video" |
Example service configuration data response
Response containing service configuration data
This is an example of a JSON dictionary of key value pairs that contains service configuration data.
{ "status" : "success", "result" : { "service_type" : "conference", "name" : "Alice Jones", "service_tag" : "abcd1234", "description" : "Alice Jones personal VMR", "pin" : "1234", "allow_guests" : true, "guest_pin" : "5678", "view" : "one_main_zero_pips", "automatic_participants" : [ { "remote_alias" : "sip:alice@example.com", "local_alias" : "meet.alice@example.com", "local_display_name" : "Alice's VMR", "description" : "Dial out to VMR owner", "protocol" : "sip", "role" : "chair", "system_location_name" : "London" } { "remote_alias" : "rtmp://example.com/live/alice_vmr", "local_alias" : "meet.alice@example.com", "local_display_name" : "Alice's VMR", "description" : "Stream the meeting", "protocol" : "rtmp", "role" : "guest", "streaming" : true } ] }, "xyz_version" : "1.2" }
Response instructing Pexip Infinity to reject the call
This is an example response that tells Pexip Infinity to reject a call. This could be sent in a 200 OK message, or in a 404 response.
{ "status" : "success", "action" : "reject" }
Note that Pexip Infinity will also reject the call if "status" is set to a different value (such as "failure") or if "status" is omitted entirely.
Media location response
The response for a media location request must return a Content-Type of application/json where the message body contains a JSON dictionary of key value pairs as follows:
{ "status" : "success", "result" : { <media_location_data> } "<other_keys>" : "<other_values>" }
where:
- if "status" is anything other than "success", the response is deemed to have failed and Pexip Infinity will fall back to its own default behavior for that request.
- "result" contains the media location data as described below.
- "<other_keys>" and "<other_values>" can be zero, one or more optional key value pairs. If included, they do not affect how Pexip Infinity processes the response but they will be included in any relevant log messages. They could, for example, indicate the version number of the software running on the policy server, or contain "reason" information for failure responses.
Media location data
<media location data> is a JSON object containing multiple key values pairs that describe the media location to use. The fields in the JSON object can be supplied in any order.
Field name | Required | Description |
---|---|---|
location | Yes | The name* of the principal location to use for media allocation. A Conferencing Node assigned to that location will handle the media for the participant. |
primary_overflow_location | No | The name* of the system location to handle the media if the principal location has reached its capacity. |
secondary_overflow_location | No | The name* of the system location to handle the media if both the principal location and the primary overflow location have reached their capacity. |
* The returned "name" must match the name of a location configured within Pexip Infinity. If any of the location names included in the response do not match a configured location within Pexip Infinity, the entire response is deemed to have failed and Pexip Infinity will fall back to its own default behavior for that request. |
Example media location data response
This is an example of a JSON dictionary of key value pairs that contains media location data.
{ "status" : "success", "result" : { "location" : "London", "primary_overflow_location" : "Oslo" } }
Avatar responses
The response for an avatar request must return a Content-Type of image/jpeg.
All JPEG images must use the RGB or RGBA color space (CMYK is not supported).
Participant avatar response
The policy server should return a JPEG image of the requested size (width, height).
If a valid JPEG image is not returned or the image is the wrong size, Pexip Infinity will return a 404 Not Found response to the caller (i.e. the Infinity Connect client) which will then use its standard placeholder participant image.