---
title: "Queue Profiles Module Documentation"
description: "Documentation for Queues Profiles"
---

## Table of Contents
1. [Navigation & Access](#navigation--access)
2. [Screenshots & Visual Interface](#screenshots--visual-interface)
3. [Module Overview (Technical)](#1-module-overview-technical)
4. [Module Overview (Commercial/Business)](#2-module-overview-commercialbusiness)
5. [Module Overview (End User/Administrator)](#3-module-overview-end-useradministrator)
6. [User Roles & Key Capabilities](#-user-roles--key-capabilities)
7. [Configuration Tabs](#4-configuration-tabs)
8. [Settings Reference](#5-settings-reference)
9. [Common Scenarios & Examples](#6-common-scenarios--examples)
10. [Limitations & Important Notes](#7-limitations--important-notes)
11. [Troubleshooting Tips](#8-troubleshooting-tips)
12. [Glossary](#9-glossary)
13. [Model Context Protocol (MCP) AI Integration](#model-context-protocol-mcp-ai-integration)
---

## Navigation & Access

To access the Queue Profiles configuration module:
1. Log in to the Ring2All Web Portal (`https://<domain-or-ip>/login`).
2. In the left navigation sidebar, expand **Settings**.
3. Under **PBX**, click **Queues Profiles** (`/settings/pbx/queue-profiles`).
4. To create a new queue distribution policy template, click **+ Add Profile** (`/settings/pbx/queue-profiles/new`). To edit an existing profile, click on the profile row or the **Edit** action button.

---

## Screenshots & Visual Interface

### Queue Profiles Directory
Centralized inventory of contact center ACD queue behavior templates, detailing profile names, descriptions, associated tenant domain, and real-time operational status.
![Queue Profiles List](/screenshots/settings/pbx/queue-profiles-list.png)

### Queue Profile Configuration Form
Granular policy editor defining agent hunt strategies, member timeouts, active call skipping, tier rules and level progression, wrap-up announcement sounds, and maximum wait thresholds.
![Queue Profile Form](/screenshots/settings/pbx/queue-profiles-form.png)

---

## 1. Module Overview (Technical)

### What Are Queue Profiles?

Queue Profiles are **call center configuration templates** that define how queues handle calls, route to agents, manage tiers, and control caller experience. They are assigned to queues in the Queues module.

### Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                Queue Profiles Architecture                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Admin Panel                                                    │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Queue Profiles                                    │   │
│  │                                                          │   │
│  │  Tabs:                                                   │   │
│  │  ├─ General (max wait, no answer, queue size)           │   │
│  │  ├─ Caller Experience (sounds, announcements)           │   │
│  │  ├─ Tier Rules (escalation, wait times)                 │   │
│  │  └─ Advanced (debug, agent cooldown)                    │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Assigned to queues                                     │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Queues Module                                     │   │
│  │                                                          │   │
│  │  Sales Queue → Profile: aggressive-routing              │   │
│  │  Support Queue → Profile: tiered-escalation             │   │
│  │  VIP Queue → Profile: immediate-connect                 │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Applied by queue handler                               │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Queue Lua Handler                                 │   │
│  │                                                          │   │
│  │  Load profile settings → Apply to call                   │   │
│  │  ├─ Tier rule wait times                                │   │
│  │  ├─ Agent routing logic                                 │   │
│  │  ├─ Announcements and sounds                            │   │
│  │  └─ Timeout and delay settings                          │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## 2. Module Overview (Commercial/Business)

### Business Value

Queue Profiles provides **customized call center behavior**:

| Without Profiles | With Profiles |
|------------------|---------------|
| Default handling | Custom routing |
| One-size-fits-all | Different strategies |
| Fixed escalation | Tiered escalation |
| No announcements | Full caller experience |

### Use Cases

1. **Tiered Escalation**
   - Wait times per tier
   - Automatic escalation

2. **Caller Experience**
   - Position announcements
   - Estimated wait time

3. **Agent Optimization**
   - Skip busy agents
   - Cooldown periods

4. **High-Priority Queues**
   - Immediate routing
   - VIP handling

### Feature Highlights

| Feature | Benefit |
|---------|---------|
| **Tier Rules** | Escalation control |
| **Announcements** | Caller experience |
| **Agent Cooldown** | Prevent burnout |
| **Max Queue Size** | Capacity control |
| **Progressive Ring** | Ring more agents |
| **Whisper Tone** | Agent notification |

---

## 3. Module Overview (End User/Administrator)

### What Can You Do?

- Create queue profile templates
- Configure tier escalation rules
- Set caller announcements
- Configure agent timeouts
- Set queue capacity limits
- Enable position/wait time announcements
- Configure progressive ringing

### Queue Profiles Interface

```
┌─────────────────────────────────────────────────────────────────┐
│              Queue Profiles                                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Manage queue profile configurations for call center queues    │
│                                                                 │
│  [+ Create Profile]                                             │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ Name               │ Description         │ Status       │  │
│  ├────────────────────┼─────────────────────┼──────────────┤  │
│  │ default            │ Standard queues     │ ✓ Enabled    │  │
│  │ tiered-escalation  │ Multi-tier routing  │ ✓ Enabled    │  │
│  │ aggressive         │ Fast routing        │ ✓ Enabled    │  │
│  │ vip-priority       │ VIP customers       │ ✓ Enabled    │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Profile Edit View

```
┌─────────────────────────────────────────────────────────────────┐
│              Edit Queue Profile                                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  [General] [Caller Experience] [Tier Rules] [Advanced]         │
│  ─────────────────────────────────────────────────────────────  │
│                                                                 │
│  General Settings                                               │
│                                                                 │
│  Queue Profile Name: [tiered-escalation         ]              │
│                                                                 │
│  Max Wait Agents: [5                ]                          │
│    Maximum number of agents waiting in queue                    │
│                                                                 │
│  Max No Answer: [3                ]                            │
│    Maximum unanswered calls before agent skip                   │
│                                                                 │
│  Queue Max Size: [50               ]                           │
│    Maximum callers in queue (0 = unlimited)                     │
│                                                                 │
│  Agent No-Answer Delay: [10              ]                     │
│    Delay before considering agent unavailable                   │
│                                                                 │
│  Member Delay: [2                ]                             │
│    Delay before ringing member                                  │
│                                                                 │
│  Member Timeout: [30               ]                           │
│    Timeout for member to answer                                 │
│                                                                 │
│  [Save] [Cancel]                                                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Quick Tips

> [!TIP]
> **Tier Rules**: Enable for complex escalation scenarios.

> [!TIP]
> **Agent Cooldown**: Give agents time between calls.

> [!NOTE]
> **Profile Assignment**: Profiles are assigned in Queues module.

---

## 🎯 User Roles & Key Capabilities

| Role | Permissions | Key Capabilities |
|------|-------------|------------------|
| **Super Administrator** | Full Access (`read`, `write`, `delete`) | Configure enterprise ACD queue profiles, define global escalation algorithms, and set agent dispatch thresholds. |
| **Contact Center Supervisor** | Domain Management (`read`, `write`) | Customize agent cooldown wrap-up periods, configure caller queue position announcements, and adjust tier wait escalation times. |
| **Support Specialist** | Read & Diagnostic (`read`) | Audit queue profile settings, diagnose tier escalation delays, and verify queue capacity limits. |
| **Contact Center Agent** | Operational | Receive routed calls according to queue profile policies, respect cooldown timers, and respond to whisper notifications. |

---

## 4. Configuration Tabs

### General Tab

| Field | Description |
|-------|-------------|
| **Queue Profile Name** | Unique identifier |
| **Max Wait Agents** | Agent limit in queue |
| **Max No Answer** | Unanswered calls before skip |
| **Queue Max Size** | Caller capacity limit |
| **Agent No-Answer Delay** | Time before unavailable |
| **Member Delay** | Pre-ring delay |
| **Member Timeout** | Answer timeout |

### Caller Experience Tab

| Field | Description |
|-------|-------------|
| **Announce Hold Time** | Tell caller wait time |
| **Announce Position** | Tell caller queue position |
| **Announce Estimated Hold Time** | Estimated wait announcement |
| **Welcome Sound** | Played on queue entry |
| **Exit Sound** | Played on queue exit |
| **Ringback Tone** | Tone while waiting |
| **Agent Whisper Tone** | Agent notification sound |
| **Play Ringback Before MOH** | Ringback then music |
| **Announce Wrap-up Message** | Post-call message |
| **Announce Resume Playback** | Resume after announcement |

### Tier Rules Tab

| Field | Description |
|-------|-------------|
| **Tier Rules Apply** | Enable tier escalation |
| **Tier Rule Wait** | Seconds per tier |
| **Tier Rule Wait Multiply Level** | Multiply wait by tier level |
| **Tier Rule No Agent No Wait** | Skip empty tiers |
| **Tier Rule Max Wait** | Maximum tier wait |
| **Tier Skip Busy Agents** | Skip busy agents |
| **Tier Randomize Agents** | Random agent selection |
| **Tier No Wait** | Immediate tier skip |
| **Tier Wait Stop Sound** | Sound between tiers |
| **Reserve Agents** | Reserve selected agents |

### Advanced Tab

| Field | Description |
|-------|-------------|
| **Skip Agents With Active Call** | Skip busy agents |
| **Agent Cooldown Time** | Rest time between calls |
| **Agent Busy Delay** | Delay when busy |
| **Agent Reject Delay** | Delay after rejection |
| **Strict Retry** | Strict retry logic |
| **Ring Progressively** | Add agents over time |
| **Log Debug Info** | Enable debug logging |
| **Truncate Agents on Load** | Clear agents on reload |

---

## 5. Settings Reference

### Common Profile Types

| Profile | Settings |
|---------|----------|
| **Default** | Standard settings |
| **Aggressive** | Short timeouts, fast escalation |
| **Tiered** | Multi-tier with wait times |
| **VIP** | Immediate routing, short waits |

### Tier Rule Logic

```
Tier 1: Wait tier_rule_wait seconds
    ↓ (no answer)
Tier 2: Wait tier_rule_wait × 2 seconds (if multiply enabled)
    ↓ (no answer)
Tier 3: Wait tier_rule_wait × 3 seconds
    ↓ (max wait reached)
Exit to destination
```

### Timing Recommendations

| Setting | Typical Value |
|---------|---------------|
| **Member Timeout** | 20-30 seconds |
| **Agent No-Answer Delay** | 5-10 seconds |
| **Tier Rule Wait** | 30-60 seconds |
| **Agent Cooldown** | 5-15 seconds |

---

## 6. Common Scenarios & Examples

### Scenario 1: Basic Queue Profile

1. Create new profile
2. Set Max No Answer = 3
3. Set Member Timeout = 30
4. Enable Announce Position
5. Save

### Scenario 2: Tiered Escalation

1. Create new profile
2. Enable Tier Rules Apply
3. Set Tier Rule Wait = 60 seconds
4. Enable Tier Rule Wait Multiply Level
5. Set Tier Rule No Agent No Wait = Yes
6. Save

### Scenario 3: VIP Priority

1. Create new profile
2. Set Member Delay = 0
3. Set Member Timeout = 15
4. Set Tier Rule Wait = 15
5. Enable Announce Estimated Hold Time
6. Save

### Scenario 4: Agent-Friendly

1. Create new profile
2. Set Agent Cooldown Time = 10
3. Set Max No Answer = 2
4. Enable Skip Agents With Active Call
5. Save

---

## 7. Limitations & Important Notes

### Technical Notes

> [!NOTE]
> **Profile Assignment**: Profiles are assigned in Queues module.

> [!NOTE]
> **Tier Rules**: Require tiers to be configured in queue.

> [!WARNING]
> **High Thresholds**: Very high member timeouts can frustrate callers.

### Best Practices

1. **Balance Wait Times**: Not too long, not too short
2. **Enable Announcements**: Keep callers informed
3. **Use Cooldowns**: Prevent agent burnout
4. **Test Tier Rules**: Verify escalation works
5. **Monitor Metrics**: Adjust based on data

### Tier Rule Behavior

| Flag | Effect |
|------|--------|
| **Multiply Level** | Tier 2 waits 2x, Tier 3 waits 3x |
| **No Agent No Wait** | Skip tiers with no agents |
| **Skip Busy Agents** | Don't offer to busy agents |
| **Randomize Agents** | Random within tier |

---

## 8. Troubleshooting Tips

### Common Issues

| Symptom | Possible Cause | Solution |
|---------|---------------|----------|
| Calls not escalating | Tier rules disabled | Enable Tier Rules Apply |
| Agent overloaded | No cooldown | Set Agent Cooldown Time |
| Queue full | Max size reached | Increase Queue Max Size |
| Long wait times | Slow escalation | Reduce Tier Rule Wait |
| No announcements | Not enabled | Enable Announce Position |

### Check Profile Settings

```sql
SELECT 
  name,
  settings
FROM public.queue_profiles
WHERE name = 'profile-name';
```

### Debug Tier Escalation

1. Enable Log Debug Info
2. Monitor Telephony Server logs
3. Check tier transitions
4. Verify agent availability

---

## 9. Glossary

| Term | Definition |
|------|------------|
| **Queue Profile** | Queue behavior template |
| **Tier** | Agent priority level |
| **Tier Rule Wait** | Time per tier level |
| **Escalation** | Moving to next tier |
| **Cooldown** | Rest time between calls |
| **Member Timeout** | Agent ring time |
| **Whisper Tone** | Agent notification |

---

## Model Context Protocol (MCP) AI Integration

The Ring2All PBX platform integrates deep AI assistance via the Model Context Protocol (MCP). The Queue Profiles module provides comprehensive tools that allow the PBX AI Copilot to query ACD distribution templates, create or update queue policies, inspect tier escalation settings, and verify caller wait-time parameters.

### Available MCP Tools

| Tool Name | Operation Type | RBAC Risk Level | Description |
|-----------|----------------|-----------------|-------------|
| `list_queue_profiles` | Read / Query | `low` | Lists all Queue Profiles in the PBX (call center configuration templates controlling queue timeouts, tier rules, and caller experience). |
| `get_queue_profile_status` | Read / Details | `low` | Retrieves the detailed configuration, timers, and assigned queues of a specific Queue Profile by name or ID. |
| `create_queue_profile` | Write / Creation | `medium` | Creates a new ACD queue profile template with customizable member delays, timeouts, and tier escalation rules. |
| `update_queue_profile` | Write / Update | `medium` | Updates an existing Queue Profile template's settings, timers, or enabled status. |
| `delete_queue_profile` | Delete | `high` | Deletes a Queue Profile template after verifying no active call center queues are currently using it. |

### Tool Input Schemas & Parameters

#### 1. `list_queue_profiles`
```json
{
  "name": "list_queue_profiles",
  "description": "List all Queue Profiles in the PBX.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "search": {
        "type": "string",
        "description": "Filter by profile name or description (e.g. 'Support Tier 1', 'VIP Escalation')."
      }
    }
  }
}
```

#### 2. `get_queue_profile_status`
```json
{
  "name": "get_queue_profile_status",
  "description": "Get configuration and settings of a Queue Profile by name or ID.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "identifier": {
        "type": "string",
        "description": "The name or numeric ID of the queue profile (e.g. 'Default Profile' or '1')."
      }
    },
    "required": ["identifier"]
  }
}
```

### Natural Language Prompts

| User Request | Invoked MCP Tool | Expected AI Response |
|--------------|------------------|----------------------|
| *"Show me all ACD queue profiles configured for our contact center."* | `list_queue_profiles` | Returns table of queue profiles with member timeouts, tier escalation flags, and assigned queue counts. |
| *"Inspect the escalation settings on the 'Sales Aggressive' queue profile."* | `get_queue_profile_status({ identifier: "Sales Aggressive" })` | Reports tier rule wait times, agent cooldown duration, and tier level progression. |
| *"Create a new queue profile for Tier 2 Technical Support with a 20-second ring timeout."* | `create_queue_profile({ name: "Tier 2 Tech Support", settings: { memberTimeout: 20, tierRuleWaitSec: 15 } })` | Validates uniqueness and creates profile template, returning the created configuration. |

### Multi-Tenant & Security Safeguards

- **Domain Isolation**: Queue profiles are isolated to the caller's tenant domain (`domain_id`), strictly separating ACD templates between organizations.
- **Unique Name Enforcement**: Profile names are checked case-insensitively (`LOWER(name)`) upon creation and update to prevent duplicate templates.
- **Reference Integrity Protection**: `delete_queue_profile` automatically verifies whether any active call center queue is currently bound to the profile before allowing deletion.
- **Audit Logging**: All creation, modification, and deletion events are permanently tracked in the PBX audit logs.

---

*Documentation last updated: January 2026*