Integrazione con Askme Desk
Richiede un'installazione di Askme Desk raggiungibile dalla rete e un'utenza tecnica dedicata su di essa.
L'integrazione con Askme Desk permette di trasformare una conversazione in una richiesta di assistenza strutturata, con contatto associato automaticamente, sia dal workflow del chatbot sia manualmente dalla console operatore.
Prerequisiti
- Un'installazione di Askme Desk raggiungibile via rete dall'installazione di Askme Chat.
- Un'utenza tecnica dedicata, censita come tale nel pannello di amministrazione di Askme Desk, abilitata sui servizi su cui l'integrazione deve operare.
- Permesso di amministrazione integrazioni per la configurazione.
- Per l'autenticazione OAuth2, un client dedicato sul provider di identità di Askme Desk, abilitato al rilascio di token con le credenziali dell'applicazione.
Modalità di autenticazione
L'integrazione può autenticarsi verso Askme Desk in due modi, alternativi fra loro.
| Modalità | Come funziona | Quando usarla |
|---|---|---|
| HTTP Basic | Askme Chat presenta a ogni chiamata l'utenza tecnica e la relativa password | Installazioni già configurate così, o ambienti in cui non è disponibile un provider di identità |
| OAuth2 | Askme Chat richiede un token al provider di identità, lo rinnova alla scadenza e dichiara a Askme Desk l'utenza da impersonare | Configurazioni nuove, e ambienti in cui si preferisce non conservare la password di un'utenza in una configurazione applicativa |
Le installazioni già configurate con utenza e password proseguono in HTTP Basic senza alcun intervento: non è richiesta alcuna migrazione. Una configurazione nuova propone invece OAuth2.
Configurare l'integrazione
L'integrazione si attiva da Amministrazione → Integrazioni → Askme Desk (vedi anche Integrazioni): selezionare "Attiva", scegliere la modalità di autenticazione e compilare i parametri.
Parametri comuni alle due modalità:
| Parametro | Descrizione |
|---|---|
| URL Endpoint API | Indirizzo a cui è raggiungibile Askme Desk per i servizi applicativi |
| URL pubblico applicativo | Indirizzo a cui l'applicativo è raggiungibile dalla rete; può coincidere con il parametro precedente |
| Codice organizzazione | Codice di organizzazione configurato su Askme Desk (di default "GENERIC"). Obbligatorio con OAuth2, che lo richiede su ogni chiamata |
| Utenza Askme Desk | Utenza tecnica applicativa con cui l'integrazione opera su Askme Desk |
Parametri della sola modalità HTTP Basic:
| Parametro | Descrizione |
|---|---|
| Password | Password dell'utenza tecnica |
Parametri della sola modalità OAuth2:
| Parametro | Descrizione |
|---|---|
| URL del token | Indirizzo del provider di identità a cui richiedere il token |
| Client ID | Identificativo del client abilitato al rilascio del token |
| Client secret | Segreto del client |
I due indirizzi hanno scopi diversi e non sempre coincidono: il primo è quello che Askme Chat contatta per i servizi, il secondo serve a comporre i collegamenti che gli operatori aprono nel browser. Dove Askme Desk è pubblicato attraverso un reverse proxy che instrada le chiamate in base a informazioni presenti nella sessione del browser, l'endpoint applicativo va indirizzato all'istanza, perché una chiamata da server non porta con sé quelle informazioni.
Prima di salvare è possibile selezionare Verifica connessione, che tenta l'autenticazione con i valori indicati e ne riporta l'esito; i segreti già memorizzati vengono riusati se non sono stati reinseriti.
Al termine, selezionare "Applica" per salvare la configurazione.
Password e client secret non vengono mai restituiti dall'applicazione: i campi corrispondenti compaiono valorizzati con un segnaposto quando un segreto è già impostato, e vengono riscritti soltanto se l'amministratore ne inserisce uno nuovo.
Creare richieste e contatti dalla console
Dal menu contestuale di una chat, in inbox o nel dettaglio chat, l'operatore può selezionare "Crea richiesta" o "Apri contatto" su Askme Desk: viene ricercato o creato automaticamente il contatto corrispondente e aperta la relativa scheda, senza uscire dalla conversazione.
L'azione Desk nel workflow del chatbot
Per aprire automaticamente una richiesta a partire da una conversazione gestita dal chatbot è necessario configurare l'azione dedicata su un nodo del workflow: "Creazione richiesta Askme Desk".
- Esegui immediatamente: se attivo, l'azione viene eseguita al raggiungimento del nodo senza attendere un'interazione dell'utente.
- Nodo successo: nodo verso cui prosegue la conversazione se la richiesta viene creata correttamente; alla conversazione viene aggiunta la variabile
idRichiesta, riutilizzabile nei testi successivi del chatbot. - Nodo errore: nodo verso cui prosegue la conversazione in caso di errore nella creazione.
I parametri seguenti devono essere raccolti come variabili di conversazione prima dell'esecuzione del nodo:
| Parametro | Descrizione |
|---|---|
codServizio * | Codice del servizio su cui aprire la segnalazione |
codAsset * | Codice dell'asset su cui aprire la segnalazione |
codTipoRichiesta * | Codice del tipo di richiesta |
codPriorita * | Codice della priorità da assegnare |
idRichiedente ** | ID del contatto richiedente |
nomeRichiedente / cognomeRichiedente / mailRichiedente ** | Anagrafica del contatto, in alternativa a idRichiedente |
codAziendaRichiedente ** | Codice dell'azienda a cui afferisce il contatto |
oggetto * | Oggetto della segnalazione |
descrizione | Descrizione di dettaglio |
note / noteChiusura | Note libere in creazione e in chiusura |
autoclose *** | true/false: se true, la richiesta viene presa in carico e chiusa automaticamente |
idOperatore *** | Operatore Askme Desk usato per presa in carico e chiusura automatica |
Campi obbligatori (*); campi con regola condizionale (**): opzionali se è presente idRichiedente, altrimenti obbligatori; campi con regola condizionale (***): idOperatore è obbligatorio solo se autoclose è impostato a true.
Per richiamare il valore di una variabile in un messaggio del chatbot è sufficiente racchiuderne il nome tra doppie parentesi graffe, ad esempio {{idRichiesta}}.
Chiusura automatica del ticket
Quando autoclose è impostato a true, la richiesta viene automaticamente presa in carico e chiusa dall'operatore Askme Desk indicato in idOperatore. Se la configurazione della terna servizio/asset/tipo richiesta su cui viene aperta la segnalazione prevede note obbligatorie in presa in carico o in chiusura, è necessario che le variabili note e noteChiusura siano valorizzate, altrimenti la chiusura automatica fallisce.
Problemi comuni
| Problema | Causa | Soluzione |
|---|---|---|
| La richiesta non viene creata | Parametri obbligatori mancanti o non validi nel contesto della conversazione | Verificare che tutte le variabili obbligatorie siano raccolte prima del nodo azione |
| La chiusura automatica fallisce | Note obbligatorie non valorizzate secondo la configurazione della terna Askme Desk | Valorizzare note/noteChiusura con nodi precedenti nel workflow |
| L'integrazione risulta inattiva | Credenziali dell'utenza tecnica scadute o endpoint non raggiungibile | Verificare URL, credenziali e raggiungibilità di rete dell'installazione Askme Desk |
| Con OAuth2 Askme Desk rifiuta la chiamata pur rilasciando il token | Il token non riporta fra i destinatari il client con cui Askme Desk è configurato | Sul provider di identità, aggiungere al client di Askme Chat il destinatario corrispondente al client di Askme Desk |
| Con OAuth2 la chiamata viene rifiutata subito | Codice organizzazione non indicato: in questa modalità Askme Desk lo richiede su ogni chiamata | Valorizzare il codice organizzazione nella configurazione dell'integrazione |
| L'utenza indicata non viene riconosciuta | L'utenza tecnica non è censita su Askme Desk o non è attiva nell'organizzazione indicata | Censire l'utenza su Askme Desk e verificarne l'abilitazione nell'organizzazione |
| La richiesta non viene aperta per un determinato cliente | L'utenza tecnica non è abilitata al servizio per l'azienda del contatto richiedente | Verificare su Askme Desk il contratto che lega azienda e servizio e l'appartenenza dell'utenza ai gruppi previsti |