Ctrl K
ring2all.com

Time Groups Module Documentation

Table of Contents

  1. Module Overview (Technical)
  2. Module Overview (Commercial/Business)
  3. Module Overview (End User/Administrator)
  4. Configuration Fields Reference
  5. Time Conditions
  6. Common Scenarios & Examples
  7. Limitations & Important Notes
  8. Troubleshooting Tips
  9. Glossary

---

1. Module Overview (Technical)

What Are Time Groups?

Time Groups define schedules (days and hours) that can be used to control time-based call routing. They are referenced by Time Conditions, which decide where to route calls based on whether the current time matches a Time Group.

Architecture

Plaintext
┌─────────────────────────────────────────────────────────────────┐
│                  Time-Based Routing System                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Time Group: "Business Hours"                                   │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ Schedule 1: Mon-Fri, 09:00 - 17:00                        │ │
│  │ Schedule 2: Sat, 10:00 - 14:00                            │ │
│  └────────────────────────────────────────────────────────────┘ │
│                          │                                      │
│  Referenced by:          ▼                                      │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ Time Condition: "Main Line Hours"                         │ │
│  │                                                            │ │
│  │ If MATCH (business hours):                                 │ │
│  │   → Route to Main IVR                                     │ │
│  │                                                            │ │
│  │ If NO MATCH (after hours):                                 │ │
│  │   → Route to After-Hours Voicemail                        │ │
│  │                                                            │ │
│  │ Override Toggle: *81                                      │ │
│  │                                                            │ │
│  └────────────────────────────────────────────────────────────┘ │
│                                                                 │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │                 time_condition.lua                         │ │
│  │                                                            │ │
│  │  1. Get current time                                       │ │
│  │  2. Query public.time_group_schedules                      │ │
│  │  3. Check if current time matches any schedule             │ │
│  │  4. Apply override if set                                  │ │
│  │  5. Route to match or no-match destination                 │ │
│  │                                                            │ │
│  └────────────────────────────────────────────────────────────┘ │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

TablePurpose
public.time_groupsTime group definitions
public.time_group_schedulesSchedule entries per group
public.time_conditionsRouting conditions using groups

Key Files

FileDescription
admin/apps/web/src/modules/timeGroups/Frontend module
admin/apps/web/src/i18n/en/timeGroups.jsonTranslations
telephony/freeswitch/lua/main/xml_handlers/time_condition/time_condition.luaCondition handler
telephony/freeswitch/lua/main/xml_handlers/routing/time_condition.luaRouting handler
---

2. Module Overview (Commercial/Business)

Business Value

Time Groups enable time-based call routing:

Without Time GroupsWith Time Groups
Same routing 24/7Business/after-hours
Manual IVR switchingAutomatic time routing
No holiday handlingHoliday schedules
Receptionist neededSelf-service navigation

Use Cases

  1. Business Hours Routing

- 9-5 → Main IVR

- After hours → Voicemail

  1. Lunch Break Handling

- 12-1pm → Different queue

- Lunch announcement

  1. Weekend Routing

- Sat-Sun → On-call extension

- Reduced staffing

  1. Holiday Schedules

- Closed days → Holiday message

- Specific date ranges

Feature Highlights

FeatureBenefit
Multiple SchedulesComplex time patterns
Day SelectionAny day combination
Date RangesCampaign/holiday limits
Override ToggleManual override via code
BLF IntegrationVisual status indication
Reusable GroupsShare across conditions
---

3. Module Overview (End User/Administrator)

What Can You Do?

Time Groups:
  • Create named schedule groups
  • Add multiple time ranges
  • Select days of week
  • Set start/end times
  • Optional date ranges

Time Conditions:
  • Reference Time Groups
  • Set match destination
  • Set no-match destination
  • Configure toggle code
  • Manual override

Administrator Workflow

Plaintext
┌─────────────────────────────────────────────────────────────────┐
│              Creating a Time Group                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Section: Time Group Information                                │
│  ├─ Group Name: "Business Hours"                               │
│  ├─ Description: "Standard Mon-Fri working hours"              │
│  └─ Enabled: ✓                                                 │
│                                                                 │
│  Section: Schedules                                             │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ Schedule 1                                                │  │
│  │ ├─ Days: [Mon] [Tue] [Wed] [Thu] [Fri]                   │  │
│  │ ├─ Start Time: 09:00                                     │  │
│  │ ├─ End Time: 17:00                                       │  │
│  │ └─ Date Range: (optional)                                │  │
│  └───────────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ Schedule 2                                                │  │
│  │ ├─ Days: [Sat]                                           │  │
│  │ ├─ Start Time: 10:00                                     │  │
│  │ └─ End Time: 14:00                                       │  │
│  └───────────────────────────────────────────────────────────┘  │
│  [+ Add Schedule]                                               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP
Multiple Schedules: Use separate schedules for different day/time combos.
TIP
Reuse Groups: One group can be used by multiple conditions.
CAUTION
Time Format: Use 24-hour format (09:00, 17:00).

