MESSAGING
/
Try Messaging API
Last updated

Messaging API quick guide

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

This guide helps you try out the Messaging API in 15–30 minutes using our dedicated test hotel with automated replies and covers both v3.1 and v3.2 behaviour.

⏱️ 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:
    1. Create a test booking and trigger auto-replies.
    2. Retrieve an automated welcome message.
    3. Confirm receipt.
  • Code samples: Minimal, only required fields.

Note: This guide shows both v3.1 and v3.2 behaviours — where v3.2 differs, examples are highlighted in tabs.

Before you start

Make sure you:

  • Are a Managed Affiliate Partner and part of the early pilot programme for Beta endpoints.
  • Complete the Demand API prerequisites.

You'll need:

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

Every Messaging API request must be authenticated with your Demand API v3.1 and/or v3.2 credentials.

Test setup

✓ Test accommodation ID 13921698 - Demand API Messaging Test Hotel

The Messaging Test Hotel is preconfigured with automated replies, such as:

  • Welcome message after booking confirmation.
  • Rejections for requests like extra beds or parking.

Note: Real accommodations can configure their own auto-replies via Booking.com’s Extranet messaging centre.

Try it out — minimal flow

Book → get a message → confirm receipt.

Step 1 - Create a test order

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

Important

Always provide a valid test credit card in the payment field; otherwise your booking request will fail.

See Testing payments and the orders/create guide for instructions.

When successful, the orders/create response includes:

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

→ Use the reservation id to fetch conversations and send messages.

Step 2 - Retrieve the welcome message

After the booking is confirmed, the Demand API Messaging Test Hotel automatically sends a welcome message.

  • Guest view - The welcome message appears in the guest’s email (or registered app).
  • Accommodation view - The property sees the booking and message in the Booking.com Extranet messaging centre.

Example in Booking.com Extranet messaging centre:

Booking.com Extranet showing auto-reply welcome message

Accommodation hosts can use Booking.com Extranet messaging centre or any other channel to communicate with guests.

→ Call /messages/latest endpoint to fetch the automated welcome message.

Request:

  • Empty POST request.
{
  "data": {
    "messages": [
      {
        "content": "Hello, thanks for booking Demand API Test Hotel!",
        "timestamp": "2025-07-29T12:04:05.466Z"
      }
    ]
  }
}

Step 3 - Confirm receipt (happy path)

After processing, confirm messages with /messages/latest/confirm.

Request:

{
    "messages":["3f986fc8-b944-4501-b8d1-430e833ca756"]
}

When successful, the response returns HTTP 200 OK. No confirmation message.

Step 4 — Optional confirmation scenarios

Partial confirmation:

  • Multiple message IDs sent, only some confirmed.
  • Response - HTTP 200 OK; confirmedMessages in v3.2 contains only the successful confirmed IDs.

All confirmations failed:

  • No message IDs confirmed.
  • Response - HTTP 500 — retry usually succeeds due to cold start delays.

Notes & tips

  • Auto-generated messages appear within ~15–20 minutes.
  • Retry requests if you get HTTP 500 due to cold starts.
  • Always use confirmedMessages from the response to track receipt in v3.2.

Next steps

Previous page
Next page