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

API version
This guide applies to the Messaging API v3.2 Stable.

All Messaging API endpoints use the `/3.2/messages/` path prefix.

## Conversation not found

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

### Possible causes and solutions

| Possible cause | Recommended action |
|  --- | --- |
| Incorrect accommodation or reservation ID | Verify that the identifiers match the reservation associated with the conversation. |
| Incorrect conversation ID | If retrieving by conversation ID, verify that it belongs to the specified accommodation. |
| Reservation not created successfully | Check that /orders/create completed successfully and returned a reservation ID. |
| Conversation not yet available | Allow time for the conversation to become available after reservation creation, then retry according to your application's retry strategy. |
| Conversation not accessible | Verify that the conversation is available to your authenticated affiliate account. |


Use [/messages/conversations](/demand/docs/additional-services/messaging/messaging/conversations) with one of the following combinations:

* `accommodation` and `reservation`.
* `accommodation` and `conversation`.


Provide either a reservation ID or a conversation ID together with the accommodation ID.

The current schema defines these as alternative request structures.

## No messages returned when polling

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

### Possible causes and solutions

| Possible cause | Recommended action |
|  --- | --- |
| No new messages available | An empty response can occur when there are no recent messages available to retrieve. |
| Message not yet available | Allow time for the message to become available before polling again. |
| Previous messages not confirmed | Check whether previously processed messages have been confirmed using /messages/latest/confirm. |
| Incorrect affiliate account | Verify that the request uses the expected `X-Affiliate-Id` and valid credentials. |
| Expected message belongs to another conversation | Check the conversation, accommodation and reservation identifiers returned by the API. |


Use [/messages/latest](/demand/docs/additional-services/messaging/messaging/messages/latest) to retrieve recent messages.

**Example request**

POST `/3.2/messages/latest`

```json
{}
```

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

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

Use the conversation identifiers returned in each message to identify the correct booking.

## Messages not confirmed

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

### Possible causes and solutions

| Possible cause | Recommended action |
|  --- | --- |
| Incorrect message ID | Use the `id` returned for each message by /messages/latest, not the conversation or reservation ID. |
| Incorrect request structure | Provide an array of message IDs in the `messages` field. |
| Confirmation result not checked | Compare the submitted IDs with the returned `confirmedMessages` array. |
| API request failed | Check the HTTP status code and response details before retrying. |


Use [/messages/latest/confirm](/demand/docs/additional-services/messaging/messaging/messages/confirm) to confirm receipt.

**Example request**

POST `/3.2/messages/latest/confirm`

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

**Example response**

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

The `confirmedMessages` array contains the IDs confirmed by the API.

Receipt confirmation
Confirm messages only after successfully processing them.

If an ID is missing from `confirmedMessages`, do not assume that its receipt was confirmed. Investigate the result before updating your application's confirmation state.

## Unable to send a message

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

### Possible causes and solutions

| Possible cause | Recommended action |
|  --- | --- |
| Missing conversation ID | Provide the existing conversation ID in the `conversation` field. |
| Reservation ID used instead of conversation ID | Retrieve the conversation using /messages/conversations and use the returned `data.conversation.id`. |
| Missing required fields | Include `accommodation`, `conversation` and `content` in the request. |
| Incorrect accommodation ID | Verify that the accommodation ID belongs to the specified conversation. |
| Invalid attachment ID | If attachments are included, verify that each ID was returned by a successful /messages/attachments/upload request. |
| Authentication or access issue | Verify your credentials, affiliate identifier and access to the conversation. |


Use [/messages/send](/demand/docs/additional-services/messaging/messaging/messages/send) to send a message to an existing conversation.

**Example request**

POST `/3.2/messages/send`

```json
{
  "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`.

Existing conversations
The /messages/send endpoint does not create conversations.

If you only have the reservation ID, retrieve the associated conversation using /messages/conversations before sending a message.

