Automating Holiday Schedules in 3CX

Introduction

This document provides a comprehensive guide for configuring holiday announcements and call routing within 3CX. It details two primary methods for managing holiday call flows: centralized department-based holiday schedules and the holiday.cs call script.

  • Department-based holiday schedules allow administrators to define holidays and their associated prompts at a departmental level. These schedules can then be automatically applied to various endpoints, including Queues, IVRs, Ring Groups, and Department Call Handling, streamlining maintenance and ensuring consistent holiday messaging across the system.
  • The holiday.cs call script offers highly customizable call flow logic for more advanced or specific routing requirements.

Department-Based Holiday Schedules

This functionality allows you to define holidays and associated prompts at the department level, which can then be dynamically applied to multiple endpoints.

Configuration Steps

  • Step 1: Create or Select a Department: Before defining holidays, ensure you have a department configured in 3CX. If you don’t have one, you’ll need to create it.
  • Navigate to Admin > Departments.
  • Choose an existing department or click + Add to create a new one.

  • Step 2: Define Office Holidays for the Department: Once you have a department, you can define specific holidays and their associated announcements.
  • Go to Admin > Office Hours.
  • Select the relevant Department (e.g., "Italy Office").
  • Click on the Office Holidays tab.
  • Click + Add to define a new holiday.
  • Enter a Name for the holiday (e.g., "Xmas").
  • Specify the Date for the holiday (e.g., "25 December").
  • Upload or select an existing prompt message to be played during this holiday (e.g., "We are closed on Christmas day."). This prompt will be centrally attached to the holiday.

  • Step 3: Assign Department Holiday Schedule to an Endpoint: Finally, configure your desired endpoints to utilize the department’s holiday schedule.
  • Edit the specific endpoint (e.g., a Queue, Ring Group, IVR, or the Department’s own Call Handling settings).
  • Locate the "When on holiday route to" option.
  • Switch this option to e.g. "End Call" or any other destination except the default "Accept anyway".
  • This action unlocks further holiday announcement options.
  • Enable the "Play Announcement" toggle.
  • A new drop-down menu will appear, listing the available prompts.
  • Select "Play department holiday prompt".

The endpoint’s holiday route will now dynamically resolve the announcement from the active Department Holiday, while keeping its normal destination.

How Department-Based Holiday Schedules Work

When an endpoint (such as a Queue, IVR, Ring Group, or Department’s Call Handling) is configured to use the "Play department holiday prompt" option, it will automatically check the active department’s defined office holidays. If a holiday is active, the system will play the associated holiday announcement and follow the configured holiday routing. This eliminates the need to manually update prompts or rules on each endpoint for every holiday.

Using the holiday.cs Call Script

The holiday.cs call script is an existing feature that provides advanced holiday routing capabilities for specific scenarios that may not be covered by the department-based schedules.

The holiday.cs script allows for highly customized call flow logic based on specific dates or conditions. It can be modified to implement unique routing requirements, such as different prompts for different DIDs on the same holiday, or complex conditional routing.

Configuration Steps

  • Step 1: Create a Holiday
  • Navigate to Admin > Office Hours.
  • Select the relevant department and click on the Office Holidays tab.
  • Add a new holiday with a unique name (example: National Day).
  • Step 2: Prepare the Holiday Prompt
  • Record or create an audio file (.wav format) for the holiday prompt (Example: nationalday.wav) and upload it.
  • Step 3: Create a Call Processing Script in 3CX
  • Login to your Admin Console, go to Admin > Integrations > Call Scripts.
  • Click Add from Store.
  • Select holiday.cs.

  • Enter a name for the Call script (should contain lowercase characters only with no spaces).
  • Select how you want this script to be launched via the "Run this script" option. For example, choose Upon receiving a call on a trunk.
  • Assign the script to the desired SIP trunk.
  • Select a Department of your choice.
  • Click OK to proceed. This will redirect you to the code editor page, which will automatically compile the script.

  • The contents of the C# code will be loaded in the code editor.
  • Press Save to save the script and compile the code.

When compilation is successful, the script will be launched when an incoming call is detected on any DID of the assigned trunk.

How the holiday.cs Call Script Works

  • When a call comes in on the assigned SIP trunk, the script is triggered.
  • The script checks if the current date matches any of the holidays you’ve defined.
  • If a match is found, the script plays the holiday audio prompt you created in Step 2.
  • If the day falls on a holiday, the call is routed to the holiday destination.

When to Use Which Option

Department-Based Holiday Schedules

  • Recommended for: Most standard holiday routing scenarios where a consistent holiday announcement and routing apply to multiple endpoints within a department.
  • Benefits: Simplicity, centralized management, reduced manual effort, dynamic application of holiday rules.
  • Use when: You want to define a holiday once for a department and have all associated Queues, IVRs, and Ring Groups automatically play the correct holiday prompt and follow the holiday routing.

holiday.cs Call Script

  • Recommended for: Advanced or highly specific holiday routing requirements that cannot be met by the department-based schedules. This includes custom logic for DIDs routed to Users or specific call flow modifications (e.g., ending a call after a prompt or excluding specific DIDs).
  • Benefits: High flexibility, custom logic, granular control over call flow.
  • Use when: You need to implement unique routing based on specific DIDs, complex time-based conditions, or integrate with external systems for holiday information. This method requires familiarity with call script editing.
  • Example scenario: You want holiday routing to apply to specific DIDs before the call reaches an IVR or Queue, so you can control holiday behavior at the entrance level

Do Not Use Both on the Same Call Path

Avoid using both holiday.cs and endpoint-level holiday prompts on the same call path. If both are enabled, the caller may hear the holiday announcement twice: once from the call script and once again from the endpoint.

Choose one method per call flow:

  • use endpoint-level holiday prompts for simple IVR, Queue, Ring Group, or Department holiday announcements
  • use holiday.cs when you need advanced trunk, DID, caller ID, or entrance-level control and when you want something to occur before the call reaches the endpoint

See Also

Last Updated

This document was last updated 10 September 2026

https://www.3cx.com/docs/holiday-prompts/