Dynamic Destinations Module Documentation

Table of Contents

1. Module Overview (Technical)
2. Module Overview (Commercial/Business)
3. Module Overview (End User/Administrator)
4. Configuration Fields Reference
5. Call Flow / Logic Explanation
6. Common Scenarios & Examples
7. Model Context Protocol (MCP) AI Integration
8. Limitations & Important Notes
9. Troubleshooting Tips
10. 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

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

---

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

1. CRM-Based VIP Routing

   • Query CRM for customer tier
   • VIP customers → Priority queue

2. Credit/Account Status

   • Check payment status
   • Delinquent → Collections queue

3. Blacklist Enforcement

   • Query blocklist database
   • Blocked callers → Hangup or message

4. Geographic Routing

   • Look up caller location
   • Route to nearest branch

5. 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

🎯 User Roles & Key Capabilities

Role	Key Capabilities
Super Admin	Configures global database integrations, external API credentials, domain isolation, and monitors system-wide dynamic routing logs.
Tenant Admin	Creates and maintains domain-specific Dynamic Destinations, configures CRM query templates, and maps lookup values to queues, IVRs, or extensions.
Call Center Supervisor	Reviews dynamic routing options and verifies that VIP/high-value callers are routed to appropriate priority queues or departments.
Support Specialist / Agent	Benefits from automatic context-driven routing where callers are pre-screened and delivered to the correct skill-based destination.

Navigation

1. Navigate to PBX Engine → Applications → Dynamic Destination in the sidebar (or visit /pbx/applications/dynamic-destination).
2. The list view shows all configured dynamic routing engines, indicating Name, Source Type (DB/URL), Match Field, Default Destination, active Options count, and Status (Active/Inactive).
3. Click the + Add button in the top toolbar to create a new dynamic routing engine.
4. Click any existing engine row or edit button to update database connection strings, API URLs, or routing option rules.

Administrator Workflow

┌─────────────────────────────────────────────────────────────────┐
│            Creating a Dynamic Destination                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Step 1: General Settings                                       │
│  ├─ Name: "CRM Customer VIP Lookup"                             │
│  ├─ Description: "Live customer tier lookup via external CRM"   │
│  ├─ Source Type: HTTP Request (URL)                             │
│  ├─ URL: https://crm.company.com/api/v1/customer-lookup        │
│  ├─ Payload / Template: {"caller": "${caller_id_number}"}       │
│  ├─ Match Field: tier                                           │
│  ├─ Default Destination: Queues → General Support               │
│  └─ Active: Enabled                                            │
│                                                                 │
│  Step 2: Routing Options Matrix                                 │
│  ├─ Option 1: "VIP" → Queues → Priority VIP Queue (Enabled)     │
│  ├─ Option 2: "COLLECTIONS" → Extensions → Billing Dept (Enabled)│
│  └─ Option 3: "PARTNER" → Ring Groups → Partner Desk (Enabled)  │
│                                                                 │
│  Step 3: Save and Route Inbound DIDs                            │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

[!TIP] Variable Substitution: Use ${caller_id_number}, ${destination_number}, ${caller_id_name}, ${uuid}, or ${domain_name} within your SQL queries or JSON payload templates.

[!TIP] Fast Fallback: Always ensure your Default Destination points to a dependable destination (such as a primary IVR or general queue) in case the external API or database times out.

[!CAUTION] Query Latency: Telephony channels can wait a maximum of 2–3 seconds before callers experience dead air. Ensure external database indices and API endpoints respond in under 500ms.

---

4. Configuration Fields Reference

General Settings Box

Field	Description	UI Tooltip	Example	Notes
Name *	Primary identification label	Friendly name identifying this dynamic destination profile	CRM Customer VIP Lookup	Required.
Description	Contextual administrative notes	Optional description of the routing purpose or external database integration	Customer VIP check via CRM API	Optional.
Source Type *	Backend lookup protocol	Data source protocol queried during call routing	HTTP Request (URL)	Database (DB) or HTTP Request (URL). Required.
Match Field *	Extracted variable name	Field name in database row or JSON response key compared against routing rules	tier, status, account_code	Required.
Database Connection *	PostgreSQL or MySQL connection string	Connection string for database source	postgresql://user:pass@host:5432/crm	Required when Source Type is Database (DB).
SQL Query Template *	SQL query with variable placeholders	Parameterized SQL query executed to retrieve routing attributes	SELECT tier FROM clients WHERE phone = '${caller_id_number}'	Required when Source Type is Database (DB).
URL *	REST endpoint address	HTTP/HTTPS URL of the external lookup service	https://crm.company.com/api/v1/customer-lookup	Required when Source Type is HTTP Request (URL).
Payload / Query Template *	HTTP request body or query template	JSON body or query string template with parameter substitution	{"caller": "${caller_id_number}"}	Required when Source Type is HTTP Request (URL).
Default Destination *	Fallback call destination	Destination to bridge if the query returns no result or fails to match an option	Queues → General Support	Required. Module and Destination select.
Active	Operational status	Master toggle to enable or disable dynamic lookup for inbound calls	Enabled / Disabled	Toggle. Default: Enabled.

