Messaging troubleshooting

If you encounter issues when using Messaging API workflows, check the following common cases and their solutions.

If you encounter issues while using Messaging API workflows, check the following common cases and their solutions.

Conversation not found

Issue: Calling /messages/conversations with a reservation ID does not return a conversation.

Possible causes and fixes:

• The booking was not successfully created. Verify that the /orders/create response is successful and includes a reservation ID.
• The conversation may not yet be initialised. Wait a few seconds and retry.
• Ensure that both accommodation and reservation IDs are included in the request.

500 error on first call to /messages/latest

Issue: Calling /messages/latest and /messages/latest/confirm returns a 500 Internal Server Error, especially when using the endpoint for the first time.

Possible causes and fixes:

• The partner account may not yet be fully onboarded for Messaging API. In this case, contact your Booking.com Account Manager to complete the onboarding process.
• If onboarding is already complete, retry the request and check system status to rule out a temporary service disruption.

No messages returned when polling

Issue: The /messages/latest endpoint returns an empty list.

Possible causes and fixes:

• No new messages available – This is expected behaviour.
• System processing delay – A short delay may occur between when a message is sent and when it becomes available through the endpoint.
• Polling interval – If requests are too frequent, they may be rate-limited. Review and adjust your polling frequency.

Messages not marked as delivered

Issue: Messages remain in the queue even after confirmation.

Possible causes and fixes:

• Ensure you are sending the message UUID (from /messages/latest) to the /messages/latest/confirm , not the conversation or reservation ID.
• Confirm that the request body is in array format:

{ "messages": ["<message-uuid>"] }

Reply not sent

Issue: Sending a message with /messages/send does not return a message ID.

Possible causes and fixes:

• Ensure you are passing all three required identifiers: reservation, conversation, and accommodation.
• The request body must include either content or at least one valid attachment.
• Double-check the attachment upload process (See the Manage attachments guide).
• Inspect the response body for validation errors (400), as these often indicate missing or misformatted fields.

Not seeing auto-replies?

Check both guest-facing channels and your API polling setup:

Guest side:

• Verify you’re using the right hotel id (We recommend to use the test hotel ID 13921698 in sandbox before go live).
• Try different requests such as “extra bed” or “parking” to trigger predefined auto-replies.

Partner side (API):

• Confirm you are polling /messages/latest regularly — auto-replies will not be pushed to you.
• Make sure you are confirming messages with /messages/latest/confirm.
• Use /conversations if you need to retrieve the full history tied to a reservation.
• Ensure all Messaging API requests are authenticated with your Demand API v3.1 credentials.

Rate limits

Maximum of 100 requests per minute.

Next steps

Looking to improve or expand your Messaging API integration? Explore these resources: