Connettori

I connettori sono i vari elementi che costituisco il flusso logico e di processo delle richieste degli utenti e vengono elencati nella colonna di destra della sezione Process Flows, raggruppati per tematica.

Selezionando un connettore dalla lista viene visualizzata la relativa configurazione. Al salvataggio di tale configurazione, il connettore aggiunto all’area di lavoro. Posizionando il mouse sul connettore appena inserito e selezionando le relative icone è possibile:

• Modificarne il comportamento variando i parametri di configurazione
• Eliminare il connettore
• Sposare il connettore in una posizione differente dell’area di lavoro (compatibilmente con le relazioni che intercorrono tra di essi).

Molti connettori possono sfruttare alcuni valori variabili estratti dalla sessione conversazionale, i quali permettono una configurazione più flessibile dei connettori stessi. Per approfondire fare riferimento alla sezione Variabili connettori.

Action mapping

Il connettore Action mapping consente di gestire diverse tipologie di azioni direttamente con i connettori presenti in Tellya. Inserito il connettore all’interno della propria journey è possibile creare nuove azioni e percorsi dedicati. Queste azioni quindi possono essere affiancati a diversi intenti o elementi in Dialogflow.

La configurazione avviene in una pagina che va a sovrapporsi al Process flow, così da avere tutto lo spazio necessario per personalizzare il proprio percorso. Al suo interno è possibile inserire un set ristretto di connettori specifici, configurabili in modale come per il Process flow.

Per navigare tra le azioni della journey è possibile selezionarne una dall’apposita select o cercarlo cliccando sulla voce “Search action”, verrà fornita una lista aggiornata in base all’input dell’utente.

Questo connettore non è disponibile per le journey di tipo dispatcher

Per creare un’azione è necessario specificare diversi dati in base al motore di NLU utilizzato:

Dialogflow ES

1. Inserire il connettore all’interno del Process Flow
2. Cliccare sui “setting” del connettore, si aprirà una nuova schermata da cui è possibile, in alto a destra, cliccare sul bottone “+ New”.
3. Verrà mostrata una modale nella quale è possibile inserire il solo nome della action, esso deve essere uguale alla action preimpostata su Dialogflow ES nella sezione “Action and parameters”

Cliccare su “Save” per confermare la creazione, verrà aperto un nuovo spazio di lavoro in cui cominciare la personalizzazione della azione.

Dialogflow CX

Fulfilment

1. Inserire il connettore all’interno del Process Flow
2. Cliccare sui “setting” del connettore, si aprirà una nuova schermata da cui è possibile, in alto a destra, cliccare su pulsante “+ New”
3. Verrà mostrata una modale nella quale è possibile inserire il solo nome della action, esso deve essere uguale al tag preimpostato su Dialogflow nella sezione relativa ai Webhook.

Cliccare su “Save” per confermare la creazione, verrà aperto un nuovo spazio di lavoro in cui cominciare la personalizzazione della azione.

No Fulfillment

1. Inserire il connettore all’interno del Process Flow
2. Cliccare sui “setting” del connettore, si aprirà una nuova schermata da cui è possibile, in alto a destra, cliccare su bottone “+ New”.
3. Verrà mostrata una modale nella quale è possibile inserire:

• “Action name”: Nome associato alla nuova azione creata
• “Mapping”: Tabella in cui sarà possibile inserire il percorso dal quale l’azione sarà attivata, quindi è possibile selezionare 3 livelli di percorso:
  • Flow: selezionare il flusso
  • Page: selezionare la pagina (l’elenco va in base al flusso selezionato)
  • (optional): selezionare la route / intento (l’elenco va in base al flusso selezionato)

• “Priority”: Un percorso mappato può essere collegato a diverse azioni, quindi è necessario definire un ordine di esecuzione. Una volta cliccato sul campo di input sarà possibile visualizzare un elenco popup che mostra tutte le azioni già inserite per quel percorso con relativo valore di priorità affianco (PRI).
  E’ possibile inserire un numero di priorità uguale ad un’altra azione già esistente, in questo caso verranno svolte in ordine di inserimento con la stessa priorità rispetto ai livelli inferiori.

Cliccare su “Save” per confermare la creazione, verrà aperto un nuovo spazio di lavoro in cui cominciare la personalizzazione della azione.

Non tutti i connettori presenti in catalogo possono essere utilizzati nel connettore Action mapping

Code Editor

Con questo connettore è possibile inserire codice e collegarlo ad altri componenti per creare journey più complesse, aggiungendo nuovi livelli di logica.

Si possono scegliere due possibili linguaggi:

• Javascript
• Groovy

Per permettere all’utente di scrivere codice all’interno del componente in maniera agevolata è integrato all’interno della modale un code editor che offre syntax highlighting per entrambi i linguaggi aiutando l’utente ad individuare possibili errori durante la scrittura.

Per Javascript inoltre sono integrate le funzionalità di autocompletamento e analisi statica del codice mostrando warning ed errori all’utente.

L’utente non può effettuare operazioni da Amministratore, per questo utilizzando sia Groovy che Javascript esiste una “blacklist” che permette di evitare l’utilizzo di alcune classi.

E’ possibile personalizzare la visualizzazione del codice in base alle proprie esigenze utilizzando due selettori:

• Font size : ci sono 3 grandezze selezionabili (12px, 16px, 20px)
• Tema : per migliorare l’esperienza di scrittura sono selezionabili due differenti temi
  • Dark
  • Light

[INFO BOX] Le impostazioni selezionate saranno resettate al salvataggio / chiusura della modale laterale. 

All’interno dell’editor si avrà a disposizione delle parole chiavi che permettono di interagire con il prodotto Tellya:

• cache : servizio che espone due metodi per salvare e leggere degli oggetti in cache
  • cache.get(Key) → Recupera l’oggetto nella cache associato alla chiave <key> 
  • cache.put(key,object) → crea/aggiorna il valore associato alla chiave <key> con il valore object

• nluResult : contiene la risposta alla interazione con il motore NLU in uso.

I valori che possono essere reperiti sono quelli presenti all’interno della risposta JSON

Dialogflow ES

{  
    "idMessage": "94eb8048-1a12-4dbb-b08a-af0c93ccc9f0",
    "lang": "it",
    "id": "2a73d178-d728-410f-91b2-6d5858cfb105-53cb9be6",
    "timestamp": "2022-03-04T10:40:17Z",
    "sessionId": "1646390416431693FC151982",
    "result": {      
        "resolvedQuery": "Welcome",
        "action": "exampleAction",
        "score": 1,
        "parameters": {
            "exampleParameter": "name"
        },
        "contexts": [
            {
                "lifespan": 0,
                "name": "context-name-1",
                "parameters": {
                    "context-parameter-name-1": "context-parameter-value-1"
                }
            }
        ],
        "metadata": {
            "isFallbackIntent": "false",
            "intentId": "projects/example/agent/intents/
a5ef0e37-ff1e-45c4-bbba-8a297c79a28b",
            "intentName": "Default Welcome Intent",
            "flow": null,
            "landedPage": null,
            "transitionPage": null,
            "transitionRoute": null,
            "event": null,
            "webhookTag": null,
            "webhookUsed": "false",
            "webhookForSlotFillingUsed": "false",
            "allRequiredParamsPresent": true,
            "endOfConversation": false
        },
        "fulfillment": {
            "audioOutput": null,
            "messages": [
                {
                    "speech": null,
                    "text": "Ciao sono il tuo assistente!", 
                    "platform": "PLATFORM_UNSPECIFIED",  
                    "order": 0,  
                    "iterable": null,
                    "payload": null
                }  
            ] 
        }
    }    
}

Dialogflow CX

{  
    "idMessage": "94eb8048-1a12-4dbb-b08a-af0c93ccc9f0",
    "lang": "it",
    "id": "2a73d178-d728-410f-91b2-6d5858cfb105-53cb9be6",
    "timestamp": "2022-03-04T10:40:17Z",
    "sessionId": "1646390416431693FC151982",
    "result": {      
        "resolvedQuery": "Welcome",
        "score": 1,
        "parameters": {
            "exampleParameter": "name"
        },
        "metadata": {
            "isFallbackIntent": "false",
            "intentId": "",
            "intentName": "",
            "flow": {
                "dfId": "00000000-0000-0000-0000-000000000000",
                "name": "Default Start Flow",
            }
            "landedPage": {
                "dfId": "projects/example/locations/europe-west1/agents
                    /5b675207-1111-1111-1111-1746331e8d66/flows
                    /00000000-0000-0000-0000-000000000000/pages/START_PAGE",
                "name": "Start Page",
            },
            "transitionPage": [    
                {
                "dfId": "START_PAGE",
                "name": "Start Page",
                }
            ],
            "transitionRoute": [],
            "event": {
                "dfId": "11d706c6-6c47-43e0-846f-5a26fbbd2aaf",
                "name": "Welcome",
            },
            "webhookTag": null,
            "webhookUsed": null,
            "webhookForSlotFillingUsed": null,
            "allRequiredParamsPresent": "false",
            "endOfConversation": false
        },
        "fulfillment": {
            "audioOutput": null,
            "messages": [
                {
                    "speech": null,
                    "text": "Benvenuto, sono l'assistente virtuale", 
                    "platform": "PLATFORM_UNSPECIFIED",  
                    "order": 0,  
                    "iterable": null,
                    "payload": null
                }
            ]
        }
    }    
}

Facendo un esempio dalle risposte sopra riportate, per recuperare la lista dei messaggi si inserisce nell’editor nluResult.result.fulfillment.messages

Data Loss Prevention

Il connettore Data Loss Prevention sfrutta l’omonimo servizio cloud di Google e consente di rilevare ed oscurare nella conversazione dati potenzialmente sensibili. Tipicamente viene utilizzato per nascondere dati potenzialmente delicati forniti dall’utente prima di memorizzarli all’interno di database o sistemi esterni.

Quando viene inserito nella journey nasconde i dati sensibili prima di essere salvati nel database. Di conseguenza saranno nascosti anche nella history conversazionale e nel training.

La finestra di configurazione si articola in due step:

1. General setting, per configurare i parametri di base del servizio, in particolare:
   • Fields to encrypt: campi all’interno dei quali ricercare potenziali contenuti da oscurare. Sono messe a disposizione alcune variabili di sistema
   • Minimum characters: numero minimo di caratteri dopo cui effettuare l’eventuale oscuramento
   • Masking character: carattere che verrà utilizzato per sostituire il contenuto oscurato
   • Characters to skip: eventuali caratteri da non oscurare
   • Redact in Response: i campi selezionati verranno oscurati anche nella risposta restituita all’utente
2. Google infoType: è possibile selezionare quali tipologie di contenuti oscurare tra quelle che l’API di Google è in grado di riconoscere. Per ciascuna di esse è presente una descrizione di accompagnamento
3. Custom infoType: è possibile definire delle espressioni regolari custom così da poter identificare ed oscurare dei dati differenti rispetto a quelli previsti da Google. Per ciascuno di essi è possibile aggiungere una descrizione di accompagnamento oltre che la definizione del nome per identificarla

Le espressioni regolari definite non possono avere vincoli posizionali, ovvero non è possibile specificare regole per identificare un pattern all’inizio o alla fine della frase.

Data Processing

Il connettore Data Processing permette di effettuare alcune operazioni sui dati estratti dal motore di NLU durante la conversazione e salvati all’interno di parametri e/o contesti della sessione conversazionale.

In particolare è possibile eseguire due tipologie di manipolazioni:

• Remove spaces: permette di rimuove eventuali spazi presenti all’interno del valore testuale che si intende manipolare.
• Replace letters/words: permette di sostituire una o più lettere o parole presenti all’interno del valore che si intente manipolare con una nuova lettera o parola.

Dopo aver aggiunto il connettore Data Processing all’area di lavoro è necessario indicare il campo che si intende manipolare. È possibile scegliere tra:

• Parameter: quando si vuole manipolare un valore contenuto all’interno di un parametro, del quale è necessario specificare il nome (“Parameter name”).
• Parameter from context: quando si vuole manipolare un valore di un parametro salvato all’interno di un contesto. In questo caso sarà necessario specificare sia il nome del contesto (“Context name”), sia il nome del parametro (“Parameter name”).

Successivamente è possibile indicare la tipologia e l’ordine delle manipolazione da eseguire sul campo specificato precedentemente. L’aggiunta di una nuova manipolazione si effettua selezionando il pulsante “+Add manipulation”.

Ogni volta che viene premuto il pulsante viene inserita una manipolazione di tipo “Remove spaces” (la quale non richiede ulteriori configurazioni): è possibile modificarne il tipo tramite il menù a tendina.

Selezionado la manipolazione “Replace letters/words” è necessario indicare:

• Letters/words to replace: una o più lettere o parole da sostiutire (separate da una virgola).
• Replace with: la lettera o parola con cui sostituire i valori indicati nel campo precedente.

Attenzione: per utilizzare le monipolazioni effettuate dal connettore Data Processing all’interno di una risposta di un intento è che tale risposta venga definita all’interno della piattaforma Tellya e non all’interno del motore di NLU.

Data Transfer

Il connettore Data Transfer consente di utilizzare i dati recuperati da una sorgente esterna, ad esempio tramite una chiamata a servizio realizzata utilizzando il connettore REST HTTP, ed utilizzare tali valori all’interno della sessione conversazionale.

All’interno della finestra di configurazione del connettore è infatti possibile definire una o più azioni che permettono di memorizzare all’interno della sessione conversazionale i valori restituiti dal connettore posizionato precedentemente rispetto al connettore Data Transfer.

Questo connettore non è disponibile per le journey di tipo dispatcher

Per ogni azione è necessario specificare diversi dati in base al motore di NLU utilizzato:

Dialogflow ES

1. ll percorso del payload da cui estrarre il dato, utilizzando se necessario la “dot notation” per navigare all’interno del payload JSON (es. nome-connettore.0.percorso).
   • Dove consentito, è possibile utilizzare la lettura dinamica di un payload, selezionando l’opzione “Set as dynamic“.
   • Se necessario è possibile inserire anche valori di parametro, contraddistinti dall’utilizzo di doppi apici (” “). Questa opzione è utile soprattutto per l’utilizzo di parametri di default.
2. La “entità logico-conversazionale” in cui memorizzare il valore estratto dal percorso specificato precedentemente:
   • Save in Cache: memorizza il valore all’interno della cache
   • Save in Context: memorizza il valore all’interno di un parametro di contesto. Se il contesto non esiste viene creato, altrimenti il parametro viene aggiunto o sovrascritto all’interno del contesto
   • Save in Session Entity: memorizza il valore all’interno di una entità di sessione, eventualmente creandola se non presente
   • Save in Parameters: memorizza il valore come parametro estratto all’interno della sessione conversazionale
   • Clear Session Entity: Permette di resettare l’entità di sessione selezionata
3. Il nome da assegnare alla “entità logico-conversazionale” precedentemente scelta, a seconda dell’azione scelta:
   • Nel caso di “Cache” è necessario specificare il nome del parametro da salvare in memoria cache
   • Nel caso di “Save in Context” è necessario specificare il nome del contesto e del parametro all’interno del quale memorizzare il valore, rispettando il formato $sys.{contextName.parameterName}
   • Nel caso di “Session Entity” e “Clear Session Entity” è necessario specificare il nome dell’entità di sessione da popolare, selezionandola nella select
   • Nel caso di “Save in Parameters” è necessario specificare il nome del parametro da popolare

Dialogflow CX

1. Il percorso del payload da cui estrarre il dato, utilizzando se necessario la “dot notation” per navigare all’interno del payload JSON (es. nome-connettore.0.percorso)
   • Dove consentito, è possibile utilizzare la lettura dinamica di un payload, selezionando l’opzione “Set as dynamic“.
   • Se necessario è possibile inserire anche valori di parametro, contraddistinti dall’utilizzo di doppi apici (” “). Questa opzione è utile soprattutto per l’utilizzo di parametri di default.
2. La “entità logico-conversazionale” in cui memorizzare il valore estratto dal percorso specificato precedentemente:
   • Save in Cache: memorizza il valore all’interno della cache
   • Save in Session Entity : memorizza il valore all’interno di un parametro legato all’intento, sarà possibile sovrascrivere una entità già esistente o crearne una che verrà accodata alle pre-esistenti
   • Save in Parameters (solo fulfillment): memorizza il valore all’interno di un parametro legato al parametro di sessione
   • Clear Session Entity: Permette di resettare l’entità di sessione selezionata
3. Per il nome di tutti i percorsi disponibili è necessario specificare il nome del parametro da popolare:
   • Nel caso di “Cache” è necessario specificare il nome del parametro da salvare in memoria cache
   • Nel caso di “Session Entity” è necessario specificare il nome dell’entità di sessione da popolare
   • Nel caso di “Save in Parameters” è necessario specificare il nome del parametro da popolare

Per entrambe le tipologie di NLU:

• Nel caso si vogliano trasferire tutte le chiavi del percorso specificato, sarà possibile utilizzare l’apposito selettore. Attivando tale opzione, campo “Save in field…”, verrà disabilitato.
• Nel caso si selezionasse l’opzione “Save in Session entity”, l’input testuale verrà sostituito da una un elenco contenente tutte le entità di sessione disponibili. In aggiunta sarà possibile, tramite selezione, definire se l’entità scelta dovrà essere sovrascritta (flag) o semplicemente aggiunta a quelle già esistenti (no flag).

Utilizzo output connettori

Per accedere al contenuto e alle informazioni precedentemente generate da alcuni connettori in modo tale da poterle utilizzare all’interno del connettore Data Transfer, è necessario ricorrere ad una specifica sintassi che fa uso della dot notation per navigare all’interno del contenuto stesso.

