Try Messaging API out

If you are a Booking.com Managed Affiliated Partner and are part of the early access pilot program you can start trying our Messages API in your client application.

Quick guide

Follow this quick guide to start playing around with our Messaging API endpoints.

By building requests based on basic use cases on our testing hotel you will learn how to integrate with your application so your travellers can contact the property as well as the other way round.

Before you start

Before 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

To test these endpoints, we recommend using our dedicated sandbox hotel:

✓ Test accommodation ID 13921698 - Demand API Messaging Test Hotel

• 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.

Example of send/message request:

{
    "reservation": "55303962",
    "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",
    }
}

Demand API Messaging Test Hotel has set all its auto-replies via Booking.com extranet message 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.

What's next

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