Dialogflow Messenger

L'integrazione di Dialogflow Messenger fornisce al tuo agente una finestra di dialogo di chat personalizzabile, che puoi incorporare nel tuo sito web. La chat è implementata come finestra di dialogo che può essere aperta e chiusa dall'utente finale. Quando è aperta, la finestra di dialogo della chat viene visualizzata sopra i contenuti, nella parte in basso a destra dello schermo.

Screenshot di Messenger

Limitazioni

Configurazione e test

Per configurare e attivare Dialogflow Messenger:

  1. Vai alla console Dialogflow ES.
  2. Fai clic su Integrazioni nel menu della barra laterale sinistra.
  3. Fai clic su Dialogflow Messenger.
  4. Si apre una finestra di dialogo di configurazione.
  5. Scegli un ambiente.
  6. Fai clic su Abilita.
  7. Copia il codice da incorporare e incollalo nel tuo sito web.
  8. Fai clic su Prova ora per testare l'agente.
  9. Nell'angolo in basso a destra della finestra, viene visualizzato un pulsante con il logo Dialogflow. Fai clic su questo pulsante.
  10. Si apre una finestra di dialogo della chat con cui puoi interagire.
  11. Al termine del test, chiudi la finestra di dialogo della chat.
  12. Fai clic su Chiudi nella finestra di dialogo di configurazione.

Embed

Incolla il codice per l'incorporamento copiato in precedenza in una pagina web del tuo sito web. Gli elementi HTML <script> e <df-messenger> devono trovarsi nell'elemento <body> della pagina. Per consentire i layout adattabili, aggiungi anche quanto segue alla pagina:

<meta name="viewport" content="width=device-width, initial-scale=1">

Personalizzazioni HTML

Puoi personalizzare vari aspetti dell'aspetto e del comportamento della finestra di dialogo della chat. L'elemento HTML df-messenger presenta i seguenti attributi:

Attributo Criterio di input Valore
agent-id Obbligatorio ID agente associato all'agente Dialogflow. Questo campo viene precompilato con il tuo ID agente.
chat-icon Facoltativo Icona utilizzata per il pulsante di apertura della finestra di dialogo della chat. L'icona Dialogflow è l'icona predefinita. Questo campo deve essere un URL pubblico. Le dimensioni dell'icona devono essere 36 x 36 px.
chat-title Obbligatorio Titolo visualizzato nella parte superiore della finestra di dialogo della chat. Il campo viene precompilato con il nome dell'agente.
expand Facoltativo Attributo booleano che imposta l'apertura della finestra di dialogo della chat al caricamento della pagina. Per impostazione predefinita, la finestra di dialogo della chat si chiude al caricamento della pagina.
intent Facoltativo L'evento utilizzato per attivare il primo intent all'apertura della finestra di dialogo della chat. Il campo viene precompilato con l'evento WELCOME.
language-code Obbligatorio Codice lingua predefinito per il primo intent. Il campo viene precompilato con la lingua predefinita dell'agente.
session-id Facoltativo Un ID sessione. Se non viene specificato, l'integrazione genererà un ID univoco per ogni finestra di dialogo della chat.
user-id Facoltativo Può essere utilizzato per monitorare un utente tra sessioni. Puoi passare il valore a Dialogflow tramite il campo queryParams.payload.userId in una richiesta di rilevamento dell'intent.
wait-open Facoltativo Attributo booleano che ritarda l'evento di benvenuto fino all'effettiva apertura della finestra di dialogo.

Personalizzazioni CSS

Puoi personalizzare lo stile della finestra di dialogo della chat impostando le variabili CSS.

Puoi fornire le seguenti variabili CSS:

Variabile CSS Proprietà interessata
df-messenger-bot-message Colore di sfondo delle bolle per i messaggi dell'agente.
df-messenger-button-titlebar-color Colore del pulsante mobile e della barra del titolo della finestra di dialogo della chat.
df-messenger-button-titlebar-font-color Colore del carattere per il titolo nella barra del titolo.
df-messenger-chat-background-color Colore di sfondo della finestra di dialogo di chat.
df-messenger-font-color Colore del carattere per i messaggi.
df-messenger-input-box-color Colore di sfondo per la casella di immissione del testo.
df-messenger-input-font-color Colore del carattere per la casella di immissione del testo.
df-messenger-input-placeholder-font-color Colore carattere per il testo segnaposto nella casella di immissione di testo.
df-messenger-minimized-chat-close-icon-color Colore dell'icona di chiusura nella visualizzazione della chat chiusa.
df-messenger-send-icon Colore dell'icona di invio nella casella di immissione del testo.
df-messenger-user-message Colore di sfondo delle bolle per i messaggi degli utenti.

Esempio di codice:

<style>
  df-messenger {
   --df-messenger-bot-message: #878fac;
   --df-messenger-button-titlebar-color: #df9b56;
   --df-messenger-chat-background-color: #fafafa;
   --df-messenger-font-color: white;
   --df-messenger-send-icon: #878fac;
   --df-messenger-user-message: #479b3d;
  }
</style>

Le impostazioni precedenti si tradurranno in:

Screenshot di Messenger

Eventi JavaScript

Dialogflow Messenger attiva una serie di eventi per cui puoi creare ascoltatori di eventi.

Il target evento per questi eventi è l'elemento df-messenger.

Per aggiungere un listener di eventi per l'elemento df-messenger, aggiungi il seguente codice JavaScript, dove event-type è uno dei nomi di eventi descritti di seguito:

const dfMessenger = document.querySelector('df-messenger');
dfMessenger.addEventListener('event-type', function (event) {
  // Handle event
  ...
});

Sono supportati i seguenti tipi di eventi:

df-accordion-clicked

Questo evento si verifica quando un utente fa clic su un elemento accordion. La struttura dell'evento è la seguente:

element: {
  title: string,
  subtitle: string,
  image: {
    src: {rawUrl: string}
  },
  text: string
}

df-button-clicked

Questo evento si verifica quando un utente fa clic su un pulsante. La struttura dell'evento è la seguente:

element: {
  icon: {
    type: string,
    color: string
  },
  text: string,
  link: string,
  event: EventInput,
  payload: {}
}

df-chip-clicked

Questo evento si verifica quando un utente seleziona un chip di suggerimento. La struttura dell'evento è la seguente:

query: string // Text of the suggestion chip that was selected.

df-info-card-clicked

Questo evento si verifica quando l'utente finale fa clic sull'elemento informativo nella barra del titolo. La struttura dell'evento è la seguente:

element: {
  title: string,
  image: {
    src: {rawUrl: string}
  },
  actionLink: string
}

df-list-element-clicked

Questo evento si verifica quando un utente fa clic su un articolo in un elenco. La struttura dell'evento è la seguente:

element: {
  title: string,
  subtitle: string,
  image: {
    src: {rawUrl}
  },
  event: {
    name: string,
    parameters: {},
    languageCode: string
  },
  payload: {}
}

df-messenger-error

Questo evento si verifica quando l'API Dialogflow invia un codice di stato di errore. La struttura dell'evento è la seguente:

error: {
  "error": {
    "code": <error_code>,
    "message": <error_message>,
    "status": <error_status>
  }
}

df-messenger-loaded

Questo evento viene attivato quando l'elemento df-messenger viene caricato e inizializzato completamente.

df-request-sent

Questo evento si verifica quando viene effettuata una richiesta all'API Dialogflow. Questo evento, insieme a df-response-received, può essere utilizzato per monitorare la latenza delle richieste. La struttura dell'evento è la seguente:

requestBody: {
  "queryParams": {
    object(QueryParameters)
  },
  "queryInput": {
    object(QueryInput)
  },
  "inputAudio": string
}

df-response-received

Questo evento si verifica quando viene ricevuta una risposta dall'API Dialogflow. La struttura dell'evento è la seguente:

response: detectIntentResponse

df-user-input-entered

Questo evento si verifica quando l'utente finale inserisce una query. La struttura dell'evento è la seguente:

input: string // Text entered by user

Funzioni JavaScript

L'elemento df-messenger fornisce funzioni che puoi chiamare per modificarne il comportamento.

renderCustomText

Questa funzione esegue il rendering di un semplice messaggio, come se provenisse da Dialogflow come semplice risposta.

Ad esempio:

const dfMessenger = document.querySelector('df-messenger');
dfMessenger.renderCustomText('Custom text');

renderCustomCard

Questa funzione esegue il rendering di una scheda personalizzata, come se provenisse da Dialogflow sotto forma di messaggio di risposta avanzato. Il formato della risposta del payload personalizzato è definito nella sezione Messaggi di risposta avanzati.

Ad esempio:

const dfMessenger = document.querySelector('df-messenger');
const payload = [
  {
    "type": "info",
    "title": "Info item title",
    "subtitle": "Info item subtitle",
    "image": {
      "src": {
        "rawUrl": "https://example.com/images/logo.png"
      }
    },
    "actionLink": "https://example.com"
  }];
dfMessenger.renderCustomCard(payload);

showMinChat

Questa funzione mostra una versione minima degli elenchi di messaggi.

Ad esempio:

const dfMessenger = document.querySelector('df-messenger');
dfMessenger.showMinChat();

Messaggi di risposta avanzati

Quando crei messaggi di risposta avanzati, puoi creare risposte di testo e payload personalizzati dalla scheda di risposta predefinita per l'intent. Le risposte testuali vengono usate per le risposte degli agenti di base, mentre i payload personalizzati vengono usati per le risposte avanzate. Il formato payload personalizzato per tutti i tipi di risposta ha la seguente struttura di base:

{
  "richContent": [
    [
      {
        "type": "type-id",
        ...
      },
      {
        "type": "type-id",
        ...
      }
    ],
    [
      {
        "type": "type-id",
        ...
      },
      {
        "type": "type-id",
        ...
      }
    ]
  ]
}

Tieni presente che il valore richContent consente un array esterno e più array interni. Le risposte all'interno di un array interno sono associate in un'unica scheda visiva. Quando l'array esterno contiene più array interni, vengono mostrate più schede, una per ogni array interno.

Le restanti sottosezioni descrivono i vari tipi di risposte che è possibile configurare per un payload personalizzato.

Tipo di risposta alle informazioni

Il tipo di risposta informativa è un semplice intertitolo su cui gli utenti possono fare clic o toccare.

Screenshot di Messenger

Nella tabella seguente vengono descritti i campi:

Nome Tipo Descrizione
type string Tipo di risposta: "informazioni"
title string Titolo della scheda
subtitle string Sottotitolo della scheda
image oggetto Immagine
image.src oggetto Origine immagine
image.src.rawUrl string URL pubblico dell'immagine
actionLink string URL da seguire quando un utente fa clic sulla scheda

Ad esempio:

{
  "richContent": [
    [
      {
        "type": "info",
        "title": "Info item title",
        "subtitle": "Info item subtitle",
        "image": {
          "src": {
            "rawUrl": "https://example.com/images/logo.png"
          }
        },
        "actionLink": "https://example.com"
      }
    ]
  ]
}

Tipo di risposta della descrizione

Il tipo di risposta alla descrizione è una scheda informativa con più righe di testo.

Screenshot di Messenger

Nella tabella seguente vengono descritti i campi:

Nome Tipo Descrizione
type string Tipo di risposta: "descrizione"
title string Titolo della scheda
text array<stringa> Array di stringhe, in cui ogni stringa viene visualizzata su una nuova riga

Ad esempio:

{
  "richContent": [
    [
      {
        "type": "description",
        "title": "Description title",
        "text": [
          "This is text line 1.",
          "This is text line 2."
        ]
      }
    ]
  ]
}

Tipo di risposta dell'immagine

Il tipo di risposta dell'immagine è una scheda dell'immagine su cui gli utenti possono fare clic o toccare.

Screenshot di Messenger

Nella tabella seguente vengono descritti i campi:

Nome Tipo Descrizione
type string Tipo di risposta: "immagine"
rawUrl string URL pubblico dell'immagine
accessibilityText string Testo alternativo per l'immagine

Ad esempio:

{
  "richContent": [
    [
      {
        "type": "image",
        "rawUrl": "https://example.com/images/logo.png",
        "accessibilityText": "Example logo"
      }
    ]
  ]
}

Tipo di risposta del pulsante

Il tipo di risposta del pulsante è un piccolo pulsante con un'icona su cui gli utenti possono fare clic o toccare.

Screenshot di Messenger

Nella tabella seguente vengono descritti i campi:

Nome Tipo Descrizione
type string Tipo di risposta: "pulsante"
icon oggetto Icona del pulsante
icon.type string Icona della raccolta di icone dei materiali. L'icona predefinita è una freccia
icon.color string Codice esadecimale del colore
text string Testo del pulsante
link string URL da seguire quando si fa clic sul pulsante
event oggetto Evento Dialogflow che viene attivato quando si fa clic sul pulsante, consulta il riferimento REST EventInput

Ad esempio:

{
  "richContent": [
    [
      {
        "type": "button",
        "icon": {
          "type": "chevron_right",
          "color": "#FF9800"
        },
        "text": "Button text",
        "link": "https://example.com",
        "event": {
          "name": "",
          "languageCode": "",
          "parameters": {}
        }
      }
    ]
  ]
}

Elenca tipo di risposta

Il tipo di risposta dell'elenco è una scheda con più opzioni tra cui gli utenti possono scegliere.

Screenshot di Messenger

La risposta contiene un array di tipi di risposta list e divider. La tabella seguente descrive il tipo list:

Nome Tipo Descrizione
type string Tipo di risposta: "elenco"
title string Titolo opzione
subtitle string Sottotitolo opzione
event oggetto Evento Dialogflow che viene attivato quando viene fatto clic sull'opzione, consulta il riferimento REST EventInput

La tabella seguente descrive il tipo divider:

Nome Tipo Descrizione
type string Tipo di risposta: "divisore"

Ad esempio:

{
  "richContent": [
    [
      {
        "type": "list",
        "title": "List item 1 title",
        "subtitle": "List item 1 subtitle",
        "event": {
          "name": "",
          "languageCode": "",
          "parameters": {}
        }
      },
      {
        "type": "divider"
      },
      {
        "type": "list",
        "title": "List item 2 title",
        "subtitle": "List item 2 subtitle",
        "event": {
          "name": "",
          "languageCode": "",
          "parameters": {}
        }
      }
    ]
  ]
}

Tipo di risposta ad accordion

Il tipo di risposta accordion è una piccola scheda su cui l'utente può fare clic o toccare per espanderla e visualizzare altro testo.

Screenshot di Messenger

Nella tabella seguente vengono descritti i campi:

Nome Tipo Descrizione
type string Tipo di risposta: "accordion"
title string Titolo Accordion
subtitle string Sottotitolo Accordion
image oggetto Immagine
image.src oggetto Origine immagine
image.src.rawUrl string URL pubblico dell'immagine
text string Testo Accordion

Ad esempio:

{
  "richContent": [
    [
      {
        "type": "accordion",
        "title": "Accordion title",
        "subtitle": "Accordion subtitle",
        "image": {
          "src": {
            "rawUrl": "https://example.com/images/logo.png"
          }
        },
        "text": "Accordion text"
      }
    ]
  ]
}

Tipo di risposta del chip di suggerimento

Il tipo di risposta del chip di suggerimento fornisce all'utente finale un elenco di chip di suggerimenti cliccabili.

Screenshot di Messenger

Nella tabella seguente vengono descritti i campi:

Nome Tipo Descrizione
type string Tipo di risposta: "chip"
options array<object> Array di oggetti Opzione
options[].text string Testo opzione
options[].image oggetto Immagine opzione
options[].image.src oggetto Origine immagine opzione
options[].image.src.rawUrl string URL pubblico opzione per l'immagine
options[].link string Link opzione

Ad esempio:

{
  "richContent": [
    [
      {
        "type": "chips",
        "options": [
          {
            "text": "Chip 1",
            "image": {
              "src": {
                "rawUrl": "https://example.com/images/logo.png"
              }
            },
            "link": "https://example.com"
          },
          {
            "text": "Chip 2",
            "image": {
              "src": {
                "rawUrl": "https://example.com/images/logo.png"
              }
            },
            "link": "https://example.com"
          }
        ]
      }
    ]
  ]
}

Combinare i tipi di risposta

I singoli elementi di messaggi avanzati per Dialogflow Messenger possono essere utilizzati per creare una scheda personalizzata in base alle tue esigenze. Ecco un esempio utilizzando alcuni degli elementi sopra elencati:

Screenshot di Messenger

{
  "richContent": [
    [
      {
        "type": "image",
        "rawUrl": "https://example.com/images/logo.png",
        "accessibilityText": "Dialogflow across platforms"
      },
      {
        "type": "info",
        "title": "Dialogflow",
        "subtitle": "Build natural and rich conversational experiences",
        "actionLink": "https://cloud.google.com/dialogflow/docs"
      },
      {
        "type": "chips",
        "options": [
          {
            "text": "Case Studies",
            "link": "https://cloud.google.com/dialogflow/case-studies"
          },
          {
            "text": "Docs",
            "link": "https://cloud.google.com/dialogflow/docs"
          }
        ]
      }
    ]
  ]
}

Debug

Per testare l'agente con Dialogflow Messenger in locale:

  • Incorpora l'elemento Dialogflow Messenger in una pagina come descritto sopra.
  • Avvia un server HTTP locale per quella pagina con una porta specifica.
  • Accedi alla pagina all'indirizzo http://localhost:port_number.