Use & Manage via API

 

You are integrated with Rentals United as a Sales Channel or a Property Management System and you would like to automatically exchange messages with guests via Rentals United Guest Communication REST API. In this section we describe best practices for Guest Communication integration.

 

An effective Guest Communication integration for a Sales Channel is composed of the following steps:

  • Starting a new thread for newly created reservation, request or lead

  • Posting a new message in already existing thread

  • Subscribing to webhook notifications about new messages

  • Pulling new messages

 

An effective Guest Communication integration for a PMS is composed of the following steps:

  • Fetching threads attached to already existing reservations, requests or leads

  • Fetching messages for the threads

  • Subscribing to webhook notifications about new messages

  • Pulling new messages

  • Posting a new message in already existing thread

 

You can use our Guest Communication feature via API, as well. Before you start implementing API methods, you need to make sure that the Guest Communication is configured properly for channels you are interested in. Without proper configuration in Rentals United and the channels, the feature will not work. Make sure to follow these articles first:

Once you enabled Guest Communication, you can proceed to API implementation. Rentals United REST API is documented here. There you will find all the necessary methods and technical details.

Below you can read about the basic examples of this API use as well as methods to implement in order to successfully communicate with your guests.

Communication with the guests is based on threads which contain messages. There are multiple threads available, depending on the channel (for example email) or a type of communication (for example guest reviews). The important thing is that you always want to look for threads that have specific "CommunicationChannel" information. See here to learn more about available "CommunicationChannel" elements and how to use them properly.

Threads with the newest messages older than 2 years are automatically removed.

 

Airbnb messages

Airbnb does not give you a possibility to start a conversation with your guest before a unique thread ID is created. Once the thread is created, you and the guest can write to each other. Messaging threads are always created by Airbnb upon the following events:

  • you receive an instant booking

  • you confirm a reservation request

  • you receive a lead with a guest message

Hence, if you want to exchange messages via the Airbnb chat, you need to wait for the above situations to take place.

You can continue communicating via this thread, even after the reservation has already passed.

  1. Retrieve threads. Use the GET /api/messaging/threads method. In response, you want to look for the thread which has "CommunicationChannel" = "Airbnb" information.

  2. Retrieve messages for the selected thread ID. Use the GET /api/messaging/threads/{id}/messages method. In response, you will receive the message history.

  3. Send a message to the selected thread ID. Use the POST /api/messaging/threads/{id}/messages. Use the request format required for a message.

Other details about Guest Communication for Airbnb can be found here. Make sure to read them before you move on.

 

Booking.com messages

Booking.com communication is based on threads. Rentals United creates threads when a new reservation is received from Booking.com. Both guest and host can start the conversation first.

You can exchange messages with the guest from the moment of a booking until 7 days after the guest checks out or cancels the reservation. Whenever the guest responds to the message, the conversation window is extended with additional 14 days. It is not possible to communicate after 80 days have passed from the check-out or cancellation.

  1. Retrieve threads. Use the GET /api/messaging/threads method. In response, you want to look for the thread which has "CommunicationChannel" = "BookingCom" information.

  2. Retrieve messages for the selected thread ID. Use the GET /api/messaging/threads/{id}/messages method. In response, you will receive the message history.

  3. Send a message to the selected thread ID. Use the POST /api/messaging/threads/{id}/messages. Use the request format required for a message.

Other details about Guest Communication for Booking.com can be found here. Make sure to read them before you move on.

 

Expedia messages

Expedia communication is based on threads. Rentals United creates threads when a new reservation, booking request or a lead is received from Expedia. Both guest and host can start the conversation first.

  1. Retrieve threads. Use the GET /api/messaging/threads method. In response, you want to look for the thread which has "CommunicationChannel" = "Expedia" information.

  2. Retrieve messages for the selected thread ID. Use the GET /api/messaging/threads/{id}/messages method. In response, you will receive the message history.

  3. Send a message to the selected thread ID. Use the POST /api/messaging/threads/{id}/messages. Use the request format required for a message.

 

Vrbo messages

