ChatBedsEntwickler
Hotel features API

Diese Seite ist noch nicht übersetzt. Sie lesen die englische Fassung.

Night mode and phone lines

Night mode hands the front desk to Ana by hours and wakes a person only for real problems. Phone lines let Ana answer calls on WhatsApp, a Twilio or Telnyx number, or a SIP line. The settings, the ID check, lines, calls and the carrier webhooks.

Night mode is a switch by hours (for example 23:00 to 07:00, hotel time) that hands the desk to Ana. Late guests check in online or at the reception tablet. Ana answers the phone, the tablet's call button and WhatsApp. She wakes the person on call only for real problems, as far up the ladder as the owner chose. In the morning the owners and managers get a report.

Phone lines let Ana answer calls: on the hotel's WhatsApp number, on a Twilio or Telnyx number, or on a SIP line from the hotel's phone system or a licensed operator. Each call is logged with a transcript and a tag, and goes into the inbox.

Night mode

Get night mode

GET/api/v1/night-mode
Permission: settings.manage or front_desk.operate
property_id uuid (query)required
The property.
200 OK
{
  "settings": {
    "enabled": true,
    "start": "23:00",
    "end": "07:00",
    "on_call": ["3d0c8a52-1f4e-4b7a-9c61-0e2f7b9d4a15"],
    "walkins": true,
    "id_rule": "remote",
    "keys": "instructions",
    "key_instructions": "Key box left of the door, code 4821.",
    "emergency_numbers": [{ "label": "Doctor on call", "number": "+92 300 1234567" }],
    "may_offer": ["A late check-out"],
    "remind_hours": 4,
    "ladder": {
      "housekeeping": "ana",
      "desk": "ana",
      "maintenance": "message",
      "complaint": "message",
      "noise": "message",
      "lockout": "call",
      "medical": "everyone",
      "fire": "everyone",
      "security": "everyone"
    }
  },
  "on_now": false,
  "tonight": { "night": "2026-10-21", "from": "23:00", "to": "07:00", "late_arrivals": 2 },
  "team": [{ "id": "3d0c8a52-1f4e-4b7a-9c61-0e2f7b9d4a15", "name": "Bilal", "role": "Manager", "whatsapp": true }],
  "problems": { "housekeeping": "Towels, pillows, cleaning", "lockout": "Locked out, or a key that doesn't work" },
  "levels": ["ana", "message", "call", "everyone"],
  "emergency": [{ "label": "Emergency", "number": "1122" }, { "label": "Doctor on call", "number": "+92 300 1234567" }],
  "key_system": false,
  "nights": [
    { "night": "2026-10-20", "on_call": ["3d0c8a52-1f4e-4b7a-9c61-0e2f7b9d4a15"], "reminded": 1,
      "report": { "arrivals": [], "walkins": 0, "problems": [], "open_problems": 0 }, "reported_at": "2026-10-21T02:00:11+00:00" }
  ]
}
FieldMeaning
on_nowNight mode is on and it is night at the hotel now
tonightThe next (or current) night: its date, hours in hotel time, and arrivals not yet checked in
teamThe hotel's active team. whatsapp: linked on WhatsApp, so they can be on call
problemsEvery kind of problem and its label (trimmed above)
emergencyThe numbers a guest sees at once in an emergency: the country's, the hotel's, then emergency_numbers
key_systemA key-card system is connected, so keys can be system
nightsThe last 14 nights: who was on call, how many late arrivals were reminded, and the morning report (arrivals, walk-ins, problems, calls, ID checks, money taken)

Change the settings

PUT/api/v1/night-mode/settings
Permission: settings.manage

property_id is a query parameter. Send only what changes. The answer is the whole night mode, as for GET.

