# About the Messaging API

**The Messaging API acts as a communication bridge between your travellers and accommodation, enabling post-booking interactions once a reservation is created.**

Messaging API pilot - 3.2 Beta access
This API collection is currently available to selected partners as part of an early access pilot.

- **Pilot phase** - This API is under active development and may change.
- **Limited access** - This API is currently offered to a limited number of pilot affiliate partners.
  - If you are not part of the pilot, you will not have access to this API collection.
  - Contact our partnerships team to request access.
- **Frequent updates** - The documentation and API reference will be regularly updated throughout the pilot.
  * Check the [Changelog](/demand/docs/whats-new/changelog) periodically for the latest updates.


## The /messages API collection

The Messages API collection is seamlessly integrated into Demand API - Accommodation API collection, and enables secure, structured, and context-aware post-booking communication between accommodation hosts and guests, specifically tied to reservations.

### Features

The Messaging API supports a wide range of capabilities:

![Capabilities of Messaging API includes two way communication, contextual conversations, conversation history and file attachments](/assets/capabilities.b64c08920c5917f4ef5da5e4869151f1551a069438b8e13a991e4df2d7d3253c.a0931a69.png)

### Who is this for?

We recommend Messaging API integrations to **existing Demand API Affiliate Partners** who wish to provide a better post-booking experience that boosts loyalty and trust, while reducing customer services inbound.

### Integration options

The Messaging API supports flexible integration approaches to suit a variety of partner needs.

Whether you're sending welcome messages, managing two-way conversations, or exchanging attachments, the API provides the necessary endpoints to build a seamless messaging experience into your system.

| Available integration modes | Description |
|  --- | --- |
| ✅ **Send messages** | Send text messages from partners to guests, optionally with attachments. |
| ✅ **Receive messages** | Retrieve incoming messages either by conversation or via latest polling. |
| ✅ **Message threading** | Maintain full conversation context using `conversation`. |
| ✅ **Attachments** | Upload images to send with messages or download attachments from guests. |
| ✅ **Conversation metadata access** | View details about message participants, timestamps, and message status. |
| ✅ **Reservation-based context** | Use reservation ID to filter or identify message threads for specific stays. |


### Benefits of integrating the Messaging API

Integrating the Messaging API into your system can bring some benefits such as:

![Key benefits of Messaging API includes scability, data for optimisation, loyalty boost and seamless integration](/assets/key-benefits.a1de08977e7c6b3fba02f2f522ac0fe71ae5a68de89b7fc44918ee4b10dc3244.a0931a69.png)

## The communication flow

Two-way communication is enabled after a reservation is created. Either party—traveller or host—can initiate contact.

###   Accommodation to traveller

div
div
ul
strong
1. The accommodation sends a "welcome message"
 after booking is confirmed
.
br
- Accommodation can use Booking.com extranet messaging centre or any other defined channel.


2. Affiliate partner system uses Messaging API to:

- Deliver messages to travellers in the defined channel (example: by email) via the [messages/send endpoint](/demand/docs/open-api/demand-api/messages/sendmessage).
- Fetch all messages from the property through Messaging API using the [/messages/latest](/demand/docs/open-api/demand-api/messages/fetchlatestmessages) and [/messages/latest/confirm](/demand/docs/open-api/demand-api/messages/confirmmessagereceipt).


#### Common accommodation messages

Property may communicate with the guest around the following topics:

| Topic | Examples / Details |
|  --- | --- |
| Welcome messages | - Greet the guest, introduce the property, confirm the booking.

 |
| Respond to special requests. | * Reply to specific bed/room arrangements, parking availability requests, etc.

 |
| Confirm available amenities. | * Provides details on facilites such as Wi-Fi, kitchen, air conditioning, laundry, or accessibility features.

 |
| Inform about local taxes | * Requests about tourist or city taxes charges.

 |
| Provides local recommendations | * Share information about nearby attractions, restaurants, shops, or tours and activities.

 |


Example of welcome message sent via the Booking.com platform:

![auto-reply welcome message](/assets/auto-reply-welcome.299028ff6c547117c5c621f8d4955e0a696bd0768644a07176a39eb4fe260228.a0931a69.png)

###  Traveller to Accommodation

div
div
ul
strong
1. Travellers may start the conversation by sending a message
 via their email, through affiliate partners system or via the Booking.com platform
.
br
2. Affiliate partner system uses Messaging API to:.

