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:
Request URI: |
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: |
Participant avatar |
Obtains the image to display to represent the conference participant. Request URI: where * 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: where * 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:
|
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.