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 base64url-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.

  • loc_key - Notification type: a string literal in the form /[A-Z_0-9]+/, which summarizes the notification. For example, CHAT_MESSAGE_TEXT.
  • loc_args - Notification placeholder arguments: a list or arguments which, when inserted into a template, produce a readable notification.
  • custom - Custom parameters to be passed into the application when a notification is opened. Possible fields:
    • attachb64 - For notifications about media, base64url-encoded TL-serialization of the corresponding Photo / Document object
    • updates - base64url-encoded TL-serialization of the Updates object, currently sent only for PHONE_CALL_REQUEST (with updatePhoneCall inside)
    • call_id - Call ID, used in PHONE_CALL_REQUEST
    • call_ah - Call access hash, used in PHONE_CALL_REQUEST
    • encryption_id - Secret chat id for ENCRYPTION_REQUEST, ENCRYPTION_ACCEPT, ENCRYPTED_MESSAGE
    • random_id - Random id for message in ENCRYPTED_MESSAGE
    • contact_id - Telegram user identifier of contact that joined Telegram in CONTACT_JOINED
    • msg_id - Message ID for new message event or reaction event
    • channel_id - Identifier of the channel/supergroup where the event occurred
    • chat_id - Identifier of the legacy group where the event occurred
    • from_id - User ID where the event occurred
    • chat_from_broadcast_id - If the group message was sent as a channel, this field will contain the sender channel ID
    • chat_from_group_id - If the group message was sent as a supergroup, this field will contain the sender supergroup ID
    • chat_from_id - Groups only, message author identifier (ignore if any of chat_from_broadcast_id / chat_from_group_id was present)
    • mention - Whether the current user was mentioned/replied to in this new message
    • silent - Whether the message was posted silently (no sound should be played for this notification)
    • schedule - Whether the message is outgoing and was sent via scheduled messages
    • edit_date - When was the message last edited
    • top_msg_id - thread_id for new mentions/replies in threads
  • sound - The name of an audio file to be played.
  • user_id - ID of the account to which the PUSH notification should be delivered, in case of clients with multiple accounts active and running.
  • announcement - Roughly equivalent to a message received from the service notifications (Telegram Notifications, id 777000) user, but must be delivered via push notifications, without contacting the API.

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.

Type Extra custom arguments Description
DC_UPDATE data.custom.dc - number of the data-center
data.custom.addr - server address with port number in the format 111.112.113.114:443		 In case the client gets this notification, it is necessary to add the received server address to the list of possible addresses. In case the address of the first DC was passed (dc=1), it is recommended to call it immediately using help.getConfig to update dc-configuration.
MESSAGE_DELETED data.custom.channel_id: For channels and supergroups, Channel/supergroup identifier
data.custom.chat_id: For chats, Chat identifier
data.custom.from_id: For PMs, Author identifier
data.custom.messages: Comma-separated IDs of messages that were deleted		 Messages were deleted, remove multiple notifications for this chat
READ_HISTORY data.custom.channel_id: For channels and supergroups, Channel/supergroup identifier
data.custom.chat_id: For chats, Chat identifier
data.custom.from_id: For PMs, Author identifier
data.custom.max_id: Maximum ID of read messages		 Message history was read, remove multiple notifications for this chat
GEO_LIVE_PENDING   Any of the live locations currently being shared should be updated
SESSION_REVOKE   Logout and remove DB for specified session by data.user_id, only apply if coming from an MTProto-encrypted payload
MESSAGE_MUTED   Sent rarely, every 10th message in chats or once per 15 sec in PM, to update badge or download messages
MESSAGE_ANNOUNCEMENT data.announcement: Announcement Roughly equivalent to a message received from the service notifications (Telegram Notifications, id 777000) user, but must be delivered via push notifications, without contacting the API.

Possible Notifications

