Let’s imagine that we work for ACME Social, a company that specializes in tracking the success of its clients on social networks like Facebook or Google+. So, every time someone befriends one of their clients, we want WombatDialer to call the client telling them their current number of friends. The call would say something like "Hello ! Customer 1234 has 127 friends. Goodbye!"

This example shows a couple of features that are not trivial to implement on most dialers, notably:

In order to implement this, we start by editing the Asterisk dialplan and create a couple of new contexts. The first one is called "telecast" and is used to generate the message being played:

As you can see, the context above introduces two channel variables ${user} and ${friends} that are placeholders for the user-id of our client and the number of friends they currently have.

As a convenience when testing, we want all numbers dialed during the test phase to actually dial our own SIP phone; to do this we create a new context called dialout that routes any number to our extension:

We reload Asterisk to pick up the dial-plan changes. Then we log-in in WombatDialer and configure it, so that:

Your configuration will look like the following screenshot:

At this point, we create a new List called "Test" and add only one number to it; you may enter the number as:

This uploads the number and associates the variables "user" with value 10 and "friends" with value 100.

Then we create a new campaign - this is where all the pieces are tied together:

After saving the campaign, we select it and then add:

As you can see, a campaign can have multiple trunks, multiple end-points and multiple call lists, and they may be shared between multiple campaigns.

It would be fair to add some rescheduling rules as well - for example, if we do not get an answer within 30 seconds, we want the system to retry placing the call exactly once after two minutes.

In the end, you would get a situation similar to the one here:

At this point we’re ready to go:

If all goes well, within a few seconds you should receive a call to your SIP phone telling you that user 10 has 100 friends. Hooray!

After this, you should see your campaign being shown on the Live page in gold, with status IDLE; now, when our internal tracking system detects new friends for one of our valued customers, all it needs to do is to send a HTTP request to the WombatDialer, like we would manually from the command line:

If you do, in a few seconds the dialer will send this new call. You can send all the calls it needs to place, one at a time, and it will try scheduling them as soon as possible given the current system conditions, running campaigns and available outbound lines.

Now, if you want it to actually dial out and not just call our SIP phone, edit your Trunk "Out": set the dial string to something like SIP/myprovider/${num} and set its capacity as the total number of parallel calls you want to place. Then go to the Live page and reload the campaign.

When you want to stop the campaign, you have two choices:

Of course, you can have this campaign run on multiple trunks and multiple endpoints, using multiple separate Asterisk servers, just by creating the relevant items and telling the campaign to use them. This way, handling hundreds of channels is just as easy as testing with your SIP phone!

Further evolution:

You know how it goes; so many good ideas in real-life end up being limited by the amount of funds you can raise to implement them. That’s why Vicky, the energetic new president of "Friends of the Wombat", called you. "Friends of the Wombat" is a nonprofit institution that helps wombats in need, but their activities are limited by the rising cost of carrots; so they decided to start a volunteer fund-raising campaign.

What they would like to do is to call a list of known contacts that expressed an interest in wombats and ask them to make a donation. They started doing this manually with paper and pencil, but getting to a lead is really tiring and time-consuming - their volunteers spend most of the time dialing numbers and it is really hard for them to get through to somebody who is interested.

After a good cup of green tea, what you propose to do is to use WombatDialer to automate the process by dividing it into multiple stages:

This setting leads to two huge efficiency boosters:

In order to implement such a campaign with WombatDialer, we start by creating a call queue that will hold our agents and will send them calls. You can use any Asterisk GUI to do this - in the example below we use Elastix, but you can choose the one that suits you best.

We go to Queues → Create new, set the extension for the queue as 999, enter any name you want, and look on the settings below so that:

If you create a queue manually without using a GUI, configure it with the parameters below so that WombatDialer can observe it.

Now we create a custom piece of dialplan to be called as an end-point for calls that connect successfully.

(In order to make this example shorter, we assume you have a basic familiarity with WombatDialer concepts such as Campaigns, Servers, Trunks and End-points.)

Now log-in to WombatDialer and create a new End-Point:

This means that WombatDialer will try and place two calls for each agent available, but never more than 10, and will stop placing calls if there are two or more people waiting in queue. We expected to use a boost factor of three to four given the previous statistics, but it is better to start with a small figure and grow it if needed.

It is important to understand the impact of different boost factor settings; in general having more calls made than agents may result in calls waiting in queue when all of your agents are busy (in call-center parlance this is usually referred as "nuisance calls"). WombatDialer tries to minimize the impact of this case by continuously monitoring the number of calls waiting on the queue and avoiding placing new calls if there are too many. If you don’t want to have cases where calls are not immediately connected to an agent, you should leave the boost factor to 1, that is, place no more calls than available agents. The trade-off here is that agents end up being underused, as they have to wait for a successful call to come in.

We then create a test trunk, upload a list of test numbers and create a campaign called "friends" as in the previous examples; we now start the dialer and start the campaign from the Live page. When we start running it we notice that it does not seem to work - the campaign is running but no calls are placed. How comes?

If we reload the current Dialer status, we see that it is saying that the queue has 0 channels available - this is because there are no agents on the queue.

If we log an agent on (e.g. by entering 999* on Elastix), we will notice that WombatDialer starts dialing. If you pause an agent or log him off, WombatDialer will immediately react and adapt to the changed number of available end-point channels.

Another thing that we do is to track (through a status code) which callers ask for being put in contact with a volunteer - this allows easy inspection of what goes where from the Campaign Report panel.

Now all we have to do is to set our campaign to use an actual telephone trunk and upload the "real" list of numbers and we are ready to go - it’s time to buy some new carrots for our wombats!

Understanding statistics

If you run a report of our campaign with a queue analyzer like QueueMetrics, you will have two different views of the campaign:

Further expansion

Please note that outbound telemarketing, whether it is of the good or evil persuasion, is regulated by your local law, so be sure you comply to its terms before you start calling millions of people!

A Dr. Strangelove just called, saying he needs your help for an automated appointment reminder system. Dr. Strangelove is tired of patients forgetting appointments, so he needs a way to call them the day before and making sure they will be there at the right time. Also, as he specializes in every possible thing, he needs to know what the appointment will be about so he can either have an operating room ready to remove your appendix or his psych couch cleaned and stocked with a large supply of paper towels. Do you think you can help?

After calling him, you understand that he wants a system that will not only connect to a list of numbers and handle common issues (busy calls, non-answers, etc) but also a system that is able to detect whether the callee actually confirms receipt of the message. If they do, that’s okay; if they don’t, a new call is placed after a while.

He also wants a system that is able to synthesize a custom message for each call, and that is able to gather data from the callee and pass it along to his office management system as it is collected.

Doing this with WombatDialer is easy; it is basically a matter of implementing an outbound IVR and tracking call parameters and call completion codes. Doing so will also let us show how WombatDialer handles call retries. As an added bonus, we’ll see how WombatDialer notifies other systems over HTTP.

To get us started, we create a list of telephone numbers called "Appointments" with custom attributes; in order to do this, we log in to WombatDialer, go to the Lists page and create a new list. After creation, we select it and upload a list of numbers like the following one:

This means that the person at number 5551234 is to be reminded an appointment for tomorrow at 10:30. We use two separate variables as this makes life easier for our Text-to-Speech engine.

We now have to program the outbound IVR context in Asterisk; we can do that easily with the help of WD call attributes so that we know what we have to tell our customer. In this example, we will also use the Google Text-to-Speech engine to synthesize audio on-demand.

Notable points in the code above are:

We now have to create an end-point for our campaign that points at extension s@drstrangelove so that WombatDialer knows where to connect successful calls. We will also need at least one trunk to send calls through - to get us started it is advisable to have a "dummy" trunk routing everything to a local extension.

If you have not already done so, it would be advisable at this point to have a look at our previous tutorial - A social media dialer - to see how to create and control a simple campaign.

When done, we create a new Campaign to connect all pieces together.

We set the campaign to be idle on termination, so that we can add more numbers over HTTP when they become available. We also program it to be running only between 8AM and 6PM, every day of the week, so we don’t call people in the middle of the night if a nightly job is used to load new appointments every day.

We also set a forced closure after 90 seconds so that if the call exceeds a duration of 90 seconds, it is automatically hung up to prevent using valuable resources on a call that is likely invalid.

As a last measure, we set the logging format to QM_COMPATIBLE (so that we can observe activity via QueueMetrics) and enter the HTTP notification URL of Dr. Strangelove’s office management system to be notified of call events (see below for more information).

