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.1 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).