A guest arrives after midnight and messages a hotel on WhatsApp or SMS asking whether their room is ready, or asking to extend a stay during night audit. Without Property Management System (PMS) context, an AI assistant may fall back to static FAQs, repeat questions, or attempt reservation or billing changes without the property’s rules or staff approval.
Reliable after-hours hotel guest message routing with PMS context separates read lookups from staff-owned actions: grant narrow read access to property setup, stay status, and room status, and route booking changes, billing disputes, and urgent incidents—safety, medical, or complaints—to on-duty staff.
This guide uses Oracle’s third-party OHIP docs for OPERA Cloud (Oracle is a third-party vendor, not an Insonl client). The same boundaries apply to any multi-property PMS wired to guest messaging and CRM solutions.
Map property lookup and access scope before connecting a bot
Multi-property groups break first on property resolution. Map the inbound channel (WhatsApp, SMS, webchat, or confirmation code) to the five values Oracle requires per hotel (Hotel Details): Production vs. Non-Production, Region, Tenant/Chain Code, Hotel ID (x-hotelid), and Enterprise ID. Production requires a separate application and x-app-key (Authentication).
OHIP APIs are server-to-server only—never call them from browsers or mobile apps (Direct Access). Put a Backend for Frontend (BFF) between your channel and OHIP. Send Authorization: Bearer <OAuth token>, x-hotelid, and x-app-key from the backend; supply x-hubid where hub-level multi-property access exists; use a GUID in X-Request-Id for tracing; and set X-Originating-Application when microservices share a proxy (Calling APIs; Property APIs).
Scope access before writing prompts. Admins with OHIPADMIN can use Module Level Access Control to enable only the OPERA modules the integration needs. Enforce read-only access in the routing backend by allowlisting the specific lookup operations and withholding write routes from the bot. Call /crm/v1/profiles/{profileId}?fetchInstructions=Indicators first, then request only populated blocks such as Communication, and use summaryInfo=true (for example on /roomTypes) where a summary suffices (CRM v1).
Read room status and guest service state without polling the PMS
Use getHousekeepingOverview (GET /hsk/v1/hotels/{hotelId}/housekeepingOverview) for point-in-time lookups. The paginated response (limit, offset, hasMore) includes roomId, roomType, frontOfficeStatus (Vacant or Occupied), housekeepingRoomStatus, and reservationStatusList (for example, NotReserved, Arrived, or DueOut), plus optional guestServiceRequest (for example, MakeUpRoom or DoNotDisturb), filterable by housekeepingRoomStatus or serviceRequestStatus (Housekeeping Status; Active Service Status; HSK v1).
Two OPERA Cloud rules constrain automated replies (Room Status Context; Room Management Controls):
- Property controls.
Clean(CL) andDirty(DI) are standard;Inspected(IP),Pickup(PU), andTurndowndepend on active OPERA Controls. When the Inspected Status control is active, OPERA marksInspectedrooms ready for check-in; when inactive, OPERA marksCleanrooms ready for check-in. Apply the property’s readiness rule before replying. OOvs.OS.OOblocks assignment and removes the room from available inventory, affecting RevPAR, average rate, and occupancy calculations.OSstays in inventory and can still be assigned in OPERA Cloud. Route either status to the front desk before confirming room readiness.
Do not poll getHousekeepingOverview per message; Oracle flags continuous GET polling as an anti-pattern (Property APIs). Feed a local cache from OHIP Streaming over WebSockets (not native webhooks; see Why Not WebHook):
- Use
UPDATE ROOM STATUSfor room status changes and normalize theROOM STATUSdetail to your cache’s values. UseNEW OUT OF ORDER,UPDATE OUT OF ORDER,NEW OUT OF SERVICE, andUPDATE OUT OF SERVICEfor maintenance dates and remarks (Room Status Updates; OO Updates; OS Updates). - For
GUEST SERVICE STATUS REQUEST, read theGUEST SERVICE REQUESTdetail and mapDo Not Disturb,Make Up Room, andNo Status Selectedto REST values (Service Status Context; Service Status Updates). - Subscribe to reservation events (
NEW RESERVATION,UPDATE RESERVATION,CHECK IN,CHECK OUT,CANCEL,NO SHOW,JOIN GUEST,SEPARATE GUEST FROM SHARE), paired withgetReservation(CRS Reservations).
OPERA Cloud Guest Messages stores reservation notices. Retrieve them via GET /rsv/v1/hotels/{hotelId}/guestMessages by reservationId or room (Get Guest Messages). Create a notice with POST /rsv/v1/hotels/{hotelId}/reservations/{reservationId}/guestMessages and deliveryStatus: "Nr" (undelivered); use PUT on the existing guest message to update status, for example to "Mr" (delivered) (Post Guest Message; RSV v1). Keep staff escalations in the staff queue.
Routing matrix: what PMS context answers vs. what goes to staff
Assign every after-hours intent to a deterministic rule before writing prompts:
| Request class | PMS read context | Automated action allowed | Escalation rule and owner |
|---|---|---|---|
| Property facts & room readiness | x-hotelid, Reserved/InHouse, roomId, housekeepingRoomStatus |
Answer policies; confirm assigned-room readiness after identity and property Inspected/Clean checks. |
Unverified guest, unassigned room, or Dirty/OO/OS → Night front desk. |
| Service flag or notice check | Verified InHouse, roomId, guestServiceRequest, getGuestMessages |
Confirm DoNotDisturb/MakeUpRoom or read pending notices. |
getReservation reports CheckedOut, housekeeping reports NotReserved, JOIN GUEST share ambiguity, or item delivery → Front desk / Housekeeping. |
| Reservation changes | Read-only Reserved, InHouse, NoShow, Cancelled via getReservation |
No PMS writes. Summarize request with verified ID and stay state. | All writes blocked (policy_blocked) → Night front desk / Reservations. |
| Urgent safety, medical, or security | Parallel best-effort x-hotelid, roomId, InHouse lookup |
Bypass AI dialogue. Trigger alert and local emergency instructions. | Alert staff immediately without waiting for the PMS lookup or model response (urgent_safety_medical) → Duty manager / Security / Night desk. |
| Complaints, defects, or billing | Verified stay status, roomId, active OO/OS events |
Acknowledge without promising moves, refunds, or waivers; attach snapshot. | Disputes/comps blocked (guest_complaint) → Night manager / Guest relations. |
Keep postReservation, putReservation, postCancelReservation, and deleteReservationPackage off the bot path (CRS to OPERA Cloud; RSV v1; Property APIs). Oracle’s CRS modification workflow removes package products before putReservation and re-adds non-room products. Unmatched profiles can be created automatically. Validate rate, room, market, source, and required cancellation reason codes against property configuration. For CRS card data, send only tokens; for payment API calls, use the environment owner’s allocated cashierId. Property APIs omit finalized End-of-Day results.
Deliver escalations where staff work. For morning reservation or billing queues, put the stop code in a Zendesk custom field and record verified PMS facts and guest claims separately in an internal comment (Zendesk handoff fields). For live WhatsApp, SMS, or webchat takeover by night staff, keep one thread and pass compact routing attributes (Twilio Flex handoff context).
Made-up example: after-hours routing record with PMS context
This JSON is a made-up example payload (not from a real hotel, guest, reservation, or Insonl client; all IDs, codes, rooms, and timestamps are invented). It shows the handoff emitted when an InHouse guest messages at 01:42 about a broken AC, requesting a room move and one-night extension:
{
"routingDecision": "escalate_night_desk",
"stopCode": "reservation_change_and_room_issue",
"safetyUrgent": false,
"property": {
"hotelId": "HCMC01",
"chainCode": "DEMOCHAIN"
},
"pmsVerified": {
"identityVerified": true,
"reservationId": "9041822",
"reservationStatus": "InHouse",
"roomId": "412",
"housekeepingRoomStatus": "Clean",
"frontOfficeStatus": "Occupied",
"guestServiceRequest": "DoNotDisturb",
"pmsSnapshotTime": "2026-11-22T01:42:08+07:00"
},
"guestClaimed": {
"summary": "Guest reports AC stopped cooling in room 412, requests immediate room move and one-night extension."
},
"actionsExecuted": [
"cache.resolve_property -> HCMC01",
"pms.getReservation -> 9041822 (InHouse, room 412)",
"cache.get_room_status -> Clean / Occupied / DoNotDisturb"
],
"pmsWritesAttempted": false
}
Splitting pmsVerified from guestClaimed flags DoNotDisturb on room 412 before staff call or send engineering, and confirms no write ran (pmsWritesAttempted: false).
Five OHIP integration traps to guard before going live
- Per-message OAuth tokens and mismatched keys. Cache the JWT and refresh two minutes before
exp(Authentication); per-call fetches are billable for partners (Property APIs). Use separate production and non-production app keys. For401, check the OAuth token and app key; for403, check the environment-specific key, hotel and user access, API subscription, and IP allowlist as applicable; setAccept: application/jsonfor406and requestContent-Type: application/jsonfor415(HTTP Errors). Treat response headers as case-insensitive (Response Headers). - Multi-threaded or misconfigured Streaming consumers. Use the
graphql-transport-wssubprotocol and one active, single-threaded consumer per gateway, chain code, and app key (Client Runtime; Streaming APIs). Buffer events before database writes because the stream is unthrottled (Streaming Best Practices). Send a non-billablepingevery 15 seconds (server closes at 30 seconds). On planned token refresh, sendcomplete, process in-flight events, wait for OHIP to close the socket, and leave at least 10 seconds before the nextsubscribe. Omitoffsetfor routine reconnects within 24 hours; supply the desired offset for replay, or the last received offset if disconnected over 24 hours (Broken Connections). Subscribe only when ready, and on authorized REST writes sendx-externalSystemwhen suppressing self-generated events (Streaming FAQs). - Treating
UPDATE ROOM STATUSas fullOO/OSdetail. It omitsBEGIN DATE,END DATE,REASON, andREPAIR REMARKS—subscribe to the dedicatedOO/OSevents too (Room Status Updates). - Quoting overnight folio balances. Financial postings finalize after End of Day, and Property APIs omit EOD results, ledger balances, and chart-of-accounts mappings (Property APIs). Escalate billing questions.
- Logging PII, medical details, or card numbers. Oracle retains operational API logs for one year in shared Oracle Cloud log stores (PII Logs). For CRS integrations, Oracle specifies tokenized payment information and says OPERA Cloud prevents storage or transmission of clear-text card data (CRS to OPERA Cloud). Redact payment numbers before LLM calls, keep medical details out of PMS requests, and run deterministic safety-keyword bypasses before model inference.
Audit your after-hours guest routing before connecting a PMS
Insonl is a Ho Chi Minh City engineering studio building custom CRM solutions and operational AI workflows. Map property lookups, PMS read/write boundaries, and overnight escalations with our free AI workflow audit (what an AI workflow audit covers).
The audit is free; work after it is charged separately.
Sources
- Oracle Hospitality / OPERA Cloud (third-party docs, not an Insonl client): OHIP, Hotel Details, Authentication, Calling APIs, Module Level Access Control, HTTP Errors, Response Headers, Property APIs, Streaming APIs, Streaming Best Practices, Broken Connections, Room Status Context, Housekeeping Status, Room Status Updates, OO Updates, OS Updates, Service Status Context, Active Service Status, Service Status Updates, Guest Messages, Get Guest Messages, Post Guest Message, OHIP Streaming, Why Not WebHook, Client Runtime, Streaming FAQs, CRS Reservations, CRS to OPERA Cloud, Direct Access, PII Logs, Room Management Controls
- Oracle Hospitality REST API specs (third-party GitHub): CRM v1, HSK v1, RSV v1
- Insonl: CRM Solutions, Free AI workflow audit, Zendesk handoff fields, Twilio Flex handoff context, AI workflow audit guide