The myApps protocol is the WebSocket protocol used by the myApps web client to talk to the PBX.
MessagesThe following messages can be used without logging-in:
Login messages
The following messages are only allowed after successfully logging-in.
This message flow shows an attempt to login using session data from previous successful login. In this case the attempt fails with "Session expired" error. The following login with user credentials succeeds after a 2FA confirmation.
The base message format consists only of the property mt.
{
"mt": string
}Sent by the client.
{
"mt": "CheckBuild",
"url": string
}Sent by the PBX as a response to the CheckBuild message.
{
"mt": "CheckBuildResult",
"url": string,
"build": string,
"launcherUpdateBuild": string,
}Sent by the client to subscribe for UpdateRegister messages.
{
"mt": "SubscribeRegister"
}Sent by the PBX. Contains URLs for user registration and password resets to be displayed on the login page.
{
"mt": "UpdateRegister",
"signup": string,
"reset": string,
"profile": profile
}Sent by the client.
During the login procedure the Login message is sent twice. The first time it does not include any credentials and is responded with an Authenticate message including a challenge.
{
"mt": "Login",
"type": string,
"userAgent": string
}The second time it is sent with the actual login data that includes a user name and a response in the form of a digest.
{
"mt": "Login",
"type": string,
"method": string,
"username": string,
"nonce": string,
"response": string,
"userAgent": string
}If the authentication was successful the PBX will respond with LoginResult. If two-factor authentication is enabled the PBX will first send an Authorize and wait with the LoginResult until the session has been authorized over a second channel.
Hexstring(SHA256(innovaphoneAppClient:<type>:<domain>:<username>:<password>:<nonce>:<challenge>))
Hexstring(NtlmResponse(<username>,<password>))
Sent by the PBX as a response to the initial Login message.
After the client sent the first Login message without credentials, the PBX sends the Authenticate message. It includes the parameters (method, challenge and domain) that are needed to calculate the fields for the second Login message for the actual authentication.
{
"mt": "Authenticate",
"type": string,
"method": string,
"domain": string,
"challenge": string
}Sent by the PBX as a response to the second Login message.
This message is used together with two-factor authentication with the "user" type login. At this point the user password was successfully validated by the PBX but the user needs to complete the second factor of the authentication on a different channel. If that has happened the PBX proceeds by sending the LoginResult message.
{
"mt": "Authorize",
"code": integer
}Sent by the PBX as a response to the second Login message.
The message indicates that the login was successful and includes additional information for the client.
{
"mt": "LoginResult",
"info": Info,
"digest": string
}Hexstring(SHA256(innovaphoneAppClient:loginresult:<domain>:<username>:<password>:<nonce>:<challenge>:<info>))
If the login failed the message contains error information instead.
{
"mt": "LoginResult",
"error": integer,
"errorText": string
}Sent by the PBX as a response to the Login message.
The message indicates that the login was successful, but the user is on a different PBX, so a redirect should be done.
{
"mt": "Redirect",
"info": Info,
"digest": string
}Hexstring(SHA256(innovaphoneAppClient:redirect:<username>:<password>:<nonce>:<challenge>:<info>))
Sent by the client to logout the current session.
{
"mt": "Logout"
}Sent by the PBX if the current session was logged-out. This could be as a response to the Logout message or unsolicitated. The client should delete all information that is related to the session.
{
"mt": "LogoutResult"
}The login was accepted by a standby PBX before. But now the original PBX is back. The PBX terminates the connection after that message. The client should reconnect and start its normal login procedure using the same session.
{
"mt": "StandbyBack"
}Sent by the PBX. Contains the details of the logged-in user.
{
"mt": "UpdateUser",
"user": User
}Sent by the PBX if a login-session for the user has been added. If the session has the needsAuthorization flag set, the client should display the code to the user and ask if the session should be authorized. Depending on the decision by the user the AuthorizeSession or DeleteSession should be sent.
{
"mt": "SessionAdded",
"id": string,
"info": SessionInfo
}Sent by the PBX if a login-session for the user was updated. If the session has the needsAuthorization flag set, the client should display the code to the user and ask if the session should be authorized. Depending on the decision by the user the AuthorizeSession or DeleteSession should be sent.
{
"mt": "SessionUpdated",
"id": string,
"info": SessionInfo
}Sent by the PBX if a login-session for the user has been deleted. Connections in the context of the deleted session will receive the LogoutResult message afterwards.
{
"mt": "SessionDeleted",
"id": string
}Sent by the client to complete two-factor authentication for sessions that are waiting for the second factor. Only own sessions (of the same PBX user) can be authorized.
{
"mt": "AuthorizeSession",
"id": string
}Sent by the client to reject a session that is waiting for second factor authentication or to remotely logout a session. Only own sessions (of the same PBX user) can be deleted.
{
"mt": "DeleteSession",
"id": string
}Sent by the client to store parameters about the session in the PBX.
{
"mt": "SetSessionInfo",
"token": string,
"wake": [string]
}Sent by the client to subscribe for UpdateApps messages. The subscription is valid until a LogoutResult message is received.
{
"mt": "SubscribeApps"
}Sent by the PBX. Contains information about all the apps that the user has access to.
{
"mt": "UpdateApps",
"apps": [App],
"deviceApps": [App],
"selected": string
}Sent by the client to store the apps the user selected for his or her home screen.
{
"mt": "SetApps",
"home": string
}Sent by the PBX. An event has occurred that requires the client to start some apps. For example this is needed on incoming phone calls when the phone app is not running yet. The client starts an app if
{
"mt": "Wake",
"type": string,
"hw": string,
"incoming": boolean
}Sent by the client get an authentication for a given app.
{
"mt": "AppGetLogin",
"src": string,
"app": string,
"challenge": string
}Sent by the PBX as a response to the AppGetLogin message. It contains the info that shall be presented to the app service to prove the successful login.
{
"mt": "AppGetLoginResult",
"src": string,
"domain": string,
"sip": string,
"guid": string,
"dn": string,
"pbxObj": string,
"app": string,
"info": AppLoginInfo,
"digest": string,
"salt": string,
"key": string,
"error": unsigned,
"errorText": string
}<app>:<domain>:<sip>:<guid>:<dn>:<info>:<challenge>:<password>Sent by the client to publish the user activity (active, inactive) in the im: presence at the user object.
{
"mt": "SetUserActivity",
"inactive": boolean
}Sent by the client to publish the users activity and note in the tel: presence at the user object.
{
"mt": "SetOwnPresence",
"activity": string,
"note": string
}Sent by the PBX if the own presence has changed.
{
"mt": "UpdateOwnPresence",
"presence": [Presence]
}Starts a presence subscription for a given SIP URI or phone number. The PBX will start sending UpdatePresence messages for that endpoint.
{
"mt": "SubscribePresence",
"sip": string,
"num": string
}Stops a presence subscription for a given SIP URI or phone number. The PBX will stop sending UpdatePresence messages for that endpoint.
{
"mt": "UnsubscribePresence",
"sip": string,
"num": string
}Send by the PBX if the presence of the monitored endpoint has changed.
{
"mt": "UpdatePresence",
"sip": string,
"num": string,
"up": boolean,
"ep": {
"sip": string,
"dn": string,
"num": string,
"email": string,
"url": string,
"type": string
},
"presence": [Presence]
}Starts a dialog info subscription for a given SIP URI or phone number. The PBX will start sending DialogInfo messages for that endpoint.
{
"mt": "SubscribeDialog",
"sip": string,
"num": string
}Stops a dialog info subscription for a given SIP URI or phone number. The PBX will stop sending DialogInfo messages for that endpoint.
{
"mt": "UnsubscribeDialog",
"sip": string,
"num": string
}Sent by the PBX if a call of the monitored endpoint has changed its state. Note that the client needs to keep track of the current active call. If a DialogInfo for an unknown call id is received the call needs to be added to the local state. If the deleted flag is set, the calls must be removed again from the local state.
{
"mt": "DialogInfo",
"sip": string,
"num": string,
"callId": string,
"confId": string,
"remote": {
"sip": string,
"dn": string,
"num": string
},
"state": {
"name": string,
"outgoing": boolean,
"hold": boolean,
"held": boolean,
"waiting": boolean
},
"deleted": boolean
}{
"domain": string,
"sip": string,
"guid": string,
"dn": string,
"num": string,
"email": string
}The info object is generated by the PBX. It contains more information about the user.
{
"host": string,
"domain": string,
"sip": string,
"guid": string,
"dn": string,
"num": string,
"email": string,
"session": Session
}The info object is generated by the PBX when a user logs in. It contains more information about the user and optional information about the session that has been created during the login.
{
"usr": string,
"pwd": string
}During logins of type "user" a persistent session is created. This structure contains the encrypted credentials of this session. They are used for encrypting selected attributes of messages. Also, they are used for subsequent logins of type "session".
Hexstring(RC4(innovaphoneAppClient:usr:<nonce>:<password>, <session-username>))
Hexstring(RC4(innovaphoneAppClient:pwd:<nonce>:<password>, <session-password>))
{
"id": string,
"current": boolean,
"userAgent": string,
"timestamp": unsigned,
"code": unsigned,
"needsAuthorization": boolean
}An object representing a persistent login session of the user.
{
"name": string,
"title": string,
"text": string,
"url": string,
"inline": boolean,
"website": boolean,
"info": AppInfo
}An object representing an app.
{
"hidden": boolean,
"presence": boolean/string,
"apis": {
string: object,
...
},
"wake": [string]
}Additional info about the properties of an app. This info is dynamic info from the app service.
true The app answers presence subscriptions. The client should establish presence subscriptions for home screen items of that app to retrieve presence info like badge counts.string If the app does not provide the presence itself, but a different SIP URI should be monitored, it can be specified as a string.undefined If the client should not do a presence subscription for the app.
{
"appobj": string,
"appdn": string,
"appurl": string,
"cn": string,
"unlicensed": boolean,
"apps": [AppLoginInfoApp]
}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
}{
"contact": string,
"status": string,
"activity": string,
"note": string
}