Handling PUSH-notifications

Configuring the application

To be able to send APNS notifications to Apple servers or GCM notifications to Google servers, application certificates (APNS) or an application key (GCM) must be specified in the application settings.

Subscribing to notifications

To subscribe to notifications, the client must invoke the account.registerDevice query, passing in token_type and token as parameters that identify the current device. It is useful to repeat this query at least once every 24 hours or when restarting the application. Use account.unregisterDevice to unsubscribe.

The following modes are supported:

• 1 - APNS (device token for apple push)
• 2 - FCM (firebase token for google firebase)
• 3 - MPNS (channel URI for microsoft push)
• 4 - Deprecated: Simple push (endpoint for firefox's simple push API)
• 5 - Ubuntu phone (token for ubuntu push)
• 6 - Blackberry (token for blackberry push)
• 7 - MTProto separate session
• 8 - WNS (windows push)
• 9 - APNS VoIP (token for apple push VoIP)
• 10 - Web push (web push, see below)
• 11 - MPNS VoIP (token for microsoft push VoIP)
• 12 - Tizen (token for tizen push)

For 10 web push, the token must be a JSON-encoded object with the following keys:

• endpoint: Absolute URL exposed by the push service where the application server can send push messages
• keys: P-256 elliptic curve Diffie-Hellman parameters in the following object
  • p256dh: Base64url-encoded P-256 elliptic curve Diffie-Hellman public key
  • auth: Base64url-encoded authentication secret

Notification encryption

For FCM and APNS VoIP, an optional encryption key used to encrypt push notifications can be passed to account.registerDevice (secret). This key (auth_key) is used to encrypt the payloads using MTProto v2.

The FCM payload will be a JSON payload, containing a p field with the base64-encoded encrypted MTProto payload. After decryption, the result will be a JSON object, prefixed by a 32-bit little-endian integer with the length of the JSON payload. As usual, make sure to follow all security checks as described in the MTProto docs.

Example implementation.

As mentioned above, payloads can also be encrypted using P-256 Elliptic Curve Diffie-Hellman when using web push.

Notification structure

An (optionally encrypted) notification is provided as a JSON object in the following format:

{
  "data": {
    "loc_key": "CHAT_MESSAGE_CONTACT",
    "loc_args": ["John Doe", "My magical group", "Contact Exchange"],
    "user_id": 14124122,
    "custom": {
      "chat_id": 241233,
      "msg_id": 123
    },
    "sound": "sound1.mp3",
  }
}

Each notification has several parameters that describe it.

Notification type

data.loc_key - A string literal in the form /[A-Z_0-9]+/, which summarizes the notification. For example, CHAT_MESSAGE_TEXT.

Notification text arguments

data.loc_args - A list or arguments which, when inserted into a template, produce a readable notification.

Custom parameters

data.custom - Parameters which are be passed into the application when a notification is opened.

Sound

data.sound - The name of an audio file to be played.

User id

data.user_id - ID of the account to which the PUSH notification should be delivered, in case of clients with multiple accounts active and running.

Processing notifications

In principle, data.loc_key, data.custom, and an Internet connection are sufficient to generate a notification. Obviously, if possible, when generating a visual notification you need not use all of the transmitted data and may rely on the information already stored on the client. But if a user or a chat is not cached locally, the values passed in loc_args may also be used. data.user_id is the ID of the account to which the PUSH notification should be delivered, in case of clients with multiple accounts active and running.

Service notifications

The following notifications can be used to update app settings.

Possible Notifications