ChatBedsডেভেলপার
Hotel features API

এই পাতাটি এখনও অনুবাদ হয়নি, তাই আপনি ইংরেজি সংস্করণ পড়ছেন।

Negotiation

The hotel's limits for private offers, the list of negotiations with the WhatsApp status, and offers made at the desk for a caller. Ana trades rather than discounts, never under the hotel's floor.

A hotel that bargains lets Ana make private offers inside limits the owner sets. She trades rather than discounts: each kind of offer unlocks part of the allowance.

Offer kindLabelUnlocks
baseYour datesbase_pct, for nothing in return
pay_nowPay now+ pay_now_pct: the whole stay paid when booking
longerOne more night+ longer_pct, off the whole, longer stay
datesA quieter date+ dates_pct, when the guest's dates can move

A guest who stayed before gets + returning_pct. All of it is capped at max_discount_pct, and scaled by how full the hotel is that night: nothing off when nearly full, the whole allowance when quiet. A night is never priced under RevBot's floor for its room type. Opening offers keep some of the allowance back; counter-offers can reach it all, within max_rounds.

Offers are private prices for one stay, with an expiry. They are never shown as a public rate.

Guests negotiate on the booking page, on WhatsApp, at the reception kiosk, on a phone call with Ana, at the desk, through travellers' AI assistants (Negotiation for AI assistants), and through partner apps on the API (Negotiation, the channel PARTNER, off until the hotel turns it on). Each is a channel the hotel can turn off.

Get the settings

GET/api/v1/negotiation/settings
Permission: rates.view
property_id uuid (query)required
The property.
200 OK
{
  "enabled": true,
  "max_discount_pct": 15,
  "base_pct": 5,
  "pay_now_pct": 5,
  "longer_pct": 8,
  "dates_pct": 5,
  "returning_pct": 3,
  "max_rounds": 3,
  "expiry_minutes": 30,
  "nightly_cap": 0,
  "room_type_ids": [],
  "channels": {
    "BOOKING_PAGE": true,
    "WHATSAPP": true,
    "RECEPTION": true,
    "DESK": true,
    "PHONE": true,
    "AGENT": false
  }
}

The values above are the defaults. enabled is false until the owner turns it on.

Change the settings

PUT/api/v1/negotiation/settings
Permission: rates.manage

property_id is a query parameter. Send only what changes; the answer is the whole settings, as for GET.

enabled boolean
Taking offers or not.
max_discount_pct number
0 to 50. The most off, whatever the trades.
base_pct, pay_now_pct, longer_pct, dates_pct, returning_pct number
0 to 50 each. What each trade unlocks.
max_rounds integer
1 to 5. How many counter-offers a guest can make.
expiry_minutes integer
5 to 1440. How long offers stand.
nightly_cap integer
0 to 500. Once this many negotiated bookings take a night, that night gets nothing off. 0: no limit.
room_type_ids uuid[]
The room types offers may be for. Empty: all.
channels object
Any of BOOKING_PAGE, WHATSAPP, RECEPTION, DESK, PHONE, AGENT, each true or false. Channels left out keep their value.
Request
curl -X PUT "https://app.chatbeds.app/api/v1/negotiation/settings?property_id=6f1c3b2e-8a0d-4f5e-9b7a-2c3d4e5f6a7b" \
  -H "Authorization: Bearer $FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "max_discount_pct": 12, "channels": {"AGENT": true}}'

List negotiations

GET/api/v1/negotiation
Permission: rates.view

The negotiations of the last days (at most 300, newest first), a summary, the settings, and whether WhatsApp guests get offers.

property_id uuid (query)required
The property.
days integer (query)
1 to 365. Default 30.
200 OK
{
  "negotiations": [
    {
      "id": "0b6f3d1a-6c2e-4b8f-9a71-5d2c8e4f1a90",
      "channel": "WHATSAPP",
      "status": "BOOKED",
      "name": "Sara Brown",
      "phone": "+447700900123",
      "email": null,
      "arrival": "2026-11-12",
      "departure": "2026-11-14",
      "nights": 2,
      "adults": 2,
      "children": 0,
      "room_type": "Deluxe",
      "budget": 160.0,
      "currency": "USD",
      "public_total": 180.0,
      "agreed_total": 165.0,
      "offers": [],
      "rounds": [
        { "at": "2026-10-21T09:12:40+00:00", "by": "guest", "said": "Asked for an offer: 12 Nov to 14 Nov, 2 adults, about 160.00.", "amount": 160.0, "offers": null },
        { "at": "2026-10-21T09:12:41+00:00", "by": "ana", "said": "Here's what I can do. …", "amount": null, "offers": ["a1b2c3d4", "e5f6a7b8"] }
      ],
      "counters": 1,
      "reservation_id": "a589df05-30ad-4ee5-9832-16ff6c2c1d0e",
      "created_at": "2026-10-21T09:12:40+00:00",
      "expires_at": "2026-10-21T09:52:10+00:00",
      "created_by": null
    }
  ],
  "summary": {
    "total": 14,
    "open": 2,
    "booked": 5,
    "conversion": 36,
    "booked_value": 812.0,
    "public_value": 900.0,
    "average_off": 9.8,
    "currency": "USD"
  },
  "settings": { "enabled": true, "max_discount_pct": 15 },
  "whatsapp": {
    "connected": true,
    "connected_elsewhere": [],
    "guest_services": true,
    "ana": true,
    "channel_on": true,
    "taking_offers": true
  }
}
FieldMeaning
negotiations[].channelBOOKING_PAGE, WHATSAPP, RECEPTION, DESK, PHONE or AGENT
negotiations[].statusOPEN, BOOKED, DECLINED or EXPIRED
negotiations[].offers[]The offers standing now, each with id, kind, label, room_type_id, room_type, rate_plan_id, arrival, departure, nights, currency, total (with tax), public_total, room_total, public_room_total, saving, lowest (the hotel's lowest room price for it: staff only, never shown to guests), pay_now, final
negotiations[].rounds[]What each side said, in order: at, by (guest or ana), said, amount (the guest's price, else null) and offers (the IDs of the offers made then, else null)
negotiations[].created_byThe person who started it at the desk, else null
summary.conversionBooked, as a percent of all
summary.booked_value, public_valueRoom totals of booked negotiations, at the agreed and at the public price
summary.average_offPercent off the public price, over booked negotiations
settingsThe whole settings, as for GET /settings (trimmed above)
whatsappWhether a guest asking for a better price on WhatsApp gets offers from this hotel, and why not. See below

The whatsapp status

FieldMeaning
connectedThe hotel's own WhatsApp number is connected
connected_elsewhereWhen not: the names of the owner's other hotels whose number is connected. Guests writing there get offers by that hotel's settings
guest_servicesGuest services is on, so Ana answers guests
anaAna's AI is available on the server
channel_onNegotiation is on and its WHATSAPP channel is on
taking_offerschannel_on, connected and guest_services together: WhatsApp guests get offers here

Get one negotiation

GET/api/v1/negotiation/{negotiation_id}
Permission: rates.view

One negotiation, in the same shape as in the list. room_type is null here. 404 Negotiation not found. for one of another account.

Make offers at the desk

POST/api/v1/negotiation/desk
Permission: reservations.manage

Offers for someone on the phone or at the desk, inside the same limits. Needs the DESK channel on. property_id is a query parameter. The answer is the negotiation.

arrival daterequired
The first night.
departure daterequired
The day the guest leaves. Up to 30 nights.
adults integer
1 to 20. Default 1.
children integer
0 to 20. Default 0.
room_type_id uuid
One room type. Default: the cheapest that fits.
budget number
What the guest would pay for the whole stay. Under the offers, Ana counters it at once.
flexible_days integer
0 to 3. How many days the dates may move, for a quieter date.
name, phone, email string
The guest. A guest gets offers for at most 8 different stays a day at one hotel, and one negotiation open at a time. Asking again for the stay already open carries that negotiation on (a budget given is a counter-offer) and doesn't count again.
Request
curl -X POST "https://app.chatbeds.app/api/v1/negotiation/desk?property_id=6f1c3b2e-8a0d-4f5e-9b7a-2c3d4e5f6a7b" \
  -H "Authorization: Bearer $FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"arrival": "2026-11-12", "departure": "2026-11-14", "adults": 2, "budget": 160, "phone": "+447700900123"}'

When nothing is free, the negotiation comes back DECLINED with no offers.

Counter

POST/api/v1/negotiation/{negotiation_id}/counter
Permission: reservations.manage
amount numberrequired
What the guest would pay for the whole stay, with tax.
offer_id string
The offer the guest prefers. Default: all of them.

Ana accepts (one final offer at the guest's price), or moves every offer towards it. On the last round she gives her lowest, marked final. The answer is the negotiation, its expiry renewed.

Book an offer

POST/api/v1/negotiation/{negotiation_id}/book
Permission: reservations.manage

Books the room at the agreed price for the guest.

offer_id stringrequired
The offer.
first_name, last_name stringrequired
The guest.
phone, email string
The guest's contact.
paid_amount number
What the guest paid now. A pay_now offer needs the whole total.
payment_method string
CASH (default), CARD or BANK_TRANSFER, for paid_amount. With no paid_amount, the booking is paid at the hotel.

The answer is the negotiation, now BOOKED, with reservation_id.

Close

POST/api/v1/negotiation/{negotiation_id}/close
Permission: reservations.manage

Ends an open negotiation: it becomes DECLINED. A negotiation already ended is returned as it is.

Errors

StatusdetailWhen
400Each percentage must be between 0% and 50%. and similarA setting out of range
400The departure must be after the arrival., Offers are for stays of up to 30 nights., The arrival date has passed.Desk offers
400This price is for paying now: take USD 186.00 first.Booking a pay_now offer without the whole paid_amount
409This hotel isn't taking offers here. The prices shown are the best ones.Negotiation off, or the DESK channel off
409This offer has ended. Ask for a new one. / These offers have expired. Ask for a new one.Countering or booking a negotiation that isn't OPEN
409That offer has changed. Please choose again.offer_id isn't one of the offers standing now
409This booking can't be made. Please check with a manager.The guest matches the hotel's blocked list
429You've asked for several offers today. Please contact the hotel.Offers for 8 different stays from this phone or email today

কিছু বানাচ্ছেন?

এই পাতায়