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

div
strong
⏱️ Estimated time to complete:
 15 - 30 minutes 
br
br
ul
li
strong
Purpose:
 Quickly try out the Messaging API.
li
strong
When to use:
 You want to test post-booking communication flows.
li
strong
You'll learn how to:
ol
li
Create a test booking and trigger auto-replies.
li
Retrieve an automated welcome message.
li
Confirm receipt.
li
strong
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](/demand/docs/getting-started/try-out-the-api#before-you-start---prerequisites).


You'll need:

✓ A valid API key token.
✓ Your X-Affiliate-Id.
✓ Access to the [sandbox environment](/demand/docs/getting-started/sandbox).

Every Messaging API request must be [authenticated](/demand/docs/development-guide/authentication) with your Demand API v3.1 and/or v3.2 credentials.

## Test setup

div
strong
✓ 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](https://www.booking.com/hotel/nl/demand-api-messaging-test.html?aid=956509) (ID 13921698) via [/orders/preview](/demand/docs/open-api/demand-api/orders/orders/preview) and [orders/create](/demand/docs/open-api/demand-api/orders/orders/create).

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

See [Testing payments](/demand/docs/payments/how-to#testing) and the [orders/create guide](/demand/docs/orders-api/order-preview-create#create-your-orders) for instructions.

When successful, the [orders/create](/demand/docs/open-api/demand-api/orders/orders/create) response includes:


```json
{
  "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](/assets/welcome-extranet.2024bd824dd4fd1364828465700cc4abe33c9b29c85c20912f8bf933e3662f33.a0931a69.png)

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

→ Call [/messages/latest endpoint](/demand/docs/open-api/demand-api/messages/fetchlatestmessages) to fetch the automated welcome message.

**Request:**

* Empty POST request.


v3.1 response

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

v3.2 response

```json
{
  "data": {
    "messages": [
      {
        "content": "Hello, thanks for booking Demand API Test Hotel!",
        "timestamp": "2025-07-29T12:04:05.466Z",
        "id": "3f986fc8-b944-4501-b8d1-430e833ca756"
      }
    ]
  }
}
```

### Step 3 - Confirm receipt (happy path)

After processing, confirm messages with [/messages/latest/confirm](/demand/docs/open-api/demand-api/messages/confirmmessagereceipt).

**Request:**


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

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

v3.2 response
In v3.2, the response includes `confirmedMessages` — IDs of messages successfully confirmed.


```json
{
  "confirmedMessages": [
    "3f986fc8-b944-4501-b8d1-430e833ca756"
  ]
}
```

### 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

* For full messaging scenarios — including sending messages, handling rejections, and troubleshooting — see the [Manage messages guide](/demand/docs/messaging/manage-messages)
* Check the [Manage attachments guide](/demand/docs/messaging/manage-attachments) to learn how to send/download images.
* Review [Best practices](/demand/docs/messaging/messaging-best-practices) to align your messaging flows.
* Check the [Messaging API v3.2 Migration guide](/demand/docs/migration-guide/v3.2/messaging/intro) for breaking changes.