handling-attachments

name	handling-attachments
description	File attachment handling for XMTP agents. Use when sending or receiving images, files, or any encrypted remote attachments. Triggers on file upload, image sending, or remote attachment handling.
license	MIT
metadata	{"author":"xmtp","version":"1.0.0"}

XMTP attachments

Handle file attachments using encrypted remote attachments. Files are encrypted locally, uploaded to your storage provider, and sent as a remote attachment message.

When to apply

Reference these guidelines when:

• Sending files or images from an agent
• Receiving and downloading attachments
• Implementing custom upload storage
• Working with encrypted file transfers

Rule categories by priority

Priority	Category	Impact	Prefix
1	Send	CRITICAL	send-
2	Receive	CRITICAL	receive-
3	Upload	HIGH	upload-

Quick reference

Send (CRITICAL)

• send-remote-attachment - Send encrypted file attachments

Receive (CRITICAL)

• receive-attachment - Download and decrypt attachments

Upload (HIGH)

• upload-callback - Implement custom upload storage (Pinata, S3, etc.)

Quick start

import { type AttachmentUploadCallback } from "@xmtp/agent-sdk/util";

// Send an attachment
const file = new File(["Hello, World!"], "hello.txt", { type: "text/plain" });
await ctx.conversation.sendRemoteAttachment(file, uploadCallback);

// Receive an attachment
agent.on("attachment", async (ctx) => {
  const attachment = await downloadRemoteAttachment(ctx.message.content, agent);
  console.log(`Received: ${attachment.filename}`);
});

How to use

Read individual rule files for detailed explanations:

rules/send-remote-attachment.md
rules/receive-attachment.md
rules/upload-callback.md