Enviar mensagens privadas para usuários do Google Chat

Esta página explica como criar e enviar mensagens privadas como um app Google Chat.

Uma mensagem privada é uma mensagem do app do Chat destinada apenas visível para um usuário especificado do Chat. Você pode usar as mensagens privadas espaços com várias pessoas para que elas possam interagir de forma particular com Apps de chat Por exemplo, seu O app do Chat pode enviar mensagens de forma privada para fazer qualquer seguintes:

  • Responda a um comando de barra. Por exemplo, se um usuário invoca a barra /about do app do Chat em um espaço, o app do Chat pode responder com uma mensagem privada que explica o que o app do Chat faz e como usá-lo.
  • Notificar ou enviar informações que só são relevantes para um usuário. Para por exemplo, notificar um usuário de que uma tarefa foi atribuída a ele ou lembrá-lo para concluir a tarefa.
  • Enviar uma mensagem de erro. Por exemplo, se um usuário omitir o texto de argumento obrigatório para um comando de barra, o app do Chat pode enviar mensagem privada para explicar o erro e ajudar o usuário a formatar o comando.
  • Envie uma mensagem privada de boas-vindas a um usuário quando ele for adicionado a um espaço. explica as diretrizes ou como usar o app do Chat.

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 App Chat da Cymbal Labs. A mensagem diz que O app do Chat foi criado pela Cymbal Labs e compartilha um link a documentação e um link para entrar em contato com a equipe de suporte.
Figura 1: quando um app do Chat envia uma mensagem privada, o usuário vê uma mensagem com um marcador que diz Only visible to you.

Pré-requisitos

Node.js

Python

Apps Script

Enviar uma mensagem privada

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

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

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

Neste exemplo, USER representa o usuário do Chat. quem pode ver a mensagem, formatado como um User. Se você responder a uma interação do usuário, especifique o objeto User do evento de interação. Para ver um exemplo, consulte a seção a seguir Responder de maneira particular a um comando de barra.

Caso contrário, para especificar o visualizador de uma mensagem privada, você pode usar o método Campo name do User recurso:

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

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

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

Responder de maneira particular a um comando de barra

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

O app do Chat processa Evento de interação MESSAGE e responde ao comando de barra /help com uma mensagem de texto particular 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 ou usar o prefixo seguintes:

  • Anexos.
  • Ações de acessórios.
  • Mensagens parcialmente privadas. Por exemplo, um app do Chat não é possível enviar uma mensagem com texto e um cartão que fique visível somente para um usuário, mas o card fica visível para todos no espaço.
  • Autenticação de usuários: Só apps de chat podem enviar mensagens privadas. Portanto, O app do Chat não consegue se autenticar como usuário para enviar uma enviar uma mensagem privada.

Atualizar ou excluir mensagens privadas

Para atualizar ou excluir mensagens do Google Chat, chame o método API Chat. Não é possível alterar o visualizador da mensagem privada ou criar e tornar a mensagem pública. Portanto, ao atualizar mensagens privadas, você precisa omitir o campo privateMessageViewer na chamada de API (o campo é apenas a saída);

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