AdminGuide:Service:CallCampaign/en

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.

La prima operazione da fare per attivare una Campagna è quindi creare un Modello, dal pannello “Lista Modelli”, cliccando sull’azione “Aggiungi nuovo modello di campagna”.
Il pannello di creazione (o modifica) di un Modello di Campagna permette la configurazione dei seguenti parametri:

• Abilitato: check-box che indica se il Modello è abilitato. Se un Modello è disabilitato non possono essere avviate o pianificate Campagne che lo utilizzano
• Nome: nome della Campagna. Ammette caratteri alfanumerici, spazi, trattini, underscore. Questo attributo viene utilizzato come Display-Name per le chiamate effettuate dalla Campagna verso i destinatari
• Numero chiamante: è il numero chiamante utilizzato dal sistema per effettuare le chiamate della campagna. Viene utilizzato sia per le chiamate ad altri interni che per le chiamate a numeri esterni. Nel caso di chiamate esterne il numero chiamante effettivo sarà derivato da questo in base alle regole di manipolazione configurate per la linea di uscita che sarà impegnata.
• Classe di instradamento in uscita: determina l’instradamento delle chiamate verso i destinatari esterni. Nel caso in cui la classe non permetta di chiamare uno o più dei destinatari configurati, le relative chiamate falliranno ma non viene effettuato un controllo preventivo.
• Priorità: questo valore viene utilizzato dallo scheduler di generazione delle chiamate nel momento in cui si libera lo spazio per una nuova chiamata se sono presenti 2 o più campagne attive.
• File audio: selezione del file audio da riprodurre a ciascun destinatario.
• Soglia di completamento: questo parametro indica il numero di destinatari che è sufficiente contattare con successo per considerare la campagna completa.
• Numero di tentativi di chiamata: questo parametro indica il numero massimo di tentativi di chiamata (senza successo) che possono essere effettuati verso il destinatario. Al raggiungimento di tale numero di chiamate senza che il destinatario abbia risposto e dato conferma (di risposta o ascolto, se richieste), il sistema non effettuerà più nuovi tentativi di chiamata verso questo destinatario, che risulterà quindi “non contattato” in modo definitivo. È facoltà dell’utente che gestisce la campagna di poter aggiungere nuovi tentativi di chiamata verso quei destinatari per i quali sia stato esaurito questo limite.
  Questo valore non può essere illimitato (default 5).
• Timeout per chiamata: il timeout di squillo (in secondi) per ciascuna chiamata effettuata dalla campagna
• Richiedi conferma di risposta: questa check-box indica se il sistema deve richiedere al destinatario la digitazione del tasto 1 per confermare che abbia effettivamente risposto, prima di effettuare la riproduzione del messaggio. Questa impostazione vale sia per i destinatari interni che esterni, ed assicura che la chiamata non sia andata ad un risponditore o casella vocale.
• Richiesta conferma ascolto: questa check-box indica se il sistema deve richiedere al destinatario la digitazione del tasto 9 al termine dell’ascolto del messaggio, a conferma dell’effettivo ascolto e comprensione di questo. La mancata conferma o la pressione di un tasto diverso da quello indicato causa la ripetizione del messaggio. Se la chiamata viene abbattuta senza conferma di ascolto, il sistema considererà il destinatario come “non contattato”, e se il destinatario ha ancora tentativi residui (perché non ha raggiunto il numero massimo di tentativi di chiamata configurati per la campagna) potrà essere nuovamente chiamato in seguito, in base alle politiche di scheduling del servizio.
• Contemporaneità massima chiamate interne/esterne/totali: questi 3 valori determinano il numero massimo di chiamate che questa campagna può effettuare complessivamente, verso destinatari interni e verso destinatari esterni. Un valore “null” indica nessun limite. La somma dei limiti impostati per le interne e le esterne può eccedere il limite totale, ma comunque il numero di chiamate effettivamente in esecuzione non lo potrà superare.
• Elenco destinatari: questo elenco viene popolato con destinatari interni o esterni. Nel caso di contatti inseriti manualmente, oltre al numero si possono specificare un nome ed un indirizzo mail (per l’invio del messaggio). L’elenco è ordinabile; lo scheduler delle chiamate utilizzerà tale ordinamento in fase di selezione della prossima chiamata da effettuare, a parità degli altri parametri.

Una volta creato il modello questo apparirà nel pannello “Lista Modelli”, da cui l’utente abilitato può effettuare le seguenti operazioni:

• Creare un numero arbitrario di Modelli di Campagne
• Cancellare uno o più Modelli di Campagna esistenti selezionando l’icona Cestino.
  Nel caso di un Modello da cui siano state avviate o programmate una o più Campagne, la cancellazione è permessa, in quanto tutti i parametri necessari all’esecuzione della campagna di avviso sono stati già copiati dal modello nella configurazione operativa di quella campagna. All’utente viene comunque indicata l’esistenza di campagne in corso o schedulate associate a tale Modello, mediante pop-up di conferma cancellazione.
• Clonare un Modello esistente per crearne una nuova, che ne eredita le impostazioni
• Modificare la configurazione di un Modello di Campagna precedentemente creata; nel caso di una Campagna per la quale esistano una o più istanze in esecuzione o schedulata, la modifica è comunque permessa a seguito dell’indicazione mediante il pop-up di conferma.
• Visualizzare la lista dei destinatari della Campagna.

Avvio e gestione di una campagna di avviso

Dopo aver configurato un modello di campagna di avviso, l’utente può comandare l’avvio di una campagna, immediato o differito nel tempo.
La creazione della Campagna si effettua cliccando sull’icona “Avvia” nella colonna “Azioni” della Lista Modelli. Viene aperto un pannello intermedio “Avvio nuova campagna di avviso” in cui è possibile assegnare un nome alla specifica campagna, effettuare l’eventuale modifica (rispetto al modello di origine) del file audio da riprodurre e dell’elenco dei destinatari.
Infine, è possibile definire la programmazione della campagna secondo tre modalità:

• Immediata: la campagna viene avviata immediatamente alla pressione del pulsante “Avvia”
• Ritardata: selezionando il tempo (in minuti) dopo il quale la campagna viene avviata
• Orario programmato: specificando una data ed ora a cui la campagna verrà avviata

Alla conferma, selezionando premendo sul tasto “Avvia”, la nuova campagna (avviata o programmata) compare nel pannello “Lista Campagne”.

Questo pannello costituisce un registro delle campagne passate ed anche di quelle correnti, tramite il quale è possibile visualizzare lo stato istantaneo della campagna, il grado di avanzamento delle chiamate, oltre ad alcuni parametri di configurazione. La vista delle campagne mostra le seguenti informazioni:

• Come parametri di configurazione sono mostrati: Nome, Modello, numero chiamante, priorità, timeout di squillo, tentativi massimi per destinatario, valore della soglia di completamento, richiesta di risposta e conferma di ascolto, contemporaneità.
• Programmazione Avvio: l’ora prevista di inizio della campagna
• Destinatari totali: il numero totale dei destinatari della campagna
• Destinatari contattati con successo: Destinatari che hanno risposto alla campagna secondo le impostazioni della campagna stessa
• Chiamate in corso: numero delle chiamate attualmente in corso per quella campagna
• Stato: indica lo stato in cui si trova la campagna e può essere uno dei seguenti:
  • Programmata: al momento dell’attivazione. Da questo stato passa nello stato “In esecuzione” in caso di avvio immediato, o al momento previsto dalla schedulazione se avviata in modalità differita
  • In esecuzione (o Attiva): quando vengono eseguite le chiamate verso i destinatari di questa campagna.
  • Sospesa: attivabile dall’utente premendo il pulsante “Sospendi”. In questo stato non vengono generate nuove chiamate per i destinatari appartenenti a questa campagna; le chiamate in corso non vengono interrotte.
  • Bloccata: quando si eccede il grado di parallelismo previsto per le campagne
  • Incompleta: quando sono state eseguite tutte le chiamate possibili verso i destinatari ma almeno uno di questi non è stato contattato con successo.
    Nel caso in cui un destinatario passi dallo stato “Fallito” allo stato “Idle” (perché un utente gli ha assegnato nuovi tentativi di chiamata) allora la campagna torna in stato “Attiva” assegnando nuovi tentativi di chiamata per uno o più destinatari.
    In alternativa l’utente può chiuderla definitivamente portandola nello stato “Terminata” cliccando sull’icona “STOP”
  • Terminata: quando la campagna è finita, anche con alcuni destinatari non contattati in via definitiva, e non possono essere più eseguite chiamate verso i suoi destinatari. L’utente, per una campagna Incompleta, può mettere la campagna in questo stato usando il tasto corrispondente.
  • Completata: Si arriva in questo stato in modo automatico, nel momento in cui tutti i destinatari della campagna siano stati contattati con successo

Oltre a questo pannello di summary delle campagne presente un “Pannello di stato della campagna” che raccoglie tutte le informazioni relative allo stato ed allo storico della campagna.

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.