com.innovaphone.devices

The com.innovaphone.devices services api enables apps to use the whole websocket communication API from devices. E.g. the users App uses this functionality on the C++ part of the App for provisioning.
All messages are send as JSON strings and must use the mt property which is the message type.
You can also use this API to execute HTTP requests on connected devices, so called sysclients.

Summary

GetService
AppLogin
Communication with connected Sysclients
Messages send to the service
Messages received by the service

GetService

See services for the information how to exactly work with IServices!


        IServicesApi * services = ...;    // must be retrieved within the PBX websocket connection PbxInfo message to the app service.
        IService * service = services->GetService("com.innovaphone.devices");
        class IAppWebsocketClient * awsClient = IAppWebsocketClient::Create(iomux, this, tcpSocketProvider, tlsSocketProvider, dns, log);
        awsClient->Connect(service->GetWebsocketUrl(), service->GetName(), session->services->CreateAuthenticator());

AppLogin

If you do not work with IServices and you know the intance password of the Devices instance, you can also use the standard AppLogin mechanism to login to Devices.
In a multi domain environment in Devices, you're automatically admin with access to all domains, if you login with the instance password and the instance domain.
If you login with the domain password from a domain different than the instance domain, you just have access to your own domain or domains, where you got access to.

Communication with connected Sysclients

After having successfully established an AppWebsocket connection to Devices and queried the session key with the GetUserInfo message, you can start communicating with connected devices. As you are already authenticated to Devices, you do not need to authenticate the following requests anymore!
The URL is always built after the same scheme:

https://domain.com/domain/devices-instance/passthrough/SERIAL/SESSION-KEY/...

SERIAL is a MAC address, e.g. 009033020202 and the session key is a GUID like 0e6ff4c7-7a88-40c4-98eb-8c91903933e6.
The part before the passthrough can be retrieved from your Devices App object URL inside the PBX.
The session key is just valid as long as the AppWebsocket session is open.

Messages send to the service

GetUserInfo
GetProvisioningCategories
GetProvisioningCode
GetProvisionedDevice
GetDomains
GetDevices
GetFilteredDevices
GetDevicesConfigs
GetDevicesConfig
Not yet documented messages

Messages received by the service

DeviceProvisioned
DomainEdited
DomainDeleted
DomainAdded
DeviceUpdate
DeviceAdded
DeviceRemoved

GetUserInfo

Query the login info of the logged in user.

Parameters

string src Will be echoed in the result message (optional).

GetUserInfoResult

The result message for the GetUserInfo request.

Parameters

string key The session key which is used to talk to devices.
boolean admin If true, the user has access to all domains.
string src Echoed (optional).

GetProvisioningCategories

Retrieves all provisioning categories. With type='PHONE' you can just retrieve provisioning categories suitable for phones (device configurations Phone/Analog Phone exist).

Parameters

ulong64 domainId The domain ID (optional). If not given, the domain of the currently logged in user is used.
string type Device types: VA|GW|PHONE|DECT|APP_PLATFORM.
string src Will be echoed in the result message (optional).

GetProvisioningCategoriesResult

The result message for the GetProvisioningCategories request.

Parameters

array categories An array of category objects.
boolean last If true, no more GetProvisioningCategoriesResult messages are to be expected, otherwise more will follow with further categories.
string src Echoed (optional).
string error Set to an error code if an error happened (optional).

Category object

ulong64 id A unique ID for this category.
ulong64 domainId The domain ID of this category.
string name The name of the category.
boolean config If true, this category is used for provisioning and device configurations.
Example

{
    "mt":"GetProvisioningCategories",
    "last":true,
    "categories":[
        {
            "id":1,
            "name":"Cat1",
            "domainId":2,
            "config":true
        }
    ]
}

GetProvisioningCode

Generates a new provisioning code and triggers a DeviceProvisioned message on provisioning afterwards.

Parameters

ulong64 domainId The domain ID (optional). If not given, the domain of the currently logged in user is used.
string category The category name.
string sip The SIP name of the provisioning user (optional).
boolean rollout If true, the provisioning code will be valid for 7 days, otherwise 15 minutes (optional, default false).
string src Echoed (optional).
boolean administrative If true, the provisioned device will get the domain password as administrative password if the domain checkword to set these passwords is checked. (optional, default false)

GetProvisioningCodeResult

The result message for the GetProvisioningCode request.

Parameters

string code The generated code.
ulong64 validUntil A UTC unixtimestamp until the code is valid.
string src Echoed (optional).
string error An error string if an error happened (optional).

GetProvisionedDevice

