Build custom content types for use with XMTP

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

JavaScript

// A test of this content type can be found in the following PR: https://github.com/xmtp/xmtp-js/pull/509/files
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(
      content
    )}`
    // 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.

JavaScript

import { ContentTypeMultiplyNumberCodec } from "./xmtp-content-type-multiply-number";
 
const client = await Client.create({
  env: "production",
  codecs: [new ContentTypeMultiplyNumberCodec()],
});
//or
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.

JavaScript

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.

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

JavaScript

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