Push app protocol

The protocol described in this article is used between the push object in the PBX and an external push service. It's purpose is to trigger push notifications for smartphone apps on events inside the PBX. Currently those are the following:

Incoming calls
Chats
Two-factor authorization requests

The PBX triggers pushes for a user only if one or more push tokens are stored in sessions at the corresponding user object that have a flag that matches the event.

innovaphone uses that mechanism to send push notifications from customer PBXes to the innovaphone push service (services.innovaphone.com). The push service triggers actual push notifications for myPBX and myApps for iOS and Android. However the same mechanism can be used to integrate third-party smartphone apps that need to be notified about events in the PBX.

The protocol is based on AppWebsocket. The push object establishes an outgoing appwebsocket connection to the configured URL and authenticates using the configured password. The push service needs to implement the server side of the appwebsocket protocol including authentication. This document only describes the push specific messages that are exchanged after authentication.

Protocol messages

PushNotifyPost

Sends a push notification for a user identified by his or her push token.

{
    "mt": "PushNotifyPost",
    "token": string
}

token: The push token of the user

Note that we currently don't send any payload. In the future we might add an event type and detailed payload data.

PushNotifyPostResult

Answer from the push service to a PushNotifyPost message.

{
    "mt": "PushNotifyPostResult",
    "err": string,
    "info": string
}

err

An error string that is only present if an error occurred. This innovaphone push service currently defines the following errors.

UnknownApp
Malformed
Uninstalled
DatabaseErr
ApnError
ApnUnresolved
ApnShutdown
ApnSocketLost
ApnSocketError
ApnConnectFailed
ApnConnectReject
ApnTlsHandshake
ApnProcessingErr
ApnMissingToken
ApnMissingTopic
ApnMissingPayload
ApnTokenSize
ApnTopicSize
ApnPayloadSize
ApnInvalidToken
ApnProtocolErr
ApnServiceDown
GcmError
GcmUnresolved
GcmShutdown
GcmSocketLost
GcmSocketError
GcmConnectFailed
GcmReject
GcmTlsHandshake
GcmStreamBroken
GcmUnhandledErr
GcmHttpFailed
GcmBadRequest
GcmAuthentication
GcmNotFound
GcmServerError
GcmHttpError
GcmMissingReg
GcmInvalidReg
GcmNotRegistered
GcmPackageName
GcmSenderId
GcmMessageTooBig
GcmInvalidKeyword
GcmInvalidTtl
GcmTimeour
GcmDeviceRate
GcmTopicsRate
GcmApnCredential

Note that the error string is only for debugging purposes. The innovaphone PBX does not interpret the individual strings.

info

Additional debugging information, not interpreted by the PBX.

Protocol example

Login procedure

    {"mt":"AppChallenge"}

    {"mt":"AppChallengeResult","challenge":"577fb2b83962c53a"}

    {"mt":"AppLogin","sip":"push","guid":"13192b1d681c5e013aa40050569751d2","dn":"Push","digest":"909a756af923bfe2cd1acfc32a41a816b62ed4c435f5c505e112491b3f6de7de","domain":"pbx.example.com/master","app":"ws","info":{"appobj":"push","appurl":"https://services.innovaphone.com/push/ws","cn":"Push","unlicensed":true}}

    {"mt":"AppLoginResult","ok":true}

Push notification

    {"mt":"PushNotifyPost","src":"5","token":"xxxxxxxxx"}

    {"mt":"PushNotifyPostResult","src":"5"}