enabled boolean
On or off. To turn it on, at least one person on call must be linked on WhatsApp.
start, end string
24-hour times in hotel time, like 23:00 and 07:00. They must differ.
on_call uuid[]
Up to 5 people from the hotel's team.
walkins boolean
Take walk-ins at night.
id_rule string
kiosk: the ID is checked at the tablet as by day. remote: the person on call approves the ID photo before the key is made.
keys string
system (the key-card system; it must be connected), on_call (the person on call) or instructions.
key_instructions string
Up to 500 characters. Needed with instructions: how guests get their key at night.
emergency_numbers object[]
Up to 6 of {"label", "number"} (40 and 24 characters).
may_offer string[]
Up to 8 things Ana may offer a guest for a problem, 120 characters each.
remind_hours integer
0 to 12. Hours before night mode starts that arrivals not checked in online get their stay link. 0: no reminder.
ladder object
For each problem (housekeeping, desk, maintenance, complaint, noise, lockout, medical, fire, security): ana (Ana handles it, it's in the report), message (the person on call on WhatsApp), call (also rings their phone) or everyone. medical, fire and security are always everyone.
Request
curl -X PUT "https://app.chatbeds.app/api/v1/night-mode/settings?property_id=6f1c3b2e-8a0d-4f5e-9b7a-2c3d4e5f6a7b" \
  -H "Authorization: Bearer $FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "start": "23:00", "end": "07:00", "on_call": ["3d0c8a52-1f4e-4b7a-9c61-0e2f7b9d4a15"], "id_rule": "remote", "ladder": {"noise": "call"}}'

The ID check

With id_rule remote, a guest checking in at night sends an ID photo from the tablet, and the person on call approves it.

GET/api/v1/night-mode/id-checks/{request_id}
Permission: front_desk.operate
200 OK
{
  "request_id": "9a4e2c10-7b3d-4f8a-8e51-2d6c0b9f3a77",
  "status": "open",
  "guest": "Sara Brown",
  "booking_name_matches": true,
  "room_type": "Deluxe",
  "arrival": "2026-10-21",
  "departure": "2026-10-23",
  "photo": "data:image/jpeg;base64,…",
  "details": { "full_name": "SARA BROWN", "nationality": "GBR" },
  "decided": null,
  "decided_by": null
}
POST/api/v1/night-mode/id-checks/{request_id}
Permission: front_desk.operate
approve booleanrequired
true: the guest finishes checking in at the tablet. false: the guest is asked to wait for someone, and no key is made.

The answer is the ID check, with decided (approved or refused) and decided_by. Deciding again changes nothing. 404 This isn't an ID check. for any other request.

Run the night's jobs now

POST/api/v1/night-mode/run
Permission: settings.manage

Runs now what the hourly job would: the late-arrival reminders, telling the people on call that night mode is on, and the morning report once the night has ended. property_id is a query parameter. The answer is the night mode, as for GET, with done: how many things were done.

Phone lines

Get lines and calls

GET/api/v1/voice
Permission: settings.manage or inbox.use
property_id uuid (query)required
The property.
200 OK
{
  "lines": [
    {
      "id": "c2f1e7a4-5b9d-4e3c-8a10-6f2d4b7e9c31",
      "route": "twilio",
      "number": "+14155550123",
      "sip_address": null,
      "answer": "no_answer",
      "desk_phone": "+14155550199",
      "ring_seconds": 20,
      "enabled": true,
      "ready": true,
      "last_call_at": "2026-10-21T01:14:02+00:00"
    }
  ],
  "routes": { "whatsapp": true, "twilio": true, "telnyx": false, "sip": true },
  "whatsapp_connected": true,
  "sip_domain": "chatbeds.sip.twilio.com",
  "calls": [
    {
      "id": "5e8d2b41-0c7a-4f69-b3e2-91a4d6c0f852",
      "route": "twilio",
      "caller": "+447700900123",
      "status": "ended",
      "tag": "booked",
      "tag_label": "Booked",
      "night": true,
      "summary": "Booked a Deluxe room for 12 to 14 Nov.",
      "seconds": 184,
      "transferred_to": null,
      "language": "en",
      "reservation_id": "a589df05-30ad-4ee5-9832-16ff6c2c1d0e",
      "started_at": "2026-10-21T01:14:02+00:00"
    }
  ],
  "by_tag": { "booked": 1 },
  "tags": { "booked": "Booked", "link_sent": "Booking link sent" }
}
FieldMeaning
lines[].routewhatsapp, twilio, telnyx or sip
lines[].sip_addressFor sip: the address the hotel's phone system or operator forwards to, <code>@<sip_domain>
lines[].answerWhen Ana answers: always, no_answer (the desk phone rings first for ring_seconds) or night (only in night mode; by day the call goes to the desk phone)
lines[].readyChatBeds' account for this route is set up on the server
routesWhich kinds of line can be added now
callsThe last 30 days, at most 100, newest first
calls[].tagbooked, link_sent, question, request, problem, emergency or missed_opportunity (asked about rooms and prices, and nothing came of it)
calls[].callerThe caller's number. Ana never reads it out

Add a line

POST/api/v1/voice/lines
Permission: settings.manage

property_id is a query parameter. The answer is the line.

route stringrequired
whatsapp, twilio, telnyx or sip.
number string
Required for twilio and telnyx: the number bought for the hotel, with its country code.
answer string
always (default), no_answer or night. no_answer and night need desk_phone, except on WhatsApp.
desk_phone string
The desk's phone number, with its country code.
ring_seconds integer
5 to 60. Default 20.
  • whatsapp needs the hotel's WhatsApp number connected, and turns on the call button on that number. Meta allows calls only on numbers it has cleared for calling.
  • sip makes a new sip_address for the line.

Change or remove a line

PATCH/api/v1/voice/lines/{line_id}
Permission: settings.manage

Takes answer, desk_phone, ring_seconds and enabled, and property_id as a query parameter. The answer is the line.

DELETE/api/v1/voice/lines/{line_id}
Permission: settings.manage

Answers {"removed": true}. Removing the WhatsApp line turns the call button off.

Get one call

GET/api/v1/voice/calls/{call_id}
Permission: settings.manage or inbox.use

The call as in the list, with transcript and actions (what Ana did during the call). property_id is a query parameter.

Errors

StatusdetailWhen
400Night mode hours are 24-hour times, like 23:00 and 07:00.
400Night mode needs at least one person on call who is linked on WhatsApp, …Turning it on without one
400Connect the key-card system first (Settings → Reception → Key cards).keys system with no key-card system
400An emergency always wakes everyone on call and the managers.medical, fire or security set below everyone
400Give the desk phone number: calls go there first (by day, or until nobody answers).
400The number: a phone number with its country code, like +92 300 1234567.
404Line not found.
409Phone lines of this kind aren't set up on ChatBeds yet. WhatsApp calls work now.The route isn't ready
409Connect the hotel's WhatsApp number first (Settings → WhatsApp).
409WhatsApp calls are already on for this hotel.
409That number is already a line at a hotel.
409WhatsApp didn't turn calls on: …Meta refused to turn calls on for the number

Carrier setup

This is for whoever runs the ChatBeds server. Hotels don't set any of this: their Twilio and Telnyx numbers are on ChatBeds' account.

Setting
TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKENChatBeds' Twilio account. Twilio signs its webhooks with the auth token
TELNYX_API_KEY, TELNYX_PUBLIC_KEYChatBeds' Telnyx account. Telnyx signs with Ed25519; the public key checks it
VOICE_SIP_DOMAINA Twilio SIP domain. SIP lines get <code>@VOICE_SIP_DOMAIN. Needs the Twilio settings too
PUBLIC_API_URLThe API's public address. Carriers sign the exact address they call
VOICE_MAX_CALL_MINUTESThe longest call. Default 15

Set the webhooks:

CarrierWhereAddress
TwilioEach number's voice webhook, and the SIP domain's voice URLPOST {PUBLIC_API_URL}/api/v1/voice/twilio/incoming
TelnyxA TeXML application for the numbersPOST {PUBLIC_API_URL}/api/v1/voice/telnyx/incoming
  • A request whose signature doesn't match (X-Twilio-Signature, or Telnyx's telnyx-signature-ed25519 with telnyx-timestamp, at most 5 minutes old) answers 403.
  • The answer is TwiML (TeXML for Telnyx) that connects the call's audio over wss:// to /api/v1/voice/twilio/stream or /api/v1/voice/telnyx/stream. Allow WebSockets, and a request timeout of at least VOICE_MAX_CALL_MINUTES.
  • WhatsApp calls need no carrier: subscribe the Meta app's webhook to the calls field as well as messages.
  • The ladder's call step rings the person on call from the hotel's Twilio line. With no Twilio line, they get the WhatsApp message only.

Sie bauen etwas?

Auf dieser Seite