Working with attachments

Use the Messaging API to manage image file attachments in guest and accommodation conversations. This guide explains how to upload attachments, retrieve metadata, and download previously shared files.

About attachments

Guests and partners can exchange image attachments to enhance post-booking communication.

This feature is especially helpful for clarifying issues, sharing arrival details, or providing supporting visuals.

Common use cases

This guide walks you through the available endpoints and best practices for working with attachments.

Available endpoints

Use the following endpoints to manage attachments:

File requirements and limitations

Before uploading files, keep the following constraints in mind:

Uploading an attachment

→ Use the /messages/attachments/upload endpoint to upload a file to a conversation.

Request parameters

All three identifiers are required to ensure that the attachment is correctly linked to the guest and booking context. This also helps enforce security and rate limiting.

You can obtain these IDs by retrieving existing messages or reservations using the relevant Messaging or Orders endpoints.

Example request

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

Example response

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

Recommendations for base64 files

Base64 encoding converts a file (such as an image) into a text format. This is useful for safely sending files in JSON requests or over systems that expect text—not binary data.

To send files via the Messaging API, you must convert your image to base64. You can either:

• Use an online tool encoder such as base64-image.

• Use your computer terminal app running:

  base64 -i your-image.jpg -o output.txt(for Linux or macOS)

  or for Windows:

  [Convert]::ToBase64String((Get-Content "C:\path\to\your-image.jpg" -Encoding Byte)) > output.txt

Retrieving attachment metadata

→ Use the messages/attachments/metadata endpoint to fetch metadata such as size, name, and type of an existing attachment.

Example request

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

Example response

The response will provide metadata about the file, such as its size, name, and type.

{
    "request_id": "4cf641d4-dc42-4970-a1e6-8f7fb6c8785f",
    "data": {
        "metadata": {
            "file_size": 95299,
            "file_name": "c82a5350-19fe-11f0-959e-1373654fdef5.png",
            "file_type": "image/png"
        }
    }
}

Downloading an attachment

→ Use the /messages/attachments/download endpoint with the appropriate conversation and attachment ID to download a previously uploaded attachment.

Example request

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

}

Example response

The file is returned as a base64-encoded string in the response body.

{
  "request_id": "773e2c0d-1ab3-449b-b88a-3d6b5ce09ae7",
  "data": {
    "conversation": "cc872746-77f2-5886-ba7c-17e0497241b5",
    "file_content": "/9j/4AAQSkZJRgABAQACWAJYAAD/2wCEAAgGBgc..."
  }
}

Error handling

The API returns descriptive error messages for invalid requests. Validate input data before submitting requests to prevent issues.

File size exceeded

Attempting to upload a file larger than 1 MB results in a 400 bad request error.

{
  "errors": [
    {
      "id": 400,
      "message": {
        "error": "bad request",
        "message": "File size exceeds the 1MB limit"
      }
    }
  ]
}

Mismatched file size

If the actual size of file_content does not match the declared file_size, a size mismatch error is returned.

Example request

The request below attempts to upload a file with a base64-encoded string, along with metadata describing the file's name, type, and size.

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

In this case, the file_size is set to 350 bytes, while the actual file content size, as indicated by the base64-encoded string, does not match this value.

Example response

The system identifies the discrepancy between the declared file size (file_size) and the actual size of the base64-encoded content (file_content).

As a result, the API returns a 400 Bad Request error with a detailed message.

{
    "request_id": "36a34bff-1353-4689-9169-3bcf361a4ff0",
    "errors": [
        {
            "id": 400,
            "message": {
                "error": "bad request",
                "message": "Request failed with code: 400, message: Content length is 35 but metadata size is 350"
            }
        }
    ]
}

How to fix it

To resolve this issue:

1. Verify the file content size - Ensure the size of the base64-encoded content matches the file size specified in the file_size.
2. Re-encode the file if necessary - If the file was manually encoded, verify the base64 string and re-encode the file to ensure the content and the metadata size align.
3. Update metadata - Adjust the file_size value to match the actual content length.

Security and access

• Attachments are securely stored and can only be accessed by parties involved in the conversation.
• Files are not publicly accessible and require valid credentials and matching conversation context.
• Attachments currently do not expire, but we recommend downloading them soon after upload.