Este guia explica como usar o método
create()
no recurso Message
da API Google Chat para fazer o seguinte:
- Enviar mensagens com texto, cards e widgets interativos.
- Enviar mensagens particulares para um usuário específico do Chat.
- Iniciar ou responder a uma conversa.
- Nomeie uma mensagem para poder especificar em outras solicitações da API Chat.
O tamanho máximo da mensagem (incluindo texto ou cards) é de 32.000 bytes. Para enviar uma mensagem que exceda esse tamanho, o app do Chat precisa enviar várias mensagens.
Além de chamar a API Chat para criar mensagens, os apps do Chat podem criar e enviar mensagens para responder às interações do usuário, como postar uma mensagem de boas-vindas depois que um usuário adiciona o app do Chat a um espaço. Ao responder a interações, os apps de chat podem usar outros tipos de recursos de mensagens, incluindo caixas de diálogo interativas e interfaces de visualização de link. Para responder a um usuário, o app do Chat retorna a mensagem de forma síncrona, sem chamar a API Chat. Para saber como enviar mensagens para responder a interações, consulte Receber e responder a interações com o app Google Chat.
Como o Chat exibe e atribui mensagens criadas com a API Chat
É possível chamar o método create()
usando
a autenticação do app
e a autenticação do usuário.
O Chat atribui o remetente da mensagem de maneira diferente,
dependendo do tipo de autenticação que você usa.
Quando você faz a autenticação como o app Chat, ele envia a mensagem.
Quando você faz a autenticação como usuário, o app do Chat envia a mensagem em nome do usuário. O Chat também atribui o app Chat à mensagem mostrando o nome dele.
O tipo de autenticação também determina quais recursos e interfaces de mensagens podem ser incluídos na mensagem. Com a autenticação de app, os apps de chat podem enviar mensagens que contêm texto enriquecido, interfaces baseadas em cards e widgets interativos. Como os usuários do Chat só podem enviar texto nas mensagens, só é possível incluir texto ao criar mensagens usando a autenticação do usuário. Para saber mais sobre os recursos de mensagens disponíveis para a API Chat, consulte a Visão geral das mensagens do Google Chat.
Este guia explica como usar qualquer tipo de autenticação para enviar uma mensagem com a API Chat.
Pré-requisitos
Node.js
- Uma conta do Google Workspace para empresas ou empresas com acesso ao Google Chat.
- Configure o ambiente:
- Crie um projeto do Google Cloud.
- Configure a tela de consentimento OAuth.
- Ative e configure a API Google Chat com um nome, ícone e descrição para seu app do Chat.
- Instale a biblioteca de cliente do Cloud para Node.js.
- Crie credenciais de acesso com base na forma como você quer se autenticar na solicitação da API Google Chat:
- Para fazer a autenticação como um usuário do Chat,
crie credenciais de ID do cliente do OAuth e salve-as como um arquivo JSON chamado
client_secrets.json
no seu diretório local. - Para fazer a autenticação como o app de chat,
crie credenciais da conta de serviço e salve-as como um arquivo JSON chamado
credentials.json
.
- Para fazer a autenticação como um usuário do Chat,
crie credenciais de ID do cliente do OAuth e salve-as como um arquivo JSON chamado
- Escolha um escopo de autorização com base em se você quer autenticar como um usuário ou o app Chat.
- Um espaço do Google Chat em que o usuário autenticado ou o app de chat que está ligando é membro. Para fazer a autenticação como o app de chat, adicione o app de chat ao espaço.
Python
- Uma conta do Google Workspace para empresas ou empresas com acesso ao Google Chat.
- Configure o ambiente:
- Crie um projeto do Google Cloud.
- Configure a tela de consentimento OAuth.
- Ative e configure a API Google Chat com um nome, ícone e descrição para seu app do Chat.
- Instale a biblioteca de cliente do Cloud para Python.
- Crie credenciais de acesso com base na forma como você quer se autenticar na solicitação da API Google Chat:
- Para fazer a autenticação como um usuário do Chat,
crie credenciais de ID do cliente do OAuth e salve-as como um arquivo JSON chamado
client_secrets.json
no seu diretório local. - Para fazer a autenticação como o app de chat,
crie credenciais da conta de serviço e salve-as como um arquivo JSON chamado
credentials.json
.
- Para fazer a autenticação como um usuário do Chat,
crie credenciais de ID do cliente do OAuth e salve-as como um arquivo JSON chamado
- Escolha um escopo de autorização com base em se você quer autenticar como um usuário ou o app Chat.
- Um espaço do Google Chat em que o usuário autenticado ou o app de chat que está ligando é membro. Para fazer a autenticação como o app de chat, adicione o app de chat ao espaço.
Java
- Uma conta do Google Workspace para empresas ou empresas com acesso ao Google Chat.
- Configure o ambiente:
- Crie um projeto do Google Cloud.
- Configure a tela de consentimento OAuth.
- Ative e configure a API Google Chat com um nome, ícone e descrição para seu app do Chat.
- Instale a biblioteca de cliente do Cloud para Java.
- Crie credenciais de acesso com base na forma como você quer se autenticar na solicitação da API Google Chat:
- Para fazer a autenticação como um usuário do Chat,
crie credenciais de ID do cliente do OAuth e salve-as como um arquivo JSON chamado
client_secrets.json
no seu diretório local. - Para fazer a autenticação como o app de chat,
crie credenciais da conta de serviço e salve-as como um arquivo JSON chamado
credentials.json
.
- Para fazer a autenticação como um usuário do Chat,
crie credenciais de ID do cliente do OAuth e salve-as como um arquivo JSON chamado
- Escolha um escopo de autorização com base em se você quer autenticar como um usuário ou o app Chat.
- Um espaço do Google Chat em que o usuário autenticado ou o app de chat que está ligando é membro. Para fazer a autenticação como o app de chat, adicione o app de chat ao espaço.
Apps Script
- Uma conta do Google Workspace para empresas ou empresas com acesso ao Google Chat.
- Configure o ambiente:
- Crie um projeto do Google Cloud.
- Configure a tela de consentimento OAuth.
- Ative e configure a API Google Chat com um nome, ícone e descrição para seu app do Chat.
- Crie um projeto independente do Apps Script e ative o Serviço avançado de chat.
- Neste guia, você precisa usar a autenticação do usuário ou do app. Para autenticar como o app de chat, crie credenciais de conta de serviço. Para conferir as etapas, consulte Autenticar e autorizar como um app do Google Chat.
- Escolha um escopo de autorização com base em se você quer autenticar como um usuário ou o app Chat.
- Um espaço do Google Chat em que o usuário autenticado ou o app de Chat que está ligando é membro. Para fazer a autenticação como o app de chat, adicione o app de chat ao espaço.
Enviar uma mensagem como o app Chat
Esta seção explica como enviar mensagens que contêm texto, cards e widgets de acessório interativo usando a autenticação de app.
Para chamar o método CreateMessage()
usando a autenticação do app, especifique os seguintes campos na
solicitação:
- O
chat.bot
escopo de autorização. - O recurso
Space
em que você quer postar a mensagem. O app de chat precisa ser um participante do espaço. - O recurso
Message
a ser criado. Para definir o conteúdo da mensagem, é possível incluir texto formatado (text
), uma ou mais interfaces de card (cardsV2
) ou ambos.
Também é possível incluir o seguinte:
- O campo
accessoryWidgets
para incluir botões interativos na parte de baixo da mensagem. - O campo
privateMessageViewer
para enviar a mensagem de forma privada a um usuário específico. - O campo
messageId
, que permite nomear a mensagem para usar em outras solicitações de API. - Os campos
thread.threadKey
emessageReplyOption
para iniciar ou responder a uma conversa. Se o espaço não usar a linha de execução, esse campo será ignorado.
O código a seguir mostra um exemplo de como um app de chat pode enviar uma mensagem postada como o app de chat que contém texto, um card e um botão clicável na parte de baixo da mensagem:
Node.js
Python
Java
Apps Script
Para executar este exemplo, substitua SPACE_NAME
pelo ID do campo
name
do espaço. Você pode conseguir o ID chamando o método
ListSpaces()
ou pelo URL do espaço.
Adicionar widgets interativos na parte de baixo de uma mensagem
No primeiro exemplo de código deste guia, a mensagem do app de chat mostra um botão clicável na parte de baixo da mensagem, conhecido como widget de acessório. Os widgets de acessório aparecem depois de qualquer texto ou card em uma mensagem. Você pode usar esses widgets para pedir que os usuários interajam com sua mensagem de várias maneiras, incluindo:
- Avalie a precisão ou satisfação de uma mensagem.
- Denunciar um problema com a mensagem ou o app Chat.
- Abrir um link para conteúdo relacionado, como documentação.
- Descartar ou adiar mensagens semelhantes do app Chat por um período específico.
Para adicionar widgets acessórios, inclua o campo
accessoryWidgets[]
no corpo da solicitação e especifique um ou mais widgets que você quer
incluir.
A imagem a seguir mostra um app de chat que anexa uma mensagem de texto com widgets acessórios para que os usuários possam avaliar a experiência com o app de chat.
O exemplo a seguir mostra o corpo da solicitação que cria uma mensagem de texto com
dois botões de acessório. Quando um usuário clica em um botão, a função
correspondente (como doUpvote
) processa a interação:
{
text: "Rate your experience with this Chat app.",
accessoryWidgets: [{ buttonList: { buttons: [{
icon: { material_icon: {
name: "thumb_up"
}},
color: { red: 0, blue: 255, green: 0 },
onClick: { action: {
function: "doUpvote"
}}
}, {
icon: { material_icon: {
name: "thumb_down"
}},
color: { red: 0, blue: 255, green: 0 },
onClick: { action: {
function: "doDownvote"
}}
}]}}]
}
Enviar uma mensagem particular
Os apps de chat podem enviar mensagens particulares para que elas fiquem visíveis apenas para um usuário específico no espaço. Quando um app de chat envia uma mensagem privada, ela mostra um rótulo que notifica o usuário de que a mensagem só está visível para ele.
Para enviar uma mensagem particular usando a API Chat, especifique o campo
privateMessageViewer
no corpo da solicitação. Para especificar o usuário, defina o valor como o recurso
User
que representa o usuário do Chat. Também é possível usar o campo
name
do recurso User
, conforme mostrado no exemplo a seguir:
{
text: "Hello private world!",
privateMessageViewer: {
name: "users/USER_ID"
}
}
Para usar este exemplo, 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.
Para enviar uma mensagem particular, omita o seguinte na solicitação:
Enviar uma mensagem de texto em nome de um usuário
Esta seção explica como enviar mensagens em nome de um usuário usando a autenticação do usuário. Com a autenticação do usuário, o conteúdo da mensagem só pode conter texto e precisa omitir recursos de mensagens que estão disponíveis apenas para apps de chat, incluindo interfaces de cards e widgets interativos.
Para chamar o método CreateMessage()
usando a autenticação do usuário, especifique
os seguintes campos na solicitação:
- Um escopo de autorização
que ofereça suporte à autenticação do usuário para esse método. O exemplo a seguir usa
o escopo
chat.messages.create
. - O recurso
Space
em que você quer postar a mensagem. O usuário autenticado precisa ser um participante do espaço. - O recurso
Message
a ser criado. Para definir o conteúdo da mensagem, é necessário incluir o campotext
.
Também é possível incluir o seguinte:
- O campo
messageId
, que permite nomear a mensagem para usar em outras solicitações de API. - Os campos
thread.threadKey
emessageReplyOption
para iniciar ou responder a uma conversa. Se o espaço não usar a linha de execução, esse campo será ignorado.
O código a seguir mostra um exemplo de como um app de chat pode enviar uma mensagem de texto em um determinado espaço em nome de um usuário autenticado:
Node.js
Python
Java
Apps Script
Para executar este exemplo, substitua SPACE_NAME
pelo ID do campo
name
do espaço. Você pode conseguir o ID chamando o método
ListSpaces()
ou pelo URL do espaço.
Iniciar ou responder a uma conversa
Em espaços que usam linhas de execução, é possível especificar se uma nova mensagem inicia uma linha de execução ou responde a uma existente.
Por padrão, as mensagens criadas usando a API Chat iniciam uma nova linha de execução. Para ajudar a identificar a linha de execução e responder a ela mais tarde, especifique uma chave de linha de execução na solicitação:
- No corpo da solicitação, especifique o campo
thread.threadKey
. - Especifique o parâmetro de consulta
messageReplyOption
para determinar o que acontece se a chave já existir.
Para criar uma mensagem que responde a uma conversa:
- No corpo da solicitação, inclua o campo
thread
. Se definido, é possível especificar othreadKey
criado. Caso contrário, use oname
da linha de execução. - Especifique o parâmetro de consulta
messageReplyOption
.
O código a seguir mostra um exemplo de como um app de chat pode enviar uma mensagem de texto que inicia ou responde a uma determinada linha de execução identificada pela chave de um determinado espaço em nome de um usuário autenticado:
Node.js
Python
Java
Apps Script
Para executar este exemplo, substitua o seguinte:
THREAD_KEY
: uma chave de linha de execução no espaço ou para criar uma nova linha de execução, um nome exclusivo para a linha de execução.SPACE_NAME
: o ID do camponame
do espaço. Você pode conseguir o ID chamando o métodoListSpaces()
ou pelo URL do espaço.
Nomear uma mensagem
Para recuperar ou especificar uma mensagem em chamadas de API futuras, você pode nomear uma mensagem
definindo o campo messageId
na solicitação.
Ao nomear a mensagem, você pode especificar a mensagem sem precisar armazenar o
ID atribuído pelo sistema no nome do recurso da mensagem (representado no
campo
name
).
Por exemplo, para extrair uma mensagem usando o método get()
, use o
nome do recurso para especificar qual mensagem extrair. O nome do recurso é
formatado como spaces/{space}/messages/{message}
, em que {message}
representa
o ID atribuído pelo sistema ou o nome personalizado definido ao criar a
mensagem.
Para nomear uma mensagem, especifique um ID personalizado no campo
messageId
ao criar a mensagem. O campo messageId
define o valor do campo
clientAssignedMessageId
do recurso Message
.
Só é possível nomear uma mensagem quando ela é criada. Não é possível nomear ou modificar um ID personalizado para mensagens existentes. O ID personalizado precisa atender aos seguintes requisitos:
- Começa com
client-
. Por exemplo,client-custom-name
é um ID personalizado válido, mascustom-name
não é. - Contém até 63 caracteres e apenas letras minúsculas, números e hifens.
- É exclusivo em um espaço. Um app de chat não pode usar o mesmo ID personalizado para mensagens diferentes.
O código abaixo mostra um exemplo de como um app de chat pode enviar uma mensagem de texto com um ID para um determinado espaço em nome de um usuário autenticado:
Node.js
Python
Java
Apps Script
Para executar este exemplo, substitua o seguinte:
SPACE_NAME
: o ID do camponame
do espaço. Você pode conseguir o ID chamando o métodoListSpaces()
ou pelo URL do espaço.MESSAGE-ID
: um nome para a mensagem que começa comcustom-
. Precisa ser exclusivo de qualquer outro nome de mensagem criado pelo app Chat no espaço especificado.
Resolver problemas
Quando um app do Google Chat ou um card retorna um erro, a interface do Chat mostra uma mensagem informando que "Ocorreu um erro". ou "Não foi possível processar sua solicitação". Às vezes, a interface do Chat não mostra nenhuma mensagem de erro, mas o app ou o card do Chat produz um resultado inesperado. Por exemplo, uma mensagem de card pode não aparecer.
Embora uma mensagem de erro possa não aparecer na interface do Chat, mensagens de erro descritivas e dados de registro estão disponíveis para ajudar a corrigir erros quando o registro de erros para apps de chat estiver ativado. Para saber como visualizar, depurar e corrigir erros, consulte Resolver e corrigir erros do Google Chat.
Temas relacionados
- Use o Card Builder para projetar e visualizar mensagens de cards JSON para apps de chat.
- Formatar mensagens.
- Conferir detalhes sobre uma mensagem.
- Listar mensagens em um espaço.
- Atualizar uma mensagem.
- Excluir uma mensagem.
- Identifique usuários nas mensagens do Google Chat.
- Enviar mensagens para o Google Chat com webhooks de entrada.