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: Include the conversation and accommodation IDs.
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 full conversation history up to one year after guest checkout.
Steps:
- Get the
conversation,accommodationandreservationids from the messages/latest response. - Include them in the /messages/conversations request.
Example request:
{
"conversation": "cc872746-77f2-5886-ba7c-17e0497241b5",
"accommodation": 2098153,
"reservation": 4380765874
}Example response:
{
"request_id": "b1e97a78-bd84-4abc-9816-11a20f5eec00",
"data": {
"conversations": {
"messages": [
{
"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": [],
"id": "883989e0-d1b6-11ef-84a9-c5586b98bad5",
"timestamp": "2025-01-13T13:58:57.150Z"
},
{
"sender": "4a7be1f2-f788-561e-8738-f3560d0e228e",
"reply_to": "6c22a16d-a3bd-5f5b-82d9-ce1030f21b1f",
"content": "Thank you. Actually we were wondering whether there is hair dryer in the room",
"attachments": [],
"id": "2c81ced0-19f2-11f0-9abc-eb0ed4c38229",
"timestamp": "2025-01-15T12:07:16.797Z"
}
],
"id": "34e3f98d-f4e4-5a56-b33d-b773793e2a5b",
"reservation": "4447905900",
"access": "read_write",
"participants": [
{
"metadata": {
"type": "property",
"id": "6819547"
},
"id": "6c22a16d-a3bd-5f5b-82d9-ce1030f21b1f"
},
{
"metadata": {
"type": "guest"
},
"id": "4a7be1f2-f788-561e-8738-f3560d0e228e"
}
]
}
}
}
This example shows a conversation between a property and a guest retrieved via the Messaging API. The conversation contains two messages:
Message from the property (sender ID: 6c22a16d-a3bd-5f5b-82d9-ce1030f21b1f) welcoming the guest and offering assistance during their stay.
Guest reply (sender ID: 4a7be1f2-f788-561e-8738-f3560d0e228e) inquiring about the availability of a hair dryer in the room.
Each message includes metadata such as the sender, timestamp, message content, and message ID.
The conversation also includes participant information and indicates that the property has read-write access to this conversation.
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.