Type Template example Arguments
AUTH_REGION New login from unrecognized device {1}, location: {2} 1. Device name
2. Location
AUTH_UNKNOWN New login from unrecognized device {1} 1. Device name
CHANNEL_MESSAGES {1} posted an album 1. Message author
CHANNEL_MESSAGE_AUDIO {1} posted a voice message 1. Message author
CHANNEL_MESSAGE_CONTACT {1} posted a contact {2} 1. Message author
2. Contact name
CHANNEL_MESSAGE_DOC {1} posted a file 1. Message author
CHANNEL_MESSAGE_DOCS {1} posted {2} files 1. Channel name
2. Number of documents that were posted
CHANNEL_MESSAGE_FWDS {1} posted {2} forwarded messages 1. Message author
2. Number of forwarded messages
CHANNEL_MESSAGE_GAME {1} invited you to play {2} 1. Message author
2. Game name
CHANNEL_MESSAGE_GAME_SCORE {1} scored {3} in game {2} 1. User
2. Game name
3. Score
CHANNEL_MESSAGE_GEO {1} posted a location 1. Channel name
CHANNEL_MESSAGE_GEOLIVE {1} posted a live location 1. Channel name
CHANNEL_MESSAGE_GIF {1} posted a GIF 1. Channel name
CHANNEL_MESSAGE_NOTEXT {1} posted a message 1. Channel name
CHANNEL_MESSAGE_PHOTO {1} posted a photo 1. Channel name
CHANNEL_MESSAGE_PHOTOS {1} posted {2} photos 1. Channel name
2. Number of photos that was sent
CHANNEL_MESSAGE_PLAYLIST {1} posted {2} music files 1. Channel name
2. Number of audio files that were posted
CHANNEL_MESSAGE_POLL {1} posted a poll {2} 1. Channel name
2. Poll name
CHANNEL_MESSAGE_QUIZ {1} posted a quiz {2} 1. Channel name
2. Quiz name
CHANNEL_MESSAGE_ROUND {1} posted a video message 1. Channel name
CHANNEL_MESSAGE_STICKER {1} posted a {2} sticker 1. Channel name
2. Sticker emoji
CHANNEL_MESSAGE_TEXT {1}: {2} 1. Channel name
2. Message body
CHANNEL_MESSAGE_VIDEO {1} posted a video 1. Channel name
CHANNEL_MESSAGE_VIDEOS {1} posted {2} videos 1. Channel name
2. Number of videos that were posted
CHAT_ADD_MEMBER {1} invited {3} to the group {2} 1. Message author
2. Chat name
3. New participant name
CHAT_ADD_YOU {1} invited you to the group {2} 1. User name
2. Group name
CHAT_CREATED {1} invited you to the group {2} 1. Message author
2. Chat name
CHAT_DELETE_MEMBER {1} removed {3} from the group {2} 1. Message author
2. Chat name
3. Dropped participant name
CHAT_DELETE_YOU {1} removed you from the group {2} 1. Message author
2. Chat name
CHAT_JOINED {1} joined the group {2} 1. User name
2. Group name
CHAT_LEFT {1} left the group {2} 1. Message author
2. Chat name
CHAT_MESSAGES {1} sent an album to the group {2} 1. User name
2. Group name
CHAT_MESSAGE_AUDIO {1} sent a voice message to the group {2} 1. Message author
2. Chat name
CHAT_MESSAGE_CONTACT {1} shared a contact {3} in the group {2} 1. User name
2. Group name
3. Contact name
CHAT_MESSAGE_DOC {1} sent a file to the group {2} 1. User name
2. Group name
CHAT_MESSAGE_DOCS {1} sent {3} files to the group {2} 1. User name
2. Group name
3. Number of documents that were sent
CHAT_MESSAGE_FWDS {1} forwarded {3} messages to the group {2} 1. User name
2. Group name
3. Number of messages that were forwarded
CHAT_MESSAGE_GAME {1} invited the group {2} to play {3} 1. User name
2. Group name
3. Game name
CHAT_MESSAGE_GAME_SCORE {1} scored {4} in game {3} in the group {2} 1. User name
2. Group name
3. Game name
4. Score
CHAT_MESSAGE_GEO {1} sent a location to the group {2} 1. Message author
2. Chat name
CHAT_MESSAGE_GEOLIVE {1} shared a live location with the group {2} 1. User name
2. Group name
CHAT_MESSAGE_GIF {1} sent a GIF to the group {2} 1. User name
2. Group name
CHAT_MESSAGE_INVOICE {1} sent an invoice to the group {2} for {3} 1. User name
2. Group name
3. Product name
CHAT_MESSAGE_NOTEXT {1} sent a message to the group {2} 1. Message author
2. Chat name
CHAT_MESSAGE_PHOTO {1} sent a photo to the group {2} 1. Message author
2. Chat name
CHAT_MESSAGE_PHOTOS {1} sent {3} photos to the group {2} 1. User name
2. Group name
3. Number of photos that were sent
CHAT_MESSAGE_PLAYLIST {1} sent {3} music files to the group {2} 1. User name
2. Group name
3. Number of audio files that were sent
CHAT_MESSAGE_POLL {1} sent a poll {3} to the group {2} 1. User name
2. Group name
3. Poll name
CHAT_MESSAGE_QUIZ {1} sent a quiz {3} to the group {2} 1. User name
2. Group name
3. Quiz name
CHAT_MESSAGE_ROUND {1} sent a video message to the group {2} 1. User name
2. Group name
CHAT_MESSAGE_STICKER {1} sent a {3} sticker to the group {2} 1. User name
2. Group name
3. Sticker emoji
CHAT_MESSAGE_TEXT {1} @ {2}: {3} 1. Message author
2. Chat name
3. Message body
CHAT_MESSAGE_VIDEO {1} sent a video to the group {2} 1. Message author
2. Chat name
CHAT_MESSAGE_VIDEOS {1} sent {3} videos to the group {2} 1. User name
2. Group name
3. Number of videos that were sent
CHAT_PHOTO_EDITED {1} changed the group photo for {2} 1. Message author
2. Chat name
CHAT_REACT_AUDIO {1}: {3} to your voice message in {2} 1. User name
2. Group name
3. Reaction
CHAT_REACT_CONTACT {1}: {3} to your contact {4} in {2} 1. User name
2. Group name
3. Reaction
4. Contact name
CHAT_REACT_DOC {1}: {3} to your file in {2} 1. User name
2. Group name
3. Reaction
CHAT_REACT_GAME {1}: {3} to your game in {2} 1. User name
2. Group name
3. Reaction
CHAT_REACT_GEO {1}: {3} to your map in {2} 1. User name
2. Group name
3. Reaction
CHAT_REACT_GEOLIVE {1}: {3} to your live location in {2} 1. User name
2. Group name
3. Reaction
CHAT_REACT_GIF {1}: {3} to your GIF in {2} 1. User name
2. Group name
3. Reaction
CHAT_REACT_INVOICE {1}: {3} to your invoice in {2} 1. User name
2. Group name
3. Reaction
CHAT_REACT_NOTEXT {1}: {3} to your message in {2} 1. User name
2. Group name
3. Reaction
CHAT_REACT_PHOTO {1}: {3} to your photo in {2} 1. User name
2. Group name
3. Reaction
CHAT_REACT_POLL {1}: {3} to your poll {4} in {2} 1. User name
2. Group name
3. Reaction
4. Poll name
CHAT_REACT_QUIZ {1}: {3} to your quiz {4} in {2} 1. User name
2. Group name
3. Reaction
4. Quiz name
CHAT_REACT_ROUND {1}: {3} to your video message in {2} 1. User name
2. Group name
3. Reaction
CHAT_REACT_STICKER {1}: {3} to your {4} sticker in {2} 1. User name
2. Group name
3. Reaction
4. Sticker emoji
CHAT_REACT_TEXT {1}: {3} in {2} to your "{4}" 1. User name
2. Group name
3. Reaction
4. Message body
CHAT_REACT_VIDEO {1}: {3} to your video in {2} 1. User name
2. Group name
3. Reaction
CHAT_REQ_JOINED {2}|{1} was accepted into the group 1. User name
2. Chat name
CHAT_RETURNED {1} returned to the group {2} 1. Message author
2. Chat name
CHAT_TITLE_EDITED {1} renamed the group {2} 1. User name
2. Group name
CHAT_VOICECHAT_END {1} ended a voice chat in the group {2} 1. User name
2. Chat name
CHAT_VOICECHAT_INVITE {1} invited {3} to a voice chat in the group {2} 1. User name
2. Chat name
3. Invited users
CHAT_VOICECHAT_INVITE_YOU {1} invited you to a voice chat in the group {2} 1. User name
2. Chat name
CHAT_VOICECHAT_START {1} started a voice chat in the group {2} 1. User name
2. Chat name
CONTACT_JOINED {1} joined Telegram! 1. Contact name
ENCRYPTED_MESSAGE You have a new message  
ENCRYPTION_ACCEPT You have a new message  
ENCRYPTION_REQUEST You have a new message  
LOCKED_MESSAGE You have a new message  
MESSAGES {1} sent you an album 1. User name
MESSAGE_AUDIO {1} sent you a voice message 1. Message author
MESSAGE_CONTACT {1} shared a contact {2} with you 1. User name
2. Contact name
MESSAGE_DOC {1} sent you a file 1. User name
MESSAGE_DOCS {1} sent you {2} files 1. User name
2. Number of documents that were sent
MESSAGE_FWDS {1} forwarded you {2} messages 1. User name
2. Number of messages that were forwarded
MESSAGE_GAME {1} invited you to play {2} 1. User name
2. Game name
MESSAGE_GAME_SCORE {1} scored {3} in game {2} 1. User name
2. Game name
3. Score
MESSAGE_GEO {1} sent you a location 1. Message author
MESSAGE_GEOLIVE {1} sent you a live location 1. User name
MESSAGE_GIF {1} sent you a GIF 1. User name
MESSAGE_INVOICE {1} sent you an invoice for {2} 1. User name
2. Product
MESSAGE_NOTEXT {1} sent you a message 1. Message author
MESSAGE_PHOTO {1} sent you a photo 1. Message author
MESSAGE_PHOTOS {1} sent you {2} photos 1. User name
2. Number of photos that were sent
MESSAGE_PHOTO_SECRET {1} sent you a self-destructing photo 1. User name
MESSAGE_PLAYLIST {1} sent you {2} music files 1. User name
2. Number of audio files that were sent
MESSAGE_POLL {1} sent you a poll {2} 1. User name
2. Poll name
MESSAGE_QUIZ {1} sent you a quiz {2} 1. User name
2. Quiz name
MESSAGE_ROUND {1} sent you a video message 1. User name
MESSAGE_SCREENSHOT {1} took a screenshot 1. User name
MESSAGE_STICKER {1} sent you a {2} sticker 1. User name
2. Sticker emoji
MESSAGE_TEXT {1}: {2} 1. Message author
2. Message body
MESSAGE_VIDEO {1} sent you a video 1. Message author
MESSAGE_VIDEOS {1} sent you {2} videos 1. User name
2. Number of videos that were sent
MESSAGE_VIDEO_SECRET {1} sent you a self-destructing video 1. User name
PHONE_CALL_MISSED You missed a call from {1} 1. User name
PHONE_CALL_REQUEST {1} is calling you! 1. User name
PINNED_AUDIO {1} pinned a voice message 1. User name
PINNED_AUDIO {1} pinned a voice message in the group {2} 1. User name
2. Group name
PINNED_CONTACT {1} pinned a contact {2} 1. User name
2. Contact name
PINNED_CONTACT {1} pinned a contact {3} in the group {2} 1. User name
2. Group name
3. Contact name
PINNED_DOC {1} pinned a file 1. User name
PINNED_DOC {1} pinned a file in the group {2} 1. User name
2. Group name
PINNED_GAME {1} pinned a game 1. User name
PINNED_GAME {1} pinned a game in the group {2} 1. User name
2. Group name
PINNED_GAME_SCORE {1} pinned a game score 1. User name
PINNED_GAME_SCORE {1} pinned a game score in the group {2} 1. User name
2. Group name
PINNED_GEO {1} pinned a map 1. User name
PINNED_GEO {1} pinned a map in the group {2} 1. User name
2. Group name
PINNED_GEOLIVE {1} pinned a live location 1. User name
PINNED_GEOLIVE {1} pinned a live location in the group {2} 1. User name
2. Group name
PINNED_GIF {1} pinned a GIF 1. User name
PINNED_GIF {1} pinned a GIF in the group {2} 1. User name
2. Group name
PINNED_INVOICE {1} pinned an invoice 1. User name
PINNED_INVOICE {1} pinned an invoice in the group {2} 1. User name
2. Group name
PINNED_NOTEXT {1} pinned a message 1. User name
PINNED_NOTEXT {1} pinned a message in the group {2} 1. User name
2. Group name
PINNED_PHOTO {1} pinned a photo 1. User name
PINNED_PHOTO {1} pinned a photo in the group {2} 1. User name
2. Group name
PINNED_POLL {1} pinned a poll {2} 1. User name
2. Poll name
PINNED_POLL {1} pinned a poll {3} in the group {2} 1. User name
2. Group name
3. Poll name
PINNED_QUIZ {1} pinned a quiz {2} 1. User name
2. Quiz name
PINNED_QUIZ {1} pinned a quiz {3} in the group {2} 1. User name
2. Group name
3. Quiz name
PINNED_ROUND {1} pinned a video message 1. User name
PINNED_ROUND {1} pinned a video message in the group {2} 1. User name
2. Group name
PINNED_STICKER {1} pinned a {2} sticker 1. User name
2. Sticker emoji
PINNED_STICKER {1} pinned a {3} sticker in the group {2} 1. User name
2. Group name
3. Sticker emoji
PINNED_TEXT {1} pinned "{2}" 1. User name
2. Message body
PINNED_TEXT {1} pinned "{3}" in the group {2} 1. User name
2. Group name
3. Message body
PINNED_VIDEO {1} pinned a video 1. User name
PINNED_VIDEO {1} pinned a video in the group {2} 1. User name
2. Group name
REACT_AUDIO {1}: {2} to your voice message 1. User name
2. Reaction
REACT_CONTACT {1}: {2} to your contact {3} 1. User name
2. Reaction
3. Contact name
REACT_DOC {1}: {2} to your file 1. User name
2. Reaction
REACT_GAME {1}: {2} to your game 1. User name
2. Reaction
REACT_GEO {1}: {2} to your map 1. User name
2. Reaction
REACT_GEOLIVE {1}: {2} to your live location 1. User name
2. Reaction
REACT_GIF {1}: {2} to your GIF 1. User name
2. Reaction
REACT_INVOICE {1}: {2} to your invoice 1. User name
2. Reaction
REACT_NOTEXT {1}: {2} to your message 1. User name
2. Reaction
REACT_PHOTO {1}: {2} to your photo 1. User name
2. Reaction
REACT_POLL {1}: {2} to your poll {3} 1. User name
2. Reaction
3. Poll name
REACT_QUIZ {1}: {2} to your quiz {3} 1. User name
2. Reaction
3. Quiz name
REACT_ROUND {1}: {2} to your video message 1. User name
2. Reaction
REACT_STICKER {1}: {2} to your {3} sticker 1. User name
2. Reaction
3. Sticker emoji
REACT_TEXT {1}: {2} to your "{3}" 1. User name
2. Reaction
3. Message body
REACT_VIDEO {1}: {2} to your video 1. User name
2. Reaction
Telegram
Telegram is a cloud-based mobile and desktop messaging app with a focus on security and speed.
About
Mobile Apps
Desktop Apps
Platform
About
Blog
Apps
Platform
Twitter