Controlling Queue Members via the CLI

We can add queue members to any available queue through the Asterisk CLI command queue add. The format of the queue add command is (all on one line):

*CLI> queue add member channel to queue [[[penalty penalty] as 
membername] state_interface interface]

The channel is the channel we want to add to the queue, such as SIP/0000FFFF0003, and the queue name will be something like support or sales—any queue name that exists in /etc/asterisk/queues.conf. For now we’ll ignore the penalty option, but we’ll discuss it in “Advanced Queues” (penalty is used to control the rank of a member within a queue, which can be important for agents who are logged into multiple queues, or have differing skills). We can define the membername to provide details to the queue-logging engine.

The state_interface option informs the queue of the device state to be monitored for this agent. The details of how to work with device states are discussed in Chapter 13. Go ahead and work through that chapter, and then come back here and continue on. Don’t worry, we’ll wait.

Now that you’ve added callcounter=yes to sip.conf (we’ll be using SIP channels throughout the rest of our examples), let’s see how to add members to our queues from the Asterisk CLI.

Adding a queue member to the support queue can be done with the queue add member command:

*CLI> queue add member PJSIP/SOFTPHONE_B to support 

Added interface 'PJSIP/SOFTPHONE_B' to queue 'support'

A query of the queue will verify that our new member has been added:

*CLI> queue show support

support has 0 calls (max unlimited) in 'rrmemory' strategy (0s holdtime, 0s talktime), 
W:0, C:0, A:0, SL:0.0%, SL2:0.0% within 0s
   Members:
      PJSIP/SOFTPHONE_B (ringinuse disabled) (dynamic) (Not in use) has taken no calls yet
   No Callers

To remove a queue member, you would use the queue remove member command:

*CLI> queue remove member PJSIP/SOFTPHONE_B from support

Removed interface PJSIP/SOFTPHONE_B from queue 'support'

Of course, you can use the queue show command again to verify that your member has been removed from the queue:

*CLI> queue show support

support has 0 calls (max unlimited) in 'rrmemory' strategy (0s holdtime, 0s talktime), 
W:0, C:0, A:0, SL:0.0%, SL2:0.0% within 0s
   Members:
      PJSIP/SOFTPHONE_B (ringinuse disabled) (dynamic) (Not in use) has taken no calls yet
   No Callers

We can also pause and unpause members in a queue from the Asterisk console, with the queue pause member and queue unpause member commands. They take a similar format to the previous commands we’ve been using:

*CLI> queue pause member PJSIP/SOFTPHONE_B queue support reason Callbacks

paused interface 'PJSIP/SOFTPHONE_B' in queue 'support' for reason 'Callbacks'

*CLI> queue show support
support      has 0 calls (max unlimited) in 'rrmemory' strategy 
(0s holdtime, 0s talktime), W:0, C:0, A:0, SL:0.0% within 0s
   Members: 
      SIP/0000FFFF0001 (dynamic) (paused) (Not in use) has taken no calls yet
   No Callers

*CLI> queue show support

support has 0 calls (max unlimited) in 'rrmemory' strategy (0s holdtime, 0s talktime), 
 W:0, C:0, A:0, SL:0.0%, SL2:0.0% within 0s
   Members:
      PJSIP/SOFTPHONE_B (ringinuse disabled) (dynamic) (paused:Callbacks) (Not in use) 
has taken no calls yet
   No Callers

By adding a reason for pausing the queue member, such as lunchtime, you ensure that your queue logs will contain some additional information that may be useful. Here’s how to unpause the member:

*CLI> queue unpause member PJSIP/SOFTPHONE_B queue support reason FinishedCallBacks 

unpaused interface 'PJSIP/SOFTPHONE_B' in queue 'support' for reason 'FinishedCallbacks'

In a production environment, the CLI would not normally be the best way to control the state of agents in a queue. Instead, there are dialplan applications that allow agents to inform the queue as to their availability.

Defining Queue Members in the queue_members Table

If you define a queue member in the asterisk.queue_members table of the database, that member will always be logged into the queue. This usually doesn’t work well if your members are human beings, since humans tend to get up and move about.

Within each queue definition, you simply define the members thus:

MySQL> insert into `asterisk`.`queue_members`
(queue_name,interface,penalty)

VALUES
'hotline','PJSIP/SOME_NON_HUMAN','0');

In a typical queue (one in which you have a group of people responsible for answering calls), you will find that defining the members in the queue_members table might not serve you well. Human agents usually need to be able to log in and out (and not be automatically logged in whenever the queue is reloaded). We do not recommend defining members in the queue_members table unless they have some other purpose (such as a bank of devices that answer calls, where you want to use the queue to load-balance calls to the device pool, or a ring group, where all phones ring for all calls all the time regardless of whether anyone is sitting near the phone).

Controlling Queue Members with Dialplan Logic

In a call center staffed by live agents, it is most common to have the agents themselves log in and log out at the start and end of their shifts (or whenever they go for lunch, or to the bathroom, or are otherwise not available to the queue).

To enable this, we will make use of the following dialplan applications:

• AddQueueMember()

• RemoveQueueMember()

While logged into a queue, it may be that an agent needs to put themself into a state where they are temporarily unavailable to take calls. The following applications will allow this:

• PauseQueueMember()

• UnpauseQueueMember()

The Add/Remove applications are used to log in and log out, and Pause/Unpause are used for short periods of agent unavailability. The difference is simply that Pause and Unpause set the member as unavailable/available without actually removing them from the queue. This is mostly useful for reporting purposes (if a member is paused, the queue supervisor can see that they are logged into the queue, but simply not available to take calls at that moment). If you’re not sure which one to use, we recommend that the agents use Add/Remove whenever they are not physically at their phone, and Pause/Unpause when they are at their desk, but temporarily not available.

If in doubt, it’s usually better to have your agents log out.

Let’s build some simple dialplan logic that will allow our agents to indicate their availability to the queue. We are going to use the CUT() dialplan function to extract the name of our channel from our call to the system, so that the queue will know which channel to log into the queue.

We have built this dialplan to show a simple process for logging into and out of a queue, and changing the paused status of a member in a queue. We are doing this only for a single queue that we previously defined in the queues.conf file. The status channel variables that the AddQueueMember(), RemoveQueueMember(), PauseQueueMember(), and UnpauseQueueMember() applications set might be used to Playback() announcements to the queue members after they’ve performed certain functions to let them know whether they have successfully logged in/out or paused/unpaused:

exten => *731,1,Page(${PAGELIST},i,120)

exten => *732,1,Verbose(2,Logging In Queue Member)
   same => n,Set(MemberChannel=${CHANNEL(channeltype)}/${CHANNEL(endpoint)})
   same => n,AddQueueMember(support,${MemberChannel})
   same => n,Verbose(1,${AQMSTATUS}) ; ADDED, MEMBERALREADY, NOSUCHQUEUE
   same => n,Playback(agent-loginok)
   same => n,Hangup()

exten => *733,1,Verbose(2,Logging Out Queue Member)
   same => n,Set(MemberChannel=${CHANNEL(channeltype)}/${CHANNEL(endpoint)})
   same => n,RemoveQueueMember(support,${MemberChannel})
   same => n,Verbose(1,${RQMSTATUS}) ; REMOVED, NOTINQUEUE, NOSUCHQUEUE
   same => n,Playback(agent-loggedoff)
   same => n,Hangup()

exten => *734,1,Verbose(2,Pause Queue Member)
   same => n,Set(MemberChannel=${CHANNEL(channeltype)}/${CHANNEL(endpoint)})
   same => n,PauseQueueMember(support,${MemberChannel})
   same => n,Verbose(1,${PQMSTATUS}) ; PAUSED, NOTFOUND
   same => n,Playback(dictate/paused)
   same => n,Hangup()

