Try Messaging API out

If you're a Managed Affiliate Partner enrolled in the early access pilot, you can start testing the Messaging API in your application today.

Quick guide

Explore how to enable two-way communication between travellers and accommodations using our Messaging API.

This hands-on guide walks you through realistic scenarios using our dedicated test hotel—complete with automated replies—to help you understand how messaging flows work, from booking confirmations to handling special requests.

Before you start

Before you start trying out our Demand API, make sure that:

Authentication

Every API request must be authenticated using:

• A valid API token.
• Your partner affiliate id (X-Affiliate-Id).

Testing the Messaging API

Start testing your integration now using our dedicated sandbox hotel in sandbox environment.

• This hotel has been set up with various preconfigured automated responses.
• This setup allows you to simulate realistic messaging scenarios and verify how your implementation handles different types of system-generated replies.

Auto-replies

Scheduled messages are automatically triggered in the following situations:

• Welcome message after the reservation is confirmed.
• One day before checkin.
• One day before checkout.

Special requests

Auto-replies are also configured in the Demand API Messaging Test Hotel for the scenarios when travellers send remarks.special_requests in their orders.

By default the test hotel sends rejection messages for the following request types:

• Check-in/ check-out times outside permitted hours.
• Parking requests.
• Bed and/or smoking preferences.

Use case 1 - Booking and welcome message

Follow these steps to test an initial communication flow with the following actions:

Step 1 - Create a test order

Create a reservation at the Demand API Messaging Test Hotel (using the accommodation ID 13921698) in the sandbox environment.

• Endpoints - Use the /orders/preview and orders/create endpoints.
• Specify in the request:
  • payment - Use a valid credit card as recommended in the Testing payments section.
  • Guests details - Include guests allocation and details such as complete name and email where messages will be sent.

Example:

{
  "accommodation": {
    "products": [
      {
        "id": "333",
        "bed_configuration": "123456",
        "guests": [
          {
            "email": "ada.smith@booking.com",
            "name": "Ada Smith"
          }
        ]
      }
    ],
  },
  "booker": {
    "address": {
      "address_line": "Road-1, house-2",
      "city": "Amsterdam",
      "country": "nl",
      "post_code": "11111"
    },
    "company": "",
    "email": "ada.smith@booking.com",
    "language": "en-gb",
    "name": {
      "first_name": "Ada",
      "last_name": "Smith"
    },
    "telephone": "12345678"
  },
  "order_token": "sample-token",
  "payment": {
    "card": {
      "cardholder": "Ada Smith",
      "cvc": "111",
      "expiry_date": "2030-10",
      "number": "23333333333333"
    },
    "include_receipt": true,
    "method": "card",
    "timing": "pay_at_the_property"
  }
}

→ Try it yourself

Step 2 - Identify the reservation Id

A succesful orders/create response returns a valid reservation id, that will be the identifier for further calls.

{
  "request_id": "01j69mtd91x3pdcmqyj0spebt9",
  "data": {
    "payment": {
      "receipt_url": "https://secure.booking.com/payment_receipt.html?product_type=BookingBudget&aid=2373042&auth_key=8riKJJ0XuxDhk4ds&lang=en",
      "authorisation_form_url": null
    },
    "accommodation": {
      "order": "5006302528200239",
      "pincode": "884512",
      "reservation": 55303962
    }
  }
}

Step 3 - Auto-reply welcome message

As the reservation has been confirmed in the Demand API Messaging Test Hotel, the guest receives an automatic welcome message in the provided email.

• By default, it automatically starts a new conversation, which is identified by a conversation id in Messaging API and tied to the reservation id.

Example of send/message request:

{
    "reservation": "55303962",
    "conversation": "55555",
    "accommodation": 13921698,
    "content": "Hello Ada Smith, Thanks for booking at Demand API Test Hotel! We are happy to see you on Thursday 22 August 2025"
}

When successfully sent, it generates a message_id that identifies the welcome message.

{
    "request_id": "cdb0b154-2eae-481b-8fee-fb2725296e1f",
    "data": {
        "message_id": "3164e570-19e0-11f0-baca-e5019c8df435",
    }
}

→ Try it yourself

Demand API Messaging Test Hotel has set all its auto-replies via Booking.com extranet messaging centre, from where it can directly handle this conversation with the guest:

Use case 2 - Booking and special request

Follow these steps to test the communication flow with the following actions:

Step 1 - Create a test order with special request

Create a reservation at the Demand API Messaging Test Hotel (using the accommodation ID 13921698) in the sandbox environment.

• Endpoints - Use the /orders/preview and orders/create endpoints.
• Specify in the request:
  • payment - Use a valid credit card as recommended in the Testing payments section.
  • Guests details - Include guests allocation and details such as complete name and email where messages will be sent.
  • special_requests under remarks field, in this case requesting an extra bed.

Example:

"remarks": {
        "estimated_arrival_time": {
          "hour": 12
        },
        "special_requests": "I would need an extra bed in the room. Is this possible? Thanks"
      }

→ Try it yourself

Step 2 - Accommodation receives message

The accommodation host receive the request in this case via Booking.com Extranet messages center, where the Demand API Messaging Test Hotel has a pre-defined rejection reply that is automatically sent to the guest.

Example of the automatic rejection message sent to the guest email:

Step 3 - Guest receives rejection message

The guest receives the rejection message directly to the provided email (or registered app).

In this example, the guest has a Booking.com authenticated email and can access the full list of messages, and different conversations from the Booking.com platform.

Troubleshooting

Not seeing auto-replies?

• Double-check that you're using the test hotel ID 13921698 in the sandbox environment for the requests.

• Make sure the special_requests field includes a scenario that triggers an auto-reply.

• Check your email inbox or Booking.com account for the message.

What's next

Read the following guidelines to get familiar with the Messaging API: