<h3><aclass="anchor"href="#configuring-the-application"id="configuring-the-application"name="configuring-the-application"><iclass="anchor-icon"></i></a>Configuring the application</h3>
<p>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 <ahref="/myapp">application settings</a>.</p>
<h3><aclass="anchor"href="#subscribing-to-notifications"id="subscribing-to-notifications"name="subscribing-to-notifications"><iclass="anchor-icon"></i></a>Subscribing to notifications</h3>
<p>To subscribe to notifications, the client must invoke the <ahref="/method/account.registerDevice">account.registerDevice</a> query, passing in <strong>token_type</strong> and <strong>token</strong> 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 <ahref="/method/account.unregisterDevice">account.unregisterDevice</a> to unsubscribe.</p>
<li><code>4</code> - Simple push (endpoint for firefox's deprecated simple push API): note that this push type can also be used by an open source push notification spec like <ahref="https://unifiedpush.org/">UnifiedPush »</a>.<br>
Simple push works by sending a simple PUT request with a <code>version=number</code> payload to the specified HTTPS endpoint every time a relevant message is received: upon receiving such a notification, clients should connect to the MTProto API and fetch <ahref="/api/updates">updates</a>.<br>
(Note that the <code>number</code> won't necessarily be incremental in Telegram's implementation, just treat each distinct request as a signal that a new message is waiting to be fetched via MTProto).</li>
<p>For FCM and APNS VoIP, an optional encryption key used to encrypt push notifications can be passed to <ahref="/method/account.registerDevice">account.registerDevice</a> (<code>secret</code>). This key (<code>auth_key</code>) is used to encrypt the payloads using <ahref="/mtproto/description">MTProto v2</a>.</p>
<p>The FCM payload will be a JSON payload, containing a <code>p</code> field with the base64url-encoded encrypted <ahref="/mtproto/description">MTProto payload</a>. 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 <ahref="/mtproto/description#important-checks">MTProto docs</a>.</p>
<p>As mentioned <ahref="#subscribing-to-notifications">above</a>, payloads can also be encrypted using <ahref="https://tools.ietf.org/html/rfc8291">P-256 Elliptic Curve Diffie-Hellman when using web push</a>.</p>
<p>An (<ahref="#notification-encryption">optionally encrypted</a>) notification is provided as a JSON object in the following format:</p>
<pre><code>{
"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",
}
}</code></pre>
<p>Each notification has several parameters that describe it.</p>
<ul>
<li>loc_key - Notification type: a string literal in the form <code>/[A-Z_0-9]+/</code>, which summarizes the notification. For example, <code>CHAT_MESSAGE_TEXT</code>.</li>
<li>loc_args - Notification placeholder arguments: a list or arguments which, when inserted into a template, produce a readable notification.</li>
<li>custom - Custom parameters to be passed into the application when a notification is opened. Possible fields:<ul>
<li>attachb64 - For notifications about media, base64url-encoded TL-serialization of the corresponding <ahref="/type/Photo">Photo</a> / <ahref="/type/Document">Document</a> object</li>
<li>updates - base64url-encoded TL-serialization of the <ahref="/type/Updates">Updates</a> object, currently sent only for PHONE_CALL_REQUEST (with <ahref="/constructor/updatePhoneCall">updatePhoneCall</a> inside)</li>
<li>call_id - Call ID, used in PHONE_CALL_REQUEST</li>
<li>call_ah - Call access hash, used in PHONE_CALL_REQUEST</li>
<li>encryption_id - Secret chat id for ENCRYPTION_REQUEST, ENCRYPTION_ACCEPT, ENCRYPTED_MESSAGE</li>
<li>random_id - Random id for message in ENCRYPTED_MESSAGE</li>
<li>contact_id - Telegram user identifier of contact that joined Telegram in CONTACT_JOINED</li>
<li>msg_id - Message ID for new message event or reaction event</li>
<li>channel_id - Identifier of the <ahref="/api/channel">channel/supergroup</a> where the event occurred</li>
<li>chat_id - Identifier of the <ahref="/api/channel#basic-groups">basic group</a> where the event occurred</li>
<li>from_id - User ID where the event occurred</li>
<li>chat_from_broadcast_id - If the group message was sent as a channel, this field will contain the sender channel ID</li>
<li>chat_from_group_id - If the group message was sent as a supergroup, this field will contain the sender supergroup ID</li>
<li>chat_from_id - Groups only, message author identifier (ignore if any of chat_from_broadcast_id / chat_from_group_id was present)</li>
<li>mention - Whether the current user was mentioned/replied to in this new message</li>
<li>silent - Whether the message was posted silently (no sound should be played for this notification)</li>
<li>schedule - Whether the message is outgoing and was sent via <ahref="/api/scheduled-messages">scheduled messages</a></li>
<li>edit_date - When was the message last edited</li>
<li>top_msg_id - thread_id for new mentions/replies in <ahref="/api/threads">threads</a></li>
</ul>
</li>
<li>sound - The name of an audio file to be played.</li>
<li>user_id - ID of the account to which the PUSH notification should be delivered, in case of clients with multiple accounts active and running.</li>
<li>announcement - Roughly equivalent to a message received from the service notifications (Telegram Notifications, id <code>777000</code>) user, but must be delivered via push notifications, without contacting the API.</li>
<p>In principle, <strong>data.loc_key</strong>, <strong>data.custom</strong>, 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. <strong>data.user_id</strong> is the ID of the account to which the PUSH notification should be delivered, in case of clients with multiple accounts active and running.</p>
<p>The following notifications can be used to update app settings.</p>
<tableclass="table">
<thead>
<tr>
<th>Type</th>
<th>Extra custom arguments</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>DC_UPDATE</td>
<td><strong>data.custom.dc</strong> - number of the data-center<br><strong>data.custom.addr</strong> - server address with port number in the format <code>111.112.113.114:443</code></td>
<td>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 (<code>dc=1</code>), it is recommended to call it immediately using <ahref="/method/help.getConfig">help.getConfig</a> to update dc-configuration.</td>
</tr>
<tr>
<td>MESSAGE_DELETED</td>
<td><strong>data.custom.channel_id</strong>: For <ahref="/api/channel">channels and supergroups</a>, <ahref="/api/channel">Channel/supergroup</a> identifier<br><strong>data.custom.chat_id</strong>: For <ahref="/api/channel">chats</a>, <ahref="/api/channel">Chat</a> identifier<br><strong>data.custom.from_id</strong>: For PMs, Author identifier<br><strong>data.custom.messages</strong>: Comma-separated IDs of messages that were deleted</td>
<td>Messages were deleted, remove multiple notifications for this chat</td>
</tr>
<tr>
<td>READ_HISTORY</td>
<td><strong>data.custom.channel_id</strong>: For <ahref="/api/channel">channels and supergroups</a>, <ahref="/api/channel">Channel/supergroup</a> identifier<br><strong>data.custom.chat_id</strong>: For <ahref="/api/channel">chats</a>, <ahref="/api/channel">Chat</a> identifier<br><strong>data.custom.from_id</strong>: For PMs, Author identifier<br><strong>data.custom.max_id</strong>: Maximum ID of read messages</td>
<td>Message history was read, remove multiple notifications for this chat</td>
</tr>
<tr>
<td>GEO_LIVE_PENDING</td>
<td></td>
<td>Any of the live locations currently being shared should be updated</td>
</tr>
<tr>
<td>SESSION_REVOKE</td>
<td></td>
<td>Logout and remove DB for specified session by <strong>data.user_id</strong>, only apply if coming from an <ahref="#notification-encryption">MTProto-encrypted payload</a></td>
</tr>
<tr>
<td>MESSAGE_MUTED</td>
<td></td>
<td>Sent rarely, every 10th message in chats or once per 15 sec in PM, to update badge or download messages</td>
<td>Roughly equivalent to a message received from the service notifications (Telegram Notifications, id <code>777000</code>) user, but must be delivered via push notifications, without contacting the API.</td>
<td>{1} posted a giveaway of {2}x {3}m Premium subscriptions</td>
<td>1. Channel name<br>2. Number of Telegram Premium subscriptions in the giveaway<br>3. Duration in months of each Telegram Premium subscription in the giveaway</td>
<td>{1} sent a giveaway of {3}x {4}m Premium subscriptions to the group {2}</td>
<td>1. User name<br>2. Group name<br>3. Number of Telegram Premium subscriptions in the giveaway<br>4. Duration in months of each Telegram Premium subscription in the giveaway</td>
<td>{1} sent you a Gift Code for {2} of Telegram Premium</td>
<td>1. User name<br>2. Duration of Telegram Premium subscription</td>
</tr>
<tr>
<td>MESSAGE_GIVEAWAY</td>
<td>{1} sent you a giveaway of {2}x {3}m Premium subscriptions</td>
<td>1. User name<br>2. Number of Telegram Premium subscriptions in the giveaway<br>3. Duration in months of each Telegram Premium subscription in the giveaway</td>
