---
title: "Dynamic Destinations Module Documentation"
description: "Documentation for Dynamic Destination"
---

## Table of Contents
1. [Module Overview (Technical)](#1-module-overview-technical)
2. [Module Overview (Commercial/Business)](#2-module-overview-commercialbusiness)
3. [Module Overview (End User/Administrator)](#3-module-overview-end-useradministrator)
4. [Configuration Fields Reference](#4-configuration-fields-reference)
5. [Call Flow / Logic Explanation](#5-call-flow--logic-explanation)
6. [Common Scenarios & Examples](#6-common-scenarios--examples)
7. [Model Context Protocol (MCP) AI Integration](#7-model-context-protocol-mcp-ai-integration)
8. [Limitations & Important Notes](#8-limitations--important-notes)
9. [Troubleshooting Tips](#9-troubleshooting-tips)
10. [Glossary](#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.

![Dynamic Destinations List View](/screenshots/pbx/applications/dynamic-destination-list.png)

### 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

![Dynamic Destination Configuration Form](/screenshots/pbx/applications/dynamic-destination-form.png)

### 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
```json
{
  "tool": "list_dynamic_destinations",
  "arguments": {
    "search": "CRM"
  }
}
```

#### Provisioning an AI-Driven VIP Routing Lookup
```json
{
  "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:**
```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;
```

---

## 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*