Calendar API & Business Hours

Manage contact center schedules and integrate with NICE CXone Studio

Introduction

The Calendar API is a powerful tool for managing your contact center's business hours and holidays. By centralizing schedule management, you can ensure consistent handling of business hours across all your customer touchpoints. The API integrates seamlessly with NICE CXone Studio, allowing you to automate schedule-based routing and messaging without manual updates.

Whether you need to set regular operating hours, manage seasonal schedules, or handle unexpected closures, our Calendar API provides a simple yet flexible solution for contact centers of all sizes.

Pro Tool

Advanced Calendar API features are available exclusively with a Pro subscription. Free users can access basic schedule management functionality.

Key Features

Business Hours Management

Define regular operating hours for each day of the week with support for multiple time ranges per day. Set different schedules for different departments or service lines.

Holiday Calendar

Create and manage holidays, special events, and temporary closures. Choose from a pre-populated list of common holidays or add custom dates specific to your business.

Real-time Status API

Check current open/closed status in real-time with a simple API call. Get time remaining until next status change, upcoming holidays, and detailed schedule information.

Studio Integration

Integrate directly with NICE CXone Studio to automate call routing based on business hours. Automatically route calls to after-hours messaging or alternate queues when outside operating hours.

Calendar Import/Export

Import business hours and holidays from external calendar systems like Google Calendar, Outlook, or iCal feeds. Export your schedule to standard calendar formats for sharing with other systems.

Multiple Locations Support

Manage different schedules for multiple locations or departments. Support for different time zones and region-specific holidays across your global operations.

Getting Started

Follow these steps to set up and use the Calendar API:

1. Configure Your Calendar

Set up your business schedule:

  • Navigate to Calendar API in your CX Tools dashboard
  • Define your regular business hours for each day of the week
  • Add holidays and special events to your calendar
  • Configure time zone settings for your schedule
  • Optionally set up multiple schedules for different departments

2. Generate API Key

Create an API key to access your calendar data:

  • Go to the Settings tab in the Calendar tool
  • Click "Generate API Key"
  • Copy and securely store your API key
  • Configure permissions and access restrictions if needed
  • Set up your custom API endpoint URI (Pro feature)

3. Integrate with Studio

Connect your calendar to NICE CXone Studio:

  • In Studio, create a new Web Services node or use an existing one
  • Configure the node to call the Calendar API status endpoint
  • Add your API key to the authorization header
  • Create branches based on the "isOpen" response value
  • Route calls differently based on open/closed status
  • Optionally use additional data like "nextStatusChange" for messaging

4. Test and Monitor

Verify and maintain your integration:

  • Use the testing tool to verify your API endpoint is working correctly
  • Test different times and dates to confirm proper status changes
  • Set up API usage monitoring to track calls (Pro feature)
  • Configure alerts for issues or failed API calls
  • Review the API logs to troubleshoot any issues

API Reference

Status Endpoint

GET /api/calendar/status/{your-uri}

Returns the current status of your business hours: 

{
  "isOpen": true,
  "currentTime": "2023-06-30T14:25:30-04:00",
  "nextStatusChange": "2023-06-30T17:00:00-04:00",
  "nextStatus": "closed",
  "timeRemaining": {
    "hours": 2,
    "minutes": 34,
    "seconds": 30
  },
  "timezone": "America/New_York",
  "holidayToday": false
}

Holidays Endpoint

GET /api/calendar/holidays/{your-uri}

Returns upcoming holidays and special events: 

{
  "holidays": [
    {
      "name": "Independence Day",
      "date": "2023-07-04",
      "isFullDay": true
    },
    {
      "name": "Company Event",
      "date": "2023-07-15",
      "isFullDay": false,
      "hours": {
        "closed": [
          {
            "start": "13:00:00",
            "end": "17:00:00"
          }
        ]
      }
    }
  ],
  "upcomingCount": 2,
  "nextHoliday": {
    "name": "Independence Day",
    "date": "2023-07-04",
    "daysUntil": 4
  }
}

Schedule Endpoint

GET /api/calendar/schedule/{your-uri}

Returns your full business hour schedule: 

{
  "schedule": {
    "monday": [
      {
        "open": "09:00:00",
        "close": "17:00:00"
      }
    ],
    "tuesday": [
      {
        "open": "09:00:00",
        "close": "17:00:00"
      }
    ],
    "wednesday": [
      {
        "open": "09:00:00",
        "close": "17:00:00"
      }
    ],
    "thursday": [
      {
        "open": "09:00:00",
        "close": "17:00:00"
      }
    ],
    "friday": [
      {
        "open": "09:00:00",
        "close": "16:00:00"
      }
    ],
    "saturday": [],
    "sunday": []
  },
  "timezone": "America/New_York",
  "effectiveDate": "2023-06-01"
}