exten => *735,1,Verbose(2,Unpause Queue Member)
   same => n,Set(MemberChannel=${CHANNEL(channeltype)}/${CHANNEL(endpoint)})
   same => n,UnpauseQueueMember(support,${MemberChannel})
   same => n,Verbose(1,${UPQMSTATUS}) ; UNPAUSED, NOTFOUND
   same => n,Playback(agent-loginok)
   same => n,Hangup()

exten => *98,1,NoOp(Access voicemail retrieval.)

Automatically Logging Into and Out of Multiple Queues

It is quite common for an agent to be a member of more than one queue. Rather than having a separate extension for logging into each queue (or demanding information from the agents about which queues they want to log into), this code uses the Asterisk database (astdb) to store queue membership information for each agent, and then loops through each queue the agents are a member of, logging them into each one in turn.

In order for this code to work, an entry similar to the following will need to be added to the AstDB via the Asterisk CLI. For example, the following would store the member SOFTPHONE_A as being in both the support and sales queues:³

*CLI> database put queue_agent SOFTPHONE_A/available_queues support^sales

You will need to do this once for each agent, regardless of how many queues they are members of.

If you then query the Asterisk database, you should get a result similar to the following:

pbx*CLI> database show queue_agent
/queue_agent/SOFTPHONE_A/available_queues         : support^sales

The following dialplan code is an example of how to allow this queue member to be automatically added to both the support and sales queues. We’ve defined a subroutine that is used to set up three channel variables (MemberChannel, MemberChanType, AvailableQueues). These channel variables are then used by the login (*736), logout (*737), pause (*738), and unpause (*739) extensions. Each of the extensions uses the subSetupAvailableQueues subroutine to set these channel variables and to verify that the AstDB contains a list of one or more queues for the device the queue member is calling from.

Near the end of your extensions.conf file, where you’ve put your subroutines, add the following:

[subSetupAvailableQueues]
; This subroutine is used by the various login/logout/pausing/unpausing routines
; in our multiple queue login example.
;
exten => start,1,Verbose(2,Checking for available queues)
; Get the current channel's peer name
   same => n,Set(MemberChannel=${CHANNEL(endpoint)})
; Get the current channel's technology type
   same => n,Set(MemberChanType=${CHANNEL(channeltype)})
; Get the list of queues available for this agent
   same => n,Set(AvailableQueues=${DB(queue_agent/${MemberChannel}/available_queues)})
; if there are no queues assigned to this agent we'll handle it in the
; no_queues_available extension
   same => n,GotoIf($[${ISNULL(${AvailableQueues})}]?no_queues_available,1)
   same => n,Return()

exten => no_queues_available,1,Verbose(2,No queues available for agent ${MemberChannel})
; playback a message stating the channel has not yet been assigned
   same => n,Playback(silence/1&channel&not-yet-assigned)
   same => n,Hangup()

Next, in your [sets] context, add the following:

; Logging into multiple queues via the AstDB system
exten => *736,1,Verbose(2,Logging into multiple queues per the database values)
; get the available queues for this channel
   same => n,GoSub(subSetupAvailableQueues,start,1())
   same => n,Set(QueueCounter=1)  ; setup a counter variable
; using CUT(), get the first listed queue returned from the AstDB
; Note that we've used '^' as our delimiter
   same => n,Set(WorkingQueue=${CUT(AvailableQueues,^,${QueueCounter})})
; While the WorkingQueue channel variable contains a value, loop
   same => n,While($[${EXISTS(${WorkingQueue})}])
; AddQueueMember(queuename[,interface[,penalty[,options[,membername
;  [,stateinterface]]]]])
; Add the channel to a queue, setting the interface for calling
; and the interface for monitoring of device state
; *** This should all be on a single line
     same => n,AddQueueMember(
     ${WorkingQueue},${MemberChanType}/${MemberChannel},,,${MemberChanType}/${MemberChannel})
     same => n,Set(QueueCounter=$[${QueueCounter} + 1])    ; increase our counter
; get the next available queue; if it is null our loop will end
     same => n,Set(WorkingQueue=${CUT(AvailableQueues,^,${QueueCounter})})
     same => n,EndWhile()
; let the agent know they were logged in okay
   same => n,Playback(silence/1&agent-loginok)
   same => n,Hangup()

exten => no_queues_available,1,Verbose(2,No queues available for ${MemberChannel})
   same => n,Playback(silence/1&channel&not-yet-assigned)
   same => n,Hangup()

; Used for logging agents out of all configured queues per the AstDB
exten => *737,1,Verbose(2,Logging out of multiple queues)
; Because we reused some code, we've placed the duplicate code into a subroutine
   same => n,GoSub(subSetupAvailableQueues,start,1())
   same => n,Set(QueueCounter=1)
   same => n,Set(WorkingQueue=${CUT(AvailableQueues,^,${QueueCounter})})
   same => n,While($[${EXISTS(${WorkingQueue})}])
   same => n,RemoveQueueMember(${WorkingQueue},${MemberChanType}/${MemberChannel})
   same => n,Set(QueueCounter=$[${QueueCounter} + 1])
   same => n,Set(WorkingQueue=${CUT(AvailableQueues,^,${QueueCounter})})
   same => n,EndWhile()
   same => n,Playback(silence/1&agent-loggedoff)
   same => n,Hangup()

; Used for pausing agents in all available queues
exten => *738,1,Verbose(2,Pausing member in all queues)
   same => n,GoSub(subSetupAvailableQueues,start,1())
   ; if we don't define a queue, the member is paused in all queues
   same => n,PauseQueueMember(,${MemberChanType}/${MemberChannel})
   same => n,GotoIf($[${PQMSTATUS} = PAUSED]?agent_paused,1:agent_not_found,1)

exten => agent_paused,1,Verbose(2,Agent paused successfully)
   same => n,Playback(dictate/paused)
   same => n,Hangup()

; Used for unpausing agents in all available queues
exten => *739,1,Verbose(2,UnPausing member in all queues)
   same => n,GoSub(subSetupAvailableQueues,start,1())
   ; if we don't define a queue, then the member is unpaused from all queues
   same => n,UnPauseQueueMember(,${MemberChanType}/${MemberChannel})
   same => n,GotoIf($[${UPQMSTATUS} = UNPAUSED]?agent_unpaused,1:agent_not_found,1)

exten => agent_unpaused,1,Verbose(2,Agent paused successfully)
   same => n,Playback(silence/1&available)

; Used by both pausing and unpausing dialplan functionality
exten => agent_not_found,1,Verbose(2,Agent was not found)
   same => n,Playback(silence/1&cannot-complete-as-dialed)

You could further refine these login and logout routines to take into account that the AQMSTATUS and RQMSTATUS channel variables are set each time AddQueueMember() and RemoveQueueMember() are used. For example, you could set a flag that lets the queue member know they have not been added to a queue, or even add recordings or text-to-speech systems to play back the particular queue that is producing the problem. Or, if you’re monitoring this via the Asterisk Manager Interface, you could have a screen pop, or use JabberSend() to inform the queue member via instant messaging, or…(ain’t Asterisk fun?).

Priority Queue (Queue Weighting)

Sometimes you need to add people to a queue at a higher priority than that given to other callers. Perhaps the caller has already spent time waiting in a queue, and an agent has taken some information but realized the caller needed to be transferred to another queue. In this case, to minimize the caller’s overall wait time, it might be desirable to transfer the call to a priority queue that has a higher weight (and thus a higher preference), so it will be answered quickly.

Setting a higher priority on a queue is done with the weight option. If you have two queues with differing weights (e.g., support and support-priority), agents assigned to both queues will be passed calls from the higher-priority queue in preference to calls from the lower-priority queue. Those agents will not take any calls from the lower-priority queue until the higher-priority queue is cleared. (Normally, there will be some agents who are assigned only to the lower-priority queue, to ensure that those calls are dealt with in a timely manner.) For example, if we place queue member James Shaw into both the support and support-priority queues, callers in the support-priority queue will have a preferred standing with James over callers in the support queue.

Let’s take a look at how we could make this work. First, we need to create a new queue that’s similar to the support queue except for the weight option.

MySQL> INSERT INTO `asterisk`.`queues` 
(name,strategy,joinempty,leavewhenempty,ringinuse,autofill,musiconhold,monitor_format,
monitor_type,weight) 

VALUES
('support-priority','rrmemory','unavailable,invalid,unknown','unavailable,invalid,unknown',
'no','yes','default','wav','MixMonitor','10');

With our new queue configured, we can now create two extensions to transfer callers to. This can be done wherever you would normally place your dialplan logic to perform transfers. We’re going to use the LocalSets context, which we’ve previously enabled as the starting context for our devices:

exten => 611,1,Noop()
  same => n,Progress()
  same => n,Queue(support)
  same => n,Hangup()

exten => 612,1,Noop()
  same => n,Progress()
  same => n,Queue(support-priority)
  same => n,Hangup()

exten => *724,1,Noop(Page)

The only other configuration left to do is to make sure some or all of your queue members are placed in both queues.

Queue Member Priority

Within a queue, we can apply a penalty to members in order to lower their preference for being called when there are people waiting in a particular queue. For example, we may penalize queue members when we want them to be a member of a queue, but only receive calls when the queue gets full enough that all our preferred agents are unavailable. By defining different penalties for each member of the queue,⁴ we can help control the preference for where callers are delivered, but still ensure that other queue members will be available to answer calls if the preferred member is unavailable.

Penalties can also be defined using AddQueueMember(). We’ll modify our multiple queue login to provide the required penalties.

First, let’s update our AstDB to include penalties for a member:

*CLI> database put queue_agent SOFTPHONE_A/penalty 0^2 

*CLI> database show queue agent 

/queue_agent/SOFTPHONE_A/available_queues         : support^sales
/queue_agent/SOFTPHONE_A/penalty                  : 0^2

Next, a few tweaks to our dialplan.

The subroutine needs a new line (some code has been removed for brevity, replaced with ;...):

[subSetupAvailableQueues]
; ...
; Get the list of queues available for this agent
   same => n,Set(AvailableQueues=${DB(queue_agent/${MemberChannel}/available_queues)})
   same => n,Set(MemberPenalties=${DB(queue_agent/${MemberChannel}/penalty)})
; if there are no queues assigned ...

The [sets] context requires a couple of new lines as well (some code has been removed for brevity, replaced with ;...). Only insert/change the code written in bold.

exten => *736,1,Verbose(2,Logging into multiple queues per the database values)
; ...
   same => n,Set(WorkingQueue=${CUT(AvailableQueues,^,${QueueCounter})})
   same => n,Set(WorkingPenalty=${CUT(MemberPenalties,^,${QueueCounter})}) 
; While the WorkingQueue ...
; ...
     same => n,Set(WorkingQueue=${CUT(AvailableQueues,^,${QueueCounter})})
     same => n,Set(WorkingPenalty=${CUT(MemberPenalties,^,${QueueCounter})})
     same => n,EndWhile()
; ...

These examples are probably not suitable for a production environment (we’d use purpose-built MySQL tables for this sort of thing rather than AstDB), but it gives you an idea of how the dialplan can be used to apply dynamic logic to more complex configuration scenarios.

Changing Penalties Dynamically (queuerules)

Using the asterisk.queuerules table, it is possible to define rules that change the values of the QUEUE_MIN_PENALTY and QUEUE_MAX_PENALTY channel variables. The QUEUE_MIN_PENALTY and QUEUE_MAX_PENALTY channel variables are used to control which members of a queue are preferred for servicing callers. Let’s say we have a queue called support, and we have five queue members with various penalties ranging from 1 through 5. If, prior to a caller entering the queue, the QUEUE_MIN_PENALTY channel variable is set to a value of 2 and the QUEUE_MAX_PENALTY is set to a value of 4, only queue members whose penalties are set to values ranging from 2 through 4 will be considered available to answer that call:

   same => n,Set(QUEUE_MIN_PENALTY=2)   ; set minimum member penalty
   same => n,Set(QUEUE_MAX_PENALTY=4)   ; set maximum member penalty
   same => n,Queue(support)             ; entering the queue with min and max 
                                        ; member penalties to be used

What’s more, during the caller’s stay in the queue, we can dynamically change the values of QUEUE_MIN_PENALTY and QUEUE_MAX_PENALTY for that caller. This allows either more or a different set of queue members to be used, depending on how long the caller waits in the queue. For instance, in the previous example, we could modify the minimum penalty to 1 and the maximum penalty to 5 if the caller has to wait more than 60 seconds in the queue.

The sample file ~/src/asterisk-15.<TAB>/configs/samples/queuerules.conf.sample contains an excellent reference for how queue rules work.

The rules are defined using the asterisk.queuerules table. Multiple rules can be created in order to facilitate different penalty changes throughout the call. Let’s take a look at how we might choose to define a rule:

MySQL> insert into `asterisk`.`queue_rules`
(rule_name,time,min_penalty,max_penalty)

VALUES
('more_members',60,5,1);

We’ve named the rule more_members and defined the following values:

60

The number of seconds to wait before changing the penalty values.

5

The new QUEUE_MAX_PENALTY.

1

The new QUEUE_MIN_PENALTY.

We can now tell our queues to make use of it.

MySQL> update `asterisk`.`queues`

set defaultrule='more_members' where `name` in ('sales','support')

The queuerules.conf.sample file shows that these rules are quite flexible. If you want fine-grained control over call prioritization, some additional lab work may be worth your while.

Announcement Control

Asterisk has the ability to play several announcements to callers waiting in the queue. For example, you might want to announce the caller’s position in the queue, announce the average wait time, or periodically thank your callers for waiting (or whatever your audio files say). It’s important to carefully tune the values that control when these announcements are played to the callers, because announcing their position, thanking them for waiting, and informing them of the average hold time too frequently is going to tend to annoy them, which is not the goal of these things.

There are several options in the queues table that you can use to fine-tune what and when announcements are played to your callers. The full list of queue options is available in the ~/src/asterisk-15.<TAB>/configs/samples/queues.conf.sample file. Table 12-3 reviews a few of the more useful ones.

Table 12-4 defines the files that will be used when announcements are played to the caller.

There’s a ton of flexibility possible when designing a caller’s experience while they’re waiting, but please don’t forget that your callers will never be happy to be waiting in the queue. Also, if you’ve found some half-decent hold music, and your callers are enjoying it, an interruption to play yet another message runs the risk of really setting their blood boiling. When they are finally answered, your poor agents will get the brunt of their anger, even though it is actually your fault.⁵

So keep your on-hold tweaking simple. Callers know they’re waiting, and they aren’t going to be happy about it. Get them to an agent as quickly as possible, with the bare minimum amount of silliness while they’re holding, and don’t succumb to the temptation of making the queue more important to your callers than it actually is.

Overflow

Unfortunately, your queue will not always get your callers to an agent in a timely manner. When various conditions cause the queue to reject incoming callers, we have an overflow situation. Overflowing out of the queue is done either with a timeout value or when no queue members are available (as defined by joinempty or leavewhenempty). In this section we’ll discuss how to control when overflow happens.

; Queue
exten => 610,1,Noop()
  same => n,Progress()
  same => n,Queue(sales,120)
  same => n,Voicemail(${EXTEN}@queues,u)
  same => n,Hangup()

