Understanding the Messaging API¶
The Messaging API enables you to let properties communicate with their guests.
What is possible with the Messaging API?¶
The Messaging API enables you to do the following:
- Retrieve messages and conversations in multiple ways.
- Send (and reply to) text messages.
- Reply to free text special requests.
- Upload, download, and send attachments.
- Tag conversations as no reply needed.
- Tag messages as read.
- Querying and retrieving historical messages and conversations.
Special and structured requests not yet possible
Currently the Messaging API does not support structured requests. This means that when a guest sends a structured request after a reservation this does not show up in the Messaging API.
Main URL and use of shortened endpoint paths¶
The Messaging API's main URL is https://supply-xml.booking.com/messaging. All shortened endpoint paths imply that you must add the main URL. For example: /messages becomes https://supply-xml.booking.com/messaging/messages in an actual request.
Authentication¶
The Messaging API uses the same authentication methods as other APIs.
When can properties send messages to guests?¶
Properties can send messages to guests within the following time frames:
- From the time of booking until 7 days after the guest checkout.
- From the time of booking until 7 days after the booking is cancelled.
If the guest messages about the booking, the property gets an additional 14-day window to reply to the guest irrespective of when the booking was cancelled or when the guest checked out.
Currently, guests can send messages to properties from the time of booking till 66 days after the checkout.
Self-assessment tutorial¶
In this self-assessment tutorial you use the Messaging API to:
- Start a conversation with a guest.
- Retrieve a guest's reply.
- Send a message with an attachment.
- Tag conversations.
Who is this for?¶
You should follow this tutorial if you're any of the following:
- A developer who works for an existing Connectivity Partner that intends to implement the Messaging API.
- A developer who wants to estimate the time needed to implement the Messaging API.
- A developer who wants to test the functionalities of the Messaging API.
If you want to pass certification for the Messaging API finish the tutorial and send an email to connectivity@booking.com with your provider ID and the specified proof (indicated in the tutorial).
Tutorial requirements¶
To follow this tutorial, you need a test property with an active connection that has at least one room type with availability and prices.
Getting started¶
Go through the following steps:
- Go to https://secure.booking.com/book.html?test=1;hotel_id={property_id}. Ensure that you use your test property's id to replace {property_id}
- Create a test reservation by providing all the required reservation details. (If you need to add credit card information, you can use 4111111111111111.)
This is reservation one. - Message the property with an attachment as the guest using the app (or desktop).
- Create another test reservation, but this time do not send a message as the guest.
This is reservation two. -
Regarding reservation one, perform the following actions:
- Retrieve the message you sent as a guest.
- Retrieve the attachment you sent with the message.
- Tag the message as read.
- Reply to the guest's message as the property.
You need to show RUIDs of the above actions and screenshots of what it looks like in your system. -
Regarding reservation two, perform the following actions:
- Retrieve the (emtpy) conversation.
- Start conversation with a guest by sending a message to the conversation.
- Tag conversation as no reply needed.
You need to show RUIDs of the above actions and screenshots of what it looks like in your system.
Contact us¶
Before you go live with your Messaging API integration, we recommend contacting your account manager or the Connectivity Support team.
Need help integrating with the Messaging API? The experts in our Connectivity Support team are here to help.
Have ideas for how we can improve your experience of using the Messaging API? To give us your feedback:
- Log in to the Connectivity Portal
- In the top menu, click .
- Select Give Feedback.