Working with attachments

This guide outlines how to manage file attachments within the Messaging API, including uploading, retrieving metadata, and downloading attachments linked to conversations.

About attachments

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

This is particularly useful for clarifying issues, sharing logistical details, or providing important visual information.

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 restrictions

Keep the following in mind when working with attachments:

Uploading an attachment

To upload a file to a conversation, use the messages/attachments/upload endpoint.

Request parameters

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"
    }
}

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 appropiate 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 response includes the binary content of the file.

This is returned as a base64-encoded string.

Error handling

The API returns detailed error responses for invalid requests.

Always validate inputs and handle errors gracefully.

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"
            }
        }
    ]
}

Resolving the error

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.