1. WombatDialer 0.7.5: bug fixes and more

    What is Erwin the Wombat doing sitting on a large cup of coffee? well, he’s been working quite a bit lately.

    We have just released version 0.7.5, that is meant mostly as a bug fix release but also adds some architectural improvements.

    • First, we fixed a number of issues to improve the accuracy of call and queue tracking. The bottom line is that the dialer is more efficient when tracking queues and will try to keep them fully saturated at all times. We also fixed a number of error conditions that were reported by our partners.
    • Secondarily, we changed the log storage model. This means that logs will no longer make entities impossible to delete. Logs will also be scanned more efficiently for large systems (over 1M records).
    • The third important item is that the dialer will now start up immediately as the web application is loaded, unless you just performed an update. This means that you will not have to log in to restart the dialer after a system reboot.
    • The fourth important item is that from the Reports page you can now export to CSV the details of all the calls that were placed in a set of runs. This was a popular demand.
    • Last but not least, the dialer view is way more clear when tracking queues - you can now see who is logged on, how many calls are being placed, and how many channels are used by that queue.

    The downside is that the upgrade may take a while to run - as logs have to be converted, the updater processes about 30,000 calls per minute - so if you have a log database of one million calls, the upgrade may take about 45 minutes to complete. We suggest making a complete backup of the database beforehand, just in case.

    What remains to be done for 0.8? a public regression test. We are working on a suite of tests that will let you run a stress test of WombatDialer on your own systems, to assess system capacity and gettiong familiar with the different dialing modes Wombat offers. This will be a simplified and cleaned-up version of the one we use internally to test the capacities of a release. We are also working on a tutorial of how to run a blended inbound/outbound call-center using WombatDialer and QueueMetrics.

    So - it’s time to update WombatDialer to 0.7.5 now.

    We welcome your feedback about what you would like to see in new releases - we have a public suggestion jar at http://wombatdialer.userecho.com/

    Happy dialing!

     
  2. WombatDialer 0.6.5 released

    Today we released version 0.6.5 of WombatDialer - this version contains a few minor fixes for the UI, most noticeably a complete reworking of the security system with locks and keys.

    Together with version 0.6.5, we release a new version of the User Manual that is now complete and covers all topics, including full documentation for the APIs, system administration and a Cookbook section that presents some real-life scenarios, plus a Getting Started section that shows a basic installation on Elastix.

    We have a new video tutorial displaying WombatDialer installation and how to set up a simple telecasting campaign to run on an existing Elastix system in less than 10 minutes. It also shows how to set up basic rescheduling rules and how to analyze what went on during the campaign.

     
  3. Elastix queue call-backs with WombatDialer

    You are called in to a client site; they seem to have a problem. They run a small (10 agents) inbound call centre, and when you join everybody else in the meeting room, there is a large and colourful 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:

    • your customer are happy; they don’t have to wait in queue for so long
    • your call center manager is twice happy: the first time because wait times and abandon rates go down, the second one because by placing calls at a convenient time they can smooth out the workload of their agents during the day

    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 a definite topology 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:

    • First we create a normal queue, for inbound. We call it “400”.
    • Then we create a call-back queue. If our main queue is called “400”, then let’s call this second queue “401”. The idea is that WD will monitor this queue - when you have members on this queue, then WD will start placing calls. This way an inbound call-center with multiple queues will find it very natural to have some agents join and leave a call-back queue. When you creet this queue, make sure you set “Ring Strategy: rrmemory”, “Event When Called: Yes”, “Member Status: Yes”, “Autofill: yes” so that WD can use it effectively.
    • we create a piece of dialplan that will handle the exits from queue “400” and will gather the telephone number
    • we create a new “custom extension” (399) that will jump in the dialplan at “Local/1@queue-leavenumber”
    • In Elastix, we create an IVR menu and set it as a destination for queue “400”. This menu has only one option (1) that basically jumps to the custom extension “399” that we just created, in order to call our script
    • we go back to the queue “400” and set its “Fail Over Destination” as our IVR we just created

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

    [queue-leavenumber]
    exten => 1,1,NoOp
    exten => 1,n(Start),agi(googletts.agi,"Please enter your telephone number and we will call you back.",en)
    exten => 1,n,agi(googletts.agi,"The number must be composed of 7 digits.",en)
    exten => 1,n,Read(CBNUM,beep,7,,2,5)
    exten => 1,n,NoOp( Num ${CBNUM} )
    exten => 1,n,GotoIf($["${LEN(${CBNUM})}"="7"]?lenOk)
    exten => 1,n,agi(googletts.agi,"The number you entered has the wrong number of digits.",en)
    exten => 1,n,GoTo(1)
    
    exten => 1,n(lenOk),agi(googletts.agi,"You entered the following number",en)
    exten => 1,n,SayDigits(${CBNUM})
    exten => 1,n,Wait(1)
    exten => 1,n,agi(googletts.agi,"Press 1 to confirm or any other digit to start again.",en)
    exten => 1,n,Read(CONF,beep,1,,2,5)
    exten => 1,n,GotoIf($["${CONF}"="1"]?Store:Start)
    
    exten => 1,n(Store),NoOp
    exten => 1,n,Set(WHEN=${STRFTIME(${EPOCH},,%y%m%d-%H%M%S )}
    exten => 1,n,Set(PARM=number=${CBNUM}&attrs=orgQ:400%2Cwhen:${WHEN})
    exten => 1,n,Set(foo=${CURL(http://10.10.5.18:8080/wombat/api/calls/? op=addcall&campaign=callback&${PARM})})
    exten => 1,n,agi(googletts.agi,"Thank you! we will call you back as soon as possible.",en)
    exten => 1,n,Hangup
    

    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 comma ‘,’).

    In order to configure WombatDialer:

    • We create a trunk called “Trunk” with a dial-string of Local/9${num}@from-internal and a capacity of 10 lines. This basically replies all numbers as if they were entered on a local extension prefixed by 9.
    • We create an End-Point of type Queue for monitoring queue 401; set extension to “401” and context to “from-internal”; max number of lines to 10; boost factor as 1 and max waiting calls to 2. This means that the number of calls placed will match the number of available agents on queue 401.
    • We create a campaign called “callback”; set it to Idle on termination and turn on QM_COMPATILE logging. We add the trunk and the EP we just created. We create a set of reschedule rules in order to handle REJECTED, BUSY, INVALID and NOANSWER calls, e.g. by retrying up to 5 times each waiting 10 minutes between each attempt. Note that we create no lists for this campaign.
    • We start the new campaign; having no numbers, it should immediately turn yellow on the Live page to tell you it’s idling.

    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:

     Number:     5551235
     Attributes: orgQ:400   when:121115-153402
    

    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 there is a caller-id on the call, you could ask the caller whether to use it as the number to be called back
    • You could add time limits to the WD campaign so that you are sure that no calls are made otside acceptable periods

    See also

     
  4. Helping wombats - one carrot at a time

    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 non-profit 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 dialling 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:

    • Create an electronic list of those leads
    • Leads from their list are dialled
    • If the call is answered, a message is played that explains what the campaign is for
    • If the callee is interested, they press 1 to be put in conversation with a volunteer that will explain how to send a donation.

    This setting leads to two huge efficiency boosters:

    • As numbers are dialled automatically and error conditions are handled behind the scenes, a lot of drudge work with paper and telephone keyboards is automated; no more post-it notes to recall a busy number!
    • As they noticed that about 50% of the calls made manually result in calls to busy numbers or numbers where nobody picks up, and that only 50% of the callees are actually interested after an initial interview, they expect that 75 calls out of every 100 they make can be screened out automatically. So if they have 4 volunteers on shift, WombatDialer could start 16 calls at once on average, and have all of our volunteers busy most of the time with people who are actually interested in contributing.

    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:

    • Strategy is set to “rrmemory”
    • Queue events: yes (this is very important – if you don’t do this Wombat won’t be able to observe your queue at all).
    • Autofill: yes (all free agents are assigned calls at the same time)

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

    [999]
    autofill=yes
    eventmemberstatus=yes
    eventwhencalled=no
    maxlen=0
    strategy=rrmemory
    

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

    [friendscampaign]
    exten => 100,1,Answer
    exten => 100,n,Playback(campaign_message)
    exten => 100,n,Read(type,,1)
    exten => 100,n,GotoIf($["${type}" = "1"]?ok)
    exten => 100,n,Goto(1)
    
    exten => 100,n(ok),UserEvent(CALLSTATUS,Uniqueid:${UNIQUEID},V:1)
    exten => 100,n,Queue(999,,120)
    

    (In order to make this example shorter, we assume you have a baisc familiarity with WombatDialer concepts such as Campaigns, Servers, Trunks and End-points. If you don’t, see the tutorial at http://blog.wombatdialer.com/post/23597570852/tut-idle )

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

    • Type: QUEUE
    • Queue: 999
    • Max channels: 10
    • Boost factor: 2.0
    • Max waiting callers: 2

    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 under-used, 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:

    • if you analyze the queue “friends” (the one that matches the name of your WombatDialer campaign) you will see the total “external” system activity – all calls placed on the campaign are tracked, and the wait time matches the external wait time (that is, the time between the dial request and a successful connect). All calls appear to be connected on the end-point, as you could have multiple ones assigned to the same campaign.
    • if you analyze the queue “999”, you will see the human side of action – how many calls were queues for humans to interact with, how fast they were answered and by whom.

    Further expansion

    • You can use the same end-point in multiple parallel campaigns, if needed.
    • It is possible that your campaign reaches someone who is interested but is currently doing something else so does not have the time to speak to your volunteers. They could tell you by hitting 2 – you could add a Reschedule Rule that reschedules the call in a few hours.
    • You could easily generate personalized messages instead of one single rescorded message by using a Text-to-Speech synthesizer, as in example http://blog.wombatdialer.com/post/24187267017/drstrangelove

    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!

     
  5. Tutorial: Outbound IVRs and dr. Strangelove

    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:

    5551234,HH:10,MM:30
    5556785,HH:11,MM:00
    5552012,HH:11,MM:30
    

    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.

    [drstrangelove]
    exten => s,1,Answer
    exten => s,n,Set(TIMEOUT(response)=5)
    exten => s,n,UserEvent(CALLSTATUS,Uniqueid:${UNIQUEID},V:0)
    exten => s,n(start),agi(googletts.agi,"Your appointment with doctor 
                    strangelove is for tomorrow at ${HH} ${MM}")
    exten => s,n,agi(googletts.agi,"Press 1 for to book for major surgery 
                    press 2 for psychiatric counseling.")
    exten => s,n,Read(type,,1)
    exten => s,n,GotoIf($["${type}" = "1"]?appe)
    exten => s,n,GotoIf($["${type}" = "2"]?psyc)
    exten => s,n,Goto(start)
    
    exten => s,n(appe),UserEvent(ATTRIBUTE,Uniqueid:${UNIQUEID},APPT:APPE)
    exten => s,n,agi(googletts.agi,"You choose the appendectomy.")
    exten => s,n,Goto(confirm)
    
    exten => s,n(psyc),UserEvent(ATTRIBUTE,Uniqueid:${UNIQUEID},APPT:PSYC)
    exten => s,n,agi(googletts.agi,"You choose psychiatric counseling.")
    exten => s,n,Goto(confirm)
    
    exten => s,n(confirm),agi(googletts.agi,"Thank you! Now press 1 
                    to confirm the appointment")
    exten => s,n,agi(googletts.agi,"or 2 to cancel it.")
    exten => s,n,Read(conf,,1)
    exten => s,n,GotoIf($["${conf}" = "1"]?ok) 
    exten => s,n,GotoIf($["${conf}" = "2"]?ko)
    exten => s,n,Goto(confirm)
    
    exten => s,n(ok),UserEvent(CALLSTATUS,Uniqueid:${UNIQUEID},V:1)
    exten => s,n,agi(googletts.agi,"The appointment was confirmed. 
                    See you tomorrow.")
    exten => s,n,Hangup
    
    exten => s,n(ko),UserEvent(CALLSTATUS,Uniqueid:${UNIQUEID},V:2)
    exten => s,n,agi(googletts.agi,"Boo the appointment was cancelled.")
    exten => s,n,Hangup
    

    Notable points in the code above are:

    • Custom call attributes HH and MM are passed along with the phone number so we can know what to tell each client.
    • We set the call status to “0”, “1” or “2”. “0” means that the call was connected but no choice was made, “1” means that the appointment is confirmed and “2” is that it is cancelled
    • We generate some UserEvents in order to populate the outbound (that is, coming from outbound) attribute APPT with the patient’s choice.

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

    • If the call is unanswered, busy or in error, we retry every 300 seconds for up to five times.
    • If the call times out because of a forced closure, we retry after 120 seconds.
    • If the call completes naturally but its extended status is 0 (no choice), we retry it for up to three times after 300 seconds each.
    • If a call completes naturally but its extended status is not 0, then it is not retried.

    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:

    curl "http://server:8088/wombat/api/calls/index.jsp?
     op=addcall&campaign=AppRemiders&number=45678
     &attrs=HH:12,MM:15"
    

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

    curl "http://server:8088/wombat/api/calls/index.jsp?
     op=addcall&campaign=AppRemiders&number=45678
     &attrs=HH:12,MM:15
     &schedule=2012-06-01.10:00:00"
    

    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:

    <?
    $out = "";
    foreach($_POST as $name => $value) {
       $out .= "$name:$value ";
    }
    print($out);
    error_log("RQ: $out",0, "", "");
    ?>
    

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

    RQ: num:5551234 reschedule:0 I_MM:30 extstate: 
         state:RS_REJECTED I_HH:10 retry:0
    RQ: num:5556785 reschedule:0 I_MM:00 extstate: 
         state:RS_REJECTED I_HH:11 retry:0
    RQ: num:5552012 reschedule:0 I_MM:30 extstate: 
         state:RS_REJECTED I_HH:11 retry:0
    RQ: num:5551234 reschedule:0 I_MM:30 extstate:1 
         state:TERMINATED I_HH:10 O_APPT:APPE retry:0
    RQ: num:5556785 reschedule:300 I_MM:00 extstate: 
         state:RS_NOANSWER I_HH:11 retry:0
    RQ: num:5552012 reschedule:0 I_MM:30 extstate:2 
         state:TERMINATED I_HH:11 O_APPT:PSYC retry:0
    RQ: num:5556785 reschedule:300 I_MM:00 extstate:0 
         state:TERMINATED I_HH:11 retry:1
    RQ: num:5556785 reschedule:300 I_MM:00 extstate:0 
         state:TERMINATED I_HH:11 retry:2
    RQ: num:5556785 reschedule:300 I_MM:00 extstate:0 
         state:TERMINATED I_HH:11 retry:3
    RQ: num:5556785 reschedule:0 I_MM:00 extstate:0 
         state:TERMINATED I_HH:11 retry:4
    

    You see that for each call:

    • num is set to the number dialed
    • state is the call state at its completion
    • extstate is the call’s extended state, if present
    • retry is the retry counter
    • reschedule is set to the time to be waited before a reschedule; if no reschedule is necessary, it will be set to zero
    • all inbound attributes (the ones you set with the telephone number) are passed along prepended by I_
    • all outbound attributes (the ones you read from the callee), if any, are passed along prepended by O_

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

    Further developments

    • By connecting multiple trunks and end-points residing on multiple servers you can scale this example up to hundreds of parallel lines
    • If you have clients living in different time zones, you could have multiple campaigns active with different time windows to place calls
    • It is often a good idea to set call attributes that are not actually used by Asterisk (e.g. a patient ID) but make life easier for third-party systems to find out what the call was about.

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

     
  6. Tutorial: A social media dialer

    As we are getting started with WombatDialer, we present an initial fictional scenario that shows a number of interesting features.

    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:

    • The message will be customized with a number of parameters, so that each client receives a personalized version and not just a pre-recorded note
    • The dialer starts calling on-demand when something happens and handles reschedules internally

    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:

    [telecast]
    exten => 100,1,Wait(1)
    exten => 100,2,Answer
    exten => 100,n,Playback(hello-world)
    exten => 100,n,Playback(agent-loginok)
    exten => 100,n,SayDigits(${user})
    exten => 100,n,Playback(vm-youhave)
    exten => 100,n,SayDigits(${friends})
    exten => 100,n,Playback(vm-Friends)
    exten => 100,n,Playback(vm-goodbye)
    exten => 100,n,Hangup
    

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

    [dialout]
    exten => _X.,1,Dial(SIP/500)
    exten => _X.,n,Hangup
    

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

    • AS is our Asterisk server
    • We create a trunk called “Out” on server AS that points to our telephone. We enter Local/${num}@dialout as its dial string and set its capacity to 1 (so we never receive more than one call)
    • We create an end-point called “Msg” on our server AS with extension 100@telecast and a capacity that is enough for the campaign – let’s say 10 lines.

    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:

    0916300000,user:10,friends:100
    

    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:

    • We set its name as “Runme” – avoid long names or spaces if you plan to control it externally
    • We set its priority to 10 – the priority is the order in which campaigns are queued when trying to assign free lines. A campaign with a lower number will run first, while campaigns with the same priority will have a fair share each.
    • We set “Idle on termination?” to Yes – this way this campaign will not just stop when it is out of numbers but will wait for more.
    • We set “Additional logging” to “QM compatible” so that you can use a famously reliable call-center monitoring tool to keep track of it.

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

    • Trunks: Out
    • Endpoints: Msg
    • Lists:Test

    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:

    • make sure that the WombatDialer engine is turned on (from the Home Page, click on the “Play” icon)
    • go to the “View Live” page and select our campaign “Runme” under “Available campaigns”
    • click on “Start”

    If all goes well, within a few seconds you shoul 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:

    curl "http://server:8080/wombat/api/calls/index.jsp?
    op=addcall&campaign=Runme
    &number=0916309765&attrs=user:107,friends:123"
    

    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:

    • You can temporarily pause it
    • You can remove it from running campaigns when it is paused

    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 could create your own audio recordings - the example here was created with sounds present in a standard Asterisk distribution, but of course you should record your own messages.
    • You can do even better and embed a Text-to-Speech engine script, so you are not limited to inserting numbers but can play back nearly anything
    • You can add an IVR option to the “telecast” context, so that if the callee wants to talk to a live person, they are sent to a queue. By monitoring the number of lines that you are using on your trunk and the number of available agents, the WombatDialer acts as a simple progressive dialer.
    • As all the configuration is GUI-agnostic, you can use your favourite Asterisk configuration GUI to create End-points – play messages, read IVRs, add time-dependent rules like you would for incoming calls. All you need to know is the point in the dial-plan that they start from - e.g. internal number 123 in FreePBX is always available as 123@from-internal.
    • You can optionally add an Active Period to the running campaign, so that calls on it are placed only – say – between 9 AM and 6 PM no matter when the messages are queued.

    Links

    A number of Asterisk Text-to-Speech solutions are available, see e.g.

     
  7. A first preview version of the Wombat Dialer is available for download - see http://www.wombatdialer.com/installation.jsp

    After you install, you need to define a few things to have it run:

    • A trunk, that is a set of outbound channels. This can be shared with other users on your PBX, so it basically tells Wombat to use no more than the chosen number of channels - e.g you could have an outbound trunk called DAHDI/g2/${num} and you tell Wombat to use no more than 10 channels out of it.

    • An end-point, that is a point in your dial-plan that has to be called when the call connects on the trunk. You could have Asterisk play back a message, run an IVR, enter a queue - you choose. For example, if you run FreePBX and want the calls to connect to the same point you’d get by dialling 1234, you would set this as 1234@from-internal. Here you have to define again the maximum channels to use - for a start, make it as large as the trunk.

    • A list of numbers to be dialled. They can optionally have parameters that are passed to Asterisk dialplan, so to you have an automated message that plays “Your invoice # 1234 is past due” , you would make your extension play "Your invoice number", then synthesize the content of variable INVOCE_NUMBER, then play "is past due".

    Given these rules, it is possible to start experimenting with the Wombat. Good luck!