The AppWebsocket protocol is the base protocol for all app-related communication. It is used for websocket connections
It provides the following services:
{
"mt": string,
"api": string,
"src": string
}The base message format consists of the three properties mt, api and src.
This sample message flow shows an example of a websocket connection to an app object on the PBX.
The app object assumed to have following sample configuration:
In the example following operations are performed:
{
"mt": "AppChallenge"
}With this message the client requests a challenge for the login. The challenge is a random string which is included in the digest calculation of the login together with shared secret (password) and other parameters. With this mechanism an an adequately random string, replay attacks are not possible.
{
"mt": "AppChallengeResult",
"challenge": string
}Returns the challenge to the client.
{
"mt": "AppLogin",
"app": string,
"domain": string,
"sip": string,
"guid": hexstring,
"dn": string,
"digest": hexstring,
"pbxObj": string,
"info": Info
}The login message, which contains parameters, which are included in the digest calculation, so that they cannot be changed by an intermediate system.
The digest calculated to verify the knowledge of the shared secret. It is calculated as SHA256 hash over the string:
<app>:<domain>:<sip>:<guid>:<dn>:<info>:<challenge>:<password>In case no Info parameter is provided as part of the AppLogin message the string for hash calculation should be following:
<app>:<domain>:<sip>:<guid>:<dn>:<challenge>:<password>Following examples can be used as test vectors for your implementation of the digest calculation.
Example 1:
Password on the "pbxadminapi" app object is "pwd". No info object is provided.
{
"app": "pbxadminapi",
"digest": "a205299ed2ef2786c311e0be1b14db343f2cadd906a6ae7b564eee34bda5e9a1",
"dn": "",
"domain": "",
"guid": "",
"mt": "AppLogin",
"sip": ""
}pbxadminapi:::::0123456789abcdef:pwd
Example 2:
Password on the "pbxadminapi" app object is "pwd". An empty info object is provided.
{
"app": "pbxadminapi",
"digest": "57b23fe824b9222a7ac879597cb509bcdc865a1bfeb057d9d12118cef0c3ba34",
"dn": "",
"domain": "",
"guid": "",
"info": {},
"mt": "AppLogin",
"sip": ""
}pbxadminapi:::::{}:0123456789abcdef:pwd
Example 3:
Password on the "pbxadminapi" app object is "pwd". An info object is provided.
{
"app": "pbxadminapi",
"digest": "96db3c3f657230c2b68194becc6d2a77f05de9f79f01fc81e9ca0fb196b10d9d",
"dn": "",
"domain": "",
"guid": "",
"info": {
"cn": "Test User"
},
"mt": "AppLogin",
"sip": ""
}pbxadminapi:::::{"cn":"Test User"}:0123456789abcdef:pwd
Example 4:
Password on the "pbxadminapi" app object is "pwd". An info object is provided. The parameters for dn, domain, guid and sip are provieded.
{
"app": "innovaphone-users",
"digest": "ef1b811ffaa8f9255c39c653d8fb26b4687b2d8c4d9ac91b4821bff6bae3ff44",
"dn": "Administrator User",
"domain": "example.com",
"guid": "0123456789abcdef0123456789abcdef",
"info": {
"appobj": "users",
"apps": [
{
"name": "users"
},
{
"name": "profile"
}
],
"appurl": "https://1.2.3.4/example.com/usersapp/innovaphone-users",
"unlicensed": true
},
"mt": "AppLogin",
"pbxObj": "users",
"sip": "administrator"
}innovaphone-users:example.com:administrator:0123456789abcdef0123456789abcdef:Administrator User:{"appobj":"users","apps":[{"name":"users"},{"name":"profile"}],"appurl":"https://1.2.3.4/example.com/usersapp/innovaphone-users","unlicensed":true}:0123456789abcdef:pwdAn optional JSON Object with additional information. For the digest calculation this must be JSON encoded without any unnecessary white space and no unnecessary escaping. This is the encoding done by the json_io library of the SDK, by the Javascript JSON.stringify function or by a PHP function json_encode($input, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES).
Possible properties are:
testmode is set to true if the gateway or the IPVA running the PBX is in the Test-Mode. This property can be used to detect the active Test-mode of the connecting PBX in the App Service.Example for an info object:
{
"appobj": "sampleapp",
"appdn": "sampleapp",
"appurl": "https://ap.example.com/sampleapp/acme-sampleapp",
"pbx": "master",
"cn": "sampleapp",
"testmode": true,
"apps": [
{
"name": "otherapp",
"dn": "otherapp"
}
]
}{
"mt": "AppLoginResult",
"ok": bool
}Response to AppLogin. If the login was successful, the property ok is present with a value of true;
{
"mt": "CheckBuild",
"url": string
}Used to verify that the App loaded in the browser has the current version. A mismatch can happen when the App is loaded from a cache on the client side.
{
"mt": "CheckBuildResult",
"url": string
}Used to send back the current URL.
{
"mt": "AppInfo",
"app": string
}After login to an App Service, this message is used to request more information. The PBX uses this message for api information stored at the App Object in the PBX. This way the myApps client knows the Apis availabe and can load the App when the Api is requested by another App
{
"mt": "AppInfoResult",
"info": AppInfo,
"seviceInfo": AppServiceInfo,
"deviceapp": string
}An Json object with information about the App Service is returned
{
"mt": "PbxInfo",
"domain": string,
"pbx": string,
"pbxDns": string,
"apis": [ string ],
"version": string,
"build": string
}This messages is sent by the PBX app object on outgoing websocket connections directly after receiving the AppLoginResult message from the app service. It contains certain information about the PBX and the PBX APIs that the app service can use on that connection.
{
"appobj": string,
"appdn": string,
"appurl": string,
"cn": string",
"unlicensed": bool,
"lics": unsigned,
"apps": [App,...]"
}The info object is generated by the PBX when the App is requesting a login for an App Service. It contains more information about the user.
{
"name": string
}{
"hidden": bool,
"apis": object
}Info about the App Service