com.innovaphone.devices

The com.innovaphone.devices services api enables apps to use the whole websocket communication API from devices. 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.

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 GetLoginInfo message, you can start communicating with connected devices.
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

GetLoginInfo
GetProvisioningCategories
GetProvisioningCode
GetProvisionedDevice
Not yet documented messages

Messages received by the service

DeviceProvisioned

GetLoginInfo

Query the login info of the logged in user.

Parameters

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

GetLoginInfoResult

The result message for the GetLoginInfo 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).

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, a DeviceProvisioned message will be triggered later.

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.
string uri The URI under which this device is accessible during the current session.
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
        }
    ]
}

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