Messaging API quick guide

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

This guide walks you through realistic messaging scenarios using our dedicated test hotel—complete with automated replies.

Before you start

Before you start, make sure you:

• Are part of the early access Messaging API pilot program
• Have completed the Demand API prerequisites.

You’ll need:

✓ A valid API key token.
✓ Your X-Affiliate-Id.
✓ Access to the sandbox environment.

Test setup

The Messaging Test Hotel is configured with automated replies:

• Welcome message when booking is confirmed.
• Reminder before check-in and checkout.
• Special request rejection (if remarks.special_requests is set).

End-to end flow

Here’s a simple flow on how messaging works:

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

Make a reservation at the Demand API Messaging Test Hotel (ID 13921698) using the /orders/preview and orders/create endpoints.

When successful, the orders/create response includes:

{
  "data": {
    "accommodation": {
      "reservation": 55303962,
      "order": "5006302528200239",
      "pincode": "884512"
    }
  }
}

→ reservation → Use this id to fetch and send messages.

Step 2 - 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:

Step 3 - Send a reply

Use messages/send to respond to the accommodation:

{
  "reservation": "55303962",
  "conversation": "55555",
  "accommodation": 13921698,
  "content": "Thanks, looking forward to my stay!"
}

Success response:

{
  "data": {
    "message_id": "41a53b20-1a0d-11f0-baca-e5019c8df435"
  }
}

Use case 2 - Booking with a 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 (ID 13921698) using 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"
      }

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?

• Confirm you’re using hotel ID 13921698 in sandbox.

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

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

Next steps

• Integrate /messages/latest and /messages/confirm polling into your workflow.
• Use /conversations to display history to agents or travellers.
• Handle guest replies programmatically.
• Monitor message delivery and failures.

Resources

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