- Deliver messages from/to travellers in the defined channel (example: by email) via the [messages/send endpoint](/demand/docs/open-api/demand-api/messages/sendmessage).
- Fetch all messages from the property through Messaging API using the [/messages/latest](/demand/docs/open-api/demand-api/messages/fetchlatestmessages) and [/messages/latest/confirm](/demand/docs/open-api/demand-api/messages/confirmmessagereceipt).


#### Common traveller messages

Travellers may communicate with the accommodation around the following topics:

| Topic | Examples / Details |
|  --- | --- |
| Check-in details | - Estimated arrival and departure times (checkin/checkout times)
- Early or late check-in requests.
- Self check-in instructions or key collection info.

 |
| Directions & transport | - Request directions to the property.
- Parking availability.
- Request airport transfer info.

 |
| Booking modifications | - Requests about date or guest changes.
- Clarify cancellation and refund policies.

 |
| Amenities & services | - Confirm availability of Wi-Fi, kitchen, air conditioning, laundry, or accessibility features.

 |
| Special requests | - Requests for baby cots, extra beds, dietary needs, or celebration-related setups.
- Multiple rooms to be located near each other.

 |
| Local recommendations | - Request about nearby attractions, restaurants, shops, or tours and activities.

 |
| Payment & charges | - Confirm accepted payment methods, deposits, or tourist/city taxes.

 |


## Message delivery channels

Messages sent via the Messaging API can be delivered through a wide range of channels based on your particular setup and/or preferences:

| Participant | Where messages appear |
|  --- | --- |
| Guest | - In-app (Booking.com app)
- email
- partner Messaging centre
- AI or automated assistants (if available).

 |
| Accommodation (property) | - Extranet Messaging centre
- email notifications,
- or via connected systems (channel manager / PMS) through API.

 |
| Partner (you) | - Via Messaging API calls ([/messages/conversations](/demand/docs/open-api/demand-api/conversations/retrieve-conversation), [/messages/latest](/demand/docs/open-api/demand-api/messages/fetchlatestmessages), [/messages/latest/confirm](/demand/docs/open-api/demand-api/messages/confirmmessagereceipt), [/messages/send](/demand/docs/open-api/demand-api/messages/sendmessage), etc.)

 |


## Affiliate partners responsibilities

As a Managed Affiliate Partner integrating the Messaging API, you are responsible for ensuring successful message delivery to the end user.

You must:

* Guarantee reliable delivery of all messages sent through the API.
* Display messages clearly and without delay within your platform.
* Minimise delivery issues, which could negatively affect guest experience and partner performance.


## Available endpoints

### Messages endpoints

| Endpoint | Use it to ... |
|  --- | --- |
| [/messages/send](/demand/docs/open-api/demand-api/messages/sendmessage) | Send a new message starting a new conversation, or add a message to an existing conversation thread. |
| [/messages/latest](/demand/docs/open-api/demand-api/messages/fetchlatestmessages) | Retrieve the latest messages across all conversations (up to 100). |
| [/messages/latest/confirm](/demand/docs/open-api/demand-api/messages/confirmmessagereceipt)
 | Confirms the message was received.
This is required in order to receive new messages from [POST /messages/latest](/demand/docs/open-api/demand-api/messages/fetchlatestmessages).
 |
| [/messages/conversations](/demand/docs/open-api/demand-api/conversations/retrieve-conversation) | Retrieve the conversation history for the authenticated user up to 1 year after checkout. |


### Attachments endpoints

| Endpoint | Use it to ... |
|  --- | --- |
| [/messages/attachments/upload](/demand/docs/open-api/demand-api/attachments/uploadattachment) | Upload an image to a conversation (for files smaller than 1MB). |
| [/messages/attachments/metadata](/demand/docs/open-api/demand-api/attachments/getattachmentmetadata) | Retrieve details about a previously uploaded image, such as name, type and size. |
| [/messages/attachments/download](/demand/docs/open-api/demand-api/attachments/downloadmessageattachment) | Download an attachment. |


## What's next

Read the following guidelines to start getting familiar with the Messaging API:

* Get started - [Try the messaging endpoints](/demand/docs/getting-started/try-out-the-api/)
* Refer to our detailed guides for Messaging API examples and best practices:
  * [Manage messages](/demand/docs/messaging/manage-messages)
  * [Manage attachments](/demand/docs/messaging/manage-attachments)