Ricevere e rispondere alle interazioni degli utenti

Questa pagina descrive come la tua app Google Chat può ricevere e rispondere alle interazioni degli utenti in Google Chat.

Per creare interfacce interattive per le app di chat, utilizza i seguenti componenti:

• Trigger: i modi in cui gli utenti di Google Chat possono richiamare un'app di Chat, ad esempio aggiungendola a uno spazio o inviandole un messaggio.
• Oggetti evento: i dati che le app di chat ricevono da trigger o interazioni con la UI.
• Azioni: i modi in cui le app di chat possono rispondere alle interazioni, ad esempio inviando messaggi o restituendo un'interfaccia utente basata su schede.

Le app di chat possono creare e visualizzare interfacce nei seguenti modi:

• Messaggi che possono contenere testo, schede statiche o interattive e pulsanti degli accessori.
• Home page (Home app) che vengono visualizzate nella scheda Home dei messaggi diretti 1:1 con l'app Chat.
• Finestre di dialogo, ovvero schede che si aprono in una nuova finestra e in genere chiedono agli utenti di inviare informazioni.
• Anteprime dei link, ovvero schede che mostrano in anteprima informazioni su un servizio esterno.

Prerequisiti

• Un account Google Workspace Business o Enterprise con accesso a Google Chat.
• Crea un progetto Google Cloud.
• Configura la schermata per il consenso OAuth.
• Abilita e configura l'API Google Chat.

Come funzionano le interazioni utente

Quando un utente interagisce con un'app Chat, Google Chat richiama un trigger configurato e invia un oggetto evento all'endpoint o alla funzione dell'app Chat. L'app di chat elabora l'oggetto evento e può restituire un'azione in modo sincrono entro 30 secondi o rispondere in modo asincrono utilizzando l'API Chat.

Il seguente diagramma mostra come le app Google Chat elaborano e rispondono alle interazioni degli utenti:

Trigger

I trigger sono i modi specifici in cui gli utenti richiamano un'app Chat utilizzando l'interfaccia utente di Chat, ad esempio utilizzando @menzioni o comandi dell'app.

La tabella seguente mostra i trigger di chat, una descrizione e la risposta tipica delle app di chat:

Configura gli endpoint o le funzioni di callback per questi trigger nella console Google Cloud nella pagina Configurazione dell'API Chat. Per istruzioni passo passo, vedi Configurare l'API Google Chat.

Configurare i prompt iniziali

I prompt iniziali aiutano gli utenti a scoprire le funzionalità della tua app Chat quando aprono un messaggio diretto 1:1 vuoto con la tua app. Puoi configurare fino a tre prompt iniziali.

Per aggiungere e configurare i prompt iniziali:

1. Nella console Google Cloud, vai alla pagina Configurazione dell'API Chat:

   Vai alla pagina di configurazione dell'API Chat

2. Nella sezione Funzionalità interattive, individua Prompt iniziali e fai clic su Aggiungi un prompt.

3. Nel campo Ranking (1-3), inserisci un numero da 1 a 3 per specificare l'ordine di visualizzazione.

4. In Selezione del tipo, scegli il comportamento della richiesta:

   • Prompt testuale: compila la barra di scrittura con un testo predefinito quando l'utente fa clic sul chip di prompt.
   • Prompt dei comandi: esegue un comando slash o un comando rapido registrato quando viene selezionato. Non è possibile selezionare i comandi che richiedono argomenti aggiuntivi.

5. Configura il prompt in base al tipo selezionato:

   • Se hai selezionato Prompt di testo:

     1. In Titolo, inserisci il titolo del prompt visualizzato nel chip (fino a 30 caratteri).
     2. In Testo del prompt, inserisci il testo compilato nella barra di scrittura (fino a 60 caratteri).
     3. (Facoltativo) Aggiungi titoli e testo localizzati per gli utenti in altre lingue:
     4. Nella sezione Prompt localizzati, fai clic su Aggiungi una lingua.
     5. In Lingua, seleziona una lingua supportata dal menu a discesa.
     6. In Titolo localizzato, inserisci il titolo localizzato (fino a 30 caratteri).
     7. In Testo del prompt localizzato, inserisci il testo del prompt localizzato (fino a 60 caratteri).
     8. Ripeti la procedura per aggiungere altre lingue, se necessario.

   • Se hai selezionato Prompt dei comandi:

     1. In Comando slash / Comando rapido, seleziona il comando dal menu a discesa.

6. Fai clic su Fine e poi su Salva in fondo alla pagina.

Gestire i nuovi tentativi di chiamata HTTP al servizio

Se una richiesta HTTPS al tuo servizio non va a buon fine (ad esempio un timeout, un errore di rete temporaneo o un codice di stato HTTPS non 2xx), Google Chat potrebbe riprovare a inviare la richiesta alcune volte entro pochi minuti (ma non è garantito). Di conseguenza, in determinate situazioni, un'app di chat potrebbe ricevere lo stesso evento più volte. Se la richiesta viene completata correttamente, ma restituisce un payload di risposta non valido, Google Chat non riprova a inviare la richiesta.

Oggetti evento

Le app di chat ricevono oggetti evento quando viene eseguito un trigger di Chat o quando gli utenti di Chat interagiscono con un'interfaccia utente dell'app Chat (ad esempio facendo clic su un pulsante o inviando una finestra di dialogo). L'oggetto evento ti consente di utilizzare i dati di interazione per rispondere o aggiornare un'interfaccia utente.

Payload degli oggetti evento

Ogni oggetto evento Chat include un commonEventObject con i dettagli di host e piattaforma (hostApp: "CHAT", clientPlatform, userLocale, userTimezone, parameters e formInputs) e un oggetto chat contenente il contesto specifico di Chat:

• Per un trigger Home app (quando un utente apre la scheda Home in un messaggio diretto 1:1 con l'app Chat), l'oggetto chat contiene chat.user e chat.eventTime senza un campo payload unione. Quando un utente fa clic su un pulsante nella scheda della home page, l'oggetto evento include chat.buttonClickedPayload insieme a commonEventObject.parameters (e commonEventObject.formInputs se la scheda contiene input del modulo).
• Per le interazioni con spazi e messaggi (Aggiunto allo spazio, Messaggio, Rimosso dallo spazio, Comando app o interazioni con pulsanti e widget), l'oggetto chat include chat.user, chat.space, chat.eventTime e il payload di interazione corrispondente:
  • messagePayload: contiene space, message e configCompleteRedirectUri quando un utente invia un messaggio.
  • addedToSpacePayload: contiene space, interactionAdd e configCompleteRedirectUri quando l'app Chat viene aggiunta a uno spazio.
  • removedFromSpacePayload: contiene space quando l'app Chat viene rimossa da uno spazio.
  • buttonClickedPayload: contiene space, message, isDialogEvent e dialogEventType quando un utente fa clic su un pulsante di una scheda o di una finestra di dialogo.
  • widgetUpdatedPayload: contiene space quando un utente interagisce con un widget, ad esempio quando digita in un menu a selezione multipla con un'origine dati esterna.
  • appCommandPayload: contiene space, message, appCommandMetadata, isDialogEvent, dialogEventType e configCompleteRedirectUri quando un utente richiama un comando dell'app.

Per scoprire di più sugli oggetti evento dei componenti aggiuntivi in Chat e in altre applicazioni Google Workspace, consulta Oggetti evento.

Fornire una risposta

Questa sezione spiega come le app di chat utilizzano le azioni per rispondere in modo sincrono alle interazioni degli utenti.

Per rispondere con un'azione, un'app di chat deve rispondere entro 30 secondi e la risposta deve essere applicata allo spazio in cui si è verificata l'interazione. Queste risposte sincrone non richiedono autenticazione. Se la tua app di Chat ha bisogno di più di 30 secondi o deve agire al di fuori dello spazio, configura l'autenticazione e rispondi in modo asincrono utilizzando l'API Google Chat.

Per rispondere in modo sincrono alle interazioni degli utenti, la tua app di chat gestisce l'oggetto evento in entrata e restituisce uno dei seguenti oggetti JSON:

• DataActions: crea o aggiorna messaggi chat (CreateMessageAction, UpdateMessageAction) o allega anteprime dei link (UpdateInlinePreviewAction) utilizzando chatDataActionMarkup.
• RenderActions: crea, aggiorna o chiude una home page o una finestra di dialogo (pushCard, updateCard, endNavigation: "CLOSE_DIALOG") oppure fornisce suggerimenti di input dinamici per un menu a selezione multipla (modifyCard).
• AuthorizationError: Chiede agli utenti con una scheda di autorizzazione di base (basic_authorization_prompt) di accedere o autenticarsi a un servizio esterno.

La seguente tabella mostra come le app di chat possono rispondere con azioni. Le app di chat possono restituire direttamente oggetti JSON o creare la risposta utilizzando AddOnResponseService e CardService di Apps Script.

Rispondi con un messaggio

Le app di chat possono rispondere con un messaggio a uno qualsiasi dei seguenti trigger o interazioni:

• Trigger dei messaggi, ad esempio quando gli utenti menzionano @o inviano un messaggio diretto a un'app di chat.
• Trigger Aggiunto allo spazio, ad esempio quando gli utenti installano l'app Chat da Google Workspace Marketplace o la aggiungono a uno spazio.
• Trigger dei comandi dell'app, ad esempio quando gli utenti richiamano un comando slash o un comando rapido.
• Clic sui pulsanti delle schede nei messaggi o nelle finestre di dialogo. Ad esempio, quando gli utenti inseriscono informazioni e fanno clic su Invia.

Le app di chat possono includere uno dei seguenti elementi in un messaggio:

• Testo che contiene link ipertestuali, @menzioni ed emoji. Vedi Formattazione dei messaggi.
• Una o più schede, che possono essere visualizzate in un messaggio o aperte in una nuova finestra come dialogo. Vedi Creare schede per le app Google Chat.
• Uno o più widget di accessori, ovvero pulsanti che vengono visualizzati dopo qualsiasi testo o scheda in un messaggio.

Per rispondere con un messaggio, restituisci DataActions con un oggetto CreateMessageAction:

{
  "hostAppDataAction": {
    "chatDataAction": {
      "createMessageAction": {
        "message": <var>MESSAGE</var>
      }
    }
  }
}

Sostituisci MESSAGE con una risorsa Message dell'API Chat.

Nell'esempio seguente, un'app Chat crea e invia un messaggio di testo di onboarding ogni volta che viene aggiunta a uno spazio rispondendo al trigger Aggiunta allo spazio con DataActions:

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The request object from Google Chat.
 * @param {Object} res The response object from the Chat app.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  const chatEvent = req.body.chat;
  // Send an onboarding message when added to a Chat space
  if (chatEvent.addedToSpacePayload) {
    res.json({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
      text: 'Hi, Cymbal at your service. I help you manage your calendar ' +
        'from Google Chat. Take a look at your schedule today by typing ' +
        '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. ' +
        'To learn what else I can do, type `/help`.'
    }}}}});
  }
};

from flask import Flask, request, json
app = Flask(__name__)

@app.route('/', methods=['POST'])
def cymbal_app():
  """Sends an onboarding message when the Chat app is added to a space.

  Returns:
    Mapping[str, Any]: The response object from the Chat app.
  """
  chat_event = request.get_json()["chat"]
  if "addedToSpacePayload" in chat_event:
    return json.jsonify({ "hostAppDataAction": { "chatDataAction": {
      "createMessageAction": { "message": {
        "text": 'Hi, Cymbal at your service. I help you manage your calendar ' +
        'from Google Chat. Take a look at your schedule today by typing ' +
        '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. ' +
        'To learn what else I can do, type `/help`.'
      }}
    }}})

@SpringBootApplication
@RestController
public class App {
  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /*
   * Sends an onboarding message when the Chat app is added to a space.
   *
   * @return The response object from the Chat app.
   */
  @PostMapping("/")
  @ResponseBody
  public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
    JsonNode chatEvent = event.at("/chat");
    if (!chatEvent.at("/addedToSpacePayload").isEmpty()) {
      return new GenericJson() { {
        put("hostAppDataAction", new GenericJson() { {
          put("chatDataAction", new GenericJson() { {
            put("createMessageAction", new GenericJson() { {
              put("message", new Message().setText(
                "Hi, Cymbal at your service. I help you manage your calendar " +
                "from Google Chat. Take a look at your schedule today by typing " +
                "`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. " +
                "To learn what else I can do, type `/help`."
              ));
            } });
          } });
        } });
      } };
    }
    return new GenericJson();
  }
}

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Google Chat.
 * @return {Object} Response from the Chat app.
 */
function onAddedToSpace(event) {
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: 'Hi, Cymbal at your service. I help you manage your calendar ' +
          'from Google Chat. Take a look at your schedule today by typing ' +
          '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. ' +
          'To learn what else I can do, type `/help`.'
  }}}}};
}

L'esempio di codice restituisce il seguente messaggio:

Aggiornare un messaggio

Le app di chat possono anche aggiornare i messaggi che inviano. Ad esempio, un'app di chat può aggiornare un messaggio dopo che un utente invia una finestra di dialogo o fa clic su un pulsante su una scheda in un messaggio.

Per aggiornare un messaggio dell'app di chat in risposta a un'interazione, restituisci DataActions con un UpdateMessageAction:

{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateMessageAction": {
        "message": <var>MESSAGE</var>
      }
    }
  }
}

Sostituisci MESSAGE con una risorsa Message dell'API Chat.

Le app di chat possono anche aggiornare un messaggio inviato da un utente per allegare una scheda di anteprima del link utilizzando updateInlinePreviewAction. Per maggiori dettagli, vedi Anteprima dei link.

Rispondere in modo asincrono utilizzando l'API Google Chat

Anziché restituire un'azione in modo sincrono, le app di Chat potrebbero dover chiamare l'API Google Chat per rispondere a un'interazione o inviare messaggi proattivi. Ad esempio, le app di chat devono chiamare l'API Google Chat per eseguire una delle seguenti operazioni:

• Rispondere a un'interazione dopo 30 secondi (ad esempio dopo aver completato un'attività a esecuzione prolungata).
• Invia messaggi in base a una pianificazione o notifiche relative a modifiche apportate a risorse esterne.
• Eseguire attività al di fuori dello spazio in cui si è svolta l'interazione.
• Eseguire in Chat attività non disponibili come azioni sincrone, ad esempio elencare gli spazi o aggiungere membri a uno spazio.
• Eseguire attività per conto di un utente di Chat (che richiede l'autenticazione dell'utente).

Quando rispondi a un'interazione dopo 30 secondi, per evitare che l'utente visualizzi un messaggio di errore rivolto agli utenti che indica che la tua app Chat non risponde, devi confermare la ricezione dell'oggetto evento entro 30 secondi restituendo una risposta vuota:

async function onEvent(req, res) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return res.send({});
};

def on_event(event) -> dict:
  # Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return {}

public String onEvent(JsonNode event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return "{}";
}

function onEvent(event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return null;
}

Per inviare un messaggio utilizzando l'API Chat, configura l'autenticazione e chiama il metodo spaces.messages.create. Per la procedura, vedi Inviare un messaggio. Per guide sull'utilizzo di metodi API Chat aggiuntivi, consulta la panoramica dell'API Chat.

Argomenti correlati

• Configurare l'API Google Chat
• Invia un messaggio
• Rispondere ai comandi
• Aprire finestre di dialogo interattive
• Leggere i dati inseriti dagli utenti nei moduli sulle schede
• Link di anteprima
• Creare una home page per un'app di chat
• Verifica le richieste di Chat
• Testare le funzionalità interattive per le app Google Chat

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The event object from Chat API.
 * @param {Object} res The response object from the Chat app.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  // Send an onboarding message when added to a Chat space
  if (req.body.type === 'ADDED_TO_SPACE') {
    res.json({
      'text': 'Hi, Cymbal at your service. I help you manage your calendar ' +
        'from Google Chat. Take a look at your schedule today by typing ' +
        '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To ' +
        'learn what else I can do, type `/help`.'
    });
  }
};

from flask import Flask, request, json
app = Flask(__name__)

@app.route('/', methods=['POST'])
def cymbal_app():
  """Sends an onboarding message when the Chat app is added to a space.

  Returns:
    Mapping[str, Any]: The response object from the Chat app.
  """
  event = request.get_json()
  if event['type'] == 'ADDED_TO_SPACE':
    return json.jsonify({
      'text': 'Hi, Cymbal at your service. I help you manage your calendar ' +
      'from Google Chat. Take a look at your schedule today by typing ' +
      '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To ' +
      'learn what else I can do, type `/help`.'
    })
  return json.jsonify({})

@SpringBootApplication
@RestController
public class App {
  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /*
   * Sends an onboarding message when the Chat app is added to a space.
   *
   * @return The response object from the Chat app.
   */
  @PostMapping("/")
  @ResponseBody
  public Message onEvent(@RequestBody JsonNode event) {
    switch (event.get("type").asText()) {
      case "ADDED_TO_SPACE":
        return new Message().setText(
          "Hi, Cymbal at your service. I help you manage your calendar " +
          "from Google Chat. Take a look at your schedule today by typing " +
          "`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. " +
          "To learn what else I can do, type `/help`.");
      default:
        return new Message();
    }
  }
}

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onAddToSpace(event) {
  return {
    'text': 'Hi, Cymbal at your service. I help you manage your calendar ' +
      'from Google Chat. Take a look at your schedule today by typing ' +
      '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn ' +
      'what else I can do, type `/help`.'
  };
}