AdminGuide:Service:CallCampaign

Return to AdminGuide:Service

N.B: This service is available for firmware version 4.9.4 or later.

Call campaign service

KalliopePBX's "Call Campaign" service lets you execute a session of automated calls towards a group of recipients, playing an audio message and gathers confirmation that each recipient has listened to the call.

On a general level, this service lets you configure call campaigns through a web panel, each with the following settings:

• list of participants (internal and external)
• audio message
• maximum number of simultaneous external calls
• whether or not to collect confirmations
• number of call attempts for each recipient

A user with the required permissions can start (instantaneously or with a delay), suspend, or stop a call campaign, or view its status.

A campaign will end the moment, for each configured recipient:

• the recipient answers the call and, if required, provides confirmation that they have answered and/or listened to the message (this is the "success" condition);
• the number of call attempts for the recipient has been reached without satisfying the previous condition.

In the case that all recipients have been successfully reached (or the minimum number set for that specific campaign), the status of the campaign will be set to "completed"; otherwise, once the maximum number of call attempts have been reached for all recipients, it will be set to "incomplete". In the latter case, the user may assign further call attempts for one or more of the recipients that have not been successfully reached, or mark the campaign as permanently closed, setting its status to "terminated".

The web panel allows the user to manage individual campaigns in real time (with the ability to view the status for each recipient) as well as access a log with the details of concluded campaigns: this log displays the events and parameters relative to the execution of the campaign and all, so that they can be consulted even if the settings have been changed or the campaign has been deleted.

Configuration

The call campaign services can be configured on the "PBX Applications" -> "Call Campaign" panel. Users may view the panel and its tabs if their role has the required permissions.

The call campaign panel has three tabs:

• Models list and Campaigns list (associated to the "Call Campaign Management" permission);
• General settings (associated to the "Call Campaign general settings management" permissions)

In the "General settings"' users you can configure the global limits of the service, i.e. the maximum number of simultaneous active campaigns and the maximum number of simultaneous calls (internal, external, or overall) between all active campaigns. the parameters that can be set are:

• Maximum number of simultaneous active campaigns: the maximum number of campaigns that can set as "active" at the same time.
  

This parallelism concerns the effective execution of the calls, so for instance so with a parallelism of 1 a campaign can be started even if another one is already being executed. The campaigns will be ordered according to their "priority" attribute, and if two campaigns are started at the same moment, the system will make the calls for the campaign with the highest priority (within the simultaneity constraints set both generally and for that campaign).
The empty value means unlimited.

• Maximum number of simultaneous calls (total/internal/external): these three values determine the maximum number of calls that the system can make among all active campaigns.
  

The empty value means unlimited.
N.B.: The sum of the values set for internal and external calls may exceed the total limit, but in this case the effective number of overall calls cannot exceed it (e.g. with the values 10/8/6, there can be at most 8 internal calls, 6 external calls, but no more than 10 calls in total; if at one moment 7 internal calls are active, only 3 external one can be made)

Every time a call is terminated, whether successfully or not, or when a new campaign is started, the call scheduler (which determines whether or not a new call may be made and towards which recipient among all those for all campaigns) operates according to the current limits.

To start a campaign, you must first set a Campaign model with the parameters that determine the behavior of the active campaigns and then start a campaign from that model (or set it to start at a later time). Multiple campaign may be started from the same model at different times, changing a subset of settings such as the audio file to be played or the list of recipients.

Models can be created from the "Models list" panel by clicking on "Add a new campaign model".

The panel for creating a new model or editing an existing one contains the following parameters:

• Enabled: this checkbox determines whether the model is enabled or disabled. If a model is disabled new campaigns may not be started or scheduled from it.
• Name: the name of the campaign. Can contain alphanumeric characters, spaces, dashes, and underscores. This attribute is used as the Display-Name for calls made by the campaign.
• Caller number: the number used by the system to make the calls (both internal and external). For external calls, the effective caller number will be derived from this attribute based on the manipulation rules of the outbound line used.
• Outbound Call Routing class: determines the routing of external calls. If the class does not allow one or more of the configured recipients, those calls will fail; no preemptive checks will be made.
• Priority: the value used by the scheduler to make the calls if more than one campaign is active at the same time.
• Sound file: the audio file played to each recipient.
• Completion threshold: the number of recipients that must be successfully reached in order to to consider the campaign complete.
• Number of call attempts per recipient: the maximum number of unsuccessful call attempts that will be made towards each recipient. Once this number has been reached for a recipient, the system will not make any new attempts and the recipient will be definitively considered "not reached". The user that manages the campaign may add new call attempts.
  

This value cannot be unlimited (default 5).

• Call timeout (seconds): the ring timeout (in seconds) for each call
• Request answer confirmation: this checkbox determines whether or not the system must require the recipient to dial 1 to confirm that they have actually answered before playing the message. This applies to both internal and external calls and ensures that the call was not sent to an answering machine or a voicemail box.
• Request listening confirmation: this checkbox determines whether or not the system must require the recipient to dial 9 after the message has been played to confirm that they have actually listened and understood it. If 9 is not dialed, or if another button is dialed, the message will be repeated. If the call ends before confirmation is given, the system will consider the recipient to be "not reached", and if call attempts are still available a new one may be made depending on the policies of the scheduler.
• Maximum number of simultaneous total/internal/external calls: these three values determine the maximum number of calls that the campaign cam make. The empty value means unlimited. The sum of the values set for internal and external calls may exceed the total limit, but in this case the effective number of overall calls cannot exceed it.
• Recipients: the list of internal or external recipients. For contacts inserted manually, the user can specify a name and an email address along with the number. The list can be ordered; the scheduler will make calls according to the order if other parameters are equal.

