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 and url value as seed (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 and turnServer value as seed(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
0 | SDES-DTLS |
1 | DTLS-SDES |
2 | SDES |
3 | DTLS |
4 | No encryption |
SRTP ciphers
0 | AES128/32 |
1 | AES128/80 |
2 | AES192/32 |
3 | AES192/80 |
4 | AES256/32 |
5 | AES256/80 |
Dial tones
0 | EUROPE-PBX |
1 | EUROPE-PUBLIC |
2 | US |
3 | UK |
4 | ITALY-PUBLIC |
5 | CZECH-PBX |
6 | CZECH-PUBLIC |
7 | SWEDEN |
8 | FRANCE |
9 | SWISS |
10 | ITALY-PBX |
11 | BELGIUM |
12 | NETHERLANDS |
13 | NORWAY |
14 | DENMARK |
15 | GERMANY |
16 | SPAIN |
17 | FINLAND |
18 | AUSTRIA |
19 | IRELAND |
20 | AUSTRALIA |
21 | NEWZEALAND |
22 | MALAYSIA |
23 | TURKEY |
24 | RUSSIA |
25 | SOUTH AFRICA |
26 | BRAZIL |
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
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
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
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
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