User Additional Phones Services¶
The User Additional Phone Services APIs manage directly the an Access Device such as it was a property of the User and not of the Groups such as in the Application Server. It means that they will create/delete/modify the Access Device at Group level when needed and manage its link to an End User.
This set of APis allow to manage additional devices in addition of his main phone (that is covered by the User Main Phone).
In the specific case where the additional device is the main device of an other user, there are end points at the level of this user to see the extra users connected to his phone (aka the “extra lines” on his phone).
- The integrated management of extra devices for an End User is quite a complex logic as it orchestrates several low level APIs at Application Server side. APIO team had therefore to do some choices
in terms of logic and rules to build ids. But always choices reduce the full flexibility, therefore if these decision are not valid for a specific deployment it is always possible for a project to use directly the low level APIs and not use these integrated APIs.
Retrieve the Additional Phones of a User¶
-
GET
/api/v1/tenants/
(string: tenant_id)/groups/
(string: group_id)/users/
(string: user_id)/access_device/extra_phones/
¶ Retrieve the list of additional access devices of the User.
Authorization Right: minimum End User.
Example request:
GET /api/v1/tenants/foo/groups/foogroup/users/foouser/access_device/extra_phones/ HTTP/1.1 Host: example.com
Example response:
HTTP/1.1 200 OK Content-Type: "application/json" { "extra_phones": [{ "deviceName": "dev3225156783m1", "deviceType": "Generic SIP Phone", "deviceOwner": "foouser", "deviceUsage": "PHONE", "_description": "extra-own-device-1", "extra_phone_id": 1, "linePort": "+3225156783A1@sip.netaxis.be", }, { "deviceName": "dev3225156785m2", "deviceType": "Generic SIP Phone", "deviceOwner": "foouser", "deviceUsage": "PHONE", "_description": "extra-own-device-2" "extra_phone_id": 2, "linePort": "+3225156783A2@sip.netaxis.be", }], "quantity_free_ids": 3 }
- Response JSON Object:
extra_phones (array) – the list of additional phones linked to the User. See User Device Extra Endpoint Attributes.
quantity_free_ids (integer) – the amount of free Ids for creation of extra phones.
- Status Codes:
200 OK – no error
Create an Additional Phone for a User¶
-
POST
/api/v1/tenants/
(string: tenant_id)/groups/
(string: group_id)/users/
(string: user_id)/access_device/extra_phones/
¶ - Create an additional phone for an User.The device can be created with an auto-generated name or it can be created by using deviceName.Instead to create a new device, it can be used an existing main device of another User using target_user_id. In that case it will be more a multi-lines concept at the level of the target user.With target_user_id is forbidden to send the deviceType as there is no device created to be created.
The linePort will always be auto-generated by APIO using configurable auto-generation rules as defined in Configuration Information for the Additional Phones.
Authorization Right: minimum Group Admin.
Example request:
POST /api/v1/tenants/foo/groups/foogroup/users/foouser/access_device/extra_phones/ HTTP/1.1 Host: example.com { "deviceType": "Generic SIP Phone", "macAddress": "AABBCCDDEEFF00", "extra_phone_id": 1 }
Example request with deviceName:
POST /api/v1/tenants/foo/groups/foogroup/users/foouser/access_device/extra_phones/ HTTP/1.1 Host: example.com { "deviceType": "Generic SIP Phone", "deviceName": "my_device_name", "macAddress": "AABBCCDDEEFF00", "extra_phone_id": 1 }
Example request with target_user_id:
POST /api/v1/tenants/foo/groups/foogroup/users/foouser/access_device/extra_phones/ HTTP/1.1 Host: example.com { "target_user_id": "foouser@netaxis.be", "extra_phone_id": 2 }
Example response:
HTTP/1.1 200 OK Content-Type: "application/json"
- Response:
Similar to GET instance method response.
- Request JSON Object:
deviceType (string) – (conditional) the Type of Device to te added, mandatory only when creating a new device, forbidden with target_user_id.
extra_phone_id (integer) – (optional) the id of the phone (must be unique)
deviceName (string) – (conditional) the device name.
target_user_id (string) – (conditional) link as multi-line to the main device of the target user.
macAddress (string) – (optional) the MAC address of the device, not relevant in case of target_user_id.
serialNumber (string) – (optional) the serial number of the device, not relevant in case of target_user_id.
phoneUsername (string) – (optional) the username of phone credentials, depending on the phone type and not relevant in case of target_user_id. Mandatory with phoneUsername.
phonePassword (string) – (optional) the password of phone credentials, depending on the phone type and not relevant in case of target_user_id. Mandatory with phonePassword.
active (boolean) – (optional) enable this SCA.
allowOrigination (boolean) – (optional) allow Origination from this SCA.
allowTermination (boolean) – (optional) allow Termination to this SCA.
- Response:
Similar to GET instance method response.Except that the following additional parameter can be present when relevant.
- Response JSON Object:
deviceActivationCode (string) – If the device type supports the auto-configuration via a Device Activation Code it will be returned.
- Status Codes:
201 Created – no error
- Statusocde 400:
Unable to create the device, with possible sub-error codes:
9: MISSING_CONDITIONAL_PARAMETERS, “When a field between phoneUsername and phonePassword is sent, the other is conditionally mandatory”
18: INVALID_OPERATION, “No more free id available for an additional phone.”
18: INVALID_OPERATION, “No more free ports available on the target device”
2: INVALID_PARAMETERS, “The fields deviceName and target_user_id are mutually exclusive”
18: INVALID_OPERATION, “Cannot use the same User’s main device”
9: MISSING_CONDITIONAL_PARAMETERS, “This device type requires ‘lineNumber’”
1: MISSING_MANDATORY_PARAMETERS, “deviceType”
43: IMPOSSIBLE_TO_GENERATE_ID, “Impossible to generate device name or line port”
18: INVALID_OPERATION, “The user main device is linked to an app”
18: INVALID_OPERATION, “The target user has no main device”
2: INVALID_PARAMETERS, “This value is reserved for Integrated Apps.”: if trying to use an extra_phone_id reserved for integrated App but not with the correct deviceType.
- note:
The extra_phone_id can be provided if the user wants to force that specific id or it can be omitted and in that case the APIO will try to find a free one and based on rules presented at the end of this page.
Retrieve the Additional Phone of a User¶
-
GET
/api/v1/tenants/
(string: tenant_id)/groups/
(string: group_id)/users/
(string: user_id)/access_device/extra_phones/
(string: instance_name)/
¶ Retrieve the details of an Additional Access Device of the User.
Authorization Right: minimum End User.
Example request:
GET /api/v1/tenants/foo/groups/foogroup/users/foouser/access_device/extra_phones/dev3225156783m1/ HTTP/1.1 Host: example.com
Example response:
HTTP/1.1 200 OK Content-Type: "application/json" { "deviceName": "dev3225156783m1", "deviceType": "Generic SIP Phone", "deviceUsage": "PHONE", "_description": "extra-own-device-1", "macAddress": "AA:BB:CC:DD:EE:FF:00", "serialNumber": "", "linePort": "+3225156783A01@sip.netaxis.be", "active": true, "allowOrigination": false, "allowTermination": false }
- Response JSON Object:
deviceName (string) – the device name.
deviceType (string) – the Type of Device to te added, mandatory only when creating a new device, forbidden with target_user_id.
deviceUsage (string) – the device usage. See deviceUsage User Device Extra Endpoint Attributes.
_description (string) – The description “extra-own-device-” followed by a number indicates the number of the extra device. NOTE: for internal user only.
macAddress (string) – the MAC address of the device.
serialNumber (string) – the serial number of the device.
linePort (string) – the line port.
phoneUsername (string) – (conditional) the username of phone credentials, only if relevant.
active (boolean) – enable this SCA.
allowOrigination (boolean) – allow Origination from this SCA. NOTE: an End User cannot modify it, silent discard.
allowTermination (boolean) – allow Termination to this SCA. NOTE: an End User cannot modify it, silent discard.
- Status Codes:
200 OK – no error
- Statusocde 404:
the user has no phone linked to him, with possible sub-error codes:
8: NOT_FOUND_AT_NE
Update an Additional Phone of a User¶
-
PUT
/api/v1/tenants/
(string: tenant_id)/groups/
(string: group_id)/users/
(string: user_id)/access_device/extra_phones/
(string: instance_name)/
¶ Update an additional phone of an User.
Authorization Right: minimum End User.
- Note:
An EndUser is allowed to modify only the active flag.
Example request:
PUT /api/v1/tenants/foo/groups/foogroup/users/foouser/access_device/extra_phones/dev3225156783m1/ HTTP/1.1 Host: example.com Content-Type: "application/json" { "macAddress": "AABBCCDDEEFF33", "allowOrigination": false, "phoneUsername": "user-test", "phonePassword": "tesT_pasSw0rd", }
Example response:
HTTP/1.1 200 OK Content-Type: "application/json"
- Response:
Similar to GET instance method response.
- Request JSON Object:
macAddress (string) – (optional) the MAC address of the device.
serialNumber (string) – (optional) the serial number of the device.
useCustomUserNamePassword (string) – (optional) to toggle the phone credentials. When disabling the credentials, phoneUsername and phonePassword MUST not be provided.
phoneUsername (string) – (optional) the username of phone credentials, depending on the phone type and not relevant in case of target_user_id. Mandatory with phoneUsername.
phonePassword (string) – (optional) the password of phone credentials, depending on the phone type and not relevant in case of target_user_id. Mandatory with phonePassword.
active (boolean) – (optional) enable this SCA.
allowOrigination (boolean) – (optional) allow Origination from this SCA. NOTE: an End User cannot modify it, silent discard.
allowTermination (boolean) – (optional) allow Termination to this SCA. NOTE: an End User cannot modify it, silent discard.
- Response:
Similar to GET instance method response.Except that the following additional parameter can be present when relevant.
- Response JSON Object:
deviceActivationCode (string) – If the device type supports the auto-configuration via a Device Activation Code and the Mac Address is changed it will be returned.
- Status Codes:
200 OK – no error
- Statusocde 404:
no phone linked to the user, with possible sub-error codes:
8: NOT_FOUND_AT_NE
- Statusocde 400:
error during the update, with possible sub-error codes:
9: MISSING_CONDITIONAL_PARAMETERS, When one of the field phoneUsername or phonePassword is sent, the other is conditionally mandatory.
Delete an Additional Phone of a User¶
-
DELETE
/api/v1/tenants/
(string: tenant_id)/groups/
(string: group_id)/users/
(string: user_id)/access_device/extra_phones/
(string: instance_name)/
¶ Delete an extra phone of an User.
Authorization Right: minimum Group Admin.
Example request:
DELETE /api/v1/tenants/foo/groups/foogroup/users/foouser/access_device/extra_phones/dev3225156783m1/ HTTP/1.1 Host: example.com Content-Type: "application/json" { }
Example response:
HTTP/1.1 200 OK Content-Type: "application/json" { }
- Status Codes:
200 OK – no error
- Statusocde 400:
error during the removal, with possible sub-error codes:
8: NOT_FOUND_AT_NE
18: INVALID_OPERATION, “This device is linked to an APP”. When using Integrated App, the device will be deleted when the associated Service pack will be unassigned.
Retrieve the User’s Phone Extra Lines¶
-
GET
/api/v1/tenants/
(string: tenant_id)/groups/
(string: group_id)/users/
(string: user_id)/access_device/extra_lines/
¶ Retrieve the User’s phone extra lines linked to it. This is the result of a user linked to the main device of this user using the target_user_id.
Authorization Right: minimum End User.
Example request:
GET /api/v1/tenants/foo/groups/foogroup/users/foouser/access_device/extra_lines/ HTTP/1.1 Host: example.com
Example response:
HTTP/1.1 200 OK Content-Type: "application/json" { "extra_lines": [{ "userId": "ApioUserTest1@sip.netaxis.be", "linePort": "lp_test_1@sip.netaxis.be", "firstName": "Test1", "lastName": "Test1", "phoneNumber": "+3225126778", "department": { "tenantId": "ApioSpTest", "groupId": "ApioGrpTest", "departmentName": "test_department_initial", "fullPathName": "test_department_initial" }, "order": 3 }], "availablePorts": 9, }
- Response JSON Object:
extra_lines (array) – the list of extra lines linked to the User. See User Device Extra Line Attributes.
availablePorts (optional) (integer) – the number of ports still available on the main device, it allows the client to know how much extra lines he can add to it. It must be noted that it will not be present if not known.
- Status Codes:
200 OK – no error
Adding Extra Lines to the User’s Phone¶
-
POST
/api/v1/tenants/
(string: tenant_id)/groups/
(string: group_id)/users/
(string: user_id)/access_device/extra_lines/
¶ Adding extra lines to the main phone of the user. It is the same operation as Create an Additional Phone for a User but viewed from the other side of the association.
Authorization Right: minimum Group Admin.
Example request:
POST /api/v1/tenants/foo/groups/foogroup/users/foouser/access_device/extra_lines/ HTTP/1.1 Host: example.com Content-Type: "application/json" { "userIds": ["ApioUserTest@sip.netaxis.be", "ApioUserTest1@sip.netaxis.be"] }
Example response:
HTTP/1.1 200 OK Content-Type: "application/json" { "results": [ { "userId": "ApioUserTest@sip.netaxis.be", "status": "SUCCESS", "data": { "deviceName": "test_apio_device_for_ml", "deviceType": "Yealink-T42S", "deviceUsage": "Phone", "_description": "", "macAddress": "D4:2E:CC:6A:FD:01", "linePort": "+3225126779A01@sip.netaxis.be", "active": True, "allowOrigination": True, "allowTermination": True, "extra_phone_id": 1 } }, { "userId": "ApioUserTest1@sip.netaxis.be", "status": "FAILED", "reason": "No more free id available for an additional phone.", "error": { "code": 18, "message": "No more free id available for an additional phone.", "details": { "reason": "No more free SCA available for additional CPE." } } } ] }
- Request JSON Object:
userIds (array) – list of user ids for which an extra line must be added to the user’s main phone.
- Response JSON Object:
result (array) – an array with an object giving the result for each requested user.
- Status Codes:
201 Created – no error
207 Multi Status – partial success, i.e. the lines were added, others not
- Statusocde 400:
the operation fully failed
Retrieve the details of one User’s Phone Additional Line¶
-
GET
/api/v1/tenants/
(string: tenant_id)/groups/
(string: group_id)/users/
(string: user_id)/access_device/extra_lines/
(string: instance_name)/
¶ Retrieve the User’s phone extra line linked to it, the instance name being the user id of the user who repolicated his line on this phone.
Authorization Right: minimum End User.
Example request:
GET /api/v1/tenants/foo/groups/foogroup/users/foouser/access_device/extra_lines/ApioUserTest1@sip.netaxis.be/ HTTP/1.1 Host: example.com
Example response:
HTTP/1.1 200 OK Content-Type: "application/json" { "userId": "ApioUserTest1@sip.netaxis.be", "linePort": "lp_test_1@sip.netaxis.be", "firstName": "Test1", "lastName": "Test1", "phoneNumber": "+3225126778", "department": { "tenantId": "ApioSpTest", "groupId": "ApioGrpTest", "departmentName": "test_department_initial", "fullPathName": "test_department_initial" }, "active": true, "allowOrigination": true, "allowTermination": true, "order": 3 }
- Response JSON Object:
userId (string) – the userId of the user who has duplicated his line on this phone.
linePort (string) – the linePort of this extra line.
firstName (string) – the first name of the user who has duplicated his line on this phone.
lastName (string) – the last name of the user who has duplicated his line on this phone.
phoneNumber (string) – the phone number of the user who has duplicated his line on this phone.
department (string) – the department of the user who has duplicated his line on this phone.
active (boolean) – this extra line is enabled.
allowOrigination (boolean) – Originated calls from this extra line are allowed.
allowTermination (boolean) – Terminated calls to this extra line are allowed.
order (integer) – the order of the extra line.
- Status Codes:
200 OK – no error
- Statusocde 404:
the user has no extra lines linked to the main device, with possible sub-error codes:
8: NOT_FOUND_AT_NE
Configuration Information for the Additional Phones¶
In the POST API, when creating an additional phone, a device name and a line port will be generated.
The APIO behaviour is controlled by the following settings:
"APIO_OBJECT_CREATION": {
"GENERATED_ID_DATA": true
},
"AUTOMATIC_ID_RULES": {
"USER_EXTRA_DEVICE_NAME": "DP_{{user_id}}A{{extra_phone_id}}",
"LINE_PORT_USER_EXTRA_DEVICE": "LP_{{user_id}}A{{extra_phone_id}}@{{domain}}",
"USER_EXTRA_DEVICE_NAME_OVERWRITE": true,
"GENERIC_DEVICE_NAME_RULE": "DP_{{RND_36}}"
},
"DEVICE_TYPES_FOR_INTEGRATED_APPS": ["BroadWorks Communicator", "Business Communicator - Mobile", "Business Communicator - PC"],
"PATTERN_USER_EXTRA_OWN_DEVICE": "extra-own-device-%s",
"SEARCH_PATTERN_FOR_ID_IN_LINE_PORT": "A([0-9]*)@"
"EXTRA_PHONE_IDS_RESERVED_FOR_INTEGRATED_APPS" : [6, 7, 8],
"MAX_EXTRA_PHONE_ID_VALUE_FOR_PHONE": 10,
"DEVICE_NAME_MAX_LENGTH": 40,
There is one mandatory constraint on the format of the rule for the LINE_PORT_USER_EXTRA_DEVICE: the {{extra_phone_id} must be at the end of the value just before the @ and it must be separated from the previous variable by at least one fixed char. This is needed in order that the APIO can retrieve thanks to this the “extra_phone_id” from the Line Port as it would need the ones already created in order to validate new ones.
- Explanation of the parameters:
GENERATED_ID_DATA: APIO will enable the auto-generation of ids. Default is False, it must be set to have this feature working
USER_EXTRA_DEVICE_NAME: the formatting rule for the user extra device name. Default is “DP_{{user_id}}A{{extra_phone_id}}”.
FALLBACK_USER_EXTRA_DEVICE_NAME: the fallback formatting rule if the main one has failed (for example based on a phone number but the user has no phone number). Recommended to be based on the User ID as this one will always be present. None by default.
LINE_PORT_USER_EXTRA_DEVICE: the formatting rule for the line port. Default is “LP_{{user_id}}A{{extra_phone_id}}@{{domain}}”. It must contains the extra_phone_id.
FALLBACK_LINE_PORT_USER_EXTRA_DEVICE: the fallback formatting rule if the main one has failed (for example based on a phone number but the user has no phone number). Recommended to be based on the User ID as this one will always be present. It must contains the extra_phone_id. None by default.
SEARCH_PATTERN_FOR_ID_IN_LINE_PORT: A regex pattern that will be used to extract the extra_phone_id. from the linePort.
DEVICE_TYPES_FOR_INTEGRATED_APPS: the list of device of type APP. Default is [“BroadWorks Communicator”, “Business Communicator - Mobile”, “Business Communicator - PC”, “Connect - Mobile”, “Connect - Tablet”] (note “Connect - Tablet” has been added in 1.10.4)
PATTERN_USER_EXTRA_OWN_DEVICE: the pattern for the extra access device description (for internal user only) to identify if the requesting user owns that device (needed to delete it when deleting the user). It must contains “%s” as it will be replaced by the device id. Default is “extra-own-device-%s”.
EXTRA_PHONE_IDS_RESERVED_FOR_INTEGRATED_APPS: the list of extra phone ids that will bne reserved for Apps and therefore not available for additional regular phones. Default is an empty list.
MAX_EXTRA_PHONE_ID_VALUE_FOR_PHONE: the maximum value for the extra_phone_id. It could, but not mandatory, include the values for App. So in our example upper we have 1, 2, 3, 4, 5, 9, 10 avaiable for additional phones. Not defined by default. If is not present then APIO will aloows to create as much additional phones as the Application Server allows to do.
USER_EXTRA_DEVICE_NAME_OVERWRITE: if that name was already existing in APIO DB, it is replaced by this one (new in APIO 1.7.1), This is used both for device name and for the line port. Default in True. Should not be enabled if the names are using random parameters.
DEVICE_NAME_MAX_LENGTH: the maximum length for the deviceName. The default value is 40 and if set to 0 no length check is performed
GENERIC_DEVICE_NAME_RULE: a generic fallback auto-generation rule. This rule is used only when the device name excedes DEVICE_NAME_MAX_LENGTH
- note:
LINE_PORT_USER_EXTRA_DEVICE, FALLBACK_LINE_PORT_USER_EXTRA_DEVICE and SEARCH_PATTERN_FOR_ID_IN_LINE_PORT MUST be aligned in order that the linePort generated by one of the 2 rules can be analysed by the regex. It is putting some constraints on the possible values.
- In these rules the following variables can be used:
phone_number_e164: The phone number in E164 format
country_code: The country code of the phone number
national_no_0: The national number, without trailing 0, of the phone number
extra_phone_id: The extra phone ID
domain: the domain
tenant_id: the Tenant Id
group_id: the Group Id
user_id: the User part (aka left part of the User ID)