Gets the device provisioned with a certain code. This is useful if a provisioning was interrupted and might have been finished in the meantime.
If not yet finished, a DeviceProvisioned message will be triggered on the actual provisioning.

Parameters

ulong64 domainId The domain ID (optional). If not given, the domain of the currently logged in user is used.
string code The code to be checked.
string src Echoed (optional).

GetProvisionedDeviceResult

The result message for the GetProvisionedDevice request.

Parameters

object device A device object. Just given, if provisioning with the requested code was already done.
string code The provisioning code.
string src Echoed (optional).
string error An error string if an error happened (optional).

Device object

number id A unique ID for this device.
string hwId The hardware ID.
string name The name of the device, if configured.
number domainId The domain ID.
string product The product name, e.g. IP811.
string version The software and hardware version, e.g. 13r1 dvl [13.A110/13A146/200]
string type The hardware type (possible types are GW,VA,PHONE,DECT,APP_PLATFORM).
boolean pbxActive If true, the PBX is enabled on this device.
boolean online If true, this device is currently online.
boolean hasLeaseLicenses If true, this device has rental licenses.
boolean other If true, this device is no innovaphone device, but e.g. a Yealink phone.
array ethIfs An array of ethernet objects.
string uri The URI under which this device is accessible during the current session (not always set!, e.g. not in GetDevicesResult).

Ethernet object

string if Interface name.
string ipv4 The IPv4 address (optional).
string ipv6 The IPv6 address (optional).
Example

{
    "mt":"GetProvisionedDeviceResult",
    "code": "123123123123",
    "device":[
        {
            "id":1,
            "hwId":"0090334100be",
            "name":"Kari2",
            "domainId":2,
            "product":"IP811",
            "version":"13r1 dvl [13.A110/13A146/200]",
            "type":"GW",
            "pbxActive":true,
            "online":true
        }
    ]
}

GetDomains

Gets domains.
The answer might be sent multiple times until the last property is set.

Parameters

boolean recvUpdates set this flag, if you want to get messages over domain updates (DomainAdded, DomainDeleted, DomainEdited) (optional).
string src Echoed (optional).

GetDomainsResult

The result message for the GetDomains request.

Parameters

array domains An array of domain objects.
boolean last If last is set, no further GetDomainsResult messages will be received.
string src Echoed (optional).
string error An error string if an error happened (optional).
Example

{
    "mt": "GetDomainsResult",
    "last": true,
    "domains": [{
            "id": 1,
            "name": "domain.com",
            "hasRentalProducts": true,
            "deployAdminPasswords": true,
            "isInstanceDomain": true,
            "categories": [{
                    "id": 1,
                    "name": "Test",
                    "config": false
                }, {
                    "id": 2,
                    "name": "Test2",
                    "config": false
                }
            ]
        }
    ]
}
    

Domain object

number id A unique ID for this domain.
string name The name of the domain.
boolean hasRentalProducts If true, rental software or hardware is used within this domain.
boolean deployAdminPasswords If true, the domain password is deployed to all devices within this domain.
boolean isInstanceDomain If true, this is the domain which matches to the configured domain of the Devices instance in the AP Manager.
array categories An array of category objects.

Category object

number id A unique ID for this category.
string name The name of the category.
boolean config If true, this category is used as provisioning category for device configurations.

GetDevices

Gets devices with certain filters.
The answer might be sent multiple times until the last property is set.

Parameters

boolean recvUpdates set this flag, if you want to get messages over device updates (DeviceAdded, DeviceRemoved, DeviceUpdate) (optional).
boolean unassigned set this flag, if you want to get devices which are not assigned to a domain (DeviceAdded, DeviceRemoved, DeviceUpdate) (optional).
string domainIds A comma separated string with ulong64 domainIds, e.g. "10,12". Just devices are returned within these domains (optional).
string categories A comma separated string with category names, e.g. "test1,Test 2". Just devices are returned with these categories (optional).
string subcategories A comma separated string with category names, e.g. "test1,Test 2". Just devices are returned with these subcategories in addition to categories (optional).
string src Echoed (optional).

Note

If you do not set domainIds, categories and unassigned, you will get all devices. If you just set unassigned, you will just get unassigend but if you set domainIds in addition, you will get unassigned and devices within domains.
Example

{
    "mt": "GetDevices",
    "recvUpdates": true,
    "domainIds": "1",
    "categories": "",
    "subcategories": "",
    "unassigned": true
}
    

GetDevicesResult

The result message for the GetDevices request.

Parameters

