Trang này chưa được dịch, nên bạn đang đọc bản tiếng Anh.
Negotiation for AI assistants
An open protocol for travellers' AI assistants to find independent hotels, ask them for private offers on a traveller's dates, counter, and book, with payment by the traveller. REST and MCP, signed quotes, no key needed.
Many hotels on ChatBeds bargain: they make private offers inside limits their owners set, trading rather than discounting (paying now, one more night, a quieter date) and never going below their own floor. This protocol lets a traveller's AI assistant do what a guest does on a hotel's booking page: ask for offers, counter, and book.
Anyone may use it. There's no key to ask for. Calls are limited per address, and each traveller can have one live negotiation per hotel at a time.
The protocol is described, machine-readably, at https://app.chatbeds.app/.well-known/chatbeds-negotiation.json (the
same as GET /public/v1/agents/protocol).
A hotel takes offers from assistants when its owner turns on negotiation and its AGENT channel (off by default). See
Negotiation for the hotel's side.
The flow
- Find hotels that take offers:
GET /public/v1/agents/hotels?city=Lahore(alsocountry,qfor a name). Only hotels whose owners chose to take offers from AI assistants are listed.GET /public/v1/agents/hotels/{hotel_id}gives one hotel's details, with its room types. - Ask for offers:
POST /public/v1/negotiatewith the hotel, the dates, the guests, optionally a budget for the whole stay and how many days the dates can move, and the traveller's email or phone. - Counter:
POST /public/v1/agents/negotiate/{token}/counterwith what the traveller would pay for the whole stay. The hotel answers with new offers, or its last word. - Book:
POST /public/v1/negotiate/{token}/bookwith the offer and the traveller's name and phone. The room is held for an hour; give the travellerpayment_url: they pay by card on the hotel's payment page (Stripe). Never collect card details yourself.
Send the header X-Assistant with your assistant's name (for example X-Assistant: Trip Helper 2.1). The hotel sees
it next to the negotiation.
All addresses are on https://app.chatbeds.app.
Asking for offers
POST /public/v1/negotiate
Content-Type: application/json
X-Assistant: Trip Helper 2.1
{
"hotel_id": "6f1c3b2e-…",
"arrival": "2026-11-12",
"departure": "2026-11-14",
"adults": 2,
"children": 0,
"budget": 180,
"flexible_days": 1,
"guest": { "name": "Sara Brown", "email": "sara@example.com" }
}| Field | |
|---|---|
hotel_id | From the list of hotels |
arrival, departure | YYYY-MM-DD; up to 30 nights |
adults, children | The party |
room_type_id | Optional: one room type (from the hotel's details) |
budget | Optional: what the traveller would pay for the whole stay. Under the offers, the hotel answers it at once |
flexible_days | Optional, 0 to 3: the hotel may offer the same stay up to that many days earlier or later, for less |
guest | name, and email or phone (required: offers belong to a traveller) |
The answer:
{
"token": "Xk3…",
"status": "OPEN",
"currency": "USD",
"expires_at": "2026-11-01T10:30:00+00:00",
"expires_in": 1799,
"bookable": true,
"offers": [
{ "id": "a1b2c3d4", "kind": "pay_now", "label": "Pay now", "room_type": "Deluxe",
"arrival": "2026-11-12", "departure": "2026-11-14", "nights": 2, "currency": "USD",
"total": 186.0, "public_total": 200.0, "saving": 14.0, "pay_now": true, "final": false,
"quote": "eyJhbGciOiJFZERTQSIs…" }
],
"said": [ { "by": "guest", "said": "Asked for an offer: …" }, { "by": "ana", "said": "Here's what I can do. …" } ],
"next": "To book an offer: …",
"booking_page": "https://app.chatbeds.app/book?p=6f1c3b2e-…"
}status:OPEN(offers stand untilexpires_at),BOOKED,DECLINED(nothing free, or the hotel's last word was refused),EXPIRED.totalis what the traveller pays, taxes included;public_totalis the price anyone sees for the same stay.final: trueis the hotel's last word: countering again won't move it.bookable: false: the hotel takes payment at the hotel only, so assistants can't book it. Send the traveller tobooking_page.
Offers are private prices for this traveller. Don't publish them.
Signed quotes
Every offer carries quote: a compact JWS (alg EdDSA, Ed25519, typ chatbeds-quote+jwt) of what the hotel
promised: the hotel, the negotiation and offer, the room, the dates, the party, the total, the public price, the terms
and exp. Check it with the key at GET /public/v1/agents/jwks.json (kid in the header). Passing it back when
booking is optional; a changed quote is refused.
Countering
POST /public/v1/agents/negotiate/{token}/counter
{ "amount": 160, "offer_id": "a1b2c3d4" }amount is the price for the whole stay; offer_id optional (the trade the traveller prefers). The answer is the
negotiation again: new offers moving towards the traveller's price, never under the hotel's floor, or its last word.
A hotel allows a few rounds.
GET /public/v1/agents/negotiate/{token} gives where it stands at any time.
Booking
POST /public/v1/negotiate/{token}/book
X-Assistant: Trip Helper 2.1
{ "offer_id": "a1b2c3d4", "quote": "eyJhbGciOiJFZERTQSIs…",
"guest": { "first_name": "Sara", "last_name": "Brown", "email": "sara@example.com", "phone": "+447700900123" } }The answer is 201 Created:
{ "ref": "4F2A9C", "status": "waiting_for_payment", "payment_url": "https://checkout.stripe.com/c/pay/…",
"pay_by": "2026-11-01T11:05:00+00:00", "stay_page": "https://app.chatbeds.app/stay?t=…",
"currency": "USD", "total": 186.0 }The booking is at the agreed price and held until pay_by. Unpaid by then, the room is let go. Once paid, the hotel
sends its confirmation, and stay_page is the traveller's page for the stay (arrival time, extras, online check-in).
MCP
The same is an MCP server (streamable HTTP, JSON answers) at https://app.chatbeds.app/public/v1/agents/mcp, with
these tools: find_hotels, hotel_details, request_offers, counter_offer, negotiation_status, book_offer.
Their inputs are the fields above; their results come as structuredContent (and the same as text). An error the
traveller can act on (dates passed, nothing free, an offer expired) comes back as a tool result with isError: true.
Errors
| Status | When |
|---|---|
| 400 | A field is missing or wrong (the message says which) |
| 404 | The hotel doesn't take offers from assistants, or the negotiation isn't one |
| 409 | The hotel isn't taking offers now, an offer expired, or the hotel takes payment at the hotel only |
| 429 | Too many calls from your address, or too many negotiations for this traveller today |
Errors are {"detail": "…"}, written to be shown to the traveller.
Bạn đang xây dựng gì đó?
Attendance machines
Send punches from any attendance machine or its software to ChatBeds with the Attendance API. Each punch becomes a staff member's clock-in or clock-out at the minute it happened.
Agent API and MCP
Let an AI agent work a hotel on ChatBeds as a member of its team, over REST or MCP, with the hotel's rules, previews, approvals and undo. Sign in with an agent key or OAuth.