Push Notifications

Push notifications are used to notify users of events that occur in the background, such as incoming messages or calls.

After authenticating, a mobile client can register a device push notification token with the server using the Register Device endpoint. This token is then used to send push notifications to the client's device.

Registering Tokens

A client registers its device's token with the Register Device endpoint, or with Sync Devices when several accounts share the device. It also keeps the token it was given by the operating system, and attaches it to requests that provision a new authentication token, so the device stays registered across the change without a second round trip.

Currently, these endpoints are Modify Current User and Reset Password.

Push Notification Provider

¹ Local providers are only used by locally-built clients, identified by a com.hammerandchisel.discord.local bundle ID prefix.

² VOIP-specific push notification providers are used to provide rich notifications for VOIP calls on iOS.

Push Notification Payloads

Push notifications are delivered as data-only messages. The payload carries the entities the event concerns, and the client renders, groups, and routes the notification itself. Which fields are present depends on the type of push notification.

On iOS, the payload's fields are sent as top-level siblings of the standard APNs aps dictionary. On Android, they are sent as an FCM data message; there is no notification block, so notifications are always rendered by the client rather than by the system.

Only type is guaranteed to be present. Every other field is optional, and a client that receives a type it does not recognize is expected to ignore the notification. The fields belonging to a notification's type are sent alongside the ones below rather than nested in an object of their own.

Push Notification Structure

¹ Used on devices with multiple accounts logged in. The client switches to this account before acting on the notification. See Sync Devices for more information.

² Android only. Modern clients derive the notification channel from notif_type_id instead; see notification channels.

³ Used as the last acknowledged timestamp when a notification acknowledges channels. Clients that do not receive this field fall back to the time the push was sent.

Push Notification Type

¹ These types retract notifications instead of displaying one; see acknowledging notifications.

² This is used for notification types that have no dedicated handling in the client.

Message Create Structure

¹ Contains only the author, mentions, embeds, components, sticker_items, and poll fields.

² Only sent for messages in a DM that invite the user to a guild.

Attachment Text Variant

Sent when the message's own content should not be shown.

Invite Title Variant

Forum Thread Created Structure

Relationship Add Structure

Friend Suggestion Create Structure

Call Ring Structure

Call Connect Structure

¹ Android only.

Activity Start Structure

Application Library Install Complete Structure

Stage Instance Create Structure

Guild Stream Start Structure

Guild Scheduled Event Update Structure

¹ Always present for events with a STAGE_INSTANCE or VOICE entity type. Clients ignore events hosted at any other kind of entity.

Generic Push Notification Structure

¹ Deep links are a URL using either the discord:// protocol or a Discord hostname.

² Only sent with ICYMI_SUMMARY notifications.

³ A value of 0 should be treated the same as a null value.

Notification Type

Every notification Discord can send has a type, independent of the push notification type used to deliver it. It is sent as notif_type_id, and determines which notification channel the notification is posted to and which user notification settings suppress it. Types with no dedicated handling in the client are delivered as GENERIC_PUSH_NOTIFICATION_SENT push notifications, which name their type in notification_type instead.

¹ Delivered by email rather than as a push notification.

Tracking Type

Example Push Notification

{
  "aps": {
    "alert": { "title": "general (My Cool Server)", "body": "hey, are you around?" },
    "sound": "default",
    "badge": 3
  },
  "type": "MESSAGE_CREATE",
  "notif_type_id": "1",
  "notif_instance_id": "1536922843542192241",
  "sent_at_ms": "1786502869340",
  "channel_id": "1029315212521771020",
  "channel_type": "0",
  "channel_name": "general",
  "guild_id": "1029315212005888060",
  "guild_name": "My Cool Server",
  "guild_icon": "546242649e3b09a97af7e8f29983837b",
  "message_id": "1536922843542192240",
  "message_type_": "0",
  "message_content": "hey, are you around?",
  "user_id": "852892297661906993",
  "user_username": "dolfies",
  "user_global_name": "Dolfies",
  "user_avatar": "14733482e560d9267c0a414b21b2fb8d",
  "__category": "can_reply"
}

Acknowledging Notifications

Discord retracts notifications it has already sent by sending another push notification. These types never display anything:

• CHANNEL_ACK: the channels in channel_ids were read on another device
• CALL_ACK: the call in the channels in channel_ids was answered on another device
• CALL_RING_END: the user is no longer being rung in the channels in channel_ids

sent_at_ms is the acknowledgement time. Clients should convert it to a snowflake and dismiss the notifications for each acknowledged channel whose newest message is older than it, leaving anything that arrived after the acknowledgement was sent in place. A notification the user has already replied to inline is kept and re-rendered as replied rather than dismissed.

CALL_RING_END is handled differently: rather than being dismissed, the ringing notification is replaced with a silent missed call notification.

Notification Channels

Android requires every notification to be posted to a notification channel, which the user can configure or disable individually. Channels are gathered into groups in the system settings UI.

Clients register the channels below with the operating system on startup, and pick one for each notification from its notif_type_id.

Notification Channel

¹ Clients that support custom call ringtones register one channel per ringtone, named calls_{ringtone} (i.e. calls_default and calls_halloween).

Notification Channel Group

Default Notification Channel Mapping

CALL_RING and CALL_RING_END push notifications are always posted to the call channel, regardless of their notification type.

VOIP Notifications

Incoming calls on iOS are delivered over PushKit rather than APNs, so the system's native call UI can be presented before the app is running. These notifications use a payload of their own, unrelated to the one above.

VOIP Push Notification Structure

VOIP Push Notification Type

Clients register the call with the system as discord:{channel.id}.{channel.type}.{recipient.id} for DMs, and discord:{channel.id}.{channel.type}.{guild.id} otherwise.

Endpoints

Registers an FCM/APNs push notification token for the client's device. Returns a 204 empty response on success.

JSON Params

¹ VOIP-specific push notification tokens are only used with PushKit on iOS.

Unregisters an FCM/APNs push notification token for the client's device. Returns a 204 empty response on success.

JSON Params

Returns a push notification sync token for the current user. This token can be used to synchronize push notification tokens across multiple accounts.

Response Body

Example Response

{ "token": "ODUyODkyMjk3NjYxOTA2OTkz.ZfoufA.rHvCtpfHjr9kdRab1ZTl83PRhhZ" }

Synchronizes the client's FCM/APNs push notification token across multiple accounts.

JSON Params

¹ A device sync token can be obtained for each account using the Get Device Sync Token endpoint.

Response Body

Example Response

{ "invalid_push_sync_tokens": ["ODUyODkyMjk3NjYxOTA2OTkz.ZfoufA.rHvCtpfHjr9kdRab1ZTl83PRhhZ"] }