Attachments

Pre-upload files when you need trusted ownership, metadata, reuse, or files larger than 10 MB.

1. Create an upload

const allocation = await relay.attachments.create({
  filename: "report.pdf",
  content_type: "application/pdf",
  size_bytes: bytes.byteLength,
});

curl -sS -X POST https://api.relayapp.im/v1/attachments \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filename":"report.pdf",
    "content_type":"application/pdf",
    "size_bytes":48291
  }'

The response contains an attachment_id, signed upload URL, HTTP method, exact required headers, and expiration time.

{
  "attachment_id":"01993d50-d263-7d6b-87ce-90aba89b7815",
  "upload_url":"https://api.relayapp.im/attachment-transfers/<token>",
  "download_url":"https://api.relayapp.im/attachment-transfers/<token>",
  "http_method":"PUT",
  "expires_at":"2026-08-29T06:35:00.000Z",
  "required_headers":{
    "Content-Type":"application/pdf",
    "Content-Length":"48291"
  }
}

2. Upload the raw bytes

await relay.attachments.upload(allocation, bytes);

curl -sS -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  -H "Content-Length: 48291" \
  --data-binary @report.pdf

Do not use multipart form data. The body length and Content-Type must match the allocation.

3. Send the Attachment

await relay.chats.messages.send(chatId, {
  message: {
    parts: [{
      type: "media",
      attachment_id: allocation.attachment_id,
    }],
  },
});

curl -sS -X POST "https://api.relayapp.im/v1/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message":{
      "parts":[{
        "type":"media",
        "attachment_id":"01993d50-d263-7d6b-87ce-90aba89b7815"
      }]
    }
  }'

Import a public media URL

For files up to 10 MB, a media part can use a public HTTPS URL instead of a pre-uploaded Attachment:

await relay.chats.messages.send(chatId, {
  message: {
    parts: [{
      type: "media",
      url: "https://cdn.yourdomain.com/report.pdf",
    }],
  },
});

curl -sS -X POST "https://api.relayapp.im/v1/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message":{
      "parts":[{
        "type":"media",
        "url":"https://cdn.yourdomain.com/report.pdf"
      }]
    }
  }'

Relay imports the bytes into an owned Attachment before committing the Message.

Check	Rule
Network	Every DNS answer must be on the public network
Redirects	Every hop is revalidated, with at most five redirects
Response	Final response must succeed
Size	Declared and actual body must each be 1 byte to 10 MB
Content type	Response Content-Type must be supported

Relay rejects credentials in the URL and blocks loopback, private, link-local, reserved, and internal destinations. A redirect cannot bypass these checks.

Media metadata

Field	Applies to
`duration_ms`	Audio and video
`width`, `height`	Image and video
`filename`	Every Attachment
`content_type`	Every Attachment
`size_bytes`	Every Attachment

Width and height must be supplied together.

Image formats

Relay accepts raster image formats including JPEG, PNG, GIF, HEIC, TIFF, BMP, and WebP. Relay rejects SVG.

This is a Relay content-safety decision. Reference material disagreed about SVG support, so Relay chose one explicit rule: accept WebP raster bytes and avoid SVG’s additional active-content and renderer surface.

Limits

Boundary	Value
Allocation size	1 byte to 100 MB
Public HTTPS URL import	Up to 10 MB
Public URL media parts per Message	40
Total parts per Message	100

Ownership

Only the Contact that allocated an Attachment can retrieve or send it. An Attachment can be reused across Messages, but it cannot be deleted after a Message or group photo references it. Signed transfer URLs are capabilities; keep them out of logs.

Introduction

Getting started

Messaging

Chats

Contacts

Agent events

Webhooks

WebSocket

Platform

Examples

1. Create an upload

2. Upload the raw bytes

3. Send the Attachment

Import a public media URL

Media metadata

Image formats

Limits

Ownership

​1. Create an upload

​2. Upload the raw bytes

​3. Send the Attachment

​Import a public media URL

​Media metadata

​Image formats

​Limits

​Ownership

​Related

1. Create an upload

2. Upload the raw bytes

3. Send the Attachment

Import a public media URL

Media metadata

Image formats

Limits

Ownership

Related