Learn how to retrieve a conversation associated with a new booking, receive an automated welcome message, confirm its receipt and send a reply to the property using the Messaging API.
This use case demonstrates a complete post-booking messaging workflow using the Demand API Messaging Test Hotel in the sandbox environment.
Scenario: A guest books a room at the Demand API Messaging Test Hotel (accommodation ID
13921698). After the reservation is confirmed, the property automatically sends a welcome message. Your integration retrieves the conversation and welcome message, confirms receipt and sends a reply to the property..
Make sure you have:
- Completed the Messaging API quick guide.
- Access to the sandbox environment.
- Valid Demand API credentials and your
X-Affiliate-Id. - Access to the Messaging API.
- A confirmed reservation at the Demand API Messaging Test Hotel (
13921698).
All Messaging API requests require Bearer authentication and the X-Affiliate-Id header.
For more information, see Authentication.
This guide uses the Messaging API v3.3 Stable endpoints.
Send requests to the sandbox base URL:
https://demandapi-sandbox.booking.com
Follow these four steps to complete the messaging scenario:
- Retrieve the conversation associated with the test reservation.
- Retrieve the latest messages to obtain the automated welcome message.
- Confirm message receipt to continue receiving new messages.
- Send a reply to the existing conversation.
After a successful booking through /orders/create, the reservation is associated with a messaging conversation.
The Demand API Messaging Test Hotel is configured to send an automated welcome message after booking confirmation.
Use /messages/conversations to retrieve the conversation associated with your reservation.
The endpoint accepts an accommodation ID together with either a reservation ID or a conversation ID.
Since you've just created a booking, use the reservation ID returned by /orders/create.
Request with reservation ID
POST /messages/conversations
{
"accommodation": "13921698",
"reservation": "6066547158"
}Example response
{
"request_id": "7889a8c0-aa43-494c-863d-72d2306849c1",
"data": {
"conversation": {
"id": "bbb76179-7565-5a23-8632-33e164aa13db",
"reservation": "6066547158",
"messages": [
{
"id": "1fd6c3a0-6c74-11f0-8a0a-3dbfea505c1d",
"sender": "94914645-adbc-546b-a759-d1a1b48b6e1e",
"content": "Hello! Thanks for booking Demand API Messaging Test Hotel. We look forward to welcoming you!",
"attachments": [],
"timestamp": "2026-09-18T12:28:51.149Z"
}
],
"participants": [
{
"id": "94914645-adbc-546b-a759-d1a1b48b6e1e",
"metadata": {
"type": "property",
"name": "13921698"
}
},
{
"id": "fee4a6c8-16e2-5d7b-9ad0-2027f8eae9df",
"metadata": {
"type": "guest"
}
}
]
}
}
}The response includes:
| Field | Description |
|---|---|
data.conversation.id | Unique identifier of the conversation. |
data.conversation.reservation | Reservation associated with the conversation. |
data.conversation.messages | Messages belonging to the conversation, including their content, sender, attachments and timestamp. |
data.conversation.participants | Conversation participants, including the guest and property. |
Save the data.conversation.id value.
You'll use this conversation ID, together with the accommodation ID, when sending a reply in Step 4.
Use /messages/latest to retrieve recent messages without requesting the complete conversation each time.
This endpoint returns messages sent by both guests and properties.
After the reservation is confirmed, the Demand API Messaging Test Hotel automatically generates a welcome message.
Request
POST /messages/latest
Send an empty JSON object:
{}Example response
{
"request_id": "ddcf96b3-e17c-4e6f-8f8c-4d685489ce04",
"data": {
"messages": [
{
"conversation": {
"id": "bbb76179-7565-5a23-8632-33e164aa13db",
"reservation": "6066547158",
"accommodation": "13921698"
},
"content": "Hello! Thanks for booking Demand API Messaging Test Hotel. We look forward to welcoming you!",
"id": "1fd6c3a0-6c74-11f0-8a0a-3dbfea505c1d",
"sender": {
"participant": "94914645-adbc-546b-a759-d1a1b48b6e1e",
"metadata": {
"type": "property",
"name": "Demand API Messaging Test Hotel"
}
},
"attachments": [],
"timestamp": "2026-09-18T12:28:51.149Z"
}
]
}
}The response includes:
| Field | Description |
|---|---|
id | Unique identifier of the message. Use this ID to confirm receipt. |
conversation | Conversation, reservation and accommodation identifiers associated with the message. |
content | Plain-text content of the message. |
sender | Information about the sender, including their participant ID and whether they are a guest or property. |
attachments | Array of attachment IDs associated with the message, if any. |
timestamp | Date and time when the message was sent, in ISO 8601 format. |
By default, /messages/latest returns up to 100 messages in reverse chronological order, with the newest messages first.
The /messages/latest endpoint retrieves recent messages available to your affiliate account, not only messages associated with the test reservation.
Use the conversation.id, conversation.reservation and conversation.accommodation fields to identify messages associated with your booking.
To keep your application synchronised with Booking.com:
- Call /messages/latest to retrieve recent messages.
- Identify the conversation associated with each message.
- Process the messages in your application.
- Confirm successfully processed messages using /messages/latest/confirm.
- Continue polling for subsequent messages.
Automated messages might not be available immediately after booking confirmation.
If the welcome message is not returned, wait before polling again. Follow the applicable Demand API rate limits.
After processing the welcome message, use /messages/latest/confirm to confirm its receipt.
Confirmation is required to continue receiving new messages through /messages/latest.
Request
POST /messages/latest/confirm
Provide the message ID returned in Step 2.
{
"messages": [
"1fd6c3a0-6c74-11f0-8a0a-3dbfea505c1d"
]
}Example response
{
"request_id": "cdb0b154-2eae-481b-8fee-fb2725296e1f",
"confirmedMessages": [
"1fd6c3a0-6c74-11f0-8a0a-3dbfea505c1d"
]
}A successful request returns HTTP 200 OK.
The confirmedMessages array contains the IDs of messages successfully confirmed by the API.
Compare the returned IDs with those submitted in the request to determine which messages were confirmed.
Only confirm messages after your application has successfully processed them.
If a message ID is missing from confirmedMessages, do not assume that its receipt was confirmed.
The welcome message has been retrieved and its receipt confirmed.
Your application can continue polling /messages/latest for new messages.
Use /messages/send to send a reply to the existing conversation.
The endpoint requires:
| Field | Description |
|---|---|
accommodation | Unique identifier of the property associated with the conversation. |
conversation | Unique identifier of the conversation retrieved in Step 1. |
content | Plain-text content of the message. |
Request
POST /messages/send
{
"accommodation": "13921698",
"conversation": "bbb76179-7565-5a23-8632-33e164aa13db",
"content": "Thanks for the welcome message! We look forward to our stay."
}Example response
{
"request_id": "3a097c09-cad1-4a91-9586-1834e27b9004",
"data": {
"message": "2c05c1c0-8fb6-11f0-9fe0-231a553b7d81"
}
}A successful request returns HTTP 200 OK.
The response includes the unique identifier of the newly sent message in data.message.
Your reply has been sent successfully.
You can retrieve the conversation again using /messages/conversations to view the updated message history.
You can include image attachments when sending a message.
First, upload each image using /messages/attachments/upload.
The upload response returns an attachment ID.
Include the attachment ID in the optional attachments array of your /messages/send request.
For example:
{
"accommodation": "13921698",
"conversation": "bbb76179-7565-5a23-8632-33e164aa13db",
"content": "Please see the attached image.",
"attachments": [
"c325f460-1dc6-11f0-80f0-8d0908786f77"
]
}For implementation details, see Manage attachments.
Follow these recommendations when implementing this messaging scenario:
✅ Maintain conversation context: Store the accommodation, reservation and conversation identifiers to associate messages with the correct booking.
✅ Track message IDs: Use the message IDs returned by /messages/latest to identify and process messages reliably.
✅ Confirm messages after processing: Call /messages/latest/confirm only after successfully processing messages.
✅ Check confirmation results: Compare submitted message IDs with the confirmedMessages array before marking messages as confirmed.
✅ Handle automated replies: Allow time for automated messages to become available and avoid excessive polling.
✅ Prevent duplicate processing: Track previously processed message IDs to avoid processing the same message more than once.
✅ Handle errors appropriately: Validate requests and follow the applicable Demand API error-handling and retry guidance.
- Use case 2 – Request and rejection – Send a guest request and handle an automated rejection response.
- Manage messages – Review the available messaging operations and workflows.
- Manage attachments – Learn how to upload, send and retrieve image attachments.
- Messaging best practices – Review recommendations for reliable messaging integrations.
- Messaging troubleshooting – Learn how to troubleshoot common messaging issues.