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:
Pré-requisitos
Node.js
- Um projeto do Google Cloud com a API Google Chat ativada e configurada. Veja as etapas em Criar um app do Google Chat.
- Para responder de maneira particular a um comando de barra, um comando de barra configurado para o app do Chat. Para criar uma, consulte Responder a comandos de barra.
- Para enviar uma mensagem privada usando o
método
messages.create()
, você precisa usar a autenticação de app.
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
- Um projeto do Google Cloud com a API Google Chat ativada e configurada. Veja as etapas em Criar um app do Google Chat.
- Para responder de maneira particular a um comando de barra, um comando de barra configurado para o app do Chat. Para criar uma, consulte Responder a comandos de barra.
- Para enviar uma mensagem privada usando o
método
messages.create()
, você precisa usar a autenticação de app.
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
- Um app do Chat. Para criar um app do Chat, siga este quickstart.
- Para responder de maneira particular a um comando de barra, um comando de barra configurado para o app do Chat. Para criar uma, consulte Responder a comandos de barra.
- Para enviar uma mensagem privada usando o
método
messages.create()
, você precisa usar a autenticação de app.
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.
Temas relacionados
- Enviar uma mensagem
- Identificar e especificar usuários do Google Chat
- Responder a comandos de barra
- Atualizar uma mensagem
- Excluir uma mensagem