Chapter 3. WombatDialer Concepts

In order to work profitably with WombatDialer, it is necessary to understand the core concepts that come into play.

3.1. The architecture of WombatDialer

WombatDialer is a complex system that is built out of different subsystems. Understanding which ones they are and what they are for will make understanding the whole product easier.

WombatDialer schematics

As a first thing, WombatDialer can be accessed through its GUI Client (in order to configure it, view what it is doing and run reports) or through APIs (see the HTTP API section Section 8.3, “Controlling WD over HTTP”). APIs are meant for external programs to control the behavior of the dialer, e.g. by controlling runs, adding new numbers to dial and creating new campaigns.

The dialer itself is controlled by the GUI Server - this way you can start and stop the dialer process from the GUI. When the dialer runs, an associated watchdog process runs - if the dialer process is to terminate for an unexpected error, the watchdog is supposed to log the error on the system log and restart it. As the dialer is able to sync to the state of an external PBX, during the restart phase calls might not be placed for a few seconds but existing calls will be preserved and tracked correctly.

When the dialer is running, it creates separate AMI handlers for each Asterisk PBX. Each of them runs as a separate thread and connects to a PBX throgh its Asterisk Manager Interface (AMI). If a PBX crashes, the rest of the system keeps on working; and if one PBX is delayed or loses connection, this does not impact other PBXs. In case of errors, each AMI handler will automatically retry until a connection is estabilished.

The dialer also spawns a helper thread that is meant to run long operations, e.g. HTTP notifications (see the HTTP Notifications section Section 8.6, “HTTP life-cycle notifications of calls”), without delaying the main dialer.

Both the dialer and the GUI use a persistence layer that reads and writes to the MySQL database used for long-term persistence and log tracking.

3.2. Asterisk servers

WombatDialer can control activities on multiple Asterisk servers at once. It does so by keeping a control channel open with each server through its Asterisk Manager Interface (AMI for short). Each server is managed independently and in case of failure does not stop the rest of WD from running. Servers can be on the same network as WD is, or can be in remote locations.

Asterisk configuration

When editing an Asterisk server, the following information is required:

  • Server description: the name that this server will appear under in WD
  • Server address: the PBX server’s name or IP address
  • AMI port: the port that Asterisk’s AMI interface uses. Default 5038.
  • Login and Password: the login and password for the AMI user
  • Unit length and Max msg per unit: these settings work as congestion control on the AMI port.
  • Security key is the key that will protect this resource. Leave blank if not needed.

3.2.1. How congestion control works

In order to avoid flooding the PBX with too many messages at once, WD uses the concept of Time Unit; this is a period of time in which no more than a fixed number of messages can be sent.

For example, using the default values, if WD has to start 100 calls at once, it will send no more than 5 requests to Asterisk every 50 ms, and will queue the rest for the next time unit. This still amounts to a respectable rate of about 100 messages per second! (though multiple messages are needed to track a call’s lifecycle).

The difference is hardly ever noticeable from a human point of view, but sometimes the PBX might crash if it receives too many requests at once. If your PBX runs on low-end hardware, you may want to reduce the number of messages per unit; on the other side, if your PBX is on a high-end server, you may want to increase it. In general the defaults work fine in the majority of cases.

3.2.2. Do I have to configure Asterisk to work with WombatDialer?

You need to tell Asterisk that WD is allowed to connect and send commands. Our suggestion is to have a dedicated AMI user on each machine - so it is easier to keep track of which applications are connected to the PBX at a given time.

You could e.g. have a stanza in your /etc/asterisk/manager.conf file like the following one:

[wombat]
secret = dials
read = all
write = all

Even in high load conditions, it is safe to run WD with events "all", as it will automatically manage the set of events that Asterisk is to send it in order to avoid overloading the channel.

3.2.3. What is the Asterisk status?

When WD is running, it will display the current Asterisk status - if a successful connection is possible, then the Asterisk instance will be UP, otherwise it will be DOWN and WD will simply retry after a few seconds.

The current Asterisk status is propagated to the entities that belong to that instance - that is, its trunks, end-points and queues. If there are calls being processed while an Asterisk system becomes unreachable, WD will try and reconcile them to the current status as soon as the system comes back up. This should work even if WD is restarted in the meantime.

3.3. Trunks

A trunk is a set of lines that are addressed as a single logical entity. They can be a set of physical lines (like a DAHDI interface in Asterisk) or a set of logical lines (like a connection to your SIP provider, or to another PBX). It may be one single line as well if nothing else is available!

Trunk configuration

  • Asterisk server: is the name of the PBX on which this trunk is located
  • Name: is a logical name for the trunk to appear in WD
  • Dial string: is the actual Asterisk channel name that WD will invoke (see below)
  • Capacity: is the number of parallel calls that WD can dial. Make sure you do not exceed the trunk’s physical capacity!
  • Security key is the key that will protect this resource. Leave blank if not needed.

You do not need to define all the trunks that are on your PBX, or to define them to their full capacity. For example, if you have a 15-channel E1 to your telco, you might define the trunk in WD as being a 10-channel one, so that you can use the rest with your PBX without any special rule.

It is also perfectly legal to define a physical trunk multiple times, splitting its capacity: again in the example you have a 15-channel trunk, you might define it as two trunks in WD, one having 10 channels and another having 5. Then you can assign each (or even both) to campaigns to control the maximum number of parallel outgoing calls.

A note on the dial string: it must be a valid Asterisk channel name, and the string ${num} is replaced with the actual number being dialed. So the following ones are valid examples:

  • DAHDI/g0/0${num} - dial the number through group 0 of your PSTN interface, prepending the digit zero
  • SIP/myprovider/${num} - dial the number through the SIP server myprovider defined in sip.conf
  • Local/${num}@from-internal/n - dial the number as if was input on an local extension when using a popular Asterisk GUI
[Warning]

When using channels of type Local, Asterisk will sometimes change them during the call, so that Wombat may lose them. Though WD is able to keep track of calls through multiple masquerades and channel renames, if all else fails, you may want to add a trailing /n to your Local channels to make sure that their channel names are not renamed.

