Automate holiday messaging and call routing with custom prompts for specific dates.

This script lets you play a custom holiday message based on the date before routing an incoming call. It uses the new 3CX V20 feature to trigger scripts for calls received on SIP trunks. Unlike the default single holiday prompt, this script allows a unique message for each holiday.

For example, on December 25th, callers might hear:
“Merry Christmas! Our offices are closed for the holiday. Normal operations will resume on December 26th.“

Before you enable the script, you first need to record custom prompts and link them to a department by going to “Office Hours” > “Office Holidays” and add your own custom prompt with the date and time when this holiday prompt should be played. Once configured, calls will be routed once the appropriate holiday message is played, highlighting the flexibility of Call Processing Scripts and the potential for further customization.

How the Holiday Prompt Script Works

  1. Check for Holidays: Confirms if the current date matches a pre-configured holiday.
  2. Play Prompt: Plays the holiday message corresponding to the date.
  3. Route the Call: Directs the call to the appropriate destination after playing the prompt.

How to Set Up the Play Holiday Prompts Script

  1. Log in to the Admin Console.
  2. Go to Integrations > Call Scripts.
  3. Select Add from Store and choose Play Holiday Prompts.
  4. Name the script for easy identification.
  5. Set the script to run Upon Receiving a Call on a Trunk.
  6. Assign the trunk where the script will be used.

How to Use the Script

  • Configure holidays in the system.
  • Record custom audio prompts for each holiday (e.g., Christmas, New Year, etc.).
  • Install and activate the script to ensure specific prompts play on their corresponding dates.

Script Functionality and Implementation

  • Implementation:
    • Uses the ExternalLine object and GetTimeBasedRoutingInfo function to check holiday status.
    • Plays the holiday prompt if configured, then routes the call.
  • Functionality:
    • Checks if a holiday applies to the call’s destination department.
    • If so, it plays the appropriate prompt before routing the call.

Example Script

DISCLAIMER! This script is for reference purposes only. For the latest version, download from the store.


#nullable disable
using CallFlow;
using System;
using System.Threading;
using System.Linq;
using System.Threading.Tasks;
using TCX.Configuration;
using TCX.PBXAPI;
using System.Collections.Generic;
namespace dummy
{
//this handler plays holiday prompt as specified for destination
public class PlayDestinationHolidayPromptBeforeRouting : ScriptBase {
//reference implementation of trunk routing.
DestinationStruct FindDefaultDestination(ExternalLine trunk, string callerID, string DID)
{
DestinationStruct retval = new();
string[] range;
foreach (var a in trunk.RoutingRules)
{
bool match = (a.Conditions.Condition.Type == RuleConditionType.BasedOnDID &&
(
a.Data == DID
|| (a.Data.StartsWith('*') && DID.EndsWith(a.Data[1..]))
))
||
(
a.Conditions.Condition.Type == RuleConditionType.BasedOnCallerID &&
a.Data.Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries)
.Any
(x =>
x == "*"
|| x == callerID
|| x.StartsWith('*') && callerID.EndsWith(x[1..])
|| x.EndsWith('*') && callerID.StartsWith(x[..^1])
|| x.StartsWith('*') && x.EndsWith('*') && callerID.Contains(x[1..^1])
|| ((range = x.Split("-", StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries)).Length == 2 ?
(range[0].Length == callerID.Length && range[1].Length == callerID.Length) && (range[0].CompareTo(callerID) <= 0 && range[1].CompareTo(callerID) >= 0) : false)
)
)
||
(a.Conditions.Condition.Type == RuleConditionType.ForwardAll);
if (match)
{
retval.CopyFrom(a.ForwardDestinations.OfficeHoursDestination);
break;
}
}
return retval;
}
public override async Task StartAsync()
{
if(MyCall.Caller.DN is ExternalLine externalLine && MyCall.IsInbound) //only from trunk
{
//get the inbound target
var defaultDestination = FindDefaultDestination(externalLine, MyCall.Caller.CallerID, MyCall.Caller.CalledNumber).Internal;
//if the destination is Internal
if (defaultDestination != null)
{
var timeBasedroute = defaultDestination.GetTimeBasedRoutingInfo();
//if destination is currently "on holiday" and holiday prompt is defined, we play it
if (timeBasedroute.reason == CallControlAPI.DivertReason.Holiday && !string.IsNullOrWhiteSpace(timeBasedroute.holiday?.HolidayPrompt))
{
await MyCall.AssureMedia()
.ContinueWith(x => MyCall.PlayPrompt(null, [timeBasedroute.holiday?.HolidayPrompt], PlayPromptOptions.Blocked))
.Unwrap();
}
}
}
return false;//we always return false to continue default trunk routing procedure.
}
}
}

Last updated
This blog was last updated 28 November 2024