---
title: "Time Conditions Module Documentation"
description: "Documentation for Time Conditions"
---

## Table of Contents
1. [Navigation & Access](#navigation--access)
2. [Screenshots & Visual Interface](#screenshots--visual-interface)
3. [Module Overview (Technical)](#1-module-overview-technical)
4. [Module Overview (Commercial/Business)](#2-module-overview-commercialbusiness)
5. [Module Overview (End User/Administrator)](#3-module-overview-end-useradministrator)
6. [Configuration Fields Reference](#4-configuration-fields-reference)
7. [Status Modes](#5-status-modes)
8. [Common Scenarios & Examples](#6-common-scenarios--examples)
9. [Model Context Protocol (MCP) AI Integration](#7-model-context-protocol-mcp-ai-integration)
10. [Limitations & Important Notes](#8-limitations--important-notes)
11. [Troubleshooting Tips](#9-troubleshooting-tips)
12. [Glossary](#10-glossary)
---

## Navigation & Access

To access the Time Conditions module:
1. Log in to the Ring2All Web Portal.
2. In the left navigation sidebar, expand **PBX Engine**.
3. Under **Incoming Call Tools**, click **Time Conditions** (`/pbx/incoming-tools/time-conditions`).

---

## Screenshots & Visual Interface

### Time Conditions Overview
Displays all time condition policies, associated time groups, current active status, toggle feature codes, and action controls.
![Time Conditions List View](/screenshots/pbx/incoming-tools/time-conditions-list.png)

### Time Condition Configuration Form
Configures condition name, time group association, match destination (e.g. IVR), no-match destination (e.g. voicemail/extension), and BLF toggle override code.
![Time Condition Configuration Form](/screenshots/pbx/incoming-tools/time-conditions-form.png)

---

## 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

```
┌─────────────────────────────────────────────────────────────────┐
│                  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

```
┌─────────────────────┐     ┌─────────────────────┐
│    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        │
                            └─────────────────────┘
```

---

## 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

1. **Business/After-Hours**
   - Business hours → Main menu
   - After hours → Voicemail

2. **Holiday Routing**
   - Holiday → Closed message
   - Normal days → Standard routing

3. **Lunch Break**
   - Lunch hour → Reduced staffing queue
   - Normal hours → All agents

4. **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

```
┌─────────────────────────────────────────────────────────────────┐
│              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

```
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. Model Context Protocol (MCP) AI Integration

Ring2All exposes native Model Context Protocol (MCP) tools for **Time Conditions**, allowing AI agents and PBX Copilots to inspect active business schedule routing, query override states (default vs forced open/closed), adjust day/night branch destinations, and provision or toggle time condition rules programmatically with domain-level isolation and numbering collision protection.

### Available MCP Tools

| Tool Name | Description | Key Parameters |
|:---|:---|:---|
| `list_time_conditions` | Lists all Time Conditions in the domain, displaying linked Time Group, match/no-match destinations, toggle code, and current override status (`default`, `forced-match`, `forced-nomatch`). | `search` (optional string) |
| `get_time_condition_status` | Retrieves full configuration and current live schedule routing decision (open vs closed destination targets) of a specific Time Condition. | `name` (required string) |
| `create_time_condition` | Provisions a new Time Condition linking an existing Time Group to match and no-match destinations. Strictly validates name uniqueness and **enforces cross-module numbering anti-collision** on `toggleCode`. | `name`, `timeGroupName`, `destinationMatchModule`, `destinationMatchValue`, `destinationNomatchModule`, `destinationNomatchValue`, `toggleCode`, `description` |
| `update_time_condition` | Updates routing destinations, linked Time Group schedule, BLF toggle code, or manual status override. | `name`, `newName`, `timeGroupName`, `destinationMatchModule`, `destinationMatchValue`, `destinationNomatchModule`, `destinationNomatchValue`, `toggleCode`, `status`, `enabled` |
| `diagnose_time_condition` | Performs deep operational diagnostic on a Time Condition: evaluates server time, timezone offset, and Time Group schedule intervals, inspects manual override states (forced open vs forced closed), verifies match and non-match destination targets exist, and analyzes recent incoming schedule routing decisions. | `name` (required string) |
| `delete_time_condition` | Safely removes a Time Condition after verifying via `assertCanDeleteTimeCondition` that no active Inbound Routes or IVR options route to it. | `name` (required string) |

### Protection Guards & Anti-Collision Integrity
- **Toggle Code Numbering Anti-Collision**: When assigning an optional feature toggle code (e.g. `*271`), Ring2All executes `validateNumberUniqueness` across the entire tenant domain. Toggle codes cannot collide with existing SIP extensions, ring groups, call queues, conferences, or call flows.
- **Dependency Guard (`assertCanDeleteTimeCondition`)**: A Time Condition cannot be deleted if any inbound DID route points to it as primary destination or failover.
- **Atomic Telephony Server Synchronization**: Schedule updates immediately invalidate dialplan XML cache (`reloadxml`), ensuring instant activation on subsequent call arrivals.

### AI Agent Operational Examples

#### Auditing Time Condition Status & Overrides
```json
{
  "tool": "get_time_condition_status",
  "arguments": {
    "name": "Main Office Business Hours"
  }
}
```

#### Diagnosing Schedule Matching & Destination Readiness
```json
{
  "tool": "diagnose_time_condition",
  "arguments": {
    "name": "Main Office Business Hours"
  }
}
```

#### Provisioning an After-Hours Routing Condition
```json
{
  "tool": "create_time_condition",
  "arguments": {
    "name": "Emergency Night Routing",
    "timeGroupName": "Standard Business Hours",
    "destinationMatchModule": "ring-group",
    "destinationMatchValue": "600",
    "destinationNomatchModule": "voicemail",
    "destinationNomatchValue": "1001",
    "toggleCode": "*272"
  }
}
```

### Recommended Natural Language Prompts
- *"What is the current status and destination of the 'Main Office Business Hours' Time Condition?"*
- *"Force open the office phone lines by setting status to 'forced-match' on 'Business Hours Check'."*
- *"Check if feature code '*271' is available to use as a toggle code or if it collides with another number."*
- *"Update the no-match destination of 'Support Hours' to transfer callers to Queue 800."*

---

## 8. 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

1. **Name Clearly**: Use descriptive condition names
2. **Set Both Destinations**: Always configure match AND no-match
3. **Use Toggle Codes**: Enable quick override access
4. **Protect with PIN**: Secure important toggles
5. **Test Thoroughly**: Verify routing at different times
6. **Document Overrides**: Track who has toggle access

---

## 9. 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];
```

### Telephony Server Logs

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

---

## 10. 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 |

---

*Documentation last updated: January 2026*