3.4. End-points

An end-point is where a call goes after being answered on the trunk.

Trunk configuration

  • Server: is the Asterisk server the EP is on
  • Description: a free name that the EP will appear as
  • EP Type: it can be QUEUE (if it is an Asterisk queue - see below) or PHONE in all other cases.
  • Max channels: the maximum number of parallel calls to be handled by this EP.
  • Located at Extension and Context: the location in the Asterisk dialplan where the EP can be reached.
  • Security key is the key that will protect this resource. Leave blank if not needed.

WD will try and connect answered calls from trunks to end-points on the same Asterisk server. If a campaign has multiple end-points, it will try to connect any EP that has free capacity.

An end point of type PHONE could be:

  • a dial-plan script that plays a recorded message
  • a physical phone given to an agent (set max channels to 1 to receive one call after the other)
  • an IVR script
  • a conference call
  • anything that can be programmed in Asterisk!
[Warning]

WD assumes that Trunks and EPs are always usable to their declared capacity, so it will try to fill them in as soon as possible. If they are to be shared, make sure you have enough capacity for WD plus other resources that may be using them. If you exceed their physical capabilities, you may experience REJECTED calls or a degradation of speech quality for VoIP. Beware!

3.4.1. Queue end-points

As a special case, it is possible to have EPs of type QUEUE. They are used to distribuite calls on a set of agents that are members of a queue. WD will try and observe the queue, in order to determine:

  • how many agents are logged on to the queue
  • how many of them are currently available, that is, neither in conversation nor paused
  • how many calls are currently queued without being answered

The difference between the number of available agents and the number of calls queued is taken as the current capacity of the queue. This value is computed in real-time, so the EP will immediately respond to changes in state to its agent set and to calls queued.

Please note that you can use a single queue both for inbound and outbound activity: if the number of free agents exceeds the number of queued calls, WD will try and fill-in the rest. This makes it easy to implement small blended (inbound/outbound) call-centers.

If the number of free agents is below the number of calls waiting, WD will not place any call and will wait until there are free slots on the queue. This way:

  • calls are in general distribuited to agents as soon as they are queued
  • if the number of available agents is not enough to serve calls at once (e.g because some logged off, or pause in the meantime) then calls are queued and picked up by available agents when they become free.

Queue EPs have a few additional parameters that control their behavior:

  • Queue Name: The exact name of the Asterisk queue being used
  • Boost factor: as most of the calls in a campaign are going to be unanswered, it is often effective to have WD place a number of calls that is a multiple of available agents. For example, if you have a boost factor of 1.5 and 4 available agents, it will try and place 6 calls at once. If more calls are completed successfully than the available agents, the remaining calls are held waiting on the queue. The boost factor is applied only on the number of calls that should be made to saturate agents that do not have a call currently in progress for them. Please note that the boost factor can then be managed on running campaign from the Live page, so you can tweak it dynamically as needed - see Boost factor on the Live page Section 4.3.2, “Controlling the boost factor” - or you can have WD manage it for you based on current traffic conditions - see Adaptive boosting Section 3.6.3, “Adaptive boosting”
  • Max waiting calls: if there are more than this number of calls waiting on the queue, then stop making calls. The number of waiting calls is computed as the number of available channels on the queue minus the numbers of calls currently waiting, as Asterisk will report a call to be waiting even when it’s being connected. In theory there should never be calls queued, as they follow the number of availble agents, but it is possible that either some agent logs off after being counted or some calls reach a queue without passing through WD. This also acts as a counterbalance to high "boost factor" values.
  • Reverse dialing: check to make this EP use Reverse dialing (see below for "Dialing mode")
  • Preview: check to use Preview mode (only valid in Reverse mode)
  • Find and Replace: sometimes - notably in FreePBX systems - agents that are on a queue cannot be dialed directly, and therefore do not work in Reverse Dialing mode. You find that your queue has agents in the format Local/4851@from-queue but what you would like to do is to dial Local/4851@from-internal instead. By setting @from-queue as the Find item and @from-internal as the Replace item, you can easily obtain this result.

In addition to these parameters, the maximum capacity of the EPs is used - so if you have a queue with 100 agents but you set the EPs capacity to 10, WD will never use more than 10 lines on this EP at once.

General Asterisk tips for using Queue endpoints

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

  • Though WD works with static member channels, if you want your calls to go through to agents who may or may not be available (e.g. some days they may be sick) it is strongly advisable to use dynamic agents who log on and off from the queue.
  • As an agent cannot be physically available at all times during the day, it is important that they have a way to pause themselves, be it to run "wrap up" activities after calls or to take breaks. The QueueMetrics web interface offers an excellent panel that lets you add pause codes as well.
  • The queue must provide informational "events" about agent activities. This is enabled by setting "eventswhencalled=true" - otherwise the queue will be unobservable. It is also important that extension presence is correctly observed - e.g. if an end-point is busy because the agent is making a personal call, its queue status should immediately reflect this. Whether this happens or not on your system is a matter of Asterisk version and type of channel that is used to reach the agent - with recent versions of Asterisk and SIP channels this should work automatically. You can make sure this is working correctly by observing the queue status as described in Controlling the Dialer Section 4.2, “Controlling the dialer”
  • The queue should connect calls to agent as efficiently as posssible when there are multiple calls waiting and multiple available agents, so it should have the "autofill" option set to true.
  • Do not use the queue wrap-up feature. As Asterisk does not publish wrap-up events though the AMI interface, WD sees the agent as "idle" and tries routing calls to paused agents.

3.4.2. Dialing modes