## Automated replies not received

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

### Check the test setup

| Check | Recommended action |
|  --- | --- |
| Test accommodation | Verify that you're using accommodation ID `13921698` in the sandbox environment. |
| Test reservation | Confirm that the reservation was created successfully and is associated with the test accommodation. |
| Conversation ID | Verify that the message was sent to the conversation associated with the test reservation. |
| Supported test scenario | Use a scenario configured for the test hotel, such as a welcome message or an extra-bed request. |
| Message availability | Allow time for the automated response to become available. |


### Check your API integration

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.


The current Messaging API collection uses /messages/latest to retrieve new messages. It does not define a webhook endpoint for new-message notifications.

Automated responses might not be available immediately after a message is sent.

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

## Attachment upload or download fails

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

### Possible causes and solutions

| Possible cause | Recommended action |
|  --- | --- |
| Unsupported file format | Use PNG or JPEG images with an appropriate MIME type. |
| File exceeds the size limit | Ensure the original binary file does not exceed 1,048,576 bytes (1 MiB). |
| Incorrect file size | Set `file_size` to the original binary file size, not the length of the base64-encoded content. |
| Invalid base64 content | Verify that `file_content` contains the complete, correctly encoded image. |
| Incorrect attachment ID | Use the attachment ID returned by /messages/attachments/upload or associated with an existing message. |
| Incorrect conversation context | Verify that the accommodation, conversation and attachment identifiers belong together. |
| Missing required upload fields | Include `accommodation`, `conversation`, `file_size`, `file_name`, `file_type` and `file_content`. |


### Attachment 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. |


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

## Authentication and access errors

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

### Recommended checks

| Check | Recommended action |
|  --- | --- |
| Bearer token | Verify that you're using a valid Demand API authentication token. |
| Affiliate identifier | Include the correct `X-Affiliate-Id` header. |
| Environment | Verify that you're sending requests to the intended sandbox or production environment. |
| API access | Confirm that your affiliate account has access to the Messaging API. |
| Conversation access | Verify that the requested conversation is available to your authenticated affiliate account. |


For authentication details, see [Authentication](/demand/docs/development-guide/authentication).

## HTTP 500 Internal Server Error

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

### Recommended actions

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.


Do not assume that an HTTP 500 response means the affiliate account is not onboarded or that the service is experiencing a cold start.

If access is uncertain, verify Messaging API availability for your affiliate account separately.

## Rate limits

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

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

### Recommended actions

✅ **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](/demand/docs/support/error-handling/http-4xx-scenarios#429---too-many-requests).

## Before contacting support

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

| Information | Description |
|  --- | --- |
| Endpoint | The Messaging API endpoint and HTTP method used. |
| Environment | Sandbox or production. |
| Request ID | The `request_id` returned by the API, if available. |
| HTTP status code | The status code returned by the failed request. |
| Error details | The error response, with sensitive information removed. |
| Relevant identifiers | Accommodation, conversation, reservation or message IDs, as applicable. |
| Time of failure | The approximate time when the issue occurred, including the time zone. |


Sensitive information
Do not include API tokens, guest personal information or base64-encoded attachments in support requests unless explicitly required through an approved secure channel.

## Additional resources

* [About the Messaging API](/demand/docs/messaging/about-messaging) – Review the available messaging capabilities.
* [Messaging API quick guide](/demand/docs/messaging/try-out-messages) – Test the API using the Demand API Messaging Test Hotel.
* [Manage messages](/demand/docs/messaging/manage-messages) – Learn how to retrieve conversations, send messages and confirm receipt.
* [Manage attachments](/demand/docs/messaging/manage-attachments) – Learn how to upload, send and retrieve image attachments.
* [Messaging best practices](/demand/docs/messaging/messaging-best-practices) – Review recommended integration practices.
* [Messaging API FAQs](/demand/docs/messaging/messaging-api-faqs) – Find answers to common questions.