Messaging API FAQs

Find answers to the most common questions regarding payment methods, timings, and more.

General overview

What is the Booking.com Messaging API?

The Messaging API facilitates structured, two-way communication between guests and accommodation hosts, tied to specific reservations. It supports features like contextual conversations, attachments, and access to conversation history.

Who can access the Messaging API?

Currently, the Messaging API is part of an early access pilot program available to selected affiliate partners. General availability is targeted for Q3 2025.

Authentication & access

How do I authenticate API requests?

All Messaging API endpoints require:

• A valid API token.
• Your affiliate ID (X-Affiliate-Id).

These credentials are consistent with those used for other Demand API v3 endpoints.

Messaging flow & timing

When can guests and hosts send messages?

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

How are conversations initiated?

Conversations are automatically created upon reservation.

• Guests can initiate communication by including a message in the remark field during booking via the orders/create endpoint.

Testing the API

How can I test the Messaging API?

Partners enrolled in the early access pilot 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. See the Try out guide for more details.

What are the available test scenarios?

Test scenarios include:

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

Managing messages

How do I send a message?

Use the messages/send endpoint with the required parameters:

• reservation - ID of the reservation.
• accommodation - ID of the accommodation.
• content - The message body.

Optional parameters:

• reply_to - ID of the message being replied to.
• attachments - IDs of uploaded attachments.

How do I retrieve the latest messages?

Use the messages/latest endpoint to fetch up to 100 of the most recent messages. Each message includes metadata such as sender information, content, attachments, and timestamp.

How do I confirm message retrieval?

After retrieving messages using messages/latest, confirm receipt by calling messages/latest/confirm.

This acknowledges successful retrieval and removes the messages from the queue.

Attachments

Can messages include attachments?

Yes. Both guests and partners can upload image attachments to enhance post-booking communication. This is useful for sharing booking confirmations, ID documents, photos, and more.

Do attachments expire?

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

Can attachments be deleted?

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

Are attachments scanned for viruses?

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

Are attachments encrypted?

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

Can multiple attachments be sent in one request?

Yes. While uploads are handled individually, the /messages/send endpoint accepts an array of attachments.

Best practices

Should I store messages in my system?

It's recommended to store messages to maintain conversation history, enable efficient message retrieval, and support features like tagging messages as read or indicating no reply is needed.

How can I handle duplicate messages?

Implement a cron job that periodically filters out duplicate messages. This ensures that messages already confirmed are not stored again.

For more detailed information and updates, please refer to the Messaging API guidelines: