Skill Chat

La Skill Chat di CAITY consente di usufruire di un setup nella piattaforma tramite l'utilizzo di un componente chat, integrabile all'interno di un qualsiasi sito web. Questa è la modalità principale di interfacciamento a CAITY, ed è utile per l'implementazione di uno o più chatbot evoluti all'interno di un qualsiasi sito web.

La prima operazione compiuta dalla skill chat è quella di utilizzare il suo caity-id per recuperare il setup della skill chat associata, che contiene le informazioni necessarie per la corretta visualizzazione e funzionamento della chat. Il caity-id è un identificativo univoco che viene fornito da AIDAPT al cliente, e deve essere inserito per poter ottenere il setup personalizzato della skill chat. Una volta configurata e rederizzata in pagina, la chat tenta di recuperare l'ultima Sessione salvata o ne crea una nuova. Una Sessione è identificata da un specifico UUID, e viene utilizzato come base per determinare lo stato corrente della chat, così come la storia della conversazione tra l'utente e il bot. L'utente può eventualmente anche resettare la Sessione tramite la chat, oppure possono essere presenti meccanismi di scadenza della sessione e conseguente reset automatico della Sessione (descritti di seguito).

Configurazione della chat

Per includere la chat all'interno del proprio sito, è necessario innanzitutto creare un Setup che sia collegato ad una Skill che abbia un Archetipo di tipo Chat. Di seguito i passaggi per la creazione del setup:

1. General information

In questa sezione vengono fornite informazioni generali sulla configurazione della chat.

• Name: il nome del Setup della chat. - si consigliano nomi facilmente identificabili sul tipo di chat che si vuole implementare.
• Organization: l'organizzazione a cui appartiene la configurazione della chat. - serve per mostrare il setup ai broker apparteneni alla stessa organizzazione. Inoltre la valorizzazione di questo parametro apre al terzo step di configurazione, mostrando solo i flow e le skill associate all'organizzazione scelta.

2. Limit of use

In questa sezione possiamo specificre il budget mensile dedicato a questo Setup. Durante la costruzione di un flow si deve prevedere l'impatto economico che questo avrà con il suo uso e dunque il budget da dedicargli. Il budget è mensile e il suo superamento comporta la sospensione della chat fino al mese successivo. Il budget è espresso in dollari.

3. Flow

In questa sezione è possibile selezionare uno dei flow che saranno utilizzati dalla chat. I flow sono le entità che definiscono le azioni che la chat può eseguire, e possono essere utilizzati per gestire le richieste degli utenti, rispondere a domande frequenti, o eseguire operazioni specifiche. È possibile selezionare un solo flow da associare alla chat.

Sulla base del flow selezionato la procedura di creazione del setup si adatterà, mostrando i campi di configurazione specifici per il flow scelto. Ad esempio, se il flow selezionato è un flow di tipo Tree, verranno mostrati ulteriori campi per l'inserimento delle informazioni necessarie alla sua configurazione.

4. Skill

Questo quarto step del Setup permette di selezionare uno delle skill diposnibili all'oranizzazione. In questo caso dovremo selezionare la skill chat e a quel punto la form mostrerà le ulteriori opzioni per modififcare le caratteristiche, anche dette Aspects, della chat.

• Skill config:

  • Session Expiration Policy: definisce la modalità di scadenza di una sessione della chat:
    • None: non è prevista una scadenza automatica della sessione.
    • Inactivity Timeout: è prevista una scadenza automatica della sessione, definita dal tempo trascorso dall'ultimo messaggio scritto dall'utente.
  • Maximum Inactivity Period (minutes): nel caso in cui c'è una policy basata sull'inattività, questo campo viene usato per indicare il periodo in minuti che deve trascorrere dall'ultimo messaggio dell'utente affinché la sessione scada.
  • Enable file upload: se abilitato, abilita le rotte necessarie per il caricamento dei file dalla chat. ATTENZIONE: per usufruire del caricamento del file dalla chat, è anche necessario abilitare l'impostazione negli Aspect che abilita la modalità di caricamento dei file da un punto di vista grafico
  • Enable Aithentication: se abilitato, il meccanismo di chat viene protetto tramite un meccanismo di autenticazione (descritto più in dettaglio di seguito)
  • Authentication Secret: se l'autenticazione è abilitata, è il parametro utilizzato per la generazione e la verifica dei token

