# Attachments

Add images, video, audio, files, and interactive content to a message.

API 4.0 · 4.1

Attachments live in the `attachments` array of a message, alongside `text` or `block`. Each item is an `Attachment` object.

## Choose an attachment type

For media and documents, use **`type: "file"`**. The `mimetype` distinguishes an image, video, audio clip, or document; do not use `type: "image"` or `type: "video"` for these file examples.

| Content | Attachment `type` | Content field |
| --- | --- | --- |
| Image | `file` | `mimetype: "image/jpeg"` or another image MIME type. |
| Video | `file` | `mimetype: "video/mp4"`, for example. |
| Audio | `file` | `mimetype: "audio/mpeg"`, for example. |
| Document | `file` | `mimetype: "application/pdf"`, for example. |
| Link preview | `link` | `url`, `title`, and `description`. |
| Buttons | `button` | `buttons` array. |
| Quick replies | `quick_replies` | `quick_replies` array. |
| Cards | `generic` | `elements` array. |

These are common attachment shapes supported by the Subiz model and renderers. Destination channels can restrict formats, actions, and media. The examples use synthetic metadata and placeholder URLs; replace them with real assets before sending.

## File fields

| Field | Meaning |
| --- | --- |
| `url` | Source URL of the file. Use a URL Subiz can retrieve directly. |
| `mimetype` | MIME type, such as `image/jpeg`. Match the actual file content. |
| `name` | File name, including its extension when applicable. |
| `size` | File size in bytes. |
| `thumbnail_url` | Thumbnail URL, when available. |
| `width`, `height` | Image dimensions in pixels, when available. |
| `duration` | Audio or video duration in seconds, when available. |

Optional metadata can be omitted when unknown. Subiz processes file attachments and can replace the source URL and metadata with stored file information. Preserve the returned values instead of assuming the response matches the request exactly.

## Images

A JPEG image attachment:

```json
{
  "type": "file",
  "mimetype": "image/jpeg",
  "url": "https://example.com/photo.jpg",
  "name": "photo.jpg",
  "size": 245760,
  "width": 1200,
  "height": 800
}
```

PNG or GIF files use their actual MIME types, such as `image/png` or `image/gif`. Rendering and animation support depend on the destination.

## Video

An MP4 video attachment with a preview image:

```json
{
  "type": "file",
  "mimetype": "video/mp4",
  "url": "https://example.com/demo.mp4",
  "name": "demo.mp4",
  "thumbnail_url": "https://example.com/demo-preview.jpg",
  "size": 5242880,
  "duration": 30
}
```

`thumbnail_url` is a preview, not the video source. The video itself belongs in `url`. Container and codec support depend on the channel and player.

## Audio

An MP3 audio attachment:

```json
{
  "type": "file",
  "mimetype": "audio/mpeg",
  "url": "https://example.com/voice.mp3",
  "name": "voice.mp3",
  "size": 262144,
  "duration": 12
}
```

`duration` is measured in seconds, unlike the millisecond timestamps used by events. Other audio files must use their correct MIME type.

## Documents and other files

A downloadable PDF attachment:

```json
{
  "type": "file",
  "mimetype": "application/pdf",
  "url": "https://example.com/guide.pdf",
  "name": "guide.pdf",
  "size": 2048
}
```

For other documents, keep `type: "file"` and use the matching MIME type and file name. A document attachment is not a block node.

## Link previews

Use `link` for a separate preview rather than a link embedded in formatted text:

```json
{
  "type": "link",
  "url": "https://example.com/delivery",
  "title": "Delivery guide",
  "description": "Delivery options and estimated timelines."
}
```

For a labeled link inside a sentence, use a [link block](/developers/messages/formats#links-inside-a-block) instead.

## Buttons

A `button` attachment contains a `buttons` array. This example uses a `MessageButton` with `type: "url_button"`:

```json
{
  "type": "button",
  "buttons": [
    {
      "type": "url_button",
      "title": "View delivery guide",
      "url": "https://example.com/delivery"
    }
  ]
}
```

The button's visible label is `title`, and its destination is `url`. Support for button actions depends on the channel.

## Quick replies

A `quick_replies` attachment offers suggested responses. Each `QuickReply` has a visible `title`; `payload` carries your application-specific value:

```json
{
  "type": "quick_replies",
  "quick_replies": [
    {
      "content_type": "text",
      "title": "Track my order",
      "payload": "track_order"
    },
    {
      "content_type": "text",
      "title": "Talk to support",
      "payload": "contact_support"
    }
  ]
}
```

These payload strings are example values for your integration, not built-in Subiz commands. Receiving and handling the selection depends on the channel; do not assume it arrives as an ordinary text message.

## Cards

A `generic` attachment contains an `elements` array. Each `GenericElementTemplate` can have a title, subtitle, image, and buttons:

```json
{
  "type": "generic",
  "elements": [
    {
      "title": "Delivery options",
      "subtitle": "Choose the delivery service for your order.",
      "image_url": "https://example.com/delivery.jpg",
      "buttons": [
        {
          "type": "url_button",
          "title": "See options",
          "url": "https://example.com/delivery"
        }
      ]
    }
  ]
}
```

The schema supports multiple elements, but the destination determines how many it accepts and how it displays them. This page does not define a universal card or button limit.

## Send an attachment

Wrap the attachment in `data.message.attachments` and send it to an existing conversation. The text and the image are part of the same message:

```http
POST https://api.subiz.com.vn/4.1/conversations/YOUR_CONVERSATION_ID/messages
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "type": "message_sent",
  "data": {
    "message": {
      "format": "plaintext",
      "text": "Here is the product photo.",
      "attachments": [
        {
          "type": "file",
          "mimetype": "image/jpeg",
          "url": "https://example.com/photo.jpg",
          "name": "photo.jpg",
          "size": 245760,
          "width": 1200,
          "height": 800
        }
      ]
    }
  }
}
```

The example URLs are placeholders. Use a retrievable HTTPS file URL, not a local path, browser `blob:` URL, or a page that requires your browser's login. Check that the actual file is available before sending.

See [Send to a conversation](/developers/api-reference/messages/send) for the endpoint and [Message formats](/developers/messages/formats) for combining attachments with text or a block.

## Read attachment payloads

Process every item in `attachments`. For file attachments, inspect `mimetype`; for structured attachments, inspect `type` before reading nested fields. A message with no text may still contain an image, audio, or a document.

The wider schema also includes channel-specific and application-specific attachments. Preserve types your integration does not recognize instead of treating every attachment as a file. Refer to [webhook payloads](/developers/webhooks/payloads) when consuming message events.