Dial Profiles Module Documentation
Table of Contents
- Module Overview (Technical)
- Module Overview (Commercial/Business)
- Module Overview (End User/Administrator)
- Configuration Fields
- Common Scenarios & Examples
- Limitations & Important Notes
- Troubleshooting Tips
- Glossary
---
1. Module Overview (Technical)
What Are Dial Profiles?
Dial Profiles are reusable call behavior templates that control how calls behave before they are bridged or transferred. They define who can transfer/park calls, what ringback callers hear, call screening behavior, and custom FreeSWITCH channel variables.
Architecture
Key Tables
| Table | Purpose |
|---|---|
public.dial_profiles | Profile definitions |
Key Files
| File | Description | |
|---|---|---|
modules/dialProfiles/ | Frontend module | |
modules/dialProfiles/api/dialProfileApi.ts | API calls |
2. Module Overview (Commercial/Business)
Business Value
Dial Profiles provides consistent call handling:
| Without Dial Profiles | With Dial Profiles | |
|---|---|---|
| Configure each route | Apply templates | |
| Inconsistent behavior | Standardized handling | |
| Manual variable setting | Reusable profiles | |
| Hard to change | Update once, apply everywhere |
Use Cases
- Transfer Control
- Restrict external caller transfers
- Ringback Customization
- Custom branded audio
- Call Screening
- Announce caller info
- Advanced Call Flows
- Specialized behavior
Feature Highlights
| Feature | Benefit | |
|---|---|---|
| Transfer Control | Who can transfer | |
| Park Control | Who can park calls | |
| Ringback Options | Custom ringback/MOH | |
| Call Screening | Caller confirmation | |
| Custom Variables | FreeSWITCH flexibility | |
| Reusable | Apply to many routes |
3. Module Overview (End User/Administrator)
What Can You Do?
- Create dial profile templates
- Configure transfer permissions
- Configure park permissions
- Set ringback tones
- Enable call screening
- Add custom FreeSWITCH variables
- Apply profiles to routes
Dial Profiles Interface
Profile Edit View
Quick Tips
TIP
Transfer Control: Set "None" to prevent any transfers.TIP
MOH Ringback: Use "music/default" for hold music while ringing.NOTE
Custom Variables: Advanced users can add FreeSWITCH channel variables.---
4. Configuration Fields
General Settings
| Field | Description | |
|---|---|---|
| Name | Profile identifier | |
| Description | Purpose notes | |
| Active | Enable/disable profile |
Transfer & Parking
| Field | Options | Description | |
|---|---|---|---|
| Allow Transfer By | None, Caller, Recipient, Both | Who can transfer | |
| Allow Park By | None, Caller, Recipient, Both | Who can park calls |
Ringback Options
| Option | Description | |
|---|---|---|
| Default | System default ringback | |
| None (Ringback) | Standard phone ring | |
| music/default | Hold music while ringing | |
| Custom value | Custom stream/file path |
Call Screening
| Option | Description | |
|---|---|---|
| Disabled | Connect immediately | |
| Ask Once | Confirm once per call | |
| Always Ask | Confirm every transfer |
Advanced Options
| Field | Description | |
|---|---|---|
| Custom Options | FreeSWITCH channel variables (key=value) | |
| Ringing Tone | Enable ringing before bridge |
5. Common Scenarios & Examples
Scenario 1: Standard Office Profile
- Create new profile
- Allow Transfer By = Both
- Allow Park By = Both
- Ringback = music/default
- Call Screening = Disabled
- Save and apply to routes
Scenario 2: Queue Calls (No Transfer)
- Create new profile
- Allow Transfer By = Recipient only
- Allow Park By = Recipient only
- Ringback = music/default
- Call Screening = Ask Once
- Apply to queue destinations
Scenario 3: VIP Handling
- Create new profile
- Allow Transfer By = Both
- Ringback = Custom (VIP music)
- Call Screening = Disabled
- Add custom var: absolute_codec_string=OPUS
- Apply to VIP routes
Scenario 4: External Call Control
- Create new profile
- Allow Transfer By = Recipient
- Allow Park By = None
- Call Screening = Always Ask
- Apply to external DIDs
---
6. Limitations & Important Notes
Technical Notes
NOTE
Module Assignment: Dial Profiles can be applied to the following modules:
- Extensions: Set under the Advanced settings tab to define variables and permissions for user calls.
- Gateways: Assigned under the Basic Information settings of a SIP Trunk to control behavior on all incoming calls through the gateway.
- Inbound Routes: Configured under the Destination settings of a route to control call variables (transfers, custom ringbacks, screening) for incoming DIDs.
- Outbound Routes: Configured under the Advanced Options tab of the route to apply variables on outbound bridged calls.
NOTE
Variables: Custom options are FreeSWITCH channel variables.WARNING
Invalid Variables: Incorrect custom options may cause call failures.Best Practices
- Create Purpose-Specific: Different profiles for different call types
- Test Changes: Verify behavior after changes
- Document Profiles: Use description field
- Limit Custom Vars: Only use when necessary
- Standard Naming: Use clear, descriptive names
Transfer/Park Permission Matrix
| Setting | Caller Can | Recipient Can | |
|---|---|---|---|
| None | ✗ | ✗ | |
| Caller | ✓ | ✗ | |
| Recipient | ✗ | ✓ | |
| Both | ✓ | ✓ |
7. Troubleshooting Tips
Common Issues
| Symptom | Possible Cause | Solution | |
|---|---|---|---|
| Can't transfer | Wrong permission | Check Allow Transfer By | |
| No ringback | Wrong setting | Check Ringback Tone | |
| Screening not working | Profile not applied | Verify route assignment | |
| Call fails | Bad custom var | Check Custom Options | |
| Wrong music | Invalid path | Verify ringback path |
Common Custom Variables
| Variable | Purpose | |
|---|---|---|
continue_on_fail=true | Try next route on failure | |
ignore_early_media=true | Ignore early media | |
hangup_after_bridge=true | Hangup after bridge | |
call_timeout=30 | Ring timeout seconds | |
absolute_codec_string=OPUS | Force codec |
Debug Workflow
- Check profile is active
- Verify route uses correct profile
- Check FreeSWITCH logs for variables
- Test with simple profile first
- Add custom options one at a time
---
8. Glossary
| Term | Definition | |
|---|---|---|
| Dial Profile | Call behavior template | |
| Ringback | Audio caller hears while ringing | |
| Call Screening | Confirm before connecting | |
| Transfer | Move call to another party | |
| Park | Hold call in shared lot | |
| Channel Variable | FreeSWITCH call setting |
Lua Script Status ℹ️
No Dedicated Handler Required
| Component | Status |
|---|---|
| Dial Profiles | ℹ️ Configuration module - variables applied during routing |
---
Documentation last updated: January 2026