Page tree

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


This is

titleThis wiki has been updated for Version 13 of your PBX GUI

Part of the VQ Plus Commercial Module

Table of Contents


Queue Penalty Rules are part of the VQ Plus commercial module. This component allows you to assign dynamic queue penalty rules to escalate calls based on the length of hold time. For example, the system might try agents with a penalty of 0 for the first 30 seconds, then agents with penalties of 0 and 1 for the next minute.

This wiki assumes you are familiar with assigning agent penalties in the Queues module. For more information on how to do this, please see the Queues Module User Guide.


By default app_queue in asterisk handles agent penalties in a fashion some people do not like. Asterisk tries to call the lowest-numbered penalty group first. Only if nobody in that group is able to take a call does the system escalate to calling the next group. Any agent logged into the queue who is not paused or on a call is considered available to take a call. This means if you have one agent who has stepped away from their phone and they are in penalty group 1, the queue will never move on to calling a higher penalty group until that agent either is logged out, paused, or on a call, or until the queue's minimum penalty is changed to be greater than that agent's penalty.

One way to get around this is to enable auto-pause in the queue page in the PBX GUI. This will automatically pause agents when they miss a call, until they unpause themselves. When paused, the agent will not be considered available.

The other way around this is to use the lazymember patch that we have built and included in Asterisk 11 and newer on FreePBX Distro and PBXact systems only. This will force app_queue to mark the agent who does not answer a call as "busy" for the current caller, which will allow app_queue to move on to the next penalty group. Once all agents in all penalties have been called for that inbound call, the system will reset the temporary "busy" and restart the cycle again. You can turn on lazymembers on a per-queue basis in the queue module in the PBX GUI.

Navigating to Queue Penalty Rules

  • Log into the PBX GUI
  • In the top menu go to Admin
  • In the drop-down menu go to Queue Penalty Rules

Creating a Queue Penalty Rule

A queue penalty rule dynamically changes the minimum and/or maximum agent penalties that will be tried, based upon how long the caller has been waiting.

Click the New Rule Set button.

Image Added


Enter a friendly name for this queue penalty rule set to help you identify it.

Image Added

Queue Rules Table

This table is a list of penalty change rules. You can enter one or more rules, and they will be applied in order from top to bottom.

Image Added


The number of seconds prior to making the prescribed rule change. This is NOT the absolute time as used in queuerules.conf. For the first rule in the list, the duration is the time since the caller entered the queue. For all subsequent rules, the duration is the time since the previous rule was applied.

Max Penalty Change

The new QUEUE_MAX_PENALTY value. This can be entered as an absolute penalty value by entering a number. Or, it can be entered as a change in penalty by prepending a "+" or "-" before the number.

For example, to set the new maximum penalty to 1, enter "1." To increase the previous penalty by 1, enter "+1."

Min Penalty Change

The new QUEUE_MIN_PENALTY value. As with the max penalty change above, you can enter an absolute value here, or you can use "+" or "-" before the number to define a change in value.


You do not have to change bothmaximum and minimum penalties at the same time. For example, you can define a rule that keeps the same max penalty as the previous rule, while only adjusting the minimum penalty.


Click the Submit button, then click the Apply Config button.

Next, visit the Queue Plus options tab within the Queues module to link your queue penalty rule to a queue, as described below.

Linking a Queue Penalty Rule to a Queue

After you have created your ruleset as described above, you can apply the queue penalty rule to a queue.

This option is found in the Queue Plus Options tab when editing a queue in the Queues module.

For more info, see the VQ Plus Options in Queues wiki.