array devices An array of device objects.
boolean last If last is set, no further GetDevicesResult messages will be received.
string src Echoed (optional).
string error An error string if an error happened (optional).
Example

{
    "mt": "GetDevicesResult",
    "devices": [{
            "id": 0,
            "hwId": "009033280177",
            "domainId": 0,
            "product": "IP111",
            "version": "13r2 sr2 [13.6146/136146/400]",
            "type": "PHONE",
            "pbxActive": false,
            "online": true,
            "ethIfs": [{
                    "if": "ETH0",
                    "ipv4": "172.16.136.105",
                    "ipv6": "2002:91fd:9d07:136:290:33ff:fe28:177"
                }
            ]
        }
    ],
    "last": true
}
    

GetFilteredDevices

Gets devices with certain filters.
The answer might be sent multiple times until the last property is set.

Parameters

ulong64 domainId Search within this domain (optional). If not given, the domain of the AppWebsocket login is used for searching.
boolean justFxs Just return devices with FXS interfaces (optional).
array types An array of strings to filter for device types. Possible types: VA|GW|PHONE|DECT|APP_PLATFORM (optional)
string hwIds A comma separated string with hardware ids (optional), a hwId is e.g. 009033090909.
string src Echoed (optional).

GetFilteredDevicesResult

The result message for the GetFilteredDevices request.

Parameters

array devices An array of device objects.
boolean last If last is set, no further GetDevicesResult messages will be received.
string src Echoed (optional).
string error An error string if an error happened (optional).

GetDeviceConfigs

Gets device configurations of a domain.
The answer might be sent multiple times until the last property is set.

Parameters

ulong64 domainId Search within this domain (optional). If not given, the domain of the AppWebsocket login is used for searching.
boolean recvUpdates set this flag, if you want to get messages over device config changes (DeviceConfigAdded, DeviceConfigDeleted, DeviceConfigEdited) (optional).
string src Echoed (optional).

GetDeviceConfigsResult

The result message for the GetDeviceConfigs request.

Parameters

array configs An array of device config objects without their configuration values.
boolean last If last is set, no further GetDeviceConfigsResult messages will be received.
string src Echoed (optional).
string error An error string if an error happened (optional).

Device configuration object

A device configuration object always has common fields. Every device configuration type has its own fields in addition.

Common fields

number id A unique ID for this device config.
number domainId The domain ID of this device config.
string desc The description of this device config (optional).
string type The configuration type, one of ALARM_SERVER | EXPERT | FXS_PHONE | MEDIA | NTP | PHONE | TLS_PROFILE .
array categories An array of category objects. If array is empty, the configuration is valid for all devices independent of their category.

Fields type ALARM_SERVER

string url The URL of an alarm server (optional).
string logUrl The URL of a logging server (optional).
string logUser The user name used for HTTP authentication (optional).
string logPassword The password used for HTTP authentication, encrypted with the AppWebsocket encryption function (optional).
string seed The seed used to encrypt the password (optional).
boolean setLogUrl If setLogUrl is set, also empty logging URLs are set.

Note: the logPassword field is transferred encrypted to 3rd party sysclients inside the configuration message! Instead of seed, use logSeed and see for how to decrypt it!

Fields type EXPERT

string script The update script. As this field can exceed 64kb, its value is transferred with GetDeviceConfigValueResult.

Note: the script field is not transferred to 3rd party sysclients inside the configuration message!

Fields type FXS_PHONE and PHONE

string gk1 The primary gatekeeper (optional).
string gk2 The secondary gatekeeper (optional).
string gkId The gatekeeper identifier (optional).
string coder One of G711A | G711u | G722 | OPUS-NB | OPUS-WB.
dword frameSize Framesize [ms], 20 - 80ms (optional).
boolean exclusive Exclusive (optional).
boolean fax Fax device (T.38 on, featurecodes off) (optional, just FXS_PHONE).
boolean setRecordingUrl If set, the recording URL is set (optional).
boolean audioOnly Audio onle (optional, just PHONE).
boolean noCtHookOn No transfer on hang up (optional, just PHONE).
boolean protectCfg Protect configuration at phone (optional, just PHONE).
boolean allowUserCfg Allow user settings at phone (optional, just PHONE).
boolean hideCompleteCfg Hide complete configuration at phone (optional, just PHONE).
boolean hideAdminCfg Hide administration configuration at phone (optional, just PHONE).
boolean silenceComp Silence compression (optional).
boolean noDtmfDetect No DTMF detection (optional).
boolean noPhysicalLocation No physical location (optional).
string srtpKey A string representing a number, see SRTP key exchange.
string srtpCipher A string representing a number, see SRTP ciphers.
string recordingUrl The recording URL (optional).
int dialTone The Dial tone, value from 0 - 26, see dial tones.

