Support push notifications
With XMTP, you can enable real-time push notifications to keep users updated on new conversations and messages.
Get a Welcome message topic ID
Get the topic identifier for an app installation. This topic ID tells your app where to listen on the network for push notifications about any new group chat or DM conversations.
// Request
alix.welcomeTopic()
// Response
/xmtp/mls/1/w-$installationId/proto
Get a message topic ID
Get the topic identifier for a group chat or DM conversation that’s already in progress. This topic ID tells your app where to listen on the network for push notifications about any new messages in a specific group chat or DM conversation.
// Request
conversation.topic
// Response
/xmtp/mls/1/g-$conversationId/proto
List push topics for a DM conversation
Lists topics for a specific DM conversation.
conversation.getPushTopics()
List push topics for all conversations
Lists topics for all group chat and DM conversations, including duplicate DM conversations.
Duplicate DM conversations can occur when a user creates new conversations with the same contact from different installations or devices. While DM stitching automatically combines these conversations into a single view for users, each duplicate conversation maintains its own push notification topic. Ensure that users receive push notifications for messages sent through any of the stitched conversations, even as the system gradually consolidates them into a single conversation.
To learn more, see Understand DM stitching and push notifications.
conversations.allPushTopics()
Subscribe to topics
Subscribe to all relevant topics, allowing your app to monitor for push notifications about both new and ongoing conversations.
This code sample retrieves all topics associated with alix
’s conversations, for example, enabling the app to receive push notifications only for conversations in which alix
is a part of.
const conversations = await alix.conversations.list();
const topics = conversations.map((conv: any) => conv.topic);
await subscribeAll([alix.welcomeTopic(), ...topics]);
Receive push notifications
On receipt of a push notification, decode it:
const receivedBytes = Buffer.from(received.message, "base64").toString("utf-8");
Then determine whether it’s for a new conversation or an existing one.
-
If it’s a Welcome message for a new conversation (
alix.welcomeTopic() == received.topic
), initiate the conversation withfromWelcome
:React Nativeconst conversation = await alix.conversations.fromWelcome( receivedBytes );
-
If it’s a message for an existing conversation, find the corresponding topic, sync the conversation, and process the new message:
React Nativeconst conversation = await alix.findConversationByTopic(received.topic); await conversation.sync(); const message = await conversation.processMessage(receivedBytes);
Resubscribe to topics to get new HMAC keys
As soon as your apps receive a user preference update event indicating new HMAC keys for a user, resubscribe to topics to get the new HMAC keys. For example:
conversations.allTopics.forEach { -> topic
val hmacKeysResult = conversations.getHmacKeys()
val hmacKeys = hmacKeysResult.hmacKeysMap
val result = hmacKeys[topic]?.valuesList?.map { hmacKey ->
Service.Subscription.HmacKey.newBuilder().also { sub_key ->
sub_key.key = hmacKey.hmacKey
sub_key.thirtyDayPeriodsSinceEpoch = hmacKey.thirtyDayPeriodsSinceEpoch
}.build()
}
val subscription = Service.Subscription.newBuilder().also { sub ->
sub.addAllHmacKeys(result)
sub.topic = topic
sub.isSilent = false
}.build()
}
PushNotificationTokenManager.xmtpPush.subscribeWithMetadata(subscription)
This ensures that older installations (or your XMTP push notification server code) now know about and resubscribe to all conversations for all of the new HMAC keys.
Get HMAC keys for a conversation
Gets the HMAC keys for a specific group chat or DM conversation.
For DM conversations, the response includes HMAC keys for all topics associated with the conversation. This is necessary because a single DM conversation can have multiple underlying topics due to DM stitching, where multiple conversations between the same participants are combined into one view.
For example, if Alix and Bo have a conversation that was created from two different installations, there might be two topics (topic1
and topic2
) for what appears as a single conversation to the user. The response will include HMAC keys for both topics to ensure push notifications work correctly regardless of which topic the message was sent through.
To learn more, see Understand DM stitching and push notifications.
conversation.getHmacKeys()
Run a push notification server
To implement push notifications in your app, you must run a push notification server. This server acts as an intermediary between the XMTP network and your app’s push notification service, ensuring that users receive timely and relevant notifications.
Why is a push notification server required?
- Continuous monitoring: The XMTP network operates on a decentralized protocol, where messages are exchanged directly between clients. However, for push notifications, your app needs a dedicated server to continuously listen for new messages or events on the XMTP network, even when the user’s device is offline or the app is not running.
- Message processing: Upon detecting new messages or events, the server processes them to determine their relevance and formats them appropriately for push notifications. This includes extracting necessary information, such as the sender’s identity and message content, to craft meaningful notifications.
- Integration with push notification services: The server interfaces with platform-specific push notification services, like Apple Push Notification Service (APNs) for iOS or Firebase Cloud Messaging (FCM) for Android. It sends the processed notifications to these services, which then deliver them to the user’s device.
To learn more about running a push notification server, see Understand push notifications with XMTP.
Then you can: