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 alla tua app di chat o richiama l'app in uno spazio.
  • Aggiunto 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.
  • Clic sulla scheda:un utente fa clic su una scheda interattiva o una finestra di dialogo inviata dall'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, ovvero un payload JSON che rappresenta l'interazione. Questo payload dell'evento 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 Event dell'API Google Chat.

Campi comuni

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

Campo 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:

Campo 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 finestra di dialogo o una scheda interattiva. CARD_CLICKED

Payload di eventi 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 suoi 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.

L'esempio JSON seguente 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 la tua app di 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.

L'esempio JSON seguente 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 Chat e l'utente. L'app installata viene visualizzata nel riquadro dei messaggi diretti degli utenti. Se gli amministratori installano 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 gli amministratori di Google Workspace Installare le app del Marketplace nel dominio.

L'esempio JSON seguente mostra il corpo della richiesta per un evento di interazione ADDED_TO_SPACE quando un amministratore di Google Workspace installa un'app Chat per un utente. Poiché un amministratore ha installato l'app 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 la tua app di chat è stata rimossa da uno spazio. Le app di chat non rispondono con messaggi a questo evento perché sono già state rimosse.

L'esempio JSON seguente 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"
  }
}

Disinstallata 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 l'utente ha installato l'app di chat prima dell'amministratore, l'app rimarrà installata per l'utente. In questo caso, poiché l'app di chat è ancora installata, non riceve un evento di interazione REMOVED_FROM_SPACE.

L'esempio JSON seguente mostra il corpo della richiesta per un evento di interazione REMOVED_FROM_SPACE quando un amministratore di Google Workspace disinstalla un'app 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"
  }
}

Clic sulla carta

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 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 una finestra di dialogo.

L'esempio JSON seguente 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: imposta su true per gli eventi di interazione che coinvolgono finestre di dialogo.
  • DialogEventType: il tipo di interazione con la finestra di dialogo, incluso se un utente apre, invia o annulla una finestra di dialogo.

L'esempio JSON seguente 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 di chat:

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

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