Managing message queries

Message queries enable you to search for messages by property or within a 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:

  1. Set up a query to return a specific batch of messages.
    The endpoint returns a job id.
  2. Consult the status of the query with the job id to see whether it is ready to be retrieved.
  3. Retrieve the batch of messages with the job id.

Specifying a message query to retrieve messages

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

The GET /messages/search request enables you to set up 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:

{
  "errors": [],
  "meta": {
      "ruid": "UmFuZG9tSVYkc2RlIyh9YYuVGLmv13PU4evLP4Wf16AsiNznmynDQ+M+EvyDAKl0ZvMclqe4+hkPurFk4dRl+NagNC7uJsMR"
  },
  "data": {
      "job_id": "45157560-e157-11ea-a6d4-0b92d6337fed",
      "ok": true
  },
  "warnings": []

Response body elements

The following table describes the response elements:

Element Description Type Notes
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.

Consulting status of message query

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

The GET /messages/search/result/{job_id}/status request enables you to consult the status of the message query to see whether it is ready to be retrieved.

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 consult its status. string required

Response body example

The following is a successful response body example:

Response body elements

The following table describes the response elements:

Element Description Type Notes
ok Indicates whether the request was successfull. boolean
status Specifies the status of the message query. string Possible values: submitted, processing, ready, and expired.

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.

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:

{
  "data": {
      "ok": true,
      "messages": [
          {
              "message_uuid": "19a86b20-da78-11ea-bd8b-2f85a75e52aa",
              "property_id": 6378711,
              "sender": {
                  "metadata": {
                      "participant_type": "hotel",
                      "name": "hotel_6378711"
                  },
                  "participant_id": "9f6be5fd-b3a8-5691-9cf9-9ab6c6217327"
              },
              "content": " ",
              "timestamp": "2020-08-09T19:39:54.962Z",
              "conversation": {
                  "conversation_type": "reservation",
                  "conversation_id": "e2ecbf06-0ea3-5102-bdf8-7f003c1d3ef4",
                  "conversation_reference": "3569175458"
              }
          },
          ...
          {
              "property_id": 6378711,
              "message_uuid": "3cc14050-da78-11ea-bd8b-2f85a75e52aa",
              "sender": {
                  "participant_id": "9f6be5fd-b3a8-5691-9cf9-9ab6c6217327",
                  "metadata": {
                      "name": "hotel_6378711",
                      "participant_type": "hotel"
                  }
              },
              "timestamp": "2020-08-09T19:40:53.845Z",
              "content": "<br>",
              "conversation": {
                  "conversation_id": "e2ecbf06-0ea3-5102-bdf8-7f003c1d3ef4",
                  "conversation_reference": "3569175458",
                  "conversation_type": "reservation"
              }
          }
      ],
      "next_page_id": 1
  },
  "warnings": [],
  "errors": [],
  "meta": {
      "ruid": "UmFuZG9tSVYkc2RlIyh9YYuVGLmv13PUkKa5j8gnlJSMLBZRGUEUezGVxi84fPe0l8rEBFMX8K0T6U/deQKgZ684ENVFqsn/"
  }

Response body parameters

The following table describes the response elements:

Element Description Type Notes
ok Indicates whether the request was successfull. boolean
messages Contains the messages that you retrieved from the message queue. array
: message Contains the information related to the message that you retrieved from the message queue. object
:: 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.
:: reply_to Specifies the id of the participant to which the message is sent to. string
:: sender Contains the information related to the participant that sent the message. object
::: participant_id Specifies the id of the participant that sent the message. string
::: Metadata Contains additional information on the participant that sent the message. object
:::: name Specifies the name of the participant that sent the message. string
:::: participant_type Specifies the type of the participant that sent the message. string
: conversation Contains the information related to the conversation to which the message belongs. object
:: property_id Specifies the property id of the property to which the conversation applies. string
:: conversation_id Specifies the id of the conversation. string
:: conversation_reference Specifies the id of the reservation to which this conversation applies. string
:: conversation_type Specifies the type of the conversation. string Possible values: reservation.