You are here: Integration > External policy > Policy server responses

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	JPG 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 depends upon the service type and are as described below for a Virtual Meeting Room / Virtual Auditorium, Pexip Distributed Gateway call and 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: "conference" — a Virtual Meeting Room, or "lecture" — a Virtual Auditorium
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: true — the conference has two types of participants: Hosts and guests. The pin to be used by Hosts must be specified. A guest_pin can optionally be specified; if a guest_pin is not specified, guests can join without a PIN. false — all participants have Host privileges 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: "one_main_zero_pips" — full-screen main speaker only "one_main_seven_pips" — large main speaker and up to 7 other participants "one_main_twentyone_pips" — small main speaker and up to 21 other participants Default: "one_main_seven_pips"
host_view (applies to service_type of "lecture" only)	No	String	The layout seen by Hosts: "one_main_zero_pips" — full-screen main speaker only "one_main_seven_pips" — large main speaker and up to 7 other participants "one_main_twentyone_pips" — small main speaker and up to 21 other participants Default: "one_main_seven_pips"
guest_view (applies to service_type of "lecture" only)	No	String	The layout seen by Guests: "one_host" — full-screen main speaker only "hosts_only" — only Hosts are displayed (in a 1 + 7 layout) "hosts_and_guests" — Hosts and Guests are displayed (in a 1 + 21 layout) Default: "hosts_only"
locked	No	Boolean	Whether to lock the conference on creation: true — the conference will be locked on creation false — the conference will not be locked Note that 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: "video" — main video plus presentation "video-only" — main video only "audio" — audio-only 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: true — the Host sending the presentation stream will always hold the main video position false — the main video position is voice-switched 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: true — mute guests when they first join the conference false — do not 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: "gateway" — a Pexip Distributed Gateway call
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: "h323" — an H.323 call; you can also optionally nominate an h323_gatekeeper_name "sip" — a SIP call; you can also optionally nominate a sip_proxy_name "mssip" — a Microsoft Lync / Skype for Business call; you can also optionally nominate an mssip_proxy_name and a turn_server_name "rtmp" — uses the RTMP protocol; typically this is used for content streaming
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: "video" — main video plus presentation "video-only" — main video only "audio" — audio-only "auto" — match the capability of the outbound call to that of the inbound call Default: "video"
* 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: "two_stage_dialing" — a Virtual Reception
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: "video" — main video plus presentation "video-only" — main video only "audio" — audio-only 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 as a text overlay in some layout configurations.
protocol	Yes	String	The protocol to use to place the outgoing call: "h323" — an H.323 call "sip" — a SIP call "mssip" — a Microsoft Lync / Skype for Business call "rtmp" — uses the RTMP protocol; typically this is used for content streaming 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: "chair" — the participant has Host privileges "guest" — the participant has guest privileges
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. true — the participant is a streaming or recording device false — the participant is not 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: "keep_conference_alive" — keep alive when the ADP is the only participant remaining "keep_conference_alive_if_multiple" — keep alive if two or more ADPs with this setting remain in the call "keep_conference_alive_never" — terminate the conference if they are the only participant remaining Default: "keep_conference_alive_if_multiple"
call_type	No	String	The call capability of the participant. It can be limited to: "video" — main video plus presentation "video-only" — main video only "audio" — audio-only 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 JPG images must use the RGB or RGBA color space (CMYK is not supported).

Participant avatar response

The policy server should return a JPG file of the requested size (width, height).

If a valid JPG file 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.