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

Nesta página, descrevemos 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 dos eventos de interação

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

  • Mensagem:um usuário envia uma mensagem ao seu app do Chat ou invoca seu 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 ou caixa de diálogo interativo enviado pelo seu app do Chat.

Sempre que um usuário interage com um 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 ao tipo de evento.

Para saber mais sobre os campos em um evento de interação, consulte a documentação de referência do 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 a 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, e 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 cartão interativo ou caixa de diálogo. CARD_CLICKED.

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

Mensagem

Esse evento de interação representa quando uma pessoa envia uma mensagem ao 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 de 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 para o app do Chat, um usuário postará uma mensagem contendo um link que corresponda ao padrão de 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 o app do Chat foi adicionado a um espaço. Os apps geralmente respondem a esse evento de interação postando um 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 de 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"
  }
}

Instalada 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 o app do Chat e o usuário. O app instalado aparece no painel de mensagem direta dos usuários. Quando os administradores instalam 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 do administrador do Google Workspace Instalar apps do Marketplace no domínio.

O exemplo de 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 com 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 na 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, ele 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 de 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 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"
  }
}

Cartão clicado

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

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 em um botão Send feedback em um cartão, que abre uma caixa de diálogo para que o usuário insira informações.
  • O usuário clica em um botão Submit depois de inserir informações em um cartão ou caixa de diálogo.

O exemplo 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 na mensagem de um card que atribui um tíquete de suporte recebido 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 adicionais:

  • 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 caixa de diálogo.

O exemplo JSON a seguir mostra uma parte do corpo de uma 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: