Skip to main content

Content Types with XMTP

When you build an app with XMTP, all messages are encoded with a content type to ensure that an XMTP 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 three categories of content types with XMTP:

  • Standard
  • Standards-track
  • Custom

Experimental playground πŸŽ²β€‹

To explore implementations of standard and standards-track content types, see the XMTP React playground:

GitHub repo | Web app

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).

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.

Here are the current standard content types:

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.

await conversation.send("gm");

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.

import { CompositeCodec } from "@xmtp/xmtp-js";
//xmtp = await Client.create(signer, { env: "dev" });
xmtp.registerCodec(new CompositeCodec());

Standards-track content types​

A standards-track content type is one that is being actively reviewed for adoption as a standard content type through the XIP process.

Here are standards-track content types that you can review, test, and adopt in your app today:

Attachment content type​

Use to send an attachment smaller than 1MB using the AttachmentCodec. The codec automatically encrypts the attachment and uploads it to the XMTP network.

Remote attachment content type​

Use to send a remote attachment of any size using the RemoteAttachmentCodec and a storage provider.

Read receipt content type​

Use to send a read receipt, which is a timestamp that indicates when a message was read. The read receipt is sent as a message and you can use it to calculate the time since the last message was read.

Reaction content type​

Use a reaction to send 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​

Use a reply to send a direct response to a specific message in a conversation. Users can select and reply to a particular message instead of sending a new one.

On-chain transaction reference content type​

Use to send references to on-chain transactions, such as crypto payments.

Create a custom content type​

Any developer building with XMTP can create a custom content type and immediately start using it in their app. Unlike a standard content type, use of a custom content type doesn't require prerequisite formal adoption through the XRC and XIP processes.

For example, if you need a content type that isn't covered by a standard or standards-track content type, you can create a custom content type and begin using it immediately in your app.

caution

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

If another app wants to display your custom content type, they must implement your custom content type in their code exactly as it's defined in your code.

Fallback plain text is "alt text"-like description text that you can associate with a custom content type if you are concerned that a receiving app might not be able to handle the content. If the receiving app is unable to handle the custom content, it displays the fallback plain text instead.

Here are tutorials you can use to learn how to create custom content types:

Basic: Multiply a number​

Create a custom content type used to multiply numbers.

Advanced: Send a Polygon transaction​

Create a custom content type used to send transaction hashes on the Polygon blockchain.

Was the information on this page helpful?
powered by XMTP

On this page
XMTP icon
CC BY 4.0Privacy policyTerms of service
𝕏