Management command API

Response format

The response for a command will be a JSON object with the following attributes:

Individual commands may have response attributes specific to the command. See the command examples for more information.

Dialing a participant into a conference

By submitting a POST request to the dial resource URI, a new participant can be dialed into a conference.

When using this command, note that:

• The conference_alias is used for two purposes:

  • The participant being dialed will see the incoming call as coming from this alias.
  • On answer, the participant will join the conference instance associated with this alias.

• If routing is set to routing_rule then:

  • The destination alias must match an outgoing Call Routing Rule for the call to be placed (and it then uses the protocol, outgoing location and call control systems etc. as configured for that rule).
  • You must specify system_location. In this case, this acts as the notional source location used when considering if a Call Routing Rule applies or not. A random node in that location is used, which may just take the signaling for the call if the node is loaded.
  • You do not need to specify node or protocol.

• If routing is set to manual then:

  • One or both of the node and system_location must be specified.
  • The node overrides the system_location if both are given.
  • If only the system_location is given, a random node in that location is used, which may just take the signaling for the call if the node is loaded.
  • The node must be an IP address and not an FQDN.

The following example places a call to the alias alice and uses Call Routing Rules. The node/location used to place the call is determined by whichever Call Routing Rule matches this dial request. The rule can optionally use the Calls being handled in location condition to test against the nominated source location of London. Alice will see the call as coming from alias meet@example.com, and on answer will join the Virtual Meeting Room associated with that alias (in this case VMR_1, based on our configuration API examples), as a Host.

import requests
import json
response = requests.post(
    "https://<manageraddress>/api/admin/command/v1/participant/dial/",
    auth=('<user1>', '<password1>'),
    data={
        'conference_alias': 'meet@example.com',
        'destination': 'alice',
        'routing': 'routing_rule',
        'remote_display_name': 'Alice Parkes',
        'role': 'chair',
        'system_location': 'London',
        },
    verify=True)
print("New participant created:", json.loads(response.content)['data']['participant_id'])

Note that if the dial command is successful the response will contain a participant_id attribute which can be used in queries for status and other conference control commands such as Disconnecting a participant and Muting a participant.

Disconnecting a participant

By submitting a POST request to the disconnect resource URI, an existing participant can be disconnected from a conference instance.

import requests
response = requests.post(
    "https://<manageraddress>/api/admin/command/v1/participant/disconnect/",
    auth=('<user1>', '<password1>'),
    data={
        'participant_id': '00000000-0000-0000-0000-000000000001',
        },
    verify=True)

Muting a participant

By submitting a POST request to the mute resource URI, the audio being sent from an existing conference participant can be muted, meaning all other participants will not hear them.

import requests
response = requests.post(
    "https://<manageraddress>/api/admin/command/v1/participant/mute/",
    auth=('<user1>', '<password1>'),
    data={
        'participant_id': '00000000-0000-0000-0000-000000000001',
        },
    verify=True)

Muting all Guest participants

By submitting a POST request to the mute_guests resource URI, the audio being received from all Guest participants within an existing conference will be muted.

import requests
response = requests.post(
    "https://<manageraddress>/api/admin/command/v1/conference/mute_guests/",
    auth=('<user1>', '<password1>'),
    data={
        'conference_id': '00000000-0000-0000-0000-000000000001',
    },
    verify=True)

Unmuting a participant

By submitting a POST request to the unmute resource URI, a previously muted conference participant will have their audio restored, meaning other participants will again be able to hear them.

import requests
response = requests.post(
    "https://<manageraddress>/api/admin/command/v1/participant/unmute/",
    auth=('<user1>', '<password1>'),
    data={
        'participant_id': '00000000-0000-0000-0000-000000000001',
        },
    verify=True)

Unmuting all Guest participants

By submitting a POST request to the unmute_guests resource URI, the audio being received from all Guest participants within an existing conference will be unmuted.

import requests
response = requests.post(
    "https://<manageraddress>/api/admin/command/v1/conference/unmute_guests/",
    auth=('<user1>', '<password1>'),
    data={
        'conference_id': '00000000-0000-0000-0000-000000000001',
    },
    verify=True)

Locking a conference instance

By submitting a POST request to the conference lock resource URI, the conference instance will be locked, preventing new participants from joining. Instead new participants will be held at the Waiting for conference host screen. Note that if a service has a Host PIN, participants who enter the PIN will still be able to access the conference even when it is locked. For more information, see Locking a conference and allowing participants to join a locked conference.

import requests
response = requests.post(
    "https://<manageraddress>/api/admin/command/v1/conference/lock/",
    auth=('<user1>', '<password1>'),
    data={
        'conference_id': '00000000-0000-0000-0000-000000000001',
    },
    verify=True)

Unlocking a conference instance

By submitting a POST request to the conference unlock resource URI, a previously locked conference instance can be unlocked, meaning new participants will be allowed to join. Any participants held at the Waiting for conference host screen will also automatically join the conference.

import requests
response = requests.post(
    "https://<manageraddress>/api/admin/command/v1/conference/unlock/",
    auth=('<user1>', '<password1>'),
    data={
        'conference_id': '00000000-0000-0000-0000-000000000001',
    },
    verify=True)

Unlocking a participant

By submitting a POST request to the participant unlock resource URI, a participant held at the Waiting for conference host screen because the conference has been locked will be allowed to join the conference.

import requests
response = requests.post(
    "https://<manageraddress>/api/admin/command/v1/participant/unlock/",
    auth=('<user1>', '<password1>'),
    data={
        'participant_id': '00000000-0000-0000-0000-000000000001',
    },
    verify=True)

Transferring a participant

By submitting a POST request to the participant transfer resource URI, a participant can be moved from one conference to another. The target conference is identified by an alias in the conference_alias field, and they will have the specified role.

If the target conference is PIN-protected, the participant will bypass the PIN entry.

import requests
response = requests.post(
    "https://<manageraddress>/api/admin/command/v1/participant/transfer/",
    auth=('<user1>', '<password1>'),
    data={
        'participant_id': '00000000-0000-0000-0000-000000000001',
        'conference_alias': 'meet@example.com',
        'role': 'guest'
    },
    verify=True)

Changing a participant's role

By submitting a POST request to the participant role resource URI, a participant can have its role changed. The target participant is identified by the participant_id field, and it will be given the specified role ("guest" or "chair").

import requests
response = requests.post(
    "https://<manageraddress>/api/admin/command/v1/participant/role/",
    auth=('<user1>', '<password1>'),
    data={
        'participant_id': '00000000-0000-0000-0000-000000000001',
        'role': 'chair',
    },
    verify=True)

Changing a conference's layout

By submitting a POST request to the conference transform_layout resource URI, you can control the layout, overlay text and other in-conference indicators.

import requests
response = requests.post(
    "https://<manageraddress>/api/admin/command/v1/conference/transform_layout/",
    auth=('<user1>', '<password1>'),
    data={
        'conference_id': '00000000-0000-0000-0000-000000000001',
        'enable_overlay_text': True,
        'layout': '4:0'
    },
    verify=True)

You can create a system backup by submitting a POST request to the platform backup_create resource URI.

You must specify a passphrase (replacing <backup_password> in the example below). The passphrase is used to encrypt the backup file. You must remember the passphrase as it will be required if you need to subsequently restore the data.

import requests
response = requests.post(
    "https://<manageraddress>/api/admin/command/v1/platform/backup_create/",
    auth=('<user1>', '<password1>'),
    data={
        'passphrase': '<backup_password>',
    },
    verify=True)

You can perform a GET on /api/admin/configuration/v1/system_backup/ to list the available backup files on the Management Node that can be restored (however, restoration must occur on exactly the same software version of Pexip Infinity that the backup was taken from).

import requests
response = requests.get(
    "https://<manageraddress>/api/admin/configuration/v1/system_backup/",
    auth=('<user1>', '<password1>'),
    verify=True)
print(response.content)

The response will include data similar to this for each backup file:

{
    "build": "59437.0.0",
    "date": "2021-01-08T15:36:16",
    "filename": "pexip_backup_10-44-7-0-mgr_25_59437.0.0_21_01_08_09_05_43.tar.pexbak",
    "resource_uri": "/api/admin/configuration/v1/system_backup/pexip_backup_10-44-7-0-mgr_25_59437.0.0_21_01_08_09_05_43.tar.pexbak/",
    "size": 214702132,
    "version": "25"
}

The "filename" value is what you will use in place of <filename> in the following GET command to download the file.

Note that if a backup file is no longer needed, you can perform a DELETE on the https://<manageraddress>/api/admin/configuration/v1/system_backup/<filename>/ URL to delete individual files.

Next you can perform a GET on /api/admin/configuration/v1/system_backup/<filename>/ to download the backup file to a temporary location.

import requests
response = requests.get(
    "https://<manageraddress>/api/admin/configuration/v1/system_backup/<filename>/",
    auth=('<user1>', '<password1>'),
    verify=True)
with open("/tmp/temp.bak", "w") as file_handle:
    file_handle.write(response.content)

This downloads the backup file to /tmp/temp.bak — you can change this to your preferred location and filename if required.

Using the example response from the list of available backups, the GET would be for: "https://10.44.7.0/api/admin/configuration/v1/system_backup/pexip_backup_10-44-7-0-mgr_25_59437.0.0_21_01_08_09_05_43.tar.pexbak/"

Finally, you can restore the contents of the backup file by submitting a POST request to the platform backup_restore resource URI, telling it to use the temporary file created in the previous step.

You must also specify the passphrase that was used to encrypt the backup file when it was generated.

import requests
response = requests.post(
    "https://<manageraddress>/api/admin/command/v1/platform/backup_restore/",
    auth=('<user1>', '<password1>'),
    data={
        'passphrase': '<backup_password>',
    },
    files={
        'package': open('/tmp/temp.bak'),
    },
    verify=True)