Direct Dial Module Documentation

Module Overview (Technical)
Module Overview (Commercial/Business)
Module Overview (End User/Administrator)
Configuration Fields Reference
Call Flow / Logic Explanation
Common Scenarios & Examples
Limitations & Important Notes
Troubleshooting Tips
Glossary
Suggested UI Improvements

---

1. Module Overview (Technical)

What Is Direct Dial?

Direct Dial is a routing shortcut mechanism that maps feature codes (like 8050 or 8050) to specific destinations in the PBX. It provides quick-access shortcuts to any module in the system without requiring users to remember complex extension numbers.

Architecture

Plaintext
┌─────────────────────────────────────────────────────────────────┐ │ Direct Dial System │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ User dials: *8050 │ │ │ │ │ ▼ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ Direct Dial Dialplan Lookup │ │ │ │ SELECT * FROM direct_dials WHERE code = '*8050' │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ Route Based on Module │ │ │ │ │ │ │ │ ├─ extension → Dial extension (e.g., 1001) │ │ │ │ ├─ ivr → Send to IVR menu (e.g., main_menu) │ │ │ │ ├─ queue → Send to call queue (e.g., support) │ │ │ │ ├─ conference → Join conference room (e.g., 8000) │ │ │ │ ├─ announcement → Play announcement │ │ │ │ └─ transfer → Blind transfer to destination │ │ │ │ │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ Call routed to destination │ │ │ └─────────────────────────────────────────────────────────────────┘

Key Tables

Table Purpose
public.direct_dials Direct dial code definitions
public.dialplan_applications Generated dialplan entries
Key Files

File Description
admin/apps/api/src/modules/telephony/direct-dial/services/ Backend service
admin/apps/web/src/modules/directDial/DirectDialFormView.tsx Form view
admin/apps/web/src/i18n/en/directDial.json English translations
Destination Modules

Module Description Example Value
extension Direct to an extension 1001
ivr Send to IVR menu main_menu
queue Send to call queue sales_queue
conference Join conference room 8000
announcement Play announcement holiday_notice
transfer Blind transfer +15551234567
---
2. Module Overview (Commercial/Business)

Business Value

Direct Dial simplifies user experience with memorable shortcuts:

Without Direct Dial With Direct Dial
"Dial 9001235555 for support" "Dial 5555 for support"
Users forget long numbers Short memorable codes
Complex dialplan changes Simple UI configuration
Use Cases

Feature Codes

- 22 → Check voicemail

- 67 → Anonymous call

- 72 → Forward calls

Department Shortcuts

- 100 → Reception desk

- 200 → IT Helpdesk

- 300 → HR Department

Emergency/Priority

- 911 → Emergency services

- 99 → Security office

- 77 → Urgent support queue

External Services

- 800 → Company hotline

- 411 → Directory services

- 555 → Conference bridge

Feature Highlights

Simple Mapping: Code → Destination in one setting

Multiple Targets: Route to any module type

Enable/Disable: Quickly toggle without deleting

Context Aware: Different codes per domain/context

---

3. Module Overview (End User/Administrator)

What Can You Do?

Create feature codes that route to specific destinations

Map codes to extensions, IVRs, queues, conferences, or announcements

Enable/disable codes without deletion

Organize shortcuts by descriptive names

User Workflow

Plaintext
┌─────────────────────────────────────────────────────────────────┐ │ Creating a Direct Dial │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ 1. Basic Information │ │ ├─ Code: *5555 │ │ ├─ Name: "Support Hotline" │ │ └─ Description: "Routes to support queue" │ │ │ │ 2. Destination │ │ ├─ Module: Queue │ │ └─ Value: support_queue │ │ │ │ 3. Enable: ✓ │ │ │ │ 4. Save → Users can now dial *5555 │ │ │ └─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP
Use Asterisk Prefix: Codes starting with are easy to remember and reduce conflicts with extension numbers.

TIP
Descriptive Names: Use clear names like "IT Helpdesk" instead of "DD1" for easier management.

CAUTION
Code Conflicts: Ensure your direct dial codes don't conflict with existing extensions or feature codes.

---

4. Configuration Fields Reference

Basic Information

Field Description Example Required
Code Dialable feature code 8050 Yes
Name Descriptive name Main Menu IVR Yes
Description Purpose documentation Routes to main IVR No
Context Dialplan context default Yes
Destination

Field Description Options Required
Module Target module type extension, ivr, queue, conference, announcement, transfer Yes
Value Target identifier Based on module Yes
Value Examples by Module

Module Value Format Examples
Extension Extension number 1001, 2050, 9999
IVR IVR name or ID main_menu, sales_ivr
Queue Queue name support, sales_queue
Conference Conference extension 8000, 9001
Announcement Announcement ID holiday_hours, closed_notice
Transfer Phone number +15551234567, 9001234567
Status

Field Description Default
Enabled Whether the code is active Yes
---
5. Call Flow / Logic Explanation

Direct Dial Routing Flow

Plaintext
┌─────────────────────────────────────────────────────────────────┐ │ Direct Dial Flow │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ 1. User dials *5555 from their phone │ │ │ │ │ ▼ │ │ 2. FreeSWITCH dialplan matches direct_dial application │ │ │ │ │ ▼ │ │ 3. Lua handler queries database: │ │ SELECT destination_module, destination_value │ │ FROM direct_dials │ │ WHERE code = '*5555' AND enabled = true │ │ │ │ │ ├─ Found → Continue │ │ └─ Not Found → "Number not found" + hangup │ │ │ │ │ ▼ │ │ 4. Based on destination_module: │ │ ├─ extension → session:execute("transfer", "1001 XML") │ │ ├─ ivr → session:execute("ivr", "main_menu") │ │ ├─ queue → session:execute("callcenter", "queue@...") │ │ ├─ conference → session:execute("conference", "8000@...") │ │ ├─ announcement → play announcement, then hangup │ │ └─ transfer → session:execute("bridge", "sofia/.../dest") │ │ │ │ │ ▼ │ │ 5. Call proceeds to destination │ │ │ └─────────────────────────────────────────────────────────────────┘

---

6. Common Scenarios & Examples

Scenario 1: Department Hotlines
Create shortcuts for department access:
Code Name Module Value
100 Reception extension 1000
200 IT Support queue it_support
300 HR Department extension 3000
400 Sales queue sales_queue
Scenario 2: IVR Access
Create shortcuts to IVR menus:
Code Name Module Value
0 Main Menu ivr main_menu
1 Sales Menu ivr sales_ivr
2 Support Menu ivr support_ivr
Scenario 3: Conference Quick Access
One-touch conference joining:
Code Name Module Value
8000 Daily Standup conference daily_standup
8001 Team Meeting conference team_room
8002 All Hands conference all_hands
Scenario 4: External Transfer
Quick access to external numbers:
Code Name Module Value
911 Emergency transfer 911
411 Directory transfer 411
800 Company Toll-Free transfer +18005551234
---
7. Limitations & Important Notes

Technical Limitations

WARNING
Code Uniqueness: Codes must be unique within a domain. Duplicate codes will cause routing failures.

WARNING
Asterisk Conflicts: Some codes are reserved by FreeSWITCH or telephony standards. Check for conflicts.

IMPORTANT
Dialplan Priority: Direct dial entries are processed in dialplan order. Ensure they don't conflict with higher-priority routes.

Best Practices

Use Consistent Prefixes: All department codes with 1xx, all queues with 2xx, etc.

Document Purpose: Use description field to explain why the code exists

Test Before Deploy: Verify routing works before publishing codes to users

Avoid Numeric-Only: Pure numbers may conflict with extensions

Reserved Codes (Commonly)

