Calendar and Scheduling

The Oquira Calendar module allows you to manage your team's schedules, define operator availability, and plan recurring events.

Event Types

Operator Availability Impact

Events of type break, closure, and unavailability affect operator availability in real-time. When an operator is listed in the attendees of such an event (or if the event has no attendees, making it organization-wide), they are considered unavailable for the duration of the event. This impacts:

• Queue assignment and ticket calling
• Operator availability indicators on the dashboard
• Automatic operator selection for VIP/offline tickets

Operator Restrictions

Operators have limited calendar permissions:

• Own events: Operators can create, edit, and delete events they created themselves (availability/unavailability events).
• Other events: Events created by managers or owners are read-only for operators. They can view the details but cannot modify or delete them.
• Active events: Once an event has started, operators can only edit the title and description — time, service, and attendee fields are locked.

Get Events

Get all calendar events for an organization within a date range.

GET /v1/business/calendar
X-API-Key: your_api_key_here

Create Event

Add a new event to the organization's calendar.

POST /v1/calendar/organization/{organizationId}
X-API-Key: your_api_key_here
Content-Type: application/json

{
  "title": "John's Shift",
  "description": "VIP Counter",
  "startDate": "2024-03-18T09:00:00Z",
  "endDate": "2024-03-18T18:00:00Z",
  "eventType": "shift",
  "serviceId": "ser_xyz...",
  "attendees": ["usr_abc123"],
  "color": "#2196F3"
}

Create Availability (Operator)

Operators can declare their own availability.

POST /v1/calendar/organization/{organizationId}/availability
X-API-Key: your_api_key_here
Content-Type: application/json

{
  "title": "Available morning",
  "startDate": "2024-03-20T08:00:00Z",
  "endDate": "2024-03-20T12:00:00Z"
}

Note: This route uses the CALENDAR_CREATE_OWN_AVAILABILITY permission which allows operators to manage only their own availability events.

Update Event

PATCH /v1/calendar/{eventId}
X-API-Key: your_api_key_here
Content-Type: application/json

{
  "title": "John's Shift (modified)",
  "endDate": "2024-03-18T17:00:00Z"
}

Delete Event

DELETE /v1/calendar/{eventId}
X-API-Key: your_api_key_here

Recurring Events

Recurring events are automatically expanded to individual occurrences when retrieved. For example, a daily shift will create an occurrence for each day in the requested range.

Supported Recurrence Patterns

POST /v1/calendar/organization/{organizationId}
X-API-Key: your_api_key_here
Content-Type: application/json

{
  "title": "Lunch Break",
  "startDate": "2024-03-01T12:00:00Z",
  "endDate": "2024-03-01T14:00:00Z",
  "eventType": "break",
  "recurrencePattern": "daily"
}