Time Conditions Module Documentation

Module Overview (Technical)
Module Overview (Commercial/Business)
Module Overview (End User/Administrator)
Configuration Fields Reference
Status Modes
Common Scenarios & Examples
Limitations & Important Notes
Troubleshooting Tips
Glossary

---

1. Module Overview (Technical)

What Are Time Conditions?

Time Conditions are routing rules that evaluate whether the current time matches a Time Group's schedule. Based on the result, calls are routed to either a "match" destination or a "no-match" destination.

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                  Time Condition Flow                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Inbound Route → Time Condition: "Business Hours Check"        │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                time_condition.lua                        │   │
│  │                                                          │   │
│  │  1. Load condition from public.time_conditions           │   │
│  │  2. Check status (default, forced-match, forced-nomatch) │   │
│  │  3. If default: evaluate Time Group schedules            │   │
│  │  4. If forced: use override status                       │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ├── MATCH ──────────────────────────────────────────────► │
│       │   Route to: Main IVR                                   │
│       │                                                         │
│       └── NO MATCH ───────────────────────────────────────────► │
│           Route to: After-Hours Voicemail                      │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Relationship with Time Groups

Plaintext

┌─────────────────────┐     ┌─────────────────────┐
│    Time Group       │     │   Time Condition    │
│  "Business Hours"   │◄────│  "Main Line Hours"  │
│                     │     │                     │
│  Mon-Fri 9:00-17:00 │     │  Match → Main IVR   │
│  Sat 10:00-14:00    │     │  No Match → VM      │
└─────────────────────┘     │  Toggle: *81        │
                            └─────────────────────┘

Key Tables

Table	Purpose
`public.time_conditions`	Condition definitions
`public.time_groups`	Referenced time groups
`public.time_group_schedules`	Schedule entries

Key Files

File	Description
`admin/apps/web/src/modules/timeConditions/`	Frontend module
`admin/apps/web/src/i18n/en/timeConditions.json`	Translations
`telephony/freeswitch/lua/main/xml_handlers/time_condition/time_condition.lua`	Main handler
`telephony/freeswitch/lua/main/xml_handlers/routing/time_condition.lua`	Routing handler

---

2. Module Overview (Commercial/Business)

Business Value

Time Conditions enable smart time-based routing:

Without Time Conditions	With Time Conditions
Manual route switching	Automatic time routing
24/7 same experience	Business/after-hours
Staff always needed	Self-service after hours
No holiday handling	Automatic holiday routing

Use Cases

Business/After-Hours

- Business hours → Main menu

- After hours → Voicemail

Holiday Routing

- Holiday → Closed message

- Normal days → Standard routing

Lunch Break

- Lunch hour → Reduced staffing queue

- Normal hours → All agents

Weekend Support

- Weekdays → Full support

- Weekends → On-call only

Feature Highlights

Feature	Benefit
Time Group Reference	Reusable schedules
Match/No-Match Routing	Dual destination
Toggle Override	Manual control (code)
BLF Integration	Visual status on phones
Auth PIN	Protected toggle
Multiple Destination Types	Extension, IVR, Queue, etc.

---

3. Module Overview (End User/Administrator)

What Can You Do?

Create time conditions
Link to Time Groups
Set match destination (during scheduled time)
Set no-match destination (outside scheduled time)
Configure toggle feature code
Set override status
Enable BLF indication

Administrator Workflow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              Creating a Time Condition                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Section: General Information                                   │
│  ├─ Condition Name: "Business Hours Check"                     │
│  ├─ Description: "Routes based on business hours"              │
│  ├─ Time Group: Business Hours                                 │
│  ├─ Context: tc_business_hours (auto-generated)                │
│  └─ Enabled: ✓                                                 │
│                                                                 │
│  Section: Routing Configuration                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ On Match Destination (During Schedule):                   │  │
│  │ ├─ Type: IVR                                              │  │
│  │ └─ Value: Main Menu                                       │  │
│  └───────────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ On No Match Destination (Outside Schedule):               │  │
│  │ ├─ Type: Voicemail                                        │  │
│  │ └─ Value: General Mailbox                                 │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  Section: Override Settings                                     │
│  ├─ Toggle Code: *81                                           │
│  ├─ Auth PIN: 1234 (optional)                                  │
│  ├─ Status: Default (Auto)                                     │
│  └─ BLF Inverted: Off                                          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP

Use Descriptive Names: "Business Hours Check" is clearer than "TC1".

TIP

Toggle Code Convention: Use 81, 82, etc. for easy reference.

CAUTION

Always Set Both Destinations: Ensure match AND no-match are configured.

---

4. Configuration Fields Reference

General Fields

Field	Description	Example
Condition Name	Unique identifier	`Business Hours Check`
Description	Optional notes	`Routes during work hours`
Time Group	Schedule to evaluate	Business Hours
Context	Dialplan context	`tc_business_hours`

Routing Fields

Field	Description
On Match Module	Destination type when matched
On Match Value	Specific destination
On No Match Module	Destination type when not matched
On No Match Value	Specific destination

Destination Types

Type	Description
Extension	Route to extension
IVR	Route to IVR menu
Ring Group	Route to ring group
Queue	Route to call queue
Voicemail	Route to voicemail
Hangup	Terminate call

Override Fields

Field	Description	Default
Toggle Code	Feature code to toggle	None
Auth PIN	PIN for toggle protection	None
Status	Current override status	Default
BLF Inverted	Invert BLF indication	Off

