Get threads

Retrieve one or more threads with /find_thread or /list_recent.

Use /list_recent to get the list of threads that have messages in most recent order. Request parameters can be used to retrieve only threads that are pending messages (status = pending_property) or threads with unread messages.

/find_thread requires a reservation id. It can be used to get a thread_id from a reservation_id. The thread_id can then be used to get a list of message for that specific thread. It can as well be used to get more information about this thread (status, topic, unread counts, etc..).

Before you start

You'll need:


Get threads by reservation ID

Retrieve the threads for a reservation with /find_thread.

HTTP request

POST https://chat.booking.com/3/find_thread

Request body

{
  "auth": "{{MessagingAPIAuthToken}}",
  "only_top_thread": "0",
  "reservation_ids": [
    "{{ReservationID}}"
  ]
}

See Messaging API reference for details.

Response body

{
  "threads": [
    {
      "thread": {
        "id": "ed9544f6-3a9f-489a-8011-2309dd7e93cc",
        "context_data": {
          "hotelreservation_id": "1411422237"
        },
        "message_count": 83,
        "pending_subthreads": 0,
        "readonly": false,
        "status": "new",
        "topic": "reservation",
        "type": "Contextual",
        "unread_count": 1,
        "unread_subthreads": 1,
      },
      "last_messages": [
        {
          "fallback": "https://www.booking.com/error404.html?chat_fallback=1&message_id=509cb344-c7e1-11e8-8760-cf1c4ba25119",
          "message": {
            "command": "/start",
            "command_params": {
              "entry_point": "hotel_free_text_to_guest"
            },
            "language": null,
            "prediction": null,
            "reply_options": [],
            "selected_options": [
              {
                "caption": "",
                "image_urls": [],
                "input_value": "We look forward to welcoming you once again!",
                "mandatory": 0,
                "name": "",
                "options": [],
                "payload": "",
                "presentation": "",
                "type": "PlainText"
              }
            ],
            "text": null,
            "type": "ContextualMessage"
          },
          "message_id": "509cb344-c7e1-11e8-8760-cf1c4ba25119",
          "recipient": {
            "id": "db703eb009b71b32",
            "name": "Booking Assistant",
            "type": "Bot",
            "type_name": "Booking Assistant"
          },
          "sender": {
            "id": "6efed84ee32cc7b9",
            "images": {},
            "name": "Test Hotel 20",
            "type": "Hotel",
            "type_name": "Property"
          },
          "thread_id": "ed9544f6-3a9f-489a-8011-2309dd7e93cc",
          "time": 1538663116,
          "unread": true
        }
      ],
      "subthreads": [
        {
          "thread": {
            "context_data": {
              "hotelreservation_id": "1411422237"
            },
            "id": "760addb4-e041-4d96-9771-aa630bf613e6",
            "message_count": 58,
            "pending_subthreads": 0,
            "readonly": false,
            "status": "pending_none",
            "topic": "checkout_time",
            "type": "Contextual",
            "unread_count": 1,
            "unread_subthreads": 0,
          },
          "last_messages": [
            {
              "fallback": "https://www.booking.com/error404.html?chat_fallback=1&message_id=6c6ad782-c7c2-11e8-8264-a9547cbde734",
              "message": {
                "client_info": {
                  "gr_card": {
                    "gr_id": "7d1c2097-c70d-11e8-9399-10468058fe8c",
                    "seq": "3"
                  }
                },
                "in_reply_to": "11e06c68-c7b4-11e8-a25a-93644a22a6d1",
                "language": null,
                "prediction": null,
                "reply_groups": [],
                "reply_options": [],
                "selected_options": [],
                "text": "I accept the extra cost.",
                "type": "ContextualMessage"
              },
              "message_id": "6c6ad782-c7c2-11e8-8264-a9547cbde734",
              "recipient": {
                "id": "6efed84ee32cc7b9",
                "images": {},
                "name": "Test Hotel 20",
                "type": "Hotel",
                "type_name": "Property"
              },
              "sender": {
                "id": "db703eb009b71b32",
                "name": "Booking Assistant",
                "type": "Bot",
                "type_name": "Booking Assistant"
              },
              "thread_id": "760addb4-e041-4d96-9771-aa630bf613e6",
              "time": 1538649849,
              "unread": true
            }
          ]
        }
      ]
    }
  ]
}

