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.
This message flow shows a login flow using OAuth2 and 2FA. In that case the username and password are not verified by the PBX, but by an external ID provider. The username is taken from the ID token and sent from the PBX to the myApps client. Instead of the password that is unknown by the PBX and the myApps client, an ECDHE handshake is done in order to create a shared secret. That shared secret is used instead of the user's password.
The base message format consists only of the property mt.
{
"mt": string
}Sent by the client.
{
"mt": "CheckBuild",
"url": string,
"always": boolean
}CheckBuildResult should trigger a redirect in any case. undefined otherwise.
Sent by the PBX as a response to the CheckBuild message.
{
"mt": "CheckBuildResult",
"url": string,
"version": 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.
This message can be used to query the available authentication methods on the PBX. The PBX answers with the LoginInfoResult message.
{
"mt": "LoginInfo"
}Sent by the PBX.
This message is sent by the PBX as an answer to the LoginInfo message and contains the activated authentication methods.
Depending on the activated methods for login type "user" the client should display different elements in the login screen.
{
"mt": "LoginInfo",
"user": {
"digest": bool,
"ntlm": bool,
"oauth2": bool
},
"session": {
"digest": bool
}
}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
}When using Using OAuth2 the login message is only sent once. It does not contain the username and response parameter, but an additional ECDHE key share.
{
"mt": "Login",
"type": string,
"method": string,
"nonce": string,
"keyShare": 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>))For type "ntlm"
Hexstring(NtlmResponse(<username>,<password>))For method "oauth2"
undefined
Hexstring(ECDH(secp256r1, <private-key>, <Login.keyShare>, <LoginResult.info.keyShare>))or
Hexstring(ECDH(secp256r1, <private-key>, <Login.keyShare>, <Redirect.info.keyShare>))
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,
"url": 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
}<password> := Hexstring(ECDH(secp256r1, <private-key>, <Login.keyShare>, <LoginResult.info.keyShare>))
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
}<password> := Hexstring(ECDH(secp256r1, <private-key>, <Login.keyShare>, <Redirect.info.keyShare>))
Hexstring(SHA256(innovaphoneAppClient:redirect:<username>:<password>:<nonce>:<challenge>:<info>))
Sent by the client to cancel a started login with method "oauth2". The PBX responds with LoginResult with an error.
{
"mt": "LoginCancel"
}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"
}The PBX sends this message when it is turned off. The PBX terminates the connection after that message. The client should reconnect and start its normal login procedure using the same session.
{
"mt": "Disconnect"
}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,
"keyShare": string,
"alt": string,
"altHttp": string
}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.
Hexstring(ECDH(secp256r1, <private-key>, <Login.keyShare>, <LoginResult.info.keyShare>))or
Hexstring(ECDH(secp256r1, <private-key>, <Login.keyShare>, <Redirect.info.keyShare>))
host:port/module-name, e.g. standby.example.com:4433/PBX0host:port/module-name, e.g. standby.example.com:8080/PBX0{
"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,
"apis": {
string: object,
...
},
"wake": [string]
}Additional info about the properties of an app. This info is dynamic info from the app service.
{
"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
}