MESSAGING
/
Manage messages
/
Use case 1 - Booking & welcome message
Last updated

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.

⏱️ Estimated time to complete: 20–30 minutes

Workflow steps

This workflow has 4 steps:

1. Retrieve the conversation.
2. Poll messages programmatically.
3. Confirm delivery.
4. Send a reply.

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 endpoint and include in the request:
    • The accommodation id.
    • And reservation id.

Example request – With accommodation + reservation ID

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

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

Example response

The response includes the conversation with the welcome message:

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

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.

senderInformation about the participant (guest or property).
attachmentsWill be empty if no attachments.
timestampISO timestamp of the message - This is relevant for tracking purposes.
contentBody of the message.

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


{
    "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 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:

{
    "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

Example request:

{
  "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:

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

See the Managing attachments guide to learn how to upload images.

Example response:

A successful response includes the assigned message id:

{
  "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?
Previous page
Next page