Custom Applications 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 Are Custom Applications?

Custom Applications allow administrators to create programmable call logic using Lua scripts or XML dialplan entries. When a user dials the trigger number, FreeSWITCH executes the custom code before optionally routing to a final destination.

Two Application Types

Type	Description	Use Case
Lua Script	Programmatic logic with Lua code	Complex logic, API calls, database queries
XML Dialplan	Declarative FreeSWITCH XML	Simple routing, variable setting

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                Custom Applications Architecture                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  User dials: *99 (trigger number)                               │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Custom Application Lookup                   │   │
│  │  SELECT * FROM custom_applications                       │   │
│  │  WHERE trigger_number = '*99' AND enabled = true         │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Execute Script                              │   │
│  │                                                          │   │
│  │  LUA SCRIPT:                                             │   │
│  │  ├─ Load script from file system                         │   │
│  │  ├─ Execute Lua code (session:answer(), play, etc.)      │   │
│  │  └─ Access variables: caller_id, CUSTOM_APP_UUID, etc.   │   │
│  │                                                          │   │
│  │  XML DIALPLAN:                                           │   │
│  │  ├─ Parse XML content                                    │   │
│  │  └─ Execute as inline dialplan                           │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Final Destination (if not skipped)          │   │
│  │                                                          │   │
│  │  ├─ extension   → Transfer to extension                  │   │
│  │  ├─ queue       → Send to call queue                     │   │
│  │  ├─ ivr         → Send to IVR menu                       │   │
│  │  ├─ conference  → Join conference                        │   │
│  │  ├─ voicemail   → Send to voicemail                      │   │
│  │  ├─ announcement→ Play announcement                      │   │
│  │  ├─ external    → Dial external number                   │   │
│  │  └─ hangup      → End call                               │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

Table	Purpose
`public.custom_applications`	Application definitions (name, trigger, script)

Script Storage

Scripts are stored as files in FreeSWITCH:

Plaintext

/usr/share/freeswitch/scripts/custom_apps/[uuid].lua
/usr/share/freeswitch/scripts/custom_apps/[uuid].xml

Available Variables

Variable	Description
`CUSTOM_APP_DOMAIN`	The domain/tenant the call is in
`CUSTOM_APP_UUID`	Unique ID of this application
`caller_id_number`	Caller's phone number
`caller_id_name`	Caller's name
`destination_number`	Number that was dialed

Key Files

File	Description
`admin/apps/web/src/modules/customApplications/`	Frontend module
`admin/apps/web/src/i18n/en/customApplications.json`	English translations
`telephony/freeswitch/lua/main/custom_app_handler.lua`	Lua handler

---

2. Module Overview (Commercial/Business)

Business Value

Custom Applications provide extensibility without core modifications:

Without Custom Apps	With Custom Apps
Hardcoded logic only	Dynamic programmable logic
Developer required	Admin can create via UI
System restart needed	Hot-deployed scripts
No customization	Unlimited flexibility

Use Cases

Custom IVR Logic

- Complex branching based on caller ID

- Database lookups for personalized greetings

- API integrations with external systems

Pre-Call Announcements

- "This call may be recorded"

- Holiday hour announcements

- Emergency notifications

Call Routing Logic

- Time-based routing with custom logic

- VIP caller detection

- Geographic routing

Integration Points

- CRM lookups before connecting

- Ticket creation on call start

- SMS notifications

Feature Highlights

Feature	Benefit
Lua Scripting	Full programming language for complex logic
XML Dialplan	Simple declarative routing
Final Destination	Route anywhere after script completes
Skip Destination	Script handles everything (hangup internally)
Hot Deploy	Changes apply immediately

---

3. Module Overview (End User/Administrator)

What Can You Do?

Create custom applications with Lua or XML code
Assign trigger numbers (extension or feature code)
Define final destinations for post-script routing
Enable/disable applications without deleting

User Workflow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                 Creating a Custom Application                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Step 1: Basic Information (General Settings Tab)               │
│  ├─ Name: "Recording Disclaimer"                               │
│  ├─ Trigger Number: *99                                        │
│  ├─ Description: "Plays recording notice before transfer"      │
│  └─ Application Type: Lua Script                               │
│                                                                 │
│  Step 2: Script Content (Script Content Tab)                    │
│  ├─ Write Lua code:                                            │
│  │   session:answer()                                          │
│  │   session:sleep(500)                                        │
│  │   session:streamFile("ivr/recording_disclaimer.wav")        │
│  │   -- Final destination handles the rest                     │
│  │                                                              │
│  Step 3: Final Destination                                      │
│  ├─ Skip Final Destination: ✗ (transfer after script)         │
│  ├─ Destination Type: Queue                                    │
│  └─ Destination Value: support_queue                           │
│                                                                 │
│  Step 4: Enable and Save                                        │
│  └─ Enabled: ✓                                                 │
│                                                                 │
│  Result: Dial *99 → Plays disclaimer → Transfers to queue      │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP

Start Simple: Begin with basic Lua scripts before attempting complex integrations.

TIP

Test Thoroughly: Always test custom applications in a development environment first.

CAUTION

Syntax Errors: Invalid Lua/XML will cause the application to fail. Check FreeSWITCH logs for errors.

---

4. Configuration Fields Reference

General Settings Tab

Field	Description	Example	Required
Name	Unique application name	`Recording Disclaimer`	Yes
Trigger Number	Extension/feature code	`99`, `8001`	Yes
Description	Purpose documentation	`Plays recording notice`	No
Application Type	Lua Script or XML Dialplan	Lua Script	Yes
Enabled	Active/inactive	On/Off	Yes

Script Content Tab

Field	Description	Notes
Script Content	Lua code or XML dialplan	Monaco editor with syntax highlighting

Final Destination Section

Field	Description	Options
Skip Final Destination	Don't route after script	On = script handles hangup
Destination Type	Where to route	Extension, Queue, IVR, Conference, Voicemail, Announcement, External, Hangup, Time Condition, Call Flow, Ring Group
Destination Value	Target identifier	Depends on type

Destination Types

Type	Value Format	Example
Extension	Extension number	`1001`
Queue	Queue name	`support_queue`
Ring Group	Ring group ID	`sales_group`
IVR	IVR name	`main_menu`
Voicemail	Extension number	`1001`
Announcement	Announcement ID	`holiday_hours`
Conference	Conference extension	`8000`
Hangup	(none)	Ends call
External	Phone number	`+15551234567`
Time Condition	Time condition ID	`business_hours`
Call Flow	Call flow ID	`main_flow`

---

5. Call Flow / Logic Explanation

Custom Application Execution Flow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              Custom Application Execution Flow                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. User dials *99 (trigger number)                             │
│     │                                                           │
│     ▼                                                           │
│  2. Dialplan matches custom_application route                   │
│     │                                                           │
│     ▼                                                           │
│  3. Load application from database                              │
│     ├─ Verify enabled = true                                   │
│     ├─ Get app_type (lua/xml)                                  │
│     └─ Get script_filename                                     │
│     │                                                           │
│     ▼                                                           │
│  4. Set channel variables                                       │
│     ├─ CUSTOM_APP_DOMAIN = [domain]                             │
│     ├─ CUSTOM_APP_UUID = [uuid]                                 │
│     └─ (other call variables available)                         │
│     │                                                           │
│     ▼                                                           │
│  5. Execute script                                              │
│     │                                                           │
│     ├─ LUA:                                                     │
│     │   session:execute("lua", "custom_apps/[uuid].lua")       │
│     │                                                           │
│     └─ XML:                                                     │
│         process inline dialplan from file                       │
│     │                                                           │
│     ▼                                                           │
│  6. Script completes                                            │
│     │                                                           │
│     ├─ skip_final_destination = true → DONE (call ends)        │
│     │                                                           │
│     └─ skip_final_destination = false → Step 7                  │
│     │                                                           │
│     ▼                                                           │
│  7. Route to final destination                                  │
│     ├─ extension → transfer("1001 XML default")                │
│     ├─ queue → callcenter("support@...")                       │
│     ├─ ivr → ivr("main_menu")                                  │
│     └─ etc.                                                    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

6. Common Scenarios & Examples

Scenario 1: Recording Disclaimer

Purpose: Play "This call may be recorded" before connecting to support. Configuration:

Setting	Value
Name	Recording Disclaimer
Trigger	99
Type	Lua Script
Skip Destination	No
Final Destination	Queue: support_queue

Script:

Lua

-- Recording Disclaimer
session:answer()
session:sleep(500)
session:streamFile("ivr/this_call_may_be_recorded.wav")
-- Final destination handles transfer to queue

Scenario 2: VIP Caller Detection

Purpose: Check if caller is VIP and route accordingly. Configuration:

Setting	Value
Name	VIP Router
Trigger	77
Type	Lua Script
Skip Destination	Yes (script handles routing)

Script:

Lua

-- VIP Caller Detection
local caller = session:getVariable("caller_id_number")
local vip_numbers = {"5551234567", "5559876543", "5551111111"}

local is_vip = false
for _, num in ipairs(vip_numbers) do
    if caller:find(num) then
        is_vip = true
        break
    end
end

session:answer()
if is_vip then
    session:streamFile("ivr/vip_welcome.wav")
    session:transfer("1001", "XML", "default")  -- VIP extension
else
    session:transfer("5000", "XML", "default")  -- Regular queue
end

Scenario 3: Emergency Announcement

Purpose: Play emergency message and hang up. Configuration:

Setting	Value
Name	Emergency Notice
Trigger	911
Type	Lua Script
Skip Destination	Yes

Script:

Lua