Once the model has been created, it will appear in the "models list", from which an enabled user can:

• Create any number of models.
• Delete one or more existing models by clicking on the thrash icon.

Models from which one or more campaigns have been started or scheduled can be deleted, as the necessary parameters have already been copied to the campaign configuration. The user will still be alerted of the presence of such campaigns through a confirmation popup.

• Clone an existing model to create a new one with inherited settings.
• Edit the configuration of an existing model; models from which one or more campaigns have been started or scheduled can be edited after clicking a confirmation popup.
• View the list of recipients of the campaign.

Starting and managing a call campaign

After configuring a call campaign model, you can start a new campaign, immediately or with a delay.

You can create a campaign by clicking on the "Start" icon in the "Actions" column of the Models List. A new panel will open in which you can set the name of the campaign and change the audio file or the list of recipients if necessary.

Finally, you can configure the start of the campaign in three modes:

• Immediate: the campaign will start immediately after you press "start";
• Delayed: select the delay (in minutes) after which the campaign will start;
• Set schedule: specify the time and date on which the campaign will start.

After clicking the "Start" button, the new campaign will appear in the "Campaigns list" panel.

This panel is a log of past and current campaigns through which you can view the details of the campaigns:

• The following configuration parameters: Name, Model, caller number, priority, ring timeout, maximum call attempts per recipient, completion threshold, answer and listing confirmation, simultaneity.
• Start time.
• Total number of recipients.
• Successfully reached recipients: the recipients that have been reached by the campaign according to its settings.
• Current calls: the number of calls that are currently active.
• Status: the status of the campaign, which can be one of the following:
  • Scheduled: at the time of activation. The status will change to "Active" if the starting mode is immediate, or at the moment set in the configuration if the starting mode is immediate is delayed.
  • Active: calls towards the recipients are currently being made.
  • Paused: can be activated by the user by clicking the "Pause" button. New calls will not be made; current calls will not be interrupted.
  • Blocked: the number of simultaneous calls has been reached.
  • Incomplete: all possible calls towards the recipients have been made but at least one has not been successfully reached.
    

If the status of a recipient changes to "Failed" to "Idle" (because the user added new call attempts)the the campaign will switch to "Active" mode again.
Alternatively, the user can permanently close the campaign by clicking the "STOP" icon.

• • Terminated: the campaign has ended even if some recipients have not been successfully reached. If a campaign is "Incomplete", the user can switch it to this status.
  • Completed: this status is automatically reached the moment all recipients have been successfully reached.

There is also a "Campaign status" panel that displays all the data regarding the status and history of a campaign.

This panel, which can be accessed by clicking the magnifying glass icon, displays the list of recipients and the current status for each: time of last call, outcome, number of call attempts, timestamp of last answer or listening confirmation, list of call attempts and corresponding events and timestamps. Within this panel you can execute actions regarding the campaign (pause and terminate) and the recipients (stop call attempts, add more call attempts, etc.).

The panel shows the state changes of a recipient, which are driven by the initiation and termination of calls directed to it, and can cause the state of the campaign to which they belong to change:

• Idle: inactive, available to be called (if the campaign is in Active state).
• Active: a call is in progress
• Contacted: has been successfully contacted, and required acknowledgments have been given (answered and listened to, if provided)
• Failed: several call attempts equal to the maximum expected number have been made, without being successfully contacted. From this state, the user can assign further call attempts to that recipient, which then returns to the "Idle" state again

Call scheduling logic

The logic by which the system decides on the execution of a new call to a recipient belonging to a certain campaign depends on several parameters:

• Maximum simultaneity of campaigns
• Maximum simultaneity of total calls (total/internal/external)
• Maximum simultaneity of calls per campaign (total/internal/external)
• Priority of campaigns
• Start timestamp of each campaign
• Timestamp of last call attempt to each recipient (unsuccessful)

Campaigns active at a given time are sorted by priority, and in case of a tie, precedence is given to the campaign with an earlier start timestamp.
Starting with the highest priority campaign, the system generates as many calls until the maximum simultaneities (of the campaign and overall) are reached. Recipients who have not been called previously are called first, according to the order in which they are listed in the campaign configuration. If a concurrent limit has been reached, such as for internal, the system will continue to select recipients from that campaign, choosing only from external ones. When you run out of recipients, who have never been called, if there is still room for more calls for that same campaign, the system will switch to calling back previously called recipients, starting with those who have been called furthest back in time. When a new recipient cannot be selected from this campaign, the scheduler repeats the evaluation on the second campaign (by priority/start time), until the overall call limits are reached, or the available recipients are exhausted. Each time a call ends, a new campaign is started, or when global service limits are changed, the scheduling algorithm is run again to determine whether one or more new calls can be made.