Inviare messaggi di Google Chat

Questa pagina spiega come le app Google Chat possono inviare messaggi per rispondere alle interazioni degli utenti.

  • Modulo di contatto dal comando slash.
    Figura 1. Un'app di chat risponde a un comando slash con un messaggio di testo e un pulsante.
  • Modulo di contatto in una finestra di dialogo.
    Figura 2. Un'app di chat apre una finestra di dialogo in cui gli utenti possono inserire informazioni.
  • Messaggio della scheda con widget di input del modulo.
    Figura 5. Un'app Chat invia un messaggio con testo e una scheda interattiva.

Prerequisiti

Node.js

Un componente aggiuntivo di Google Workspace che estende Google Chat. Per crearne uno, completa la guida rapida HTTP.

Apps Script

Un componente aggiuntivo di Google Workspace che estende Google Chat. Per crearne uno, completa la guida rapida di Apps Script.

Progetta il messaggio

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

  • Testo contenente link ipertestuali, @menzioni ed emoji.
  • Una o più schede, che possono essere visualizzate in un messaggio o aperte in una nuova finestra come finestra di dialogo.
  • Uno o più widget accessori, ovvero pulsanti che vengono visualizzati dopo qualsiasi testo o scheda in un messaggio.

Per informazioni sulla progettazione dei messaggi, consulta la seguente documentazione dell'API Google Chat:

Rispondi con un messaggio

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

  • Trigger di 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.
  • Clic sui pulsanti delle schede nei messaggi o nelle finestre di dialogo. Ad esempio, quando gli utenti inseriscono informazioni e fanno clic su Invia.

In caso contrario, le app di chat possono inviare messaggi in modo proattivo chiamando l'API Google Chat.

Per rispondere con un messaggio, restituisci l'azione DataActions con un oggetto CreateMessageAction:

{ "hostAppDataAction": { "chatDataAction": { "createMessageAction": {
  "message": MESSAGE
}}}

Sostituisci MESSAGE con una risorsa Message dell'API Chat. Per scoprire di più su come funzionano le azioni, consulta Azioni di chat.

Nell'esempio seguente, un'app di chat crea e invia un messaggio di testo ogni volta che viene aggiunta a uno spazio. Per inviare un messaggio di testo quando un utente aggiunge la tua app Chat a uno spazio, la tua app Chat risponde al trigger Aggiunta allo spazio restituendo l'azione DataActions:

Node.js

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The request object from Google Workspace add-on.
 * @param {Object} res The response object from the Chat app. An onboarding message that
 *                     introduces the app and helps people get started with it.
 */
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`.'
    }}}}});
  }
};

Apps Script

/**
 * 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. An onboarding message that
 *                  introduces the app and helps people get started with it.
 */
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`.'
  }}}}};
}

Il codice campione restituisce il seguente messaggio di testo:

Messaggio di onboarding di esempio.

Per altri esempi di come rispondere con un messaggio, consulta le seguenti guide:

Aggiornare un messaggio

Le app di chat possono anche aggiornare i messaggi che inviano. Ad esempio, per aggiornare un messaggio dopo che un utente ha inviato una finestra di dialogo o fatto clic su un pulsante un messaggio.

Per aggiornare un messaggio dell'app Chat, restituisci l'azione DataActions con un UpdateMessageAction, come mostrato nell'esempio seguente:

{ "hostAppDataAction": { "chatDataAction": { "updateMessageAction": {
  "message": MESSAGE
}}}}

Sostituisci MESSAGE con una risorsa Message dell'API Chat.

Per scoprire di più su come funzionano le azioni, consulta Azioni di chat.

Le app di chat possono anche aggiornare un messaggio di un utente per restituire un'anteprima di un link che ha inviato. Per maggiori dettagli, vedi Visualizzare l'anteprima dei link nei messaggi di Google Chat.

Rispondere alle interazioni o inviare messaggi proattivi utilizzando l'API Google Chat

Anziché restituire un'azione del componente aggiuntivo, le app di chat potrebbero dover utilizzare l'API Google Chat per rispondere a un&#x0D> 'interazione. Ad esempio, le app Chat devono chiamare l'API Google Chat per eseguire una delle seguenti operazioni:

  • Invia messaggi in base a una pianificazione o in merito a modifiche alle risorse esterne. Ad esempio, notifiche relative a un nuovo problema o una nuova richiesta.
  • Rispondere più di 30 secondi dopo l'interazione. Ad esempio, per rispondere con un messaggio dopo aver completato un'attività di lunga durata.
  • Invia un messaggio al di fuori dello spazio in cui si è svolta l'interazione.
  • Inviare un messaggio per conto di un utente di Chat.

Per inviare un messaggio utilizzando l'API Chat, devi configurare l'autenticazione e chiamare il metodo create() sulla risorsa Message. Per una descrizione dei passaggi, vedi Inviare un messaggio utilizzando l'API Google Chat.