Manage attachments

Use the Messaging API to manage image attachments in guest and accommodation conversations.

Enhance post-booking communication by uploading, sending, and retrieving images securely.

About attachments

Attachments allow guests and hosts to exchange images for:

• Clarifying issues (e.g., broken furniture, unclean rooms)
• Sharing arrival details.
• Providing supporting visuals (e.g., documents or photos)

Common scenarios

Available endpoints

Use the following endpoints to manage attachments:

File requirements and limitations

Before uploading images, keep the following constraints in mind:

Uploading an attachment

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

Required parameters

All three identifiers are required to ensure that the attachment is correctly linked to the guest and booking context:

Example request

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

Example response

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

Base64 recommendations

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.

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.

Example - File too large

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

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

Fix: Compress or resize image before uploading.

Example - 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.

Best Practices

• Validate file size before encoding.
• Upload only relevant images.
• Cache downloads if multiple retrievals are needed.
• Keep Base64 content secure; do not share publicly.