Managing messages
Learn how to manage messages and conversations between guests and properties via the Messaging API.
Introduction
Use the Messaging API to send and retrieve messages between guests and properties.
This guide walks you through sending messages, fetching the latest replies, confirming delivery, and accessing conversation histories. These steps help you integrate the messaging flow into your platform.
Authentication
All Messaging API endpoints require:
- A valid API token.
- Your affiliate ID.
Use the same credentials as for other Demand API v3 endpoints. See Authentication guide for more details.
Message timing rules
Messaging availability is restricted to specific timeframes based on reservation status:
| User type | Send window | Read window |
|---|---|---|
| Guests | From booking → 66 days post-checkout/cancellation. | Until 66 days post-checkout/cancellation. |
Accommodation | From booking → 7 days post-checkout/cancellation. If guest sends a message: +14 days to reply. | (Same as guests) |
| All Users | Messages readable up to 1 year after checkout or cancellation. |
Available endpoints
| Endpoint | Use it to ... |
| /messages/send | Send a message to start or continue a conversation. |
| /messages/latest | Retrieve up to the 100 most recent messages. |
| /messages/latest/confirm | Confirm receipt of messages from /messages/latest. |
| /messages/conversations | Fetch the full message history (up to 1 year after checkout). |
Retrieve details of uploaded attachments. (See the Managing attachments guide for more details) |
Message flow overview
- Step 1 — Send a message.
- Step 2 — Retrieve latest messages.
- Step 3 — Confirm delivery
- Optional — Fetch full conversation history
Steps - Sending and managing messages
Step 1 - Send a message
To initiate a conversation, use the /messages/send endpoint with the required parameters.
Starting a new conversation:
Provide the following:
| Required fields | |
|---|---|
✅ reservation | ID of the reservation. |
✅ accommodation | ID of the accommodation. |
✅ content | The body of the message to be sent. |
If a special request was added when creating the booking (via orders/create endpoint), this is automatically sent as the first message and generates a conversation id.
Example request:
{
"reservation": "4380765874",
"accommodation": 2098153,
"content": "Thank you for choosing Demand API Messaging Test Hotel! It is indeed a great pleasure to welcome you to our hotel."
}Example response
A successful response includes the assigned message ID:
{
"request_id": "cdb0b154-2eae-481b-8fee-fb2725296e1f",
"data": {
"message": "3164e570-19e0-11f0-baca-e5019c8df435",
}
}Sending a message to an existing conversation
If a conversation already exists, send a message by including the conversation ID together with the content.
Example:
{
"conversation": "8586a789",
"accommodation": "6819547",
"content": "Thanks for your request. We are working on it and will do all we can to meet your requirements."
}
Optional parameters
You may also include:
reply_to- The ID of the message being replied to. Defaults to the conversation ID.attachment id- The identifier of an image (uploaded via the /attachments/upload endpoint).
Example:
{
"accommodation": 2098153,
"attachments":["c325f460-1dc6-11f0-80f0-8d0908786f77"],
"content": "I appreciate you consider our request.",
"reply_to": "8586a789"
}See the Managing attachments guide for how to upload images and view restrictions.
Step 2 - Retrieve latest messages.
Use the /messages/latest endpoint to fetch up to 100 of the most recent messages.
Request:
- Just send an empty body request.
Response: The response includes a list of messages.
Each message includes metadata about the sender, content, attachments, and timestamp.
sender | Information about the participant (guest or property). |
attachments | Will be empty if no attachments. |
timestamp | ISO timestamp of the message - This is relevant for tracking purposes. |
content | Body of the message. |
In this example there are 4 messages, some from the same conversation:
{
"request_id": "ddcf96b3-e17c-4e6f-8f8c-4d685489ce04",
"data": {
"messages": [
{
"reply_to": "cc8a390c-6b54-5a52-ae09-fc1415c479a3",
"conversation": {
"reservation": "4363562386",
"accommodation": "2098153",
"conversation": "8586a789"
},
"content": "Approved to modify reservation at lower price",
"message": "8a269910-19d1-11f0-bb60-972708bd278a",
"sender": {
"participant_id": "6c22a16d-a3bd-5f5b-82d9-ce1030f21b1f",
"metadata": {
"type": "property",
"id": "Demand API Messaging Test Hotel"
}
},
"attachments": [],
"timestamp": "2025-04-15T08:13:40.000Z"
},
{
"reply_to": "cc8a390c-6b54-5a52-ae09-fc1415c479a3",
"conversation": {
"reservation": "4363562386",
"accommodation": "2098153",
"conversation": "8586a789"
},
"content": "from 49.50 to 40 EUR",
"message": "94a20230-19d1-11f0-ad0b-070f57f7896d",
"sender": {
"participant_id": "6c22a16d-a3bd-5f5b-82d9-ce1030f21b1f",
"metadata": {
"type": "property",
"id": "Demand API Messaging Test Hotel"
}
},
"attachments": [],
"timestamp": "2025-04-15T08:13:58.000Z"
},
{
"reply_to": "7cde2da2-a3f3-5e68-8eb8-352672074534",
"conversation": {
"reservation": "4580465458",
"accommodation": "2098153",
"conversation": "ccffd27c-7e53-5f31-9760-a5846de75d8e"
},
"content": "Unfortunately, we must apply some cancellation fees according to our cancellation policies",
"message": "38914fd0-19ce-11f0-9ba3-8fd61549a30a",
"sender": {
"participant_id": "6c22a16d-a3bd-5f5b-82d9-ce1030f21b1f",
"metadata": {
"type": "property",
"id": "Demand API Messaging Test Hotel"
}
},
"attachments": [],
"timestamp": "2025-04-15T07:49:55.000Z"
},
{
"reply_to": "6c22a16d-a3bd-5f5b-82d9-ce1030f21b1f",
"conversation": {
"reservation": "4380765874",
"accommodation": "6819547",
"conversation": "cc872746-77f2-5886-ba7c-17e0497241b5"
},
"content": "Ok, lets proceed with the cancellation",
"message": "41544f00-19d8-11f0-9ea6-f35823f251fe",
"sender": {
"participant_id": "00a40ffc-f7a7-55d7-a8d8-b45ef2a7a99e",
"metadata": {
"type": "guest",
"id": ""
}
},
"attachments": [],
"timestamp": "2025-04-15T09:01:44.000Z"
}
]
}
}Step 3 - Confirm delivery
Use /messages/latest/confirm to acknowledge messages you've received.
Required parameter
messages- The list of message IDs (UUIDS) that needs to be confirmed.
Get the message id from the message/latest response.
Example request:
{
"messages":["3f986fc8-b944-4501-b8d1-430e833ca756"]
}
A successful response will return a 200 OK.
Optional - Retrieve full conversation history
Use the /messages/conversations endpoint, to retrieve the entire conversation between a guest and an accommodation, up to one year after guest checkout.
Requirements:
- The request must include the
accommodationid and either theconversationid or thereservationid — but not both. - This ensures precise targeting of the conversation context.
Steps:
- Retrieve the relevant
accommodation,conversationorreservationids from the messages/latest response. - Send a request to /messages/conversations using one of the supported combinations:
Example 1 – Retrieve by accommodation + conversation ID
{
"accommodation": "2098153",
"conversation": "cc872746-77f2-5886-ba7c-17e0497241b5"
}Example 2 – Retrieve by accommodation + reservation ID
{
"accommodation": "2098153",
"reservation": "4380765874"
}
Example response:
{
"request_id": "b1e97a78-bd84-4abc-9816-11a20f5eec00",
"data": {
"conversation": {
"id": "34e3f98d-f4e4-5a56-b33d-b773793e2a5b",
"reservation": "4447905900",
"access": "read_write",
"messages": [
{
"id": "883989e0-d1b6-11ef-84a9-c5586b98bad5",
"sender": "6c22a16d-a3bd-5f5b-82d9-ce1030f21b1f",
"reply_to": "34e3f98d-f4e4-5a56-b33d-b773793e2a5b",
"content": "Demand API Messaging Test Hotel,\n\nThank you for choosing Demand API Messaging Test Hotel, we look forward to taking care of you during your stay. If you have any questions you can best reach us here or call reception at 04597206.\n\nBest wishes",
"attachments": [],
"timestamp": "2025-01-13T13:58:57.150Z"
},
{
"id": "2c81ced0-19f2-11f0-9abc-eb0ed4c38229",
"sender": "4a7be1f2-f788-561e-8738-f3560d0e228e",
"reply_to": "34e3f98d-f4e4-5a56-b33d-b773793e2a5b",
"content": "Thank you. Actually we were wondering whether there is hair dryer in the room",
"attachments": [],
"timestamp": "2025-01-15T12:07:16.797Z"
}
],
"participants": [
{
"id": "6c22a16d-a3bd-5f5b-82d9-ce1030f21b1f",
"metadata": {
"type": "property",
"id": "6819547"
}
},
{
"id": "4a7be1f2-f788-561e-8738-f3560d0e228e",
"metadata": {
"type": "guest"
}
}
]
}
}
}This example shows a real-time conversation between a property and a guest, retrieved via the Messaging API. It includes:
Two messages:
- A welcome message from the property, offering assistance.
- A follow-up from the guest, asking about a hair dryer.
Each message contains structured metadata:
id,sender,reply_to,content,timestamp, andattachments.
The conversation object also includes:
participantslist, identifying each party (guest or property).accesslevel — which here is "read_write".
The reply_to field can refer to either the conversation id or message id. In the above example, it refers to the same conversation id "34e3f98d-f4e4-5a56-b33d-b773793e2a5b".
Rate limits
- Maximum of 100 requests per minute per partner.
Error handling
Standard HTTP status codes are used (e.g. 403 Forbidden, 400 Bad Request).
Refer to our General error handling guide for details.
- Get started - Try the messaging endpoints with a Testing hotel.
- Refer to the Managing attachments guide for instructions on uploading/downloading images.