Depending on how you set up your end-point, WombatDialer offers different dialing modes.

  • Direct dialing is the default and works with extension and queue end-points. When doing direct dialing, WD will first try to connect the callee and will then route the call to a local extension, that may or may not be a queue. This is fine for delivering voice messages or for situations where any agent can process any call. When working with call queues, this dialing mode might introduce a slight delay, as the call has to be answered by the agent - not usually a big deal, but it might be there.
  • Reverse dialing has WombatDialer connecting the agent first and then placing the call. This is less effective in terms of agent efficiency than direct dialing, as the agent has to wait for the call to connect. The big advantage is that when the callee picks up, he is immediately on line with your agent. WD picks an agent at random from the available pool in order to share the load with all available agents.
  • Reverse preview dialing has the agent reviewing the call before the call is made. This may happen through the API, or by using a special page that WD offers. A number is "reserved" when an agent is to dial it, and the agent has 10 minutes to accept it (and have it placed) or skip it. Calls skipped are marked as such and not retried, unless you set up a reschedule rule to have them retried. Calls for which a decision is not made within 10 minutes are simply returned to the pool of callable numbers.

When using reverse dialing (vanilla or preview) WombatDialer uses a queue to keep track of agent presence. This lets you manage log ons, log offs, agent pause and unpauses the same way you would for inbound queues. Also, as agent state is shared across multiple queues, you can have agents working on multiple queues at once. In reverse dialing, through, calls are NOT connected through queues, as WD decides which agent is to receive which call; in order to do this, the agent channels are connected directly without going through the queue.

When using preview dialing, the agent must reserve a call before it can be placed. In order to do this, WD offers a rich API for your integration software see Preview API Section 8.3.4, “Preview dialing”.

[Tip]

WombatDialer includes a simple preview panel that can be called as a web page and lets you reserve calls and open external URLs for previewing - typically you will use it to preview a call in your CRM software before it goes live. See the Preview Page Section 5.5.1, “Using the agent’s page for preview dialing” for more information.

A simple example tutorial on preview dialing can be found in Preview dialing with Elastix, WombatDialer, QueueMetrics and SugarCRM.

3.4.3. Safety measures when running in reverse dialing

Though most calls will correctly be handled in Reverse or Reverse Preview mode, it is always possible that a call gets "stuck" because the agent that was to serve it was not able to complete it or to answer the phone (this often happens with remote agents becoming suddenly unavailable because of network problems, or because their sofphones crash. It’s wise to make plans in advance).

In this case, WD has a set of built-in safety measures, including:

  • If a call stays reserved for more than 10 minutes, it is unreserved and put back in the pool
  • If an agent is not able to anser to a call that they asked for within 60 seconds, the call is closed with state RS_NOAGENT. You should usually add a reschedule rule in order to "recycle" those numbers.

3.5. Call lists and call records

Call lists are sets of numbers (or more technically, sets of call records) ready to be dialed.

Call list

After being created they cannot be deleted, so you will end up having quite a number of them. In order to avoid having too many of them as visible/selectable items, it is possible to set a "hidden" flag so that they disappear from normal views.

As happens with the campaigns, you can enter a tilde "~" symbol in the search box to see all lists, including hidden ones. All searches happen on both visible and hidden lists.

[Note]

If you add calls to running campaigns through the APIs, WD will create a list called "CampaignName/AUTO" to which all of your new items will be added to. This list is just a placeholder for those numbers and should not be run manually or added to existing campaigns.

It is possible to import and export data from lists through the GUI, and it is possible to create new lists based on the final state of existing campaign runs from the Reports page.

A call list will store multiple instances of the same number and will dial them in succession; so if you upload the same set of numbers multiple times, you get them called multiple times.

As with other WD resources, call lists can be proteced by Security keys.

3.5.1. Call records

A call record represents a single number to be dialed by WD.

Call record

  • Number is the number to be dialed
  • Attributes are an (optional) set of variables that are sent or read from Asterisk during the call processing phase.

Attributes make WD very powerful: input attributes are sent to Asterisk along the number and are availble at the dialplan level as standard channel variables, and can also be used to compose the interrnal or external caller-id. Output attributes instead are values set by Asterisk on this call and are meant for data collection.

You can manually edit the number or the attributes from the web GUI, though you cannot delete an existing call record.

3.6. Campaigns

A campaign is the basic unit of work of WD. It behaves as a template for running an actual campaign, that we call a Campaign Run. A campaign defines:

  • a set of general properties
  • a set of trunks
  • a set of end-points
  • a set of list (zero or more). They are further claassified as normal or black lists.
  • a set of reschedule rules
  • a set of disposition rules
  • a set of opening hours

A campaign can only be run one at a time - before running it again, you must make sure that any actual runs are terminated. Trunks, end-points and list are instead shared entities - you can have multiple campaigns using them at the same time.

Campaign configuration

The following properties are defined for a campaign:

Basics

  • Name: a name to display in WD
  • Priority: the relative importance of this campaign against any other (see below)
  • Status: this field lets you decide what to do with the campaign:

    • RUNNABLE: this campaign can be run
    • CLOSED: this campaign cannot be run, but it is still visibile in the default editor
    • HIDDEN: this campaign is not visible anymore unless you set the flag "Display hidden campaigns"
    • ERROR: this campaign is marked as an error. Cannot be started but visible.
  • Idles on termination: whether this campaign terminates when out of numbers, or will live on waiting for more numbers to be added via the API
  • Batch size: The number of calls to be placed that are cached in memory when reading from the database. They should be roughly 2x the size of outgoing trunks.
  • Security key is the optional key that protects this resource.

Active Period

  • Start active period: the time of day after which this campaign can place calls
  • End active period: the time of day before which this campaign can place calls
  • Allowed Days of Week: the days of the week that the campaign is allowed to run on

Call Placing Details

  • Answer timeout: if the number dialed does not answer within this period (expressed in milliseconds), consider the call to be a NOANSWER
  • Forced closure: the maximum length of this call, in seconds. If reached, the call is forcibly closed and set to status TIMEOUT. Set to zero to turn off.
  • Dial CLID: the caller-id to use for this campaign
  • Agent CLID: the caller-id that will be set on the end-point. This might for example be the internal code of the campaign, or the name of the called person. If the Agent CLID is not displayed correctly, try adding a short delay between the start of the EP leg and the queueing, so that WD has a bit of time to set it up before the call is queued.
  • Dial account: the account code that will be used by Asterisk when writing CDR records
  • Dial presentation: The number to set as "call presentation", that is the number that callees are expected to see as the caller-id. This may be overridden by your provider.
  • Autopause: if this is set and the campaign has queue end-points, each agent will be automatically paused when the call terminates (so that they can process their wrap-up activities). The agent will then have to manually unpause when he is ready to take a new call. (Note: this is not currently implemented).
  • Campaign variables: a set of variables defined for this specific campaign. They should be in the format "A:B,C:D" to set a diaplan variable "A" to "B" and "C" to "D".

