Understand content types with XMTP

XMTP application messages carry a content type. The type tells an app how to decode the payload.

The payload is bytes. It can carry text, JSON, or binary content. Apps must agree on the type and its encoding.

Content type reference

Every content type ID has the form authorityId/typeId:versionMajor.versionMinor. The encoded envelope contains the type ID, parameters, content bytes, and optional fallback text. shouldPush is a send option, separate from the content envelope. The table gives each type’s default. An explicit send option can override that default.

Content type	Type ID	Wire payload	Fallback	Default shouldPush
Text	xmtp.org/text:1.0	UTF-8 bytes and an encoding parameter	None	true
Markdown	xmtp.org/markdown:1.0	UTF-8 bytes and an encoding parameter	None	true
Reply	xmtp.org/reply:1.0	Nested EncodedContent; reference parameters	Describes the reply	true
Reaction	xmtp.org/reaction:2.0	ReactionV2 protobuf	Describes the reaction	false
Read receipt	xmtp.org/readReceipt:1.0	Empty	None	false
Attachment	xmtp.org/attachment:1.0	Raw bytes; MIME type and file name parameters	Names the unsupported file	true
Remote attachment	xmtp.org/remoteStaticAttachment:1.0	URL bytes and decryption parameters	Names the unsupported file	true
Multiple remote attachments	xmtp.org/multiRemoteStaticAttachment:1.0	MultiRemoteAttachment protobuf	Describes unsupported attachments	true
Group update	xmtp.org/group_updated:1.0	GroupUpdated protobuf	None	false
Transaction reference	xmtp.org/transactionReference:1.0	JSON-encoded TransactionReference	Describes the transaction	true
Wallet send calls	xmtp.org/walletSendCalls:1.0	JSON-encoded WalletSendCalls	Describes the request	true
Delete message	xmtp.org/deleteMessage:1.0	DeleteMessage protobuf	None	false
Leave request	xmtp.org/leave_request:1.0	LeaveRequest protobuf	None	false
Actions	coinbase.com/actions:1.0	JSON-encoded Actions	Numbered action list	true
Intent	coinbase.com/intent:1.0	JSON-encoded Intent	Names the selected action	true

Browser, Node, Kotlin, and Swift include these standard codecs. Core decodes standard content without app registration. Register codecs only for custom content that your app receives. A codec matches the authority, type ID, and major version; the minor version is not part of this match.

Node exports standalone codecs from @xmtp/node-sdk. Browser exports them from @xmtp/browser-sdk/pure; call initPureWasm() before you use them. Kotlin and Swift expose typed codec wrappers over the same Rust encoders and decoders.

Group updates are local transcripts produced from commits. Apps cannot publish a group-update transcript as an application message. Delete messages are control messages; Core applies authorized deletion and exposes the result as deleted-message content. Use the SDK delete methods to request deletion.

Fallback and unsupported content

When building with XMTP, you can’t know in advance whether a recipient’s app will support a given content type, especially a custom one. Likewise, your own app might receive messages with content types it doesn’t support.

To prevent a poor user experience or app crashes, you should use the fallback property.

For sending: When sending a message with a custom content type, always provide a fallback string. This string offers a human-readable representation of the content. If the recipient’s app doesn’t support your custom type, it can display the fallback text instead.

For receiving: When your app receives a message, check if it supports the message’s contentType. If not, render the fallback text.

Some background types, such as read receipts, have no fallback. A renderer can skip them. Do not assume that message.content is missing for an unsupported type. Browser and Node expose a content union with unknown and custom variants. Kotlin and Swift expose SDKMessageContent with standard, custom, and unknown variants. Raw bytes and decode errors remain available.

These examples show a text-only renderer. It shows text, skips read receipts, and uses fallback text for other content. Extend it with the types your app can display.

Browser

import type { Message } from "@xmtp/browser-sdk";

export function displayText(message: Message): string | undefined {
  switch (message.content.kind) {
    case "text":
      return message.content.value;
    case "readReceipt":
      return undefined;
    default:
      return message.fallback;
  }
}

Node

import type { Message } from "@xmtp/node-sdk";

export function displayText(message: Message): string | undefined {
  switch (message.content.kind) {
    case "text":
      return message.content.value;
    case "readReceipt":
      return undefined;
    default:
      return message.fallback;
  }
}

Kotlin

import uniffi.xmtp_sdk.Message
import uniffi.xmtp_sdk.MessageContent
import uniffi.xmtp_sdk.SDKMessageContent

fun displayText(message: Message): String? {
    val content = message.content
    if (content is SDKMessageContent.Standard) {
        return when (val value = content.value) {
            is MessageContent.Text -> value.v1
            is MessageContent.ReadReceipt -> null
            else -> message.fallback
        }
    }
    return message.fallback
}

Swift

import XmtpSdk

func displayText(_ message: Message) -> String? {
    switch message.content {
    case let .standard(.text(text)):
        return text
    case .standard(.readReceipt):
        return nil
    default:
        return message.fallback
    }
}

Custom content types

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

Writing custom codecs

A content type needs a codec which must satisfy the ContentCodec interface from @xmtp/node-sdk or @xmtp/browser-sdk.

Example:

import type {
  ContentCodec,
  ContentTypeId,
  EncodedContent,
} from "@xmtp/node-sdk";

// Define the content type identifier.
export const CustomContentType: ContentTypeId = {
  authorityId: "your-domain.com",
  typeId: "your-custom-id",
  versionMajor: 1,
  versionMinor: 0,
};

// Implement a codec for string values.
export class CustomCodec implements ContentCodec<string> {
  readonly type = CustomContentType;

  encode(content: string): EncodedContent {
    return {
      type: this.type,
      parameters: new Map(),
      content: new TextEncoder().encode(content),
      fallback: content,
    };
  }

  decode(content: EncodedContent): string {
    return new TextDecoder().decode(content.content);
  }

  fallback(content: string): string | undefined {
    return content;
  }

  shouldPush(): boolean {
    return false;
  }
}

Registering custom codecs

Pass custom codec instances in the codecs option to Browser or Node Client.create(), or to Agent.create(). Kotlin and Swift accept a codecs argument on SDKClient.create(). Registration decodes incoming custom content. To send a custom value, pass the codec and value to a typed send method.

This example registers a codec with an agent:

import { Agent } from "@xmtp/agent-sdk";

// Set XMTP_WALLET_KEY and XMTP_BACKEND_URL before this program runs.
const agent = await Agent.createFromEnv({
  codecs: [new CustomCodec()],
});