Learn how to test the Messaging API using the Demand API Messaging Test Hotel. Create a test reservation, retrieve an automated welcome message and confirm receipt using the v3.3 Stable endpoints.
This guide walks you through a basic post-booking messaging workflow in the Demand API sandbox environment.
- Purpose: Quickly try out the Messaging API.
- When to use: You want to test post-booking communication flows.
- You'll learn how to:
- Create a test accommodation reservation.
- Retrieve messages associated with the reservation.
- Identify the conversation and message IDs.
- Confirm receipt of messages to continue receiving new messages.
- Code samples: Minimal, only required fields.
This guide uses the Messaging API v3.3 Stable endpoints.
All Messaging API requests use the /messages/ path prefix.
Make sure you have:
- Completed the Demand API prerequisites.
- A valid Demand API authentication token.
- Your affiliate identifier (
X-Affiliate-Id). - Access to the sandbox environment.
- Access to the Messaging API for your affiliate account.
All Messaging API requests require Bearer authentication and the X-Affiliate-Id header.
For more information, see Authentication.
Use the following sandbox environment to test your integration:
https://demandapi-sandbox.booking.com
The Messaging API endpoints are available under /messages/.
For example, to retrieve the latest messages, send a POST request to:
https://demandapi-sandbox.booking.com/messages/latest
Use your sandbox credentials when testing. Do not use production credentials or real guest reservations for this workflow.
Demand API Messaging Test Hotel
| Property | Value |
|---|---|
| Accommodation name | Demand API Messaging Test Hotel |
| Accommodation ID | 13921698 |
| Environment | Sandbox |
| Purpose | Test post-booking messaging workflows using automated property responses. |
The test accommodation is configured to support messaging scenarios such as:
- Sending an automated welcome message after a reservation is confirmed.
- Responding to selected guest requests, such as requests for extra beds or parking.
These scenarios allow you to test how your application retrieves and processes messages without relying on a property representative to respond manually.
The automated responses described here are specific to the Messaging Test Hotel. Real properties can configure their own messaging preferences and automated replies through Booking.com.
Follow these steps to create a test reservation, retrieve a message and confirm receipt.
Create an accommodation reservation for the Demand API Messaging Test Hotel (accommodation ID 13921698).
Use the standard Demand API booking flow:
- Search for availability at the test accommodation.
- Select an available accommodation product.
- Call /orders/preview to preview the reservation and retrieve an order token.
- Call /orders/create with the order token and the required booking details.
Provide valid sandbox payment details when required by the selected accommodation product and booking flow.
See Testing payments and Create your orders for guidance.
When the reservation is created successfully, the response includes the reservation identifier.
For example:
{
"data": {
"accommodation": {
"reservation": "6066547158",
"order": "5006302528200239",
"pincode": "884512"
}
}
}Save the reservation identifier. You'll use it together with the accommodation ID to retrieve the associated conversation.
Reservation created - You can now retrieve the conversation associated with the test reservation and check for messages sent by the property.
After the reservation is confirmed, the Demand API Messaging Test Hotel automatically sends a welcome message to the guest.
The message is available through the Booking.com messaging platform and can be retrieved using the Messaging API.
Depending on the communication setup:
- Guest view: The welcome message may appear in the guest's Booking.com account, app or email notifications.
- Property view: The property can view the reservation and its messages through the Booking.com Extranet messaging centre.
- Affiliate partner view: Your application can retrieve the message using /messages/latest.
Example of an automated welcome message in the Booking.com Extranet:
Accommodation hosts can use Booking.com Extranet messaging centre or any other channel to communicate with guests.
→ Call /messages/latest to retrieve recent messages available to your affiliate account.
Request:
POST /messages/latest
Send an empty JSON object:
{}Example response
{
"request_id": "0248d85a-17e0-44b3-a37c-7d4b5c03f58b",
"data": {
"messages": [
{
"conversation": {
"id": "c3cc6522-aa63-559d-99f1-94efdd527c3c",
"reservation": "6066547158",
"accommodation": "13921698"
},
"content": "Thank you for choosing Demand API Messaging Test Hotel!",
"id": "52100000-2be9-11f0-bced-bdc849c480b6",
"sender": {
"participant": "6c22a16d-a3bd-5f5b-82d9-ce1030f21b1f",
"metadata": {
"type": "property",
"name": "Demand API Messaging Test Hotel"
}
},
"attachments": [],
"timestamp": "2026-09-18T12:28:51.149Z"
}
]
}
}The response includes:
| Field | Description |
|---|---|
data.messages[].id | Unique identifier of the message. Use this ID to confirm receipt. |
data.messages[].content | Plain-text content of the message. |
data.messages[].conversation | Conversation, reservation and accommodation identifiers associated with the message. |
data.messages[].sender | Information about the sender, including whether the message originated from the guest or property. |
data.messages[].timestamp | Date and time when the message was sent, in ISO 8601 format. |
data.messages[].attachments | List of attachment IDs associated with the message, if any. |
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 your test reservation.
Use the conversation.accommodation and conversation.reservation identifiers to locate the welcome message associated with your booking.
If the message is not yet available, wait before polling again. Automated messages might not be delivered immediately after reservation creation.
Save the message id returned in the response. You'll use it in the next step to confirm receipt.
After successfully retrieving and processing the welcome message, confirm its receipt using /messages/latest/confirm.
Confirmation is required to continue receiving new messages through /messages/latest.
Request
POST /messages/latest/confirm
Provide the ID of the message retrieved in Step 2.
{
"messages": [
"52100000-2be9-11f0-bced-bdc849c480b6"
]
}Example response
{
"request_id": "cdb0b154-2eae-481b-8fee-fb2725296e1f",
"confirmedMessages": [
"52100000-2be9-11f0-bced-bdc849c480b6"
]
}A successful request returns HTTP 200 OK.
The confirmedMessages array contains the IDs of the messages successfully confirmed.
Compare the returned IDs with those submitted in your request to determine which messages were confirmed.
Confirm messages only after your application has successfully processed them.
If a message ID is not included in confirmedMessages, do not assume that its receipt was confirmed.
You've completed the basic Messaging API testing workflow:
- Created a test reservation.
- Retrieved the automated welcome message.
- Confirmed receipt of the message.
Your application can now continue polling /messages/latest to retrieve subsequent messages and confirm them as they are processed.
You can also retrieve the complete conversation associated with your test reservation using /messages/conversations.
This is useful when you want to retrieve conversation history, identify participants or obtain the conversation ID before sending a reply.
The endpoint accepts an accommodation ID together with either a reservation ID or a conversation ID.
Request
POST /messages/conversations
Use the accommodation and reservation IDs from Step 1:
{
"accommodation": "13921698",
"reservation": "6066547158"
}Example response
{
"request_id": "7889a8c0-aa43-494c-863d-72d2306849c1",
"data": {
"conversation": {
"id": "c3cc6522-aa63-559d-99f1-94efdd527c3c",
"reservation": "6066547158",
"messages": [
{
"id": "52100000-2be9-11f0-bced-bdc849c480b6",
"sender": "6c22a16d-a3bd-5f5b-82d9-ce1030f21b1f",
"content": "Thank you for choosing Demand API Messaging Test Hotel!",
"attachments": [],
"timestamp": "2026-09-18T12:28:51.149Z"
}
],
"participants": [
{
"id": "5dba2525-2c49-5d2c-91cc-7195526c0c7a",
"metadata": {
"type": "guest"
}
},
{
"id": "6c22a16d-a3bd-5f5b-82d9-ce1030f21b1f",
"metadata": {
"type": "property",
"name": "13921698"
}
}
]
}
}
}The response contains the conversation ID, associated reservation, messages and participants.
The reservation ID identifies the booking, while the conversation ID identifies the messaging thread.
To send messages using /messages/send, provide the conversation ID and accommodation ID.
For implementation details, see Manage messages.
If your test does not behave as expected, review these common scenarios.
| Issue | Recommended action |
|---|---|
| No welcome message returned | Verify that the reservation was created successfully. Allow time for the automated message to become available, then poll /messages/latest again. |
| Message belongs to another reservation | Check the accommodation and reservation IDs returned in the message's conversation object. |
| No new messages returned | Verify that previously processed messages have been confirmed using /messages/latest/confirm. |
| Message receipt not confirmed | Compare the submitted message IDs with the returned confirmedMessages array. Investigate any IDs that were not confirmed. |
| Authentication error | Verify your Bearer token, X-Affiliate-Id and Messaging API access. |
| API request fails | Check the HTTP status code and response details. Follow the applicable Demand API error-handling and retry guidance. |
Automated messages might take time to become available after reservation creation.
Avoid excessive polling and follow the applicable Demand API rate limits.
- Manage messages – Learn how to send messages, retrieve conversations and synchronise message receipt.
- Manage attachments – Upload images, include attachments in messages and retrieve attachment content.
- Messaging best practices – Learn how to handle message processing, confirmations and integration reliability.