Create Message Rule

Creates a message rule for one listing (listingID), the listings of one listing group (listingGroupID), or every listing (allListings: true). Send exactly one of the three. Every option of Host Tools' rule editor is available. Requires the messageRules:write scope.

Each event takes its own options (see the request body). An option that doesn't fit the rule, such as preapprove on a check-out rule, is refused with a 400 that says why.
Scheduled messages. Saving a rule (new, edited, or turned back on) reschedules the messages of the account's existing reservations in the background, the same as saving in Host Tools. A new rule can schedule messages onto bookings that already exist, and some may send right away (for example a check-in rule on a stay that starts today).

Email, SMS and webhooks. sendTo email and sms send the message to the addresses or numbers given instead of the guest. SMS goes to US and Canadian numbers only, and only from accounts with an Airbnb or VRBO account connected. sendTo webhook POSTs the message as JSON ({"data": ...}) to webhookUrl, which must be an https address on the public internet.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
string
required

The rule's name, for the host. Used as the email subject for sendTo email.

string
enum
required

What sends the message. checkin and checkout send days before or after at minutes; occupied sends on dayOfTheWeek during a stay. The others send when the event happens, after delay minutes: booking (confirmed), inquiry, pending (a booking request), timedout (a pre-approval expired), cancelled, doorUnlocked, and the four changes to a booking.

string
enum

Which reservations the rule sends for. internal is reservations added in Host Tools or with Create Reservation. Default all.

Allowed:
integer
-365 to 365

checkin and checkout only: days before (negative) or after the check-in or check-out, 0 for the day itself. Default 0.

integer
0 to 1439

checkin, checkout and occupied only: the time to send, in minutes after midnight in the listing's timezone. Default 1020 (5 PM).

string
enum

occupied only, and required there: the weekday of the stay to send on

Allowed:
integer
≥ 0

Every event but checkin, checkout, occupied and doorUnlocked: minutes to wait after the event. Default 0.

integer

1 (the default) for any stay; a larger number for stays of at least that many nights; a negative number for stays of at most that many nights (-3 is 3 nights or fewer).

integer

0 (the default) for any number of guests; a positive number for at least that many guests; a negative number for at most that many.

limitDays
array of strings

Send only when the check-in or check-out (see limitEvent) falls on these weekdays, such as for a cleaner who works some days. Empty or left out for any day.

limitDays
Allowed:
string
enum

With limitDays, which day it checks. Default checkout.

Allowed:
string
enum

Send only if the night before check-in (before), the night after check-out (after) or either is open. Useful for offering extra nights. Default none.

Allowed:

The message, as texts by language. default is required and is sent when the guest's language has no text of its own; add language codes such as es or fr for others. A plain string is taken as the default text; a rule read back always has the object form. Message tags such as {{Guest First Name}} fill in when the message is sent. Required, unless the rule only leaves a review (reviewEnabled without sendMessageAfterLeavingReview).

boolean

Send the text in the guest's language when there is one. Left out, it's true when messages has more than the default text. Guest messages only.

boolean

checkin rules with days 0 or less: a booking made after the send time gets the message right away instead of not at all.

The last-minute message, if it should differ from messages, as texts by language like messages. Left out, messages is sent.

boolean

booking rules: don't send for a last-minute booking

boolean

Leave the guest a 5-star review. Only checkout rules with days 0 or more, sendTo guest, and channel all, Airbnb or VRBO.

With reviewEnabled, and required there: the public review to leave, as texts by language like messages.

boolean

With reviewEnabled, leave the review just before the review window closes.

boolean

Don't send the message if the guest has already left a review.

boolean

With reviewEnabled, also send the message after leaving the review.

string
enum

Who gets the message: the guest in the channel's inbox (default), the addresses in email, the numbers in sms, or webhookUrl.

Allowed:
string

sendTo email: addresses, separated by commas

string

sendTo sms: US or Canadian phone numbers, separated by commas

string

sendTo webhook: the https address on the public internet to POST to

boolean

inquiry rules: also pre-approve the inquiry

boolean

pending rules: also accept the booking request

boolean

booking, inquiry and pending rules: let AI personalise the message from the guest's message, the listing's details and the host's quick replies.

string

The listing the rule is for

string

The listing group the rule is for

boolean

true for a rule on every listing

Headers
string

Partner API key (deprecated — use OAuth 2.0 for new integrations)

string

User's authentication token (legacy). Use Authorization Bearer header for new integrations.

Responses

429

Too many requests

Language
Credentials
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json