Amd & Boosting

  • Boosting model: turn this on to enable Adaptive mode (see Adaptive boosting Section 3.6.3, “Adaptive boosting”) or leave to OFF for manual mode (controlled by the default boost factor and the manual boost factor on the Live page).
  • Initial boost factor: This is the extra boost factor applied when a campaign runs. This value can be modified dynamically through the Live page.
  • AMD FAX tracking mode: Determines which AMD/FAX tracking mode is to be used. If AMD or fax are to be detected, the dialplan variable AMD_MODE is set to the required mode. See AMD and fax tracking Section 3.7, “AMD & Fax detection”.
  • Extra AMD settings: A string of additional parameters to be used when doing AMD detection. This is translated into the dialplan variable AMD_EXTRA. You may or may not want to use this.
  • Audio file to send on AMD: The name of a file to be sent to the client on AMD detection. This is passed to the dialplan under the name AMD_FILE
  • TIFF file to send on fax: The name of a TIFF file to be sent to the client on fax detection. This is passed to the dialplan under the name FAX_FILE

Logging

  • Additional logging: set to QM_COMPATIBLE to have the campaign log to queue_log on the Asterisk server
  • Alias for logging: if this field is set, this is the name that this campaign will be logged under on the queue_log. If empty, the name of the campaign is used. This way you can have multiple WD campaigns log as the same Asterisk queue.
  • Attributes to be logged as QM variables: which attributes (if any) are to be sent to QueueMetrics. See Logging of attributes Section 5.2.1, “Logging of attributes” for a detailed explanation.
  • HTTP notification URL: the URL to be called when a call has a state change in WD
  • Send campaign events by e-mail: whether WD should send lifecycle notifications by e-mail. Can be set to:

    • NO: No notifications.
    • ALL: All campaign life-cycle changes.
    • FINISH: Send only on campaign completions.
  • E-mail addresses: a set of e-mail addresses to receive notifications for this campaign.

A campaign has a priority so that you can have multiple running campaigns at the same time. Priorities are taken into consideration from the lowest to the highest, where each priority level has a go to fill in all available channels; if some available channels are left over, campaigns with a higher priority number are processed. For example, imagine you have a campaign of priority 1 linked to a queue (for human outbound) and then a quality review automated campaign running at priority 10. If there are available agents, it is just natural that the campaign at priority 1 has its go first at placing calls. But if for example some of your agents are paused, then not all outbound lines are used - in this case, they are used by the campaign at priority 10. As soon as your agents go back on line, calls for them are dialed first.

If you have multiple campaigns at the same priority level, they are offered a fair chance of placing calls, so you would expect them to place roughly the same number of calls if calling an homogeneus set of callees. In practice the numbers may differ based on call length, call completion ratio and average answer times.

You can define an active period for calling, so that you can e.g. tell WD to place calls between 9 AM and 4 PM of working days. Any reschedules will be placed only in the active period. If the campaign is in its active period, then any Opening Hours linked to the campaign wil lbe processed. They will be processed in the order they are defined, and in case of no match, the value from the last rule will be used to decide whether the campaign can run or not. See Opening Hours Section 3.9, “Opening Hours”.

There is no guarantee as which trunks and end-points will be chosen when a campaign is running. Call lists instead are processed in order from the first to the last.

If you want WD to send you e-mail when something happens on a campaign, you should make sure that you configured the SMTP parameters as explained in Configuring e-mail Section 7.1.4, “Configuring e-mail”. You can have WD send you notifications for all campaign life-cycle event changes, or simply when the campaign completes.

3.6.1. What happens to hidden campaigns?

Hidden campaigns are removed from the editor so that you don’t have to see them all of the time. They are still present on the database, and may be found again by:

  • entering a search string. It will match all campaigns, including hidden ones (this way it easy to access them and un-hide them if necessary)
  • entering a single tilde "~" in the campaign search box. This will display all campaigns, whether they are hidden or not.

3.6.2. Using attributes in Caller-Ids

WombatDialer lets you enter placeholder values in the Dial CLID, Agent CLID, Dial account, and Caller presentation fields. These values are expanded when a call is actually being connected using the values of attributes set for the number dialed.

For example, you may be dialing number 5551234 to reach mr. White. You may upload a list of numbers setting the attribute NAME to the name of the person called, and you may want the caller-id changed when the call reaches your agents so that they see "WHITE" instead of the campaign’s caller id. Or you may dial a list of numbers by setting an unique call presentation for each of them.

In order to do this, you have to specify attributes to be expanded. For example, if you set the agent CLID of your campaign to "C1 ${NAME}", agents will see on their phone "C1 WHITE", "C1 SMITH" and so on. You may use multiple variables in the same ID, so that you can pass along a practice ID, or the code used to find the person called in your CRM.

Together with the custom attributes you manually define for each number, WombatDialer will also expand:

  • ${NUM} to the number being called
  • ${LST} to the name of the list that the number belongs to

3.6.3. Adaptive boosting

WombatDialer has a zero-configuration adaptive-boosting mode that lets Wombat manage the overdialing rate of a queue-based campaign. This way, you can start with a rough idea of the required overdialing rate (say, 3x) and Wombat will tweak it continuously based on recent traffic, state of the underlying queue, current completion rates and nuisance calls detected.

The model is based on the fact that the quality of traffic on the same campaign, with leads coming from the same list, is strongly correlated in time; so by looking at recent data it is able to extract reasonable call patterns and adapt the current overdialing rate.

The adaptive model is allowed to boost calls in the range from 1x to 4x; this way, if you are running a campaign with a default boost factor of 2X, the booster will have it run between 2X and 8X. On top of this, you can always use the Boosting control from the Live page to further correct the current amount of applied boosting.

[Tip]

Please note that the adaptive booster will try counterbalancing any change you make manually, so you should use the manual toggle only to "speed up" the adaptive convergency behavior in case the dialer should not be aggressive enough at pursuing it.

As with all adaptive and predictive models, the quality of its predictions is strongly linked to how much data it has and how many calls are being made at once, as higher numbers tend to make the system more stable and smoothen its variance.

It works well if you have a good number of calls (dialing at least 40 channels simultaneously) where it can usually get you an agent occupation of 60% to 80% with a nuisance rate of about 1-3%, and it scales back reasonably well for smaller systems with about 10 channels. Of course these figures may be significantly different based on your traffic patterns.

An adaptive boosting example

The following simulation is based on actual real-life data; it shows you a situation where you have 30 agents and you are initially overdialing at a rate of 10X, for a period of a few hours, placing a total of about 100,000 calls. The blue line in the graph is the actual number of agents that are in conversation.

No boosting model

As you can see, the overdialing rate is initially adequate, but the blue line often has "valleys" where the overdialing rate is not adequate. Especially in the second part of the campaign, traffic patterns change and Wombat is not dialling effectively anymore. At the end of the campaign, agents have an utilization of about 56% and a nuisance rate of about 3%.

Adaptive boosting model

By using the adaptive model, you can see that the blue line is consistently higher, and that it matches trends in calls by counterbalancing the quality of traffic. By the end of the campaign we have a total utilization of 73% (+30% over the basic model) with a nuisance rate of 4%.

This example was chosen because the quality of the leads was intentionally pretty bad, and this is the case where you nahe the highest improvement in using a predictive model.

3.6.4. Reschedule rules

It is a fact of life: most calls placed on an outgoing campaign are destined to fail. Maybe the user is not available, maybe your provider has a temporary failure, or maybe your PBX (or even WD itself!) crashes while calling. It is advisable to take this into consideration when programming a campaign. For example, you could say that:

  • if a number is busy, you retry two times after 5 minutes each
  • if a number does not answer, you retry two times after 30 minutes each
  • if a call has a technical glitch and ends in error, or is lost due to a PBX crash, then retry it once in 10 minutes

The number of retries is computed after the call is first attempted - so if you have a retry rule of 2, the call is first tried once and then retried twice, for a maximum of three times if it goes wrong every time. All retries are attempted in the active period of the campaign - so if a call is rescheduled in 20 minutes at 5:50 PM and the campaign is not allowed to run after 6 PM, then it is retried the next day.

WD in general tries first to obey any applicable reschedules and then fetches new calls form call lists, so you can expect the retry period to be quite accurate in most scenarios. Still there is no hard guarantee that a call will be placed at exactly the time it was rescheduled for.

Parametrs are set as follows:

  • On status: the call status this rule applies to
  • With custom status: the custom status to consider (see below). Custom statuses can be set through the API - see Controlling WD from Asterisk Section 8.2, “Controlling WD from Asterisk”.
  • Max Attempts: the maximum attempts this rules applies to
  • Retry after: the number of seconds to retry after
  • With mode: the way to compute the retry period

When rescheduling, you can set the mode to FIXED or MULTI. In fixed mode, if you set the retry time to 5 minutes, it tries after 5 minutes at every attempt. In multiplicative mode, the retry period is computed multiplying the number of the current attempt by the number of attempt it’s trying - so it would be 5 minutes on the first attempt, 10 minutes on the second, 15 minutes on the third and so on.

If a call has a normal completion or is over the maximum number of retries, then it is not rescheduled. You can look-up the status of the last attempt in order to know why it was not rescheduled.

Writing advanced reschedule rules

It is valid to have multiple reschedule rules that pertain to the same status code - in this case, WD will find the rule that matches. For example, imagine we have two rules:

             Attempts   Retry in
             --------   --------
RS_BUSY         2         300s
RS_BUSY         5        1800s

Up to the second BUSY attempt, WD will retry in 5 minutes (300 seconds); from the third to the fifth, it will retry in 1800 seconds (30 minutes).

The status code considered is always the current status code; so for example given this set of rules:

             Attempts   Retry in
             --------   --------
RS_BUSY         3         300s
RS_NONASWER     1         600s

If we get a BUSY on first attempt and a NOANSWER on second attempt, as the NOANSWER retries only once, the call is not retried.

You can also have an extended status set through the APIs - if that is present on the call, the rule matches only if the extended status matches - see Controlling WD from Asterisk Section 8.2, “Controlling WD from Asterisk”.

If you specify an ExtStatus for the call, then only the same ExtStatus will match. If you do NOT specify an ExtStatus, then the rule will match any ExtStatus. If you need the rule to match only on an empty ExtStatus, then you must set it to $.

3.6.5. Disposition rules

Disposition rules are like Reschedule Rules; the main difference is that while a Reschedule Rule is applied on each call tried, a Disposition Rule is matched only when the call is not rescheduled further.

For example, let’s say that you are dialing out on a campaign where there is a reschedule rule to retry twice in 10 seconds on busy. You dial a number, and the number is busy; it is rescheduled in 10 seconds, retried and it’s busy again; it’s rescheduled again, and again it’s busy. At this point the call is "complete", meaning that it is not meant to be rescheduled again. So, the call will be matched against any disposition rules with the current status of "busy".

With disposition rules, you can have actions that are more complex than reschedule rules and are meant to interact with external systems. You can:

  • Call an HTTP service of type GET or POST, with a variable payload.
  • Send an email (for example, if you want someone to be notified when some rare status happens)
  • Add the number to an existing list,
  • Add the number to an existing blacklist. This is the same thing as adding the number to a list, but with an optional parameter to control the amount of time the number is to be blacklisted.
  • Pipe the number to be recalled on a different run. The run must be active at the time the number is added.

Multiple rules may match the same call, so for example you might be sending two separate HTTP notifications and an email, or you could reschedule the number to be recalled and add it to a new list at the same time. Matching happens on the basis of the (last) dialing state. If the rule specifies an extened state, it is to be matched as well.

