Use case 2 – Send a request and handle rejection

Learn how to send a special request to a property, retrieve its automated rejection and confirm receipt using the Messaging API.

This use case demonstrates how to handle a guest request that cannot be fulfilled by the property, using the Demand API Messaging Test Hotel in the sandbox environment.

Scenario: A guest requests an extra bed at the Demand API Messaging Test Hotel (accommodation ID 13921698). The property is configured to send an automated rejection for this type of request. Your integration sends the request, retrieves the rejection message and confirms receipt.

Make sure you have:

• Completed Use case 1 – Booking and welcome message.
• Access to the sandbox environment.
• Valid Demand API credentials and your X-Affiliate-Id.
• Access to the Messaging API.
• An existing reservation at the Demand API Messaging Test Hotel (13921698).
• The conversation ID associated with the reservation.

All Messaging API requests require Bearer authentication and the X-Affiliate-Id header.

For more information, see Authentication.

Follow these four steps to complete the scenario:

1. Send the guest request to the property.
2. Receive the automated rejection generated by the test hotel.
3. Retrieve the rejection message using the Messaging API.
4. Confirm message receipt to continue receiving new messages.

Use /messages/send to send an extra-bed request to the Demand API Messaging Test Hotel.

The endpoint requires:

Request

POST /messages/send

{
  "accommodation": "13921698",
  "conversation": "bbb76179-7565-5a23-8632-33e164aa13db",
  "content": "I would need an extra bed in the room. Is this possible? Thanks!"
}

In this example:

• accommodation identifies the Demand API Messaging Test Hotel.
• conversation identifies the existing conversation associated with the guest's reservation.
• content contains the guest's extra-bed request.

{
  "request_id": "6483bacb-41a6-4f18-8747-9f04f40f2f45",
  "data": {
    "message": "ce18cdf0-8fb5-11f0-9aad-81db133940ac"
  }
}

A successful request returns HTTP 200 OK.

The data.message field contains the unique identifier of the sent message.

The Demand API Messaging Test Hotel is configured to automatically reject certain guest requests, including requests for extra beds.

After your integration sends the message:

1. The request becomes available to the property through the Booking.com messaging platform.
2. The test accommodation generates a predefined rejection response.
3. The rejection message becomes available through the conversation.

The property can view the guest's request in the Booking.com Extranet messaging centre.

Example of an extra-bed request:

The test accommodation automatically generates a rejection message.

Example of the automated rejection:

Depending on the communication setup, the guest may receive the rejection through the Booking.com app, website or email notifications.

The guest can also view the conversation through the available Booking.com communication channels.

Example of the guest conversation:

Use /messages/latest to retrieve the automated rejection programmatically.

This allows your integration to process the response without requiring the guest to check their email or Booking.com account.

Request

POST /messages/latest

Send an empty JSON object:

{}

{
  "request_id": "ddcf96b3-e17c-4e6f-8f8c-4d685489ce04",
  "data": {
    "messages": [
      {
        "conversation": {
          "id": "bbb76179-7565-5a23-8632-33e164aa13db",
          "reservation": "6066547158",
          "accommodation": "13921698"
        },
        "content": "Unfortunately, we cannot provide an extra bed for your reservation.",
        "id": "8a269910-19d1-11f0-bb60-972708bd278a",
        "sender": {
          "participant": "94914645-adbc-546b-a759-d1a1b48b6e1e",
          "metadata": {
            "type": "property",
            "name": "Demand API Messaging Test Hotel"
          }
        },
        "attachments": [],
        "timestamp": "2026-09-18T12:35:40.000Z"
      }
    ]
  }
}

The response includes:

By default, /messages/latest returns up to 100 messages in reverse chronological order, with the newest messages first.

After retrieving the message:

1. Identify the conversation associated with the guest's request.
2. Check that the message was sent by the property.
3. Process the rejection message according to your application's communication workflow.
4. Make the response available to the guest through the appropriate channel.
5. Save the message ID for receipt confirmation.

After successfully processing the rejection message, use /messages/latest/confirm to confirm receipt.

Confirmation is required to continue receiving new messages through /messages/latest.

Request

POST /messages/latest/confirm

Provide the message ID returned in Step 3.

{
  "messages": [
    "8a269910-19d1-11f0-bb60-972708bd278a"
  ]
}

Example response

{
  "request_id": "cdb0b154-2eae-481b-8fee-fb2725296e1f",
  "confirmedMessages": [
    "8a269910-19d1-11f0-bb60-972708bd278a"
  ]
}

A successful request returns HTTP 200 OK.

The confirmedMessages array contains the IDs of messages confirmed by the API.

Compare the returned IDs with those submitted in the request to determine which messages were confirmed.

Follow these recommendations when handling guest requests and automated responses:

✅ Use the correct conversation: Include the accommodation and conversation IDs associated with the guest's reservation.

✅ Track message IDs: Store the IDs of sent and received messages to support reliable message processing.

✅ Identify the sender: Use the sender metadata to distinguish property responses from guest messages.

✅ Associate responses with reservations: Use the conversation identifiers to match incoming messages to the correct booking.

✅ Confirm messages after processing: Call /messages/latest/confirm only after successfully processing the received messages.

✅ Check confirmation results: Compare submitted message IDs with confirmedMessages before marking messages as confirmed.

✅ Avoid excessive polling: Allow time for automated responses and follow the applicable Demand API rate limits.

✅ Handle errors appropriately: Validate requests and apply suitable retry strategies without generating duplicate messages.