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 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.
• Audio 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: 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: the ring timeout (in seconds) for each call
• Require 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.
• Require listing 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.
• List of 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.

In questo pannello (a cui si accede cliccando sull’icona della lente di ingrandimento) viene visualizzato anche l’elenco dei destinatari e per ciascuno di essi lo stato corrente: ultima volta che è stato chiamato, esito, numero di tentativi di chiamata, timestamp di ultima risposta e di ascolto, l’elenco dei tentativi di chiamata con i relativi eventi e timestamp. All’interno di questo pannello è possibile per l’utente comandare azioni relative alla campagna (sospendi e termina) e al destinatario (interrompi tentativi di chiamata, assegna ulteriori N tentativi, …).

Nel pannello sono visibili i cambi di stato di un destinatario, che sono pilotati dall’avvio e termine delle chiamate dirette ad esso, e possono causare il cambio di stato della campagna a cui appartengono:

• Idle: inattivo, disponibile ad essere chiamato (se la campagna si trova in stato “Attiva”)
• Attivo: è in corso una chiamata
• Contattato: è stato contattato con successo e sono state date le conferme richieste (risposta e ascolto, se previste)
• Fallito: è stato fatto un numero di tentativi di chiamata pari al massimo previsto, senza che sia stato contattato con successo. Da questo stato l’utente può assegnare altri tentativi di chiamata a quel destinatario, che torna quindi nuovamente nello stato “Idle”

Logica di scheduling delle chiamate

La logica con cui il sistema decide l’esecuzione di una nuova chiamata verso un destinatario appartenente ad una certa campagna dipende da numerosi parametri:

• Contemporaneità massima delle campagne
• Contemporaneità massima delle chiamate complessive (totali/interne/esterne)
• Contemporaneità massima delle chiamate per campagna (totali/interne/esterne)
• Priorità delle campagne
• Timestamp di avvio di ciascuna campagna
• Timestamp dell’ultimo tentativo di chiamata verso ciascun destinatario (con esito negativo)

Le campagne attive ad un dato momento vengono ordinate in base alla priorità, ed in caso di parità viene data precedenza alla campagna con timestamp di avvio precedente.
Partendo dalla campagna a massima priorità, il sistema genera tante chiamate fino al raggiungimento delle contemporaneità massime (della campagna e complessive). Vengono chiamati per primi i destinatari che non sono stati chiamati in precedenza, secondo l’ordine con cui sono elencati nella configurazione della campagna. Nel caso in cui cia raggiunto un limite di contemporaneità, ad esempio per le interne, il sistema continuerà a selezionare destinatari da quella campagna, scegliendolo solo da quelli esterni. Quando si esauriscono i destinatari che non sono mai stati chiamati, se c’è ancora posto per ulteriori chiamate per quella stessa campagna, il sistema passa a richiamare i destinatari già chiamati in precedenza, partendo da quelli che sono stati chiamati più lontano nel tempo. Nel momento in cui non sia possibile selezionare un nuovo destinatario da questa campagna lo scheduler ripete la valutazione sulla seconda campagna (per priorità/tempo di avvio), e così via fino al raggiungimento dei limiti complessivi di chiamata o all’esaurimento di destinatari disponibili.
Ogni volta che una chiamata termina, oppure ogni volta che viene avviata una nuova campagna, oppure quando vengono modificati i limiti globali del servizio, viene eseguito di nuovo l’algoritmo di scheduling per determinare se è possibile effettuare una o più nuove chiamate.