Example Use Cases

After-Hours Call Routing

Scenario: Automatically route calls to voicemail or an after-hours message when your contact center is closed. 

// Studio code example (pseudocode)
var response = WebServices.Call("GET", "https://cxtools.xyz/api/calendar/status/your-company")
var isOpen = response.isOpen

if (isOpen) {
    // Route to normal queue
    RouteCall("main-queue")
} else {
    // Get time until opening
    var nextStatus = response.nextStatus
    var timeRemaining = response.timeRemaining
    
    if (nextStatus == "open") {
        // Play closed message with time until opening
        PlayPrompt("We're currently closed. We will open in " + 
                   timeRemaining.hours + " hours and " + 
                   timeRemaining.minutes + " minutes.")
    } else {
        // Play general closed message
        PlayPrompt("We're currently closed. Please call back during regular business hours.")
    }
    
    // Route to voicemail
    RouteCall("voicemail")
}

Holiday Announcements

Scenario: Inform customers about upcoming holidays or special hours before they reach an agent. 

// Studio code example (pseudocode)
var response = WebServices.Call("GET", "https://cxtools.xyz/api/calendar/holidays/your-company")
var hasUpcoming = (response.upcomingCount > 0)

if (hasUpcoming && response.nextHoliday.daysUntil < 7) {
    // Announce upcoming holiday
    PlayPrompt("Please note that we will be closed on " + 
               response.nextHoliday.date + " for " + 
               response.nextHoliday.name)
}

// Continue with regular call flow
ContinueCallFlow()

Best Practices

API Usage

Optimizing your Calendar API implementation:

  • Cache API responses when appropriate
  • Implement retry logic for failed API calls
  • Set up monitoring for API usage
  • Keep your API key secure
  • Use HTTPS for all API requests
  • Set up alerts for schedule changes
  • Test your integration thoroughly

Schedule Management

Tips for effective calendar maintenance:

  • Plan holidays well in advance
  • Establish a regular schedule update process
  • Document special schedules
  • Test schedule changes before they go live
  • Maintain emergency override procedures
  • Regularly audit your calendar for accuracy
  • Set up notifications for calendar updates

Studio Integration

Best practices for NICE CXone Integration:

  • Set appropriate timeout values for API calls
  • Implement fallback logic for API failures
  • Cache schedule data when appropriate
  • Use a dedicated Web Services node for calendar checks
  • Set up error notifications
  • Test all branches of your call flow
  • Document API integration points

Advanced Configuration

Pro tips for complex implementations:

  • Use multiple calendars for different departments
  • Implement progressive disclosure of near-closing warnings
  • Configure emergency override capabilities
  • Set up automatic imports from corporate calendars
  • Create custom notifications for schedule changes
  • Implement A/B testing for after-hours messaging
  • Develop custom reporting on schedule adherence

Frequently Asked Questions

How often is the calendar data updated?

Calendar data is updated in real-time. Any changes you make to your business hours or holidays are immediately reflected in API responses. There is no delay or caching on our end, ensuring that your IVR systems always have the most up-to-date information about your operating hours.

Can I manage different schedules for multiple locations?

Yes, Pro users can create separate calendars for different locations, departments, or service lines. Each calendar gets its own API endpoint and can have unique business hours, holidays, and settings. This allows you to route calls differently based on which location or department the caller is trying to reach.

What happens if the API is unavailable?

While our API maintains 99.9% uptime, we recommend implementing fallback logic in your Studio scripts. If the API call fails, your script can default to a specific behavior (such as routing to live agents during expected business hours). Pro users can also set up redundant endpoints and notification alerts for any API disruptions.

Can I import holidays from external calendar systems?

Yes, our Calendar API supports importing holidays and business hours from external calendar systems including Google Calendar, Microsoft Outlook/365, and any system that provides iCal format exports. Pro users can configure automatic syncing to keep calendars updated from corporate scheduling systems.

Related Documentation

Studio Tools

Explore other tools for enhancing your NICE CXone Studio implementation.

API Keys

Learn how to manage API keys for secure access to CX Tools services.

IVRchitect AI

Integrate calendar status checks into your AI-generated IVR flows.

Format Converter

Convert calendar data between different formats for integration with other systems.