Content Types - LibXMTP

Overview

LibXMTP uses a codec system to encode and decode different types of message content. Each content type has a unique identifier and version, following the format:

authority_id/type_id:version_major.version_minor

Example: xmtp.org/text:1.0

Standard content types

All standard content types use xmtp.org as the authority ID.

Text

Plain text messages with UTF-8 encoding. Type ID: xmtp.org/text:1.0 Structure:

pub struct Text {
    pub content: String,
}

Encoding (Node.js):

import { encodeText } from '@xmtp/node-bindings'

const encoded = encodeText('Hello, world!')
await conversation.send(encoded, { shouldPush: true })

Decoding:

if (message.content.type === DecodedMessageContentType.Text) {
  console.log(message.content.text)
}

Triggers push: Yes

Markdown

Markdown-formatted text for rich content. Type ID: xmtp.org/markdown:1.0 Structure:

pub struct Markdown {
    pub content: String,
}

Encoding (Node.js):

import { encodeMarkdown } from '@xmtp/node-bindings'

const encoded = encodeMarkdown('# Heading\n\n**Bold text**')
await conversation.send(encoded, { shouldPush: true })

Triggers push: Yes

Reaction

Emoji or text reactions to messages. Type ID: xmtp.org/reaction:2.0 Structure:

pub struct ReactionV2 {
    pub reference: String,              // Message ID being reacted to
    pub reference_inbox_id: String,     // Inbox ID of message author
    pub action: ReactionAction,         // Added or Removed
    pub content: String,                // Emoji or text content
    pub schema: ReactionSchema,         // Unicode, Shortcode, or Custom
}

pub enum ReactionAction {
    Unspecified = 0,
    Added = 1,
    Removed = 2,
}

pub enum ReactionSchema {
    Unspecified = 0,
    Unicode = 1,      // Standard emoji: 👍
    Shortcode = 2,    // Shortcode format: :thumbsup:
    Custom = 3,       // Custom reaction format
}

Encoding (Node.js):

import { encodeReaction, ReactionAction, ReactionSchema } from '@xmtp/node-bindings'

const encoded = encodeReaction({
  reference: messageId,
  referenceInboxId: senderInboxId,
  action: ReactionAction.Added,
  content: '👍',
  schema: ReactionSchema.Unicode
})

await conversation.send(encoded, { shouldPush: false })

Fallback text: "Reacted with \"👍\" to an earlier message" Triggers push: No Legacy support: Version 1.0 uses JSON encoding, automatically converted to v2

Reply

Threaded replies to previous messages. Type ID: xmtp.org/reply:1.0 Structure:

pub struct Reply {
    pub in_reply_to: Option<Box<DecodedMessage>>,  // Referenced message (enriched only)
    pub content: Box<MessageBody>,                  // Reply content
    pub reference_id: String,                       // Message ID being replied to
}

Encoding (Node.js):

import { encodeReply, encodeText } from '@xmtp/node-bindings'

const replyContent = encodeText('Great point!')
const encoded = encodeReply({
  reference: originalMessageId,
  referenceInboxId: originalSenderInboxId,
  content: replyContent
})

await conversation.send(encoded, { shouldPush: true })

Enrichment: When using listEnrichedMessages(), the in_reply_to field is populated with the referenced message. Fallback text: "Replied with \"Great point!\" to an earlier message" (for text replies) Triggers push: Yes

Attachment

Direct file attachments with content embedded. Type ID: xmtp.org/attachment:1.0 Structure:

pub struct Attachment {
    pub filename: Option<String>,
    pub mime_type: String,
    pub content: Vec<u8>,  // Raw file bytes
}

Encoding (Node.js):

import { encodeAttachment } from '@xmtp/node-bindings'
import { readFileSync } from 'fs'

const fileData = readFileSync('document.pdf')
const encoded = encodeAttachment({
  filename: 'document.pdf',
  mimeType: 'application/pdf',
  content: fileData
})

await conversation.send(encoded, { shouldPush: true })

Fallback text: "Can't display document.pdf. This app doesn't support attachments." Triggers push: Yes Note: For large files, use RemoteAttachment instead.

RemoteAttachment

Reference to externally stored file. Type ID: xmtp.org/remoteAttachment:1.0 Structure:

pub struct RemoteAttachment {
    pub url: String,
    pub content_digest: Vec<u8>,
    pub secret: Vec<u8>,
    pub salt: Vec<u8>,
    pub nonce: Vec<u8>,
    pub scheme: String,
    pub filename: Option<String>,
    pub content_length: Option<u64>,
}

Usage: Upload file to external storage (IPFS, S3, etc.), then send reference. Triggers push: Yes

MultiRemoteAttachment

Multiple remote file references in a single message. Type ID: xmtp.org/multiRemoteAttachment:1.0 Structure:

pub struct MultiRemoteAttachment {
    pub attachments: Vec<RemoteAttachment>,
}

Triggers push: Yes

ReadReceipt

Indicates message has been read. Type ID: xmtp.org/readReceipt:1.0 Structure:

pub struct ReadReceipt {}

Encoding (Node.js):

import { encodeReadReceipt } from '@xmtp/node-bindings'

const encoded = encodeReadReceipt()
await conversation.send(encoded, { shouldPush: false })

Triggers push: No Note: Empty payload, presence indicates receipt.

TransactionReference

Reference to blockchain transaction. Type ID: xmtp.org/transactionReference:1.0 Structure:

pub struct TransactionReference {
    pub chain_id: u64,
    pub namespace: String,       // e.g., "eip155"
    pub reference: String,       // Transaction hash
    pub metadata: HashMap<String, String>,
}

Encoding (Node.js):

import { encodeTransactionReference } from '@xmtp/node-bindings'

const encoded = encodeTransactionReference({
  chainId: 1,
  namespace: 'eip155',
  reference: '0x123abc...',
  metadata: { amount: '1.5 ETH' }
})

await conversation.send(encoded, { shouldPush: true })

Triggers push: Yes

WalletSendCalls

Wallet function call data (EIP-5792). Type ID: xmtp.org/walletSendCalls:1.0 Structure:

pub struct WalletSendCalls {
    pub version: String,
    pub chain_id: String,
    pub calls: Vec<SendCallsParams>,
}

Triggers push: Yes

GroupUpdated

Group metadata change notification. Type ID: xmtp.org/groupUpdated:1.0 Structure:

pub struct GroupUpdated {
    pub metadata_field_changes: Vec<MetadataFieldChange>,
}

Triggers push: No Note: Automatically sent when group name, image, or description changes.

LeaveRequest

Request to leave a group. Type ID: xmtp.org/leaveRequest:1.0 Structure:

pub struct LeaveRequest {}

Triggers push: No

Intent

User intent or action. Type ID: xmtp.org/intent:1.0 Structure:

pub struct Intent {
    pub intent_type: String,
    pub parameters: HashMap<String, String>,
}

Triggers push: Varies

Actions

Interactive action buttons or options. Type ID: xmtp.org/actions:1.0 Structure:

pub struct Actions {
    pub actions: Vec<Action>,
}

Triggers push: Varies

System content types

DeletedMessage

Placeholder for deleted messages (read-only). Type ID: xmtp.org/deletedMessage:1.0 Structure:

MessageBody::DeletedMessage {
    deleted_by: DeletedBy,
}

pub enum DeletedBy {
    Sender,
    Admin(String),  // Admin's inbox_id
}

Note: Cannot be sent directly. Created automatically when messages are deleted.

Custom content types

If LibXMTP encounters an unknown content type, it wraps it as MessageBody::Custom:

MessageBody::Custom(EncodedContent)

Accessing custom content:

if (message.content.type === DecodedMessageContentType.Custom) {
  const encoded = message.content.custom
  const contentType = encoded.type
  const parameters = encoded.parameters
  const content = encoded.content
  
  // Handle custom decoding
}

ContentCodec trait

All content types implement the ContentCodec trait:

pub trait ContentCodec<T> {
    fn content_type() -> ContentTypeId;
    fn encode(content: T) -> Result<EncodedContent, CodecError>;
    fn decode(content: EncodedContent) -> Result<T, CodecError>;
    fn should_push() -> bool;
}

Implementing custom codecs

use xmtp_content_types::{ContentCodec, CodecError};
use xmtp_proto::xmtp::mls::message_contents::{ContentTypeId, EncodedContent};

pub struct CustomCodec;

impl CustomCodec {
    const AUTHORITY_ID: &'static str = "example.com";
    pub const TYPE_ID: &'static str = "custom";
    pub const MAJOR_VERSION: u32 = 1;
    pub const MINOR_VERSION: u32 = 0;
}

impl ContentCodec<MyCustomType> for CustomCodec {
    fn content_type() -> ContentTypeId {
        ContentTypeId {
            authority_id: Self::AUTHORITY_ID.to_string(),
            type_id: Self::TYPE_ID.to_string(),
            version_major: Self::MAJOR_VERSION,
            version_minor: Self::MINOR_VERSION,
        }
    }
    
    fn encode(data: MyCustomType) -> Result<EncodedContent, CodecError> {
        // Encode logic
    }
    
    fn decode(content: EncodedContent) -> Result<MyCustomType, CodecError> {
        // Decode logic
    }
    
    fn should_push() -> bool {
        true
    }
}

Content type detection

Check content type before accessing fields:

switch (message.content.type) {
  case DecodedMessageContentType.Text:
    return message.content.text
    
  case DecodedMessageContentType.Reaction:
    const reaction = message.content.reaction!
    console.log(`${reaction.action}: ${reaction.content}`)
    break
    
  case DecodedMessageContentType.Reply:
    const reply = message.content.reply!
    console.log(`Reply to ${reply.reference}:`, reply.content)
    break
    
  case DecodedMessageContentType.Attachment:
    const attachment = message.content.attachment!
    saveFile(attachment.filename, attachment.content)
    break
    
  case DecodedMessageContentType.DeletedMessage:
    const deleted = message.content.deletedMessage!
    if (deleted.deletedBy === 'sender') {
      console.log('Message deleted by sender')
    } else {
      console.log(`Message deleted by admin: ${deleted.adminInboxId}`)
    }
    break
}

Fallback text

Most content types include fallback text for clients that don’t support them:

if (!supportsContentType(message.contentType)) {
  console.log(message.fallback)  // "Replied to an earlier message"
}

Fallback text is automatically generated during encoding based on content type.

Source code references

Rust content types: crates/xmtp_content_types/src/
Node.js bindings: bindings/node/src/content_types/
Core codec trait: crates/xmtp_content_types/src/lib.rs:94
Message body enum: crates/xmtp_mls/src/messages/decoded_message.rs:61

Documentation Index

​Overview

​Standard content types

​Text

​Markdown

​Reaction

​Reply

​Attachment

​RemoteAttachment

​MultiRemoteAttachment

​ReadReceipt

​TransactionReference

​WalletSendCalls

​GroupUpdated

​LeaveRequest

​Intent

​Actions

​System content types

​DeletedMessage

​Custom content types

​ContentCodec trait

​Implementing custom codecs

​Content type detection

​Fallback text

​Source code references

Overview

Standard content types

Text

Markdown

Reaction

Reply

Attachment

RemoteAttachment

MultiRemoteAttachment

ReadReceipt

TransactionReference

WalletSendCalls

GroupUpdated

LeaveRequest

Intent

Actions

System content types

DeletedMessage

Custom content types

ContentCodec trait

Implementing custom codecs

Content type detection

Fallback text

Source code references