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.

Use /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.

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.
5. Continue polling for subsequent messages.

✅ 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.

Use /messages/latest/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.

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.

✅ 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.

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

Use /messages/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.

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.

✅ 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.

Use /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.

✅ 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 and Use case 2 – Send a request and handle rejection.

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.

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.

✅ 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 Messaging API supports PNG and JPEG image attachments.

Use the following endpoints:

✅ 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.

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

✅ 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.

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

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

✅ 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.