UX best practices when building with XMTP

Consider these UX best practices when building your app with XMTP.

General

• If needed, use XMTP brand assets provided here: XMTP brand guidelines

• Resolve popular namespaces such as ENS, .lens, cb id, and so forth. For example, here is ENS name resolution in xmtp.chat:

  

  To achieve this functionality, consider using the Everyname resolution service.

• Provide error messaging when a user enters an address in the To field and the address hasn't created an XMTP identity.

  

• When displaying .eth names, look for and display an ENS avatar. When displaying .lens names, look for and display a Lens profile photo. Use blockies for raw 0x addresses.

Onboarding

• In your app onboarding flow, enable your users to activate XMTP DMs. User access to DMs can help with app engagement and re-engagement. For example, here is a prompt to activate XMTP DMs in the onboarding flow to claim a Lens handle:

  

• In your app onboarding flow, request user permission to display app-specific push notifications to reach users outside of an app session.

Conversations

• Provide an interoperable inbox UI in your app. This inbox enables your user to access and engage with all of their conversations without leaving your app. An interoperable inbox is the default state of listing conversations. For example, here is an interoperable inbox in the Orb app:

  

• Use conversation labels to provide context. For example, here is conversation labeling in an interoperable inbox helping the user understand the different origins of two conversations with the same address.

  

• Hide empty conversations.

• For multiple non-empty conversations with the same conversation ID and between the same pair of addresses, pick the earliest conversation and write to it, effectively abandoning the other conversations.

• Consider using conversation IDs and metadata to provide filtered views of conversations. For example, here is the Orb app with conversations filtered to show Lens conversations only:

  

• Enable users to filter based on friends on a social graph, such as Lens, or a client-side grant/revoke list. For example, here is the Buttrfly app displaying only conversations with Lens profiles you follow:

  

Push notifications

• Provide a separate setting for enabling and disabling direct message push notifications. For example, if you’re building a Lens app, provide a setting for XMTP push notifications that’s separate from Lens push notifications for posts, comments, likes, and so forth. For example, here are push notification settings in the Orb app:

  

• Decrypt messages for push notifications so you can display the contents within the notification. For example, here is a decrypted push notification provided by the Converse app.

  

• Display push notifications only for messages sent to a user. In other words, do not send a push notification to a user about a message they sent. To do this, filter out messages sent by the user and don't send push notifications for them.

Badging

• Display badges that indicate the presence of new notifications, messages, or conversations to help with engagement and interaction success.

  • Here is a conversation icon badge showing the presence of an unread message:

    

    Along these lines, be sure to unbadge conversations in which the user sent the latest message to avoid displaying unnecessary badges as users send messages across different apps. The action of sending the latest message implies that the user has seen the conversation.

  • Here is an app icon badge showing the number of unread messages in the Orb app: