SubizDeveloper Docs
Conversations & Messages

API 4.0 · 4.1

Attachments

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

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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.

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

{
  "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 instead.

Buttons

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

{
  "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:

{
  "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:

{
  "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:

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 for the endpoint and Message 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 when consuming message events.