ChatBedsالمطورون
الموارد

لم تُترجم هذه الصفحة بعد، لذا فأنت تقرأ النسخة الإنجليزية.

Changelog

What's new in the ChatBeds partner API and app platform.

Within v1, ChatBeds only adds: new fields, operations and webhook events. Ignore fields you don't know. A change that would break existing code would come under a new path. See Versioning.

2026-11-07

Staging

  • staging.chatbeds.app: a separate ChatBeds to build and test on, with every feature unlocked, Stripe test mode, simulated WhatsApp and cbk_test_ keys. Releases reach it at least 48 hours before production. See Environments.
  • Test tools (staging only) under /partner/v1/sandbox: reset to a scenario, time travel, send a webhook event now, the webhook log with replay, the API log, and simulated card payments and guest WhatsApp messages. See Test tools.
  • Keys and tokens now carry their environment: cbk_live_ / cbat_live_ in production (existing cbk_ keys keep working), cbk_test_ / cbat_test_ on staging. Each environment answers the other's with 401 and the address to use.

Everywhere

  • Every answer has an X-Request-Id header, your own when you send one.

2026-11-02

Rooms and rates

  • Room types have cancellation_policy_id: a room type's own cancellation policy, used for its bookings unless the rate plan has one. See policies.

2026-10-24

Hotel features API

  • Guests, loyalty and memberships. Guest Memory and consent, the loyalty programme, paid memberships and win-back when rooms are empty. See Guests, loyalty and memberships.
  • ChatBeds Network. /api/v1/network: joining, referrals, monthly statements, walks and shifts. See ChatBeds Network.

Booking page

  • GET /public/v1/book/{property_id}/network: nearby network hotels with a room when this one is full.
  • POST /public/v1/book/{property_id}/reservations takes network_ref, and guest.passport also takes a good stay's signed record (up to 4,000 characters, so the JWT fits). The answer's passport says whether the deposit was skipped.
  • GET /public/v1/book/{property_id} has network.

Signed records

2026-10-21

Hotel features API

A new section, Hotel features API, documents the ChatBeds app's own endpoints for newer features. They are called with a signed-in person's login (a Firebase ID token), inside their role, not with a partner key. The partner API (/partner/v1) and its webhooks don't change.

  • Payments in WhatsApp and phone bookings. GET and PUT /api/v1/finance/chat-payment: the booking page's way (FOLLOW), pay at the hotel (HOTEL), or an advance (ADVANCE: a percent or the first night). The room is held 2 hours, the guest reminded after 1. GET /public/v1/pay/{token} is the Pay now button's address. See Payments in WhatsApp and phone bookings.
  • Negotiation. The limits (/api/v1/negotiation/settings), the negotiations with a summary and a whatsapp status that says whether WhatsApp guests get offers and why not, and offers made at the desk. See Negotiation.
  • Night mode and phone lines. /api/v1/night-mode (hours, on call, the ladder, the remote ID check) and /api/v1/voice (lines and calls), with the Twilio and Telnyx webhook addresses for whoever runs the server. See Night mode and phone lines.
  • AI manager. /api/v1/ai-manager: its jobs and limits, the price questions, and running it now. See AI manager.

AI assistants

  • GET /public/v1/agents/hotels/{hotel_id} and GET /public/v1/agents/protocol are now described on Negotiation for AI assistants. Booking an offer answers 201.

2026-10-19

Changing a booking

  • Preview a change. PATCH /reservations/{id}?dry_run=true (reservation.previewChange, scope reservations:write) prices a change exactly as saving would, and saves nothing. It sends no webhook, touches no payment link and is not stored for Idempotency-Key. It answers {"preview": {"before", "after", "difference", "dry_run"}}, with each night's price. See Preview a change.
  • expected_total on a change. PATCH /reservations/{id} takes expected_total. If the new total differs, nothing is saved and the answer is 409 "The price has changed: the new total is USD 450.00. Preview the change again."
  • Room type and rate plan. PATCH /reservations/{id} takes room_type_id and rate_plan_id, before arrival only (409 otherwise). Every night is priced again. The room type must be free (409) and fit the guests (400). The room is kept if it is of the new type; otherwise unit becomes null. A booking with a price agreed by hand is refused (409).
  • Links voided after a change. The PATCH response has voided_payment_links. When the open card links ask more than is now owed, they are all voided, at Stripe too. Make one new link for what is owed.

Cancelling

  • Cancellation quote. GET /reservations/{id}/cancellation-quote (reservation.cancellationQuote, scope reservations:read) gives exactly the fee and explanation cancelling would give now, refundable, balance_after and refund_due_after. 409 for a booking already cancelled, checked in or out. See Get a cancellation quote.
  • Policy on the booking. Every reservation (in responses and webhooks) has cancellation_policy: the policy, free_until, free_now, fee_now and explanation. null unless the booking is confirmed or pending.
  • Refunds due. Every reservation has refund_due: what was paid beyond the total. ChatBeds does not refund through Stripe by itself; the hotel refunds and records it. See Refunds.

Payments

  • Void a payment link. POST /payments/{id}/void (payment.void, scope payments:write) closes an unpaid card link at Stripe. Its status becomes VOIDED. A link paid meanwhile is recorded and returned COMPLETED. Cancelling a booking now voids its open links too. See Void a payment link.
  • Open links on the booking. Every reservation has payment_links: the card links that can still be paid.

Webhooks

  • Payment events. payment.completed, payment.failed, payment.expired, payment.voided and payment.refunded, with data.payment and data.reservation. Same signature and retries as booking events. They need folios:read or payments:write. See Webhooks.
  • Off by default. A key or app receives only the three reservation.* events until its developer turns others on: on the Developers page or PATCH /api/v1/developer/apps/{id} (webhook_events) for apps; on Settings → Partner API or PUT /api/v1/partner-keys/{key_id}/webhook-events for keys. See Choosing events.

Developers

  • Scopes show their endpoints. The Developers page shows which endpoints each scope opens. GET /api/v1/developer/catalogue lists every scope with its endpoints and every webhook event. See Scopes.
  • Capabilities. GET /capabilities lists 25 operations. features adds webhook_events_on, reservation_preview, room_type_change, cancellation_quote and void_payment_link; webhooks lists all 8 events.

2026-10-17

Room content

  • Descriptions, photos and videos. Hotels now upload photos and short videos of each room type to ChatBeds. Room types carry videos, media (photos then videos with kind, position, alt, hosted, mime_type, size) and updated_at. Hosted files live at https://app.chatbeds.app/public/v1/media/{id}: the address never changes, needs no credential and answers byte ranges. See Rooms and rates.
  • Two new operations: roomType.get (GET /properties/{property_id}/room-types/{room_type_id}) and roomType.media (GET .../room-types/{room_type_id}/media).
  • Syncing and caching. roomType.list takes updated_since; room type reads answer with an ETag (send it in If-None-Match for 304) and Cache-Control: private, max-age=60.

Guests and room features

  • Children's ages. offer.search takes child_ages (repeated); reservation.create and reservation.modify take child_ages, cots and extra_beds; reservations return them. Children under 2 are infants: free and not counted against the room's size. Every booking is checked against the room's size and the hotel's children policy (400).
  • Prices for more guests. Room types carry pricing (base_occupancy, extra_adult_price, child_bands, infants_under); offers' nights carry extra_guests.
  • Room features. Room types carry features (pets, accessibility, smoking, bathroom, view, space codes), beds, cots, extra_beds and extra_bed_price.
  • The property for guests. GET /properties adds description, photos, photo_alts, facilities and policies (pets, children, minimum check-in age, smoking, accessibility, house rules).

Extras

  • Room-specific and complimentary extras. Extras carry room_type_ids (only with those room types; empty: all) and included (complimentary: comes free with the room). Adding an extra to a booking of another room type, or adding a complimentary one, is refused with 400.

2026-10-12

Channels

  • Bookings from the channel manager. Hotels can connect Booking.com, Expedia, Agoda, Airbnb and more through a channel manager. Those bookings carry the source CHANNEX:<site>, for example CHANNEX:Booking.com, and come in webhooks like any other booking. Treat an unknown source as "another channel". See Reservations.
  • Closed to arrival and departure. A hotel can close a night to arrivals (no stay may start that night) or to departures (no stay may end that morning). Quotes and bookings that break them are refused with 400 "Standard is closed to arrivals on ..." or "... closed to departures on ...", and offers leave them out. See Availability.

Groups

  • Rooms held for groups. A hotel can hold rooms for a group (a wedding, a tour) until a release date. Held rooms aren't counted in available, and booking them is refused with the usual 409 "No ... room is available". They come back on the release date. See Availability.

Guests

  • "Do not book". A hotel can mark a guest it won't take. Booking them is refused with 409 "The hotel does not accept this booking. Ask the guest to contact the hotel." The reason is never shown. See Reservations.

Money

  • Several taxes. The property's tax now lists each tax in tax.taxes[]: a percent of the room, extras or both (added or included in prices), or an amount per guest or per room per night. tax.rate stays, as the percents added together. See Rooms and rates.
  • Deposits. A reservation has deposit when the hotel asks one: the amount at booking, when the rest is due, and what is owed now. See Reservations.
  • Quotes show each tax in tax.lines[] and the deposit asked in deposit.

Key cards

  • The ChatBeds Key API. Hotels connect their own key-card system. ChatBeds sends it make, cancel and test requests: a guest's key at check-in, cancelled at any check-out. See Key cards.
  • Two ways to connect. Signed requests to an https address (the lock company's cloud, or a connector service), with the same ChatBeds-Signature as webhooks. Or the bridge, a small program on the hotel's desk computer that asks for requests with its own ckb_ token.
  • For lock companies and connector services: the request and answer format, the bridge's handlers, and a template for a brand's own protocol.

2026-10-10

The app platform

  • Apps. Register an app in the developer console and connect it to any number of hotels. See Apps.
  • OAuth 2.0. The authorization code flow with PKCE (S256). Access tokens (cbat_) last an hour; refresh tokens (cbrt_) last 90 days and are replaced on every use. See OAuth.
  • Scopes. Eight scopes, from property:read to payments:write. Hotels see exactly what they allow; a call outside them answers 403. See Scopes.
  • The Apps directory. Apps that pass review are listed for every ChatBeds hotel. See Review and listing.
  • App webhooks. One webhook address and secret per app, for every connection that allowed reservations:read.
  • Free developer accounts. Sign up as a developer and get a Sandbox Hotel with rooms, rates, guests and a key, never billed. See The sandbox.

2026-10-06

Partner API v1

  • 20 operations: identity and properties, room types, rate plans, units, extras, policies, offers, reservations (create, get, search, modify, cancel, add an extra), folios, payments and payment links.
  • Bookings priced by the hotel's own pricing engine, with expected_total to catch price changes.
  • Idempotency-Key on every write.
  • Signed webhooks for reservation.created, reservation.modified and reservation.cancelled, with retries for about two days.
  • Rate limits of 120 calls a minute per key.

هل تبني شيئًا؟

في هذه الصفحة