# Messaging API quick guide **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.2 Stable endpoints.** This guide walks you through a basic post-booking messaging workflow in the Demand API sandbox environment. ⏱️ Estimated time to complete: 15 - 30 minutes 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. API version This guide uses the Messaging API v3.2 Stable endpoints. All Messaging API requests use the `/3.2/messages/` path prefix. ## Before you start Make sure you have: * Completed the [Demand API prerequisites](/demand/docs/getting-started/try-out-the-api#before-you-start---prerequisites). * A valid Demand API authentication token. * Your affiliate identifier (`X-Affiliate-Id`). * Access to the [sandbox environment](/demand/docs/getting-started/sandbox). * 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](/demand/docs/development-guide/authentication). ### Test environment Use the following sandbox environment to test your integration: `https://demandapi-sandbox.booking.com` The Messaging API endpoints are available under `/3.2/messages/`. For example, to retrieve the latest messages, send a POST request to: `https://demandapi-sandbox.booking.com/3.2/messages/latest` Use your sandbox credentials when testing. Do not use production credentials or real guest reservations for this workflow. ### Test accommodation **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. ## Test the messaging flow Follow these steps to create a test reservation, retrieve a message and confirm receipt. ### Step 1 – Create a test reservation Create an accommodation reservation for the Demand API Messaging Test Hotel (accommodation ID `13921698`). Use the standard Demand API booking flow: 1. Search for availability at the test accommodation. 2. Select an available accommodation product. 3. Call [/orders/preview](/demand/docs/open-api/3.2/demand-api/orders/orders/preview) to preview the reservation and retrieve an order token. 4. Call [/orders/create](/demand/docs/open-api/3.2/demand-api/orders/orders/create) with the order token and the required booking details. Test payment details Provide valid sandbox payment details when required by the selected accommodation product and booking flow. See [Testing payments](/demand/docs/payments/how-to#testing) and [Create your orders](/demand/docs/orders-api/order-preview-create#create-your-orders) for guidance. When the reservation is created successfully, the response includes the reservation identifier. For example: ```json { "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. ### Step 2 – Retrieve the automated welcome message 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:** ![Booking.com Extranet showing auto-reply welcome message](/assets/welcome-extranet.2024bd824dd4fd1364828465700cc4abe33c9b29c85c20912f8bf933e3662f33.a0931a69.png) Accommodation hosts can use Booking.com Extranet messaging centre or any other channel to communicate with guests. #### Retrieve the message using the API → Call [/messages/latest](/demand/docs/additional-services/messaging/messaging/messages/latest) to retrieve recent messages available to your affiliate account. **Request:** POST `/3.2/messages/latest` Send an empty JSON object: ```json {} ``` **Example response** ```json { "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. Identify your test message 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. ### Step 3 – Confirm message receipt After successfully retrieving and processing the welcome message, confirm its receipt using [/messages/latest/confirm](/demand/docs/additional-services/messaging/messaging/messages/confirm). Confirmation is required to continue receiving new messages through /messages/latest. **Request** POST `/3.2/messages/latest/confirm` Provide the ID of the message retrieved in Step 2. ```json { "messages": [ "52100000-2be9-11f0-bced-bdc849c480b6" ] } ``` **Example response** ```json { "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 processed messages 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. Test completed 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. ## Optional – Retrieve the complete conversation You can also retrieve the complete conversation associated with your test reservation using [/messages/conversations](/demand/docs/additional-services/messaging/messaging/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 `/3.2/messages/conversations` Use the accommodation and reservation IDs from Step 1: ```json { "accommodation": "13921698", "reservation": "6066547158" } ``` **Example response** ```json { "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. Conversation identifiers 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](/demand/docs/messaging/manage-messages). ## Troubleshooting 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. ## Next steps * [Manage messages](/demand/docs/messaging/manage-messages) – Learn how to send messages, retrieve conversations and synchronise message receipt. * [Manage attachments](/demand/docs/messaging/manage-attachments) – Upload images, include attachments in messages and retrieve attachment content. * [Messaging best practices](/demand/docs/messaging/messaging-best-practices) – Learn how to handle message processing, confirmations and integration reliability.