Este guia explica as diferentes maneiras como os apps do Google Chat podem enviar mensagens:
- Envie mensagens de texto e de cartões em tempo real respondendo a uma interação do usuário.
- Envie mensagens de texto e de cartão de forma assíncrona chamando o método
create
no recursoMessage
. - Inicie ou responda a uma conversa.
- Envie e nomeie uma mensagem.
O
recurso Message
representa uma mensagem de
texto
ou
cartão
no Google Chat. Você pode executar create
, get
, update
ou delete
em uma mensagem na API Google Chat chamando métodos correspondentes. Para saber mais sobre mensagens de texto e cards, consulte a
Visão geral de mensagens do Google Chat.
Em vez de chamar o método create
no recurso Message
da
API Google Chat para enviar 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 do usuário em
tempo real. As respostas a interações do usuário não exigem autenticação e
oferecem suporte a outros tipos de mensagens, incluindo caixas de diálogo interativas e visualizações
de links. Para mais detalhes, consulte
Receber e responder a interações com o app do Google Chat.
Pré-requisitos
Node.js
- Uma conta do Google Workspace com acesso ao Google Chat.
- Um app do Chat publicado. Para criar um app do Chat, siga este quickstart.
- autorização configurada para que o app do Chat envie mensagens assíncronas. Nenhuma configuração de autorização é necessária para enviar mensagens em tempo real.
- O envio de uma
mensagem de texto
é compatível com os dois métodos de autorização a seguir:
- Autenticação de usuário com o escopo de autorização
chat.messages.create
ouchat.messages
. - Autenticação de apps
com o escopo de autorização
chat.bot
.
- Autenticação de usuário com o escopo de autorização
- O envio de uma
mensagem de cartão
requer
autenticação de app
com o escopo de autorização
chat.bot
.
- O envio de uma
mensagem de texto
é compatível com os dois métodos de autorização a seguir:
Python
- Python 3.6 ou superior
- A ferramenta de gerenciamento de pacotes pip
As bibliotecas de cliente mais recentes do Google para Python. Para instalá-los ou atualizá-los, execute o seguinte na interface de linha de comando:
pip3 install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib oauth2client
Um app do Chat publicado. Para criar e publicar um app do Chat, consulte Criar um app do Google Chat.
autorização configurada para que o app do Chat envie mensagens assíncronas. Nenhuma configuração de autorização é necessária para enviar mensagens em tempo real.
- O envio de uma
mensagem de texto
é compatível com os dois métodos de autorização a seguir:
- Autenticação de usuário com o escopo de autorização
chat.messages.create
ouchat.messages
. - Autenticação de apps
com o escopo de autorização
chat.bot
.
- Autenticação de usuário com o escopo de autorização
- O envio de uma
mensagem de cartão
requer
autenticação de app
com o escopo de autorização
chat.bot
.
- O envio de uma
mensagem de texto
é compatível com os dois métodos de autorização a seguir:
Apps Script
- Uma conta do Google Workspace com acesso ao Google Chat.
- Um app do Chat publicado. Para criar um app do Chat, siga este quickstart.
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 é adicionado a um espaço. Para saber mais sobre as práticas recomendadas para integrar usuários, consulte Incentivar pessoas e espaços a começar com uma integração útil.
Para enviar uma mensagem de texto quando um usuário adiciona o app do Chat
a um espaço, o app do Chat
responde a um
evento de interação com ADDED_TO_SPACE
. Para responder a
eventos de interação do ADDED_TO_SPACE
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 a autenticação de apps e de usuário.
Para enviar uma mensagem de texto, transmita o seguinte na sua solicitação:
- Com a autenticação do app, especifique o escopo da autorização
chat.bot
. Com a autenticação do usuário, especifique o escopo de autorizaçãochat.messages.create
. - Chame o
método
create
no recursoMessage
.
Enviar uma mensagem de texto com a autenticação de app
Veja como enviar uma mensagem de texto com a autenticação de app:
Python
- No 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 httplib2 import Http from oauth2client.service_account import ServiceAccountCredentials from apiclient.discovery import build # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name( 'credentials.json', SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http())) # 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 pode ser encontrado no métodospaces.list()
da API Chat ou no 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 de
Message
que detalha a mensagem enviada.
Enviar uma mensagem de texto com a autenticação de usuário
Veja como enviar uma mensagem de texto com a autenticação do usuário:
Python
- No 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 membership. print(result) if __name__ == '__main__': main()
No código, substitua
SPACE
por um nome de espaço, que pode ser encontrado no métodospaces.list()
da 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 de
Message
que detalha a mensagem enviada.
Enviar mensagens do cartão
Nesta seção, descrevemos como enviar mensagens de cartão de duas maneiras:
- Envie uma mensagem com um card em tempo real respondendo a uma interação do usuário.
- Envie uma mensagem de card chamando a API Google Chat de forma assíncrona.
Envie uma mensagem com um cartão em tempo real
Os apps de chat podem criar mensagens com cards para responder a uma interação do usuário, por exemplo, quando um usuário envia uma mensagem ao app do Chat 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 eventos de interação no app do Chat.
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 mostra o nome do usuário e a imagem do avatar:
Node.js
Python
Apps Script
Enviar uma mensagem de card de forma assíncrona
Para enviar uma mensagem do cartão, transmita as seguintes informações na solicitação:
- Com a autenticação do app, especifique o escopo da autorização
chat.bot
. Não é possível enviar uma mensagem de cartão com a autenticação do usuário. - Chame o
método
create
no recursoMessage
.
Este é um exemplo de mensagem de card:
Confira como enviar uma mensagem de cartão com a autenticação de apps:
Python
- No 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 httplib2 import Http from oauth2client.service_account import ServiceAccountCredentials from apiclient.discovery import build # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name( 'credentials.json', SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http())) # 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 pode ser encontrado no métodospaces.list
da API Chat ou no 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 um grupo de mensagens
Para iniciar uma conversa, envie uma mensagem e deixe
thread.name
vazio. O Google Chat a preenche ao criar a conversa. Opcionalmente, para
personalizar o nome da linha de execução, especifique o campo
thread.threadKey
.
Para responder a uma conversa, envie uma mensagem que especifique o campo threadKey
ou name
da conversa. Se a conversa foi criada por uma pessoa ou por outro
app do Chat, use o campo thread.name
.
Se nenhuma linha de execução correspondente for encontrada, você pode especificar
se uma mensagem deve iniciar uma nova conversa ou não ser postada ao definir o campo
messageReplyOption
.
Confira como iniciar ou responder a uma conversa com o campo threadKey
definido como
nameOfThread
:
Python
- No 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 httplib2 import Http from oauth2client.service_account import ServiceAccountCredentials from apiclient.discovery import build # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name( 'credentials.json', SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http())) # 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 pode ser encontrado no métodospaces.list
da API Chat ou no 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 de
Message
que detalha a mensagem enviada.
Enviar e nomear uma mensagem
Nesta seção, explicamos como enviar uma mensagem com um nome personalizado. Use
nomes de mensagens para
receber,
atualizar
ou
excluir mensagens.
A atribuição de um nome personalizado também permite que um app do Chat recupere
a mensagem sem salvar o name
do
corpo da resposta
retornado ao enviar a mensagem.
A atribuição de um nome personalizado não substitui o campo name
gerado, o
nome do recurso da mensagem. Em vez disso, ele define o nome personalizado como o campo
clientAssignedMessageId
, que pode ser referenciado ao processar operações
posteriores, como atualizar ou excluir a mensagem.
Os nomes personalizados têm os seguintes requisitos:
- Comece com
client-
. Por exemplo,client-custom-name
é um nome personalizado válido, mascustom-name
não é. - conter apenas letras minúsculas, números e hifens.
- Não pode ter mais de 63 caracteres.
- A especificação de um nome personalizado ao
enviar
uma mensagem retorna um erro, mas outros métodos, como
update
edelete
, funcionam conforme o esperado.
Veja como enviar e nomear uma mensagem:
Python
- No 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 httplib2 import Http from oauth2client.service_account import ServiceAccountCredentials from apiclient.discovery import build # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name( 'credentials.json', SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http())) # 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-custom-name', # The message to create. body={'text': 'Hello, world!'} ).execute() print(result)
No código, substitua
SPACE
por um nome de espaço, que pode ser encontrado no métodospaces.list
da API Chat ou no URL de um espaço.No diretório de trabalho, crie e execute o exemplo:
python3 chat_create_named_message.py
A API Chat retorna uma instância de
Message
que detalha a mensagem enviada.
Resolver problemas
Quando um app ou card do Google Chat retorna um erro, a interface do Chat mostra uma mensagem dizendo "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 de card pode não aparecer.
Mesmo que 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 a corrigir erros quando o registro de erros dos apps do Chat está ativado. Se precisar de ajuda para ver, depurar e corrigir erros, consulte Resolver problemas e corrigir erros do Google Chat.
Temas relacionados
- Formatar uma mensagem.
- Ver detalhes de uma mensagem.
- Listar as 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.