Vrbo communication is based on threads. Rentals United creates threads when a new reservation, booking request or a lead is received from Vrbo. Both guest and host can start the conversation first.

  1. Retrieve threads. Use the GET /api/messaging/threads method. In response, you want to look for the thread which has "CommunicationChannel" = "Vrbo" information.

  2. Retrieve messages for the selected thread ID. Use the GET /api/messaging/threads/{id}/messages method. In response, you will receive the message history.

  3. Send a message to the selected thread ID. Use the POST /api/messaging/threads/{id}/messages. Use the request format required for a message.

Other details about Guest Communication for Vrbo can be found here. Make sure to read them before you move on.

 

Email messages

Email messaging is also based on threads and can be used for remaining sales channels. Threads are created by Rentals United upon receiving a message from the guest, but optionally you can create them, too, if you want to start the conversation first.

  1. Create the thread first. Use the POST /api/messaging/threads method.

  2. Send a message to the selected thread ID. Use the POST /api/messaging/threads/{id}/messages. Use the request format required for a message.

  3. Retrieve threads. Use the GET /api/messaging/threads method. In response, you want to look for the thread which has "CommunicationChannel" = "Email" information.

 

Attachments

Attachments are supported for all the "CommunicationChannel" which include messages:

  • Email

  • Airbnb

  • BookingCom

  • Vrbo

The basic methods you need to implement in order to start sending and receiving attachments are the following:

If you have implemented the LNM webhook mechanism (PUT /api/messaging/notifications/subscribe) you will be notified about all new messages. However, due to the attachment size limits, the attached content will not be included in these notifications. The attachments can be pulled by the GET /api/messaging/messages.

Click the links and you will be redirected to the API documentation where you can read in detail about these and other methods.

There may be some format and size requirements when sending attachments due to limitations on the sales channels side. Note that it is entirely up to the channels and Rentals United cannot do anything about it. In such a case, you will receive a relevant notification via API. You can see size and format limits here.

Other details about attachments can be found here. Make sure to read them before you move on.

Airbnb reviews

Airbnb review threads become available after the reservation ends. Both you and your guest can write the first review. The review thread accepts up to four messages: 1 x guest review, 1 x host review, 1 x guest reply and 1 x host reply. You can use this thread only for a limited time (14 days after the check out to submit the review and 30 days to reply). If you exchange all the messages that are available for this thread or the review period passes, the thread becomes unavailable and will not accept any more messages. You can read more about Guest Reviews here.

Recommended Airbnb review flow

  • host review

  • guest review

  • host reply

  • guest reply

Note that in Airbnb it is also possible that it is the guest who submits the review first. If this is the case, feel free to change the order of the steps.

  1. Get the review thread details. Provide a reservation ID and receive a reservation thread details (including reservation thread ID) in the response. There will be only one thread. If the response is empty, it means this reservation does not have a thread (yet).

    GET /api/reviews/thread/{reservationId}

  2. Provide your own host review.

    POST /api/reviews/airbnb/review

  3. Retrieve all messages for this thread ID and look for reviews submitted by the guest. You should look for the following parameters:  \"Mode\":\"review\" and "Creator\":\"guest\". If the response is empty, it means no reviews or replies have been submitted to this thread.

    GET /api/reviews/thread/{id}/messages

  4. Provide one reply to the guest's review.

    POST /api/reviews/airbnb/review-reply

  5. Retrieve all messages for this thread ID and look for replies submitted by the guest. You should look for the following parameter:  \"Mode\":\"reply\".

    GET /api/reviews/thread/{id}/messages

Other details about Guest Reviews for Airbnb can be found here. Make sure to read them before you move on.

If you implemented the Guest Reviews before 2024-01-25, your flow may be as described below. Note that this flow (only regarding reviews) will be deprecated by the end of April, 2024, and all the Rentals United users are required to switch to Recommended Airbnb review flow. You will still be able to use these methods for retrieving and submitting regular Guest Communication messages.

  1. Retrieve threads. Use the GET /api/messaging/threads method. In response, you want to look for the thread which has "CommunicationChannel" = "AirbnbGuestReview" information.

  2. Retrieve messages for the selected thread ID. Use the GET /api/messaging/threads/{id}/messages method. In response, you will receive the message history.

  3. Send a message to the selected thread ID. Use the POST /api/messaging/threads/{id}/messages. Use the request format required for a review or reply.

 

Booking.com reviews

Booking.com review threads become available after the reservation ends. The review thread accepts up to two messages: 1 x guest review, 1 x host reply. It is always the guest who writes the review first and the host can only submit the reply. This order cannot be changed. Note that the host can only respond to the review with comments. In case the guest provides only the rating, it is not possible to reply to such a review. If you exchange all the messages that are available for this thread or the review period passes, the thread becomes unavailable and will not accept any more messages. You can read more about Guest Reviews here.

Recommended Booking.com review flow

  1. Get the review thread details. Provide a reservation ID and receive a reservation thread details (including reservation thread ID) in the response. There will be only one thread. If the response is empty, it means this reservation does not have a thread (yet).

    GET /api/reviews/thread/{reservationId}

  2. Retrieve all messages for this thread ID and look for reviews submitted by the guest. If the response is empty, it means no reviews or replies have been submitted to this thread.

    GET /api/reviews/thread/{id}/messages

  3. Provide a reply to the guest's review.

    POST /api/reviews/bcom/review-reply

Other details about Guest Reviews for Booking.com can be found here. Make sure to read them before you move on.

If you implemented the Guest Reviews before 2024-01-25, your flow may be as described below. Note that this flow (only regarding reviews) will be deprecated by the end of April, 2024, and all the Rentals United users are required to switch to Recommended Booking.com review flow. You will still be able to use these methods for retrieving and submitting regular Guest Communication messages.

  1. Retrieve threads. Use the GET /api/messaging/threads method. In response, you want to look for the thread which has "CommunicationChannel" = "GuestReview" information.

  2. Retrieve messages for the selected thread ID. Use the GET /api/messaging/threads/{id}/messages method. In response, you will receive the message history.

  3. Send message to the selected thread ID. Use the POST /api/messaging/threads/{id}/messages. Use the request format required for a message.

 

Vrbo reviews

The Vrbo review thread accepts three types of messages:

  • 1 x guest review - a review from the guest including text, star rating and a category rating

  • 1 x rating - a star rating from the host

  • 1 x host reply - a response from the host to the guest review including only text

Vrbo review thread becomes available after the reservation ends, which means that you and your guest can review the stay starting on the day of the check-out. Vrbo accepts that both the host and guest can review the stay first. More importantly, the first reviewer has up to 365 days after the check-out day to start the review process. The second reviewer has only 14 days to respond. If the review period passes, the second reviewer will not be allowed to submit the response anymore.

Other details about Guest Reviews for Vrbo can be found here. Make sure to read them before you move on.

Recommended Vrbo review flow

  1. Get the review thread details. Provide a reservation ID and receive a reservation thread details (including reservation thread ID) in the response. There will be only one thread. If the response is empty, it means this reservation does not have a review thread (yet).

    GET /api/reviews/thread/{reservationId}

  2. As a host, provide your rating as soon as the review thread ID is available.

    POST api/reviews/vrbo/rate-guest

  3. Regularly retrieve all messages for this thread ID and look for the guest review. Check below which parameters indicate different types of messages accepted by Vrbo. If the response is empty, it means no messages have been submitted to this thread.

    • guest review: "type":"GuestReview"

    • rating: "type":"GuestRating"

    • host reply: "type":"GuestReviewReply"

    GET /api/reviews/thread/{id}/messages

  4. Once the guest review is present, you can provide the host reply, if necessary.

    POST api/reviews/vrbo/review-reply

  5. Vrbo checks the content of the host reply. You will be able to view the status of the host reply in the "status" parameter.

    • "status":"submitted" - the host reply awaits the approval from Vrbo

    • "status":"rejected" the host reply was rejected by Vrbo, you can submit another host reply

    • "status":"approved", Vrbo accepted the host reply

Airbnb pre-approvals

Read more about what pre-approvals are and how they work here.

  1. Send a pre-approval using the POST /api/airbnb/specialOffers method.

  2. Withdraw the pre-approval using the PUT /api/airbnb/specialOffers method.

  3. Retrieve information on pre-approvals for a specific thread using the GET /api/airbnb/specialOffers.