# Messaging best practices

**Follow these recommendations to build reliable messaging integrations between guests and properties using the Messaging API.**

This guide covers message synchronisation, conversation management, receipt confirmation, attachment handling and error recovery.

The recommendations apply to applications that integrate guest and property communication into their own platforms.

## Retrieve and synchronise messages regularly

Use [/messages/latest](/demand/docs/additional-services/messaging/messaging/messages/latest) to retrieve recent messages sent by guests and properties.

By default, the endpoint returns up to 100 messages in reverse chronological order, with the newest messages first.

### Recommended approach

1. Poll /messages/latest at an interval appropriate for your application's communication requirements.
2. Identify the conversation associated with each returned message.
3. Process and store the messages according to your integration needs.
4. Confirm successfully processed messages using [/messages/latest/confirm](/demand/docs/additional-services/messaging/messaging/messages/confirm).
5. Continue polling for subsequent messages.


### Best practices

✅ **Choose an appropriate polling interval:** Balance timely message retrieval with the applicable Demand API rate limits.

✅ **Process messages before confirming:** Ensure your application has successfully handled each message before confirming its receipt.

✅ **Track message IDs:** Use the unique message identifiers to detect messages already processed by your application.

✅ **Associate messages with conversations:** Use the conversation, accommodation and reservation identifiers to match messages to the correct booking.

Message synchronisation
The /messages/latest endpoint retrieves recent messages available to your affiliate account, not only messages associated with a specific reservation.

Confirmation through /messages/latest/confirm is required to continue receiving new messages.

## Confirm message receipt reliably

Use [/messages/latest/confirm](/demand/docs/additional-services/messaging/messaging/messages/confirm) after successfully processing messages retrieved through /messages/latest.

The endpoint accepts an array of message IDs and returns the IDs confirmed by the API in `confirmedMessages`.

### Recommended approach

1. Process the messages returned by /messages/latest.
2. Collect the IDs of successfully processed messages.
3. Submit those IDs to /messages/latest/confirm.
4. Compare the submitted IDs with the returned `confirmedMessages` array.
5. Update your application's confirmation state only for messages confirmed by the API.


### Best practices

✅ **Confirm only processed messages:** Avoid confirming messages before your application has successfully handled them.

✅ **Check confirmation results:** Do not assume every submitted message ID was confirmed. Verify the `confirmedMessages` response.

✅ **Track processing and confirmation separately:** A message can be processed by your application without its receipt having been confirmed by the API.

✅ **Handle repeated messages safely:** Use message IDs to avoid processing the same message more than once.

Receipt confirmation
Confirming receipt does not indicate that a guest has read the message.

The confirmation operation is part of message synchronisation between your application and the Messaging API.

## Maintain conversation context

Each conversation is associated with an accommodation and may also be associated with a reservation.

Use [/messages/conversations](/demand/docs/additional-services/messaging/messaging/conversations) to retrieve an existing conversation and its messages.

The endpoint accepts an accommodation ID together with either a conversation ID or a reservation ID.

### Recommended approach

1. Retrieve the conversation associated with the reservation.
2. Store the conversation ID and its associated accommodation and reservation identifiers.
3. Use the conversation ID when sending messages or managing attachments.
4. Retrieve the conversation again when your application needs its message history.


### Best practices

✅ **Store conversation identifiers:** Maintain the relationship between accommodation, reservation and conversation IDs.

✅ **Use the correct identifier for each operation:** Retrieve conversations using a reservation or conversation ID, but use the conversation ID when sending messages.

✅ **Retrieve conversation history when needed:** Use /messages/conversations to display messages and participants associated with a specific conversation.

✅ **Identify message senders:** Use participant metadata to distinguish messages sent by guests and properties.

Existing conversations
The Messaging API operates on existing conversations.

The /messages/send endpoint does not create a new conversation. Retrieve the conversation ID before sending a message.

## Send messages using existing conversations

Use [/messages/send](/demand/docs/additional-services/messaging/messaging/messages/send) to send plain-text messages to existing conversations.

The request requires:

* `accommodation`: The accommodation ID.
* `conversation`: The conversation ID.
* `content`: The message body.


You can optionally include an array of previously uploaded attachment IDs.

### Best practices

✅ **Validate conversation context:** Verify that the accommodation and conversation IDs refer to the intended booking.

✅ **Provide clear message content:** Keep messages relevant to the guest's reservation and easy to understand.

✅ **Track sent messages:** Store the message ID returned in `data.message` when needed for your application's communication workflows.

✅ **Handle retries carefully:** Check the outcome of failed or interrupted requests before resending a message to reduce the risk of duplicate communication.

For practical examples, see [Use case 1 – Booking and welcome message](/demand/docs/messaging/manage-messages-use-case1) and [Use case 2 – Send a request and handle rejection](/demand/docs/messaging/manage-messages-use-case2).

## Display conversation history in your application

Use /messages/conversations to retrieve the messages and participants associated with an existing conversation.

This can help your application provide a consistent communication history for guests or customer-support teams.

### Recommended approach

1. Identify the accommodation and conversation associated with the booking.
2. Retrieve the conversation using /messages/conversations.
3. Process the returned `messages` and `participants` arrays.
4. Use the sender IDs and participant metadata to identify who sent each message.
5. Display messages using their content and timestamps.


### Best practices

✅ **Preserve message context:** Display messages within the correct conversation and reservation.

✅ **Identify participants correctly:** Match each message's sender ID to the corresponding participant.

✅ **Use message timestamps:** Display messages in the appropriate order for your application.

✅ **Handle attachments:** Use attachment IDs to retrieve images when needed.

The /messages/conversations response contains a list of messages and conversation participants.

Use /messages/latest for ongoing message synchronisation rather than repeatedly retrieving the complete conversation.

## Handle attachments securely

The Messaging API supports PNG and JPEG image attachments.

Use the following endpoints:

| Endpoint | Purpose |
|  --- | --- |
| [/messages/attachments/upload](/demand/docs/additional-services/messaging/messaging/attachments/upload) | Upload a base64-encoded image and retrieve its attachment ID. |
| [/messages/attachments/metadata](/demand/docs/additional-services/messaging/messaging/attachments/metadata) | Retrieve the file name, MIME type and size of an attachment. |
| [/messages/attachments/download](/demand/docs/additional-services/messaging/messaging/attachments/download) | Retrieve the base64-encoded content of an attachment. |


### Best practices

✅ **Validate files before uploading:** Check that each image uses a supported format and does not exceed 1,048,576 bytes (1 MiB).

✅ **Calculate file size correctly:** Set `file_size` to the original binary file size, not the length of the base64-encoded string.

✅ **Upload before sending:** Upload each image separately and include the returned attachment IDs in the `attachments` array of /messages/send.

✅ **Protect attachment content:** Avoid exposing base64-encoded files in logs or other unsecured locations.

✅ **Validate downloaded files:** Check the content and file type before storing or displaying attachments.

For detailed instructions, see [Manage attachments](/demand/docs/messaging/manage-attachments).

## Handle errors and retries appropriately

Messaging integrations should account for invalid requests, temporary failures and rate limits.

### Best practices

✅ **Validate required fields:** Ensure requests contain the correct accommodation, conversation and message identifiers.

✅ **Handle authentication failures:** Verify your Bearer token, `X-Affiliate-Id` and Messaging API access.

✅ **Respect rate limits:** Avoid excessive polling and handle HTTP 429 responses according to the applicable Demand API guidance.

✅ **Avoid unnecessary duplicate operations:** Check the outcome of a failed request before retrying operations such as sending messages.

✅ **Track request identifiers:** Retain the `request_id` returned by the API when troubleshooting requests or contacting support.

For additional guidance, see [Error handling](/demand/docs/support/error-handling/about-errors).

## Protect guest and reservation information

Messaging data can contain personal information, reservation details and image attachments.

Apply appropriate security and data-protection practices when processing or storing this information.

### Best practices

✅ **Use secure authentication:** Protect your API credentials and avoid exposing them in client-side applications or logs.

✅ **Restrict access:** Make messages and attachments available only to authorised users within your application.

✅ **Apply retention policies:** Store messages and attachments only for as long as necessary under your applicable data-retention requirements.

✅ **Avoid logging sensitive content:** Do not log complete message bodies or base64-encoded attachments unless explicitly required and appropriately protected.

✅ **Handle downloaded attachments safely:** Validate files and apply suitable security checks before processing or displaying them.

## Additional resources

* [Messaging API quick guide](/demand/docs/messaging/try-out-messages) – Test the basic messaging workflow using the Demand API Messaging Test Hotel.
* [Manage messages](/demand/docs/messaging/manage-messages) – Review the available messaging operations and workflows.
* [Use case 1 – Booking and welcome message](/demand/docs/messaging/manage-messages-use-case1) – Retrieve a welcome message and send a reply.
* [Use case 2 – Send a request and handle rejection](/demand/docs/messaging/manage-messages-use-case2) – Send a guest request and process an automated rejection.
* [Manage attachments](/demand/docs/messaging/manage-attachments) – Learn how to upload, send and retrieve image attachments.
* [Messaging API FAQs](/demand/docs/messaging/messaging-api-faqs) – Find answers to common integration questions.