Envía mensajes privados a usuarios de Google Chat

En esta página, se explica cómo crear y enviar mensajes privados como una app de Google Chat.

Un mensaje privado es un mensaje de la app de Chat que solo es visible para un usuario de Chat específico. Puedes usar mensajes privados en espacios con varias personas para que puedan interactuar de forma privada con apps de Chat. Por ejemplo, tu app de Chat puede enviar mensajes de forma privada para realizar alguna de las siguientes acciones:

  • Responde a un comando de barra. Por ejemplo, si un usuario invoca el comando de barra /about de tu app de Chat en un espacio, tu app de Chat puede responder con un mensaje privado que explica lo que hace la app de Chat y cómo usarla.
  • Envía notificaciones o envía información que solo sea relevante para un usuario. Por ejemplo, notifica a un usuario que se le asignó una tarea o recuérdale que la complete.
  • Envía un mensaje de error. Por ejemplo, si un usuario omite el texto de argumento requerido para un comando de barra, la app de Chat puede enviar un mensaje privado para explicar el error y ayudar al usuario a darle formato al comando.

Cuando una app de Chat envía un mensaje privado, se muestra una etiqueta que notifica al usuario que el mensaje solo es visible para él:

Mensaje privado para la app de Chat de Cymbal Labs. Aquí se indica que Cymbal Labs creó la app de Chat, y comparte un vínculo a la documentación y otro para comunicarte con el equipo de asistencia al cliente.
Figura 1: Cuando una app de Chat envía un mensaje privado, el usuario ve un mensaje con una etiqueta que dice Only visible to you.

Requisitos previos

Node.js

Nota: Las muestras de código de Node.js de esta guía se escriben para ejecutarse como una función de Google Cloud.

Python

Nota: Las muestras de código de Python en esta guía están escritas para ejecutarse como una función de Google Cloud Functions, con Python 3.10.

Apps Script

Envía un mensaje privado

Para enviar un mensaje de forma privada como una app de Chat, especifica el campo privateMessageViewer en el mensaje cuando lo crees. Puedes crear mensajes privados del mismo modo que creas cualquier mensaje: puedes responder a una interacción del usuario o llamar de forma asíncrona al método create() de la API de Google Chat en el recurso Message. Si quieres conocer los pasos para enviar mensajes de texto o tarjetas, consulta Cómo enviar un mensaje.

En el siguiente ejemplo, se muestra el JSON de un mensaje de texto privado que dice Hello private world!:

{
    "text": "Hello private world!",
    "privateMessageViewer": "USER"
}

En este ejemplo, USER representa al usuario de Chat que puede ver el mensaje, con el formato de un recurso User. Si respondes a una interacción del usuario, puedes especificar el objeto User del evento de interacción. Para ver un ejemplo, consulta la siguiente sección Responde de forma privada a un comando de barra.

De lo contrario, para especificar el lector de un mensaje privado, puedes usar el campo name del recurso User:

{
    "text": "Hello private world!",
    "privateMessageViewer": {
      "name": "users/USER_ID"
    }
}

En este ejemplo, se usa el campo name para especificar el nombre del recurso User del usuario en Google Chat. Reemplaza USER_ID por un ID único para el usuario, como 12345678987654321 o hao@cymbalgroup.com.

Si quieres obtener más información para especificar usuarios, consulta Cómo identificar y especificar usuarios de Google Chat.

Cómo responder de forma privada a un comando de barra

En el siguiente código, se muestra un ejemplo de una app de Chat que responde a un comando de barra con un mensaje privado.

La app de Chat procesa un evento de interacción MESSAGE y responde al comando de barra /help con un mensaje de texto privado que explica cómo usarlo:

Node.js 

/**
* Responds to a MESSAGE event in Google Chat.
*
* @param {!Object} req Request sent from Google Chat app
* @param {!Object} res Response to send back
*
* @return {!Object} respond to slash command
*/
exports.onMessage = function onMessage(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    return res.send('Hello! This function is meant to be used in Google Chat app.');
  }

  const event = req.body;

  // Checks for the presence of event.message.slashCommand.
  // If the slash command is "/help", responds with a private text message.
  if (event.message.slashCommand) {
    switch (event.message.slashCommand.commandId) {
      case '1':  // /help
        return res.json({
          privateMessageViewer: event.user,
          text: 'This Chat app was created by Cymbal Labs. To get help with this app, <https://cymbalgroup.com/docs|see our documentation> or <https://cymbalgroup.com/support|contact our support team>.'
        });
    }
  }

  // If the Chat app doesn't detect a slash command, it responds
  // with a private text message
  return res.json({
    privateMessageViewer: event.user,
    text: 'Try a slash command.'
  });
};

Apps Script 

/**
* Responds to a MESSAGE event in Google Chat.
*
* @param {Object} event the event object from Google Chat
*/
function onMessage(event) {
  if (event.message.slashCommand) {
    switch (event.message.slashCommand.commandId) {
      case 1: // Responds to /help
        return {
          "privateMessageViewer": event.user,
          "text": "This Chat app was created by Cymbal Labs. To get help with this app, <https://cymbalgroup.com/docs|see our documentation> or <https://cymbalgroup.com/support|contact our support team>."
        };
    }
  }
  else {
    return { "text": "Try a slash command.", "privateMessageViewer": event.user };
  }
}

Python 

from typing import Any, Mapping

import flask
import functions_framework

@functions_framework.http
def main(req: flask.Request) -> Mapping[str, Any]:
  """Responds to a MESSAGE event in Google Chat.

  Args:
      req (flask.Request): the event object from Chat API.

  Returns:
      Mapping[str, Any]: open a Dialog in response to a card's button click.
  """
  if req.method == 'GET':
    return 'Hello! This function must be called from Google Chat.'

  request = req.get_json(silent=True)

  # Checks for the presence of event.message.slashCommand.
  # If the slash command is "/help", responds with a private text message.
  if request.get('message', {}).get('slashCommand'):
    command_id = request.get('message', {}).get('slashCommand').get('commandId')
    if command_id == '1':  # /help
      return {
          'privateMessageViewer': request.get('user'),
          'text': (
              'This Chat app was created by Cymbal Labs. To get help with this'
              ' app, <https://cymbalgroup.com/docs|see our documentation> or'
              ' <https://cymbalgroup.com/support|contact our support team>.'
          ),
      }

  return {
      'privateMessageViewer': request.get('user'),
      'text': 'Try a slash command.',
  }

Limitaciones

Para enviar un mensaje privado, no puede contener ni usar lo siguiente:

  • Archivos adjuntos.
  • Acciones de los accesorios.
  • Mensajes parcialmente privados. Por ejemplo, una app de Chat no puede enviar un mensaje con texto ni una tarjeta en los que el texto solo sea visible para un usuario, pero la tarjeta es visible para todos los miembros del espacio.
  • Autenticación de usuarios. Solo las apps de Chat pueden enviar mensajes privados, por lo que esta no puede autenticarse como usuario para enviar un mensaje de forma privada.

Actualiza o borra mensajes privados

Para actualizar o borrar mensajes de Google Chat, debes llamar a la API de Chat. No puedes cambiar el usuario del mensaje privado ni hacerlo público. Por lo tanto, cuando actualizas mensajes privados, debes omitir el campo privateMessageViewer en la llamada a la API (el campo es de solo salida).

Para actualizar un mensaje privado, consulta Cómo actualizar un mensaje. Para borrar un mensaje privado, consulta Cómo borrar un mensaje.