Understand content types with XMTP

When you build an agent 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

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 agent or app.

Here is the current standard content type:

Text content type

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

await sendText('gm');

Receiving content types

When your agent receives messages with different content types, use event handlers to handle them appropriately:

// Listen for specific content types
agent.on('attachment', async (ctx) => {
  // Handle attachment logic
});
 
agent.on('reaction', async (ctx) => {
  // Handle reaction logic
});
 
agent.on('reply', async (ctx) => {
  // Handle reply logic
});
 
// For custom content types, you can access the content type directly
agent.on('message', async (ctx) => {
  const contentType = ctx.message.contentType;
  if (contentType?.typeId === 'my-custom-type') {
    // Handle custom content logic
  }
});

Standards-track content types

A standards-track content type is one that's 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 agent today:

• Group updates content type: Use to send group updates, such as name, description, and members.
• Remote attachment content type: Use to send attachments of any size.
• Markdown content type: Use to send rich formatted text messages with headers, lists, tables, and code blocks.
• Reaction content type: Use a reaction to send a quick and often emoji-based way to respond to a message.
• 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.
• Onchain transaction reference content type: Use to send references to onchain transactions, such as crypto payments.
• Onchain transaction content type: Use to support sending transactions to a wallet for execution.

Custom content types

Custom content types allow you to define your own schemas for messages that go beyond what is covered by standard or standards-track types. These are useful for experiments, domain-specific features, or app-specific behaviors.