---

4. Configuration Fields Reference

Time Group Fields

FieldDescriptionExample
Group NameUnique identifierBusiness Hours
DescriptionOptional notesMon-Fri 9-5
EnabledGroup activeOn/Off

Schedule Fields

FieldDescriptionExample
Days of WeekActive daysMon, Tue, Wed...
Start TimePeriod begins09:00
End TimePeriod ends17:00
Start DateOptional start2026-01-01
End DateOptional end2026-12-31

Day Selection

DayShort
Mondaymon
Tuesdaytue
Wednesdaywed
Thursdaythu
Fridayfri
Saturdaysat
Sundaysun
---

5. Time Conditions

What Are Time Conditions?

Time Conditions are the routing rules that use Time Groups. They define:

  • Which Time Group to evaluate
  • Where to route if time matches
  • Where to route if time doesn't match
  • Optional toggle code for manual override

Time Condition Configuration

FieldDescription
NameCondition identifier
Time GroupGroup to evaluate
Match DestinationRoute when time matches
No-Match DestinationRoute when time doesn't match
Toggle CodeFeature code for override (81)
StatusNormal / Override On / Override Off

Override Toggle

Users can dial a feature code to manually override the time condition:

  • 81 → Toggle between override_on and override_off
  • override_on: Always routes to match destination
  • override_off: Always routes to no-match destination

Plaintext
Normal mode: Routes based on schedule
   ↓
Dial *81 → Override ON (always match)
   ↓
Dial *81 → Override OFF (always no-match)
   ↓
Dial *81 → Normal mode

---

6. Common Scenarios & Examples

Scenario 1: Business Hours

Time Group: "Business Hours"
ScheduleDaysTime
1Mon-Fri09:00 - 17:00
Time Condition: "Main Line"
SettingValue
Time GroupBusiness Hours
Match DestinationMain IVR
No-Match DestinationAfter-Hours Voicemail

Scenario 2: Extended Weekend Hours

Time Group: "Extended Hours"
ScheduleDaysTime
1Mon-Fri08:00 - 18:00
2Sat10:00 - 14:00

Scenario 3: Lunch Break Routing

Time Group: "Lunch Break"
ScheduleDaysTime
1Mon-Fri12:00 - 13:00
Time Condition: "Lunch Handling"
SettingValue
Time GroupLunch Break
Match DestinationLunch Announcement
No-Match DestinationNormal Routing

Scenario 4: Holiday Closure

Time Group: "Holiday 2026"
ScheduleDaysStart DateEnd Date
1All2026-12-242026-12-26
2All2026-01-012026-01-01
---

7. Limitations & Important Notes

Technical Notes

NOTE
Timezone: Time evaluation uses server timezone.
WARNING
Schedule Overlap: Multiple schedules combine (OR logic).
WARNING
Override Priority: Override status takes precedence over schedules.

Best Practices

  1. Clear Names: Use descriptive names like "Business Hours"
  2. Group Reuse: Create generic groups for common patterns
  3. Test Schedules: Verify time matching works correctly
  4. Document Holidays: Keep holiday dates updated
  5. BLF Buttons: Use for quick override indication

---

8. Troubleshooting Tips

Common Issues

SymptomPossible CauseSolution
Wrong routingSchedule mismatchVerify time/day settings
Always one routeOverride activeCheck condition status
Time not matchingTimezone issueCheck server timezone
Group not foundNot enabledEnable time group

Diagnostic SQL

List time groups:

Sql
SELECT id, name, description, enabled
FROM public.time_groups
WHERE domain_id = [domain_id];

Check schedules:

Sql
SELECT g.name, s.day_of_week, s.start_time, s.end_time
FROM public.time_group_schedules s
JOIN public.time_groups g ON s.group_id = g.id
WHERE g.domain_id = [domain_id]
ORDER BY g.name;

Check time conditions:

Sql
SELECT name, status, destination_match_value, destination_nomatch_value
FROM public.time_conditions
WHERE 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

TermDefinition
Time GroupNamed collection of schedules
ScheduleDay/time range definition
Time ConditionRouting rule using a time group
MatchCurrent time within schedule
No-MatchCurrent time outside schedule
OverrideManual toggle to bypass schedule
Toggle CodeFeature code to switch override
---

Lua Script Status ✅

Fixed in This Session

ScriptStatus
time_condition.lua✅ Fixed: Changed from core.tenants, core.time_conditions, core.time_group_schedules to public.domains, public.time_conditions, public.time_group_schedules. Also fixed tenant_id to domain_id and update_at to updated_at.
Lua fixes applied!

---

Documentation last updated: January 2026*

AI Assistant

👋 Hello! I'm your Ring2All documentation assistant. I can help you find information about configuring and using the Ring2All PBX platform.

How can I help you today?