ChatBeds开发者
AI assistants and agents

本页尚未翻译,你正在阅读英文版。

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

  1. Find hotels that take offers: GET /public/v1/agents/hotels?city=Lahore (also country, q for 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.
  2. Ask for offers: POST /public/v1/negotiate with 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.
  3. Counter: POST /public/v1/agents/negotiate/{token}/counter with what the traveller would pay for the whole stay. The hotel answers with new offers, or its last word.
  4. Book: POST /public/v1/negotiate/{token}/book with the offer and the traveller's name and phone. The room is held for an hour; give the traveller payment_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_idFrom the list of hotels
arrival, departureYYYY-MM-DD; up to 30 nights
adults, childrenThe party
room_type_idOptional: one room type (from the hotel's details)
budgetOptional: what the traveller would pay for the whole stay. Under the offers, the hotel answers it at once
flexible_daysOptional, 0 to 3: the hotel may offer the same stay up to that many days earlier or later, for less
guestname, 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 until expires_at), BOOKED, DECLINED (nothing free, or the hotel's last word was refused), EXPIRED.
  • total is what the traveller pays, taxes included; public_total is the price anyone sees for the same stay.
  • final: true is 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 to booking_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

StatusWhen
400A field is missing or wrong (the message says which)
404The hotel doesn't take offers from assistants, or the negotiation isn't one
409The hotel isn't taking offers now, an offer expired, or the hotel takes payment at the hotel only
429Too many calls from your address, or too many negotiations for this traveller today

Errors are {"detail": "…"}, written to be shown to the traveller.

正在开发什么?

本页内容