Content Types with XMTP

When you build an app with XMTP, all messages are encoded with a content type to ensure that an XMTP message API client knows how to encode and decode messages, ensuring interoperability and consistent display of messages across apps.

In addition, message payloads are transported as a set of bytes. This means that payloads can carry any content type that a client supports, such as plain text, JSON, or even non-text binary or media content.

At a high level, there are two categories of content types with XMTP:

• Standard
• Custom

Experimental Playground 🎲

To see a live example of all content types implemented, check out the React Playground.

GitHub repo | Live Version.

Standard content types

A standard content type is one that has undergone the XMTP Request for Comment (XRC) process and has been adopted as an XMTP Improvement Proposal (XIP).

To learn more about the XRC and XIP processes that enable a framework for community members to propose standards and achieve consensus about their adoption, see XMTP Improvement Proposals (XIPs).

Once adopted, a standard content type is bundled in XMTP client SDKs. A developer can then import the standard content type from an SDK for use in their app.

• Text Content Type

An app built with XMTP uses the TextCodec (plain text) standard content type by default. This means that if your app is sending plain text messages only, you don’t need to perform any additional steps related to content types.

• Composite Content Type

If you want your app to be able to send multiple content types; such as any combination of plain text, images, audio, and video; in a single message, you must set up your app to use the CompositeCodec standard content type.

• Attachment Content Type

Attachments smaller than 1MB can be sent using the AttachmentCodec. The codec will automatically encrypt the attachment and upload it to the XMTP network.

• Remote Attachment Content Type

Remote attachments of any size can be sent using the RemoteAttachmentCodec and a storage provider.

• Read Receipt Content Type

A read receipt is a timestamp that indicates when a message was read. It is sent as a message and can be used to calculate the time since the last message was read.

• Reaction Content Type

A reaction is a quick and often emoji-based way to respond to a message. Reactions are usually limited to a predefined set of emojis or symbols provided by the messaging app.

• Reply Content Type

A reply is a method to directly respond to a specific message in a conversation. Users can select and reply to a particular message instead of sending a new one.

Create Custom Content Types

caution

Your custom content type WILL NOT automatically be supported by other apps and will display fallback text in them instead.

Keep in mind that any other application that intends to use your custom content type must implement it as per your definition.

• Basic: Number multiplier Content Type

This tutorial will walk you through the process of building a custom content type dedicated to multiplying numbers. For demonstration purposes, we'll create a MultiplyCodec custom content type.

• Advanced: Sending a polygon transaction

This tutorial will walk you through the process of building a custom content type dedicated to send transaction hashes on the polygon blockchain.

Handle unsupported Content Types

const codec = xmtp.codecFor(content.contentType);
if (!codec) {
  const fallback = `missing codec for content type "${content.contentType.toString()}"`;
  throw new Error(fallback);
}

Feature support list

Compilation of apps that support different contentType.

• Attachments

  • Converse
  • Lenster

• Payments

  • Coinbase Wallet

• Reactions

  • Converse