Recibe interacciones de los usuarios y responde a ellas

En esta página, se describe cómo tu app de Google Chat puede recibir interacciones de los usuarios en Google Chat y responder a ellas.

Para compilar interfaces interactivas para las apps de Chat, usa los siguientes componentes:

• Activadores: Son las formas en que los usuarios de Google Chat pueden invocar una app de Chat, como agregarla a un espacio o enviarle un mensaje.
• Objetos de evento: Son los datos que las apps de Chat reciben de los activadores o las interacciones de la IU.
• Acciones: Son las formas en que las apps de Chat pueden responder a las interacciones, como enviar mensajes o devolver una interfaz de usuario basada en tarjetas.

Las apps de Chat pueden compilar y mostrar interfaces de las siguientes maneras:

• Mensajes que pueden contener texto, tarjetas estáticas o interactivas, y botones de accesorios
• Páginas principales (página principal de la app) que aparecen en la pestaña Página principal de los mensajes directos 1:1 con la app de Chat.
• Diálogos, que son tarjetas que se abren en una ventana nueva y, por lo general, solicitan a los usuarios que envíen información.
• Vistas previas de vínculos, que son tarjetas que muestran información preliminar sobre un servicio externo

Requisitos previos

• Una cuenta de Google Workspace de Business o Enterprise con acceso a Google Chat
• Crea un proyecto de Google Cloud
• Configura la pantalla de consentimiento de OAuth.
• Habilita y configura la API de Google Chat.

Cómo funcionan las interacciones del usuario

Cuando un usuario interactúa con una app de Chat, Google Chat invoca un activador configurado y envía un objeto de evento al extremo o a la función de tu app de Chat. Tu app de Chat procesa el objeto de evento y puede devolver una acción de forma síncrona en un plazo de 30 segundos o responder de forma asíncrona con la API de Chat.

En el siguiente diagrama, se muestra cómo las apps de Google Chat procesan las interacciones de los usuarios y responden a ellas:

Activadores

Los activadores son las formas específicas en que los usuarios invocan una app de Chat con la IU de Chat, como las @menciones o los comandos de la app.

En la siguiente tabla, se muestran los activadores de Chat, una descripción y cómo suelen responder las apps de Chat:

Configura los extremos o las funciones de devolución de llamada para estos activadores en la página Configuración de la API de Chat en la consola de Google Cloud. Para obtener instrucciones paso a paso, consulta Configura la API de Google Chat.

Configura instrucciones de inicio

Las instrucciones de inicio ayudan a los usuarios a descubrir la funcionalidad de tu app de Chat cuando abren un mensaje directo 1:1 vacío con tu app. Puedes configurar hasta tres instrucciones de inicio.

Para agregar y configurar instrucciones de inicio, sigue estos pasos:

1. En la consola de Google Cloud, ve a la página Configuración de la API de Chat:

   Ir a la página de configuración de la API de Chat

2. En Funciones interactivas, busca Instrucciones de inicio y haz clic en Agregar una instrucción.

3. En el campo Clasificación (1-3), ingresa un número del 1 al 3 para especificar el orden de visualización.

4. En Selección del tipo, elige cómo se comporta el mensaje:

   • Instrucción de texto: Completa la barra para escribir con texto predefinido cuando el usuario hace clic en el chip de instrucciones.
   • Símbolo del sistema: Ejecuta un comando de barra o un comando rápido registrado cuando se hace clic en él. No se pueden seleccionar los comandos que requieren argumentos adicionales.

5. Configura el mensaje según el tipo que hayas seleccionado:

   • Si seleccionaste Instrucción de texto, haz lo siguiente:

     1. En Título, ingresa el título del mensaje que se muestra en el chip (hasta 30 caracteres).
     2. En Texto de la instrucción, ingresa el texto que se completará en la barra para escribir (hasta 60 caracteres).
     3. Opcional: Agrega títulos y texto localizados para los usuarios que hablan otros idiomas:
     4. En Mensajes localizados, haz clic en Agregar un idioma.
     5. En Idioma, selecciona un idioma compatible en el menú desplegable.
     6. En Título localizado, ingresa el título localizado (hasta 30 caracteres).
     7. En Texto de la instrucción localizada, ingresa el texto de la instrucción localizada (hasta 60 caracteres).
     8. Repite el proceso para agregar más idiomas según sea necesario.

   • Si seleccionaste Símbolo del sistema:

     1. En Comando de barra/Comando rápido, selecciona el comando en el menú desplegable.

6. Haz clic en Listo y, luego, en Guardar en la parte inferior de la página.

Controla los reintentos de llamadas HTTP a tu servicio

