Neste guia, explicamos 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.
- Envie mensagens privadas para um usuário específico do Chat.
- Inicie ou responda a uma conversa.
- Dê um nome a uma mensagem para que ela possa ser especificada 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 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 às 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 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 seu app do Google Chat.
Como o Chat mostra e atribui mensagens criadas com a API Chat
Você pode 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ê se autentica como o app Chat, ele envia a mensagem.
App
ao lado do nome dele.Quando você se autentica como um usuário, o app Chat envia a mensagem em nome dele. 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 apps, os apps do Chat podem enviar mensagens com rich text, interfaces baseadas em cards e widgets interativos. Como os usuários do Chat só podem enviar texto nas mensagens, você só pode incluir texto ao criar mensagens usando a autenticação de 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 um dos tipos de autenticação para enviar uma mensagem com a API Chat.
Pré-requisitos
Node.js
- Uma conta do Google Workspace Business ou Enterprise com acesso ao Google Chat.
- Configure seu ambiente:
- Crie um projeto do Google Cloud.
- Configure a tela de permissão OAuth.
- Ative e configure a API Google Chat com um nome, um ícone e uma descrição para seu app do Chat.
- Instale a biblioteca de cliente do Cloud do Node.js.
- Crie credenciais de acesso com base na forma como você quer se autenticar na solicitação da API Google Chat:
- Para autenticar como um usuário do Chat,
crie credenciais de ID do cliente OAuth e salve-as como um arquivo JSON chamado
credentials.json
no seu diretório local. - Para autenticar como o app Chat,
crie credenciais de
conta de serviço e salve-as como um arquivo JSON chamado
credentials.json
.
- Para autenticar como um usuário do Chat,
crie credenciais de ID do cliente 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 faz a chamada é um membro. Para autenticar como o app Chat, adicione o app Chat ao espaço.
Python
- Uma conta do Google Workspace Business ou Enterprise com acesso ao Google Chat.
- Configure seu ambiente:
- Crie um projeto do Google Cloud.
- Configure a tela de permissão OAuth.
- Ative e configure a API Google Chat com um nome, um ícone e uma descrição para seu app do Chat.
- Instale a biblioteca de cliente do Cloud Python.
- Crie credenciais de acesso com base na forma como você quer se autenticar na solicitação da API Google Chat:
- Para autenticar como um usuário do Chat,
crie credenciais de ID do cliente OAuth e salve-as como um arquivo JSON chamado
credentials.json
no seu diretório local. - Para autenticar como o app Chat,
crie credenciais de
conta de serviço e salve-as como um arquivo JSON chamado
credentials.json
.
- Para autenticar como um usuário do Chat,
crie credenciais de ID do cliente 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 faz a chamada é um membro. Para autenticar como o app Chat, adicione o app Chat ao espaço.
Java
- Uma conta do Google Workspace Business ou Enterprise com acesso ao Google Chat.
- Configure seu ambiente:
- Crie um projeto do Google Cloud.
- Configure a tela de permissão OAuth.
- Ative e configure a API Google Chat com um nome, um ícone e uma 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 autenticar como um usuário do Chat,
crie credenciais de ID do cliente OAuth e salve-as como um arquivo JSON chamado
credentials.json
no seu diretório local. - Para autenticar como o app Chat,
crie credenciais de
conta de serviço e salve-as como um arquivo JSON chamado
credentials.json
.
- Para autenticar como um usuário do Chat,
crie credenciais de ID do cliente 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 faz a chamada é um membro. Para autenticar como o app Chat, adicione o app Chat ao espaço.
Apps Script
- Uma conta do Google Workspace Business ou Enterprise com acesso ao Google Chat.
- Configure seu ambiente:
- Crie um projeto do Google Cloud.
- Configure a tela de permissão OAuth.
- Ative e configure a API Google Chat com um nome, um ícone e uma 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 de usuário ou de app. Para autenticar como o app Chat, crie credenciais de conta de serviço. Para ver 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 faz a chamada é um membro. Para autenticar como o app Chat, adicione o app 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órios interativos 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 escopo de autorização
chat.bot
. - O recurso
Space
em que você quer postar a mensagem. O app Chat precisa ser um participante do espaço. - O recurso
Message
a ser criado. Para definir o conteúdo da mensagem, você pode 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 linhas 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 no 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, conhecido como widget acessório. Os widgets de acessórios aparecem depois de qualquer texto ou cards em uma mensagem. Você pode usar esses widgets para pedir aos usuários que interajam com sua mensagem de várias maneiras, incluindo:
- Avalie a precisão ou a satisfação de uma mensagem.
- Informe um problema com a mensagem ou o app Chat.
- Abra um link para conteúdo relacionado, como documentação.
- Dispensar ou adiar mensagens semelhantes do app Chat por um período específico.
Para adicionar widgets de 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 do Chat que adiciona uma mensagem de texto com widgets de acessórios para que os usuários possam avaliar a experiência com o app do Chat.

A seguir, mostramos o corpo da solicitação que cria uma mensagem de texto com
dois botões de acessórios. 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 do Chat envia uma mensagem privada, ela mostra um indicador 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. Você também pode usar o campo
name
do recurso User
, conforme mostrado no exemplo a seguir:
{
text: "Hello private world!",
privateMessageViewer: {
name: "users/USER_ID"
}
}
Para usar essa amostra, 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 sua 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 disponíveis apenas para apps de chat, incluindo interfaces de card 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 oferece suporte à autenticação de usuários 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 membro do espaço. - O recurso
Message
a ser criado. Para definir o conteúdo da mensagem, inclua 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 linhas de execução, esse campo será ignorado.
O código a seguir mostra um exemplo de como um app do 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 no URL do espaço.
Iniciar ou responder em uma conversa
Para espaços que usam conversas, é possível especificar se uma nova mensagem inicia uma conversa ou responde a uma conversa existente.
Por padrão, as mensagens criadas com a API Chat iniciam uma nova thread. Para ajudar você a identificar e responder à conversa depois, especifique uma chave de conversa na sua 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 responda a uma conversa:
- No corpo da solicitação, inclua o campo
thread
. Se definido, você pode especificar othreadKey
que criou. 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 conversa identificada pela chave de um determinado espaço em nome de um usuário autenticado:
Node.js
Python
Java
Apps Script
Para executar esta amostra, substitua o seguinte:
THREAD_KEY
: uma chave de conversa existente no espaço ou para criar uma conversa, um nome exclusivo para ela.SPACE_NAME
: o ID do camponame
do espaço. Você pode conseguir o ID chamando o métodoListSpaces()
ou no URL do espaço.
Nomear uma mensagem
Para recuperar ou especificar uma mensagem em chamadas de API futuras, nomeie uma mensagem
definindo o campo messageId
na sua solicitação.
Ao nomear a mensagem, você pode especificá-la sem precisar armazenar o ID atribuído pelo sistema do 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 ao criá-la. Não é possível nomear ou modificar um ID personalizado para mensagens atuais. 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 hífens.
- É único em um espaço. Um app de chat não pode usar o mesmo ID personalizado para mensagens diferentes.
O código a seguir mostra um exemplo de como um app do Chat pode enviar uma mensagem de texto com um ID para um espaço específico em nome de um usuário autenticado:
Node.js
Python
Java
Apps Script
Para executar esta amostra, substitua o seguinte:
SPACE_NAME
: o ID do camponame
do espaço. Você pode conseguir o ID chamando o métodoListSpaces()
ou no URL do espaço.MESSAGE-ID
: um nome para a mensagem que começa comcustom-
. Precisa ser diferente de qualquer outro nome de mensagem criado pelo app Chat no espaço especificado.
Resolver problemas
Quando um app ou card do Google Chat retorna um erro, a interface do Chat mostra a mensagem "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 card do Chat produz um resultado inesperado. Por exemplo, uma mensagem do card pode não aparecer.
Embora uma mensagem de erro não apareça na interface do Chat, mensagens de erro descritivas e dados de registro estão disponíveis para ajudar você a corrigir erros quando o registro de erros para apps do Chat está ativado. Para ajuda com a visualização, depuração e correção de erros, consulte Resolver e corrigir erros do Google Chat.
Temas relacionados
- Use o Card Builder para criar e visualizar mensagens de card JSON para apps do Chat.
- Formatar mensagens.
- Receber detalhes sobre uma mensagem.
- Listar mensagens em um espaço.
- Atualizar uma mensagem.
- Excluir uma mensagem.
- Identificar usuários em mensagens do Google Chat.
- Enviar mensagens para o Google Chat com webhooks de entrada.