You are here: Integration > External and local policy > Requests sent to the policy server

Requests sent to the external policy API from Pexip Infinity

Pexip Infinity accesses the external policy API via a GET request over HTTP or HTTPS to the appropriate external policy server URI (as configured in the policy profile).

A number of request parameters are added to the request URI according to the request type. This provides flexibility to the decision-making process within the policy server, and means, for example, that the policy server could return:

different media location information based on the remote_alias or the call protocol
a different avatar for the same participant based on the originally dialed local_alias or the service_name
a different set of directory contacts depending on the registered_alias making the request.

This topic contains a summary of the supported requests and response guidelines. Each request type is then explained in more detail (see service configuration, media location, participant avatar, directory information and registration alias) including the parameters sent to the policy server for that request, the expected response and some examples. Finally, there is a summary matrix showing which parameters are contained in each policy request type.

Request types summary

The following table shows the different API request types that a Conferencing Node running version 14.2 can send to an external policy server.

Policy request type	Description and request URI
Service configuration	Obtains the configuration details of a service. Pexip Infinity typically makes this request when it: receives an incoming call request needs to place a call to a given alias Request URI: <policy_server_uri>/policy/v1/service/configuration
Media location	Obtains the system location to use for media allocation. A Conferencing Node assigned to that location will handle the media for the participant. A media location request is often made after a service configuration data request. Request URI: <policy_server_uri>/policy/v1/participant/location
Participant avatar	Obtains the image to display to represent a conference participant or directory contact. Request URI: <policy_server_uri>/policy/v1/participant/avatar/<alias> where <alias>* is the alias of the participant/contact whose avatar is required.
Directory information	Obtains directory information — a list of device or VMR aliases and their associated names. This is used to provide phonebook information to Infinity Connect desktop clients and Infinity Connect Mobile clients that are registered to a Pexip Infinity Conferencing Node. Request URI: <policy_server_uri>/policy/v1/registrations
Registration alias	Used to determine whether a device alias is allowed to register to a Conferencing Node. Request URI: <policy_server_uri>/policy/v1/registrations/<alias> where <alias>* is the alias of the device that is making the registration request.
* The alias may include scheme information, for example sip:alice@example.com. The policy server must be able to parse the received alias in an appropriate manner.

Note that:

You can configure whether specific request types are sent or not, on a per policy profile basis, via Call control > Policy Profiles. If a request type is disabled, Pexip Infinity will fall back to its own default behavior for that request type.
Pexip Infinity has a non-configurable timeout of 5 seconds for each attempt it makes to contact a policy server.
Most policy requests are sent from the Conferencing Node that is handling the call signaling or has received the registration request. However, requests are sent from the Conferencing Node that is handling the call media in the following situations:
- it is a participant avatar request
- the participant is in a Virtual Reception (note that when the endpoint initially calls the Virtual Reception alias, the requests will come from the Conferencing Node handling the signaling — as usual, but after being placed into the Virtual Reception all subsequent requests i.e. when the participant enters the number of the VMR they want to join, are sent from the Conferencing Node that is handling the Virtual Reception call media).

Policy server responses — general information

The 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 response for all requests, except for participant avatar requests, must return a Content-Type of application/json. 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 response to a request takes the basic format:

{
"status" : "success",
"action" : "reject|continue",
"result" : { <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 default behavior (which is to attempt to retrieve the relevant data from its own internal database), unless the "action" field is supported in the response for that request type, in which case the "action" field instructs Pexip Infinity how to proceed.
"action" is an optional value that may be included in responses to service configuration and registration alias requests. When present, it instructs Pexip Infinity how to proceed in failure scenarios:
- "reject" instructs Pexip Infinity to reject the request — for a service configuration request this would mean to reject the call immediately (i.e. return "conference not found"), and for a registration request it would mean to reject the registration.
- "continue" (or any other value except "reject") instructs Pexip Infinity to fall back to its default behavior (which is to attempt to retrieve the service configuration or device alias data from its own internal database).
"result" is a JSON object of key value pairs as appropriate for the request type. The specific requirements of what must be included in the result is included below in the descriptions of each request type. The fields in the JSON object can be supplied in any order.
"<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.

Note that responses to participant avatar requests have different requirements (see Participant avatar response for details).

Service configuration requests

Obtains the configuration details of a service. Pexip Infinity typically makes this request when it:

receives an incoming call request
needs to place a call to a given alias

Request URI: <policy_server_uri>/policy/v1/service/configuration

Pexip Infinity includes the following fields in a service configuration request:

Parameter	Description
bandwidth	The maximum requested bandwidth for the call.
call_direction	The direction of the call that triggered the request. Values: "dial_in" (calls in to Pexip Infinity), "dial_out" (calls dialed out from Pexip Infinity), or "None" (other policy triggers, for example if a SIP Subscribe request is received).
local_alias	In the context of service configuration requests, this is the incoming alias (typically the alias that the endpoint has dialed). This is the primary item of information that the policy server will use to return appropriate service configuration data.
location	The name of the Pexip Infinity system location associated with the Conferencing Node making the request/notification.
ms-subnet †	The sender's subnet address.
node_ip	The IP address of the Conferencing Node making the request.
p_Asserted-Identity†	The authenticated identity of the user sending the SIP message.
protocol	The call protocol. Values: "api", "webrtc", "sip", "rtmp", "h323" or "mssip". (Note that the protocol is always reported as "api" when an Infinity Connect client dials in to Pexip Infinity.)
pseudo_version_id	The Pexip Infinity software build number.
remote_address	The IP address of the remote participant.
remote_alias	The name of the user or the registered alias of the endpoint. The remote_alias may include scheme information, for example sip:alice@example.com.
remote_display_name	The display name of the remote participant.
remote_port	The IP port of the remote participant.
registered	Whether the remote participant is registered or not. Values: "True" or "False".
vendor	System details about the remote participant, such as manufacturer name and version number for hard endpoints, or browser and operating system details for soft clients.
version_id	The Pexip Infinity software version number.
† only included if the request was triggered by a SIP message, and the parameter is included as a field in the SIP message header

This example shows a GET request for service configuration data when alice@example.com has dialed meet.bob from a SIP endpoint:

GET /example.com/policy/v1/service/configuration?protocol=sip&node_ip=10.44.99.2&registered=False&remote_address=10.44.75.249&version_id=14&bandwidth=0&pseudo_version_id=33529.0.0&vendor=TANDBERG/518 (TC6.0.1.65adebe)&local_alias=meet.bob&remote_port=58435&call_direction=dial_in&remote_alias=sip:alice@example.com&remote_display_name=Alice&location=London

This example shows a call from an mssip (Lync / Skype for Business) endpoint:

GET /example.com/policy/v1/service/configuration?P-Asserted-Identity=%22Alice%22%3Csip%3Aalice%40example%3E&protocol=mssip&node_ip=10.47.2.43&registered=False&remote_address=10.47.2.20&version_id=14&bandwidth=0&pseudo_version_id=33529.0.0&vendor=RTCC%2F5.0.0.0+UCWA%2F5.0.0.0+AndroidLync%2F6.10.0.4+%28SM-G900F+Android+6.0.1%29&local_alias=sip%3Ameet.alice%40example.com&remote_port=63726&call_direction=dial_in&remote_alias=sip%3Aalice%40example.com&remote_display_name=Alice&location=London

Response to a service configuration request

The response to a service configuration request takes the basic format:

{
"status" : "success",
"action" : "reject|continue",
"result" : { <service_configuration_data> }
}

where:

"action" is an optional value that, when included, instructs Pexip Infinity how to proceed in failure scenarios:
- "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)
"result" is a JSON object of multiple key value pairs that describes 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, "two_stage_dialing" for a Virtual Reception, or "test_call" for a Test Call Service.
the "action" field is ignored if "status" is "success" and "result" contains valid data (and it is a 200 OK message).

The fields expected in the response for each service type are described below:

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 typically determines 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 128000 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 128000 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" — main speaker and up to 21 other participants "two_mains_twentyone_pips" — two main speakers 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" — main speaker and up to 21 other participants "two_mains_twentyone_pips" — two main speakers 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_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" — main speaker and up to 21 other participants "two_mains_twentyone_pips" — two main speakers and up to 21 other participants Default: "one_main_seven_pips" Only Hosts are displayed. Guests can hear but not see any of the other Guests.
enable_overlay_text	No	Boolean	If enabled, the display name or alias of each main speaker is shown. For more information, see Showing the names of speakers. true — speaker names are shown false — speaker names are not shown Default: false
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 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: "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. Ensure that all gateway service instances have a unique name to avoid conflicts between calls. 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 128000 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 128000 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"
called_device_type	No	String	The device or system to which to route the call: "external" — route the call to a matching registered device if it is currently registered, otherwise attempt to route the call via an external system "registration" — route the call to a matching registered device only (providing it is currently registered) "mssip_conference_id" — route the call via a Lync / Skype for Business server to a Lync / Skype for Business meeting where the remote_alias is a Lync / Skype for Business Conference ID "mssip_server" — route the call via a Lync / Skype for Business server to a Lync / Skype for Business client or meeting 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: "two_stage_dialing" — a Virtual Reception
name	Yes	String	The name of the service. The policy server typically determines 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 128000 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 128000 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"
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.
system_location_name	No	String	This is an optional field used in conjunction with the mssip_proxy_name setting. If specified, a Conferencing Node in this system location will perform the Lync / Skype for Business Conference ID lookup on the Lync / Skype for Business server. If a location is not specified, the IVR ingress node will perform the lookup.
match_string	No	String	An optional regular expression used to match against the alias entered by the caller into the Virtual Reception. If the entered alias does not match the expression, the Virtual Reception will not route the call. If this field is left blank, any entered alias is permitted. For more information, see Restricting or transforming the aliases entered into a Virtual Reception.
replace_string	No	String	An optional regular expression used to transform the alias entered by the caller into the Virtual Reception. (Only applies if a regex match string is also configured and the entered alias matches that regex.) Leave this field blank if you do not want to change the alias entered by the caller.

Test Call Service type response fields

Pexip Infinity expects the following fields to be returned for a service_type of "test_call" (Test Call Service):

Field name	Required	Type	Description
service_type	Yes	String	The type of service, in this case: "test_call" — a Test Call Service
name	Yes	String	The name of the service. The policy server typically determines 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 128000 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 service. 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.
remote_display_name	No	String	An optional friendly name for this participant. This may be used instead of the participant's alias in participant lists and as a text overlay in some layout configurations.
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.
routing	No	String	Specifies how to route the call: "manual" — uses the requested protocol and the defaults for the specified system_location_name. "routing_rule" — routes the call according to the configured Call Routing Rules— this means that the dialed alias must match an outgoing Call Routing Rule for the call to be placed (using the protocols and call control systems etc. as configured for that rule). Default: "manual"
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	An optional DTMF sequence to be transmitted after the call to the 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	Determines whether the conference continues when all other non-ADP participants have disconnected: "keep_conference_alive" — the conference continues to run until this participant disconnects (applies to Hosts only). "keep_conference_alive_if_multiple" — the conference continues to run as long as there are two or more "keep_conference_alive_if_multiple" participants and at least one of them is a Host. "keep_conference_alive_never" — the conference terminates automatically if this is the only remaining participant. 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: "video" — main video plus presentation "video-only" — main video only "audio" — audio-only Default: "video"
presentation_url	No	String	This additional parameter can be specified for RTMP calls to send the presentation stream to a separate RTMP destination.

Example service configuration data responses

Response containing service configuration data

This is an example response of service configuration data for a "conference" service type:

{
"status" : "success",
"action" : "continue",
"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",
  "enable_overlay_text" : true,
  "automatic_participants" : 
  [
    {
      "remote_alias" : "sip:alice@example.com",
      "remote_display_name" : "Alice",
      "local_alias" : "meet.alice@example.com",
      "local_display_name" : "Alice's VMR",
      "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",
      "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 requests

Obtains the system location to use for media allocation. A Conferencing Node assigned to that location will handle the media for the participant. A media location request is often made after a service configuration data request.

Request URI: <policy_server_uri>/policy/v1/participant/location

Pexip Infinity includes the following fields in a media location request:

Parameter	Description
bandwidth	The maximum requested bandwidth for the call.
call_direction	The direction of the call that triggered the request. Values: "dial_in" (calls in to Pexip Infinity), "dial_out" (calls dialed out from Pexip Infinity), or "None" (other policy triggers, for example if a SIP Subscribe request is received).
local_alias	For participant requests (media location and participant avatar) this contains the originally-dialed incoming alias for the associated service.
location	The name of the Pexip Infinity system location associated with the Conferencing Node making the request/notification.
ms-subnet †	The sender's subnet address.
node_ip	The IP address of the Conferencing Node making the request.
p_Asserted-Identity†	The authenticated identity of the user sending the SIP message.
protocol	The call protocol. Values: "api", "webrtc", "sip", "rtmp", "h323" or "mssip". (Note that the protocol is always reported as "api" when an Infinity Connect client dials in to Pexip Infinity.)
pseudo_version_id	The Pexip Infinity software build number.
remote_address	The IP address of the remote participant.
remote_alias	The name of the user or the registered alias of the endpoint. The remote_alias may include scheme information, for example sip:alice@example.com.
remote_display_name	The display name of the remote participant.
remote_port	The IP port of the remote participant.
registered	Whether the remote participant is registered or not. Values: "True" or "False".
service_name	The service name. This will match the name field returned by the policy server from the original service configuration request.
service_tag	The service tag associated with the service_name parameter.
unique_service_name	The unique name used by Pexip Infinity to identify the service: For "gateway" services this is the matching rule name followed by a unique identifier (so as to distinguish between separate calls that match the same rule). For all other services, this is the same as the service_name parameter.
vendor	System details about the remote participant, such as manufacturer name and version number for hard endpoints, or browser and operating system details for soft clients.
version_id	The Pexip Infinity software version number.
† only included if the request was triggered by a SIP message, and the parameter is included as a field in the SIP message header

This example shows a GET request for the media location to use for alice@example.com:

GET /example.com/policy/v1/participant/location?protocol=sip&node_ip=10.44.99.2&service_name=meet.bob&registered=False&remote_address=10.44.75.250&version_id=14&service_tag=&bandwidth=0&pseudo_version_id=33529.0.0&vendor=TANDBERG/518 (TC6.0.1.65adebe)&unique_service_name=meet.bob&local_alias=meet.bob&remote_port=58426&call_direction=dial_in&remote_alias=sip:alice@example.com&remote_display_name=Alice&location=London

Media location response

The response to a media location request takes the format:

{
"status" : "success",
"result" : { <location_data> }
}

where "result" is a JSON object of key value pairs that describes the media location to use. The fields that may be included are:

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 response containing media location data:

{
"status" : "success",
"result" : {
  "location" : "London",
  "primary_overflow_location" : "Oslo"
  }
}

Participant avatar requests

Obtains the image to display to represent a conference participant or directory contact.

Request URI: <policy_server_uri>/policy/v1/participant/avatar/<alias> where <alias> is the alias of the participant/contact whose avatar is required.

Pexip Infinity includes the following fields in a participant avatar request:

Parameter	Description
bandwidth	The maximum requested bandwidth for the call.
call_direction	The direction of the call that triggered the request. Values: "dial_in" (calls in to Pexip Infinity), "dial_out" (calls dialed out from Pexip Infinity), or "None" (other policy triggers, for example if a SIP Subscribe request is received).
height *	The required height in pixels of the image to be returned.
local_alias	For participant requests (media location and participant avatar) this contains the originally-dialed incoming alias for the associated service.
location *	The name of the Pexip Infinity system location associated with the Conferencing Node making the request/notification.
ms-subnet †	The sender's subnet address.
node_ip *	The IP address of the Conferencing Node making the request.
p_Asserted-Identity†	The authenticated identity of the user sending the SIP message.
protocol	The call protocol. Values: "api", "webrtc", "sip", "rtmp", "h323" or "mssip". (Note that the protocol is always reported as "api" when an Infinity Connect client dials in to Pexip Infinity.)
pseudo_version_id *	The Pexip Infinity software build number.
remote_address	The IP address of the remote participant.
remote_alias	The name of the user or the registered alias of the endpoint. The remote_alias may include scheme information, for example sip:alice@example.com.
remote_display_name	The display name of the remote participant.
remote_port	The IP port of the remote participant.
registered	Whether the remote participant is registered or not. Values: "True" or "False".
role	The role associated with the remote_alias. Values: "chair" (for Host participants), "guest" or "unknown" (a participant who is at the PIN entry screen).
service_name	The service name. This will match the name field returned by the policy server from the original service configuration request.
service_tag	The service tag associated with the service_name parameter.
unique_service_name	The unique name used by Pexip Infinity to identify the service: For "gateway" services this is the matching rule name followed by a unique identifier (so as to distinguish between separate calls that match the same rule). For all other services, this is the same as the service_name parameter.
vendor	System details about the remote participant, such as manufacturer name and version number for hard endpoints, or browser and operating system details for soft clients.
version_id *	The Pexip Infinity software version number.
width *	The required width in pixels of the image to be returned.
* these are the only parameters included in a participant avatar request when Pexip Infinity is retrieving directory information (as opposed to service participant-related information where all parameters are included) † only included if the request was triggered by a SIP message, and the parameter is included as a field in the SIP message header

This example shows a GET request for a participant avatar for the alias "alice" who is in the conference "meet.bob", where the participant device is an unregistered Infinity Connect client:

GET /example.com/policy/v1/participant/avatar/alice?protocol=webrtc&node_ip=10.44.99.2&service_name=meet.bob&registered=False&remote_address=10.44.75.250&version_id=14&service_tag=&bandwidth=0&pseudo_version_id=33529.0.0&vendor=Mozilla%2F5.0+%28X11%3B+Linux+x86_64%29+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%29+Chrome%2F40.0.2214.111+Safari%2F537.36&height=100&unique_service_name=meet.bob&local_alias=meet.bob&remote_port=58426&call_direction=dial_in&remote_alias=alice&remote_display_name=Alice&width=100&role=chair&location=London

This example shows a GET request for a participant avatar for the alias "alice" that has been triggered in response to a previous directory information request:

GET /example.com/policy/v1/participant/avatar/alice?node_ip=10.47.2.46&registered=True&version_id=14&height=40&width=40&location=London&pseudo_version_id=33529.0.0

Participant avatar response

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), and be 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.

Directory information requests

Obtains directory information — a list of device or VMR aliases and their associated names. This is used to provide phonebook information to Infinity Connect desktop clients and Infinity Connect Mobile clients that are registered to a Pexip Infinity Conferencing Node.

Request URI: <policy_server_uri>/policy/v1/registrations

Pexip Infinity includes the following fields in a directory information request:

Parameter Available call_info variables	Description
limit	The maximum number of results to return (currently this is always set to 10).
location	The name of the Pexip Infinity system location associated with the Conferencing Node making the request/notification.
node_ip	The IP address of the Conferencing Node making the request.
pseudo_version_id	The Pexip Infinity software build number.
q	The string to lookup in the directory.
registration_alias	The alias of the registered client performing the directory lookup.
version_id	The Pexip Infinity software version number.

This example shows a GET request for directory information where the search string is "ali":

GET /example.com/policy/v1/registrations?q=ali&registration_alias=bob@example.com&limit=10&location=london&node_ip=10.44.155.21&pseudo_version_id=33529.0.0&version_id=14

Directory information response

The response to a directory information request takes the format:

{
"status" : "success",
"result" : [ <directory_data> ],
"ignore_local" : True|False
}

where:

"result" is a JSON list containing objects representing individual directory entries. Each JSON object in the list contains the following fields:

Field name	Required	Description
username	Yes	The username associated with the device or VMR. This is currently unused by Pexip Infinity.
alias	Yes	The alias of the device or VMR. This is the alias Pexip Infinity will use as the <alias> in the URI in a subsequent participant avatar request, and the alias that Pexip Infinity clients will dial.
description	Yes	A description or name associated with the alias.

The policy server should sort the list of aliases into the order in which it wants them to be presented.

"ignore_local" is optional and defaults to False. If set to True it instructs Pexip Infinity to ignore the aliases of any local services or devices i.e. to only use the aliases returned from the policy server as the directory information. When "ignore_local" is False, Pexip Infinity adds the aliases of any local services or devices to the list of aliases returned by the policy server.

Example directory information responses

This is an example of a JSON dictionary of directory information data containing 2 devices:

{
"status" : "success",
"result" : 
  [
    {
      "username" : "alice",
      "alias" : "alice@example.com",
      "description" : "Alice's VMR",
    },
    {
      "username" : "bob",
      "alias" : "bob@example.com",
      "description" : "Bob's VMR",
    }
  ]
}

This is an example response that instructs Pexip Infinity to not supply any directory information at all — no aliases are returned by the policy server and it also tells Pexip Infinity to ignore any local aliases ("ignore_local" is True):

{
"status" : "success",
"result" : [],
"ignore_local": True
}

Registration alias requests

Used to determine whether a device alias is allowed to register to a Conferencing Node.

Request URI: <policy_server_uri>/policy/v1/registrations/<alias> where <alias> is the alias of the device that is making the registration request.

Pexip Infinity includes the following fields in a registration request:

Parameter Available call_info variables	Description
location	The name of the Pexip Infinity system location associated with the Conferencing Node making the request/notification.
node_ip	The IP address of the Conferencing Node making the request.
pseudo_version_id	The Pexip Infinity software build number.
version_id	The Pexip Infinity software version number.

This example shows a GET request for a registration alias of "alice@example.com":

GET /example.com/policy/v1/registrations/alice@example.com?pseudo_version_id=33529.0.0&location=london&version_id=14&node_ip=10.44.155.21

Registration alias response

The response to a registration alias request takes the format:

{
"status" : "success",
"action" : "reject|continue",
"result" : { <alias_data> }
}

where:

"action" is an optional value that, when included, instructs Pexip Infinity to either reject the registration or use its internal database:
- "reject" instructs Pexip Infinity to reject the registration
- "continue" (or any other value except "reject") instructs Pexip Infinity to fall back to its default behavior, which is to check if the alias and optionally any associated credentials are configured in its local database of allowed aliases.

"result" is an optional value that, when included, is a JSON object of key value pairs that contains the credentials to use to authenticate the registration request. The fields that may be included are:

Field name	Required	Description
username	No	The username associated with the device.
password	No	The password associated with the device and username. Note that the password is sent "in the clear" so we recommend using a secure https connection to your policy server.

Field name

Required

Description

username

The username associated with the device.

password

The password associated with the device and username.

Note that the password is sent "in the clear" so we recommend using a secure https connection to your policy server.

Pexip Infinity handles the response as follows:

If the "action" field is specified, all other fields are ignored and Pexip Infinity performs a "reject" or "continue" as specified by the "action".
If "status" is "success" (and the "action" field is not specified):
- If the "result" field (containing username / password credentials ) is included, then the device alias may register if it supplies matching credentials.
- If the "result" field is not included, then the device alias may register without any authentication / credential checking.
If "status" is not "success" or an error code e.g. 404 is returned (and the "action" field is not specified), then Pexip Infinity will fall back to its own default behavior (to check if the alias and optionally any associated credentials are configured in its local database of allowed aliases).

Example registration alias responses

Allowed alias (with authentication): this is an example response containing the required credentials for an allowed alias (the device must then supply the matching credentials to be permitted to register):

{
"status" : "success",
"result" : {
  "username" : "alice",
  "password" : "password123"
  }
}

Allowed alias (without authentication): this is an example response that allows the alias to register without authentication:

{
"status" : "success",
}

Denied alias: this is an example response to reject the requested alias:

{
"status" : "success",
"action" : "reject"
}

Summary of request parameters per request type

This table summarizes which fields are included by Pexip Infinity in each request type:

Parameter	Description	Service config	Media location	Participant avatar	Directory info	Registration alias
bandwidth	The maximum requested bandwidth for the call.
call_direction	The direction of the call that triggered the request. Values: "dial_in" (calls in to Pexip Infinity), "dial_out" (calls dialed out from Pexip Infinity), or "None" (other policy triggers, for example if a SIP Subscribe request is received).
height *	The required height in pixels of the image to be returned.
limit	The maximum number of results to return (currently this is always set to 10).
local_alias	In the context of service configuration requests, this is the incoming alias (typically the alias that the endpoint has dialed). This is the primary item of information that the policy server will use to return appropriate service configuration data. For participant requests (media location and participant avatar) this contains the originally-dialed incoming alias for the associated service.
location *	The name of the Pexip Infinity system location associated with the Conferencing Node making the request/notification.
ms-subnet †	The sender's subnet address.
node_ip *	The IP address of the Conferencing Node making the request.
p_Asserted-Identity†	The authenticated identity of the user sending the SIP message.
protocol	The call protocol. Values: "api", "webrtc", "sip", "rtmp", "h323" or "mssip". (Note that the protocol is always reported as "api" when an Infinity Connect client dials in to Pexip Infinity.)
pseudo_version_id *	The Pexip Infinity software build number.
q	The string to lookup in the directory.
registration_alias	The alias of the registered client performing the directory lookup.
remote_address	The IP address of the remote participant.
remote_alias	The name of the user or the registered alias of the endpoint. The remote_alias may include scheme information, for example sip:alice@example.com.
remote_display_name	The display name of the remote participant.
remote_port	The IP port of the remote participant.
registered	Whether the remote participant is registered or not. Values: "True" or "False".
role	The role associated with the remote_alias. Values: "chair" (for Host participants), "guest" or "unknown" (a participant who is at the PIN entry screen).
service_name	The service name. This will match the name field returned by the policy server from the original service configuration request.
service_tag	The service tag associated with the service_name parameter.
unique_service_name	The unique name used by Pexip Infinity to identify the service: For "gateway" services this is the matching rule name followed by a unique identifier (so as to distinguish between separate calls that match the same rule). For all other services, this is the same as the service_name parameter.
vendor	System details about the remote participant, such as manufacturer name and version number for hard endpoints, or browser and operating system details for soft clients.
version_id *	The Pexip Infinity software version number.
width *	The required width in pixels of the image to be returned.
* these are the only parameters included in a participant avatar request when Pexip Infinity is retrieving directory information (as opposed to service participant-related information where all parameters are included) † only included if the request was triggered by a SIP message, and the parameter is included as a field in the SIP message header