Use content types

All messages in XMTP are encoded with a content type to ensure interoperability and consistency of experience across the XMTP network.

Two standard content types come bundled with the XMTP client SDK:

1. xmtp.org/text:1.0, which defines a default TextCodec for plain text content

   To learn more about this text content type, see XIP-5.

2. xtmp.org/composite:1.0, which defines an optional CompositeCodec for multiple content types in a single message

   To learn more about this composite content type, see XIP-9.

For these standard content types, xmtp.org is the authorityId value. xmtp.org is reserved for use as the authorityId for standard content types. Standard content types are those that have been adopted through the XMTP Improvement Proposal (XIP) process.

caution

Do not use xmtp.org as the authorityId for a custom content type that you create for your app. Instead, consider using a unique DNS domain or ENS name that can be widely recognized as belonging to your app. For example, frenz.xyz.

To learn more about authorityId and other parameters in a content type identifier, see Content Type Identifier and Parameters.

To learn more about the difference between standard and custom content types, see Content types with XMTP.

Send plain text messages using the TextCodec standard 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.

Send multiple content types in a message using the CompositeCodec standard 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.

info

While XMTP supports the CompositeCodec standard content type, the app reading the composite message must support the content types used in the composite message to be able to display them.

Import the CompositeCodec standard content type

Import the CompositeCodec content type from the xmtp-js client SDK to make it available in your app. For example:

import { CompositeCodec } from '@xmtp/xmtp-js'

Tag a message with the CompositeCodec standard content type

To enable a message API client to know to use the CompositeCodec content type to encode and decode a message, tag the message with the content type.

To do this, pass the CompositeCodec content type as an option to the Client.create() method. This configures the message API client instance to use CompositeCodec when encoding and decoding messages. For example:

const xmtp = Client.create(wallet, { codecs: [new CompositeCodec()] })

Send a custom content type

You can use xmtp-js to specify and send a custom content type beyond the standard TextCodec and CompositeCodec content types.

info

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.

caution

Do not use xmtp.org as the authorityId for a custom content type that you create for your app. xmtp.org is reserved for use as the authorityId for standard content types only.

To learn more about authorityId and other parameters in a content type identifier, see Content Type Identifier and Parameters.

To send a custom content type:

1. Specify a custom content type to enable during client initialization.

   // Adding support for a fictional `frenz.xyz/number` content type
   import { NumberCodec } from '@xmtp/xmtp-js'
   const xmtp = Client.create(wallet, { codecs: [new NumberCodec()] })

   This example enables a fictional "number" custom content type in the form of NumberCodec.

   The predefined TextCodec content type supports numbers in a text string, such as "Pi is the number 3.14." However, TextCodec doesn't support a number outside a text string, such as 3.14. To handle this number, you can specify this "number" custom content type.

   This snippet registers the NumberCodec custom content type with the sending client. During the registration process, the sending client automatically associates the codec with the content type it says it supports. For example, NumberCodec might say that it supports the ContentTypeNumber content type.

2. Send a message using the specified custom content type and fallback plain text.

   // Assuming NumberCodec can be used to encode numbers and is
   // identified with ContentTypeNumber, you can use it as follows.
   conversation.send(3.14, {
     contentType: ContentTypeNumber,
     contentFallback: '3.14'
   })

   This example sends a message using the fictional "number" custom content type, including fallback plain text.

   The receiving client uses the contentType value of ContentTypeNumber to identify the content type of the 3.14 message sent through the send API. If the receiving client supports the content type, it displays the message. If it doesn't support the content type, it displays the fallback plain text.

   To learn more about the send API, see Sending messages.

To learn more about sending custom content types, see Different content types.