Managing messages

This section describes all the possible actions related to messaging between properties and guests after they make a reservation.

Retrieving and confirming retrieval of messages

The Messaging API queues messages on the machine account (all your connected properties). Every message is part of a specific conversation, which exists between two participants: Property and Guest. To make best use of this messaging queue you should:

  1. Retrieve messages.
  2. Confirm the successfull retrieval of those messages.
    This removes the retrieved messages from the queue.
  3. Follow steps one and two until the queue is empty.

Retrieving messages

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

The GET /messages/latest request enables you to retrieve messages from a message queue on the machine account level. Every request retrieves a maximum of 100 messages.

Response body example

The following is a successful response body example:

{
  "meta": {
      "ruid": "UmFuZG9tSVYkc2RlIyh9YYuVGLmv13PUyJxscfB0hkeHNTLsLGWx80EBzv17yAX3aPO0RTlx5doV49/NRR4qak1qNsDGbilP"
  },
  "warnings": [],
  "data": {
      "messages": [
          {
              "sender": {
                  "participant_id": "9f6be5fd-b3a8-5691-9cf9-9ab6c6217327",
                  "metadata": {
                      "participant_type": "hotel"
                  }
              },
              "timestamp": "2020-08-17T16:54:19.270Z",
              "conversation": {
                  "conversation_type": "reservation",
                  "conversation_id": "f3a9c29d-480d-5f5b-a6c0-65451e335353",
                  "conversation_reference": "3812391309"
              },
              "message_id": "4ad42260-e0aa-11ea-b1cb-0975761ce091",
              "content": "Property message 4f523a42-dc9a-40a5-9ab7-fd2db124cd62"
          },
          {
              "sender": {
                  "participant_id": "9f6be5fd-b3a8-5691-9cf9-9ab6c6217327",
                  "metadata": {
                      "participant_type": "hotel"
                  }
              },
              "timestamp": "2020-08-17T16:57:09.124Z",
              "conversation": {
                  "conversation_id": "f3a9c29d-480d-5f5b-a6c0-65451e335353",
                  "conversation_type": "reservation",
                  "conversation_reference": "3812391309"
              },
              "message_id": "b011cc40-e0aa-11ea-b928-810a184a831c",
              "content": "Property message 53fef484-ec48-487f-acb6-5086ef87da29"
          },
          {
              "conversation": {
                  "conversation_id": "f3a9c29d-480d-5f5b-a6c0-65451e335353",
                  "conversation_type": "reservation",
                  "conversation_reference": "3812391309"
              },
              "message_id": "485f18d0-e0ac-11ea-8397-c17827e93026",
              "content": "Property message 81ec552a-7c13-416e-a58e-937283ab6bfc",
              "sender": {
                  "participant_id": "9f6be5fd-b3a8-5691-9cf9-9ab6c6217327",
                  "metadata": {
                      "participant_type": "hotel"
                  }
              },
              "timestamp": "2020-08-17T17:08:34.141Z"
          }
      ],
      "ok": true,
      "number_of_messages": 3,
      "timestamp": "2020-08-18T14:59:26.41"
  },
  "errors": []

Response body elements

The following table describes the response elements:

Element Description Type Notes
ok Indicates whether the request was successfull. string
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 Notes
::: 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.

Confirming the retrieval of messages

PUT https://supply-xml.booking.com/messaging/messages

The PUT /messages request enables you to confirm the successfull retrieval of messages, removing those messages from the queue. You should always confirm the retrieval of messages to prepare the retrieval of the remaining messages.

→ If you want to understand the user flow, see retrieving and confirming retrieval of messages.

Query parameters

The following table describes the query parameters you must add:

Element Description Type Required/Optional Notes
number_of_messages Specifies the amount of messages you want to confirm you retrieved. integer required You can find the value of number_of_messages in the response body when you retrieve latest messages.

Response body example

The following is a successful response body example:

{
  "data": {
      "ok": true
  },
  "warnings": [],
  "meta": {
      "ruid": "UmFuZG9tSVYkc2RlIyh9YYuVGLmv13PUghc+S+Hxf8kDDmE9pIcRJDlql5z0me9U/HXdkK5kNTwJ8bDjF+xIG9WsKhazErNd"
  },
  "errors": []

Response body elements

The following table describes the response elements:

Element Description Type Notes
ok Indicates whether the request was successfull. boolean