Ogni connettore salva i propri risultati all’interno di un oggetto identificato da un nome (cfr. la tabella sottostante), detto “chiave”, all’interno del quale è possibile trovare tutte le informazioni generate da tale connettore

Se nella journey da costruire vi è la necessità di avere più connettori dello stesso tipo (ad esempio due restHttp) è importante selezionare a quale connettore in ordine si fa riferimento.Es: Nella journey sono inseriti due connettori di tipo restHttp. Sarà necessario utilizzare il numero d’ordine (a partire dall’alto) dello stesso.

Quindi per recuperare i dati del secondo connettore restHttp dovremo utilizzare la notazione → restHttp.1.percorso

É importante ricordarsi che l’ordine dei connettori parte da 0.

Dispatcher

Il connettore “Dispatcher” permette di configurare le dinamiche di smistamento supportate da una journey di tipo “Dispatcher”, al fine di definire le modalità e le regole di trasferimento del dialogo da una journey all’altra.

Il connettore “Dispatcher” è selezionabile solo all’interno di una journey di tipo “Dispatcher”.

All’inizio del dialogo tra utente ed agente virtuale, l’elemento di chat che si occupa di inviare la richiesta utente verso Tellya (es. il canale “Chat Widget”), deve anche il parametro “Journey code” (identificato dal campo “currentJourneyCode” nell’API Orchestrate) che identifica la journey di default da invocare alla prima interazione (tipicamente l’intento di “Welcome”).

Al parametro “Journey code”, il cui valore è da scegliere arbitrariamente in fase di configurazione, deve corrispondere l’indicazione che informa Tellya riguardo a quale journey invocare quando si presenta tale valore di parametro. Tale collegamento viene impostato sfruttando le prime due colonne della configurazione del connettore “Dispatcher”:

• Parameters: valore del parametro che invierà l’elemento di chat verso Tellya
• Default Journey: journey che il “Dispatcher” deve invocare quando l’elemento di chat invia a Tellya il valore di parametro definito nel campo “Parameters”.

Facendo riferimento all’esempio quindi, se l’elemento di chat invia come “Journey Code”/”Parameters” il valore “AT”, il connettore “Dispatcher” indirizzerà la conversazione verso la journey “Assistenza Tecnica”.

Una volta configurato il collegamento alla “Default journey” è possibile procedere con la configurazione delle altre journey a cui è possibile che che l’utente venga trasferito mentre sta dialogando con la “Default journey” (nell’esempio la journey “Assistenza Tecnica”).

In particolare, all’interno dell’agent configurato nella “Default journey”, sarà possibile contrassegnare tramite Tag alcuni elementi (intenti, page, route…): quando il flusso conversazionale transiterà per tali elementi, verrà innescato il passaggio ad una journey (e quindi ad un agent) differente.

A tale scopo è possibile sfruttare le ultime due colonne della configurazione del connettore “Dispatcher”:

• Dispatcher code (Tag): valore utilizzato per contrassegnare l’elemento e che determina una transizione verso una journey differente.
• Switch journey: journey che il “Dispatcher” dovrà invocare quando il Tag associato ad un elemento dell’agente della “Default journey” assume il valore specificato come “Dispatcher code (Tag)”

Facendo ancora riferimento all’esempio quindi, se durante il dialogo con l’agent configurato per la journey “Assistenza Tecnica” si transita per un elemento contrassegnato dal Tag con valore “CO”, il “Dispatcher” effettuerà la transizione verso la journey “Consumer” che si occuperà, attraverso il suo agente, di rispondere alle successive richieste dell’utente.

È possibile configurare più transizioni attivabili dalla “Default journey” (tramite il pulsante “+Add”): nell’esempio è stato anche configurato un possibile passaggio verso la journey “Customer Experience” quando il Tag assume valore “CX”.

Analogamente è inoltre possibile configurare diverse combinazioni di “Parameters” – “Default Journey” in modo da prevedere diverse journey di avvio della conversazione ed ulteriori transizioni tra journey.

Come “Default Journey” e “Switch” journey possono essere selezionate unicamente journey Standard (non “Dispatcher” o “Fulfillment”).

Per completare la configurazione del meccanismo del “Dispatcher” e definire gli snodi conversazionali in cui effettuare il passaggio tra una journey e l’altra è necessario contrassegnare tali snodi sfruttando i Tag.

All’interno della journey contrassegnata come “Default journey” è quindi necessario contrassegnare uno o più snodi conversazionali (nell’esempio l’intento “Dispatch-to-CO”) con un tag le seguenti caratteristiche:

• Category: “Dispatcher”
• Name: uno dei valori definiti come “Dispatcher code (Tag)”, a seconda della journey verso cui si desidera dirottare il dialogo una volta che lo snodo conversazionale viene raggiunto (nell’esempio “CO”).

Se, nell’agente configurato per la journey “CO”, si vuole poter tornare alla journey che ha generato la transizione (nell’esempio “AT”), è possibile associare un tag Category “Dispatcher” e Name “{back}”. Attraverso l’impostazione di tale “parola chiave” (che per funzionare correttamente non può essere modificata) in un determinato snodo conversazionale, Tellya si occuperà, attraverso il “Dispatcher” di dirottare la conversazione tornando all’agente originale di partenza.

Error Handler

Il connettore Error handler consente di gestire direttamente nel Process flow le operazioni da effettuare in caso di errore da parte di una chiamata REST HTTP, gestendo in un solo connettore diverse tipologie di codice errore.

All’interno della schermata è possibile modificare principalmente 3 elementi:

• Error code: in questo input è possibile inserire il codice di errore da gestire con due possibili formattazioni
  • Codice completo, quindi la cifra completa (es formattazione: 402, 403) dividendoli utilizzando una virgola tra uno e l’altro
  • Insieme di codici, facendo riferimento alla prima e/o seconda cifra di errore, comprendendo tutti i possibili codici successivi (es formattazione: 40*, 5**)
• Connector: tramite una select sarà possibile selezionare i connettori che verranno eseguiti al verificarsi del codice precedentemente inserito. Sono con ordine “a scendere” e possono essere impostati aprendoli singolarmente Una volta cliccato sull’icona “setting” si accede alla modale classica di modifica. Nel caso si selezionasse il connettore sbagliato è possibile rimuoverlo tramite l’icona “trash”
• Skip journey: questa checkbox permette di saltare i connettori successivi all’error handler in caso il codice di errore sia censito nell’elenco. Questo permette di evitare possibili stati di errore al proseguire della journey
  Esempio: come da immagine, se la checkbox “Skip journey” è selezionata, al verificarsi dell’errore 403 viene eseguito il percorso configurato per Error handler ma non il connettore Translate successivo, terminando di fatto la journey

Ogni riga della tabella può essere eliminata, rimuovendo anche tutti i connettori ad essa associati tramite la croce (X) presente sulla sinistra.

Non tutti i connettori presenti in catalogo possono essere utilizzati nel connettore Error Handler

Event Caller

Il connettore Event Caller permette di invocare eventi.

Event Caller ha due comportamenti diversi in base al connettore Dialogflow presente all’interno della journey:

• Journey ES: se la journey è di tipo ES, sarà possibile configurare sia il nome dell’evento, che i parametri da utilizzare.

• Journey CX: se la journey è di tipo CX, sarà possibile configurare solo il nome dell’evento.

Questo connettore non è disponibile per le journey di tipo fulfillment e dispatcher

Generic Rule

Il connettore “Generic Rule” permette di innescare l’esecuzione di un flusso secondario di connettori, all’interno di una journey, solo al verificarsi di particolari condizioni. Tale connettore permette quindi di introdurre delle “esecuzioni condizionali” all’interno del normale flusso di processo e di esecuzione di una journey.

La configurazione del connettore “Generic Rule” varia a seconda della tipologia di NLU utilizzato all’interno della journey, ma in tutti i casi viene richiesto di specificare una o più condizioni che devono verificarsi al fine di innescare il flusso secondario (di cui viene richiesto di specificare il primo connettore da eseguire).

Il connettore “Generic Rule” non è disponibile all’interno delle journey di tipo “dispatcher“.

Configurazione

Dalla finestra di configurazione del connettore “Generic Rule” è possibile specificare:

• Un nome da assegnare alla regola, in modo tale da distinguere il connettore più facilmente all’interno della journey, nel caso in cui ne vengano configurati diversi
• Una o più condizioni che devono essere soddisfatte per poter innescare il flusso secondario. Le condizioni possono essere valutate in congiunzione logica AND (“Match EVERY rule”), caso in cui tutte le condizioni configurate devono verificarsi per poter innescare il flusso secondario, oppure in disgiunzione logica OR (“Match AT LEAST ONE rule”), dove è sufficiente che una sola delle condizione configurate venga verificata.
  Per ogni condizione devono essere configurati i tre relativi campi:
  • Field type: campo o parametro conversazionale che deve essere verificato (scelto tra quelli elencati nella tabella sottostante)
  • Operand: operatore logico di confronto
  • Value: valore che il campo o parametro specificato in “Field type” deve assumere per considerare la condizione come verificata
• Run the connector: il primo connettore del flusso secondario che deve essere eseguito al verificarsi delle condizioni configurate all’interno del connettore “Generic Rule”.

Generic SMTP

Il connettore Generic SMTP consente di innescare l’invio di un messaggio di posta elettronica di cui è possibile definire le diverse caratteristiche e proprietà.

Il wizard di configurazione si articola in tre step:

1. SMTP server, configurazioni relative al server di posta che effettuerà l’invio del messaggio di posta:
   • Indirizzo dell’host
   • Numero di porta del server
   • Username e password per l’accesso
   • Eventuale alias da impostare
2. Recipient, per configurare i dettagli del destinatario
   • Indirizzo del destinatario
   • Eventuali indirizzi da aggiungere in copia conoscenza o copia conoscenza nascosta
3. Content, per configurare le caratteristiche del messaggio:
   • Oggetto del messaggio
   • Corpo del messaggio, il quale può essere un testo semplice oppure un template HTML.

Nel caso si selezioni l’opzione template HTML come corpo del messaggio è possibile anche definire, all’interno della tabella che appare nella parte inferiore della modale, i valori che sostituiranno le eventuali chiavi presenti nel template.

Google Dialogflow ES

Il connettore Google Dialogflow ES permette di inserire all’interno della journey un agente virtuale creato tramite la piattaforma conversazionale Dialogflow ES di Google.

Aggiungendo un nuovo connettore di questo tipo all’area di lavoro è possibile, accedendo alle sue impostazioni, selezionare quale agente Dialogflow ES utilizzare all’interno della journey tra quelli disponibili all’interno del proprio account Tellya.

Accedendo successivamente alla configurazione di tale connettore vengono messe a disposizione due opzioni:

• “Switch agent”: permette di modificare l’agente Dialogflow ES assegnato alla journey. Prima di concludere tale operazione è possibile esportare in locale tutti i dati relativi agli intenti (risposte, tag, ecc…) e la cronologia conversazionale.
  Inoltre è possibile mantenere o eliminare tutti i dati analitici e conversazionali dell’agente precedente.
• “Import agent data”: permette di importare delle configurazioni relative agli intenti all’interno dell’attuale agente Dialogflow ES assegnato alla journey

Switch agent

La modifica dell’agente associato ad una journey si sviluppa in due passaggi:

1. “General Settings”: tramite il menu a tendina “Agent” è possibile selezionare l’agente Dialogflow ES desiderato.
2. “Export data & history”: è possibile esportare le configurazioni relative agli intenti dell’agente attualmente associato alla Journey (“Status” degli intenti, configurazioni di risposte, tag associati…) e la relativa cronologia conversazionale. Tutte le configurazioni relative all’agente definite all’interno del progetto Dialogflow ES non subiranno invece modifiche.

