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.
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. Structured requests include the following:
- Check in/out time
- Date change
- Cancel for less
- Parking
- Bed preference
- Extra crib
- Extra bed ("Add an extra bed")
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 Support 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
Booking.com has temporarily removed the possibility for guests to send attachments via messages. Therefore, before we enable the function for guests again, you don’t need to perform the following during the self-assessment:
- send an attachment as the guest in step 3
- retrieve the attachment you sent with the message in step 5
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.
Going live
Before you go live with your API integration, you'll need to meet certain requirements. For more information, see Going Live.
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.
Do you want us to improve this page? Click Yes | No in the Was this page helpful? box at the bottom of this page.