See Messaging API reference for details.


Get recently updated threads

Retrieve a list of threads that recently received new messages with /list_recent.

HTTP request

POST https://chat.booking.com/3/list_recent

Request body

{
  "auth": [
    {
      "auth": "{AuthorisationToken}",
      "type": "Contextual"
    }
  ]
}

See Messaging API reference for details.

Response

The request returns a list of threads that recently received new messages, sorted from most to least recent. The results are paged.

{
  "pages": {
    "after": "page-536ae354-90c6-11e8-9b6d-48f356cbdb25"
  },
  "threads": [
    {
      "last_messages": [
        {
          "fallback": "https://www.booking.com/error404.html?chat_fallback=1&message_id=526ae354-90c6-1ae4-9b6d-48f356cbdb25",
          "message": {
            // ...
            "quoted_text": "Hi! I have a special request.",
            "in_reply_to": "52405554-90c6-11e8-98f4-3c2a91e17db3",
            // ...
          },
          "message_id": "526ae354-90c6-1ae4-9b6d-48f356cbdb25",
          "recipient": {
            "id": "2df379c8b3141875",
            "images": {},
            "name": "The Best Hotel",
            "type": "Hotel",
            "type_name": "Property"
          },
          "sender": {
            "id": "db703easga9b71b32",
            "name": "Booking Assistant",
            "type": "Bot",
            "type_name": "Booking Assistant"
          },
          "thread_id": "28306ad9-2lm3-4ada-98a2-0b1c5a802f59",
          "time": 1532604211,
          "unread": true
        }
      ],
      "poll_delay": 10,
      "subthreads": [
        {
          "last_messages": [
            {
              "fallback": "https://www.booking.com/error404.html?chat_fallback=1&message_id=536ae354-90c6-11e8-9b6d-48f356cbdb25",
              "message": {
                // ...
                "quoted_text": "Hi! I have a special request.",
                "in_reply_to": "52405554-90c6-11e8-98f4-3c2a91e17db3",
                // ...
              },
              "message_id": "536ae354-90c6-11e8-9b6d-48f356cbdb25",
              "recipient": {
                "id": "2df379c8b3141875",
                "images": {},
                "name": "The Best Hotel",
                "type": "Hotel",
                "type_name": "Property"
              },
              "sender": {
                "id": "db703eb009b71b32",
                "name": "Booking Assistant",
                "type": "Bot",
                "type_name": "Booking Assistant"
              },
              "thread_id": "28306ad9-c91a-4ada-98a2-0b1c5a802f59",
              "time": 1532604211,
              "unread": true
            }
          ],
          "poll_delay": 10,
          "thread": {
            "context_data": {
              "hotelreservation_id": "1724842840"
            },
            "id": "28306ad9-c91a-4ada-98a2-0b1c5a802f59",
            "message_count": 11,
            "pending_subthreads": 0,
            "readonly": false,
            "status": "property_checkout_expired",
            "topic": "special_request_special",
            "type": "Contextual",
            "unread_count": 1,
            "unread_subthreads": 0
          }
        },
        {
          "last_messages": [],
          "poll_delay": 10,
          "thread": {
            "context_data": {
              "hotelreservation_id": "1724842840"
            },
            "id": "f2c2640f-2bb7-439a-bc8f-ae56fc0a6e7b",
            "message_count": 0,
            "pending_subthreads": 0,
            "readonly": false,
            "status": "new",
            "topic": "free_text",
            "type": "Contextual",
            "unread_count": 0,
            "unread_subthreads": 0
          }
        }
      ],
      "thread": {
        "context_data": {
          "hotelreservation_id": "1724842840"
        },
        "id": "44ab8ad8-342c-4feb-982a-6a373ecfde1d",
        "message_count": 2,
        "pending_subthreads": 0,
        "readonly": false,
        "status": "new",
        "topic": "reservation",
        "type": "Contextual",
        "unread_count": 1,
        "unread_subthreads": 1
      }
    },
    // Additional threads (if any) follow here.
  ]
}

See Messaging API reference for details.


Next steps