Messaging API FAQs Beta

The Messaging API is an additional service to Demand API that facilitates two-way communication between guests and accommodation partners through conversations associated with an accommodation and, where applicable, a reservation.

It supports sending and retrieving messages, retrieving conversation history, and exchanging file attachments.

The main capabilities are:

The Messaging API can help partners:

• Integrate guest and accommodation communication into their own systems.
• Keep messages associated with the relevant accommodation, conversation and reservation.
• Synchronise new messages by polling the latest-messages endpoint.
• Exchange files as part of a conversation.
• Retrieve conversation history when handling post-booking communication.

Authenticate requests using the credentials required for Demand API integrations.

• A valid API token.
• Your X-Affiliate-Id header.

You can access conversations available to your authenticated partner account.

Use the /messages/conversations endpoint to retrieve a conversation by providing the accommodation ID together with either:

• A conversation ID.
• A reservation ID.

Conversations are identified by a conversation ID. A conversation can also be associated with a reservation and an accommodation.

• When sending a message, provide the conversation ID and accommodation ID.
• When retrieving a conversation, you can use either the conversation ID or the reservation ID together with the accommodation ID.

• Guests – From the time of booking until 66 days after checkout or cancellation.
• Hosts – From the time of booking until 7 days after checkout or cancellation.

If a guest sends a message, hosts can reply for up to 14 days from the guest's message timestamp, even if this exceeds the 7-day post-checkout limit.

Conversations are automatically created upon reservation, if there is a pre-defined Welcome message in property configuration.

Conversation history is retained for 1 year.

Attachments follow separate retention rules (see Do attachments expire?).

You can use the Demand API Messaging Test Hotel (Accommodation ID: 13921698) in the sandbox environment.

This test hotel has preconfigured automated responses to simulate realistic messaging scenarios.

Test scenarios include:

• Booking and receiving a welcome message.
• Sending special requests and receiving automated responses (e.g., rejections for certain requests).

Use the messages/send endpoint and provide the following information:

• conversation – ID of the conversation.
• accommodation – ID of the accommodation.
• content – The message body.

You can optionally include attachments as an array of attachment IDs returned by the /messages/attachments/upload endpoint.

Use the messages/latest endpoint.

• The endpoint retrieves the most recent messages, including messages sent by the accommodation and the guest.
• By default, it returns up to 100 messages in reverse chronological order, with the newest message first.

Each message can include:

• The conversation and reservation information.
• The message ID.
• The sender and sender metadata.
• The message content.
• Attachment IDs.
• The message timestamp.

You can use this endpoint to synchronise messages or poll for updates.

Provide the accommodation ID together with either:

• The conversation ID.
• The reservation ID.

The response includes the conversation ID, reservation ID, messages and conversation participants.

After processing messages/latest, use messages/latest/confirm to confirm their receipt.

Provide the IDs of the messages you have successfully processed. Confirmation is required in order to receive new messages from /messages/latest.

The Messaging API is subject to the same rate limits as other Demand API endpoints.

Check the applicable Demand API limits and handle 429 Too Many Requests responses according to the general Demand API Error handling guidance.

Yes. Message content is treated as UTF-8 text.

Automatic translation is not provided; Partners should handle language selection and translation in their own systems where required.

Currently, polling via /messages/latest is the supported approach.

Webhooks or push notifications may be added in future releases (partners will be informed in advance).

Yes. You can upload a file and include the returned attachment ID in a message.

The attachment workflow is:

1. Upload a file using /messages/attachments/upload.
2. Add the returned attachment ID to the attachments array in /messages/send.
3. Retrieve attachment metadata using /messages/attachments/metadata.
4. Download the file using /messages/attachments/download.

Use the /messages/attachments/upload endpoint.

Provide the accommodation ID, conversation ID and file information, including:

• file_size
• file_name
• file_type
• file_content

The file content is provided in the request as a base64-encoded value. The response returns an attachment ID.

Upload each file separately using /messages/attachments/upload.

Then include the returned attachment IDs in the attachments array when calling /messages/send endpoint.

Use the /messages/attachments/metadata endpoint.

Provide the accommodation ID, conversation ID and attachment ID. The response includes metadata such as:

• File size.
• File name.
• File type.

Use the /messages/attachments/download endpoint.

Provide the accommodation ID, conversation ID and attachment ID. The response includes the file content in base64-encoded format.

• Unlinked attachments (uploaded but not sent in a message) are stored for 24 hours.
• Linked attachments (included in a message) are stored for 7–10 years.

No. The Messaging API does not currently support deleting attachments.

Yes. All files are automatically scanned by our internal virus-scanning gateway.

Yes. Files are uploaded in base64 format and stored securely.

You may store messages in your own system if you need to maintain a local conversation history or support message-related workflows.

If you store messages or attachments, apply appropriate access controls, security measures and data-retention policies.

Use the message IDs to detect messages that have already been processed. Confirm messages with /messages/latest/confirm after successfully processing them.