Messaging API overview

Hold Notice

This product is currently on hold. Unfortunately, this means we will not provide support or certify any new providers until the hold is released.

Connect your software to our Messaging API to enable properties to communicate with guests, using your interface. This helps properties respond quickly and effectively to questions, leading to happier guests, more bookings, and better business.

Features

  • Retrieve threads, sub-threads, and messages
  • Reply with text and/or image attachments
  • Use quick replies to instantly process special requests
  • RESTful API that speaks JSON

Getting started

To use the Messaging API, you must:

After you've taken care of the above, you can request authorisation tokens from /json/messaging-auth. You need these tokens to call the other endpoints of the Messaging API.

The examples in the table of contents will show you how to start using the Messaging API. A good first step is to retrieve the number of pending message threads with /global_counters.

Besides the examples, you'll also need the technical details in the Messaging API reference.

Authentication

As with our other APIs, you need a machine account to use the Messaging API. But unlike the other APIs, the Messaging API also requires you to provide a limited-lifetime authorisation token with each request.

The authorisation token you use determines for which properties you retrieve data. If the token is valid for all properties, then the response also applies to all properties. If the token is valid for just one property, the response applies to that property.

Working with Messaging API

This section explains important background information for working with this API. Don't forget to also check out:

  • the example requests and response in the table of contents (on the left);
  • the Messaging API reference, containing the full details of the API's technical characteristics.

Data model: threads, sub-threads, messages

Messages are organised in threads. Each reservation has one main thread, with a reservation ID.

There is one exception: If you work with Booking Home properties and support pre-booking messages, then pre-booking threads will not have a reservation ID. Pre-booking messages are disabled by default.

A main thread contains one or more sub-threads. Most sub-threads are about a particular topic. For example, one sub-thread can be about a request for a different check-in time, and another about an extra bed for a child. The only sub-threads without a specified topic are free-text threads.

This diagram shows the relationships between threads, sub-threads, and messages:

Messaging API data model

See the Messaging API reference for more details.

Rendering threads/sub-threads

The thread/sub-thread distinction is important for Booking Assistant, but it's not important for your users. You can hide the data model in your UI by presenting everything as one thread. For an example, see our messaging interface on admin.booking.com.

Booking Assistant

You will often see the name Booking Assistant appear as the sender or recipient of a message. The Booking Assistant is our chatbot which moderates most messages between guests and properties.

This is how the Booking Assistant sits between the guest and property:

Booking Assistant messaging flow

API reference

In addition to the documentation you're reading now, be sure to also check out the Messaging API reference, which provides technical details about the API's functions and characteristics.

Support & feedback

If you have questions or suggestions for improvement, please feel free to contact us.