Este guia explica como usar o
create()
no recurso Message
da API Google Chat para realizar uma das seguintes ações:
- Enviar mensagens com texto, cards e widgets interativos.
- Envie mensagens particulares para um usuário específico do Chat.
- Iniciar ou responder a uma conversa de mensagens.
- Nomeie uma mensagem para especificá-la em outra API Chat solicitações.
O tamanho máximo da mensagem (incluindo qualquer texto ou cartão) é 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, como caixas de diálogo interativas e interfaces de visualização de links. 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
Você pode chamar o método create()
usando
autenticação de apps
e a autenticação de usuários.
O Chat atribui o remetente da mensagem de maneira diferente,
dependendo do tipo de autenticação que você usa.
Quando você autentica como o app do Chat, o app do Chat envia a mensagem.
Quando você faz a autenticação como usuário, o app do Chat envia o 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 para incluir na mensagem. Com a autenticação de apps, os apps de chat podem enviar mensagens com texto rico, interfaces baseadas em cards e widgets interativos. Como os usuários do Chat só podem enviar texto nas mensagens, você pode: incluir texto apenas ao criar mensagens usando a autenticação do usuário. Para saber mais sobre mensagens recursos disponíveis para a API Chat, consulte o 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 para empresas ou empresas com acesso ao Google Chat.
- Configure o ambiente:
- Crie um projeto do Google Cloud.
- Configure a tela de permissão 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 em como você quer autenticar na API Google Chat
solicitação:
- Para autenticar como um usuário do Chat, faça o seguinte:
criar ID do cliente OAuth
credentials e salve-as como um arquivo JSON chamado
client_secrets.json
ao diretório local. - Para autenticar como o app do Chat, faça o seguinte:
criar conta de serviço
credentials e salve-as como um arquivo JSON chamado
credentials.json
- Para autenticar como um usuário do Chat, faça o seguinte:
criar ID do cliente OAuth
credentials 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 que chamou o app do Chat. Para fazer a autenticação como o app de chat, adicione o app de chat ao espaço.
Python
- Uma empresa Conta do Google Workspace com acesso a Google Chat.
- Configure o ambiente:
- Crie um projeto do Google Cloud.
- Configure a tela de permissão OAuth.
- Ative e configure a API Google Chat com um nome, ícone e descrição para seu app do Chat.
- Instale o Python biblioteca de cliente do Cloud.
- Crie credenciais de acesso com base em como você quer autenticar na API Google Chat
solicitação:
- 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 autenticar como o app do Chat, faça o seguinte:
criar conta de serviço
credentials 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 para autenticar como usuário ou como App Chat.
- Um espaço do Google Chat em que o usuário autenticado ou que chamou o app do Chat. Para autenticar como o Chat, adicione o App do Chat no espaço.
Java
- Uma empresa Conta do Google Workspace com acesso a 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 o Java biblioteca de cliente do Cloud.
- 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, faça o seguinte:
criar ID do cliente OAuth
credentials e salve-as como um arquivo JSON chamado
client_secrets.json
ao 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 autenticar como um usuário do Chat, faça o seguinte:
criar ID do cliente OAuth
credentials e salve-as como um arquivo JSON chamado
- Escolha um escopo de autorização para autenticar como usuário ou como App Chat.
- Um espaço do Google Chat em que o usuário autenticado ou o app de chat que está ligando é membro. Para autenticar como o Chat, adicione o App do Chat no espaço.
Apps Script
- Uma empresa Conta do Google Workspace com acesso a Google Chat.
- Configure o ambiente:
- Crie um projeto do Google Cloud.
- Configure a tela de permissão OAuth.
- Ative e configure a API Google Chat com um nome. o ícone e a descrição do app do Chat.
- Crie um projeto independente do Apps Script, e ative o serviço avançado de chat.
- Neste guia, você deve usar as funções de usuário ou autenticação de apps. Para autenticar como o app do Chat, crie credenciais da 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 autenticar como o Chat, adicione o App do Chat no espaço.
Enviar uma mensagem como o app Chat
Esta seção explica como enviar mensagens que contenham texto, cards e widgets de acessórios interativos usando autenticação de apps.
Para chamar o método CreateMessage()
usando a autenticação do aplicativo, é necessário especificar os seguintes campos na
solicitação:
- O
chat.bot
escopo de autorização. - O
Space
o recurso em que você quer postar a mensagem. O app de chat precisa ser um participante do espaço. - O
Message
recurso a ser criado. Para definir o conteúdo da mensagem, você pode incluir rich text (text
), Uma ou mais interfaces de cartão (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 envie a mensagem anonimamente para 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 esta amostra, substitua SPACE_NAME
pelo ID de
do espaço
name
. Você pode obter o ID chamando o
ListSpaces()
ou do 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. Widgets de acessórios aparecem depois de textos ou cards em uma mensagem. Você pode usar esses widgets para enviar 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.
- Abre um link para conteúdo relacionado, como a documentação.
- Descartar ou adiar mensagens semelhantes do app Chat por um período específico.
Para adicionar widgets de acessórios, inclua o
accessoryWidgets[]
no corpo da solicitação e especificar um ou mais widgets que você quer
incluir.
A imagem a seguir mostra um app do Chat que anexa Uma mensagem de texto com widgets de acessórios para que os usuários possam avaliar a experiência com o app 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, o anúncio
(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 privada
Os apps de chat podem enviar mensagens de forma particular para que é visível apenas para um usuário específico no espaço. Quando um app de chat envia uma mensagem particular, ela mostra um rótulo que notifica o usuário de que a mensagem só é 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, você define o valor como
as
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 o autenticação do usuário. Com a autenticação do usuário, o conteúdo da mensagem só pode conter texto e precisam omitir os recursos de mensagens que estão disponíveis apenas 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 da solicitação:
- Um escopo de autorização
que oferece suporte à autenticação de usuário para este método. O exemplo a seguir usa
o escopo
chat.messages.create
. - O
Space
o recurso em que você quer postar a mensagem. O usuário autenticado precisa ser como participante do espaço. - O
Message
recurso a ser criado. Para definir o conteúdo da mensagem, você deve incluir o parâmetrotext
.
Também é possível incluir o seguinte:
- O campo
messageId
, que permite nomeie a mensagem para usar em outras solicitações da 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 esta amostra, substitua SPACE_NAME
pelo ID de
do espaço
name
. Para conseguir o ID, chame o método
ListSpaces()
ou o URL do espaço.
Iniciar ou responder em uma conversa
Para 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 que você cria usando a API Chat iniciam uma nova fio Para ajudar a identificar a conversa e responder a ela mais tarde, você pode especificar um chave de linha de execução em sua solicitação:
- No corpo da solicitação, especifique o
thread.threadKey
. - Especificar o parâmetro de consulta
messageReplyOption
para determinar o que acontecerá 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 especifiquethreadKey
que você 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 do Chat pode enviar uma mensagem de texto que inicia ou responde a uma conversa identificada pelo 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 ela.SPACE_NAME
: o ID do espaço.name
. Você pode obter o ID chamando oListSpaces()
ou do URL do espaço.
Nomear uma mensagem
Para recuperar ou especificar uma mensagem em chamadas de API futuras, é possível nomear uma mensagem
definindo o campo messageId
na solicitação.
Ao nomear sua mensagem, você pode especificá-la sem precisar armazenar o
ID atribuído pelo sistema a partir do nome do recurso da mensagem (representado no
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 que você definiu quando criou o
mensagem.
Para nomear uma mensagem, especifique um ID personalizado no campo
messageId
ao criar a mensagem. O campo messageId
define o valor da
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 hífens.
- É exclusivo em um espaço. Um app do 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 obter o ID chamando oListSpaces()
ou do URL do espaço.MESSAGE-ID
: um nome para a mensagem que começa comcustom-
. Precisa ser exclusivo em relação a qualquer outro nome de mensagem criado pelo app Chat no espaço especificado.
Resolver problemas
Quando um app ou card retornar um erro, o A interface do chat mostra a mensagem "Algo deu errado". ou "Não foi possível processar sua solicitação". Às vezes, a interface do Chat não exibe nenhuma mensagem de erro, mas o app do Chat ou produz um resultado inesperado; por exemplo, uma mensagem de cartão 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 criador de cards para projetar e visualizar mensagens de cards JSON para apps de chat.
- Formatar mensagens.
- Ver detalhes de 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.