-- Emergency Announcement
session:answer()
session:streamFile("emergency/building_evacuation.wav")
session:hangup()

Scenario 4: Simple XML Routing

Purpose: Set a variable and transfer. Configuration:

Setting	Value
Name	Department Router
Trigger	50
Type	XML Dialplan
Skip Destination	Yes

Script:

Xml

<extension name="custom_router">
  <condition field="destination_number" expression=".*">
    <action application="set" data="department=sales"/>
    <action application="transfer" data="1001 XML default"/>
  </condition>
</extension>

---

7. Limitations & Important Notes

Technical Limitations

WARNING

Syntax Errors: Invalid Lua or XML will cause the application to fail silently. Always check logs.

WARNING

No Debugging UI: Script debugging must be done via FreeSWITCH console/logs.

IMPORTANT

Script Permissions: Scripts run with FreeSWITCH privileges. Be careful with file operations.

Best Practices

Keep Scripts Simple: Complex logic is harder to debug
Use Logging: Add freeswitch.consoleLog("INFO", message) for debugging
Handle Errors: Wrap critical code in pcall() for error handling
Test Offline: Test Lua scripts in a Lua interpreter first
Document Code: Add comments explaining what the script does

Security Considerations

CAUTION

Code Injection: Custom applications run arbitrary code. Restrict who can create them.

CAUTION

External API Calls: Be careful with API calls in scripts—they can slow down call setup.

---

8. Troubleshooting Tips

Common Issues

Symptom	Possible Cause	Solution
Application not triggered	Trigger number conflict	Check for duplicate extensions
Script error	Lua syntax error	Check FreeSWITCH console logs
No audio	session:answer() missing	Ensure call is answered first
Final destination ignored	skip_final_destination = true	Set to false if routing needed
Variables undefined	Wrong variable name	Check available variables

Debugging in FreeSWITCH

Enable Lua debugging:

Bash

fs_cli -x "console loglevel debug"

Watch for custom app execution:

Bash

fs_cli -x "log 7" | grep -i custom_app

Diagnostic SQL

List custom applications:

Sql

SELECT name, trigger_number, app_type, enabled,
       final_destination_module, final_destination_value
FROM public.custom_applications
WHERE domain_id = [domain_id]
ORDER BY trigger_number;

Check script file:

Bash

ls -la /usr/share/freeswitch/scripts/custom_apps/[uuid].lua

---

9. Glossary

Term	Definition
Custom Application	User-defined script that executes when a trigger number is dialed
Lua	Lightweight programming language used for FreeSWITCH scripting
XML Dialplan	FreeSWITCH's declarative routing configuration format
Trigger Number	The extension or feature code that activates the application
Final Destination	Where the call is routed after the script completes
Skip Destination	Option to not route after script (script handles hangup)
Hot Deploy	Changes take effect immediately without restart
session	Lua object representing the active call/channel
Channel Variable	Named values attached to a call for data passing

---

10. Suggested UI Improvements

Enhanced Tooltips (Already Good)

The existing tooltips are comprehensive. Minor enhancements:

Field	Suggested Addition
scriptContent	Add link to Lua API documentation
triggerNumber	Add conflict check warning

UX Enhancements

Syntax Validation: Real-time Lua/XML syntax checking in editor

Script Templates: Dropdown of common script templates:

- Announcement + Transfer

- VIP Detection

- Time-Based Routing

- API Integration

Test Button: "Test this application" that initiates a test call

Version History: Track changes to scripts over time

Duplicate Detection: Warn if trigger number conflicts with existing entries

Log Viewer: Show recent execution logs for this application

Editor Improvements

Current	Suggested
Monaco editor	Add Lua autocomplete for FreeSWITCH API
Plain text	Syntax highlighting for FreeSWITCH functions
No validation	Real-time syntax error highlighting

---

Lua Script Status ✅

Integration Module

Component	Status	Notes
Custom Applications	✅ Active	Executes custom Lua scripts defined in the application's configuration

---

Documentation last updated: January 2026*

Custom Applications Module Documentation

Table of Contents

1. Module Overview (Technical)

What Are Custom Applications?

Two Application Types

Architecture

Key Tables

Script Storage

Available Variables

Key Files

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

General Settings Tab

Script Content Tab

Final Destination Section

Destination Types

5. Call Flow / Logic Explanation

Custom Application Execution Flow

6. Common Scenarios & Examples

Scenario 1: Recording Disclaimer

Scenario 2: VIP Caller Detection

Scenario 3: Emergency Announcement

Scenario 4: Simple XML Routing

7. Limitations & Important Notes

Technical Limitations

Best Practices

Security Considerations

8. Troubleshooting Tips

Common Issues

Debugging in FreeSWITCH

Diagnostic SQL

9. Glossary

10. Suggested UI Improvements

Enhanced Tooltips (Already Good)

UX Enhancements

Editor Improvements

Lua Script Status ✅

Integration Module