Requests and responses when using the Pexip Infinity external policy API

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

We strongly recommend that you use HTTPS (not HTTP) in production environments.

A number of request parameters are added to the request URL 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, participant properties, 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 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

Participant properties

This allows some of the participant's call properties, such as their display name or role, to be changed before they join the conference. This allows you, for example, to anonymize a participant's name or modify their role based on other properties of the call or their associated Identity Provider.

  • For WebRTC participants it is applied after any PIN entry or SSO steps (and hence has access to Identity Provider attributes).
  • For SIP/H.323 endpoints, it is applied before any PIN entry steps.

Participant policy is applied after any service configuration policy, and before media location policy.

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

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 (and after any participant policy).

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 Connect apps 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).
  • You may see multiple service configuration, participant and media location requests when handling Connect app participants.

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. Pexip Infinity will not follow any 301/302 redirects received from the policy server.

The response to a request takes the basic format:

{
"status": "success",
"action": "reject|redirect|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 or participant properties request this would mean to reject the call (i.e. return "conference not found"), and for a registration request it would mean to reject the registration. However, note that if you have local policy enabled for service configuration or participant properties, the local policy could change the action and provide updated service configuration / participant properties instead.
    • "redirect" instructs Pexip Infinity to send a SIP response with status "302 redirect" to the requesting endpoint, telling it to place an otherwise identical call to a different alias. The "result" field specifies the alias to be used, using the format
      {"new_alias": "sip:alias@example.com"}
    • "continue" (or any other value except "reject" or "redirect") 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 associated support 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).

Dialing out from conference

Pexip Infinity makes a service configuration request if it dials out from a conference to invite a participant to join (where the call_direction parameter will be dial_out). In these cases, the response to the service configuration request must match the existing service data (i.e. the same name, service_type and so on).

When dialing out, the only configuration you can control via policy is:

  • The prefer_ipv6 setting in the service configuration response.
  • The media location — you can do this in the response to the media location request that follows the service configuration request.