Este guia explica as diferentes maneiras como os apps do Google Chat podem enviar mensagens mensagens:
- Envie mensagens de texto e de card em tempo real respondendo a um usuário interação.
- Envie mensagens de texto e de cartão de forma assíncrona chamando o método
create
em o recursoMessage
. - Inicie ou responda a uma conversa.
- Envie e nomeie uma mensagem.
O
Recurso Message
representa um
texto
ou
cartão
no Google Chat. Você pode
create
, get
, update
ou delete
uma mensagem na API Google Chat chamando
métodos correspondentes. Para saber mais sobre mensagens de texto e de card, consulte
Visão geral das mensagens do Google Chat.
O tamanho máximo da mensagem (incluindo qualquer texto ou cartão) é de 32.000 bytes. Se uma mensagem exceder esse tamanho, o app do Chat pode enviar várias mensagens.
Em vez de chamar o método create
no recurso Message
da
a API Google Chat envie uma mensagem de texto ou card de forma assíncrona;
Os apps do Google Chat também podem criar mensagens para responder às interações dos usuários
tempo real. As respostas às interações do usuário não exigem autenticação e
suporte a outros tipos de mensagens, incluindo caixas de diálogo interativas e links
visualizações prévias. Para mais detalhes, consulte
Receber e responder a interações com seu app do Google Chat.
Pré-requisitos
Node.js
- Um app do Google Chat. Para criar um app do Chat: usando um serviço HTTP, conclua este guia de início rápido.
- Autorização configurada para envio pelo app do Chat
mensagens assíncronas. Nenhuma configuração de autorização é necessária para enviar
mensagens em tempo real.
- O envio de uma
mensagem de texto
oferece suporte aos dois métodos de autorização a seguir:
- Autenticação de usuários
com a autorização
chat.messages.create
ouchat.messages
do projeto. - Autenticação de apps
com o escopo de autorização
chat.bot
.
- Autenticação de usuários
com a autorização
- O envio de uma
mensagem do cartão
exige
autenticação de apps
com o escopo de autorização
chat.bot
.
- O envio de uma
mensagem de texto
oferece suporte aos dois métodos de autorização a seguir:
Python
- Um app do Google Chat. Para criar um app do Chat: usando um serviço HTTP, conclua este guia de início rápido.
- Autorização configurada para envio pelo app do Chat
mensagens assíncronas. Nenhuma configuração de autorização é necessária para enviar
mensagens em tempo real.
- O envio de uma
mensagem de texto
oferece suporte aos dois métodos de autorização a seguir:
- Autenticação de usuários
com a autorização
chat.messages.create
ouchat.messages
do projeto. - Autenticação de apps
com o escopo de autorização
chat.bot
.
- Autenticação de usuários
com a autorização
- O envio de um
mensagem do cartão
exige
autenticação de apps
com o escopo de autorização
chat.bot
.
- O envio de uma
mensagem de texto
oferece suporte aos dois métodos de autorização a seguir:
Apps Script
- Um app do Google Chat. Para criar um app do Chat: no Apps Script, conclua guia de início rápido.
- Autorização configurada para envio pelo app do Chat
mensagens assíncronas. Nenhuma configuração de autorização é necessária para enviar
mensagens em tempo real.
- O envio de uma
mensagem de texto
oferece suporte aos dois métodos de autorização a seguir:
- Autenticação de usuários
com a autorização
chat.messages.create
ouchat.messages
do projeto. - Autenticação de apps
com o escopo de autorização
chat.bot
.
- Autenticação de usuários
com a autorização
- O envio de um
mensagem do cartão
exige
autenticação de apps
com o escopo de autorização
chat.bot
.
- O envio de uma
mensagem de texto
oferece suporte aos dois métodos de autorização a seguir:
Enviar mensagens de texto
Esta seção descreve como enviar mensagens de texto de duas maneiras:
- Envie uma mensagem de texto em tempo real respondendo a uma interação do usuário.
- Envie uma mensagem de texto chamando a API Google Chat de forma assíncrona.
Enviar uma mensagem de texto em tempo real
Neste exemplo, o app do Chat cria e envia uma mensagem de texto sempre que ela for adicionada a um espaço. Para saber mais sobre as práticas recomendadas de integração de usuários, consulte Facilite a integração de pessoas e espaços com uma integração útil.
Para enviar uma mensagem de texto quando um usuário adicionar seu app do Chat:
a um espaço, o app do Chat
responde a um ADDED_TO_SPACE
.
evento de interação. Para responder a
ADDED_TO_SPACE
eventos de interação com uma mensagem de texto, use este código:
Node.js
/**
* Sends an onboarding message when the Chat app is added to a space.
*
* @param {Object} event The event object from Chat API.
* @return {Object} Response from the Chat app. An onboarding message that
* introduces the app and helps people get started with it.
*/
exports.onMessage = function onMessage(req, res) {
if (req.method === 'GET' || !req.body.message) {
res.send(
'Hello! This function is meant to be used in a Google Chat space.');
}
// Send an onboarding message when added to a Chat space
if (req.body.type === 'ADDED_TO_SPACE') {
res.json({
'text': 'Hi, Cymbal at your service. I help you manage your calendar
from Google Chat. Take a look at your schedule today by typing
`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To
learn what else I can do, type `/help`.'
});
}
};
Apps Script
/**
* Sends an onboarding message when the Chat app is added to a space.
*
* @param {Object} event The event object from Chat API.
* @return {Object} Response from the Chat app. An onboarding message that
* introduces the app and helps people get started with it.
*/
function onAddToSpace(event) {
return {
'text': 'Hi, Cymbal at your service. I help you manage your calendar
from Google Chat. Take a look at your schedule today by typing
`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn
what else I can do, type `/help`.'
}
}
O exemplo de código retorna a seguinte mensagem de texto:
Enviar uma mensagem de texto de forma assíncrona
A seção a seguir explica como enviar uma mensagem de texto de forma assíncrona com o a autenticação de apps e de usuários.
Para enviar uma mensagem de texto, faça o seguinte na sua solicitação:
- Com a autenticação do app, especifique o escopo de autorização
chat.bot
. Com autenticação do usuário, especifique o escopo de autorizaçãochat.messages.create
. - Chame o método
Método
create
no(a) RecursoMessage
.
Enviar uma mensagem de texto com a autenticação do app
Veja como enviar uma mensagem de texto com autenticação de apps:
Python
- Em seu diretório de trabalho, crie um arquivo chamado
chat_create_text_message_app.py
: Inclua o seguinte código em
chat_create_text_message_app.py
:from apiclient.discovery import build from google.oauth2 import service_account # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = service_account.Credentials.from_service_account_file( 'credentials.json', scopes=SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # Create a Chat message. result = chat.spaces().messages().create( # The space to create the message in. # # Replace SPACE with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. parent='spaces/SPACE', # The message to create. body={'text': 'Hello, world!'} ).execute() print(result)
No código, substitua
SPACE
por um nome de espaço, que que você pode conseguir na Métodospaces.list()
na API Chat ou pelo URL de um espaço.No diretório de trabalho, crie e execute o exemplo:
python3 chat_create_text_message_app.py
A API Chat retorna uma instância do
Message
que detalha a mensagem enviada.
Enviar uma mensagem de texto com a autenticação do usuário
Veja como enviar uma mensagem de texto com autenticação do usuário:
Python
- Em seu diretório de trabalho, crie um arquivo chamado
chat_create_text_message_user.py
: Inclua o seguinte código em
chat_create_text_message_user.py
:import os.path from google.auth.transport.requests import Request from google.oauth2.credentials import Credentials from google_auth_oauthlib.flow import InstalledAppFlow from googleapiclient.discovery import build from googleapiclient.errors import HttpError # Define your app's authorization scopes. # When modifying these scopes, delete the file token.json, if it exists. SCOPES = ["https://www.googleapis.com/auth/chat.messages.create"] def main(): ''' Authenticates with Chat API via user credentials, then creates a text message in a Chat space. ''' # Start with no credentials. creds = None # Authenticate with Google Workspace # and get user authorization. flow = InstalledAppFlow.from_client_secrets_file( 'client_secrets.json', SCOPES) creds = flow.run_local_server() # Build a service endpoint for Chat API. chat = build('chat', 'v1', credentials=creds) # Use the service endpoint to call Chat API. result = chat.spaces().messages().create( # The space to create the message in. # # Replace SPACE with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. parent='spaces/SPACE', # The message to create. body={'text': 'Hello, world!'} ).execute() # Prints details about the created message. print(result) if __name__ == '__main__': main()
No código, substitua
SPACE
por um nome de espaço, que que você pode conseguir na métodospaces.list()
na na API Chat ou no URL de um espaço.No diretório de trabalho, crie e execute o exemplo:
python3 chat_create_text_message_user.py
A API Chat retorna uma instância do
Message
que detalha a mensagem enviada.
Enviar mensagens do card
Esta seção descreve como enviar mensagens de cards de duas maneiras:
- Envie uma mensagem de cartão em tempo real respondendo a uma interação do usuário.
- Envie uma mensagem de cartão chamando a API Google Chat de forma assíncrona.
Enviar uma mensagem de cartão em tempo real
Os apps de chat podem criar cards para responder a um usuário interação, como quando um usuário envia ao app do Chat uma ou adiciona o app do Chat a um espaço. Para saber mais sobre como responder a interações do usuário, consulte Receber e responder a Interação com o app do Chat eventos.
Neste exemplo, um usuário envia uma mensagem para um app do Chat. e o app do Chat responde enviando uma mensagem de card que exibe o nome do usuário e a imagem de avatar:
Node.js
Python
Apps Script
Este exemplo envia uma mensagem de card retornando JSON do cartão. Você também pode usar o Serviço de card do Apps Script.
Enviar uma mensagem de cartão de forma assíncrona
Para enviar uma mensagem do cartão, transmita o seguinte na sua solicitação:
- Com a autenticação do app, especifique o escopo de autorização
chat.bot
. Você não pode enviar uma mensagem de cartão com autenticação do usuário. - Chame o método
Método
create
no(a) RecursoMessage
.
Este é um exemplo de mensagem de cartão:
Veja como enviar uma mensagem de cartão com a autenticação do app:
Python
- Em seu diretório de trabalho, crie um arquivo chamado
chat_create_card_message.py
: Inclua o seguinte código em
chat_create_card_message.py
:from apiclient.discovery import build from google.oauth2 import service_account # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = service_account.Credentials.from_service_account_file( 'credentials.json', scopes=SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # Create a Chat message. result = chat.spaces().messages().create( # The space to create the message in. # # Replace SPACE with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. parent='spaces/SPACE', # The message to create. body= { 'cardsV2': [{ 'cardId': 'createCardMessage', 'card': { 'header': { 'title': 'A card message!', 'subtitle': 'Created with the Chat API', 'imageUrl': 'https://developers.google.com/chat/images/chat-product-icon.png', 'imageType': 'CIRCLE' }, 'sections': [ { 'widgets': [ { 'buttonList': { 'buttons': [ { 'text': 'Read the docs!', 'onClick': { 'openLink': { 'url': 'https://developers.google.com/chat' } } } ] } } ] } ] } }] } ).execute() print(result)
No código, substitua
SPACE
por um nome de espaço, que que você pode conseguir na Métodospaces.list
na API Chat ou pelo URL de um espaço.No diretório de trabalho, crie e execute o exemplo:
python3 chat_create_card_message.py
Iniciar ou responder a uma conversa
Para iniciar uma conversa, envie uma mensagem e saia
thread.name
vazio; O Google Chat a preenche ao criar a conversa. Opcionalmente,
personalizar o nome do thread, especificar o
thread.threadKey
.
Para responder a uma conversa, envie uma mensagem que especifique o(a)
Campo threadKey
ou name
. Se a conversa tiver sido criada por uma pessoa ou por outra
Chat, use o campo thread.name
.
Se nenhuma conversa correspondente for encontrada, você poderá especificar
se uma mensagem deve iniciar uma nova conversa ou não ser postada pela configuração
messageReplyOption
.
Se messageReplyOption
for definido, também será preciso definir thread.name
ou thread.threadKey
.
Veja como iniciar ou responder a uma conversa com o campo threadKey
definido como
nameOfThread
:
Python
- Em seu diretório de trabalho, crie um arquivo chamado
chat_create_message_thread.py
: Inclua o seguinte código em
chat_create_message_thread.py
:from apiclient.discovery import build from google.oauth2 import service_account # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = service_account.Credentials.from_service_account_file( 'credentials.json', scopes=SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # Create a Chat message. result = chat.spaces().messages().create( # The space to create the message in. # # Replace SPACE with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. parent='spaces/SPACE', # Whether to start a thread or reply to an existing one. # # Required when threading is enabled in a space unless starting a # thread. Ignored in other space types. Threading is enabled when # space.spaceThreadingState is THREADED_MESSAGES. # # REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD replies to an existing thread # if one exists, otherwise it starts a new one. messageReplyOption='REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD', # The message body. body={ # The message to create. 'text': 'Start or reply to another message in a thread!', # The thread to start or reply to. 'thread': { 'threadKey': 'nameOfThread' } } ).execute() print(result)
No código, substitua
SPACE
por um nome de espaço, que que você pode conseguir na Métodospaces.list
na API Chat ou pelo URL de um espaço.No diretório de trabalho, crie e execute o exemplo:
python3 chat_create_message_thread.py
A API Chat retorna uma instância do
Message
que detalha a mensagem enviada.
Nomear uma mensagem
Esta seção explica como nomear uma mensagem definindo um ID personalizado para o
mensagem. Você pode usar IDs personalizados para receber, atualizar ou excluir mensagens. IDs personalizados
permitem especificar uma mensagem sem precisar armazenar o ID atribuído pelo sistema
o nome do recurso da mensagem (representado no campo name
). O recurso
é gerado no
corpo da resposta
ao criar a mensagem.
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. Se você já deu um nome à mensagem, substitua
o valor de {message}
com o ID personalizado.
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.
Veja como enviar uma mensagem com um ID personalizado:
Python
- Em seu diretório de trabalho, crie um arquivo chamado
chat_create_named_message.py
: Inclua o seguinte código em
chat_create_named_message.py
:from apiclient.discovery import build from google.oauth2 import service_account # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = service_account.Credentials.from_service_account_file( 'credentials.json', scopes=SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # Create a Chat message with a custom name. result = chat.spaces().messages().create( # The space to create the message in. # # Replace SPACE with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. parent='spaces/SPACE', # Custom name for the message used to facilitate later operations. messageId='client-NAME', # The message to create. body={'text': 'Hello, world!'} ).execute() print(result)
No código, substitua o seguinte:
SPACE
: o ID do espaço em que você quer postar a mensagem, que você encontra na Métodospaces.list
na API Chat ou pelo URL de um espaço.NAME
: o nome personalizado da mensagem.
No diretório de trabalho, crie e execute o exemplo:
python3 chat_create_named_message.py
A API Chat retorna uma instância do
Message
Adicionar widgets interativos na parte inferior de uma mensagem
Também é possível anexar mensagens com widgets de acessórios. Os widgets de acessórios aparecem depois de qualquer texto ou card em uma mensagem. Você pode usar essas para solicitar que os usuários interajam com sua mensagem de várias maneiras, incluindo o seguinte:
- 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[]
objeto na mensagem e especificar um ou mais
AccessoryWidgets
que você quer incluir. A mensagem precisa estar visível para todas as pessoas no espaço
Não é possível adicionar widgets de acessórios a mensagens privadas.
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 de código a seguir mostra o JSON dessa mensagem. Quando um usuário clica
um dos botões, a interação aciona a função correspondente (como
doUpvote
) que processa a classificaçã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",
}
}
}
]
}
}
]
Envie mensagens em particular
Os apps de chat podem enviar mensagens de texto e cards de forma privada para que os
só fica visível para um usuário no espaço. Para enviar uma mensagem privada,
você especifica o campo privateMessageViewer
na mensagem. Somente
Os apps de chat podem enviar mensagens privadas. Para enviar uma mensagem privada:
de forma assíncrona, use a autenticação de apps.
Veja mais detalhes em Enviar mensagens privadas para o Google Chat. usuários.
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
- Formatar uma mensagem.
- Ver detalhes de 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.