Inviare messaggi di Google Chat

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

In Google Chat, i componenti aggiuntivi vengono visualizzati dagli utenti come app Google Chat. Per saperne di più, consulta la panoramica di Estensione di Google Chat.

Prerequisiti

Progettare il messaggio

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

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

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

• Panoramica della messaggistica
• Formattare i messaggi
• Creare schede per le app Google Chat
• Aggiungere testo e immagini alle schede
• Aggiungere elementi interattivi della UI alle schede

Rispondi con un messaggio

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

• Attivatori dei messaggi, ad esempio quando gli utenti menzionano o inviano un messaggio diretto a un'app di chat.
• L'azione Aggiunta allo spazio si attiva, ad esempio quando gli utenti installano l'app Chat da Google Workspace Marketplace o la aggiungono a uno spazio.
• Clic sui pulsanti delle schede in messaggi o 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ù sul funzionamento delle azioni, consulta Azioni di Chat.

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

/**
 * 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`.'
    }}}}});
  }
};

/**
 * 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`.'
  }}}}};
}

L'esempio di codice restituisce il seguente messaggio:

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

• Rispondere ai comandi slash
• Aprire finestre di dialogo interattive
• Raccogliere informazioni dagli utenti di Google Chat

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 in un messaggio.

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

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

Sostituisci MESSAGE con una risorsa Message dell'API Chat.

Per scoprire di più sul funzionamento delle azioni, consulta Azioni di Chat.

Le app di chat possono anche aggiornare un messaggio inviato da 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' interazione. Ad esempio, le app di chat devono chiamare l'API Google Chat per eseguire una delle seguenti operazioni:

• Invia messaggi in base a una pianificazione o su modifiche a risorse esterne. Ad esempio, notifiche su 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à che richiede molto tempo.
• Inviare un messaggio al di fuori dello spazio in cui è avvenuta l'interazione.
• Invia 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 la procedura, consulta Inviare un messaggio utilizzando l'API Google Chat.

Argomenti correlati

• Creare interfacce di Google Chat
• Rispondere ai comandi slash
• Aprire finestre di dialogo interattive
• Raccogliere informazioni dagli utenti di Google Chat
• Visualizzare l'anteprima dei link nei messaggi di Google Chat
• Inviare un messaggio utilizzando l'API Google Chat