Tipos de eventos de interacción con apps de Google Chat

En esta página, se describen los tipos de eventos de interacción que la app de Google Chat puede recibir de este servicio.

Si quieres configurar tu app de Chat para recibir eventos de interacción, consulta Recibe y responde interacciones con tu app de Chat.

Formatos de los eventos de interacción

Los usuarios pueden interactuar con las apps de Chat de muchas maneras. Para cada tipo de interacción, Google Chat envía un tipo diferente de evento de interacción:

  • Mensaje: Un usuario envía un mensaje a tu app de Chat o invoca a tu app de Chat en un espacio.
  • Agregada al espacio: Un usuario agrega tu app de Chat a un espacio.
  • Quitada del espacio: Un usuario quita tu app de Chat de un espacio.
  • Se hizo clic en la tarjeta: Un usuario hace clic en una tarjeta interactiva o un diálogo que envió tu app de Chat.

Cada vez que un usuario interactúa con tu app de Chat, Google Chat envía un evento de interacción con el cuerpo de la solicitud, que es una carga útil de JSON que representa la interacción. Esta carga útil de evento contiene elementos comunes a todos los tipos de eventos de interacción, así como elementos específicos del tipo de evento.

Para obtener más información sobre los campos de un evento de interacción, consulta la documentación de referencia de Event de la API de Google Chat.

Campos comunes

Los siguientes campos siempre se proporcionan en la carga útil de un evento de interacción:

Campo Descripción
type El tipo de evento que recibe la app de Chat, como MESSAGE o ADDED_TO_SPACE.
eventTime Es la marca de tiempo que indica cuándo se envió el evento.
common Representa información sobre el cliente del usuario, como la configuración regional o la plataforma.

Campos por tipo de evento de interacción

Según el tipo de evento, la carga útil puede contener los siguientes campos adicionales:

Campo Descripción Tipo de evento
message Es el mensaje relacionado con el evento. MESSAGE, ADDED_TO_SPACE, CARD_CLICKED.
space El espacio relacionado con el evento. MESSAGE, ADDED_TO_SPACE, REMOVED_FROM_SPACE y CARD_CLICKED.
user El usuario relacionado con el evento. El usuario siempre es una persona (no una app de Chat). MESSAGE, ADDED_TO_SPACE, REMOVED_FROM_SPACE y CARD_CLICKED.
action Es la función que un usuario activa cuando hace clic en una tarjeta o un diálogo interactivo. CARD_CLICKED.

Ejemplos de cargas útiles de eventos

En esta sección, se describe qué activa un evento de interacción y se proporciona una carga útil de ejemplo de JSON para cada uno de los siguientes tipos de eventos:

Mensajes

Este evento de interacción representa cuando una persona envía un mensaje a la app de Chat, por ejemplo:

  • Cualquier mensaje en un espacio de mensajes directos (MD) con la app de Chat
  • Un mensaje en un espacio formado por varias personas en el que una persona @menciona la app de Chat o usa uno de sus comandos de barra.
  • Si configuraste vistas previas de vínculos para tu app de Chat, un usuario publicará un mensaje con un vínculo que coincida con el patrón de URL configurado.

En el siguiente ejemplo de JSON, se muestra un evento de interacción MESSAGE en el que un usuario @menciona una app de Chat en un espacio con varias personas:

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

Se agregó al espacio

Este evento de interacción indica que tu app de Chat se agregó a un espacio. Por lo general, las apps publican algún tipo de mensaje de bienvenida en una conversación nueva en el espacio para responder a este evento de interacción.

En el siguiente ejemplo de JSON, se muestra el cuerpo de la solicitud para un evento de interacción ADDED_TO_SPACE cuando un usuario agrega una app de Chat a un espacio:

{
  "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 por administradores de Google Workspace

El evento de interacción ADDED_TO_SPACE también puede indicar que un administrador de Google Workspace instaló tu app de Chat para un usuario de su organización.

Los administradores solo pueden instalar una app de Chat para los mensajes directos entre la app de Chat y el usuario. La app instalada aparecerá en el panel de mensajes directos del usuario. Cuando los administradores instalan apps de Chat, los usuarios no pueden desinstalarlas. Si quieres obtener más información sobre las apps de Chat que instalaron los administradores, consulta la documentación de ayuda para administradores de Google Workspace: Instala apps de Marketplace en tu dominio.

En el siguiente ejemplo de JSON, se muestra el cuerpo de la solicitud de un evento de interacción ADDED_TO_SPACE cuando un administrador de Google Workspace instala una app de Chat para un usuario. Debido a que un administrador instaló la app de Chat, adminInstalled se configura 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"
  }
}

Se quitó del espacio

Este evento de interacción indica que tu app de Chat se quitó de un espacio. Las apps de chat no responden con mensajes a este evento porque ya se quitaron.

En el siguiente ejemplo de JSON, se muestra el cuerpo de la solicitud de un evento de interacción REMOVED_FROM_SPACE cuando un usuario quita una app de Chat de un espacio:

{
  "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 por los administradores de Google Workspace

El evento de interacción REMOVED_FROM_SPACE también puede indicar que un administrador de Google Workspace desinstaló tu app de Chat para un usuario de su organización. Cuando se desinstala, la app de Chat ya no aparece en el panel de mensajes directos del usuario.

Si un usuario instaló tu app de Chat antes que el administrador, esta permanecerá instalada para el usuario. En este caso, dado que la app de Chat todavía está instalada, esta no recibe un evento de interacción REMOVED_FROM_SPACE.

En el siguiente ejemplo de JSON, se muestra el cuerpo de la solicitud de un evento de interacción REMOVED_FROM_SPACE cuando un administrador de Google Workspace desinstala una app de Chat para un usuario. Como un administrador desinstaló la app de Chat, adminInstalled se configura 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"
  }
}

Se hizo clic en la tarjeta

Este evento de interacción indica que un usuario hizo clic en un botón en un mensaje o diálogo de tarjeta.

Para recibir un evento de interacción, el botón debe activar otra interacción con la app de Chat. Por ejemplo, una app de Chat no recibe un evento de interacción CARD_CLICKED si un usuario hace clic en un botón que abre un vínculo a un sitio web, pero recibe eventos de interacción en los siguientes ejemplos:

  • El usuario hace clic en el botón Send feedback de una tarjeta, y se abre un diálogo para que el usuario ingrese información.
  • El usuario hace clic en un botón Submit después de ingresar información en una tarjeta o un diálogo.

En el siguiente ejemplo de JSON, se muestra el cuerpo de la solicitud para un evento de interacción CARD_CLICKED cuando un usuario hace clic en un botón de un mensaje de tarjeta que le asigna un ticket de asistencia entrante:

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

Clics en tarjetas para los diálogos

Cuando un usuario interactúa con un diálogo, la carga útil del evento de interacción CARD_CLICKED incluye los siguientes campos adicionales:

  • isDialogEvent: Se establece en true para los eventos de interacción que incluyen diálogos.
  • DialogEventType: Es el tipo de interacción con el diálogo, incluso si un usuario lo abre, lo envía o lo cancela.

En el siguiente ejemplo de JSON, se muestra una parte del cuerpo de una solicitud para un evento de interacción CARD_CLICKED. En este ejemplo, el usuario hizo clic en un botón de un diálogo que envía información a la app de Chat:

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

Para aprender a procesar las cargas útiles de los eventos de interacción y mostrar una respuesta, consulta las siguientes guías: