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

Requests sent to the policy server from Pexip Infinity

Access to the policy server is via a GET request over HTTP or HTTPS. A number of request parameters are added to the request URI according to the request type.

Request types

The following table shows the different request types that a Conferencing Node running version 12 can send to an external policy server. The requests have been grouped into service information and participant information request types. It also shows the URI to which each policy request is sent.

Policy request type Description and request URI
Service information requests
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
  • retrieves the current or historic status of a conference

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

Participant information requests
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.

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

Participant avatar

Obtains the image to display to represent the conference participant.

Request URI: <policy_server_uri>/policy/v1/participant/avatar/<remote_alias>

where <remote_alias>* is the alias of the participant whose avatar is required.

Audio avatar (deprecated)

This request is deprecated from version 10 onwards; use the participant avatar request instead.

Obtains the image to display for an audio-only conference participant instead of their video stream.

Request URI: <policy_server_uri>/policy/v1/participant/audioavatar/<remote_alias>

where <remote_alias>* is the alias of the participant whose audio-only avatar is required.

* The remote_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 cannot configure Pexip Infinity as to whether specific requests are sent or not — all request types may be sent when external policy servers have been configured. However, the policy server could return an error code e.g. 404 if it wants Pexip Infinity to fall back to its own default behavior for a specific request.
  • Pexip Infinity has a non-configurable timeout of 5 seconds for each attempt it makes to contact a policy server.

Request parameters

All requests contain a common set of request parameters as described below. Requests for participant information (media location and participant avatar) include additional parameters.

Common request parameters

Parameter Description
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.

The same value is also sent in the context of participant requests, i.e. the originally-dialed incoming alias.

protocol

The call protocol.

Values: "api", "webrtc", "sip", "rtmp", "h323" or "mssip".

encryption

The requested encryption mode.

Values: "On", "Off" or "Unknown" (encryption has not yet been determined).

node_ip The IP address of the Conferencing Node making the request (and is also handling the call signaling).
location The name of the Pexip Infinity system location associated with the Conferencing Node making the request.
remote_address The IP address of the remote participant.
remote_port The IP port 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.
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.
call_direction

The direction of the call that triggered the request.

Values: "dial_in" (calls in to Pexip Infinity) or "dial_out" (calls dialed out from Pexip Infinity).

bandwidth The maximum requested bandwidth for the call.
version_id The Pexip Infinity software version number.
pseudo_version_id The Pexip Infinity software build number.
ms-subnet * The sender's subnet address.
p_Asserted-Identity * The authenticated identity of the user sending the SIP message.
* only included if the request was triggered by a SIP message, and the parameter is included as a field in the SIP message header

Additional parameters for participant information requests

Policy requests for participant information (media location and participant avatar) include all of the common request parameters above plus these additional parameters:

Parameter Description
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 "conference", "lecture" and "two_stage_dialing" services, this is the same as the service_name parameter.
  • 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).
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).

height * The required height in pixels of the image to be returned.
width * The required width in pixels of the image to be returned.
* role, height and width parameters are not sent in media location requests

The various request parameters mean that, for example, 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.

Example requests

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&remote_address=10.44.75.249&version_id=12&bandwidth=0&pseudo_version_id=29669.0.0&vendor=TANDBERG/518 (TC6.0.1.65adebe)&local_alias=meet.bob&remote_port=58435&call_direction=dial_in&encryption=On&remote_alias=sip:alice@example.com&remote_display_name=Alice&location=London

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&remote_address=10.44.75.250&version_id=12&service_tag=&bandwidth=0&pseudo_version_id=29669.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&encryption=On&remote_alias=sip:alice@example.com&remote_display_name=Alice&location=London

This example shows a GET request for a participant avatar, where the participant 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&remote_address=10.44.75.250&version_id=12&service_tag=&bandwidth=0&pseudo_version_id=29669.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=1080&unique_service_name=meet.bob&local_alias=meet.bob&remote_port=58426&call_direction=dial_in&encryption=On&remote_alias=alice&remote_display_name=Alice&width=1920&role=chair&location=London

Policy server responses

For information about the responses that Pexip Infinity expects to receive in return, see Policy server responses.