Messaging troubleshooting

Find solutions to common issues when retrieving conversations, sending messages, confirming receipt and managing attachments using the Messaging API.

This guide helps you identify possible causes and resolve problems in your messaging integration.

Issue: Calling /messages/conversations does not return the expected conversation.

Use /messages/conversations with one of the following combinations:

• accommodation and reservation.
• accommodation and conversation.

Issue: /messages/latest returns an empty data.messages array or does not return the expected message.

Use /messages/latest to retrieve recent messages.

Example request

POST /messages/latest

{}

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

Issue: Your application submits message IDs to /messages/latest/confirm, but one or more messages are not confirmed.

Use /messages/latest/confirm to confirm receipt.

Example request

POST /messages/latest/confirm

{
  "messages": [
    "52100000-2be9-11f0-bced-bdc849c480b6"
  ]
}

Example response

{
  "request_id": "cdb0b154-2eae-481b-8fee-fb2725296e1f",
  "confirmedMessages": [
    "52100000-2be9-11f0-bced-bdc849c480b6"
  ]
}

The confirmedMessages array contains the IDs confirmed by the API.

Issue: Calling /messages/send fails or does not return a message ID.

Use /messages/send to send a message to an existing conversation.

Example request

POST /messages/send

{
  "accommodation": "13921698",
  "conversation": "bbb76179-7565-5a23-8632-33e164aa13db",
  "content": "Hello! Could you please confirm the check-in time?"
}

A successful response returns the message identifier in data.message.

Issue: You send a message to the Demand API Messaging Test Hotel but do not receive the expected automated response.

The test accommodation (13921698) is configured to generate automated responses for selected messaging scenarios.

1. Call /messages/conversations to retrieve the conversation associated with the test reservation.
2. Verify that your message was sent to the correct conversation.
3. Poll /messages/latest for the automated response.
4. Match the returned conversation identifiers to the test reservation.
5. Confirm receipt after successfully processing the response.

For practical examples, see Use case 1 – Booking and welcome message and Use case 2 – Send a request and handle rejection.

Issue: Uploading, retrieving metadata or downloading an attachment does not succeed.

For detailed examples, see Manage attachments.

Issue: Messaging API requests fail because of authentication or access restrictions.

For authentication details, see Authentication.

Issue: A Messaging API request returns HTTP 500.

An HTTP 500 response indicates a server-side error. The current Messaging API schema does not define a specific cause for this response.

1. Check the response details and retain the request_id, if returned.
2. Verify that your request uses the correct endpoint and required fields.
3. Check whether the failure is temporary before retrying.
4. Avoid blindly retrying /messages/send, as this could result in duplicate messages if the original request was processed.
5. If the issue persists, contact Booking.com support and provide the relevant request information.

Issue: Messaging API requests are rejected because too many requests have been submitted.

Messaging API integrations should follow the applicable Demand API rate limits.

✅ Avoid excessive polling: Choose a polling interval appropriate for your application.

✅ Handle HTTP 429 responses: Follow the applicable rate-limit guidance and wait before retrying.

✅ Use backoff strategies: Increase the delay between retries when requests are repeatedly rate-limited.

✅ Avoid unnecessary requests: Use /messages/latest for ongoing synchronisation rather than repeatedly retrieving complete conversations.

For more information, see HTTP 4xx scenarios.

If the issue persists, collect the following information to help investigate the problem: