Skip to main content

Build custom content types for use with XMTP


Be aware that your custom content type may not be automatically recognized or supported by other apps, which could result in the other apps overlooking or only displaying the fallback text for your custom content type.

Building a custom content type enables you to manage data in a way that is more personalized or specialized to the needs of your app.

For more common content types, you can usually find a standard or standards-track content type to serve your needs.

If your custom content type generates interest within the developer community, consider proposing it as a standard content type through the XIP process.

Create the content type

Create the custom content type by creating a new file

A test of this content type can be found in the following PR

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

// Create a unique identifier for your content type
export const ContentTypeMultiplyNumbers = new ContentTypeId({
authorityId: 'your.domain',
typeId: 'multiply-number',
versionMajor: 1,
versionMinor: 0,

// Define the MultiplyNumbers class
export class MultiplyNumbers {
public num1: number
public num2: number
public result: number | undefined

constructor(num1: number, num2: number, result?: number) {
this.num1 = num1
this.num2 = num2
this.result = result

// Define the MultiplyCodec class
export class ContentTypeMultiplyNumberCodec
implements ContentCodec<MultiplyNumbers>
get contentType(): ContentTypeId {
return ContentTypeMultiplyNumbers

// The encode method accepts an object of MultiplyNumbers and encodes it as a byte array
encode(numbers: MultiplyNumbers): EncodedContent {
const { num1, num2 } = numbers
return {
type: ContentTypeMultiplyNumbers,
parameters: {},
content: new TextEncoder().encode(JSON.stringify({ num1, num2 })),

// The decode method decodes the byte array, parses the string into numbers (num1, num2), and returns their product
decode(encodedContent: EncodedContent): MultiplyNumbers {
const decodedContent = new TextDecoder().decode(encodedContent.content)
const { num1, num2 } = JSON.parse(decodedContent)
return new MultiplyNumbers(num1, num2, num1 * num2)

fallback(content: MultiplyNumbers): string | undefined {
return `Can’t display number content types. Number was ${JSON.stringify(
// return undefined to indicate that this content type should not be displayed if it's not supported by a client

// Set to true to enable push notifications for interoperable content types.
// Receiving clients must handle this field appropriately.
shouldPush(): boolean {
return true;

Configure the content types

Import and register the custom content type.

import { ContentTypeMultiplyNumberCodec } from "./xmtp-content-type-multiply-number";

const client = await Client.create({
env: "production",
codecs: [new ContentTypeMultiplyNumberCodec()],
client.registerCodec(new ContentTypeMultiplyNumberCodec());

Send the content

Send a message using the custom content type. This code sample demonstrates how to use the MultiplyCodec custom content type to perform multiplication operations.

const numbersToMultiply = new MultiplyNumbers(2, 3);

conversation.send(numbersToMultiply, {
contentType: ContentTypeMultiplyNumbers,

Receive the content

To use the result of the multiplication operation, add a renderer for the custom content type.

if (message.contentType.sameAs(ContentTypeMultiplyNumber)) {
return message.content; // 21

To handle unsupported content types, refer to the fallback section.

Was the information on this page helpful?
powered by XMTP