Effettuando un cambio di agente vengono eliminate tutte le configurazioni relative agli intenti ma, di default, vengono mantenuti i dati statistici e analitici, oltre che la cronologia conversazionale. Tramite l’apposita opzione in “Export data & history” è invece possibile eliminare anche queste informazioni durante il cambio di agente.

Import agent data

Tramite l’opzione “Import agent data” è possibile caricare le configurazioni di un agente precedentemente esportato all’interno dell’agente attualmente configurato nella Journey. 

É necessario importare un file in formato .xlxs, esportato ad esempio in una precedente operazione di “Switch agent”. Affinchè il caricamento delle informazioni sia valido, è necessario che gli intenti del file caricato per cui sono presenti configurazioni (come tag o risposte) siano presenti anche nell’agente in cui tali configurazioni verranno importate.

Google Dialogflow CX

Il connettore Google Dialogflow CX permette di inserire all’interno della journey un agente virtuale creato tramite la piattaforma conversazionale Dialogflow CX di Google.

Aggiungendo un nuovo connettore di questo tipo all’area di lavoro è possibile, accedendo alle sue impostazioni, selezionare quale agente Dialogflow CX utilizzare all’interno della journey tra quelli disponibili all’interno del proprio account Tellya.

Accedendo successivamente al connettore, dopo aver selezionato un agente vengono messe a disposizione due opzioni:

• “Switch agent”: permette di modificare l’agente Dialogflow CX assegnato alla journey. Prima di concludere tale operazione è possibile esportare in locale tutti i dati relativi all’agente e la cronologia conversazionale.
  Inoltre è possibile mantenere o eliminare tutti i dati analitici e conversazionali dell’agente precedente.
• “Import agent data”: permette di importare delle configurazioni relative agli intenti all’interno dell’attuale agente Dialogflow CX assegnato alla journey

Switch agent

La modifica dell’agente associato ad una journey si sviluppa in due passaggi:

1. “General Settings”: tramite il menu a tendina “Agent” è possibile selezionare l’agente Dialogflow CX desiderato.
2. “Export data & history”: è possibile esportare le configurazioni relative all’agente dell’agente attualmente associato alla Journey (“Status” degli elementi, tag associati…) e la relativa cronologia conversazionale. Tutte le configurazioni relative all’agente definite all’interno del progetto Dialogflow CX (come ad esempio le risposte) non subiranno invece modifiche.

Effettuando un cambio di agente vengono eliminate tutte le configurazioni ma, di default, vengono mantenuti i dati statistici e analitici, oltre che la cronologia conversazionale. Tramite l’apposita opzione in “Export data & history” è invece possibile eliminare anche queste informazioni durante il cambio di agente.

Import agent data

Tramite l’opzione “Import agent data” è possibile caricare le configurazioni di un agente precedentemente esportato all’interno dell’agente attualmente configurato nella Journey. 

È necessario importare un file in formato .xlxs, esportato ad esempio in una precedente operazione di “Switch agent”. Affinché il caricamento delle informazioni sia valido, è necessario che gli elementi del file caricato per cui sono presenti configurazioni siano presenti anche nell’agente in cui tali configurazioni verranno importate.

Natural Language

Il connettore Natural Language consente di analizzare le richieste degli utenti sfruttando il servizio Natural Language API di Google, allo scopo di determinarne il “sentiment”, ovvero l’attitudine positiva o negativa di un’interazione, fornendo un relativo punteggio.

In particolare il “sentiment” è rappresentato da due valori:

• Score: punteggio che va da -1.0 (negativo) a 1.0 (positivo) corrispondente al valore dell’inclinazione emotiva complessiva della frase analizzata
• Magnitude: indica la forza complessiva dell’emozione (score), all’interno del testo analizzato, sia positiva che negativa. Ogni espressione di emozione all’interno della frase analizzata contribuisce alla magnitude complessiva della frase (quindi testi più lunghi potrebbero avere un valore di magnitude più elevato).

Per ulteriori informazioni riguardo all’analisi del “sentiment” e l’interpretazione dei valori è possibile fare riferimento alla Documentazione Google.

Il comportamento e le logiche di analisi del connettore differiscono a seconda del motore di NLU selezionato e della tipologia di journey scelta:

• Per journey Dialogflow CX Standard e Fulfillment / Dialogflow ES Standard
  • L’analisi del sentiment viene eseguita unicamente quando l’interazione è innescata da una query utente (testuale o vocale)
  • Vengono escluse le interazioni da eventi
• Per journey Dialogflow ES Fulfillment
  • L’analisi del sentiment viene eseguita sempre, anche nel caso di evento, caso in cui la stringa analizzata è il nome stesso dell’evento

Il risultato dell’analisi effettuata dal connettore Natural Language Understanding e i relativi valori di sentiment (score) e magnitude vengono visualizzati in differenti sezioni della piattaforma:

• Analytics > Engagement: vengono riportati i valori di sentiment e magnitude per ogni intento 
• Analytics > History: vengono riportati i valori di sentiment e magnitude per ogni interazione (se l’interazione è stata analizzata)
• Training: vengono riportati i valori di sentiment e magnitude per ogni interazione all’interno della finestra di dettaglio di ogni sessione conversazionale (se l’interazione è stata analizzata)

Inoltre, il risultato dell’analisi di tale connettore viene sempre fornito in output dall’API “Orchestrate”.

REST HTTP

Il connettore REST HTTP permette di eseguire delle chiamate REST verso servizi o API esterne. Il wizard di configurazione si articola in quattro step:

1. General settings, deve essere specificato:
   • Il metodo HTTP (POST/GET/PUT/DELETE)
   • L’URL della risorsa invocare
2. Headers, è possibile specificare eventuali coppie chiave valore da specificare nell’intestazione del messaggio HTTP.
3. Query Params, è possibile specificare eventuali argomenti del messaggio HTTP (coppie chiave/valore).
4. Payload, è possibile specificare un eventuale corpo del messaggio HTTP.

Salesforce Sales Cloud

Il connettore “Salesforce Service Cloud” permette di gestire, tramite la conversazione, i contatti, i lead, le opportunità e gli account dei clienti, insieme al processo vendita.

Il connettore Salesforce Sales Cloud è disponibile solo per il motore di NLU Dialogflow ES.

Prima di procedere con la configurazione del connettore è necessario aver creato una Connected App all’interno del proprio account Salesforce.

Una Connected App è un framework che consente ad una piattaforma esterna di integrarsi con Salesforce tramite le sue API. Nel caso di Tellya, può essere usata per interfacciarsi, attraverso una chat, alla piattaforma Salesforce tramite API. Per configurare una Connected App è possibile fare riferimento alla documentazione ufficiale di Salesforce.

Per poter configurare i seguenti passaggi accedere a Salesforce e navigare la sezione “Setup” > “Apps” > “App Manager”, selezionare quella desiderata e tramite il pulsante azione fare clic su “view”. 

La configurazione del connettore si articola in due passaggi:

1. General setting, dedicato alla configurare dei parametri di base del servizio, in particolare:
   • Client ID: Chiave Utente corrispondente alla “Customer Key” della Connected App di Salesforce
   • Client Secret: Chiave Segreta corrispondente alla “Consumer Secret” della Connected App di Salesforce
   • Callback URL: URL da inserire nell’omonimo campo della sezione “Manage Connected Apps”
   • AUTH_CODE: Codice di autorizzazione generato tramite Salesforce, e visualizzato selezionando la voce “Authorize on Salesforce” per autorizzare Tellya.
2. Actions & fields, per configurare le azioni che si vogliono eseguire con gli account:
   • Query Object: si può scegliere tra gli oggetti selezionabili nel menù a tendina e descrive il tipo di operazione che si vuole eseguire. Per maggiori informazioni fare riferimento alla documentazione Salesforce.
   • Type Query: permette di scegliere l’azione che si vuole eseguire. Le scelte possibili sono: create, delete, select e update
   • Action value: la “action” Dialogflow che viene configurata nell’intento specifico e che permette di invocare l’azione
   • Field name: il nome del parametro sul quale si deve eseguire l’azione, il menù a tendina visualizzato permette la selezione tra i campi disponibili
   • Value: il valore de che deve assegnato al field name 
   • Record ID: l’identificativo del record che deve essere aggiornato o eliminato
   • Query Result: a seguito di una ricerca indica quali informazioni restituire è possibile anche selezionare la count dei vai record
   • Group By: permette di aggregare i risultati della ricerca, così come offerto dalla sintassi SQL
   • Clause Type: clausola condizionale per il tipo ricerca che si vuole effettuare
   • Operator: operatore logico che permette di concatenare più campi o clausole nella ricerca

Salesforce Service Cloud

Il connettore “Salesforce Service Cloud” permette di gestire, tramite la conversazione, la creazione di un ticket di segnalazione o una richiesta di supporto all’interno dell’omonima piattaforma di assistenza clienti.

 Il connettore Salesforce Service Cloud è disponibile solo per il motore di NLU Dialogflow ES.

Prima di procedere con la configurazione del connettore è necessario aver creato una Connected App all’interno del proprio account Salesforce.

Una Connected App è un framework che consente ad una piattaforma esterna di integrarsi con Salesforce tramite le sue API. Nel caso di Tellya può essere usata per interfacciarsi tramite chat alla piattaforma Salesforce tramite API. Per configurare una Connected App fare riferimento alla documentazione ufficiale di Salesforce.

Per poter configurare i seguenti passaggi accedere a Salesforce e navigare la sezione “Setup” > “Apps” > “App Manager”. Selezionare l’applicazione desiderata e tramite il pulsante azione fare clic su “view”. 

La configurazione del connettore si articola in due passaggi:

1. General setting, dedicato alla configurare dei parametri di base del servizio, in particolare:
   • Client ID: Chiave Utente corrispondente alla “Customer Key” della Connected App di Salesforce
   • Client Secret: Chiave Segreta corrispondente alla “Consumer Secret” della Connected App di Salesforce
   • Callback URL: URL da inserire nell’omonimo campo della sezione “Manage Connected Apps”
   • AUTH_CODE: Codice di autorizzazione generato tramite Salesforce, e visualizzato selezionando la voce “Authorize on Salesforce” per autorizzare Tellya.
2. Actions & fields, dedicato alla configurare le azioni connesse al ticket:
   • Query Object: è possibile scegliere tra l’oggetto “Case”, che permette di gestire un ticket, e l’oggetto “Case comment”, che permette di aggiungere un commento al ticket. Per maggiori informazioni fare riferimento alla documentazione Salesforce.
   • Type Query: permette di scegliere l’azione che si vuole eseguire. Le scelte possibili sono: create, delete, select e update
     • Create: creazione di un nuovo case
     • Delete: cancellazione del case selezionato
     • Select; permette di ricercare un case dato un parametro
     • Update: permette di aggiornare le informazioni di un case
   • Action value: il valore “action” configurato all’interno di uno o più intenti in Dialogflow e che decreta l’innesco dell’azione.
   • Field name: il nome del parametro sul quale si deve eseguire l’azione, il menù a tendina visualizzato permette la selezione tra i campi disponibili
   • Value: il valore che deve assegnato al field name 
   • Record ID: l’identificativo del record che deve essere aggiornato o eliminato
   • Query Result: a seguito di una ricerca indica quali informazioni restituire. È possibile anche selezionare il totale (“count”) dei record
   • Group By: permette di aggregare i risultati della ricerca, per uno dei parametri restituiti
   • Clause Type: clausola condizionale per il tipo di ricerca che si vuole effettuare
   • Operator: operatore logico che permette di concatenare più campi o clausole nella ricerca

SendGrid

Il connettore SendGrid permette di configurare l’invio di messaggi di posta elettronica attraverso l’omonimo servizio di “email automation”.

La configurazione del connettore si articola in tre passaggi:

1. Configurations, per configurare i parametri di base del servizio SendGrid, in particolare:
   • Api Key: generata dall’interfaccia di amministrazione SendGrid (Settings > API Keys)
   • Sender: indirizzo email mittente. L’indirizzo specificato deve necessariamente essere censito e verificato all’interno dell’interfaccia di amministrazione SendGrid (Settings > Sender Authentication)
2. Recipient, per configurare gli indirizzi destinatari del messaggio email:
   • Email recipient: indirizzo email destinatario
   • CC: eventuale indirizzo email inserito in “copia conoscenza”
   • Ccn: eventuale indirizzo email inserito in “copia conoscenza nascosta”
3. Content, per configurare il contenuto del messaggio inviato:
   • Subject: oggetto del messaggio
   • Corpo del messaggio, il quale può essere costituito da un testo semplice (“Plain Text”) oppure da un template HTML (“HTML template”).

Nel caso si selezioni l’opzione “HTML template” come corpo del messaggio è possibile utilizzare tag HTML per formattare il messaggio e anche definire, all’interno della sottostante tabella “Template Keys”, un elenco di valori (anche estratti come variabile) che andranno a sostituire le corrispondenti parti di testo eventualmente presenti nel corpo del messaggio.

Translate

Il connettore Translate sfrutta le Cloud Translation API di Google per rilevare la lingua di un testo (tipicamente la richiesta dell’utente) e/o tradurlo in una lingua differente.

La configurazione del connettore varia a seconda del tipo di azione selezionato:

• Rilevamento lingua (Detect language), dove è possibile specificare:
  • Campo del payload in input da analizzare e sul quale effettuare il rilevamento della lingua (obbligatorio).
  • Numero minimo di caratteri di cui deve essere composta la frase o la parola affinché venga attivato il connettore
  • Possibilità di sovrascrivere con il valore lingua rilevato dal connettore con un eventuale informazione relativa alla lingua proveniente da sistemi Front End.
  • Possibilità di effettuare il rilevamento della lingua solo alla prima interazione di ogni sessione.
• Traduzione (Translate language), dove è possibile specificare:
  • Campo del payload in input da analizzare e sul quale effettuare il rilevamento della lingua (obbligatorio).
  • Lingua di traduzione

Esempio di configurazione

È possibile configurare una journey utilizzando più connettori Translate al fine di rendere “multilingua” un agente configurato per gestire unicamente una lingua.

Poniamo, ad esempio, di avere a disposizione un agente Dialogflow con intenti in lingua italiana, ma di voler comprendere anche le richieste utente che utilizzano una lingua differente e rispondere ad essi traducendo le risposte previste in italiano proprio nella lingua di interazione dell’utente.

Per rendere possibile tale meccanismo è necessario configurare due connettori Translate posti rispettivamente prima e dopo un connettore Google Dialogflow ES.

Il primo connettore Translate (posto prima del connettore Dialogflow) si occuperà di tradurre la richiesta utente (qualunque sia la lingua) nella lingua comprensibile all’agente (ad esempio l’italiano, se l’agente è configurato con intenti in grado di comprendere tale lingua).

È quindi necessario indicare nel campo “Field to analyze” la variabile $userQuery, che ad ogni interazioni verrà popolata con l’input inserito dall’utente e abilitare l’opzione “Override Front End language detection”, per demandare al connettore Transalte il riconoscimento della lingua dell’utente.

Il secondo connettore Translate invece (posizionato dopo al connettore Dialogflow), si occuperà di tradurre la risposta in italiano restituita da Dialogflow nella lingua di interazione dell’utente, rilevata dal primo connettore Translate in fase di input (selezionando l’opzione “Use original user language”).
Il campo da analizzare quindi, sarà in questo caso configurato con la variabile $outpuText.

Per verificare il corretto funzionamento dalla Test Chat di Tellya è necessario, dalle impostazioni, abilitare l’opzione “Use translate result”, che restituisce all’utente la traduzione risultante dall’esecuzione del secondo connettore Translate.

Twilio SMS

Il connettore Twilio SMS permette di configurare l’invio di SMS tramite l’omonimo servizio.

La configurazione del connettore si articola in due passaggi:

1. Configuration, per configurare i parametri di base del servizio Twilio, in particolare:
   • Account SID: generata dall’interfaccia di amministrazione Twilio (Home > Account Info)
   • Auth Token: generata dall’interfaccia di amministrazione Twilio (Home > Account Info)
2. Recipients & Contents, per configurare i numeri di mittente e destinatario e il contenuto del messaggio da inviare:
   • Sender: numero di telefono del mittente, completo di prefisso internazionale(standard E.164). Deve essere quello configurato nell’interfaccia di amministrazione Twilio.
   • Receiver: numero di telefono del destinatario, completo di prefisso internazionale(standard E.164).
   • SMS Text: corpo del messaggio da inviare. (max 1600 char. Se il corpo del messaggio contiene più di 160 caratteri GSM-7 (o 70 caratteri UCS-2), Twilio invierà il messaggio come un SMS suddiviso).

Per i campi Sender e Receiver è possibile non selezionare alcun valore per il campo “prefisso” e inserire il numero completo nell’input “Sender” o “Receiver” o recuperarlo dinamicamente dalla conversazione tramite i parametri.

Zendesk

Il connettore Zendesk permette di creare, tramite la conversazione, un ticket di segnalazione o di richiesta supporto all’interno dell’omonima piattaforma di assistenza clienti.

La configurazione del connettore si articola in due step:

1. General setting, per configurare i parametri di base del servizio, in particolare:
   • Zendesk Support URL: indirizzo del proprio “help center” Zendesk
   • Email: indirizzo mail associato all’account
   • API token: generabile dall’interfaccia di amministrazione Zendesk (Admin > Channel > API)
2. Ticket details, per configurare i dettagli del ticket (i quali possono essere anche estratti dalla conversazione sfruttando le Variabili connettori):
   • Subject: titolo/oggetto della segnalazione
   • Body: corpo/dettaglio della segnalazione