# Use case 1 - Booking & welcome message

**This use case demonstrates a complete messaging flow for a new booking: retrieving the conversation, polling messages programmatically, and sending a reply to the accommodation.**

> **Scenario:** *A guest books a room at the Messaging Test Hotel (ID 13921698). The system automatically sends a welcome message, which the partner retrieves and responds to via the Messaging API*.


div
strong
 ⏱️ Estimated time to complete:
 20–30 minutes

## Workflow steps

This workflow has 4 steps:

[1. Retrieve the conversation.](#step-1---retrieve-the-conversation)
[2. Poll messages programmatically.](#step-2---poll-messages-programmatically)
[3. Confirm delivery.](#step-3---confirm-delivery) 
[4. Send a reply.](#step-4---send-a-reply-to-the-accommodation)

## Step 1 - Retrieve the conversation

After a successful booking (/orders/create), a `reservation` id is generated, a welcome message is shared and a new conversation is automatically started.

To retrieve the conversation:

1. Call the [messages/conversations](/demand/docs/open-api/demand-api/conversations/retrieve-conversation) endpoint and include in the request:
  * The `accommodation` id.
  * And `reservation` id.


**Example request – With accommodation + reservation ID**


```json
{
  "accommodation": "2098153",
  "reservation": "4380765874"
}
```

Alternatively you can include the `accommodation` id together with the `conversation` id of your interest.

* To get the `conversation` id use [messages/latest](/demand/docs/open-api/demand-api/messages/fetchlatestmessages) endpoint.


**Example response**

The response includes the conversation with the welcome message:


```json
{
    "data": {
        "conversations": {
            "messages": [
                {
                    "id": "1fd6c3a0-6c74-11f0-8a0a-3dbfea505c1d",
                    "sender": "94914645-adbc-546b-a759-d1a1b48b6e1e",
                    "content": "Hello Ada, Thanks for booking Demand API Test Hotel! We are happy to see you on Thursday 22 August 2025. Best, Demand API Test Hotel",
                    "timestamp": "2025-07-29T12:04:05.466Z"
                }
            ],
            "id": "bbb76179-7565-5a23-8632-33e164aa13db", // This is the conversation id
            "reservation": "6066547158",
            "participants": [
                {
                    "metadata": {
                        "type": "property",
                        "name": "13921698"
                    },
                    "id": "94914645-adbc-546b-a759-d1a1b48b6e1e"
                },
                {
                    "metadata": {
                        "type": "guest"
                    },
                    "id": "fee4a6c8-16e2-5d7b-9ad0-2027f8eae9df"
                }
            ]
        }
    },
}
```

Use the `conversation` id to reference this conversation in subsequent API calls.

## Step 2 - Poll messages programmatically

To fetch messages without retrieving the full conversation each time, use the [/messages/latest endpoint](/demand/docs/open-api/demand-api/messages/fetchlatestmessages).

**Request:**

* Just send an empty body request.


**Response:**

The response includes a list of messages. Each message includes metadata about the sender, content, attachments, and timestamp.

| 
| `sender` | Information about the participant (guest or property). |
| `attachments` | Will be empty if no attachments. |
| `timestamp` | ISO timestamp of the message - This is relevant for tracking purposes. |
| `content` | Body of the message. |


In this example there are 4 messages, some from the same conversation:


```json

{
    "request_id": "ddcf96b3-e17c-4e6f-8f8c-4d685489ce04",
    "data": {
        "messages": [
            {
                "conversation": {
                    "reservation": "4363562386",
                    "accommodation": "2098153",
                    "conversation": "8586a789"
                },
                "content": "Approved to modify reservation at lower price",
                "message": "8a269910-19d1-11f0-bb60-972708bd278a",
                "sender": {
                    "participant_id": "6c22a16d-a3bd-5f5b-82d9-ce1030f21b1f",
                    "metadata": {
                        "type": "property",
                        "id": "Demand API Messaging Test Hotel"
                    }
                },
                "attachments": [],
                "timestamp": "2025-04-15T08:13:40.000Z"
            },
            {
                "conversation": {
                    "reservation": "4363562386",
                    "accommodation": "2098153",
                    "conversation": "8586a789"
                },
                "content": "from 49.50 to 40 EUR",
                "message": "94a20230-19d1-11f0-ad0b-070f57f7896d",
                "sender": {
                    "participant_id": "6c22a16d-a3bd-5f5b-82d9-ce1030f21b1f",
                    "metadata": {
                        "type": "property",
                        "id": "Demand API Messaging Test Hotel"
                    }
                },
                "attachments": [],
                "timestamp": "2025-04-15T08:13:58.000Z"
            },
            {
                "conversation": {
                    "reservation": "4580465458",
                    "accommodation": "2098153",
                    "conversation": "ccffd27c-7e53-5f31-9760-a5846de75d8e"
                },
                "content": "Unfortunately, we must apply some cancellation fees according to our cancellation policies",
                "message": "38914fd0-19ce-11f0-9ba3-8fd61549a30a",
                "sender": {
                    "participant_id": "6c22a16d-a3bd-5f5b-82d9-ce1030f21b1f",
                    "metadata": {
                        "type": "property",
                        "id": "Demand API Messaging Test Hotel"
                    }
                },
                "attachments": [],
                "timestamp": "2025-04-15T07:49:55.000Z"
            },
            {
                "conversation": {
                    "reservation": "4380765874",
                    "accommodation": "6819547",
                    "conversation": "cc872746-77f2-5886-ba7c-17e0497241b5"
                },
                "content": "Ok, lets proceed with the cancellation",
                "message": "41544f00-19d8-11f0-9ea6-f35823f251fe",
                "sender": {
                    "participant_id": "00a40ffc-f7a7-55d7-a8d8-b45ef2a7a99e",
                    "metadata": {
                        "type": "guest",
                        "id": ""
                    }
                },
                "attachments": [],
                "timestamp": "2025-04-15T09:01:44.000Z"
            }
        ]
    }
}
```

Note: You will only see those conversations that are associated to your AID.

## Step 3 - Confirm delivery

Use [/messages/latest/confirm](/demand/docs/open-api/demand-api/messages/confirmmessagereceipt) to confirm receipt of messages to mark them as processed. This is mandatory for the complete delivery of the message.

**Required parameter**

* `messages` -  The list of message IDs (UUIDS) that needs to be confirmed.


Get the message id from the message/latest response.

**Example request:**


```json
{
    "messages":["3f986fc8-b944-4501-b8d1-430e833ca756"]
}
```

A successful response will return a 200 OK.

## Step 4 - Send a reply to the accommodation

You can now reply to the accommodation via [/messages/send](/demand/docs/open-api/demand-api/messages/sendmessage)

**Example request:**


```json
{
  "reservation": "6066547158",
  "conversation": "bbb76179-7565-5a23-8632-33e164aa13db",
  "accommodation": "13921698",
  "content": "Thanks, looking forward to my stay!"
}
```

**Optional parameters**

You may also include:

- `attachments` id - The identifier of an image (uploaded via the /attachments/upload endpoint).


Example:


```json
{
    "accommodation": 13921698,
    "attachments":["c325f460-1dc6-11f0-80f0-8d0908786f77"],
    "content": "I appreciate you consider our request."
}
```

See the [Managing attachments guide](/demand/docs/messaging/manage-attachments) to learn how to upload images.

**Example response:**

A successful response includes the assigned `message` id:


```json
{
  "data": {
    "message": "2c05c1c0-8fb6-11f0-9fe0-231a553b7d81"
  },
  "request_id": "3a097c09-cad1-4a91-9586-1834e27b9004"
}
```

The message is successfully sent and recorded in the conversation.

Curious to know more?
* Read the [Manage attachments guide](/demand/docs/messaging/manage-attachments) to learn how to send and download images.
* Review [Messaging best practices](/demand/docs/messaging/messaging-best-practices) to align your messaging flows.
* Check the [Messaging troubleshooting guide](/demand/docs/messaging/messaging-troubleshooting) for help with error resolution.