Tipi di eventi di interazione con l'app Google Chat

In questa pagina vengono descritti i tipi di eventi di interazione che l'app Google Chat può ricevere da Google Chat.

Per configurare l'app di chat in modo che riceva eventi di interazione, vedi Ricevere e rispondere alle interazioni con l'app Chat.

Formati per gli eventi di interazione

Gli utenti possono interagire con le app di chat in molti modi. Per ogni tipo di interazione, Google Chat invia un tipo diverso di evento di interazione:

  • Messaggio: un utente invia un messaggio all'app Chat o richiama l'app Chat in uno spazio.
  • Aggiunta allo spazio: un utente aggiunge la tua app Chat a uno spazio.
  • Rimossa dallo spazio: un utente rimuove la tua app Chat da uno spazio.
  • Scheda selezionata:un utente fa clic su una scheda interattiva o una finestra di dialogo inviata dall'app Chat.
  • Messaggio nella home page dell'app: un utente apre un messaggio diretto con un'app di Chat e riceve un messaggio con la home page dell'app Chat.
  • Invio modulo: un utente invia le informazioni del modulo tramite un messaggio Home dell'app di Chat

Ogni volta che un utente interagisce con la tua app di Chat, Google Chat invia un evento di interazione con un corpo della richiesta, che è un payload JSON che rappresenta l'interazione. Questo payload di eventi contiene elementi comuni a tutti i tipi di eventi di interazione, nonché elementi specifici per il tipo di evento.

Per scoprire di più sui campi in un evento di interazione, consulta la documentazione di riferimento di Event dell'API Google Chat.

Campi comuni

I seguenti campi vengono sempre forniti nel payload di un evento di interazione:

Tecnico Descrizione
type Il tipo di evento ricevuto dall'app di chat, ad esempio MESSAGE o ADDED_TO_SPACE.
eventTime Il timestamp che indica quando è stato inviato l'evento.
common Rappresenta le informazioni sul client dell'utente, come le impostazioni internazionali o la piattaforma.

Campi per tipo di evento di interazione

A seconda del tipo di evento, il payload potrebbe contenere i seguenti campi aggiuntivi:

Tecnico Descrizione Tipo di evento
message Il messaggio relativo all'evento. MESSAGE, ADDED_TO_SPACE, CARD_CLICKED.
space Lo spazio relativo all'evento. MESSAGE, ADDED_TO_SPACE, REMOVED_FROM_SPACE, CARD_CLICKED.
user L'utente correlato all'evento. L'utente è sempre una persona (non un'app di chat). MESSAGE, ADDED_TO_SPACE, REMOVED_FROM_SPACE, CARD_CLICKED.
action La funzione attivata da un utente quando fa clic su una scheda o una finestra di dialogo interattiva. CARD_CLICKED.

Payload evento di esempio

Questa sezione descrive cosa attiva un evento di interazione e fornisce un payload JSON di esempio per ciascuno dei seguenti tipi di eventi:

Messaggio

Questo evento di interazione rappresenta quando una persona invia un messaggio all'app Chat, ad esempio:

  • Qualsiasi messaggio in uno spazio di messaggi diretti con l'app Chat.
  • Un messaggio in uno spazio per più persone in cui una persona @menziona l'app Chat o utilizza uno dei comandi slash.
  • Se hai configurato le anteprime dei link per la tua app Chat, un utente pubblica un messaggio contenente un link che corrisponde al pattern URL configurato.

Il seguente esempio JSON mostra un evento di interazione MESSAGE in cui un utente @menziona un'app di Chat in uno spazio con più persone:

{
  "type": "MESSAGE",
  "eventTime": {
      "seconds": 1691187414,
      "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "displayName": "Customer Support Superstars",
    "spaceType": "SPACE"
  },
  "message": {
    "name": "spaces/AAAAAAAAAAA/messages/CCCCCCCCCCC",
    "sender": {
      "name": "users/12345678901234567890",
      "displayName": "Izumi",
      "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
      "email": "izumi@example.com"
    },
    "createTime": {
      "seconds": 1691187386,
      "nanos": 954319000
    },
    "text": "@TestBot Create ticket.",
    "argumentText": " Create ticket.",
    "thread": {
      "name": "spaces/AAAAAAAAAAA/threads/BBBBBBBBBBB",
      "threadKey": "custom-thread-ID"
    },
    "annotations": [
      {
        "length": 8,
        "startIndex": 0,
        "userMention": {
          "type": "MENTION",
          "user": {
            "avatarUrl": "https://.../avatar.png",
            "displayName": "TestBot",
            "name": "users/1234567890987654321",
            "type": "BOT"
          }
        },
        "type": "USER_MENTION"
      }
    ],
    "attachment": [
      {
        "name": "spaces/5o6pDgAAAAE/messages/Ohu1LlUVcS8.Ohu1LlUVcS8/attachments/AATUf-Iz7d8kySEdRRZd-dznqBk3",
        "content_name": "solar.png",
        "content_type": "image/png",
        "drive_data_ref": {
          "drive_file_id": "H1HqaqRuH2Pfd_TOa1fF2_ltwDlV_yKRrr"
        },
        "source": "DRIVE_FILE"
      }
    ]
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

Aggiunto allo spazio

Questo evento di interazione indica che l'app Chat è stata aggiunta a uno spazio. In genere le app rispondono a questo evento di interazione pubblicando un messaggio di benvenuto in un nuovo thread nello spazio.

Il seguente esempio JSON mostra il corpo della richiesta per un evento di interazione ADDED_TO_SPACE quando un utente aggiunge un'app di chat a uno spazio:

{
  "type": "ADDED_TO_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "displayName": "Customer Support Superstars",
    "spaceType": "SPACE",
    "adminInstalled": "false"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

Installata dagli amministratori di Google Workspace

L'evento di interazione ADDED_TO_SPACE può anche indicare che un amministratore di Google Workspace ha installato la tua app Chat per un utente della sua organizzazione.

Gli amministratori possono installare un'app di chat solo per i messaggi diretti tra l'app e l'utente. L'app installata viene visualizzata nel riquadro dei messaggi diretti degli utenti. Quando gli amministratori installano le app di chat, gli utenti non possono disinstallarle. Per saperne di più sulle app di Chat installate dagli amministratori, consulta la documentazione della Guida per amministratori di Google Workspace Installare le app del Marketplace nel dominio.

Il seguente esempio JSON mostra il corpo della richiesta per un evento di interazione ADDED_TO_SPACE quando un amministratore di Google Workspace installa un'app di Chat per un utente. Poiché un amministratore ha installato l'app di Chat, adminInstalled è impostato su true:

{
  "type": "ADDED_TO_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "displayName": "Customer Support Superstars",
    "spaceType": "DIRECT_MESSAGE",
    "adminInstalled": "true"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

Rimossa dallo spazio

Questo evento di interazione indica che l'app Chat è stata rimossa da uno spazio. Le app di chat non rispondono con messaggi a questo evento, perché sono già state rimosse.

Il seguente esempio JSON mostra il corpo della richiesta per un evento di interazione REMOVED_FROM_SPACE quando un utente rimuove un'app di Chat da uno spazio:

{
  "type": "REMOVED_FROM_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "spaceType": "SPACE",
    "adminInstalled": "false"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

Disinstallato dagli amministratori di Google Workspace

L'evento di interazione REMOVED_FROM_SPACE può anche indicare che un amministratore di Google Workspace ha disinstallato la tua app Chat per un utente della sua organizzazione. Una volta disinstallata, l'app Chat non viene più visualizzata nel riquadro dei messaggi diretti dell'utente.

Se un utente ha installato l'app di Chat prima dell'amministratore, l'app rimarrà installata per l'utente. In questo caso, poiché l'app Chat è ancora installata, non riceve un evento di interazione REMOVED_FROM_SPACE.

Il seguente esempio JSON mostra il corpo della richiesta per un evento di interazione REMOVED_FROM_SPACE quando un amministratore di Google Workspace disinstalla un'app di Chat per un utente. Poiché l'app Chat è stata disinstallata da un amministratore, adminInstalled è impostato su true:

{
  "type": "REMOVED_FROM_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "spaceType": "DIRECT_MESSAGE",
    "adminInstalled": "true"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

Carta selezionata

Questo evento di interazione indica che un utente ha fatto clic su un pulsante in un messaggio della scheda o in una finestra di dialogo.

Per ricevere un evento di interazione, il pulsante deve attivare un'altra interazione con l'app di Chat. Ad esempio, un'app di Chat non riceve un evento di interazione CARD_CLICKED se un utente fa clic su un pulsante che apre un link a un sito web, ma riceve eventi di interazione nei seguenti esempi:

  • L'utente fa clic su un pulsante Send feedback in una scheda, che apre una finestra di dialogo in cui può inserire informazioni.
  • L'utente fa clic su un pulsante Submit dopo aver inserito informazioni in una scheda o in una finestra di dialogo.

Il seguente esempio JSON mostra il corpo della richiesta per un evento di interazione CARD_CLICKED quando un utente fa clic su un pulsante in un messaggio della scheda che assegna un ticket di assistenza in arrivo:

{
  "type": "CARD_CLICKED",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "common": {
    "userLocale": "en",
    "hostApp": "CHAT",
    "invokedFunction": "doAssignTicket",
    "timeZone": {
      "offset": -25200000,
      "id": "America/Los_Angeles"
    }
  },
  "action": {
    "actionMethodName": "doAssignTicket"
  },
  "message": {
    "cards": [
      {
        "header": {
          "title": "Incoming support ticket."
        },
        "sections": [
          {
            "widgets": [
              {
                "textParagraph": {
                  "text": "Incoming support ticket #12345 is unassigned and needs your attention."
                }
              },
              {
                "buttons": [
                  {
                    "textButton": {
                      "onClick": {
                        "action": {
                          "actionMethodName": "doAssignTicket"
                        }
                      },
                      "text": "Assign to me"
                    }
                  }
                ]
              }
            ]
          }
        ]
      }
    ],
    "sender": {
      "avatarUrl": "https://www.example.com/images/chat-app-icon.png",
      "displayName": "Support Chat app",
      "name": "users/98765432109876543210",
      "type": "BOT"
    },
    "createTime": {
      "seconds": 1691187386,
      "nanos": 954319000
    },
    "retentionSettings": {
      "state": "PERMANENT"
    },
    "name": "spaces/AAAAAAAAAAA/messages/CCCCCCCCCCC",
    "thread": {
      "retentionSettings": {
        "state": "PERMANENT"
      },
      "name": "spaces/AAAAAAAAAAA/threads/BBBBBBBBBBB"
    },
    "messageHistoryState": "HISTORY_ON",
    "space": {
      "spaceThreadingState": "GROUPED_MESSAGES",
      "spaceType": "SPACE",
      "displayName": "Customer Support Superstars",
      "name": "spaces/AAAAAAAAAAA",
      "spaceHistoryState": "HISTORY_ON",
      "type": "ROOM",
      "threaded": true
    }
  },
  "user": {
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "displayName": "Izumi",
    "name": "users/12345678901234567890",
    "type": "HUMAN",
    "email": "izumi@example.com",
    "domainId": "ABCDEFG"
  },
  "space": {
    "spaceThreadingState": "GROUPED_MESSAGES",
    "spaceType": "SPACE",
    "displayName": "Customer Support Superstars",
    "name": "spaces/AAAAAAAAAAA",
    "spaceHistoryState": "HISTORY_ON",
    "type": "ROOM",
    "threaded": true
  }
}

Clic sulle schede per le finestre di dialogo

Quando un utente interagisce con una finestra di dialogo, il payload per l'evento di interazione CARD_CLICKED include i seguenti campi aggiuntivi:

  • isDialogEvent: impostala su true per gli eventi di interazione che prevedono finestre di dialogo.
  • DialogEventType: il tipo di interazione con la finestra di dialogo, ad esempio se un utente apre, invia o annulla una finestra di dialogo.

Il seguente esempio JSON mostra una parte del corpo di una richiesta per un evento di interazione CARD_CLICKED. In questo esempio, l'utente ha fatto clic su un pulsante in una finestra di dialogo che invia informazioni all'app Chat:

{
  "type": "CARD_CLICKED",
  ...
  "isDialogEvent": true,
  "dialogEventType": "SUBMIT_DIALOG",
}

Messaggio della home page dell'app

Questo evento di interazione indica che un utente ha aperto un messaggio diretto con la tua app Chat e ha ricevuto un messaggio Home dell'app Chat.

Il seguente esempio JSON mostra il corpo della richiesta per un evento di interazione APP_HOME:

{
  "chat": {
    "type": "APP_HOME",
    "user": {
      "name": "users/12345678901234567890",
      "type": "HUMAN",
      "email": "izumi@example.com",
      "domainId": "ABCDEFG"
    },
    "space": {
      "name": "spaces/AAAAAAAAAAA",
      "singleUserBotDm": true,
      "spaceType": "DIRECT_MESSAGE"
    }
  },
  "commonEventObject": {
    "invokedFunction": "onAppHome",
    "userLocale": "en",
    "hostApp": "CHAT"
  }
}

Inviare un modulo in un messaggio della home page dell'app

Questo evento di interazione indica che un utente ha inviato informazioni del modulo tramite un messaggio Home dell'app di Chat.

Il seguente esempio JSON mostra il corpo della richiesta per un evento di interazione SUBMIT_FORM:

{
  "commonEventObject": {
    "userLocale": "en",
    "invokedFunction": "onSubmitFunction",
    "formInputs": {
      "username": {
        "": {
          "stringInputs": {
            "value": [
              "Ira"
            ]
          }
        }
      }
    },
    "hostApp": "CHAT"
  },
  "chat": {
    "type": "SUBMIT_FORM",
    "space": {
      "name": "spaces/AAAAAAAAAAA",
      "spaceType": "DIRECT_MESSAGE",
      "singleUserBotDm": true
    },
    "user": {
      "type": "HUMAN",
      "name": "123456789"
    }
  }
}

Per scoprire come elaborare i payload degli eventi di interazione e restituire una risposta, consulta le seguenti guide: