Cisco PhoneOS for Collaboration Devices

Bookings Workspace Integration for PhoneOS

Overview

This guide explains how to build a workspace integration that manages meeting bookings on Cisco PhoneOS devices. Unlike the RoomOS implementation, PhoneOS (latest 3.6) supports local calendar workspaces only—there is no hybrid calendar connectivity yet. All booking interactions therefore occur directly between your integration and the devices via PhoneOS cloud xAPI.

If you are migrating from the RoomOS workflow, keep the overall architecture but remove any logic that expects hybrid calendar acknowledgments. The PhoneOS devices immediately reflect successful commands as local calendar updates.

Before you start

  • Review the PhoneOS xAPI surface at https://phoneos.cisco.com/xapi.
  • Ensure your integration is authorized to call the Bookings xAPI namespace for the target workspace.
  • Plan to persist correlation identifiers (BookingRequestUUID and MeetingId) so you can match asynchronous events to the user actions that triggered them.

Supported xAPIs on PhoneOS

TypexAPIPurpose
CommandxCommand Bookings BookCreate a new booking.
CommandxCommand Bookings DeleteRemove an existing booking by BookingRequestUUID.
CommandxCommand Bookings ListRetrieve the current booking list for the workspace.
EventxEvent Bookings BookingCreatedConfirms a booking was created; includes MeetingId and BookingRequestUUID.
EventxEvent Bookings StartIndicates a booking has begun.
EventxEvent Bookings EndIndicates a booking has ended.
EventxEvent Bookings DeletedConfirms a booking was deleted.
EventxEvent Bookings SyncRequiredSignals that the integration must refresh bookings via Bookings List.
StatusxStatus Bookings AvailabilityIndicates the booking status of a device and the related time if bookings exist.
StatusxStatus Bookings CurrentThe ID of the current active booking event. It's empty if no booking is in progress.

Note: Commands such as Bookings Edit, Bookings Extend, or hybrid calendar callbacks are not available on PhoneOS yet in 3.6. Keep your command set limited to the entries above.

Local calendar flow

Because PhoneOS supports only local calendars, every booking change is applied immediately on the device and synchronized across devices in the same workspace. The device responds to each command with an event so that your integration can verify success and update its own data store.

Creating a booking

  1. Generate a unique BookingRequestUUID for the new booking and call xCommand Bookings Book with the desired start/end times and participants.
  2. Listen for xEvent Bookings BookingCreated (success) or xEvent Bookings Deleted (failure cleanup). On success, persist the returned MeetingId for future reference.
  3. If your integration misses the BookingCreated event (for example, due to network issues), use xCommand Bookings List to reconcile and re-sync bookings.

Bookings book sequence diagram

Deleting a booking

  1. Call xCommand Bookings Delete with the BookingRequestUUID.
  2. Await xEvent Bookings Deleted to confirm removal. If the event does not arrive promptly, issue xCommand Bookings List to verify the booking state.

Bookings delete sequence diagram

Synchronizing calendar data

  • Monitor xEvent Bookings SyncRequired. When it fires, the device is telling you that its local cache may be out of date.
  • Immediately call xCommand Bookings List and reconcile the returned bookings with your records.
  • Consider scheduling periodic Bookings List calls to guard against missed events.

Start and end notifications

xEvent Bookings Start and xEvent Bookings End allow your integration to trigger notifications, analytics, or room preparation workflows. Tie these events back to the booking using the MeetingId provided with each event.

Handling error scenarios

  • Conflicting bookings: xCommand Bookings Book fails implicitly if the requested slot overlaps an existing booking. Detect this by checking the response payload or by monitoring for the absence of BookingCreated and the presence of SyncRequired.
  • Device restarts or connectivity loss: Expect a SyncRequired event after the device comes back online. Always reconcile with Bookings List before accepting further user actions.
  • Missing events: Maintain a retry policy—if no confirmation event arrives within a reasonable window, refresh with Bookings List and retry or alert the operator.

Additional resources