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 applications, which could result in it being overlooked or only its fallback text being displayed.

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

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