When a Disposition Rule is matched, sometimes it is useful or necessary to access some information from the call and put it in the request, for example to specify the number called in the email body. WombatDialer offers a number of variables that you can use for this purpose:

  • NUM is the number dialed
  • N_RETRY is the number of retries made on this call
  • LIST is the list name
  • STATE is the current state
  • EXTSTATE is the extended status (if set)
  • CAMPAIGN is the name of the campaign that this call was dialed upon
  • RUNNAME is the name of the current campaign run
  • ATTR is a prefix that lets you access call attributes. They can be inbound or outbound attributes.

So if you set an HTTP GET URL of 'http://server/page.php?num=${NUM}&var=${ATTRV}' will be rewritten with the current number and the current value of attribute V.

When doing a disposition to a list or a different run, you can control which attributes are to be set on the new number. You can decide if you want ALL, NONE, INBOUND or OUTBOUND attributes; plus you can manually specify a set of attributes which values will be set on the new call.

3.6.6. Black lists

WombatDialer has the concept of Black Lists; they are lists like any other but are used to collect numbers that are not to be called.

When WombatDialer is loading numbers to be dialed, they are checked against all black lists defined for that campaign. This is done automatically and behind the scenes; if a number is found, it is logged as dialed in state BLACKLIST without actually trying it.

Blacklists are checked dynamically when a number is first scheduled; so if you add numbers to a blacklist while a campaign is running, new numbers to be scheduled will be checked against the blacklist. Numbers that are already scheduled (e.g. to be recalled) will not be affected.

[Note]

WombatDialer schedules numbers well in advance before they are called, so it may take a while before it starts checking the blacklists.

You may have multiple blacklists on a campaign; their order in unimportant.

A number may be added to a blacklist up to a specific point in time; this means that the number will be a valid match for the blacklist only until the date passed is in the future. In order to do this, you need to set a call attribute called BLACKLISTED_UNTIL with a valid date in the format "YYYY-MM-DD.hh.mm.ss" or "YYYY-MM-DD". You may also have an expiry date computed for you by using a Disposition Rule to add the call.

Note that if you use the shorter date format, the number is supposed to be blacklisted until the midnight of the given day. If the date format is not valid, the number will be blacklisted forever.

[Tip]

It is perfectly acceptable to add a call mutiple times to a blacklist, each time having different expiry dates. The number will be blacklisted up to the maximum date specified.

3.7. AMD & Fax detection

WombatDialer allows you to track answering machines (AMD) and faxes. Following the general WombatDialer philosophy of leveraging the capabilities of your PBX, WombatDialer sets a series of additional dialplan variables that are to be used in order to detect them and react accordingly. This way:

  • You configure AMD and/or fax detection on your PBX
  • When either detection triggers, you have variables that tell the dialplan how to handle those cases

In general, we suggest using an extended status of "AMD" when an answering machine is detected, and "AMDSENT" when a message is left on the machine; and "FAX" when a fax is detected and "FAXSENT" when a fax is successfully sent.

It is also wise to offer your agents a quick blind transfer hook that lets them transfer calls to AMD or FAX routines in case the detection went wrong.

[Warning]

Working with AMD and fax can be tricky. Make sure you can talk to an Asterisk consultant with a proven experience before running a large-scale campaign.

3.7.1. Detecting answering machines

Asterisk ships with an application called AMD that will analyze audio and try to guess whether the other party is a live person or an answering machine. Keep in mind that the call does not "go through" while the analysis is in progress, so there is a definite tradeoff between a long and accurate detection versus a quick but less accurate detection.

AMD receives a set of parameters to discriminate what is an answering machine and what is a live person, so you may want to experiment a bit to find a setup that works for your country and for your callers.

A good starting point would be to set in amd.conf the following parameters:

initial_silence            = 2500
greeting                   = 1500
after_greeting_silence     = 300
total_analysis_time        = 5000
min_word_length            = 120
between_words_silence      = 50
maximum_number_of_words    = 4
silence_threshold          = 384

It is also customary to send a background tone (be it blank or a beep) to the called party to help set-up the line on SIP circuits. This way the accuracy of AMD is reported to be increased considerably.

So you would:

  • Play audio, e.g. via Background(beep)
  • Run AMD, optionally passing the contents of AMD_EXTRA if you want to override the default parameters
  • Check the status of the dialplan variable AMDSTATUS. If set to "MACHINE", go to the AMD processor; else route to a live agent. You may want to log the AMDCAUSE as well; it contains an explanation of the reason why Asterisk decided the call was of the specific kind.
  • On the AMD processor, set the extstatus to "AMD", so that Wombat logs this call as an Answering Machine
  • Wait for silence (so the greeting message is terminated)
  • Play the audio file defined in AMD_FILE
  • Set the extstatus to AMD_SENT
  • Hang up.

An example is available in Answering-machine detection Section 6.9, “Effective answering-machine detection”.

3.7.2. Detecting faxes

Asterisk is natively able to detect faxes on DAHDI and SIP channels; all you have to do is tell it to run the detection engine.

  • For DAHDI, you have to turn on the option "faxdetect" in chan_dahdi.conf by setting it to "incoming", "outgoing" or "both".
  • For SIP, you need to turn on "faxdetect" in sip.conf. Valid options are "cng", "t38" or "yes" for both.

When a fax is detected, the dialplan will jump to the extension "fax". At this point:

  • you set the extstatus of the call to "FAX" in Wombat (so it can be traced)
  • you send a fax by issuing the command SendFAX(/path/to/FAX_FILE,d), where FAX_FILE is the file name set through the GUI
  • you set the extstatus to "FAXSENT" in Wombat
  • you hang up the call

The file must be a valid TIFF file that is compatible with Asterisk. Digium’s "Fax For Asterisk Administration Manual" documents a process for converting a PDF file into a TIFF using commonly available Linux command-line tools.

3.8. Campaign runs

Campaign runs are real, out-calling instances of campaigns. You start them from the Live page, by selecting one of the available campaigns. They are named after their parent campaign and the time when they were started.

The system displays a set of information on the Live page:

Campaign name: C1
Started at: Wed Oct 17 15:54:22 CEST 2012
Current state: COMPLETED
Priority: 10
Calls placed: 40 - Items in call cache: 0
Calls terminated: 10
Life-cycle termination rate: 25% - Reschedule rate: 75%
Est. remaining calls: 0
Running for: 00:00:05 - Estimated completion in: 00:00:00
Attempts per hour: 72720 - Completions per hour: 72720
High-water mark: 20 in L2

The run name is actually made of the Campaign name plus the time it was started. This uniquely identifies a run in the system.

The other parameters are as follows:

  • Current state: is the state the run is in (see below).
  • Priority: is the campaign’s priority
  • Calls placed: is the total number of call attempts made
  • Items in call cache: is the number of calls currently held in the hopper plus any open reschedules
  • Calls terminated: is the numbers of calls that have either been successful or gone through the last possible reschedule, so they will not be retried
  • Life-cycle termination rate: is the percentage of calls that are not to be retried (terminated)
  • Reschedule rate: is the percentage of calls that are to be retried
  • Est. remaining calls: this is a rough estimate of calls that remain to be placed. Might be rather inaccurate - consider it only a basic indicator that will converge to zero as the run terminates.
  • Running for: is the total time that this run has been going.
  • Estimated completion: tries to display the remaining time to completions. This time may actually vary strongly from what is displayed depending on what happens during the campaign. Estimates will be produced after a few calls have completed.
  • Attempts per hour: its the average number of calls attempted per hour on this run
  • Completions per hour: is the average number of calls completed per hour
  • High-water mark: the last call record added to the cache

3.8.1. A run’s life-cycle

When a run is first started, it goes through a set of stages.

Run life-cycle

Initially the run will be made RUNNABLE, WD will prepare to run it and will put it in RUNNING state. A run stays in state RUNNING as long as it has retries to complete or calls not yet placed. When a RUNNING campaign is out of the allowed time period, it is put to WRONG_TIME; from here it goes back automatically to RUNNING state when time conditions (hour and day of week) are successfully matched.

When out of calls, a run can either COMPLETE or become IDLE; when IDLE it waits for new calls to be added through the API and goes back to RUNNING mode to process them.

A RUNNING campaign run may be manually PAUSED and from PAUSED it can manually be made RUNNING again.

If a run is no longer needed, it can be manually set to REMOVE; when in REMOVE status the run is terminated and cannot be restarted.

3.8.2. A call’s life-cycle

When a call is started, it is first loaded in a cache called hopper that contains calls that are to be dialed soon. This way it is not necessary to consult the database for each and every call to be made.

Call life-cycle

When WD is about to place the call, it marks it as SCHEDULED and sends it to Asterisk for processing; if all goes well, it then goes from REQUESTED to DIALLING to CONNECTED and then TERMINATED.

Of course it may not be possible to start the call (so you get BUSY, NUMBER and NOANSWER states), or the call might be ended by WD because it exceeded the maximun allowed duration (TIMEOUT).

When using reverse dialing, a call starts its life being RD_SCHEDULED, so that the agent can be called. When this happens, the call progresses forward. In preview mode, the call is first RD_RESERVED and when the agent approves it, it is placed.

Initial states
IN_HOPPER
Call will be placed soon - not visible to user
SCHEDULED
WD requested the call to be placed
RD_RESERVED
When preview dialing, an agent has reserved this call but has not processed it yet
RD_AGENTREQ
When doing reverse dialing, WD is connecting the to an agent before the call is actually placed
Call processed
REQUESTED
The request was sent to Asterisk for processing
RD_REQUESTED
Asterisk is processing this call when reverse dialing
DIALLING
Asterisk confirmed the call was started
CONNECTED
The opposite side picked up the call
Error states
RS_ERROR
A technical error happened while dialing
RS_LOST
WD lost track of this call. Usually happens only on system crashes.
RS_NOAGENT
An agent that was being predialed in reverse mode did not answer. You should reschedule those calls.
Calls that could not go through
RS_REJECTED
The call was rejected by the network. This is usually caused by the upstream provider returning 'Congestion' (all circuits busy), 'Off-hook dialing' with analog interfaces, or your upstream provider terminating a call before it’s answered without providing any status code.
RS_BUSY
Number called was busy.
RS_NUMBER
Number called appears to to be invalid. Asterisk also raises this error if it cannot allocate a new channel for the call.
RS_NOANSWER
Number did not answer within the Answer timeout period set on the Campaign
Completion states
TERMINATED
Call completed successfully
RS_TIMEOUT
Call was forcibly closed because it exceeded the maximum allowed duration set on the Campaign.
RS_AGENTSKIP
Agent decided to skip this call.
RS_BLACKLIST
The call was skipped as the number was blacklisted.
States not already implemented
RS_AGENT
Agent requested special retry.

3.9. Opening Hours

It is very often needed to have a finer level of control on the opening hours of a campaign.

Typical scenarios include:

  • Having different opening and closing times for a campaign during the week. For example,you might want to dial out from 9:30 to 11:30 and 13:30 to 17:00 Monday to Thursday, and only 9:30 to 13:00 on Fridays.
  • Marking specific time periods as invalid; for example, public holidays.

It is also often needed to maintain and share these "opening hours" across campaigns; for example, by having one single instance of public holidays to be shared across all campaigns.

Opening Hours work by defining a set of items that must match for a rule to be considered valid.

  • Rules are scanned from top to bottom, in order
  • If a rule matches, its output will be passed to the campaign.
  • If no rule matches, the campaign can ask a rule for a default value.

For example, let us say that we want to implement the multiple hours scenario as described above:

Rule  DayOfWeek      DateFrom DateTo    TimeFrom   TimeTo    State

 #1   Mo Tu We Th    -        -          9:30:00   11:30:00  OPEN
 #2   Mo Tu We Th    -        -         13:30:00   17:00:00  OPEN
 #3   Fr             -        -          9:30:00   13:00:00  OPEN

You could also have a separate rule based on dates to flag some days as always invalid:

Rule  DayOfWeek      DateFrom DateTo    TimeFrom   TimeTo    State

 #1   -              25/12    26/12     -          -         CLOSED
 #2   -               1/01     1/01     -          -         CLOSED

Rule 1 tells us that Dember 25 and 26 are always invalid; and January 1 is as well.

When running on an existing campaign, you first have to make sure that the campaign is allowed to run in the specific time period.

[Tip]

In most cases, you will want to keep the campaign always active and tweak associated Opening Hours instead. This lets you use campaign rules for very simple campaigns and Opening Hours for more complex scenarios.

Then you would add:

  • First the Opening Hours based on dates. If any of these match, we know that we cannot run.
  • Then you would add the rule about time periods by day, with a default of CLOSED.
[Warning]

The order in which you add Opening Hours to a campaign is important, and so is the order of rules within an existing Opening Hour.

3.10. Opening Hours Inspector

Under the Opening Hours tab, inside of the Campaign Editor page, you can see a button named "Test Opening Hours". This button opens the Opening Hours Inspector, a tool designed to preview the effects of Opening Hours rules on your campaign.

Opening Hours Inspector

As you can see in the picture, the inspector shows a coloured bar for each day of the week, each colour representing the state of your campaign in different times of the day. You can choose the date from the calendar widget at the top of the inspector.

If you fly with your mouse over the coloured bars, WombatDialer will show you a pop-up text with the state of the campaign, the name of the rule that is beign applied and the name of the matching sub-rule. If a sub rule has no name is automatically named after a number in a sequential fashion.

Here is a list of the possible states for a campaign:

  • OPEN: The campaign is open due to the campaign active period (no Opening hours rule applied).
  • CLOSE_DAY: The campaign is closed due to the campaign active period (no Opening hours rule applied).
  • CLOSE_HOUR: The campaign is closed due to the campaign active period (no Opening hours rule applied).
  • CLOSE_RULE: The campaign is closed due to an explicit Opening Hours rule.
  • OPEN_RULE: The campaign is open due to an explicit Opening Hours rule.
  • DEFAULT_OPEN: The campaign is open due to the Def. Mode of the last Opening Hours rule
  • DEFAULT_CLOSE: The campaign is closed due to the Def. Mode of the last Opening Hour rule.

3.11. Call logs

After a call record is processed, it leaves a "trail" in the form of a call log.

Call log detail

From here we can see:

  • Call: this section displays the number that was called and any attributes that are set on that call record. Any output attributes (coming from Asterisk) are marked with a ">" prefix.
  • Campaign: the name of the campaign that this call was placed on
  • Run as: the name of the campaign run that had this call placed
  • Run started: when the campaign run was started
  • List: The list this number belongs to
  • Attempted: when the call was actually attempted
  • Wait Pre: the difference (in milliseconds) between call stages REQUESTED and DIALLING
  • Wait After: the difference (in milliseconds) between call stages DIALLING and CONNECTED
  • Talk: the duration (in milliseconds) of the active call, that is, while the callee was connected
  • Status code: the call status code when it was closed
  • Extended status: the extended status set by Asterisk
  • Retry #: The number of retry this call was on (0: initial attempt)
  • Next retry: When the next retry is scheduled. If set to zero, this means the call was not set to be rescheduled.
  • Trunk: The trunk the call was placed on
  • Log Id: The internal log id
  • Asterisk channel: The Asterisk channel that was created for the first leg of the call
  • Asterisk unique: The Asterisk internal Unique-Id that was used

3.12. Users and security

WombatDialer offers a powerful and pervasive security model that is similar to the one used in QueueMetrics. It is built around the concepts of users, classes and keys.

The idea is that each user has a keyring and all features are controlled by keys. Every time WombatDialer has a possible feature to show the user (e.g. editing servers) it checks whether the current user holds the correct key in its keyring. If he does not have it, the feature is hidden or grayed out.

Each user has a keyring that is composed of their personal keys plus all the keys for their class. This way you can organize multiple groups of users (e.g. administrators, monitors, etc) with different grants, and then give each specific user additional keys to fine-tune each person’s profile.

A set of default users Section 9.2, “Default users” and of security keys Section 9.1, “Security keys” is available below.

3.12.1. The security model

You can set security keys on most entities in WombatDialer - you can have them on servers, trunks, end-points, campaigns and lists. They will be enforced for:

  • Selection of items to be added to camapigns
  • Live monitoring
  • Reporting

The following rules apply:

  • Elements are visible both to users holding the required key and to their creator, even if he does not hold the required key (in order to avoid "locking yourself out")
  • Elements having no keys will be visible to everyone
  • Key security is not transitive, that is, if you can observe a campaign, you can observe it in its entirety, even if (say) one of the trunks it uses is protected with a key you do not hold.

3.12.2. Users

A user is some person who can log on to WombatDialer.

User editor

They have the following properties:

  • Login and Password are used to log on from the main page
  • Real Name is displayed on the WombatDialer page
  • Enabled may be toggled to avoid a user logging on without deleting it.
  • E-mail The user’s e-mail address
  • Master key: if set to "yes", all security checks are bypassed. You should only set it to yes for testing and debugging.
  • Class is a pre-defined set of keys that is used for this user. Any user must have a class.
  • User keys are additional keys granted to this user. They are space.-separated. If keys are prefixed with a minus sign, they are revoked if present in their class and ignored otherwise.
  • Logged on are the number of successful log-ons for this user and Last logon is the time this user last logged on successfully.
  • Comment and Token are free fields you can use to keep track of your users.

3.12.3. Classes

Classes are common profiles to be given to all users of a certain kind. So you do not have to remember which keys to give users for each specific functionality, but you can group them all together.

Classes editor

Any class has the following properties:

  • Class name is the name used in the User Editor to choose the class.
  • Description is a long version of the class name
  • Keys are a space-separated set of keys that are granted to all users of this class.

You can create new classes than the ones that ship with WD in order to fine-tune access controls for your instance.

3.12.4. The system log

When something important happens in WombatDialer, it is written to the System Log. The system log tracks:

  • Campaign lifecycle events
  • User logins and log-offs
  • System errors

The Syslog page