---

5. Status Modes

Status Options

Status	Behavior
Default (Auto)	Evaluate Time Group schedules
Forced Match	Always route to match destination
Forced No Match	Always route to no-match destination

Toggle Flow

Plaintext

Status: Default (Auto) ──[Dial *81]──► Forced Match
                                            │
                                      [Dial *81]
                                            │
                                            ▼
                                      Forced No Match
                                            │
                                      [Dial *81]
                                            │
                                            ▼
                                      Default (Auto)

BLF Integration

Status	BLF State	BLF Inverted
Default	Off	On
Forced Match	On	Off
Forced No Match	On	Off

---

6. Common Scenarios & Examples

Scenario 1: Business Hours Routing

Time Condition: "Main Line Hours"

Field	Value
Time Group	Business Hours (Mon-Fri 9-5)
Match Destination	Main IVR
No-Match Destination	After-Hours Voicemail
Toggle Code	81

Result:

9am-5pm weekdays → Main IVR
After hours → After-Hours Voicemail
User dials 81 → Override toggle

Scenario 2: Holiday Closure
Time Condition: "Holiday Check"
Field Value
Time Group Holidays 2026
Match Destination Holiday Announcement
No-Match Destination (continue to next TC)
Scenario 3: Emergency Override
Time Condition: "Emergency Open"
Field Value
Time Group Always Closed
Match Destination Hangup
No-Match Destination Emergency Queue
Toggle Code 99
Auth PIN 5678
Use case: Toggle 99 to force-open during emergencies.
---

7. Limitations & Important Notes

Technical Notes

NOTE
Timezone: Evaluation uses server timezone.

WARNING
Context Conflict: Ensure context names are unique.

WARNING
Missing Time Group: Condition fails if group is deleted.

Best Practices

Name Clearly: Use descriptive condition names

Set Both Destinations: Always configure match AND no-match

Use Toggle Codes: Enable quick override access

Protect with PIN: Secure important toggles

Test Thoroughly: Verify routing at different times

Document Overrides: Track who has toggle access

---

8. Troubleshooting Tips

Common Issues

Symptom Possible Cause Solution
Always same route Forced status active Check status setting
Time not matching Wrong time group Verify time group schedules
Toggle not working Wrong toggle code Check toggle code format
PIN rejected Wrong PIN Verify auth PIN
Condition not found Context mismatch Check context registration
Diagnostic SQL
List time conditions:
Sql
SELECT id, name, status, destination_match_module, destination_match_value, destination_nomatch_module, destination_nomatch_value FROM public.time_conditions WHERE domain_id = [domain_id];

Check condition with time group:
Sql
SELECT tc.name as condition, tg.name as time_group, tc.status FROM public.time_conditions tc LEFT JOIN public.time_groups tg ON tc.group_id = tg.id WHERE tc.domain_id = [domain_id];

FreeSWITCH Logs

Bash
# Check time condition evaluation grep "Time Condition" /var/log/freeswitch/freeswitch.log grep "time_condition.lua" /var/log/freeswitch/freeswitch.log

---

9. Glossary

Term Definition
Time Condition Routing rule evaluating time groups
Match Current time within schedule
No-Match Current time outside schedule
Toggle Code Feature code to override status
Forced Status Manual override (match/no-match)
BLF Busy Lamp Field - phone status light
Context Dialplan identifier
---
Lua Script Status ✅

Already Fixed (in Time Groups Task)

Script Status
time_condition.lua ✅ Uses public.domains, public.time_conditions, public.time_group_schedules (fixed from core. schema)
No additional Lua fixes needed!
---
Documentation last updated: January 2026

Field	Value
Time Group	Holidays 2026
Match Destination	Holiday Announcement
No-Match Destination	(continue to next TC)

Field	Value
Time Group	Always Closed
Match Destination	Hangup
No-Match Destination	Emergency Queue
Toggle Code	99
Auth PIN	5678

Symptom	Possible Cause	Solution
Always same route	Forced status active	Check status setting
Time not matching	Wrong time group	Verify time group schedules
Toggle not working	Wrong toggle code	Check toggle code format
PIN rejected	Wrong PIN	Verify auth PIN
Condition not found	Context mismatch	Check context registration

Term	Definition
Time Condition	Routing rule evaluating time groups
Match	Current time within schedule
No-Match	Current time outside schedule
Toggle Code	Feature code to override status
Forced Status	Manual override (match/no-match)
BLF	Busy Lamp Field - phone status light
Context	Dialplan identifier

Time Conditions Module Documentation

Table of Contents

1. Module Overview (Technical)

What Are Time Conditions?

Architecture

Relationship with Time Groups

Key Tables

Key Files

2. Module Overview (Commercial/Business)

Business Value

Use Cases

Feature Highlights

3. Module Overview (End User/Administrator)

What Can You Do?

Administrator Workflow

Quick Tips

4. Configuration Fields Reference

General Fields

Routing Fields

Destination Types

Override Fields

5. Status Modes

Status Options

Toggle Flow

BLF Integration

6. Common Scenarios & Examples

Scenario 1: Business Hours Routing

Scenario 2: Holiday Closure

Scenario 3: Emergency Override

7. Limitations & Important Notes

Technical Notes

Best Practices

8. Troubleshooting Tips

Common Issues

Diagnostic SQL

FreeSWITCH Logs

9. Glossary

Lua Script Status ✅

Already Fixed (in Time Groups Task)