Enviar mensagens privadas para usuários do Google Chat

Nesta página, explicamos como criar e enviar mensagens privadas como um app do Google Chat.

Uma mensagem privada é uma mensagem do app do Chat que é visível apenas para um usuário especificado do Chat. Você pode usar mensagens privadas em espaços com várias pessoas para que elas possam interagir de maneira particular com os apps do Chat. Por exemplo, seu app do Chat pode enviar mensagens de forma particular para realizar uma das seguintes ações:

  • Responda a um comando de barra. Por exemplo, se um usuário invocar o comando de barra /about do app do Chat em um espaço, o app do Chat poderá responder com uma mensagem privada explicando o que o app do Chat faz e como usá-lo.
  • Notificar ou enviar informações relevantes apenas para um usuário. Por exemplo, notifique um usuário de que uma tarefa foi atribuída a ele ou lembre-o de concluir a tarefa.
  • Envie uma mensagem de erro. Por exemplo, se um usuário omitir texto de argumento obrigatório em um comando de barra, o app do Chat poderá enviar uma mensagem privada para explicar o erro e ajudar o usuário a formatar o comando.

Quando um app do Chat envia uma mensagem privada, ela mostra um marcador que notifica o usuário de que a mensagem só está visível para ele:

Mensagem particular para o app Chat da Cymbal Labs. A mensagem diz que o app foi criado pela Cymbal Labs e compartilha um link para a documentação e outro para contato com a equipe de suporte.
Figura 1: quando um app de chat envia uma mensagem privada, o usuário vê uma mensagem com um rótulo que diz Only visible to you.

Pré-requisitos

Node.js

Observação: as amostras de código do Node.js neste guia foram criadas para execução como uma função do Google Cloud.

Python

Observação: as amostras de código Python neste guia foram escritas para serem executadas como uma função do Google Cloud usando Python 3.10.

Apps Script

Envie uma mensagem privada

Para enviar uma mensagem particular como um app do Chat, especifique o campo privateMessageViewer na mensagem ao criá-la. Você cria as mensagens particulares da mesma forma que cria qualquer mensagem: respondendo a uma interação do usuário ou chamando de maneira assíncrona o método create() da API Google Chat no recurso Message. Para saber como enviar mensagens de texto ou com cards, consulte Enviar uma mensagem.

O exemplo a seguir mostra o JSON de uma mensagem de texto privada que diz Hello private world!:

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

Neste exemplo, USER representa o usuário do Chat que pode visualizar a mensagem, formatado como um recurso User. Se estiver respondendo a uma interação do usuário, você poderá especificar o objeto User do evento de interação. Veja um exemplo na seção a seguir Responder de forma particular a um comando de barra.

Caso contrário, para especificar o visualizador de uma mensagem privada, use o campo name do recurso User:

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

Neste exemplo, você usa o campo name para especificar o nome do recurso User do leitor no Google Chat. Substitua USER_ID por um ID exclusivo do usuário, como 12345678987654321 ou hao@cymbalgroup.com.

Para mais informações sobre como especificar usuários, consulte Identificar e especificar usuários do Google Chat.

Responda particular a um comando de barra

O código a seguir mostra um exemplo de um app de chat que responde a um comando de barra com uma mensagem privada.

O app do Chat processa um evento de interação MESSAGE e responde ao comando de barra /help com uma mensagem de texto privada que explica como usá-lo:

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.',
  }

Limitações

Para enviar uma mensagem privada, ela não pode conter nem usar o seguinte:

  • Anexos.
  • Ações complementares:
  • Mensagens parcialmente particulares. Por exemplo, um app de chat não pode enviar uma mensagem com texto e um card em que o texto é visível apenas para um usuário, mas o card fica visível para todos no espaço.
  • Autenticação do usuário: Somente os apps do Chat podem enviar mensagens privadas. Portanto, seu app do Chat não pode ser autenticado como usuário para enviar uma mensagem privada.

Atualizar ou excluir mensagens privadas

Para atualizar ou excluir mensagens do Google Chat, chame a API Chat. Não é possível mudar o visualizador da mensagem privada nem torná-la pública. Portanto, quando você atualiza mensagens privadas, precisa omitir o campo privateMessageViewer na chamada de API (o campo é apenas de saída).

Para atualizar uma mensagem privada, consulte Atualizar uma mensagem. Para excluir uma mensagem privada, consulte Excluir uma mensagem.