Skip to main content

Support attachments in your app built with XMTP

Status Status

Use the attachment and remote attachment content types to support attachments in your app. Remote attachments of any size can be sent using the RemoteAttachmentCodec and a storage provider.

Open for feedback

You're welcome to provide feedback by commenting on the Remote Attachment Content Type Proposal XIP.

Configure the content types

In some SDKs, the AttachmentCodec is already included in the SDK. If not, you can install the package using the following command:

In the JavaScript SDK, you need to import this package first.

npm i @xmtp/content-type-remote-attachment

After importing the package, you can register the codec.

import {
} from "@xmtp/content-type-remote-attachment";
// Create the XMTP client
const xmtp = await Client.create(signer, { env: "dev" });
xmtp.registerCodec(new AttachmentCodec());
xmtp.registerCodec(new RemoteAttachmentCodec());

Send a remote attachment

Load the file. This example uses a web browser to load the file:

//image is the uploaded[0];
const data = await new Promise((resolve, reject) => {
const reader = new FileReader();
reader.onload = () => {
if (reader.result instanceof ArrayBuffer) {
} else {
reject(new Error("Not an ArrayBuffer"));

Create an attachment object:

// Local file details
const attachment = {
filename: image?.name,
mimeType: image?.type,
data: new Uint8Array(data),

Use RemoteAttachmentCodec.encodeEncrypted to encrypt an attachment:

const encryptedEncoded = await RemoteAttachmentCodec.encodeEncrypted(
new AttachmentCodec(),

Upload an encrypted attachment anywhere where it will be accessible via an HTTPS GET request. For example, you can use or Thirdweb:

const { Web3Storage } = require("");

class Upload {
constructor(name, data) { = name; = data;

stream() {
const self = this;
return new ReadableStream({
start(controller) {

const upload = new Upload("uploadIdOfYourChoice", encryptedEncoded.payload);

const web3Storage = new Web3Storage({

const cid = await web3Storage.put([upload]);
const url = `https://${cid}`;

Now that you have a url, you can create a RemoteAttachment:

const remoteAttachment = {
url: url,
contentDigest: encryptedEncoded.digest,
salt: encryptedEncoded.salt,
nonce: encryptedEncoded.nonce,
secret: encryptedEncoded.secret,
scheme: "https://",
filename: attachment.filename,

Now that you have a remote attachment, you can send it:

await conversation.send(remoteAttachment, {
contentType: ContentTypeRemoteAttachment,

Receive, decode, and decrypt a remote attachment

Now that you can receive a remote attachment, you need a way to receive a remote attachment. For example:

if (message.contentType.sameAs(RemoteAttachmentContentType)) {
const attachment = await RemoteAttachmentCodec.load(message.content, client);

You now have the original attachment:

attachment.filename // => "screenshot.png"
attachment.mimeType // => "image/png", // => [the PNG data]

Once you've created the attachment object, you can create a preview to show in the message input field before sending:

const objectURL = URL.createObjectURL(
new Blob([Buffer.from(], {
type: attachment.mimeType,

const img = document.createElement("img");
img.src = objectURL;
img.title = attachment.filename;

Was the information on this page helpful?
powered by XMTP