Dynamic Destinations 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

---

1. Module Overview (Technical)

What Are Dynamic Destinations?

Dynamic Destinations allow real-time call routing decisions based on external data sources. The system queries a database or HTTP API, evaluates the response, and routes the call to a matching destination.

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                Dynamic Destination System                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Inbound call arrives                                           │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Dynamic Destination Lookup                  │   │
│  │  SELECT * FROM public.dynamic_destinations               │   │
│  │  WHERE name = [config_name] AND active = TRUE            │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Query External Source                       │   │
│  │                                                          │   │
│  │  Source Type: DB                                         │   │
│  │  ├─ Connect to: postgresql://crm.example.com/db         │   │
│  │  └─ Execute: SELECT status FROM clients                 │   │
│  │              WHERE phone='${caller_id_number}'           │   │
│  │                                                          │   │
│  │  Source Type: URL                                        │   │
│  │  ├─ Request: https://api.example.com/lookup             │   │
│  │  └─ Path: /check?caller=${caller_id_number}             │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Response: "VIP"                                        │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Match Against Options                       │   │
│  │                                                          │   │
│  │  Option 1: VIP → Queue: vip_support           ← MATCH   │   │
│  │  Option 2: STANDARD → Queue: general_support            │   │
│  │  Option 3: BLACKLIST → Hangup                           │   │
│  │  Default: → Queue: general_support                      │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  Route call to: Queue vip_support                               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

Table	Purpose
`public.dynamic_destinations`	Configuration (name, source, query)
`public.dynamic_destination_options`	Match values and destinations

Key Files

File	Description
`admin/apps/web/src/modules/dynamicDestinations/`	Frontend module
`admin/apps/web/src/i18n/en/dynamicDestination.json`	Translations
`telephony/freeswitch/lua/main/xml_handlers/dynamic_destination/dynamic_destination.lua`	Handler

---

2. Module Overview (Commercial/Business)

Business Value

Dynamic Destinations enable intelligent, data-driven routing:

Without Dynamic Destinations	With Dynamic Destinations
Static routing rules	Real-time decisions
Same treatment for all	VIP vs. standard routing
No CRM integration	CRM-aware call handling
Manual blacklist updates	Automatic blacklist enforcement

Use Cases

CRM-Based VIP Routing

- Query CRM for customer tier

- VIP customers → Priority queue

Credit/Account Status

- Check payment status

- Delinquent → Collections queue

Blacklist Enforcement

- Query blocklist database

- Blocked callers → Hangup or message

Geographic Routing

- Look up caller location

- Route to nearest branch

Business Hours Override

- Query external schedule API

- Dynamic after-hours routing

Feature Highlights

Feature	Benefit
Database Source	Query PostgreSQL/MySQL directly
HTTP Source	Integrate with REST APIs
Variable Substitution	Use ${caller_id_number}, etc.
Multiple Options	Match different values to destinations
Default Fallback	Handle unmatched cases
Priority Ordering	Process options in order

---

3. Module Overview (End User/Administrator)

What Can You Do?

Create routing flows that query external sources
Map response values to PBX destinations
Configure fallback for unmatched responses
Support both database and HTTP queries

Administrator Workflow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│            Creating a Dynamic Destination                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Step 1: General Settings                                       │
│  ├─ Name: "CRM VIP Lookup"                                     │
│  ├─ Source Type: Database                                      │
│  ├─ Connection: postgresql://crm:pass@crm.local/customers      │
│  ├─ Query: SELECT tier FROM clients                            │
│  │         WHERE phone='${caller_id_number}'                   │
│  └─ Match Field: tier                                          │
│                                                                 │
│  Step 2: Routing Options                                        │
│  ├─ Match "VIP" → Queue: vip_support (Priority 1)              │
│  ├─ Match "GOLD" → Queue: priority_support (Priority 2)        │
│  ├─ Match "BLOCKED" → Hangup (Priority 3)                      │
│  └─ Default → Queue: general_support                           │
│                                                                 │
│  Step 3: Enable and Save                                        │
│                                                                 │
│  Result: Calls are routed based on CRM customer tier           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP

Variable Substitution: Use ${caller_id_number}, ${destination_number}, etc.

TIP

Always Set Default: Ensure fallback handles query failures.

CAUTION

Query Performance: External queries add latency—keep them fast.

---

4. Configuration Fields Reference

General Settings

Field	Description	Example	Required
Name	Identifier	`CRM VIP Lookup`	Yes
Source Type	DB or URL	Database	Yes
Source Config	Connection string or URL	`postgresql://...`	Yes
Query Template	SQL or HTTP path	`SELECT tier FROM...`	Yes
Match Field	Response key to match	`tier`, `status`	Yes
Default Destination	Fallback route	Queue: general	Yes
Description	Notes	`VIP routing`	No
Active	Enabled status	On/Off	Yes

Source Types

Type	Config Format	Query Format
Database	`postgresql://user:pass@host/db`	SQL query
HTTP Request	`https://api.example.com`	Endpoint path

Query Template Variables

Variable	Description
`${caller_id_number}`	Caller's phone number
`${destination_number}`	Dialed number
`${domain_name}`	Tenant domain
`${caller_id_name}`	Caller name
`${uuid}`	Call UUID

Routing Options

Field	Description	Example
Match Value	Value to match	`VIP`, `BLOCKED`
Destination Module	Target type	Queue, IVR, Extension
Destination	Target identifier	`vip_queue`
Priority	Processing order	1 (first), 2, 3...
Enabled	Active status	On/Off

---

