hotel_reserve
Book a hotel room. Works for ANY offer list_hotels gave you an offerId for — there is no separate check to make first, so pass the offer the guest chose. Pass that offer’s offerId exactly as you were given it — it names the hotel, room, rate, stay and price, which is why none of those are separate arguments. It expires after 30 minutes; if it has expired or the hotel has raised the price since, nothing is booked — get a fresh one by calling list_hotels with that same offerId, which re-prices just that room rather than showing the guest the whole property again. TWO OUTCOMES, and the reply tells you which. confirmationNumber means the room is booked: give the guest the number and tell them they pay the hotel at the desk — nothing has been charged. paymentUrl means the room is NOT held yet: give the guest that link to pay, their card is HELD rather than charged, and the booking is placed once they have paid. Set acceptedTerms only after the guest has agreed to book this rate. Show them that rate’s cancellation terms where list_hotels gave any; where its cancelTerms was null we hold none, so say so and that the hotel’s own terms apply, then set it once they agree on that basis — a blank is NOT a reason to refuse the booking. Ask the guest for their own phone number and billing address — the hotel puts them on the reservation and uses them to reach the guest. Never invent them. If a call comes back ambiguous, do NOT call again — a reservation may already exist.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| offerId | Yes | The `offerId` of the exact room and rate the guest chose, copied from `list_hotels` unchanged. It names the hotel, the room, the rate, the stay, the party and the price the guest was shown, so none of those are passed separately. It is valid for 30 minutes — if the guest takes longer to decide, call `list_hotels` with this same `offerId` to get a fresh one: it re-prices that one room and nothing else, so the guest is not shown the whole property a second time. Never edit it or build one yourself. | |
| guestCity | Yes | ||
| guestEmail | Yes | The hotel sends its confirmation here. It is the guest's own address, never yours. An example or placeholder address such as name@example.com is refused and nothing is reserved: ask the guest for the address they actually use. | |
| guestPhone | Yes | The guest's phone number, in any format the guest gives it. | |
| guestPostal | Yes | Postal code. | |
| guestStreet | Yes | Street and house number. | |
| guestCountry | Yes | Two-letter country code, e.g. DE, AT, CH. The country the guest lives in, not the one they are travelling to. | |
| acceptedTerms | Yes | TRUE only when the guest has agreed to book this rate. Where `list_hotels` gave that rate cancellation terms, show them first and get the agreement to those. Where its `cancelTerms` was null WE HOLD NONE — tell the guest plainly that we do not have this rate’s cancellation terms and that the hotel’s own terms apply and reach them with the hotel’s confirmation, then set this once they have said to go ahead knowing that. Never assume it on their behalf, and never treat a blank as a reason not to book. | |
| guestLastName | Yes | ||
| guestStreetNo | No | House number, when the guest gives it separately from the street. | |
| guestGivenName | Yes | ||
| guestSalutation | No | How the guest is addressed, in their own words. Only pass what the guest told you; never guess from a name. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present ONLY when nothing was booked. It carries the reason in words a guest can hear and, on a refusal you can recover from, the call to make next. Give the guest the reason; act on the rest yourself. | |
| hotel | No | The property that took the booking. | |
| reason | No | Machine-readable cause of a refusal: terms-not-accepted, guest-email-placeholder, offer-malformed, offer-bad-signature, offer-expired, offer-not-enabled, offer-not-bookable, listing-not-found, not-configured, not-recorded, room-not-offered, rate-not-offered, availability-unreadable, price-unreadable, price-moved-up, guest-details-incomplete, no-booking-identity, dry-run, ambiguous, not-confirmed, unexpected-error. | |
| checkIn | No | ||
| payment | No | What the guest owes and to whom. Nothing is ever charged here. | |
| checkOut | No | ||
| paymentUrl | No | OUR payment page, and the room is NOT reserved until the guest has paid. Their card is HELD, not charged. Present only when nothing was booked yet and payment is what gets it booked. | |
| tellTheGuest | No | Wording meant for the guest rather than for you. On an ambiguous outcome it says NOT to book again — pass that on rather than retrying. | |
| bookingReference | No | OUR reference for this booking — the number the guest quotes to US. Different from `confirmationNumber`, which is the hotel’s and is what they quote at the property. Absent only when the booking could not be recorded. | |
| confirmationNumber | No | Present ONLY when a room was actually booked. The hotel’s own reference — give it to the guest and tell them to keep it. |