Code Standard Use
67 Block Caller ID
69 Call Return
72 Call Forwarding
73 Cancel Forwarding
82 Unblock Caller ID
98 Voicemail Access
---
8. Troubleshooting Tips

Common Issues

Symptom Possible Cause Solution
"Number not found" Code not in database Verify code exists and is enabled
Wrong destination Module/value mismatch Check destination module and value
Code not recognized Dialplan not matching Check context matches dialplan
Conflict with extension Code overlaps Use asterisk prefix or different range
Diagnostic SQL
List all direct dials:
Sql
SELECT code, name, destination_module, destination_value, enabled FROM public.direct_dials WHERE domain_id = [domain_id] ORDER BY code;

Check for code conflicts:
Sql
-- Check against extensions SELECT 'CONFLICT' AS status, dd.code, e.extension FROM public.direct_dials dd JOIN public.sip_extensions e ON dd.code = e.extension WHERE dd.domain_id = [domain_id];

Find disabled codes:
Sql
SELECT code, name, destination_module FROM public.direct_dials WHERE enabled = false AND domain_id = [domain_id];

---

9. Glossary

Term Definition
Direct Dial A shortcut code that routes to a specific destination
Feature Code A dialable code (usually starting with ) that triggers a feature
Destination Module The type of target (extension, IVR, queue, etc.)
Destination Value The specific target identifier
Context Dialplan context for routing logic
Dialplan FreeSWITCH routing configuration
IVR Interactive Voice Response menu
Queue Call queue for agent distribution
Announcement Pre-recorded audio message
Transfer Redirect call to external number
---
10. Suggested UI Improvements

Enhanced Tooltips

Field Current Suggested
Code "Enter a dialable feature code" "Enter a dialable feature code (e.g., 8050). Avoid codes that conflict with extensions or reserved system codes."
Module "Select the destination module type" "Select where calls should be routed. Extension = direct user, Queue = wait for agent, IVR = menu system."
Value "Enter the target value" "Enter the target identifier. For extensions: number (1001). For IVRs: menu name. For queues: queue name."
UX Enhancements

Conflict Detection: Warn if code conflicts with existing extensions or other direct dials

Module-Specific Value Picker: Instead of free-text value, show dropdown of available destinations based on selected module

Test Button: "Test this code" button that initiates a test call

Bulk Import: CSV import for creating multiple direct dials at once

Usage Stats: Show how often each code is dialed

Visual Improvements

Current Suggested
Plain list Add module icon (phone, menu, queue, conference)
Simple toggle Colored status badge (green/red)
Text-only value Link to destination entity
---

Lua Script Status ℹ️

Integration Module

Component Status Notes
Direct Dial ℹ️ Configuration module Routing handled by dialplan XML structure
--- Documentation last updated: January 2026

Table	Purpose
`public.direct_dials`	Direct dial code definitions
`public.dialplan_applications`	Generated dialplan entries

File	Description
`admin/apps/api/src/modules/telephony/direct-dial/services/`	Backend service
`admin/apps/web/src/modules/directDial/DirectDialFormView.tsx`	Form view
`admin/apps/web/src/i18n/en/directDial.json`	English translations

Module	Description	Example Value
`extension`	Direct to an extension	`1001`
`ivr`	Send to IVR menu	`main_menu`
`queue`	Send to call queue	`sales_queue`
`conference`	Join conference room	`8000`
`announcement`	Play announcement	`holiday_notice`
`transfer`	Blind transfer	`+15551234567`

Without Direct Dial	With Direct Dial
"Dial 9001235555 for support"	"Dial 5555 for support"
Users forget long numbers	Short memorable codes
Complex dialplan changes	Simple UI configuration

Field	Description	Example	Required
Code	Dialable feature code	`8050`	Yes
Name	Descriptive name	`Main Menu IVR`	Yes
Description	Purpose documentation	`Routes to main IVR`	No
Context	Dialplan context	`default`	Yes