Fields type MEDIA

string stunServer STUN server (optional).
string turnServer TURN server (optional).
string turnUser TURN username (optional).
string turnPassword The password used for TURN authentication, encrypted with the AppWebsocket encryption function (optional).
string seed The seed used to encrypt the password (optional).
string tosRtp TOS priority - RTP data. A string represending a hex value between 0x00 and 0xff (optional).
string tosSig TOS priority - signaling. A string represending a hex value between 0x00 and 0xff (optional).
boolean setRtpPorts If set, the RTP ports are sent (optional).
dword rtpFirst First UDP-RTP port, 2052 - 65534 (optional).
dword rtpNum Number of RTP ports, 128 - 16384 (optional).
boolean setNatPorts If set, the NAT ports are sent (optional).
dword natFirst First UDP-NAT port, 2052 - 65534 (optional).
dword natNum Number of NAT ports, overlapping of NAT and RTP isn't allowed (optional).

Note: the turnPassword field is transferred encrypted to 3rd party sysclients inside the configuration message! Instead of seed, use turnSeed and see for how to decrypt it!

Fields type NTP

string ntp1 First NTP server.
string ntp2 Second NTP server.
string tz Timezone string, e.g. "CET-1CEST-2,M3.5.0/2,M10.5.0/3".

Fields type TLS_PROFILE

string profile Must be one of normal | fast | secure | strict.

SRTP key exchange

0SDES-DTLS
1DTLS-SDES
2SDES
3DTLS
4No encryption

SRTP ciphers

0AES128/32
1AES128/80
2AES192/32
3AES192/80
4AES256/32
5AES256/80

Dial tones

0EUROPE-PBX
1EUROPE-PUBLIC
2US
3UK
4ITALY-PUBLIC
5CZECH-PBX
6CZECH-PUBLIC
7SWEDEN
8FRANCE
9SWISS
10ITALY-PBX
11BELGIUM
12NETHERLANDS
13NORWAY
14DENMARK
15GERMANY
16SPAIN
17FINLAND
18AUSTRIA
19IRELAND
20AUSTRALIA
21NEWZEALAND
22MALAYSIA
23TURKEY
24RUSSIA
25SOUTH AFRICA
26BRAZIL

GetDeviceConfig

Gets a specific device configuration.

Parameters

ulong64 domainId Device configuration of this domain (optional). If not given, the domain of the AppWebsocket login is used for searching.
ulong64 id The id of the device configuration.
string src Echoed (optional).

GetDeviceConfigValueResult

A GetDeviceConfig message may trigger 0 ... n GetDeviceConfigValueResult messages before you receive the final GetDeviceConfigResult message, as a configuration value may exceed the maximum size of a single JSON message.
You must concatenate all values received for the same name to build the final value.

Parameters

string name The name of the configuration value.
string value The value itself.
string src Echoed (optional).

GetDeviceConfigResult

The result message for the GetDeviceConfig request.

Parameters

object config A device config object with its configuration values.
string src Echoed (optional).
string error An error string if an error happened (optional).

FurtherMessages

As long as not all messages are documented here, you can always open the Devices App and your browser console (F12) and take a look at the sent and received messages to the Devices App!

DeviceProvisioned

Message from the service if a device has been provisioned after the GetProvisioningCode request.

Parameters

object device A device object. Just given, if provisioning with the requested code was already done.
string code The provisioning code.
string src Echoed (optional).

DomainEdited

Message from the service if a domain has been edited. This message is just triggered if a GetDomains request with recvUpdates true has been send before.

Parameters

object domain A domain object.

DomainDeleted

Message from the service if a domain has been deleted. This message is just triggered if a GetDomains request with recvUpdates true has been send before.

Parameters

ulong64 id The id of the deleted domain.

DomainAdded

Message from the service if a domain has been added. This message is just triggered if a GetDomains request with recvUpdates true has been send before.

Parameters

object domain A domain object.

DeviceUpdate

Message from the service if a device has been updated. This message is just triggered if a GetDevices request with recvUpdates true has been send before.

Parameters

object device A device object.

DeviceAdded

Message from the service if a device has been added. This message is just triggered if a GetDevices request with recvUpdates true has been send before.

Parameters

object device A device object.

DeviceRemoved

Message from the service if a device has been removed. This message is just triggered if a GetDevices request with recvUpdates true has been send before.

Parameters

object device A device object.