Messaging API FAQs

The Messaging API is an additional Demand API service that enables affiliate partners to exchange messages between guests and properties through existing conversations.

You can use it to retrieve conversations, send and receive messages, confirm message receipt and exchange image attachments.

For an overview of its capabilities, see About the Messaging API.

The Messaging API is available with Demand API v3.3 Stable.

No. The Messaging API supports sending messages to and retrieving existing conversations. It does not provide an endpoint for creating new conversations.

Conversations are associated with an accommodation and may also be associated with a reservation.

Use /messages/conversations to retrieve an existing conversation.

All Messaging API requests require:

• A valid Bearer authentication token.
• Your affiliate identifier in the X-Affiliate-Id header.

For authentication instructions, see Authentication.

You can retrieve conversations available to your authenticated affiliate account.

To retrieve a specific conversation, provide the accommodation ID together with either the conversation ID or the reservation ID.

If a conversation cannot be retrieved, verify that the identifiers are correct and that the conversation is available to your affiliate account.

Yes. Use the Demand API sandbox environment:

https://demandapi-sandbox.booking.com

The Demand API Messaging Test Hotel (accommodation ID 13921698) is configured for testing messaging scenarios, including automated welcome messages and responses to selected guest requests.

Follow the Messaging API quick guide to create a test reservation and retrieve your first message.

Each identifier serves a different purpose:

The exact response field depends on the endpoint. For example, /messages/latest returns the message identifier as id, while /messages/send returns it as data.message.

Use /messages/conversations.

Provide:

• accommodation: The accommodation ID.
• reservation: The reservation ID.

Alternatively, provide accommodation and conversation if you already know the conversation ID.

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

For an example, see Use case 1 – Booking and welcome message.

Use the sender information returned by the API.

In /messages/latest, each message includes a sender object containing:

• participant: Unique identifier of the sender.
• metadata.type: Indicates whether the sender is a guest or property.
• metadata.name: Display name of the sender, when available.

In /messages/conversations, each message contains a sender ID that can be matched to the conversation's participants array.

Use /messages/send.

Provide the following required fields:

• accommodation: The accommodation ID.
• conversation: The existing conversation ID.
• content: The plain-text message.

You can optionally include an attachments array containing previously uploaded attachment IDs.

A successful response returns the sent message's identifier in data.message.

For an implementation example, see Manage messages.

No. The /messages/send endpoint requires a conversation ID.

If you only have the reservation ID, first call /messages/conversations with the accommodation and reservation IDs.

Use the returned data.conversation.id when sending the message.

Use /messages/latest.

Send a POST request with an empty JSON object:

{}

The endpoint retrieves recent messages sent by both guests and properties.

By default, it returns up to 100 messages in reverse chronological order, with the newest messages first.

Each message can include its ID, content, sender, timestamp, attachment IDs and associated conversation information.

No. The endpoint retrieves recent messages available to your affiliate account and is not restricted to a single reservation.

Each returned message includes conversation information that can identify:

• The conversation ID.
• The accommodation ID.
• The reservation ID, when available.

Use these identifiers to associate messages with the correct reservation in your system.

To retrieve the history of a specific conversation, use /messages/conversations.

Use /messages/latest to poll for recent messages.

A typical synchronisation workflow is:

1. Retrieve messages using /messages/latest.
2. Process the messages in your application.
3. Confirm receipt using /messages/latest/confirm.
4. Continue polling for subsequent messages.

Confirmation is required to continue receiving new messages through /messages/latest.

Follow the applicable Demand API rate limits when implementing polling.

The current Messaging API schema provides /messages/latest for retrieving recent messages.

It does not define a webhook or push-notification endpoint for new messages.

Use polling and receipt confirmation to synchronise messages with your application.

The Messaging API requires confirmation of messages retrieved through /messages/latest before your integration can continue receiving new messages.

After successfully processing messages, use /messages/latest/confirm and provide their message IDs.

Confirming receipt helps your application manage message synchronisation.

The /messages/latest/confirm response includes a confirmedMessages array containing the IDs of messages confirmed by the API.

Compare the returned IDs with those submitted in your request.

If a message ID is missing from confirmedMessages, do not assume that its receipt was confirmed. Investigate the result before marking the message as confirmed in your system.

No. The /messages/latest/confirm endpoint confirms receipt of messages retrieved by your integration.

It does not provide a guest read receipt or indicate whether a guest has opened or read a message.

Use the unique message ID to identify messages your application has already processed.

Store processed message IDs as needed to prevent duplicate processing.

Confirm messages only after successfully processing them, and check the confirmedMessages response before marking them as confirmed.

The Messaging API supports PNG and JPEG images.

The file size limit applies to the original binary file, before base64 encoding.

Other file formats, such as PDFs and videos, are not supported by the current attachment schema.

Follow these steps:

1. Upload the image using /messages/attachments/upload.
2. Retrieve the attachment ID from data.attachment.
3. Include the attachment ID in the attachments array when calling /messages/send.

Uploading an image does not automatically send it as a message.

For detailed instructions, see Manage attachments.

Yes. Upload each image separately using /messages/attachments/upload.

Then include the returned attachment IDs in the attachments array of your /messages/send request.

Each uploaded image must meet the supported format and file size requirements.

Use /messages/attachments/metadata.

Provide the accommodation ID, conversation ID and attachment ID.

The response includes:

• file_name: Original file name.
• file_type: MIME type of the attachment.
• file_size: Size of the attachment in bytes.

The metadata response does not contain the file itself.

Use /messages/attachments/download.

Provide the accommodation ID, conversation ID and attachment ID.

The response includes the base64-encoded file content in data.file_content, together with the conversation and attachment identifiers.

Decode the base64 content to restore the original file.

For implementation examples, see Manage attachments.

No. The current Messaging API collection does not provide an endpoint for deleting attachments.

If you store downloaded attachments in your own systems, manage their retention and deletion according to your applicable data-protection requirements.

Check the following:

• Message confirmation: Verify that previously processed messages have been confirmed using /messages/latest/confirm.
• Conversation context: Check whether the expected message belongs to a conversation available to your affiliate account.
• Message availability: Confirm that a new message has been sent. Automated responses might not be available immediately.
• Authentication: Verify your Bearer token and X-Affiliate-Id.
• API errors: Review the HTTP status code and response details.

For additional guidance, see Messaging troubleshooting.

Compare the submitted message IDs with the confirmedMessages array returned by /messages/latest/confirm.

If an ID is missing:

1. Check the API response for errors.
2. Keep the message's processing and confirmation states separate.
3. Do not mark the message as confirmed until confirmation has been established.
4. Follow the applicable error-handling and retry guidance.

Follow the applicable Demand API rate limits when sending requests or polling for messages.

If you receive HTTP 429 Too Many Requests, apply the recommended rate-limit handling and retry strategy.

For more information, see Error handling.

You can store messages and attachments when necessary to support your application's communication workflows.

If you do, apply appropriate:

• Access controls and security measures.
• Data-retention and deletion policies.
• Protection of guest and reservation information.
• Duplicate detection using message IDs.

Avoid storing sensitive message content or base64-encoded attachments in application logs.