• Skill aspects

  • Theme: questa sezione definisce l'aspetto visivo del componente andando a definire delle variabili che verranno utilizzate dalla chat per renderizzare i propri elementi.

    • Colors: palette dei colori

      • primary-500:: Colore della barra superiore della chat e il tasto di invio dei messaggi. Default: #1A212A
      • primary-600:: Colore delle options sulla barra superiore della chat. Default: #.
      • primary-700:: Influenza il colore della barra superiore della chat e il tasto di invio dei messaggi. Default: #
      • Secondary 500: Eventuale colore di background del logo.
      • Secondary 600: Colore base della scrollbar.
      • Secondary 700: Colore in hover della scrollbar.
      • Text Primary: Colore del testo dei messaggi nella chat e del disclaimer nonchè di tutti i testi dei tooltip.
      • Text Secondary: Colore del titolo della chat, e delle icone a sfondo primary (default: #FFF).
      • Text Tertiary: Colore del testo dei messaggi utente e delle aree di input - viene usato anche come colore delle icone a sfondo trasparente (icona allegati, rimozione allegato e chiusura dialog) (default: #005).
      • Text Placeholder: Colore del testo di aiuto delle aree di input (default: #aaa).
      • Chat Background: Colore di sfondo della chat e della dialog di feedback (default: #fff).
      • Bot Baloon Border: Colore del bordo del fumetto del bot (default: transparent).
      • Bot Baloon Background: Colore di sfondo del fumetto del bot (default: transparent).
      • User Baloon Border: Colore del bordo del fumetto dell'utente (default: #DDDFE0) - viene usato anche per indicare un input in focus.
      • User Baloon Background: Colore di sfondo del fumetto dell'utente e dei campi di input (default: #F0F3F7).

    • typography (Tipografia)

      • Font Family: La famiglia di caratteri utilizzata (default: vuoto)- quando vuoto userà la famiglia di caratterei di default del browser.

  • events (Eventi): Questa sezione definisce i messaggi di stato mostrati durante le operazioni dell'assistente.

    • Rag: Messaggio durante il caricamento dei dati (default: Sto caricando i dati...).
    • Check: Messaggio durante la verifica dei dati (default: Sto verificando i dati...).
    • Execution: Messaggio durante l'elaborazione (default: Sto pensando...).
    • Exploring: Messaggio durante l'analisi della richiesta (default: Sto analizzando la richiesta...).

  • Sezione: options (Opzioni): Questa sezione contiene le impostazioni di configurazione generali e le funzionalità associate alla chat.

    • ThemeVariant: Variante del tema, cover o floating (default: cover).
    • Open: Opzione disponibile solo con tema 'floating', specifica se il componente all'avvio della pagina è aperto o chiuso (default: falso).
    • LogoLink: Un link associato al logo (default: vuoto) - quando vuoto non verrà visualizzato nessun logo.
    • BottomNotRounded: Opzione particolare utile solo con tema cover. Se vero, rimuove l'arrotondamento dal bordo inferiore e alleneando la chat sul fondo (default: falso).
    • ContextHistory: Il numero di messaggi scambiati tra utente e bot che vengono inviati al server come contesto di conversazione. Più è alto il numero più token ogni interazione utilizza. (default: 8).
    • FeedbackEnabled: Se attivo l'utente puó esprimere il proprio feedback sulle risposte del bot. I feedback sono poi visualizzabili in dashboard del setup. (default: vero).
    • PricesEnabled: Quando attivo ogni messaggio generato dal bot mostrerà anche i costi generati. (default: falso)
    • CopySessionEnabled: Abilita la copia del codice sessione della conversazione attraverso il menù a scomparsa (default: falso).
    • ShowConnectionStatus: Mostra o nasconde lo stato della connessione - appare sotto il titolo (default: falso).
    • EnableAttachments: Abilita il caricamento di allegati dalla chat (default: falso).
    • EnableResponseEvent: Abilita la visualizzazione degli eventi nei messaggi - tempo di generazione e altre info (default: true).
    • AcceptedFileFormats (separated by comma): Se EnableAttachments è abilitato e questo campo è popolato, consente la restrizione dei formati accettati ad alcuni tipi predeterminati (default: vuoto)
    • MaxFilesNumber: Se EnableAttachments è abilitato e questo campo è popolato, permette l'upload di uno o più file fino al valore definito. (default: 1)
    • PreserveConversations: Se abilitato permette di mantenere le conversazioni attive nel database. Se la chat dovesse riprendere lo stesso codice di conversazione allora mostrerà la vecchia conversazione. (default: falso)

  • Sezione: messages (Messaggi): Questa sezione definisce i testi utilizzati nell'interfaccia utente.

    • Online: Testo per lo stato online (default: Online).
    • Offline: Testo per lo stato offline (default: Offline).
    • Greeting: Messaggio di benvenuto (default: Ciao sono il tuo assistente virtuale! Cosa posso fare per te oggi?).
    • Disclaimer: Avviso legale o di responsabilità (default: L'assistente può commettere errori. Verifica le informazioni importanti).
    • Placeholder: Testo segnaposto dell'input di testo (default: Scrivi qui la tua richiesta...).
    • WindowTitle: Titolo della finestra (default: Assistente Demo).
    • DefaultError: Messaggio di errore generico (default: C'è stato un errore inatteso, riprova più tardi).
    • AvailableChars: Testo che indica i caratteri rimanenti (default: Caratteri rimasti).
    • DropDownHistory: Testo per l'opzione di riavvio della chat (default: Riavvia chat).
    • SendingPlaceholder: Messaggio mostrato durante l'invio di una richiesta (default: Sto pensando...).
    • FeedbackDialogTitle: Titolo della finestra di dialogo per il feedback (default: Scrivi il tuo messaggio di feedback).
    • UnableToPasteCharLimit: Messaggio di errore per superamento del limite di caratteri durante l'incolla (default: Impossibile incollare, il testo supera i caratteri consentiti).
    • FeedbackDialogSendButton: Testo del pulsante di invio nella finestra di feedback (default: Invia).

Integrazione chat nel sito

Una volta configurato il setup, assieme al flow e alle impostazioni della skill associata, è possibile procedere con l'integrazione del componente di frontend della chat all'interno del sito. Per farlo, è necessario includere i seguenti elementi:

<head>
  <!-- other head elements -->
  <script src="https://chat.skill.caity.aidapt.io/caity-skill-chat.umd.js"></script>
</head>
<body>
  <!-- ... -->
  <caity-skill-chat caity-id="{YOUR-CAITY-CHAT-MODULE-ID}"></caity-skill-chat>
  <!-- ... -->
</body>

Parametri chat

Il componente <caity-skill-chat> ha dei parametri che possono essere definiti per personalizzare il suo comportamento. Il tipo di dato di questi attributi è sempre string, viene poi internamente convertito al tipo definito in questa tabella:

param	type	default
PRODUCTION PARAMETERS
caity-id	string	none	questo é l'ID che viene fornito da AIDAPT al cliente e deve obbligatoriamente essere inserito per poter ottenere il setup persoanalizzato della skill chat. Per accedere alla modalità dev di caity-skill-chat in questo campo si può inserire la chiave di test (per lo sviluppo in locale test e in produzione non esiste o é definita ad hoc nell'evironment - sconsigliato)
caity-url	string	caity.skill.aidapt.io	host che ospita l'API della skill caity-skill-chat
metadata	object	undefined	Con questo parametro è possibile specificare ulteriori dati che verranno scambiati con caity-core ad ogni chiamata. Es. in questo oggetto potrebbero finire paths a file, metaprompt, dati di autorizzazione ecc, il tutto poi verrà gestito dai flow lanciati da caity-core
chat-auth-token	string	undefined	Se l'autenticazione è abilitata, questo campo contiene il token JWT necessario per l'autenticazione della chat.
DEV-ONLY PARAMETERS			per entratre in DEV MODE il caity-id deve avere lo stesso valore della variabile d'ambiente VITE_TEST_KEYWORD
setup	object	none	verrà preso questo oggetto come setup e sarà ingorato quello inviato dal server
phrases	string[]	none	le frasi che verranno generate dal bot verranno prelevate da questo array. L'oggetto deve essere in questo formato: ['phrase 1', 'phrase 2', 'ecc...']
disable-secure-connection	bool	false	permette di effettuare connessioni in ws invece che in wss

Meccanismo di autenticazione Chat

Come descritto nei paragrafi precedenti, la Skill Chat supporta un meccanismo di autenticazione (abilitata tramite il parametro Enable Authentication), utilizzato principalmente per i seguenti scopi:

• Limitazione dell'utilizzo della chat per gli utenti non autenticati;
• Passaggio di informazioni associate all'utente da parte dell'azienda che integra CAITY all'interno della propria piattaforma, di seguito definito come Integratore (utile per effettuare eventuali operazioni tra le due piattaforma).

Il flusso di autenticazione si basa sulla generazione di token JWT da parte dell'Integratore. In particolare, nella generazione del token JWT il secret da utilizzare è quello definito nella configurazione del setup (parametro Authentication Secret). Inoltre, il JWT generato dovrà:

• Contenere l'audience caity-skill-chat al suo interno;
• Avere un payload che contenga almeno il campo sub, che ha come valore l'id dell'utente che usufruisce della chat (in formato stringa);
• Avere una scadenza appropriata rispetto al tempo di vita della chat.

Una volta generato il token JWT, questo deve essere incluso come parametro della chat tramite la valorizzazione dell'attributo chat-auth-token. Quando è abilitata l'autenticazione, la chat includerà quindi questo token come argomento da inviare in una prima comunicazione con il servizio CAITY. Se il token è validato correttamente, la chat potrà quindi essere usata normalmente per lo scambio dei messaggi fino alla fine della connessione.