Reply options

When properties send messages to guests, we provide different ways of adding content to their message, depending on the context. We call these ways "reply options". This page explains how to use reply options to construct replies.

In JSON

By the time a message from a guest reaches a property, it will automatically contain reply_options:

"message": {
  "text": "I'd like to request check-out at 10:00 - 11:00. Is that ok?",
  "reply_options": [
    {
      "caption": "Yes, we can arrange this free of charge",
      ...
    },
    {
      "caption": "Yes, we can arrange this at an extra charge",
      ...
    },
    {   
      ...
    }
  ],
},

These reply options are attached by the Booking Assistant. The options will be different depending on the message.

In our messaging interface

The example above shows reply options for a specific kind of message called a special request. In the Booking.com messaging interface, we present the reply options for special requests like this:

Guest message requesting change of check-out time, with reply option 'Yes, we can arrange this free of charge' selected.

Each radio button above represents an item in message.reply_options. Most reply options also allow additional input, such as text comments (the "Additional info" field). Some options require additional input, such as the second one, which requires the property to enter an amount under "Total cost":

Guest message requesting change of check-out time, with reply option 'Yes, we can arrange this for an extra charge' selected.

In JSON, these additional fields are represented as message.reply_options.options, with the mandatory field specifying whether a field is required:

"reply_options": [
  {
    "caption": "Yes, we can arrange this at an extra charge",
    "type": "button",
    ...
    "options": [          // Contains additional input fields.
      {
        "caption": "Total cost (for entire stay), in EUR",
        "input_value": "",
        "mandatory": 1,   // The property _must_ specify an amount.
        "type": "Cost"
        ...
      },
      {
        "caption": "Additional information:",
        "input_value": "",
        "mandatory": 0,   // The property may add a comment.
        "type": "PlainText"
        ...
      }
    ],
  },
],

Using reply options in a message

When you construct a new message, you copy the desired message.reply_options items into a message.selected_options array. A reply based on the above scenario might contain this:

"selected_options": [
  {
    "caption": "Yes, we can arrange this at an extra charge",
    "type": "button"
    ...
  },
  {
    "caption": "Total cost (for entire stay), in EUR",
    "input_value": "125",
    "mandatory": 1,
    "type": "Cost"
    ...
  },
  {
    "caption": "Additional information:",
    "input_value": "Sorry for the inconvenience.",
    "mandatory": 0,
    "type": "PlainText"
    ...
  }
]
// We left out many fields to keep this readable, but you should
// always copy the _entire_ contents of the reply_options item.

Note that, unlike in reply_options, the additional fields here are not nested in options:

"reply_options": [
  {
    Reply option 1
    "options": [
      { Sub-option 1 },
      { Sub-option 2 }
    ],
  },
]

// Above: nesting. Below: no nesting.

"selected_options": [
  { Reply option 1 },
  { Sub-option 1 },
  { Sub-option 2 }
]

In summary, follow these steps to use reply_options to construct a new message:

  1. From the old message, copy the desired reply_options item and all its children, including options.
  2. In your new message, put everything in a selected_options array, with the chosen reply option and all additional fields at the same level.
  3. Where applicable, populate the input_value field for each option.

For full sample requests you can copy/paste, see Send message to guest.

Rendering reply options in your interface

The UI mockups above should give you an idea of how you can display reply options in your interface. Here are some more tips:

  • The caption for each option contains the recommended button/field text.
  • The type field specifies what kind of input is expected.
  • After a user replies to a message, disable or hide the reply options to avoid repeated input.