Field	Description	Options	Required
Module	Target module type	extension, ivr, queue, conference, announcement, transfer	Yes
Value	Target identifier	Based on module	Yes

Module	Value Format	Examples
Extension	Extension number	`1001`, `2050`, `9999`
IVR	IVR name or ID	`main_menu`, `sales_ivr`
Queue	Queue name	`support`, `sales_queue`
Conference	Conference extension	`8000`, `9001`
Announcement	Announcement ID	`holiday_hours`, `closed_notice`
Transfer	Phone number	`+15551234567`, `9001234567`

Code	Name	Module	Value
`100`	Reception	extension	`1000`
`200`	IT Support	queue	`it_support`
`300`	HR Department	extension	`3000`
`400`	Sales	queue	`sales_queue`

Code	Name	Module	Value
`0`	Main Menu	ivr	`main_menu`
`1`	Sales Menu	ivr	`sales_ivr`
`2`	Support Menu	ivr	`support_ivr`

Code	Name	Module	Value
`8000`	Daily Standup	conference	`daily_standup`
`8001`	Team Meeting	conference	`team_room`
`8002`	All Hands	conference	`all_hands`

Code	Name	Module	Value
`911`	Emergency	transfer	`911`
`411`	Directory	transfer	`411`
`800`	Company Toll-Free	transfer	`+18005551234`

Code	Standard Use
`67`	Block Caller ID
`69`	Call Return
`72`	Call Forwarding
`73`	Cancel Forwarding
`82`	Unblock Caller ID
`98`	Voicemail Access

Symptom	Possible Cause	Solution
"Number not found"	Code not in database	Verify code exists and is enabled
Wrong destination	Module/value mismatch	Check destination module and value
Code not recognized	Dialplan not matching	Check context matches dialplan
Conflict with extension	Code overlaps	Use asterisk prefix or different range

Term	Definition
Direct Dial	A shortcut code that routes to a specific destination
Feature Code	A dialable code (usually starting with ) that triggers a feature
Destination Module	The type of target (extension, IVR, queue, etc.)
Destination Value	The specific target identifier
Context	Dialplan context for routing logic
Dialplan	FreeSWITCH routing configuration
IVR	Interactive Voice Response menu
Queue	Call queue for agent distribution
Announcement	Pre-recorded audio message
Transfer	Redirect call to external number

Field	Current	Suggested
Code	"Enter a dialable feature code"	"Enter a dialable feature code (e.g., 8050). Avoid codes that conflict with extensions or reserved system codes."
Module	"Select the destination module type"	"Select where calls should be routed. Extension = direct user, Queue = wait for agent, IVR = menu system."
Value	"Enter the target value"	"Enter the target identifier. For extensions: number (1001). For IVRs: menu name. For queues: queue name."

Current	Suggested
Plain list	Add module icon (phone, menu, queue, conference)
Simple toggle	Colored status badge (green/red)
Text-only value	Link to destination entity

Direct Dial Module Documentation

Table of Contents

1. Module Overview (Technical)

What Is Direct Dial?

Architecture

Key Tables

Key Files

Destination Modules

2. Module Overview (Commercial/Business)

Business Value

Use Cases

Feature Highlights

3. Module Overview (End User/Administrator)

What Can You Do?

User Workflow

Quick Tips

4. Configuration Fields Reference

Basic Information

Destination

Value Examples by Module

Status

5. Call Flow / Logic Explanation

Direct Dial Routing Flow

6. Common Scenarios & Examples

Scenario 1: Department Hotlines

Scenario 2: IVR Access

Scenario 3: Conference Quick Access

Scenario 4: External Transfer

7. Limitations & Important Notes

Technical Limitations

Best Practices

Reserved Codes (Commonly)

8. Troubleshooting Tips

Common Issues

Diagnostic SQL

9. Glossary

10. Suggested UI Improvements

Enhanced Tooltips

UX Enhancements

Visual Improvements

Lua Script Status ℹ️

Integration Module