Routing Options Box

The Routing Options table defines discrete matching rules evaluated against the value extracted from the Match Field.

Field	Description	UI Tooltip	Example	Notes
Match Value *	Expected return value	Exact string or code expected from the external lookup response	VIP, PLATINUM, OVERDUE	Case-sensitive string matching.
Destination *	Target module and entity	PBX destination bridged when the return value matches	Queues → Priority VIP Queue	Selectable module (Extension, Queue, Ring Group, IVR, etc.).
Enabled	Rule state	Toggle to enable or disable this specific match rule	Enabled / Disabled	Toggle per option row.
Actions	Row management	Remove this match option from the routing table	Trash Icon	Removes the row.

Query Template Variables Reference

The dynamic routing engine interpolates runtime channel variables prior to executing the database query or HTTP API call:

Variable	Description	Runtime Example
${caller_id_number}	Incoming Caller ID phone number	15551234567
${caller_id_name}	Inbound Caller ID Name (CNAM)	John Doe
${destination_number}	Dialed DID or virtual extension	18005550199
${domain_name}	PBX telephony tenant domain	pbx.company.com
${uuid}	Telephony Server unique channel identifier	e742be94-8bf1-4e78-bc5a-e14b7320a5fd

---

5. Call Flow / Logic Explanation

Dynamic Routing Flow

┌─────────────────────────────────────────────────────────────────┐
│                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. Model Context Protocol (MCP) AI Integration

Ring2All exposes dedicated Model Context Protocol (MCP) tools for Dynamic Destinations, allowing autonomous AI agents and Copilots to inspect real-time CRM/HTTP webhook routing rules, provision automated external lookup engines, and modify data source configurations with domain-level isolation.

Available MCP Tools

Tool Name	Description	Key Parameters
list_dynamic_destinations	Lists all dynamic destination engines configured in the domain, including webhook URLs, DB sources, and fallback modules.	search (optional string)
get_dynamic_destination_status	Retrieves full routing logic, webhook parsing rules, source queries, and configured match branch options for a dynamic destination.	name (required)
create_dynamic_destination	Creates a new external-lookup routing destination using an HTTP REST endpoint or SQL query, with fallback routing.	name, sourceType (‘URL’ or ‘DB’), sourceConfig, defaultModule, defaultDestination, matchField
update_dynamic_destination	Updates external source URL/query, JSON match field parsing, or fallback route destinations.	name, newName, sourceType, sourceConfig, defaultModule, defaultDestination, enabled
delete_dynamic_destination	Deletes a dynamic destination configuration from the domain.	name (required)

AI Agent Operational Examples

Querying Dynamic Destination Lookup Engines

{
  "tool": "list_dynamic_destinations",
  "arguments": {
    "search": "CRM"
  }
}

Provisioning an AI-Driven VIP Routing Lookup

{
  "tool": "create_dynamic_destination",
  "arguments": {
    "name": "HubSpot VIP Tier Routing",
    "sourceType": "URL",
    "sourceConfig": "https://api.crm.example.com/v1/lookup?caller=${caller_id_number}",
    "matchField": "customer_tier",
    "defaultModule": "queue",
    "defaultDestination": "support_standard"
  }
}

Recommended Natural Language Prompts

• “Show me all dynamic destinations that route incoming calls based on external CRM webhooks.”
• “Create a dynamic destination called ‘Zendesk VIP Check’ that queries https://crm.internal/api/tier and falls back to IVR 100.”
• “Inspect the matching rules for ‘HubSpot VIP Tier Routing’.”

---

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

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

Security Considerations

[!CAUTION] SQL Injection: Variables are substituted directly—ensure trusted sources.

---

9. 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:

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:

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

---

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

---

Documentation last updated: January 2026