Este guia explica como chamar o método
messages.create()
para realizar uma das seguintes ações:
- Envie mensagens com texto, cards e widgets interativos.
- Envie mensagens particulares para um usuário específico do Chat.
- Inicie ou responda a uma conversa.
- 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 o método messages.create()
, os apps do Chat
pode 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 do Chat podem usar outros
Tipos de recursos de mensagens, incluindo caixas de diálogo interativas e visualização de links
do Google Cloud. Para responder a um usuário, o app do Chat retorna
a mensagem de maneira síncrona, sem chamar a API Chat. Para saber
sobre como enviar mensagens para responder a interações, consulte
Receber e responder a interações com seu app do Google Chat.
Como o Chat exibe e atribui mensagens criadas com a API Chat
Você pode chamar o método messages.create()
usando
autenticação de apps
e a autenticação de usuários.
O Chat atribui o remetente da mensagem de forma diferente
dependendo do tipo de autenticação usado.
Quando você autentica como o app do Chat, o app do Chat envia a mensagem.
App
ao lado do nome.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 do 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 em rich text, interfaces baseadas em cartões 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 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.
- Instale o Node.js biblioteca de cliente do Cloud.
- Crie credenciais de acesso com base em como você quer autenticar sua API Google Chat
solicitação:
- Para autenticar como um usuário do Chat, faça o seguinte:
criar ID do cliente OAuth
credenciais e salvá-las 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
credenciais e salvá-las como um arquivo JSON chamado
credentials.json
- Para autenticar como um usuário do Chat, faça o seguinte:
criar ID do cliente OAuth
credenciais e salvá-las 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 chama o app do Chat. Para autenticar como o Chat, adicione o App do Chat no 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. o ícone e a descrição do app do Chat.
- Instale o Python biblioteca de cliente do Cloud.
- Crie credenciais de acesso com base em como você quer autenticar sua API Google Chat
solicitação:
- Para autenticar como um usuário do Chat, faça o seguinte:
criar ID do cliente OAuth
credenciais e salvá-las 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
credenciais e salvá-las como um arquivo JSON chamado
credentials.json
- Para autenticar como um usuário do Chat, faça o seguinte:
criar ID do cliente OAuth
credenciais e salvá-las 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 chama 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 permissão OAuth.
- Ative e configure a API Google Chat com um nome. o ícone e a descrição do app do Chat.
- Instale o Java biblioteca de cliente do Cloud.
- Crie credenciais de acesso com base em como você quer autenticar sua API Google Chat
solicitação:
- Para autenticar como um usuário do Chat, faça o seguinte:
criar ID do cliente OAuth
credenciais e salvá-las 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
credenciais e salvá-las como um arquivo JSON chamado
credentials.json
- Para autenticar como um usuário do Chat, faça o seguinte:
criar ID do cliente OAuth
credenciais e salvá-las 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 chama o app do Chat. 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 Google Chat.
- 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 chama o app do Chat. Para autenticar como o Chat, adicione o App do Chat no espaço.
Enviar uma mensagem pelo app do 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 messages.create()
usando a autenticação do app, especifique o
campos a seguir da solicitação:
- O escopo da autorização
chat.bot
. - O recurso
Space
em que em que você quer postar a mensagem. O app do Chat precisa ser como 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.
Opcionalmente, você pode incluir o seguinte:
- O campo
accessoryWidgets
a ser incluído botões interativos na parte inferior da mensagem. - O campo
privateMessageViewer
para envie a mensagem anonimamente para um usuário específico. - O campo
messageId
, que permite nomeie a mensagem para usar em outras solicitações da API. - Os campos
thread.threadKey
emessageReplyOption
a 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 podem enviar uma mensagem postada pelo app do Chat que contenha texto, um cartão 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
Método spaces.list()
ou pelo URL do espaço.
Adicionar widgets interativos na parte inferior de uma mensagem
No primeiro exemplo de código deste guia, A mensagem do app do Chat exibe um botão clicável na parte conhecido como widget de acessórios, na parte de baixo da mensagem. 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.
- Denuncie um problema com a mensagem ou com o app do Chat.
- Abre um link para conteúdo relacionado, como a documentação.
- Dispensar ou adiar mensagens semelhantes no 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.
![Widget de acessórios.](https://developers-dot-devsite-v2-prod.appspot.com/static/workspace/chat/images/message-accessory-widgets-reference.png?authuser=2&hl=pt)
O exemplo a seguir mostra o corpo da solicitação que cria uma mensagem de texto com
dois botões acessórios. 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 O app do Chat envia uma mensagem particular, a mensagem mostra um marcador que notifica o usuário de que a mensagem só é visível para ele.
Para enviar uma mensagem privada usando a API Chat, especifique o
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
name
do
User
, conforme mostrado no exemplo a seguir:
{
text: "Hello private world!",
privateMessageViewer: {
name: "users/USER_ID"
}
}
Para usar esta amostra, substitua 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.
Para enviar uma mensagem privada, você precisa omitir 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 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 messages.create()
usando a autenticação do usuário, especifique o
campos a seguir 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 recurso
Space
em que em que você quer postar a mensagem. O usuário autenticado precisa ser um membro do espaço. - O
Message
recurso a ser criado. Para definir o conteúdo da mensagem, você deve incluir o prefixotext
.
Opcionalmente, você pode incluir o seguinte:
- O campo
messageId
, que permite nomeie a mensagem para usar em outras solicitações da API. - Os campos
thread.threadKey
emessageReplyOption
a 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 podem 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
. Você pode obter o ID chamando o
Método spaces.list()
ou pelo URL do espaço.
Iniciar ou responder em uma conversa
Para espaços que usam linhas de execução, faça o seguinte: você pode especificar se uma nova mensagem inicia uma conversa ou se responde em um thread 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 responda a uma conversa:
- No corpo da solicitação, inclua o campo
thread
. Se definido, é possível especifiquethreadKey
que você criou. Caso contrário, você deve usar o métodoname
do thread. - Especifique o parâmetro de consulta
messageReplyOption
.
O código abaixo 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 existente no espaço; ou para criar uma nova linha de execução, com um nome exclusivo para ela.SPACE_NAME
: o ID do espaço.name
. Você pode obter o ID chamando o Métodospaces.list()
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 messages.create()
.
Ao nomear sua mensagem, você pode especificá-la sem precisar armazenar o
um ID atribuído pelo sistema a partir do nome do recurso da mensagem (representado no
name
).
Por exemplo, para recuperar uma mensagem com o método get()
, use o
nome do recurso para especificar qual mensagem será recuperada. 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
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 valor válido ID, 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 do 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 determinado espaço em nome de uma usuário autenticado:
Node.js
Python
Java
Apps Script
Para executar este exemplo, substitua o seguinte:
SPACE_NAME
: o ID do espaço.name
. Você pode obter o ID chamando o Métodospaces.list()
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 do 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 você a corrigir os erros quando a geração de registros de erros nos apps do Chat está ativada. Para receber ajuda com a visualização, depurar e corrigir erros, consulte Resolver problemas 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 sobre uma mensagem.
- Listar mensagens em um espaço
- Atualizar uma mensagem.
- Excluir uma mensagem.
- Identificar usuários nas mensagens do Google Chat
- Enviar mensagens para o Google Chat com webhooks de entrada.