We then complete the campaign by adding a trunk, our new end-point with the outbound IVR and our Appointments list.

As a last step, we create a set of Reschedule Rules that implement the retry logic.

Now it is time for us to start the campaign - make sure the WD is running, go to the Live page, select your campaign and run it. If all goes well, you should start receiving calls on your test extension.

While the campaign is running, you can add more calls to it via HTTP by issuing:

and you can even specify a minimum time for calls to be placed at, like e.g.

When the campaign terminates, it will be in IDLE state. In order to close it, first pause and then remove it.

After a successful run, you can see its statistics, by viewing the Campaign Report screen:

You will see that some calls appear as TERMINATED 0, some as TERMINATED 1 and some as TERMINATED 2, based on the extended call status entered through a user selection. Only calls in state TERMINATED 0 are retried.

You can also see the state of attributes for each call by going to the List editor:

You see that calls successfully placed will have an APPT attribute that is either APPE or PSYC; also you will see a complete log of activity for each number.

As a last item, you’ll remember we enabled HTTP notification. This basically POSTs the result of each call to a HTTP server, where you could have a simple PHP script to parse it, like in the following example:

The script above basically logs all activity on the HTTP error log. What you get is a sequence of calls like:

You see that for each call:

This way you can easily create an integration script that stores the results of the call on a database or passes them along for further processing.

Further developments

The Google-TTS script used is available at: http://zaf.github.com/asterisk-googletts/

An end-point of type queue in Wombat tries to determine the number of available channels based on the number of available agents on the queue it is observing. An agent is considered available if it is logged on to the queue, is not paused and is not currently in conversation.

After getting the number of available agents, it multiplies it by the "boost factor" (that is used to account for the success rate in connecting the numbers to be dialed) and tries to schedule as many calls. Therefore, if you have e.g. 7 available agents and a boost factor of 1.3, it will try to connect to 9 numbers at once (7 x 1.3 = 9.1).

It will also enforce two limits:

It is also important to notice that the queue is used only as a way to know how many calls can be placed on a queue, but calls will still be transferred to a point in the dial-plan that should lead to the queue. This lets you execute dialplan logic (e.g. playing pre-recorded messages or running IVRs) on the calls it just placed.

In order to use WombatDialer effectively with a queue, the following guidelines are best followed:

In order to run a campaign with a Queue endpoint, it is best to:

The Queue EPs let you use WD as a powerful progressive dialer and can lead to very complex integration scenarios, but as it involves actual people being called and answering the phone, it is better to understand it well before actually using it in production.

The WombatDialer can be used as a stand-alone product for message broadcasting, but it was built to integrate easily with QueueMetrics, the premier call-center monitoring and reporting tool for the Asterisk PBX. WombatDialer and QueueMetrics do different things, but together can be a very powerful call-center solution.

In this example, we improve the scenario described in a previous tutorial - Helping Wombats one carrot at a time - imagining that the want to:

You can have WombatDialer and QueueMetrics installed on the same server, unless you have a very high load or a very high number of lines.

As a first step, we’ll have to create a small interface script that will be our CRM application. We will call it wombatPopup.php and will store it on one of our servers as http://10.10.5.10/lenz/wombatPopup.php

This page basically displays the person’s name and ID, so we can display it immediately - or this could redirect to an external CRM application.

At the Asterisk level, if you have not already done so, create a queue "999" with the correct parameters to be monitored by Wombat - see Understanding queue end-points . Then edit your extensions_custom.conf file so that you have an extension "1235" that leads to the queue:

This rewrites the incoming caller-id for the queue to e.g. "#1234 John_Doe", so this is what the agent sees - even before the agent pop-up is opened. This also is recorded in QueueMetrics, so this is what you will see when you run call reports. Note that if you run FreePBX you cannot call the queue directly using the Queue() command but you’ll have to go through its dialplan in order to have all parameters correctly set.

In QueueMetrics, set the following properties in configuration.properties:

Then create a queue "999" and set its Queue URL to:

This tells QueueMetrics that it has to enable a screen-pop for calls coming in through that queue.

Now log on to WombatDialer; create an EndPoint of type Queue set for queue 999, and its entry point in the dialplan to 1235@from-internal-custom . Do not forget to set the "Boost factor" to 1 and the "Maximum queue length" to 2.