5. Call Flow / Logic Explanation

Dynamic Routing Flow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                Dynamic Destination Flow                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. Call arrives, triggers dynamic destination                  │
│     │                                                           │
│     ▼                                                           │
│  2. Load configuration from database                            │
│     ├─ Found & active → Continue                               │
│     └─ Not found → Use default dialplan                        │
│     │                                                           │
│     ▼                                                           │
│  3. Build query with variable substitution                      │
│     ${caller_id_number} → 5551234567                           │
│     │                                                           │
│     ▼                                                           │
│  4. Execute external query                                      │
│     ├─ Database: Run SQL, get result                           │
│     └─ HTTP: Make request, parse response                      │
│     │                                                           │
│     ▼                                                           │
│  5. Extract match field from response                           │
│     Response: {"tier": "VIP"} → Match value: "VIP"             │
│     │                                                           │
│     ▼                                                           │
│  6. Search options (by priority order)                          │
│     ├─ Option "VIP" ← MATCH                                    │
│     │   └─ Route to: Queue vip_support                        │
│     ├─ Option "STANDARD" (skipped)                             │
│     └─ Option "BLOCKED" (skipped)                              │
│     │                                                           │
│     ▼                                                           │
│  7. If no match → Use default destination                       │
│     │                                                           │
│     ▼                                                           │
│  8. Transfer call to resolved destination                       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

6. Common Scenarios & Examples

Scenario 1: CRM Customer Tier Routing

Configuration:

Setting	Value
Name	CRM Tier Routing
Source Type	Database
Connection	`postgresql://crm:pass@crm.local/customers`
Query	`SELECT tier FROM clients WHERE phone='${caller_id_number}'`
Match Field	`tier`

Options:

Match	Destination
VIP	Queue: vip_support
GOLD	Queue: priority_support
STANDARD	Queue: general_support
Default	Queue: general_support

Scenario 2: Blacklist Check via API

Configuration:

Setting	Value
Name	Blacklist Check
Source Type	HTTP Request
Base URL	`https://blocklist.example.com`
Endpoint	`/check?phone=${caller_id_number}`
Match Field	`blocked`

Options:

Match	Destination
true	Hangup
false	Queue: main_queue
Default	Queue: main_queue

Scenario 3: Payment Status Routing

Configuration:

Setting	Value
Name	Payment Status
Source Type	Database
Query	`SELECT status FROM accounts WHERE phone='${caller_id_number}'`
Match Field	`status`

Options:

Match	Destination
DELINQUENT	Queue: collections
SUSPENDED	IVR: payment_options
ACTIVE	Queue: customer_service
Default	Queue: customer_service

---

7. Limitations & Important Notes

Technical Limitations

WARNING

Query Latency: External queries add delay. Keep queries fast (<500ms).

WARNING

Connection Failures: If external source is down, default destination is used.

IMPORTANT

Security: Connection strings are stored in database. Use secure connections.

Best Practices

Fast Queries: Index lookup columns
Timeout Handling: External sources may fail
Default Always: Configure fallback for all cases
Test Thoroughly: Verify all match values route correctly
Monitor Latency: Track query performance

Security Considerations

CAUTION

SQL Injection: Variables are substituted directly—ensure trusted sources.

---

8. Troubleshooting Tips

Common Issues

Symptom	Possible Cause	Solution
Always uses default	Query returns no match	Check query and match field
"Feature not available"	Config not found/disabled	Verify active status
Long call setup	Slow external query	Optimize query, add indexes
Wrong destination	Match value mismatch	Check case sensitivity

Diagnostic SQL

List dynamic destinations:

Sql

SELECT name, source_type, match_field, active,
       (SELECT COUNT(*) FROM public.dynamic_destination_options 
        WHERE dynamic_destination_id = d.id) as option_count
FROM public.dynamic_destinations d
WHERE domain_id = [domain_id];

Check options:

Sql

SELECT match_value, destination_module, destination, priority, enabled
FROM public.dynamic_destination_options
WHERE dynamic_destination_id = [dd_id]
ORDER BY priority;

---

9. Glossary

Term	Definition
Dynamic Destination	Routing configuration that queries external sources
Source Type	Database (DB) or HTTP Request (URL)
Query Template	SQL or HTTP path with variable placeholders
Match Field	Response key containing value to match
Routing Option	Match value mapped to a destination
Default Destination	Fallback when no option matches
Variable Substitution	Replacing ${var} with call data
Priority	Order in which options are evaluated

---

Lua Script Status ✅

Integration Module

Component	Status	Location
Dynamic Destination Handler	✅ Active	`app/dynamic_destination/dynamic_destination.lua`

--- Documentation last updated: January 2026

Dynamic Destinations Module Documentation

Table of Contents

1. Module Overview (Technical)

What Are Dynamic Destinations?

Architecture

Key Tables

Key Files

2. Module Overview (Commercial/Business)

Business Value

Use Cases

Feature Highlights

3. Module Overview (End User/Administrator)

What Can You Do?

Administrator Workflow

Quick Tips

4. Configuration Fields Reference

General Settings

Source Types

Query Template Variables

Routing Options

5. Call Flow / Logic Explanation

Dynamic Routing Flow

6. Common Scenarios & Examples

Scenario 1: CRM Customer Tier Routing

Scenario 2: Blacklist Check via API

Scenario 3: Payment Status Routing

7. Limitations & Important Notes

Technical Limitations

Best Practices

Security Considerations

8. Troubleshooting Tips

Common Issues

Diagnostic SQL

9. Glossary

Lua Script Status ✅

Integration Module