Integrate guest and property messaging into your platform. Use the Messaging API to retrieve messages from Booking.com, display them to your users, send messages to properties on their behalf, and manage conversation history and attachments.
The Messaging API lets Demand API affiliate partners connect guest and property conversations to their own platforms and workflows.
- A guest can contact a property through Booking.com or through a communication channel provided by your platform.
- Your integration can retrieve messages from Booking.com, present them to the guest in your system, and send the guest's message to the property through the API.
- It can also retrieve the property's replies and make them available to the guest through your platform.
Conversations are associated with an accommodation and, where applicable, a reservation. To send a message, use the conversation and accommodation identifiers required by the endpoint.
| Capability | Description |
|---|---|
| Send messages | Send a message to a conversation on behalf of a guest using your platform. |
| Retrieve messages | Retrieve recent messages sent by guests or properties and make them available in your system. |
| Retrieve conversations | Retrieve a conversation using an accommodation ID and either a conversation ID or a reservation ID. |
| Synchronise messages | Confirm messages returned by /messages/latest after your system has processed them. |
| Exchange attachments | Upload images, include their attachment IDs in messages, retrieve attachment metadata and download attachments. |
The Messaging API is intended for Demand API affiliate partners who want to integrate guest and property communication into their own systems.
- You can use it alongside accommodation booking and post-booking workflows.
- You need valid Demand API credentials and an affiliate identifier to access the API.
The Messaging API is available in v3.2 stable. All Messaging API endpoints use the /3.2/messages/ path prefix.
Integrating messaging into your platform can help you:
| Benefit | Description |
|---|---|
| Keep communication in your platform | Let guests and your support teams manage property communication alongside booking and service workflows. |
| Improve the guest experience | Make timely, relevant property messages and replies available through the channels your platform provides. |
| Support efficient service | Give your teams access to reservation-related conversations when they assist guests. |
| Connect partner services | Link messaging workflows with booking-management systems, CRM platforms, customer-service tools or other partner systems. |
| Use conversation data | Use message timestamps and conversation history to understand and manage communication workflows. |
The Messaging API supports communication between guests and properties through your platform.
The guest does not have to start the conversation in Booking.com for your integration to send a message on their behalf.
When a guest starts a message in your platform, your integration sends it to the property through the Messaging API.
- The guest writes a message in your platform.
- Your integration sends the message to the conversation using /messages/send.
- Your integration retrieves the property's reply using /messages/latest.
- Your system processes the reply and confirms receipt using /messages/latest/confirm.
- Your platform displays or forwards the reply to the guest.
- The /messages/send request schema requires the accommodation ID, conversation ID and message content.
- If your system has a reservation ID but not a conversation ID, first retrieve the conversation using /messages/conversations with the accommodation ID and reservation ID.
Guest messages may include:
| Topic | Examples |
|---|---|
| Check-in and arrival | Estimated arrival times, early or late check-in requests and key collection questions. |
| Directions and transport | Directions to the property, parking information or airport transfer arrangements. |
| Reservation questions | Questions about reservation details, cancellation conditions or refund policies. |
| Facilities and services | Questions about Wi-Fi, accessibility, room facilities or additional services. |
| Special requests | Requests for baby cots, extra beds or specific room arrangements. |
| Local information | Questions about nearby restaurants, attractions or transport options. |
When a property sends a message through Booking.com or a connected property-management system, your integration retrieves it and makes it available to the guest through your platform.
- The property sends a message through Booking.com or a connected property-management system.
- Your integration retrieves the message using /messages/latest.
- Your system processes the message and confirms receipt using /messages/latest/confirm.
- Your platform displays or forwards the message to the guest through the appropriate channel.
- If the guest wants to reply, your integration sends the reply to the conversation using /messages/send.
Property messages may include:
| Topic | Examples |
|---|---|
| Welcome information | Greetings, booking details and information about the upcoming stay. |
| Check-in arrangements | Check-in times, key collection instructions and property access information. |
| Special requests | Responses to requests about room arrangements, parking or additional services. |
| Facilities and amenities | Information about Wi-Fi, accessibility features, air conditioning or other facilities. |
| Payments and charges | Information about deposits, accepted payment methods or local taxes. |
The /messages/conversations endpoint can retrieve a conversation using the accommodation ID together with either a conversation ID or a reservation ID. The current /messages/send request schema requires a conversation ID and accommodation ID. If you have only a reservation ID, use it to retrieve the conversation first.
The API schema does not specify how soon a conversation becomes available after a reservation is created. If a lookup does not return the conversation, retry after a short delay. A property welcome message is not listed as a prerequisite in the /messages/send request schema.
Example of welcome message sent to travellers:
Use /messages/latest to retrieve recent messages from guests and properties and keep your platform up to date. By default, the endpoint returns up to 100 messages in reverse chronological order, with the newest messages first.
For messages returned by /messages/latest:
- Retrieve the messages using /messages/latest.
- Process them in your system, for example by storing, displaying or forwarding them.
- After successful processing, confirm their IDs using /messages/latest/confirm.
- Continue polling /messages/latest for new messages.
Confirmation is required to continue receiving new messages through /messages/latest. Confirm the IDs of messages your system has processed.
This confirmation applies to messages retrieved through /messages/latest. It is not a separate confirmation that the guest has received a property message, and it is not required for a message your integration sends using /messages/send.
For implementation details, see Manage messages.
The Messaging API supports image attachments in conversations.
To send an attachment:
- Upload the image using /messages/attachments/upload.
- Store the attachment ID returned in the response.
- Include the attachment ID in the attachments array when sending the message using /messages/send.
To retrieve an attachment, use /messages/attachments/metadata to get its file information or /messages/attachments/download to retrieve its base64-encoded content.
| Requirement | Description |
|---|---|
| Supported formats | PNG and JPEG images, including .png, .jpg and .jpeg files. |
| Maximum file size | 1,048,576 bytes (1 MiB) per attachment. |
| File encoding | File content must be base64-encoded when uploading an attachment. |
| Attachment identification | Each uploaded attachment has an attachment ID. Include this ID in the attachments array when sending a message. |
For implementation details, see Manage attachments.
When integrating the Messaging API, you are responsible for processing messages and managing communication within your own systems.
Follow these recommendations:
- Poll /messages/latest according to your integration requirements.
- Confirm messages returned by /messages/latest after successfully processing them.
- Use message IDs to identify messages your system has already processed.
- Maintain the conversation and accommodation identifiers, and the reservation identifier when available.
- Make messages and property replies available to the relevant guest through your platform or chosen communication channel.
- Handle attachments securely and follow your data-retention requirements.
- Implement error handling and retry logic according to the general Demand API guidance.
The Messaging API provides seven endpoints grouped into conversations, messages and attachments.
All endpoints use the v3.2 stable API.
| Endpoint | Description |
|---|---|
| /messages/conversations | Retrieve a conversation using an accommodation ID together with either a conversation ID or a reservation ID. The response includes messages and conversation participants. |
| Endpoint | Description |
|---|---|
| /messages/send | Send a message to a conversation using the required conversation ID, accommodation ID and content. You can optionally include previously uploaded attachment IDs. |
| /messages/latest | Retrieve recent messages from guests and properties. By default, returns up to 100 messages in reverse chronological order. |
| /messages/latest/confirm | Confirm receipt of messages returned by /messages/latest so you can continue receiving new messages from that endpoint. |
| Endpoint | Description |
|---|---|
| /messages/attachments/upload | Upload a base64-encoded image attachment and retrieve its attachment ID. |
| /messages/attachments/metadata | Retrieve attachment metadata, including the file name, MIME type and file size. |
| /messages/attachments/download | Retrieve the base64-encoded content of an attachment. |
Use the following guides to integrate the Messaging API:
- Try the Messaging API – Configure your credentials and make your first Messaging API requests.
- Manage messages – Retrieve conversations, send messages and synchronise message receipt.
- Manage attachments – Upload, retrieve and download message attachments.
- Authentication – Learn how to authenticate Demand API requests.