Si falla una solicitud HTTPS a tu servicio (como un tiempo de espera, una falla temporal de la red o un código de estado HTTPS que no sea 2xx), Google Chat podría reintentar la entrega varias veces en unos minutos (pero esto no está garantizado). Como resultado, una app de Chat podría recibir el mismo evento varias veces en determinadas situaciones. Si la solicitud se completa correctamente, pero devuelve una carga útil de respuesta no válida, Google Chat no vuelve a intentar la solicitud.

Objetos de evento

Las apps de Chat reciben objetos de evento cuando se ejecuta un activador de Chat o cuando los usuarios de Chat interactúan con una IU de la app de Chat (como hacer clic en un botón o enviar un diálogo). El objeto de evento te permite usar datos de interacción para responder o actualizar una IU.

En 2025, se expandieron las apps de Google Chat para admitir eventos de complementos, y este es el comportamiento predeterminado para las apps de Chat nuevas desde julio de 2025. En toda la documentación de Chat, los eventos de complementos son el tipo de evento estándar que se muestra en las guías y las muestras de código. La documentación de los eventos de Chat (para las apps de Chat que no son complementos de Google Workspace) se divide en secciones contraídas (por ejemplo, Apps de Chat que no son complementos: Recibe eventos de interacción y responde a ellos).

Determina los tipos de eventos y respuestas

Cuando tu app de Chat recibe un objeto de evento, la estructura de la carga útil y la forma en que respondes dependen de si tu app de Chat está configurada como un complemento de Google Workspace.

Para confirmar qué tipo de objetos de evento recibe tu app y cómo debe responder, consulta la configuración de tu app con la siguiente tabla:

{
  "addOns": {
    "chat": {}
  }
}

{
  "chat": {}
}

Cargas útiles de objetos de eventos

Cada objeto de evento de complementos incluye un commonEventObject con detalles del host y de la plataforma (hostApp: "CHAT", clientPlatform, userLocale, userTimezone, parameters y formInputs) y un objeto chat que contiene el contexto específico de Chat:

• Para un activador de la página principal de la app (cuando un usuario abre la pestaña Página principal en un mensaje directo 1:1 con la app de Chat), el objeto chat contiene chat.user y chat.eventTime sin un campo de unión payload. Cuando un usuario hace clic en un botón de la tarjeta de la página principal, el objeto de evento incluye chat.buttonClickedPayload junto con commonEventObject.parameters (y commonEventObject.formInputs si la tarjeta contiene entradas de formulario).
• Para las interacciones de espacio y mensaje (Se agregó al espacio, Mensaje, Se quitó del espacio, Comando de la app o interacciones de botones y widgets), el objeto chat incluye chat.user, chat.space, chat.eventTime y la carga útil de interacción correspondiente:
  • messagePayload: Contiene space, message y configCompleteRedirectUri cuando un usuario envía un mensaje.
  • addedToSpacePayload: Contiene space, interactionAdd y configCompleteRedirectUri cuando la app de Chat se agrega a un espacio.
  • removedFromSpacePayload: Contiene el space cuando se quita la app de Chat de un espacio.
  • buttonClickedPayload: Contiene space, message, isDialogEvent y dialogEventType cuando un usuario hace clic en un botón de una tarjeta o un diálogo.
  • widgetUpdatedPayload: Contiene el space cuando un usuario interactúa con un widget, como escribir en un menú de selección múltiple con una fuente de datos externa.
  • appCommandPayload: Contiene space, message, appCommandMetadata, isDialogEvent, dialogEventType y configCompleteRedirectUri cuando un usuario invoca un comando de la app.

Para obtener información sobre los objetos de eventos de complementos en Chat y otras aplicaciones de Google Workspace, consulta Objetos de eventos.

Cómo entregar una respuesta

En esta sección, se explica cómo las apps de Chat usan acciones para responder de forma síncrona a las interacciones de los usuarios.

Para responder con una acción, una app de Chat debe responder en un plazo de 30 segundos, y la respuesta debe aplicarse al espacio en el que se produjo la interacción. Estas respuestas síncronas no requieren autenticación. Si tu app de Chat necesita más de 30 segundos o debe actuar fuera del espacio, configura la autenticación y responde de forma asíncrona con la API de Google Chat.

Para responder a las interacciones de los usuarios de forma síncrona, tu app de Chat controla el objeto de evento entrante y devuelve uno de los siguientes objetos JSON:

• DataActions: Crea o actualiza mensajes de Chat (CreateMessageAction, UpdateMessageAction) o adjunta vistas previas de vínculos (UpdateInlinePreviewAction) con chatDataActionMarkup.
• RenderActions: Crea, actualiza o cierra una página principal o un diálogo (pushCard, updateCard, endNavigation: "CLOSE_DIALOG"), o bien proporciona sugerencias de entrada dinámicas para un menú de selección múltiple (modifyCard).
• AuthorizationError: Muestra a los usuarios una tarjeta de autorización básica (basic_authorization_prompt) para que accedan o se autentiquen en un servicio externo.

En la siguiente tabla, se muestra cómo las apps de Chat pueden responder con acciones. Las apps de Chat pueden devolver objetos JSON directamente o compilar la respuesta con AddOnResponseService y CardService de Apps Script.

Responder con un mensaje

Las apps de Chat pueden responder con un mensaje a cualquiera de los siguientes activadores o interacciones:

• Activadores de Mensaje, como cuando los usuarios @mencionan o envían un mensaje directo a una app de Chat.
• Activadores de Se agregó al espacio, como cuando los usuarios instalan la app de Chat desde Google Workspace Marketplace o la agregan a un espacio.
• Activadores de comandos de la app, como cuando los usuarios invocan un comando de barra o un comando rápido.
• Clics en botones de tarjetas en mensajes o diálogos Por ejemplo, cuando los usuarios ingresan información y hacen clic en Enviar.

Las apps de Chat pueden incluir cualquiera de los siguientes elementos en un mensaje:

• Texto que contiene hipervínculos, @menciones y emojis Consulta Cómo darles formato a los mensajes.
• Una o más tarjetas, que pueden aparecer en un mensaje o abrirse en una ventana nueva como un diálogo Consulta Crea tarjetas para las apps de Google Chat.
• Uno o más widgets de accesorios, que son botones que aparecen después de cualquier texto o tarjeta en un mensaje.

Para responder con un mensaje, devuelve DataActions con un objeto CreateMessageAction:

{
  "hostAppDataAction": {
    "chatDataAction": {
      "createMessageAction": {
        "message": <var>MESSAGE</var>
      }
    }
  }
}

Reemplaza MESSAGE por un recurso Message de la API de Chat.

En el siguiente ejemplo, una app de Chat crea y envía un mensaje de texto de incorporación cada vez que se agrega a un espacio respondiendo al activador Se agregó al espacio con DataActions:

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The request object from Google Chat.
 * @param {Object} res The response object from the Chat app.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  const chatEvent = req.body.chat;
  // Send an onboarding message when added to a Chat space
  if (chatEvent.addedToSpacePayload) {
    res.json({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
      text: 'Hi, Cymbal at your service. I help you manage your calendar ' +
        'from Google Chat. Take a look at your schedule today by typing ' +
        '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. ' +
        'To learn what else I can do, type `/help`.'
    }}}}});
  }
};

from flask import Flask, request, json
app = Flask(__name__)

@app.route('/', methods=['POST'])
def cymbal_app():
  """Sends an onboarding message when the Chat app is added to a space.

  Returns:
    Mapping[str, Any]: The response object from the Chat app.
  """
  chat_event = request.get_json()["chat"]
  if "addedToSpacePayload" in chat_event:
    return json.jsonify({ "hostAppDataAction": { "chatDataAction": {
      "createMessageAction": { "message": {
        "text": 'Hi, Cymbal at your service. I help you manage your calendar ' +
        'from Google Chat. Take a look at your schedule today by typing ' +
        '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. ' +
        'To learn what else I can do, type `/help`.'
      }}
    }}})

@SpringBootApplication
@RestController
public class App {
  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /*
   * Sends an onboarding message when the Chat app is added to a space.
   *
   * @return The response object from the Chat app.
   */
  @PostMapping("/")
  @ResponseBody
  public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
    JsonNode chatEvent = event.at("/chat");
    if (!chatEvent.at("/addedToSpacePayload").isEmpty()) {
      return new GenericJson() { {
        put("hostAppDataAction", new GenericJson() { {
          put("chatDataAction", new GenericJson() { {
            put("createMessageAction", new GenericJson() { {
              put("message", new Message().setText(
                "Hi, Cymbal at your service. I help you manage your calendar " +
                "from Google Chat. Take a look at your schedule today by typing " +
                "`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. " +
                "To learn what else I can do, type `/help`."
              ));
            } });
          } });
        } });
      } };
    }
    return new GenericJson();
  }
}

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Google Chat.
 * @return {Object} Response from the Chat app.
 */
function onAddedToSpace(event) {
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: 'Hi, Cymbal at your service. I help you manage your calendar ' +
          'from Google Chat. Take a look at your schedule today by typing ' +
          '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. ' +
          'To learn what else I can do, type `/help`.'
  }}}}};
}

La muestra de código devuelve el siguiente mensaje de texto:

Actualiza un mensaje

Las apps de Chat también pueden actualizar los mensajes que envían. Por ejemplo, una app de Chat puede actualizar un mensaje después de que un usuario envía un diálogo o hace clic en un botón de una tarjeta en un mensaje.

Para actualizar un mensaje de la app de Chat en respuesta a una interacción, devuelve DataActions con un UpdateMessageAction:

{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateMessageAction": {
        "message": <var>MESSAGE</var>
      }
    }
  }
}

Reemplaza MESSAGE por un recurso Message de la API de Chat.

Las apps de Chat también pueden actualizar un mensaje enviado por un usuario para adjuntar una tarjeta de vista previa de vínculo con updateInlinePreviewAction. Para obtener más detalles, consulta Vínculos de vista previa.

Responde de forma asíncrona con la API de Google Chat

En lugar de devolver una acción de forma síncrona, es posible que las apps de Chat necesiten llamar a la API de Google Chat para responder a una interacción o enviar mensajes proactivos. Por ejemplo, las apps de Chat deben llamar a la API de Google Chat para realizar cualquiera de las siguientes acciones:

• Responder a una interacción después de 30 segundos (por ejemplo, después de completar una tarea de larga duración)
• Envía mensajes según un programa o envía notificaciones sobre cambios en recursos externos.
• Realizar tareas fuera del espacio en el que se produjo la interacción
• Realizar tareas en Chat que no están disponibles como acciones síncronas, como enumerar espacios o agregar miembros a un espacio.
• Realizar tareas en nombre de un usuario de Chat (lo que requiere autenticación del usuario)

Cuando respondas a una interacción después de 30 segundos, para evitar que aparezca un mensaje de error para el usuario que indique que tu app de Chat no responde, debes confirmar la recepción del objeto de evento en un plazo de 30 segundos. Para ello, devuelve una respuesta vacía:

async function onEvent(req, res) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return res.send({});
};

def on_event(event) -> dict:
  # Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return {}

public String onEvent(JsonNode event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return "{}";
}

function onEvent(event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return null;
}

Para enviar un mensaje con la API de Chat, configura la autenticación y llama al método spaces.messages.create. Para conocer los pasos, consulta Envía un mensaje. Para obtener guías sobre cómo usar métodos adicionales de la API de Chat, consulta la descripción general de la API de Chat.

Temas relacionados

• Configura la API de Google Chat
• Enviar un mensaje
• Responder a comandos
• Cómo abrir diálogos interactivos
• Lee los datos de formularios que ingresan los usuarios en las tarjetas
• Vínculos de vista previa
• Crea una página principal para una app de Chat
• Verifica las solicitudes de Chat
• Prueba las funciones interactivas de las apps de Google Chat

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The event object from Chat API.
 * @param {Object} res The response object from the Chat app.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  // Send an onboarding message when added to a Chat space
  if (req.body.type === 'ADDED_TO_SPACE') {
    res.json({
      'text': 'Hi, Cymbal at your service. I help you manage your calendar ' +
        'from Google Chat. Take a look at your schedule today by typing ' +
        '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To ' +
        'learn what else I can do, type `/help`.'
    });
  }
};

from flask import Flask, request, json
app = Flask(__name__)

@app.route('/', methods=['POST'])
def cymbal_app():
  """Sends an onboarding message when the Chat app is added to a space.

  Returns:
    Mapping[str, Any]: The response object from the Chat app.
  """
  event = request.get_json()
  if event['type'] == 'ADDED_TO_SPACE':
    return json.jsonify({
      'text': 'Hi, Cymbal at your service. I help you manage your calendar ' +
      'from Google Chat. Take a look at your schedule today by typing ' +
      '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To ' +
      'learn what else I can do, type `/help`.'
    })
  return json.jsonify({})

@SpringBootApplication
@RestController
public class App {
  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /*
   * Sends an onboarding message when the Chat app is added to a space.
   *
   * @return The response object from the Chat app.
   */
  @PostMapping("/")
  @ResponseBody
  public Message onEvent(@RequestBody JsonNode event) {
    switch (event.get("type").asText()) {
      case "ADDED_TO_SPACE":
        return new Message().setText(
          "Hi, Cymbal at your service. I help you manage your calendar " +
          "from Google Chat. Take a look at your schedule today by typing " +
          "`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. " +
          "To learn what else I can do, type `/help`.");
      default:
        return new Message();
    }
  }
}

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onAddToSpace(event) {
  return {
    'text': 'Hi, Cymbal at your service. I help you manage your calendar ' +
      'from Google Chat. Take a look at your schedule today by typing ' +
      '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn ' +
      'what else I can do, type `/help`.'
  };
}