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 responses, confirming delivery, and accessing full conversation histories, so you can integrate the flow in your own plaform.
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:
Guests
- Send - From the time of booking until the reservation is archived (66 days after checkout or cancellation)
- Read - Until 66 days after checkout or cancellation.
Accommodation hosts
- Send - From the time of the booking until 7 days after checkout or cancellation.
- If a guest sends a message, hosts can reply for up to 14 days from the guest's message timestamp, even if this exceeds the 7-day post-checkout limit.
All Users
- Messages are accessible for reading until 1 year after checkout or cancellation.
- After 1 year, message history is no longer available.
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). |
/messages/attachments/metadata | Retrieve details of uploaded attachments. (See the Managing attachments guide for more details) |
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:
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_id": "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": "55555",
"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": [1234562],
"content": "I appreciate you consider our request."
"reply_to": "55555"
}See the Managing attachments guide for how to upload images and view restrictions.
Step 2 - Retrieve the latest messages.
Use the /messages/latest endpoint to fetch up to 100 of the most recent messages.
Request: Send an empty request body.
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 | 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",
"id": "6a7ecae8-d0be-5cd2-85e9-8d3f6eba6d2d"
},
"content": "Approved to modify reservation at lower price",
"id": "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",
"id": "6a7ecae8-d0be-5cd2-85e9-8d3f6eba6d2d"
},
"content": "from 49.50 to 40 EUR",
"id": "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",
"id": "ccffd27c-7e53-5f31-9760-a5846de75d8e"
},
"content": "Unfortunately, we must apply some cancellation fees according to our cancellation policies",
"id": "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",
"id": "cc872746-77f2-5886-ba7c-17e0497241b5"
},
"content": "Ok, lets proceed with the cancellation",
"id": "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 message receipt
Use /messages/latest/confirm to acknowledge messages you've received.
Required parameter
messages- The list of messages 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 historial conversations
Use the /messages/conversations, 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 your request to /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":le",
"attachments": [],
"id": "2c81ced0-19f2-11f0-9abc-eb0ed4c38229",
"timestamp": "2025-04-15T12:07:16.797Z"
},
{
"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"
}
],
"id": "34e3f98d-f4e4-5a56-b33d-b773793e2a5b",
"reservation": "4447905900",
"access": "read_write",
"participants": [
{
"metadata": {
"type": "guest"
},
"id": "4a7be1f2-f788-561e-8738-f3560d0e228e"
},
{
"metadata": {
"type": "property",
"id": "6819547"
},
"id": "6c22a16d-a3bd-5f5b-82d9-ce1030f21b1f"
}
]
}
}
}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 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.