Then create a campaign called "QmSample" that idles on termination.

Set the trunks, the EP we just created, add no lists and define any reschedule rules you need. The end result should look like the following:

Now start the campaign. It will go in status IDLE immediately, as it has no numbers to dial, and you will see it all yellow in the Live page of WombatDialer.

At this point, it is time for your agents to log in in QueueMetrics. Have them log-in to their Agent’s page, and from there log them on to queue 999. At this point, make sure that each agent’s browser allows QueueMetrics to open pop-up windows (this is usually disabled in modern browsers).

Now, for each call you’d like to be started, send an HTTP request to WombatDialer that looks like the following one (we do this through the Linux shell, but there is nothing preventing you to script this in some other way:

Note that you associate two parameters: ID that is a unique id used by your CRM and PERS that is the called person’s name. You could also add additional parameters you may need, e.g. a person’s class or their telephone number.

What happens now is that when the call goes through, its caller-id is rewritten as "#2301 John_Doe" as soon as it reaches Asterisk. When your agent receives the call, they will reload the agent’s page and the pop-up will be immediately opened.

In the pop-up, you parse the caller field and extract your CRM id, so you can use this for your external application to display the correct data.

From the agent’s page you can also manually open other forms for recent calls. The agent will also see the person’s name in QueueMetrics, so this makes their life easier. The agent may also set a manual status code for each call through QueueMetrics, e.g. if the sale was successful or not, and this lets you measure your agent’s performance. You may also use QueueMetrics’s extensive QA monitoring features to analyze calls and improve the process.

Analyzing outbound campaigns

If you set your campaign to have QM_COMPATIBLE logging, you will find data about two different queues on QueueMetrics:

You are called in to a client site; they seem to have a problem. They run a small (10 agents) inbound call center, and when you join everybody else in the meeting room, there is a large and colorful graph in the middle of the table. The graph shows the call wait times during the week and boy, it’s not a good sight. Their main inbound activity is to offer client support for a company selling sport bikes, and everybody seems to be calling on Monday morning. It looks like people go riding on weekends and whatever problem they have, they call on Monday morning. Wait times peak, abandon rates spike, and nobody is happy. The call center manager is mostly concerned of having to hire and train some temp people in order to handle the load that only happens one day a week. They ask you if you have any better idea on what can be done. And yes, you have some.

You can program an Asterisk queue so that when people tire of waiting, they press a digit and get to a menu where they can leave their number. Then the system queues their call and attempts to call them at a convenient time. This way:

This scenario requires some additional "glue" to what is basically supported by Asterisk - exiting a queue and reading a number are easy, but then starts the pain. You’ll have to create a database and write a script that reads back from it. You have to handle invalid numbers, busy numbers and the like (if we promised to call back the client, we cannot just try once and forget about it). You’ll have to have a GUI of some kind for the manager to start and stop dialing. You’ll have to adapt to the number of available agents. You’ll have to report on this activities. You’ll have to avoid flooding the trunks of your PBX with too many calls. In short, it’s the kind of thing that gets more complex the more you think about it. That’s what WombatDialer is for.

What we plan to do is to use WombatDialer as the call-back engine. It can be controlled by an external HTTP API, so you can do that from the Asterisk dial-plan. It has exact knowledge of the current set-up and call back rules, so you get the number of calls you expect on one or more Asterisk servers. It can work with an existing PBX and does not interfere with calls that are not its own. It keeps track of call completions and knows what to do in case of invalid and busy numbers. It has reports of its own and can work with QueueMetrics for powerful and detailed reports.

The client uses Elastix as PBX system, so we’ll have to integrate it with WombatDialer. No problem!

So what we do is:

We start by editing the extensions_custom.conf file in our system, adding a new stanza like:

We use Google TTS as a voice synthesizer - you could use a different one or you could have the messages custom-recorded for you. What our dialplan does is first to collect a 7-digit number, then read it back asking for confirmation and when confirmed, it sends it over to WombatDialer on a campaign called "callback". Together with the number, we also store the code of the queue that the call was on and the date and time this number was gathered. (Please note that in order to send multiple comma-separated parameters in the HTTP request, we have to use '%2C' instead of the plain comma ",").

In order to configure WombatDialer:

If we start sending calls to the queue and we try and leave any numbers, we will see that a new list will be created on WombatDialer under the name "callback/AUTO" and that will contain the numbers and attributes like:

Those numbers are NOT immediately called, but WD will wait for some agent to be present and active on queue "401" so that they can be called back. This way, the call-center manager can monitor the current call backlog and decide who and when it is to join the callback queue.

Further improvements

If you run a call center, serving clients in a timely way is often very complex, as it requires having enough people available to handle traffic spikes. The number of callers that disconnect because they have been waiting too long in a queue is then an important driver of the quality of your work, and these frustrated callers are the focus of much attention and scheduling/planning efforts in all call centers. This is because in a traditional setting doing inbound calling you basically had no other way of servicing the client but waiting for the person to call in.

With an Asterisk-based PBX and using digital lines, this scenario changes a bit, as:

So it is now a conceivable scenario to improve the services you are offering by adding an automated call-back option, so that you search the logs of lost calls and you actively schedule recalls on them in order to get back to people who hung up in frustration.

Preview dialing is a type of reverse dialing where the agent has a chance to "preview" the number that is to be called before actually having a call placed.

The way it works is:

We want to run a simple outbound campaign, in which we plan to play a file and wait for the receiver’s acknowledgment by pressing '1'. We also want to make sure that in case the receiver has an Answering Machine, we play a specific audio message that will be recorded by the machine.

The first thing we need is to set up the Answering Machine Detector in Asterisk; this can be done using the embedded application AMD or a number of external tools. In this tutorial we cover the embedded AMD application.

So the first thing we do is to configure the file 'amd.conf' so that it has the following contents:

These are the default parameters used to detect a machine and they may need some tweaking for your local market and spoken language.

The we create a special dialplan extension:

And we define an extension of type PHONE that points to '1@amddetect'.

When we answer the call, we play a short beep to make sure that the channel is up, and then we start AMD detection. The call will be blocked until AMD detection is complete; so there is a definite trade-off between quick and accurate detection. To make your life easier during testing, we print the result of the detection and its cause on the Asterisk console.

On the campaign itself, we define two campaign variables that will hold the names of audio files to be played back in either case:

Though this is not strictly needed, you can tweak the parameters of the AMD detector by editing the 'Extra AMD settings' on the campaigns; these are passed as parameters to the AMD detector; if blank, defaults are used.

The final status for answered calls will be:

You can use these call statuses to decide how to reschedule those calls, and to create new lists or blacklist some specific numbers.

One of the most important features of a dialer, paradoxical as it sounds, is to avoid calling numbers that are not supposed to be contacted. But why should you, in the first place, try to call numbers that you are not supposed to call?

In practice, this is a common scenario - for example, let’s say we work for a car dealership, and you prepare a list of customers to contact because their car is ready for pick up after its service ticket. While you are running this campaign, some especially eager customers decide to contact us first to inquire about the status of their vehicle, and you tell them that it’s ready. At this point, calling them again would be a waste. It would also give the impression that we do not know about their previous interaction.

But how to do it? Once WombatDialer schedules a number, the right thing to do is to cancel the call on the campaign, if the campaign hasn’t placed the call already. So, we say, let’s delete it from the relevant list, but we may want to re-use the same list of numbers more than once, and we do not want to strike some numbers out of it "just because".

Also, if there callee ever asks "Why didn’t anybody call me? I was waiting for your call!", it is important to understand that it was an explicit decision and not a failure. As you have no way of knowing about the cancellation when preparing the list of contacts to reach, it must be an "add-on" while the system is running. That’s what blacklists do: we can keep a separate list of numbers we don’t want to call and check it dynamically as we progress through our lists.

A second common reason why you could use a blacklist is because the customer directly asks us not to be recalled. By adding them to a blacklist we can keep this information in a separate place from the lists we manage, and WombatDialer makes sure we never forget to remove those numbers from the ones we are supposed to dial.

This way, our employees tasked with extracting call lists need not worry about making sure that all canceled numbers are manually removed, and why. In many countries, you have a legal obligation to adhere to a customer’s will never to be called again, so you need to be 100% sure you are doing this process right.

So there are two related but different scenarios: in one case you want to "edit" the current run of your campaign only; in the other, you want to create a long-term database of numbers that are not to be recalled. And, in practice, you likely want to do both things on actual campaigns you are running.