Messaging API overview¶
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.
- 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
To use the Messaging API, you must:
- be a certified Booking.com Connectivity Partner (or submit your details to become one);
- ask your account manager or Connectivity Support to set up a test configuration for you.
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.
Besides the examples, you'll also need the technical details in the Messaging API reference.
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:
See the Messaging API reference for more details.
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.
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:
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.