Manage attachments

Use the Messaging API to upload, send and retrieve image attachments in existing conversations between guests and properties.

This guide explains how to:

• Upload an image and retrieve its attachment ID.
• Include uploaded images when sending messages.
• Retrieve attachment metadata.
• Download and decode image attachments.

The Messaging API supports image attachments in existing conversations.

Common scenarios include:

Attachments are associated with an existing conversation, identified by its conversation ID and accommodation ID.

You can obtain these identifiers using /messages/latest or /messages/conversations.

Use the following endpoints to manage attachments:

Make sure you have:

• Valid Demand API credentials.
• Your affiliate identifier (X-Affiliate-Id).
• Access to the Messaging API.
• An existing conversation ID and its associated accommodation ID.
• An image that meets the supported file requirements.

All Messaging API requests require Bearer authentication and the X-Affiliate-Id header.

Before uploading an attachment, validate the following requirements:

→ Use /messages/attachments/upload to upload an image to an existing conversation.

The endpoint accepts the image as a base64-encoded string and returns an attachment ID.

Before uploading:

1. Verify that the file is a supported PNG or JPEG image.
2. Check that its original size does not exceed 1,048,576 bytes.
3. Encode the file content in base64.
4. Record the original file name, MIME type and binary file size.

You can encode the image locally using your preferred programming language or command-line tool.

For example, using Python:

import base64
from pathlib import Path

file_path = Path("example_image.png")

file_bytes = file_path.read_bytes()

file_size = len(file_bytes)

file_content = base64.b64encode(file_bytes).decode("ascii")

print("File size:", file_size)
print("Base64 content:", file_content)

Use the resulting values in the upload request:

• file_size: Original file size in bytes.
• file_content: Base64-encoded image content.

Send a POST request to /messages/attachments/upload.

Request

POST messages/attachments/upload

The request requires the following fields:

Example request

{
  "accommodation": "6819547",
  "conversation": "cc872746-77f2-5886-ba7c-17e0497241b5",
  "file_name": "example_image.png",
  "file_type": "image/png",
  "file_size": 35,
  "file_content": "iVBORw0KGgoAAAANSUhEUgAAADAAAABAgMAAADW0NTUAAAA"
}

The file_content value above is an illustrative, shortened base64 string. In a real request, provide the complete encoded image and its actual binary size.

Example response

{
  "request_id": "25539c17-59e6-4465-ad85-d0a517a474c5",
  "data": {
    "attachment": "c82a5350-19fe-11f0-959e-1373654fdef5"
  }
}

A successful request returns HTTP 200 OK.

The data.attachment field contains the unique identifier of the uploaded attachment.

Save this ID. You'll need it to send the attachment, retrieve its metadata or download it.

Uploading an image does not automatically send it to the guest or property.

→ Use /messages/send to send a message containing the uploaded attachment.

Request

POST /messages/send

Include the attachment ID in the attachments array.

{
  "accommodation": "6819547",
  "conversation": "cc872746-77f2-5886-ba7c-17e0497241b5",
  "content": "Please see the attached image.",
  "attachments": [
    "c82a5350-19fe-11f0-959e-1373654fdef5"
  ]
}

Example response

{
  "request_id": "cdb0b154-2eae-481b-8fee-fb2725296e1f",
  "data": {
    "message": "3164e570-19e0-11f0-baca-e5019c8df435"
  }
}

The response returns the ID of the newly sent message.

To include multiple images in one message:

1. Upload each image separately using /messages/attachments/upload.
2. Collect the attachment IDs returned by the API.
3. Include those IDs in the attachments array of the /messages/send request.

For example:

{
  "accommodation": "6819547",
  "conversation": "cc872746-77f2-5886-ba7c-17e0497241b5",
  "content": "Here are the images you requested.",
  "attachments": [
    "c82a5350-19fe-11f0-959e-1373654fdef5",
    "695b7f90-2c08-11f0-9cee-134ca9b067d1"
  ]
}

For more information about sending messages, see Manage messages.

→ Use /messages/attachments/metadata to retrieve information about an existing attachment.

The endpoint returns the file name, MIME type and size.

Request

POST /messages/attachments/metadata

Provide the accommodation, conversation and attachment identifiers.

{
  "accommodation": "6819547",
  "conversation": "cc872746-77f2-5886-ba7c-17e0497241b5",
  "attachment": "c82a5350-19fe-11f0-959e-1373654fdef5"
}

Example response

{
  "request_id": "4cf641d4-dc42-4970-a1e6-8f7fb6c8785f",
  "data": {
    "metadata": {
      "file_size": 95299,
      "file_name": "example_image.png",
      "file_type": "image/png"
    }
  }
}

The response contains:

→ Use /messages/attachments/download to retrieve the content of an attachment associated with an existing conversation.

The API returns the file content as a base64-encoded string.

Request

POST /messages/attachments/download

{
  "accommodation": "6819547",
  "conversation": "cc872746-77f2-5886-ba7c-17e0497241b5",
  "attachment": "c82a5350-19fe-11f0-959e-1373654fdef5"
}

Example response

{
  "request_id": "773e2c0d-1ab3-449b-b88a-3d6b5ce09ae7",
  "data": {
    "conversation": "cc872746-77f2-5886-ba7c-17e0497241b5",
    "file_content": "/9j/4AAQSkZJRgABAQACWAJYAAD/2wCEAAgGBgc...",
    "attachment": "c82a5350-19fe-11f0-959e-1373654fdef5"
  }
}

The response contains:

The file_content value in this example is shortened for readability.

Decode the base64 string to restore the original image.

For example, using Python:

import base64
from pathlib import Path

encoded_content = response["data"]["file_content"]

file_bytes = base64.b64decode(encoded_content)

Path("downloaded_image.jpg").write_bytes(file_bytes)

In this example, response represents the parsed JSON response returned by /messages/attachments/download.

Use the file name and MIME type returned by /messages/attachments/metadata to determine the appropriate file extension and how to handle the downloaded content.

If an attachment request fails, validate the request fields and file requirements before retrying.

For general error-handling guidance, see HTTP 4xx scenarios.

The following request declares a file size of 350 bytes, but the supplied base64 content does not represent a file of that size.

{
  "accommodation": "6819547",
  "conversation": "cc872746-77f2-5886-ba7c-17e0497241b5",
  "file_content": "iVBORw0KGgoAAAANSUhEUgAAADAAAABAgMAAADW0NTUAAAA",
  "file_name": "example_image.png",
  "file_type": "image/png",
  "file_size": 350
}

If the API validates the declared file size against the decoded content, the mismatch can cause the request to fail.

To resolve the issue:

1. Check that the base64 content is complete.
2. Decode the content or inspect the original binary file to determine its actual size.
3. Update file_size to match the original binary size.
4. Retry the upload with valid file content and metadata.

Follow these recommendations when managing attachments:

✅ Validate before uploading: Check the image format, MIME type and original file size before encoding.

✅ Use the correct conversation context: Include the accommodation and conversation identifiers associated with the attachment.

✅ Store attachment IDs: Retain the identifiers needed to send messages and retrieve attachments.

✅ Handle base64 securely: Avoid logging or exposing encoded file content, as it contains the complete attachment data.

✅ Process downloaded files safely: Validate downloaded content before storing or displaying it.

✅ Follow data-protection requirements: Apply appropriate access controls and retention policies to stored attachments.

✅ Handle errors appropriately: Validate requests before retrying and follow the applicable API rate limits.