Searching messages

Message queries enable you to search for messages by property or within a specified date range. These queries can be very intensive and slow, so you should only use the following endpoints when you missed or lost messages using the /messages/latest endpoint.

Querying messages workflow

To make best use of the message queries, you should:

Set up a query to return a specific batch of messages.
The endpoint returns a job id.
Consult the status of the query with the job ID to see whether it is ready to be retrieved.
Retrieve the batch of messages with the same call once the status changed to ready.

Creating a message query to retrieve messages

GET
https://supply-xml.booking.com/messaging/messages/search

The GET /messages/search request enables you to create a query to retrieve specific messages.

Message queries expire after 48 hours

After a message query is ready, the job ID expires after 48 hours. That means you must create a new message query if you want to retrieve those messages again.

Query parameters

At least one parameter required

If you create a query, you must use at least one query parameter. If you do not, you receive a 400 response.

The following table describes what elements you must add in the request path:

Element	Description	Type	Required/Optional	Notes
`before`	Specifies the date and time until when you want to retrieve messages.	string	optional	Follows the ISO 8601 standard in UTC: `YYYY-MM-DDThh:mm:ss.mmmZ`. Specified time is included.
`after`	Specifies the date and time after which you want to retrieve messages.	string	optional	Follows the ISO 8601 standard in UTC: `YYYY-MM-DDThh:mm:ss.mmmZ`. Specified time is included.
`property_id`	Specifies the ID of the property you want to retrieve messages for.	string	optional
`order_by`	Indicates whether you want the messages order in ascending (oldest first) or descending (most recent first) order.	string	optional	Possible values: `asc` or `desc`.

Response body example

The following is a successful response body example:

{
  "data": {
      "expires_at": "2021-01-01T14:52:38.860Z[GMT]",
      "ok": true,
      "job_id": "a934b220-4aae-11eb-83e9-8f4bc4c2528d"
  },
  "errors": [],
  "warnings": [],
  "meta": {
      "ruid": "UmFuZG9tSVYkc2RlIyh9YYX5KO46o0C5R5CiotKrM4awgb8DeWP40oDQG6OR6x4lvYqbLiGYUQHR5EgyMmTTT8xAnK2feAdc"
  }
}

Response body elements

The following table describes the response elements:

Element	Description	Type	Notes
`data`	Contains the response object.	object
: `ok`	Indicates whether the request was successfull.	boolean
: `job_id`	Specifies the ID of the message query.	string	You need this ID to first consult the status of the message query.
: `expires_at`	Specifies when the query expires.	string	The query expires after 48 hours.

Retrieving the messages from message query

GET
https://supply-xml.booking.com/messaging/messages/search/result/{job_id}

The GET /messages/search/result/{job_id} request enables you to retrieve the batch of messages with the job id. If the query is not ready yet, you can retrieve the current status of the query.

Path parameters

The following table describes what elements you must add in the request path:

Element	Description	Type	Required/Optional	Notes
`job_id`	Specifies the ID of the message query you must use to retrieve the messages.	integer	required

Query parameters

The following table describes what elements you can add as a query:

Element	Description	Type	Required/Optional	Notes
`page_id`	Specifies the page number.	string	optional

Response body example

The following is a successful response body example:

{
    "errors": [],
    "data": {
        "ok": true,
        "messages": [
            {
                "content": "Hello World",
                "property_id": "8011855",
                "message_id": "ae3869e0-6bec-11ed-891d-51acf195687b",
                "timestamp": "2022-11-24T11:39:39.774Z",
                "attachment_ids": [],
                "sender": {
                    "metadata": {
                        "name": "A test Property",
                        "participant_type": "hotel"
                    },
                    "participant_id": "f8b14984-c3cd-557e-9d72-1e8f3vady49d"
                },
                "conversation": {
                    "conversation_type": "reservation",
                    "conversation_id": "055ceb8d-e518-5e90-ad98-29d60e61f860",
                    "conversation_reference": "3417130690"
                }
            },
            {
                "content": "Custom content. \nSupports new line and \"quotes\". ",
                "property_id": "6314570",
                "message_id": "3b9be6y0-85f4-11ed-8ed3-7d2f2a089692",
                "timestamp": "2022-12-27T14:39:13.694Z",
                "attachment_ids": [],
                "sender": {
                    "metadata": {
                        "name": "A test Hotel",
                        "participant_type": "hotel"
                    },
                    "participant_id": "6589db7a-5325-5ec4-b4fe-90398c928c22"
                },
                "conversation": {
                    "conversation_id": "26e11a6f-9843-5a1f-8876-48bd8ea54d32",
                    "conversation_reference": "2371422380",
                    "conversation_type": "reservation"
                }
            }
        ],
        "next_page_id": ""
    },
    "warnings": [],
    "meta": {
        "ruid": "UmFuZG090l7VYkc2RlIyh9YbXOFK03PYclTnK6wVHEieAtwtRloZgirf59kGDml0PlwGoYZxgZfjKg4Lcq0qqDeVBucNNdoZSD"
    }
}

Response body parameters

The following table describes the response elements:

Element	Description	Type	Notes
`data`	Contains the response data.	object
: `ok`	Indicates whether the request was successfull.	string
: `messages`	Contains the message elements.	array
:: `message_id`	Specifies the unique ID of a message.	string
:: `content`	Specifies the content of the message.	string
:: `timestamp`	Specifies the time when the message was sent.	string	Follows the ISO 8601 standard in UTC: `YYYY-MM-DDThh:mm:ss.mmmZ`.
`attachment_ids`	Contains the ids of the attachment.	array
:: `property_id`	Specifies the ID of the property.	string
:: `sender`	Contains information on the participant that sent the message.	object
::: `participant_id`	Specifies the participant ID of a participant.	string
::: `metadata`	Contains information of a participant.	object
:::: `participant_type`	Specifies the type of the participant.	string	Possible values are `hotel` or `guest`.
:::: `name`	Specifies the name of the property.	string
:: `conversation`	Contains the conversation elements.	array
::: `conversation_id`	Specifies the unique ID of a conversation.	string
::: `conversation_reference`	Specifies the unique ID of the conversation type this conversation is referring to.	integer	For now the references are all reservation ids.
::: `conversation_type`	Specifies the type of the conversation.	string	For now the only possible value is `reservation`.