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 life-cycle).

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.

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. To use Asterisk, make sure your server type is set to "Asterisk AMI".

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

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.

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.

A "Fake AMI" server is a test server that can be used for load testing/integration testing, without the need of a physical PBX to connect to. It will simulate people answering the phone (or not answering it) - so it’s a handy way to check if your environment is working or simulate an externally-driven campaign without actually making those calls. Or if you want to check how a WD instance behaves when connected to 5 separate Asterisk servers, without actually setting them up.

It will:

This ensures that the campaign will generate way more calls per second than your average "real" campaign.

When using Fake AMI, the settings for Server, Port and Login/Password are ignored (though they must still be entered).

Connection tests for Fake AMI always pass.

The Test connection button on the trunk allows you to check your trunk. In order to do this, WD first makes sure that there is a working Asterisk connection, and then tries dialing a channel on the trunk using a number that you supply. If all goes well, the number is called and a whistling "milliwatt" sound is played.

The test shows a "success" icon if the call is answered within 30 seconds.

A trunk allows fine control on its maximum numbers of calls per second. Many providers limit the maximum number of originates per second, usually to something like 25 or 30 (but it depends on your provider and the kind of contract you have with them). Providers often blacklist accounts that dial too fast, so if you exceed their allowed CPS rate all calls will end up as REJECTED or BUSY as soon as they are dialed.

As a trunk typically matches one specific outbound route, they usually map to a specific customer account for the provider that in turn would be used as their unit of measuring your originate rate.

In order to implement CPS limiting, what happens is that when Wombat inquires for the number of empty channels on a Trunk, the Trunk will keep track of the number of calls just placed within the last time period, so if the trunk has (say) 50 channels free, but in the last second 10 calls have been requested and the maximum CPS is 30, it will report back that it has only 30-10 = 20 channels free.

Rate limiting is expressed in terms of a maximum number of calls per a specific period in milliseconds. When a new trunk is created, its default is 100 calls per 1000 ms, that is a value high enough to mean "no CPS limits" for most scenarios.

Using a lower CPS limit does not usually affect so much the speed of your campaigns in real-life, as WD will only effectively "spread out" the calls to be dialed over a few seconds. If you are concerned about this, you can see its current impact by monitoring how often the status LIMITED BY TRUNK RATE appears on the running campaign in the Dialer State page.

Calls that end up on a blacklist are evaluated before they are scheduled on a trunk, so rate limiting is not influenced by the rate of black-listed calls.

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

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:

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

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.

An API driven end-point behaves exactly like a Queue end-point, but will not actively monitor the queue located on its Asterisk server; in fact, it will use the queue name as a simple placeholder, and will wait for you to update its status through a periodical API call (see API documentation). Like every other queue end-point, you can see it in real-time - and check that your API updates are working - from the Dialer State page.

Why would you want to use something like this? for example, because you have WD use a server to dial out, but then you trunk calls from the main server to another one holding the actual queues being used. Or you use WD to dial out, but actual queues or end-points are on a server that is not Asterisk based, and you want to control how quickly WD is dialing out.

The way it works is that, on agent status changes, you send WD:

If you use reverse dialling, it is important that the channels you publish let the local Asterisk reach the remote agent, so they must go through a trunk (e.g. SIP/destinationserver/123).

If you just use direct dialling, you do not need to tell WD about the exact agents being involved; you just need to tell it how many agents are in whatever state. The API offers a simmplified call format to handle this common scenario.

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

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.

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

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 soft-phones crash. It’s wise to make plans in advance).

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

The Test connection button allows you to check your End-point. In order to do this, WD:

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

Attributes make WD very powerful: input attributes are sent to Asterisk along the number and are available at the dialplan level as standard channel variables, and can also be used to compose the internal 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.

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:

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:

WombatDialer has a zero-configuration adaptive-boosting mode that lets Wombat manage the over-dialing rate of a queue-based campaign. This way, you can start with a rough idea of the required over-dialing 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 over-dialing 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.

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.

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:

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.

Parameters are set as follows:

Each rule is evaluated against the current number of attempts for the call, so it does not take into consideration the statuses for previous attempts.

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.

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:

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 extended 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:

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.

WombatDialer has the concept of Blacklists; they are lists like any other but are used to collect numbers that are not to be called. A discursive explanation of how they work and interact with the rest of the system is available at Understanding blacklists .

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 to dial 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.

Starting with WombatDialer 19+, black lists are checked two times:

This way, if you add a number to a blacklist, future retries may be blacklisted even if the original call was not.

You may have multiple blacklists on a campaign; their order in unimportant. All numbers are checked against all defined blacklists at once.

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.

If you need to cancel a blacklisted number, you might remove the number from the list or, better, add a special attribute BLACKLISTED_CANCELLED that we suggest to use to record the reason why blacklisting was cancelled. This attribute only happens to the specific number, so if the same number is present multiple times, then each of them must be cancelled separately. See also Cancel numbers from a blacklist.

You may add calls to a running campaign through the API; those numbers will be added to a list called NameOfCampaign/AUTO that is created automatically. This list is just meant as a container to store those numbers and is always present after you add at least one number through the API.

Automatic list are very useful, but they come with a couple of warnings. The first is that an auto list is never explicitly linked to a campaign – it just exists. It acts like a kind of placeholder for calls that were scheduled dynamically – as each and every number has to be a part of a list, your automatic list is the place they will go to.

The second is that the content is not fixed like a call list you upload from a file - it grown as numbers come in while a run is in progress, so it’s final content is the one at the point you stop adding a new number to it.

This has a couple of consequences that may - but most likely will not be - what you want:

So, in general, it is OK to add an automatic list from a closed campaign to another campaign, but it’s not wise to add an automatic list for a campaign that is still running to another campaign - because you definitely want to know in advance which numbers will be processed and which ones won’t.

What you most definitely don’t want to do, is add explicity, at setup time or during its execution, an automatic list to the very campaign it belongs to.

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 trade-off 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:

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:

An example is available in Answering-machine detection.

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.

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

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.

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

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.

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.

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 maximum 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.

WombatDialer is able to track calls that are transferred by the connected agent. Once a call is transferred, it keeps existing in WombatDialer, but the agent is freed so they can take another call.

The agent can transfer a call using two ways:

When a call is transferred:

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:

The following rules apply:

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

They have the following properties:

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.

Any class has the following properties:

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

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