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 del usuario y responder a ellas en Google Chat.

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

• Activadores: Son las formas en que los usuarios de Google Chat pueden invocar una app de Chat, por ejemplo, agregándola a un espacio o enviándole un mensaje.
• Objetos de eventos: 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, les solicitan a los usuarios que envíen información
• Las vistas previas de vínculos, que son tarjetas que muestran información previa sobre un servicio externo

Requisitos previos

• Una cuenta de Google Workspace para empresas 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 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 del usuario 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 usar @menciones o 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 Cómo configurar la API de Google Chat.

Cómo configurar 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 mensajes iniciales, haz lo siguiente:

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 Sugerencias iniciales y haz clic en Agregar una sugerencia.

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

4. En Selección de tipo, elige cómo se comportará la instrucción:

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

5. Configura la instrucción según el tipo que seleccionaste:

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

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

   • Si seleccionaste Símbolo del sistema, haz lo siguiente:

     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 (por ejemplo, si se agota el tiempo de espera, se produce una falla temporal en la red o se devuelve un código de estado HTTPS que no es 2xx), es posible que Google Chat vuelva a intentar 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 ciertas situaciones. Si la solicitud se completa correctamente, pero devuelve una carga útil de respuesta no válida, Google Chat no vuelve a intentarla.

Objetos de eventos

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

Cargas útiles de objetos de eventos

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

• Para un activador de 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).
• En el caso de las interacciones de espacio y mensajes (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 los campos space, message y configCompleteRedirectUri cuando un usuario envía un mensaje.
  • addedToSpacePayload: Contiene space, interactionAdd y configCompleteRedirectUri cuando se agrega la app de Chat 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, por ejemplo, cuando escribe 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 del usuario.

Para responder con una acción, una app de Chat debe hacerlo en un plazo de 30 segundos, y la respuesta debe aplicarse al espacio en el que ocurrió 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 del usuario 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 acceder a un servicio externo o autenticarse en él.

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 mensajes, como cuando los usuarios @mencionan o envían mensajes directos a una app de Chat
• Activadores de agregado 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
• Son los 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 con @ 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 accesorio, 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 en respuesta al activador Added to space 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 del vínculo con updateInlinePreviewAction. Para obtener más información, 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 deban 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)
• Enviar mensajes según un programa o enviar 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 se muestre 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 devolviendo 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 Cómo enviar un mensaje. Si deseas obtener guías para 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
• Cómo responder a comandos
• Abrir diálogos interactivos
• Leer los datos del formulario que ingresan los usuarios en las tarjetas
• Vínculos de vista previa
• Crea una página principal para una app de Chat
• Cómo verificar solicitudes de Chat
• Prueba funciones interactivas para 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`.'
  };
}