exten => 611,1,Noop()
  same => n,Progress()
  same => n,Queue(support,120)
  same => n,Voicemail(${EXTEN}@queues,u)
  same => n,Hangup()

exten => 612,1,Noop()
  same => n,Progress()
  same => n,Queue(support-priority,120)
  same => n,Voicemail(${EXTEN}@queues,u)
  same => n,Hangup()

MySQL> INSERT INTO `asterisk`.`voicemail` 
(context,mailbox,password,fullname,email) 

VALUES
('queues','610','192837','Queue sales','[email protected]'), 
('queues','611','192837','Queue support','[email protected]'), 
('queues','612','192837','Queue support-priority','[email protected]');

MySQL> update `asterisk`.`queues` set timeoutpriority='conf' 
  where name in ('sales','support','support-priority');

joinempty=unavailable,invalid,unknown

leavewhenempty=unavailable,invalid,unknown

Using Local Channels

The use of local channels as queue members is a powerful way of executing dialplan code prior to dialing the actual agent’s device. When Queue() decides to present a call to an agent, using local channels allows us to define custom channel variables, write to a logfile, set some limit on call length (e.g., if it is a paid service), send messages of all sorts all over the place, perform database transactions, and perform many of the other actions we might wish to do at that exact moment. Normally, we have no control over when the Queue() application has decided to present a caller to a specific member, but with local channels, we get one final kick at the can, and can even return Congestion(), which will have the effect of returning the caller to the queue, since the queue will not consider this call to have been successfully delivered to an agent (this can be very handy, since some external condition can be evaluated before the call is just fired off to an endpoint).

When using local channels for queues, they are added just like any other channels, typically dynamically through the AddQueueMember() dialplan application.

We’ll need to define the local channel where all the magic happens, and since local channels are typically used in a manner similar to subroutines, we like to name and locate them in the dialplan with the subroutines, with a context name starting with local (akin to how subroutines start with sub). If you’ve been building out your dialplan along with the book, you’ll notice you already have a local channel [localDialDelay]. Add this code somewhere in that part of the dialplan.

[localMemberConnector] 
exten => _[A-Za-z0-9].,1,Verbose(2,Connect ${CALLERID(all)} to Agent at ${EXTEN})
   ; filter out any bad characters, allow alphanumeric chars and hyphen
   same => n,Set(QueueMember=${FILTER(A-Za-z0-9-,${EXTEN})})
   ; assign the first field of QueueMember to Technology; hyphen as separator
   same => n,Set(Technology=${CUT(QueueMember,-,1)})
   ; assign the second field of QueueMember to Device using the hyphen separator
   same => n,Set(Device=${CUT(QueueMember,-,2)})
   ; dial the agent
   same => n,Dial(${Technology}/${Device})
   same => n,Hangup()

This code might not make total sense just yet, but what it’s doing is taking the ${EXTEN} (which is a complex alphanumeric string at this point), and slicing and dicing it to extract the actual channel to be called (i.e., we pass as part of the local channel all the information needed to dial the actual channel).

Let’s look at the AddQueueMember code and see if we can make more sense of this:

exten => *740,1,Noop(Logging in device ${CHANNEL(endpoint)} into the support queue)
   same => n,Set(MemberTech=${CHANNEL(channeltype)})
   same => n,Set(MemberIdent=${CHANNEL(endpoint)})
   same => n,Set(Interface=${MemberTech}/${MemberIdent})
   ;;; THE FOLLOWING SHOULD ALL BE ON ONE LINE
same => n,AddQueueMember(support,Local/${MemberTech}-${MemberIdent}@localMemberConnector
,,,${IF($[${MemberTech} = PJSIP]?${Interface})})
   same => n,Playback(silence/1)
   same => n,Playback(${IF($[${AQMSTATUS} = ADDED]?agent-loginok:agent-incorrect)})
   same => n,Hangup()

Once you’ve input all this and reloaded your dialplan, log into the queue by dialing *740, and let’s see what we’ve got.

*CLI> queue show support

support has 0 calls (max unlimited) in 'rrmemory' strategy (1s holdtime, 0s talktime), 
W:0, C:1, A:1, SL:0.0%, SL2:0.0% within 0s
   Members:
      PJSIP/SOFTPHONE_A (Local/PJSIP-SOFTPHONE_A@localMemberConnector) 
(ringinuse disabled) (dynamic) (Not in use)
   No Callers

The member is now identified to the queue as a local channel named PJSIP-SOFTPHONE_A in the [localMemberConnector] context. (The PJSIP/SOFTPHONE_A channel will be monitored for actual status of the endpoint.) When Queue() decides to send a call to the member, the call will end up in the [localMemberConnector] context, where the EXTEN (PJSIP-SOFTPHONE_A) will be sliced and diced in order to yield our channel type and endpoint,⁷ which is what will actually be called.

At this point, the purpose of all this extra complexity is not immediately clear. So far we don’t get anything useful out of all this extra code.

So now that we can add devices to the queue using local channels, let’s look at how this might be useful.

Let’s say we have a customer who just can’t stand our best agent. They’re a good customer, so we don’t want to lose them, but it’s our best agent, so we’re not going to fire them.

To set this up, we’re going to assign a caller ID to SOFTPHONE_B, so we have something to match against.

MySQL> UPDATE `asterisk`.`ps_endpoints` SET callerid='SOFTPHONE_B <103>' 
WHERE id='SOFTPHONE_B';

We’re going to build a little trick into our dialplan that will reject the call to the agent if the caller ID matches our sensitive customer.

[localMemberConnector]
exten => _[A-Za-z0-9].,1,Verbose(2,Connect ${CALLERID(all)} to Agent at ${EXTEN})
   same => n,Wait(0.1) ; Prevent loop from completely hogging CPU
   same => n,Set(QueueMember=${FILTER(A-Za-z0-9-_,${EXTEN})}) ; allow alphanum, - , _
   same => n,Set(Technology=${CUT(QueueMember,-,1)}) ; first field, hyphen is separator
   same => n,Set(Device=${CUT(QueueMember,-,2)})     ; second field, hypen separator
   ; is this our mismatched pair?
   same => n,DumpChan()
   same => n,Noop(${CALLERID(all)} : ${Device})
same=>n,GotoIf($["${CALLERID(num)}"="103"&"${Device}"="SOFTPHONE_A"]?rejectcall:ringagent)
   ; dial the agent
   same => n(ringagent),Dial(${Technology}/${Device})
   same => n,Hangup()
   ; send it back!
   same => n(rejectcall),Congestion()
   same => n,Hangup()

The passing back of Congestion() will cause the caller to be returned to the queue (while this is happening, the caller gets no indication that anything is amiss and keeps hearing music until their call is answered by a channel of some sort).⁸ Ideally, your queue is programmed to try another agent; however, you need to keep in mind that if app_queue determines that this member is still its first choice to present the call to, the call will simply be reconnected to the same agent (and get congestion again, and thus potentially create a CPU-hogging logic loop). To avoid this, you will need to ensure your queue is using a distribution strategy such as round_robin, random, or any strategy that ensures the same member is not tried over and over. This is also why we toss a tiny little delay into our [localMemberConnector] context, so if a loop like this does happen, there’s at least a small throttle on it.

Let’s just sanity check our code. Set the caller ID number to something other than 103, and the call should go through.

MySQL> UPDATE `asterisk`.`ps_endpoints` SET callerid='SOFTPHONE_B <123>' 
WHERE id='SOFTPHONE_B';

The use of local channels for your member channels will not make queue design and debugging easier, but it does give you far more power over your queues than just using app_queue on its own, so if you have a complex queue requirement, the use of local channels will give you a level of control you would not have otherwise.