Tipos de evento de interação com o app do Google Chat

Esta página descreve os tipos de eventos de interação que seu app do Google Chat pode receber do Google Chat.

Para configurar o app do Chat para receber eventos de interação, consulte Receber e responder a interações com o app do Chat.

Formatos para eventos de interação

Os usuários podem interagir com os apps do Chat de várias maneiras. Para cada tipo de interação, o Google Chat envia um tipo diferente de evento de interação:

  • Mensagem:um usuário envia uma mensagem ao seu app do Chat ou invoca o app do Chat em um espaço.
  • Adicionado ao espaço:um usuário adiciona seu app do Chat a um espaço.
  • Removido do espaço:um usuário remove seu app do Chat de um espaço.
  • Card clicado:um usuário clica em um card interativo ou caixa de diálogo enviado pelo app do Chat.

Sempre que um usuário interage com seu app do Chat, o Google Chat envia um evento de interação com um corpo da solicitação, que é um payload JSON que representa a interação. Esse payload de evento contém elementos comuns a todos os tipos de eventos de interação, bem como elementos específicos do tipo de evento.

Para saber mais sobre os campos em um evento de interação, consulte a documentação de referência de Event da API Google Chat.

Campos comuns

Os campos a seguir são sempre fornecidos no payload de um evento de interação:

Campo Descrição
type O tipo de evento que o app do Chat está recebendo, como MESSAGE ou ADDED_TO_SPACE.
eventTime O carimbo de data/hora que indica quando o evento foi enviado.
common Representa informações sobre o cliente do usuário, como a localidade ou plataforma.

Campos por tipo de evento de interação

Dependendo do tipo de evento, o payload pode conter os seguintes campos adicionais:

Campo Descrição Tipo de evento
message A mensagem relacionada ao evento. MESSAGE, ADDED_TO_SPACE, CARD_CLICKED.
space O espaço relacionado ao evento. MESSAGE, ADDED_TO_SPACE, REMOVED_FROM_SPACE, CARD_CLICKED.
user O usuário relacionado ao evento. O usuário é sempre uma pessoa (não um app do Chat). MESSAGE, ADDED_TO_SPACE, REMOVED_FROM_SPACE, CARD_CLICKED.
action A função que um usuário aciona quando clica em um card interativo ou caixa de diálogo. CARD_CLICKED.

Exemplos de payloads de eventos

Nesta seção, descrevemos o que aciona um evento de interação e fornecemos um exemplo de payload JSON para cada um dos seguintes tipos de evento:

A mensagem

Esse evento de interação representa quando uma pessoa envia uma mensagem para o app do Chat, como:

  • Qualquer mensagem em um espaço de mensagem direta (DM) com o app do Chat.
  • Uma mensagem em um espaço com várias pessoas em que uma pessoa @menciona o app do Chat ou usa um dos comandos de barra.
  • Se você tiver configurado visualizações de link no app do Chat, um usuário postará uma mensagem com um link que corresponda ao padrão do URL configurado.

O exemplo JSON a seguir mostra um evento de interação MESSAGE em que um usuário @menciona um app do Chat em um espaço com várias pessoas:

{
  "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"
  }
}

Adicionado ao espaço

Esse evento de interação indica que seu app do Chat foi adicionado a um espaço. Os apps geralmente respondem a esse evento de interação postando algum tipo de mensagem de boas-vindas em uma nova conversa no espaço.

O exemplo de JSON a seguir mostra o corpo da solicitação para um evento de interação ADDED_TO_SPACE quando um usuário adiciona um app do Chat a um espaço:

{
  "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"
  }
}

Instalado pelos administradores do Google Workspace

O evento de interação ADDED_TO_SPACE também pode indicar que um administrador do Google Workspace instalou seu app do Chat para um usuário na organização.

Os administradores só podem instalar um app do Chat para mensagens diretas entre ele e o usuário. O app instalado aparece no painel de mensagens diretas dos usuários. Quando os administradores instalam os apps do Chat, os usuários não podem desinstalá-los. Para saber mais sobre os apps do Chat instalados pelos administradores, consulte a documentação da Ajuda para admins do Google Workspace, Instalar apps do Marketplace no seu domínio.

O exemplo JSON a seguir mostra o corpo da solicitação de um evento de interação ADDED_TO_SPACE quando um administrador do Google Workspace instala um app do Chat para um usuário. Como um administrador instalou o app do Chat, adminInstalled está definido como 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"
  }
}

Removido do espaço

Esse evento de interação indica que o app do Chat foi removido de um espaço. Os apps de chat não respondem com mensagens a esse evento porque eles já foram removidos.

O exemplo de JSON a seguir mostra o corpo da solicitação de um evento de interação REMOVED_FROM_SPACE quando um usuário remove um app do Chat de um espaço:

{
  "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"
  }
}

Desinstalado pelos administradores do Google Workspace

O evento de interação REMOVED_FROM_SPACE também pode indicar que um administrador do Google Workspace desinstalou seu app do Chat para um usuário da organização. Quando desinstalado, o app do Chat não aparece mais no painel de mensagens diretas do usuário.

Se um usuário tiver instalado o app do Chat antes do administrador, o app do Chat permanecerá instalado para o usuário. Nesse caso, como o app do Chat ainda está instalado, ele não recebe um evento de interação REMOVED_FROM_SPACE.

O exemplo JSON a seguir mostra o corpo da solicitação de um evento de interação REMOVED_FROM_SPACE quando um administrador do Google Workspace desinstala um app do Chat para um usuário. Como o app do Chat foi desinstalado por um administrador, adminInstalled está definido como 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"
  }
}

O cartão foi clicado

Esse evento de interação indica que um usuário clicou em um botão em uma mensagem ou caixa de diálogo do card.

Para receber um evento de interação, o botão precisa acionar outra interação com o app do Chat. Por exemplo, um app do Chat não receberá um evento de interação CARD_CLICKED se um usuário clicar em um botão que abre um link para um site, mas receber eventos de interação nos exemplos a seguir:

  • O usuário clica no botão Send feedback em um cartão, que abre uma caixa de diálogo para inserir informações.
  • O usuário clica em um botão Submit depois de inserir informações em um card ou caixa de diálogo.

O exemplo de JSON a seguir mostra o corpo da solicitação para um evento de interação CARD_CLICKED quando um usuário clica em um botão em uma mensagem de cartão que atribui um tíquete de suporte a ele:

{
  "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
  }
}

Cliques no card para caixas de diálogo

Quando um usuário interage com uma caixa de diálogo, o payload do evento de interação CARD_CLICKED inclui os seguintes campos extras:

  • isDialogEvent: defina como true para eventos de interação que envolvem caixas de diálogo.
  • DialogEventType: o tipo de interação com a caixa de diálogo, incluindo se um usuário abre, envia ou cancela uma.

O exemplo JSON a seguir mostra uma parte do corpo da solicitação para um evento de interação CARD_CLICKED. Neste exemplo, o usuário clicou em um botão em uma caixa de diálogo que envia informações para o app do Chat:

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

Para saber como processar os payloads de eventos de interação e retornar uma resposta, consulte os seguintes guias: