Last updated

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:

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

Comparing response changes between v1.0 and v1.2

The GET /messages/search endpoint has two versions currently. The following are the possible changes when migrating from v1.0 to v1.2.

Default API behaviour (v1.0)New API behaviour (v1.2)Notes
Does not support self-service requests.Supports self-service requests. For example, after booking a reservation when a guest sends a self-service request, you can use Messaging API to retrieve the message. The API adds self-service messages in the response to related GET /messages/search/result/{job_id} requests.You must includes an Accept-version header with a value set to 1.2 in the request. Otherwise, responses to the GET /messages/search/result/{job_id} requests related to the search will not include self-service request messages.

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:

ElementDescriptionTypeRequired/OptionalNotes
beforeSpecifies the date and time until when you want to retrieve messages.stringoptionalFollows the ISO 8601 standard in UTC: YYYY-MM-DDThh:mm:ss.mmmZ. Specified time is included.
afterSpecifies the date and time after which you want to retrieve messages.stringoptionalFollows the ISO 8601 standard in UTC: YYYY-MM-DDThh:mm:ss.mmmZ. Specified time is included.
property_idSpecifies the ID of the property you want to retrieve messages for.stringoptional
order_byIndicates whether you want the messages order in ascending (oldest first) or descending (most recent first) order.stringoptionalPossible 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:

ElementDescriptionTypeNotes
dataContains the response object.object
: okIndicates whether the request was successfull.boolean
: job_idSpecifies the ID of the message query.stringYou need this ID to first consult the status of the message query.
: expires_atSpecifies when the query expires.stringThe 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.

Comparing response changes between v1.0 and v1.2

The GET /messages/search/result/{job_id} endpoint has two versions currently. The following are the possible changes when migrating from v1.0 to v1.2.

Default API behaviour (v1.0)New API behaviour (v1.2)Notes
Does not support self-service requests.Supports self-service requests. For example, after booking a reservation when a guest sends a self-service request, you can use Messaging API to retrieve the message.You must includes an Accept-version header with a value set to 1.2 in both the GET /messages/search and the related GET /messages/search/result/{job_id} requests. Otherwise, responses to the GET /messages/search/result/{job_id} requests related to the search will not include self-service request messages.
Does not include field message_type in the response.Includes field message_type for all messages.
Does not include attributes object in the response.Includes an optional attributes object within message entities in the response.
Does not include guest name in the response.Includes guest name in the sender object.Guest names are not provided in Request-to-Book (RtB) conversations until a reservation is confirmed. Once the booking is created, the guest's name will appear for that conversation, applying to all messages within it, including both historical and new communications.

Path parameters

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

ElementDescriptionTypeRequired/OptionalNotes
job_idSpecifies the ID of the message query you must use to retrieve the messages.integerrequired

Query parameters

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

ElementDescriptionTypeRequired/OptionalNotes
page_idSpecifies the page number.stringoptional

Response body examples

The following is a successful response body example using v1.2:

{
    "errors": [],
    "data": {
        "ok": true,
        "messages": [
            {
                "content": "Hello World",
                "property_id": "8011855",
                "message_id": "ae3869e0-6bec-11ed-891d-51acf195687b",
                "message_type": "free_text",
                "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",
                "message_type": "automatically_sent_template",
                "attributes": {
                    "template_id": "12345",
                    "template_name": "Welcome Template"
                },
                "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"
    }
}

The following is a successful response body example using v1.0:

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

ElementDescriptionTypeNotes
dataContains the response data.object
: okIndicates whether the request was successfull.string
: messagesContains the message elements.array
:: message_idSpecifies the unique ID of a message.string
:: message_typeSpecifies the type of the message.stringReturned only when the request includes an Accept-version header with a value set to 1.2.
Possible values are:
- free_text: A message composed of plain text.
- email: An email message.
- automatically_sent_template: A message automatically sent from a message template configured by the property via the extranet Messaging Preferences page.
- self_service_event: A structured message for self-service actions.
- request_to_book_event: A request-to-book event. You can find information on the request status in the content field, which denotes the request as expired, accepted by the property, confirmed by the guest or rejected, etc.
:: contentSpecifies the content of the message.string
:: timestampSpecifies the time when the message was sent.stringFollows the ISO 8601 standard in UTC: YYYY-MM-DDThh:mm:ss.mmmZ.
:: attachment_idsContains the IDs of the attachment.array
:: attributesContains the message attributes.objectReturned only when the request includes an Accept-version header with a value set to 1.2.
::: self_service_topicContains the self-service topic for messages that represent self-service events.stringPossible values include:
- checkin
- checkout
- change_dates_nr
- cancel_booking
- booking_basic_waive_fee
- parking
- free_text_parking
- bed_type
- extra_crib
- extra_bed
::: template_idContains the identifier of the message template used that was configured by the property via the extranet Messaging Preferences page.string
::: template_nameContains the name of the message template used that was configured by the property via the extranet Messaging Preferences page.string
:: property_idSpecifies the ID of the property.string
:: senderContains information on the participant that sent the message.object
::: participant_idSpecifies the participant ID of a participant.string
::: metadataContains information of a participant.object
:::: participant_typeSpecifies the type of the participant.stringPossible values are hotel or guest.
:::: nameSpecifies the name of the property.string
:: conversationContains the conversation elements.array
::: conversation_idSpecifies the unique ID of a conversation.string
::: conversation_referenceSpecifies the ID of the reservation or Booking Request Object this conversation is referring to.integerFor conversations with pre-reservation messages, the Booking Request Object id serves as the conversation_reference until the booking is confirmed.
::: conversation_typeSpecifies the type of the conversation.stringPossible values: reservation or request_to_book.