XIP-20: Reactions content type


This XIP introduces the reaction content type for XMTP clients, enabling users to react to messages with emojis. It defines an action field (values: ‘added’, ‘removed’) for reaction management, and a schema field (value: ‘unicode’) for categorizing emoji types. This standardization aims to enhance communication efficiency and engagement across XMTP clients.


The goal of this content type is to bring a dynamic and expressive form of communication to the XMTP ecosystem. Reactions are integral in modern messaging, allowing for rapid, non-verbal responses in conversations. Implementing this standard promises to streamline communication, making it more effective and enjoyable as well as consistent with expectations of current messaging apps.


The reaction content type includes:

  • reference (string): The ID of the message being reacted to.
  • emoji (string): The emoji used in the reaction.
  • action (string): Indicates if the reaction is being ‘added’ or ‘removed’.
  • schema (string): Categorizes the emoji as ‘unicode’.

Example code snippet:

// Reacting with a thumbs-up emoji
const reaction: Reaction = {
  reference: originalMessage.id,
  emoji: "👍",
  action: "added",
  schema: "unicode",

await conversation.send(reaction, {
  contentType: ContentTypeReaction,


The action and schema fields provide necessary flexibility for reaction management. action addresses the dynamic nature of conversations, while schema ensures cross-client consistency. The choice of emoji as a reaction medium leverages its universal appeal and succinct expression capabilities.

Backward Compatibility

To maintain backward compatibility, a contentFallback is stored in the codec as text — ensuring that the intent of reactions is conveyed even in non-supporting clients.

Test Cases

Test cases will validate the interpretation of schema types, handling of action, and effective use of contentFallback. These are essential for ensuring interoperability across XMTP platforms.

Reference Implementation

The reference implementation in the XMTP SDKs demonstrates the integration of the reaction content type. The full implementation can be accessed in the React playground here, and we also have a reference implementation in xmtp.chat.

Security Considerations

Clients SHOULD account for situations when an emoji character is sent that isn’t yet supported by the client or OS. This may happen when an OS update includes new emoji characters, which are then made available to a sender, but may not be supported on the recipient’s client, OS, or device.


Copyright and related rights waived via CC0.


I’ve seen this successfully implemented in several apps now including xmtp.chat. This proposal looks good to me :+1:

My only comment would be on reaction removals being the same content type just sent again with the same content but flagged as a removal. It might be nice if reaction removals were a different content type or if there was a way to make certain aspects of contentTypes mutable.

1 Like

Before we finalize this content type I want to make sure: do we really need to support non-unicode schemas in the initial version?

Unicode seems to be the only schema currently used by applications. If someone were to send a shortcode-discord emoji it is unlikely that any client application other than their own would be able to read it and display it properly. This hurts interoperability, and raises the bar substantially for an integrator to fully support this content type.

1 Like

i’m OK with this suggestion. it definitely simplifies the implementation.