Use the Messaging API to retrieve conversations, exchange messages between guests and properties, and synchronise communication with your own systems.
This guide introduces the Messaging API workflows for exchanging messages between guests and properties, including conversation retrieval, message synchronisation and receipt confirmation.
Explore the dedicated use cases below for step-by-step implementation instructions and API examples.
This guide assumes you have:
✓ Complete the Messaging API quick guide
✓ Access to your sandbox environment.
✓ Access to the Messaging API.
✓ A valid API key token and your X-Affiliate-Id.
All Messaging API requests require Bearer authentication and the X-Affiliate-Id header. For more information, see Authentication.
The Messaging API is available in Demand API v3.3 Stable.
The Messaging API enables affiliate partners to exchange messages between guests and properties through existing conversations.
Each conversation is associated with an accommodation and may also be associated with a reservation.
Your integration can retrieve messages sent by either participant, process them in your own system and send replies through the same conversation.
The following diagram illustrates how messages are exchanged between guests, properties and affiliate partners.
| Participants | Action |
|---|---|
 | Guest - Sends messages or requests through Booking.com or an available communication channel. |
 | Property - Receives and responds to guest messages through Booking.com or a connected property-management system. Properties can also send automated messages. |
 | Affiliate partner - Uses the Messaging API to retrieve conversations, process incoming messages, send replies and confirm message receipt. |
Messaging availability is restricted to specific timeframes based on reservation status:
| User type | Send window | Read window |
|---|---|---|
| Guests | From booking → 66 days post-checkout/cancellation. | Until 66 days post-checkout/cancellation. |
Property | From booking → 7 days post-checkout/cancellation. If guest sends a message: +14 days to reply. | (Same as guests) |
| All Users | Messages readable up to 1 year after checkout or cancellation. |
The Messaging API provides four endpoints for managing conversations and messages.
| Endpoint | Description |
|---|---|
| /messages/conversations | Retrieve an existing conversation, including its messages and participants, using an accommodation ID and either a conversation ID or reservation ID. |
| /messages/send | Send a plain-text message to an existing conversation. 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 processed messages to continue receiving new messages through /messages/latest. |
For request parameters, response schemas and examples, select an endpoint above to open its API reference, or explore the implementation use cases below.
The following use cases demonstrate how to implement complete messaging workflows using the Demand API Messaging Test Hotel.
Welcome message
Use case 1 – Retrieve a conversation for a new booking, receive an automated welcome message and send a reply to the property.
Open the guide
Request and rejection
Use case 2 – Send a guest request, such as an extra bed or parking request, and handle the automated rejection response.
Open the guide
For a shorter introduction, see the Messaging API quick guide.
If your messaging workflow does not behave as expected, review these common scenarios.
| Issue | Possible cause | Recommended action |
|---|---|---|
| Conversation cannot be retrieved | The accommodation, reservation or conversation identifier is incorrect. | Verify that the identifiers refer to an existing conversation available to your affiliate account. |
| Message cannot be sent | The conversation identifier is incorrect or the request is missing required fields. | Verify the accommodation ID, conversation ID and message content. |
| No new messages returned | Previously retrieved messages have not been confirmed, or no new messages are available. | Check message confirmations and continue polling according to your integration requirements. |
| Message receipt not confirmed | One or more submitted message IDs were not confirmed. | Compare the request IDs with the confirmedMessages response and investigate any missing IDs. |
| Authentication failure | Invalid credentials, affiliate identifier or API access. | Verify your Bearer token, X-Affiliate-Id and Messaging API permissions. |
| API request fails | The request is invalid or a temporary API error has occurred. | Check the HTTP status code and response details. Follow the applicable error-handling and retry guidance. |
For general troubleshooting, see Error handling.
Follow these recommendations when integrating messaging workflows:
✅ Maintain conversation context: Store conversation, accommodation and reservation identifiers to associate messages with the correct booking.
✅ Use message IDs: Track processed messages using their unique identifiers to help prevent duplicate processing.
✅ Confirm messages after processing: Call /messages/latest/confirm only after your application has successfully processed the messages.
✅ Check confirmation results: Compare submitted message IDs with the confirmedMessages array before marking messages as confirmed.
✅ Synchronise regularly: Poll /messages/latest according to your integration requirements and applicable rate limits.
✅ Handle attachments separately: Upload images before sending messages and reference their attachment IDs in the attachments array.
✅ Protect guest information: Apply appropriate security, access-control and data-retention practices when processing messages.
✅ Handle errors appropriately: Validate requests and apply suitable retry strategies without generating unnecessary duplicate operations.
- Messaging API quick guide – Test the basic messaging workflow using the Demand API Messaging Test Hotel.
- Manage attachments – Learn how to upload, send and retrieve image attachments.
- Messaging best practices – Review recommendations for reliable messaging integrations.
- Error handling – Learn how to troubleshoot API requests.