Managing conversations

A conversation is a collection of messages between two participants: Guest and property. The /conversations endpoints enable you to do the following:

Posting a message to a conversation

POST
https://supply-xml.booking.com/messaging/conversations/

The POST /conversations/ request enables you to post a message to a specific conversation.

Use cases

You can encounter the following two scenarios:

  • Guest starts conversation.
  • Property starts conversation.

→ In case a guest starts a conversation, you must retrieve the necessary conversation id by retrieving latest messages.

→ In case a property wants to start a conversation, you must retrieve the necessary conversation id by retrieving a specific conversation by conversation type and reference id.

Guests without account receive an email

If a guest does not have an account and the property starts a conversation, the system sends an email to which the guest can reply. In that case, the communication continues via email. These emails appear in the extranet, but you cannot retrieve them as messages through the Messaging API.

Query parameters

The following table describes what elements you must add as query parameters:

Element Description Type Required/Optional Notes
property_id Specifies the id of the property you want to post a message from. string required
conversation_id Specifies the id of the conversation you want to post a message to. string required

Body parameters

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

Element Description Type Required/Optional Notes
message Contains the information related to the message that you want to post to the conversation. object
: content Specifies the content of the message. string

Request body example

The following is a request body example:

{
  "message": {
      "content": "Hola,Toni! Como estas huey?"
  }

Response body example

The following is a successful response body example:

{
  "errors": [],
  "warnings": [],
  "meta": {
      "ruid": "UmFuZG9tSVYkc2RlIyh9YYuVGLmv13PU2CPBInBo6tmR2olhYRQJnBxQ28c+302tG2NR8bgV4z78HUvSFMcHY/AsImiUYbjP"
  },
  "data": {
      "message_id": "a547bac0-e156-11ea-9735-f5b2c8769b48",
      "ok": "true"
  }

Response body parameters

The following table describes the response elements:

Element Description Type Notes
ok Indicates whether the request was successfull. string
message_id Contains the conversation information. object

Retrieving all conversations by property

GET
https://supply-xml.booking.com/messaging/conversations/property/{property_id}

The GET /conversations/property/{property_id} request enables you to retrieve information per property for all its conversations.

New activity could change order

The conversations are returned in a descending order (most recent first). If a participant adds a new message to a conversation, this might change the order of the conversations you retrieve.

Path parameters

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

Element Description Type Required/Optional Notes
property_id Specifies the id of the property you want to retrieve messages for. string optional

Query parameters

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

Element Description Type Required/Optional Notes
unread Indicates whether you only want to retrieve conversations with unread messages. string optional Possible values: 1 or true.
page_id Specifies the id of the page you want to retrieve. string optional Each page returns 50 conversations.

Response body example

The following is a successful response body example:

{
  "data": {
      "ok": "true",
      "conversations": [
          {
              "conversation_id": "8ecdd44e-e5d7-5d27-8e11-9cf843ff513d",
              "participants": [
                  {
                      "participant_id": "5fe782b1-6545-55b7-8b75-588945b5f960",
                      "metadata": {
                          "type": "guest",
                          "internal_id": "422928145"
                      }
                  },
                  {
                      "participant_id": "9f6be5fd-b3a8-5691-9cf9-9ab6c6217327",
                      "metadata": {
                          "internal_id": "6378711",
                          "type": "hotel"
                      }
                  }
              ],
              "external_reference_id": "partner_chat_2557554991"
          },
          {
              "conversation_id": "f3a9c29d-480d-5f5b-a6c0-65451e335353",
              "external_reference_id": "partner_chat_3812391309",
              "participants": [
                  {
                      "participant_id": "5fe782b1-6545-55b7-8b75-588945b5f960",
                      "metadata": {
                          "internal_id": "422928145",
                          "type": "guest"
                      }
                  },
                  {
                      "participant_id": "9f6be5fd-b3a8-5691-9cf9-9ab6c6217327",
                      "metadata": {
                          "internal_id": "6378711",
                          "type": "hotel"
                      }
                  }
              ]
          }
      ]
  },
  "warnings": [],
  "meta": {
      "ruid": "UmFuZG9tSVYkc2RlIyh9YYuVGLmv13PUjrHyI/+mfzrS6NTHb75y1nS7Z8hevWszYKR7C1RjZf+PsDDn11bdmGbd+A0zWk1k"
  },
  "errors": []

Response body elements

The following table describes the response elements:

Element Description Type Notes
ok Indicates whether the request was successfull. string
conversations Contains the conversation elements. array
: conversation_id Specifies the unique id of a conversation. string
: participants Contains the information on the other participant active in a conversation. array
:: participant_id Specifies the participant id of the participant. string
:: metadata Contains the information of the participant. object
::: internal_id Specifies the internal id of the participant. string
::: type Specifies the type of the participant. string

Retrieving a specific conversation

You can retrieve a specific conversation with all its messages in the following two ways:

New activity might cause message loss

If a new message was added to the conversation when you call the second page, you might miss out on that message.

Retrieving a specific conversation by conversation id

GET
https://supply-xml.booking.com/messaging/conversations/{conversation_id}/property/{property_id}

The GET /conversations/{conversation_id}/property/{property_id} request enables you to retrieve a specific conversation with all its messages. The messages you retrieve are in descending order (most recent first).

Path parameters

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

Element Description Type Required/Optional Notes
property_id Specifies the id of the property you want to retrieve the conversation for. string required
conversation_id Specifies the id of the conversation you want to retrieve. string required

Query parameters

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

Element Description Type Required/Optional Notes
page_id Specifies the id of the page you want to retrieve. string optional Each page returns 50 messages. You must use next_page_id from response here to retrieve the next page of messages.

Response body example

The following is a successful response body example:

{
  "data": {
      "ok": "true",
      "conversation": {
          "access": "read_write",
          "participants": [
              {
                  "participant_id": "5fe782b1-6545-55b7-8b75-588945b5f960",
                  "metadata": {
                      "type": "guest"
                  }
              },
              {
                  "metadata": {
                      "type": "hotel"
                  },
                  "participant_id": "9f6be5fd-b3a8-5691-9cf9-9ab6c6217327"
              }
          ],
          "conversation_type": "reservation",
          "conversation_reference": "3114037871",
          "messages": [
              {
                  "message_id": "318a8b20-daf4-11ea-8b90-6ba51917ac8e",
                  "timestamp": "2020-08-10T10:28:12.626Z",
                  "content": "Hello world",
                  "sender_id": "5fe782b1-6545-55b7-8b75-588945b5f960"
              },
              {
                  "timestamp": "2020-08-10T10:28:10.485Z",
                  "sender_id": "5fe782b1-6545-55b7-8b75-588945b5f960",
                  "content": "Hi John",
                  "message_id": "3043da50-daf4-11ea-934a-1da93ca88861"
              }
          ],
          "conversation_id": "190f0ffc-9dbb-5b18-a1e2-b475f185859b"
      },
      "next_page_id": "f501bf00-daf0-11ea-bd8b-2f85a75e52aa"
  },
  "meta": {
      "ruid": "UmFuZG9tSVYkc2RlIyh9YYuVGLmv13PUNksRUCyRI0fH+lnHJwQIALleQNDhRIBUQVQhjyDVCzPO08DVfqTf8OOspibZTvxv"
  },
  "warnings": [],
  "errors": []

Response body parameters

The following table describes the response elements:

Element Description Type Notes
ok Indicates whether the request was successfull. string
conversation Contains the conversation information. object
: 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.
: 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.
:: 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
: participants Contains the information on the other participant active in a conversation. array
:: participant_id Specifies the participant id of the participant that received the last message. string
:: metadata Contains the information of the participant that received the last message. object
::: name Specifies the name of the participant that received the last message. string
::: participant_type Specifies the type of the participant that received the last message. string
: access Specifies the access level for the conversation. string Possible vlaues: read_only or read_write.
next_page_id Specifies the id of the next page with messages. string

Retrieving a specific conversation by conversation type and reference

GET
https://supply-xml.booking.com/messaging/conversations/property/{property_id}/type/{conversation_type}

The GET /conversations/property/{property_id}/type/{conversation_type} request enables you to retrieve a specific conversation with all its messages. The messages you retrieve are in descending order (most recent first).

Path parameters

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

Element Description Type Required/Optional Notes
property_id Specifies the id of the property you want to retrieve the conversation for. string required
type Specifies the type of the conversation you want to retrieve. string required

Query parameters

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

Element Description Type Required/Optional Notes
conversation_reference Specifies the unique id of the conversation type this conversation is referring to. integer required For now the references are all reservation ids.
page_id Specifies the id of the page you want to retrieve. string optional Each page returns 50 messages. You must use next_page_id from response here to retrieve the next page of messages.

Response body example

The following is a successful response body example:

{
  "warnings": [],
  "errors": [],
  "meta": {
      "ruid": "UmFuZG9tSVYkc2RlIyh9YYuVGLmv13PUDmCcTLCLPhKa/xm9PIsBaOlNJrv696LAQFcTkjTXytHxrNEsEBU8X7X4EMfn65n4"
  },
  "data": {
      "conversation": {
          "participants": [
              {
                  "participant_id": "5fe782b1-6545-55b7-8b75-588945b5f960",
                  "metadata": {
                      "type": "guest"
                  }
              },
              {
                  "metadata": {
                      "type": "hotel"
                  },
                  "participant_id": "9f6be5fd-b3a8-5691-9cf9-9ab6c6217327"
              }
          ],
          "access": "read_write",
          "messages": [
              {
                  "content": "Hello world",
                  "message_id": "8519d730-dd8a-11ea-bd36-fb2ae864b112",
                  "sender_id": "5fe782b1-6545-55b7-8b75-588945b5f960",
                  "timestamp": "2020-08-13T17:29:19.651Z"
              },
              {
                  "message_id": "18a63390-dd7c-11ea-9a72-e1c0bb2caae9",
                  "content": "Hi John",
                  "timestamp": "2020-08-13T15:46:04.745Z",
                  "sender_id": "9f6be5fd-b3a8-5691-9cf9-9ab6c6217327"
              }
          ],
          "conversation_id": "8ecdd44e-e5d7-5d27-8e11-9cf843ff513d",
          "conversation_reference": "2557554991",
          "conversation_type": "reservation"
      },
      "next_page_id": "54e61970-dcc7-11ea-82ae-2fdc108d4181",
      "ok": "true"
  }

Response body parameters

The following table describes the response elements:

Element Description Type Notes
ok Indicates whether the request was successfull. string
conversation Contains the conversation information. object
: 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.
: 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.
:: 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
: participants Contains the information on the other participant active in a conversation. array
:: participant_id Specifies the participant id of the participant that received the last message. string
:: metadata Contains the information of the participant that received the last message. object
::: name Specifies the name of the participant that received the last message. string
::: participant_type Specifies the type of the participant that received the last message. string
: access Specifies the access level for the conversation. string Possible vlaues: read_only or read_write.
next_page_id Specifies the id of the next page with messages. string