Course13:IT Connect - 07 Waiting Queues

From innovaphone wiki
Jump to navigation Jump to search

How to configure Waiting Queues (also introducing the PBX Manager)

Waiting Queues

A waiting queue is an object in the PBX that
  • can accept multiple calls at the same time
  • distribute it to PBX users who are free to take a call (a.k.a. agents)
  • play an announcement to calling users while they are waiting for an agent
  • interpret DTMF codes to select different routing paths ("press 1 to speak to a sales agent")

Agents can be configured to be member of one or more groups. Such groups are then associated to a waiting queue to define who is an agent to the group.

A very simple use of a waiting queue is a telephone switchboard of a company.

The "Waiting Queues" PBX Manager Plugin

As you might recall from the UsingTrunks topics, PBXManager Plugins are used for configuration work. So, to configure waiting queues, there is a PBXManager plugin called Waiting Queues. This should already be on your home screen. If not, video2.png here is how to put it there.

When you start the Waiting Queue PBXManager plugin, it will list all currently defined queues. As you have none so far, it will show an empty list and a screenshot.png + Add a Waiting Queue button.

Adding a Waiting Queue

When you click on the screenshot.png + Add a Waiting Queue button, you can enter its screenshot.png basic properties:
  • Waiting Queue: the long name of the queue. This is like the ID in a user record and likewise, it must be unique in the system. It also will be screenshot.png shown to agents on the phone when they receive a call via this queue
  • SIP: this is like the Username for a user. It must be unique in the system and can be used to call the queue

    (Further Hints) As the requirements for SIP are equivalent to the requirements for the Username, you can use the same rule of thumb: only use A-Z, a-z, 0-9 as wells as . (dot) and - (hyphen). SIP must not start with a . (dot) however

  • Number: this is like the Extension for the user. It must be unique in the system and can be used to call the queue

    Note that both SIP and Number are optional. However, if you leave both blank, the waiting call can not be called directly (although it might still be used as a switchboard)
Go ahead and create your first waiting queue and set
  • Waiting Queue to Headquarter Switchboard
  • SIP to hqswb
  • and Number to 40
Congratulation, you have created your first waiting queue!
You can video2.png call it right away. However, nobody will ever take the call. We first need to define who the agents for the queue will be.

We'll look at the queue's detail settings in the next sections. You open the details section for a queue by video2.png clicking on the respective line in the list of defined queues.

Defining the Queue Agents

In general, PBX users can be structured into groups and this mechanism is used to define the agents that will serve a group. In other words, a group is created and users are added to it. Then the group is set as "the" group that defines the agents for a queue.

The plugin will create a new group for the waiting queue when you click on the + sign underneath the Agents area. This group is called like the queue's SIP property with an index appended (hqswb-0 in our case).

In the Add a group dialogue, you can select the agents to be added to the group.

Let us video2.png add an agent group to our waiting queue and put yourself and Lisa Svensson into it!

If you now video2.png call the queue from Jean Dupont, you will hear it ring on Lisa's and your own phone.

Adding a second level Group of Agents

Unfortunately, you are busy following the training and Lisa seems to be lazy - nobody takes the call. It therefore would be nice to add another group of agents to the queue. These agents would be called if none of the first agents takes the call.

The waiting queue can do that. You might have observed the screenshot.png primary check-mark in the queue's agent group definition. It was checked by default. This suggests that there may also be a secondary group. And indeed, you can add another group of agents to the queue which is not ticked as primary.

To get a better behaviour, video2.png add a new group to the queue and add Mario Rossi as an agent to it.

When you now call the queue from Jean, you will see (and hear) that all the agents (yourself, Lisa and Mario) ring immediately. That was not the idea! The thing that is missing is to define the timeout for the switch-over to the secondary group. In this case, the PBX does it at once. This timeout is called Primary Group Timeout and can be found in the Settings section of the queue definition and is given as the number of seconds.

Configure video2.png a timeout of 5 seconds and try the call from Jean again. Now, video2.png Mario's phone will ring only after 5 s.

There are some more properties in the Settings section which allow you to create much more sophisticated behaviours. For now, it is OK if you remember the Primary Group Timeout setting and better don't touch the rest wink

Adding announcements

When no agent is or becomes available, neither from the primary nor from the secondary group, the call will alert forever (well, not exactly forever - after quite a long while, it will be disconnected). To keep the calling customers happy while they wait for an agent, it is useful to play an announcement (something like We are pleased that you have called us and your enquiry is of great importance to us. Please be patient until an agent is available to speak with you in person).

What an announcement is

To the PBX, an announcement is a file that contains raw media data. When an announcement is to be played, the PBX will retrieve the media data file from a web server using HTTP(S).

As calls may use different codecs (we have seen this during the IP Phone type of device configurations before) and the raw media data depends on the codec used, multiple files must be provided for a single announcement - one per codec. Each file would have the screenshot.png same base-name but different extensions.
NB: looking at the file sizes in this screenshot, you see the compression performance of the various codecs. OPUS-WB has more or less the same quality as G722 has but only one third of the size. OPUS-NB is superior in quality compared to all other codecs except G722 and OPUS-WB but requires only little more bandwidth than the best compressing codecs (G729 and G723) while providing much better quality.
Built-in announcements
As said before, an announcement is normally retrieved by the PBX as a file using HTTP(S) when needed and for this you need to configure the URL to the file (e.g.

However, there are 2 built-in announcements and you use them by specifying special pseudo-URLs:
  • MOH
    used as URL will produce the built-in music-on-hold
  • TONE
    will produce a constant tone (often recognized as a dial-tone).
    You can add a screenshot.png ?tone=ringback which will give you a tone sequence with 1 second tone and 4 seconds silence (this is often recognized as a ring-back tone).
    You can also add a screenshot.png ?tone=busy which will give you a busy tone sequence. Notice that the queue is only playing the busy tone, it will not disconnect the call!

How to convert raw media files

Popular sound file formats are .mp3 or .wav. So why does the PBX not accept these?

None of the usual formats is used in voice calls (this is because they are either not compressed at all or are optimized for use with music, not voice). Therefore, they need to be converted before they can be played to a caller. If the PBX would do this on-the-fly, it would consume CPU cycles unnecessarily. But you can do it up-front using the link_intern.png audio converter which is video2.png on our web site.

We have prepared two audio files for you:
Please download and convert them so that you have the raw files in a single, otherwise empty folder on your PC.

Where to store media files

As said before, the PBX will retrieve media files via HTTP(S) when needed. Therefore, to use announcements, you must store the media files on a web server.

In fact, you can use any web server you might have to store media files. In many scenarios it is much more convenient to store the media files on the PBX itself. For this, the Files App is provided. It can be used to store (and retrieve) files and provides a graphical user interface for this as well as an HTTP(S) service.

First open the Files App (do not confuse it with Backup Files. While this would work too, your announcements would not be part of your backups then). You may want to video2.png add it to your home screen first.

Here is video2.png how to store your media files on the PBX:
  • in the Files App, click on the screenshot.png create directory icon on the upper right edge and create a folder called announcements
  • check the screenshot.png little check-mark on the upper right. All items in your current folder are now ticked. Make sure that only your new folder is ticked (which is easy, as you probably only have one wink)
  • click on the screenshot.png Share symbol on the upper right
  • select screenshot.png Share as link with filekey as share mode. Do not specify user nor password!
    All files in your folder are now available to other Apps
  • open a windows explorer to the folder on your PC where you stored your converted media files
  • drag and drop all the files to the new folder in Files
  • thats it!
You can close the Files App now.

(Further Hints) Files stored and shared this way can be retrieved with HTTP(S) using screenshot.png the fileskey query argument in the URL, e.g. Fortunately, to use announcements in a waiting queue, you don't need to remember this (we see this in a minute). However, to share such files from within other applications, it may come in handy.

Assigning an announcement to the queue

When you go back to the detailed settings of your queue in the Waiting Queue PbxManager plugin, you will notice the Announcements section. Now that you have stored some media files in the Files App and have shared them with other Apps, you can easily video2.png select them for use as an announcement:
  • open the Announcement section
  • click on the Select button next to the Announcement 1 field
  • select announcement-first
  • click on OK

Defining the alert timeout

You're impatient and you just tried it?
Then you have discovered that it somehow doesn't work yet, the announcement is not played.

This is because such an announcement can be played right away when the call comes in or only after some time of ringing. This time is known as Time to announcement. It is set in the Settings section (you've already been there to set the Primary group timeout). It is given in seconds and provides for the following options:
  • empty: the announcement will never be played. Instead, incoming calls will alert all the time
  • 0: no alert tone is sent to incoming calls and the announcement is played right away
  • number: an alert is sent to incoming calls and the announcement is played only after number seconds
Note that, technically speaking, the call is answered as soon as the announcement begins to play. This for example means that the caller might need to pay for it from this moment on.

video2.png Set the Time to announcement for your queue to 3 seconds.

When you now call the queue, you will hear an alert tone for 3 seconds and then the announcement.

Assigning a second announcement to the queue

When you fully listen to our beautiful announcement, you will notice that the behaviour is not perfect yet. Once the announcement is over, the call will be terminated.

While this may seem surprising, it is by design: when there is only one announcement assigned to the queue, any incoming call is terminated once the announcement was played. This is good for You are calling out of office hours. We'll be happy to serve you monday to friday from 12 am to noon. Thank you for calling type of applications.

However, for our queue it is less than optimal. The solution is to assign a second announcement to the queue.

As you will recall, you have converted 2 mp3 files. Its now time to assign the other one as second announcement:
  • open the Announcement section
  • click on the Select button next to the Announcement 2 field
  • select announcement-second
  • click on OK
When there is a second announcement, the queue will repeat it forever. Now callers can wait for an agent to be available even if this takes really long.

Note that in this case, the incoming call will not be terminated before it is answered, not even if it lingers around for a very long time. This is again due to the fact that - technically speaking - the call is connected as soon as the announcement begins to play. That stops the PSTNs time-to-connect timeout.

Two Stage Dialing

Two stage dialling is when you dial into a waiting queue, hear a voice prompt and then can dial again to reach your final destination. Dialling when you are already connected (to the voice prompt in this case) is done with DTMF tones. The two stage dialling settings are therefore sometimes referred to as DTMF maps. This is the typical Please dial 1 for sales, 2 for support and 9 to leave a voice message type of application.

In the spoken text of the second announcement we have configured in our queue, we say ... please press 1 for Lisa Svensson, 2 for Jean Dupont and 3 for Mario Rossi.

  • go to the queue settings
  • open the DTMF two stage dialing section
  • click on the + sign

    You will see an otherwise empty line with a right arrow. Such a line represents a so-called DTMF map. It maps a DTMF key (0 - 9, #, *) to a (full or partial) extension number. So we need 3 of those lines:
  • click into the empty line, edit fields will open to the left and the right of the arrow
  • type 1 to the left and 11 to the right of the arrow (this is the mapping for Lisa)
  • confirm your edit by clicking on the check-mark on the right end of the line
  • open a new line by clicking on +
  • type 2 to the left and 12 to the right of the arrow (this is the mapping for Jean)
  • repeat for Mario (3 -> 13)
  • click on OK
Now, callers can connect to Lisa specifically by pressing 1 when prompted.

Handling exceptions

Sometimes calls in a queue cannot be answered. This can be the case if no agents are available (either they are busy with a call or have left their group) or if the calls come in outside service hours.

Such situations are handled using various types of call forwards on the waiting queue. While users can video2.png set their own call forwards using myApps, the forwarding for a queue is managed in the Call forwarding section of the Waiting Queue PbxManager plugin.

Waiting for too long

If a call remains in a queue too long and the caller hears the announcement over and over again, the caller may get annoyed. It therefore usually makes sense to switch to a different queue behavior. You could for example ask the customer to call again at a later time.

The too long to complete the call condition is generally caught by an On no response call forward.

(Further Hints) By the way, On no response type forwards are often referred to as CFNR (call forward on no response). Likewise, On busy is known as CFB (call forward on busy) and Always as CFU (call forward unconditionally).

You can try that easily:
  • use myApps to set a No response forward to 13 (Mario) for yourself (note the CFNRlittle CFNR symbol on your IP232)
  • call from Jean to yourself (10)
  • wait 15 seconds
You will see that the call is video2.png forwarded to Mario after 15 seconds.

The same mechanism is available for queues. To set a CFNR you use the Call forwarding section in the Waiting Queues PbxManager plugin and video2.png add a On no response forward.

How to implement the final announcement

The waiting queue itself can not handle a third announcement. However, if you create a new queue that has your final announcement set as Announcement 1, you can forward the call to this new queue using a CFNR set on the original queue.

To implement a terminating announcement for when no agent takes the call within time, you would therefore

If you now call the original queue (40) and listen a while (well, quite a while), you will hear a nice lady apologizing that no one can talk to you. After the new announcement has been played, your call will be disconnected.

Fair enough, but you may now ask why we set the Response Timeout to this strange value of 76 on the original queue? The reason is that we want to make sure, that the CFNR from hqswb to hqswb-to happens exactly when the first two announcements are finished. So the value used here adds up from the Time to announcement of the first queue and the respective length of the announcement files.

(Further Hints) You have seen that call forwards can be set towards names above (you have set it towards hqswb-to). Of course, you can also set it towards a number. You would type the target number in to the same field. If the forwarding target consists of digits only, it is recognized as a number.

Out of business hours

A little more difficult to handle is the situation where the queue is called out of business hours. You would probably want to play a quite similar announcement as in the case before.

In addition to that however, you need to define what your business hours are. This is done using a Time switch. You can make a call forward depend on such a time switch. If you do so, it is only executed during the time frames defined by the switch.

Fortunately, the Install has already created a time switch called Business hours for you, so we can use it right away (it defines business hours to be Monday through Friday from 9:00 to 18:00 hours).

For this desired handling of out-of-business-hours calls, we would simply set a call forward of type Always on the queue. Of course, we need to make it depend on the Business hours time switch. As we would like to use a slightly different announcement (announcement-oobh-call-again.mp3), we need an extra queue to be able to play this announcement (as before with hqswb-to).

To implement a terminating announcement for a call outside business hours, you would therefore
When you call the queue (40) now, you will probably hear the normal behaviour. This is because you probably call during business hours indeed. To be able to test the function we first need to look at ways to manipulate the time switch. We'll do this in the next chapter.

Managing time switches

Time switches are maintained with the screenshot.png Time switches PbxManager plugin. This is pretty straight forward. You can:
  • add and remove time switches
  • select a number of weekdays where the time switch shall be considered "on"
  • limit this to certain time frames (hours, days, months and years)
Also, you can add multiple such time definitions for a single time switch (the switch then is considered "on" when any of the definitions matches).

One thing however needs to be mentioned: while a time switch normally operates automatically, it may be video2.png set in to a manual mode (manual on or off). In this case, the switch behaves as if it was in the respective state, regardless of the current date and time.

This is used for example, if you want to overrule the time spans defined in the time switch due to an exceptional event. For example, you could switch the Business hours time switch to manual off for a bank holiday.

Now that you know how to override the time switch, we can try it out:
  • set the Business hours time switch to manual off
  • call the queue (40) and you will hear the out-of-business-hours message
  • set the Business hours time switch to manual on
  • call the queue again and you will hear the normal greeting message
  • remove both the on and off flag
  • call again and what you hear depends on the time you are calling wink
(Further Hints) The PbxManager plugins of course are normally available to administrators only. However, for each defined time switch, there is an app available that is screenshot.png called like the time switch itself. This allows you to modify a single time switch only and you can make it available to individual users, e.g. a switchboard operator.

Using a Waiting Queue as Loopback destination

Do you remember the trunks lesson you did earlier? When we were adding a trunk to our system we had the option to configure the loopback property, which we used to reroute calls to Mario Rossi. Let's go back to that because the loopback property fulfills an important role.

When a user calls the PBX through the trunk from the PSTN and just dials the trunk prefix, you usually want to make sure this call is not routed back to the trunk because this would give an external caller the ability to use your trunk line at your expense. This means the best course of action would be to use the loopback property to route calls to a Switchboard.

Let's go to the Trunks PBX-Manager plugin and open the trunk we created in a previous chapter which we linked to the SIP trunk and change screenshot.png the loopack property to 40 or hqswb. You most likely are using a MSN trunk at the moment. Revert it back to a SIP DDI trunk. You should know how it works.

To test the configuration we can proceed as we did in the testing section of the trunks book and dial the complete number +49 (621) 3428231-0 from Jean. The loopback property should redirect the call to the Switchboard and your Agent Lisa Svensson should ring or - depending on the time of day - you hear the out-of-business-hours announcement.

Dynamic agents

There are scenarios in which waiting queue agents need to change their agent-role dynamically. That is, sometimes they are available to serve the queue, sometimes they are not.

There are several ways to implement such a behaviour.

Generally, when an agent becomes available again, any waiting call is offered to this agent right away.

Based on presence

A common assumption is that agents are busy doing other things when presence information is set for them.

If the Presence disables operator property is set in the queue settings, any user that has a presence set is considered unavailable and will not be treated as an agent. For this, the presence state must be set other than Available, setting a note only will not do.

As you are configured as a primary agent, a call to the queue will normally ring your own phone (IP232).
  • now tick the Presence disables operator check-mark in hqswb's Settings
  • set your own presence to Away, Busy or Do not disturb (using myApps) and
  • call the queue from Jean
You will notice that you are not notified on your IP232 any more.

Based on Call Forwarding

A similar assumption is that agents are busy doing other things when they have a call forwarding set.

If the CFU disables operator property is set in the queue settings, any user that has an unconditional call forwarding set is considered unavailable and will not be treated as an agent. For this, the Always call forwarding must be set and active, Busy or No response will not do.

To try this
  • remove the previously configured presence info by changing your presence state to Available (just to be safe)
  • now set a call forward (a.k.a. call diversion) for yourself to 13 (which is Mario)
  • set the CFU disables operator option for your waiting queue
  • call the queue from Jean
You will notice that you are not notified on your IP232 any more. Also, Mario is notified only after 5 seconds (the queue's primary timeout). This proves that no call to your phone was diverted to him.

When you're done, do not forget to disable (or remove) the call forward.

Based on dynamic group membership

Finally, agents can change (enter/leave) their group membership at will. When users leave the group temporarily, the queue will not treat them as agents until they re-join. This behaviour does not have to be enabled in the queue settings.

To see how that works,
  • be sure that you have disabled or removed your CFU before
  • use myApps to leave the hqswb-0 group (which was created as primary group for the queue)
  • call the queue from Jean
You will notice that you're not called.

Advanced WQ tricks

Now that you have the overall picture, let's see what else we can do with Waiting Queues.

DTMF map tricks

Let us think what else you could do with DTMF maps.

Many installations do not have a DDI trunk, or the number range of the DDI is not large enough to call all extensions (for example, you have a DDI range from +49 7031 73009 0 to +49 7031 73009 9 but you have 100 extensions). In these cases, you can specify a DTMF map that allows you to dial many extensions. This can be done by specifying a map with an empty right side.

Sounds confusing? The way DTMF maps work is "when the pattern on the left is dialled, a call transfer to the number on the right side is started". However, the number on the right side is only used as the start of the number. The caller may dial the remaining digits. When the right side is 1 for example, the caller can dial numbers that start with 1. When the right side is empty, the caller can even dial all numbers.

Let us configure access to all extensions by dialling a star (*). That is, *11 will dial to 11, *12 to 12 etc. To configure this, you would add this map
  • * -> empty
  • dial 40 from Jean
  • wait for the announcement
  • dial *11
  • you will be video2.png transferred to Lisa (other agents stop ringing)

Keeping it secure

But watch out! You probably do not want to give callers access to all numbers. Most prominently, callers should not be able to call out again. So you must make sure that you do not give access to your trunk prefix (usually 0)!

Fortunately, the order of DTMF maps is important. So to catch bad cases, you can define a map that handles this case specially by mapping access to the trunk prefix back to the queue again. For example,
  • *0 -> 40
  • * ->
will first catch the bad case (*0) and route it back to the queue and then allow any other digits to be dialled after the star (*). With this configuration, you provide access to all extensions except for the trunk.

You may also decide to provide access to part of your internal numbering plan by specifying a map for the common prefix of this part. For example, in our PBX, all user extensions start with 1. So you could do
  • *1 -> 1
which provides access to extensions starting with 1 only.

Finally, there is an interesting meta-digit, the dot (.). It matches any DTMF digit and the matched digit will be appended to the target number specified in the right side of the match (possibly followed by further digits dialled by the user). So when you specify
  • 0 -> 40 (block trunk access)
  • . ->
you again provide access to all extensions except for the trunk.

Now remove all previous settings and then carefully configure access to all of your extensions except the trunk by dialling a pound sign (#, nerds tend to call it www.png hash nowadays). Remember to confirm each map and click on OK to save your maps.

When Jean then calls the queue, he should be able to dial directly to Lisa by typing #11. #0 should re-connect to the queue however.

Changes of Group Membership done by the Administrator

The administrator can also change the group membership status of any agent. This is done using screenshot.png the Groups PbxManager plugin.

The plugin will list all existing groups (not only those used with waiting queues) and screenshot.png their members. Also, the current membership state is shown. Surprisingly, there are 3 different states possible:
  • dynamic in (shown as DI)
    The user is currently member of the group and can choose to leave it temporarily
  • dynamic out (shown as DO)
    The user is currently not member of the group and can choose to join it again
  • static (shown as S)
    The user is member of the group and can not modify its group membership
The group membership state can be changed by video2.png clicking on the state designator. Users can also be video2.png added to or video2.png removed from groups.

An administrator would change a queue agent's group membership to S if the agent is not allowed to log-off from the queue. As a result, such memberships are not displayed in the user's Groups settings in the profile.

The active membership mode

In addition to the DI/DO/S state, you may notice another toggle with A and - as possible values. This toggles between an active (A) and inactive (-) membership. We'll see what that is used for in another book. For now it is good enough to remember that such modes exist and that they can be modified in the Groups PbxManager plugin.

Limit load

A load factor can be defined in the Max Calls/agent(%) property. This defines the number of concurrent calls a queue can take (including the calls currently handled by the primary operators) in relation to the number of primary operators. A value between 100% and 150% is a good starter. This calculation is made each time a call comes in.

Let us assume there are 2 primary operators and we set this property to 150. The queue would then allow up to 150% of 2 => 3 concurrent calls. In other words, when all primary operators (Lisa and yourself in this case) are busy talking, a third caller will wait hearing the announcement. The fourth caller however will get a busy. Max Calls/agent is therefore usually set to a value greater than 100.

All agents busy

Of course, letting callers wait for a long time only to tell them afterwards that they should call again is sort of unfriendly. It would be nicer to know in advance if the caller has a chance to get to an agent in time. To an extent, this can be done using a different type of call forward on the queue.

You may recall how we have used the Max Calls/agent(%) property to limit the load on the queue (we have discussed that in the Limit load chapter above). Instead of giving a busy to the caller, you can video2.png define an On busy type forwarding on the queue. When the overload situation occurs and a new call comes in, the On busy forward will be executed.

You can set CFB, CFNR and conditional CFU types of forward simultaneously on the same queue to handle different situations.

Round Robin mode

If the screenshot.png Round Robin Timeout(s) property is configured, an incoming call is not sent to all members of the primary group. Instead it is sent to one of the agents only.

When the round robin timeout has expired, the call is sent to all members of the primary group. The operator who receives the call first is selected in a round-robin manner.