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.
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
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 das APIs do Google.
- 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.
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.
Para enviar uma mensagem de texto em nome de um usuário, siga estas etapas:
Python
- Em seu diretório de trabalho, crie um arquivo chamado
chat_create_message_user.py
: Inclua o seguinte código em
chat_create_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', # Optional. Sets custom ID for the message to use in other requests. messageId='client-myfirstusermessage', # The text message to create. body={ 'text': '👋 🌎Hello world! Text messages can contain things like:\n\n' + '* Hyperlinks 🔗\n' + '* Emojis 😄🎉\n' + '* Mentions of other Chat users `@` \n\n' 'For details, see the <https://developers.google.com/workspace/chat/format-messages|Chat API developer documentation>.' } ).execute() # Prints details about the created message. print(result) if __name__ == '__main__': main()
Substitua
SPACE
pelo ID do espaçoname
. Você pode obter o ID chamando o Métodospaces.list()
ou pelo URL do espaço.No diretório de trabalho, crie e execute o exemplo:
python3 chat_create_message_user.py
Se um URL for solicitado, abra-o para autorizar o App do Chat baseado no escopo que você usou solicitação.
O app do Chat cria a mensagem, e o
o usuário publica a mensagem no espaço. Na interface da linha de comando, o
A API Chat retorna a instância do novo
Message
.
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 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.
Para enviar uma mensagem postada como o app do Chat que contém texto, um cartão e um botão clicável na parte de baixo da mensagem, siga estas etapas:
Python
- Em seu diretório de trabalho, crie um arquivo chamado
chat_create_message_app.py
: Inclua o seguinte código em
chat_create_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) # Specify the Chat space where the message is posted. Obtain the ID # from the resource name, or from the space's URL. SPACE = 'spaces/SPACE' # Create a Chat message. result = chat.spaces().messages().create( # The Chat space. parent=SPACE, # Optional. Sets custom ID for the message to use in other requests. messageId='client-myfirstappmessage', # The message to create with text, a card, and a button at the # bottom of the message. body= { 'text': '👋 🌎Hello world! I created this message by calling the Chat API\'s `messages.create()` method.', 'cardsV2': [{ 'cardId': 'myCardId', 'card': { 'header': { 'title': 'About this message', 'imageUrl': 'https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg', 'imageType': 'CIRCLE' }, "sections": [ { "header": "Contents", "widgets": [ { "textParagraph": { "text": "🔡 <b>Text</b> which can include hyperlinks 🔗, emojis 😄🎉, and @mentions 🗣️." }}, { "textParagraph": { "text": "🖼️ A <b>card</b> to display visual elements and request information such as text 🔤, dates and times 📅, and selections ☑️." }}, { "textParagraph": { "text": "👉🔘 An <b>accessory widget</b> which adds a button to the bottom of a message." }}, ] }, { "header": "What's next", "collapsible": True, "widgets": [ { "textParagraph": { "text": "❤️ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages.reactions/create'>Add a reaction</a>." }}, { "textParagraph": { "text": "🔄 <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/patch'>Update</a> or ❌ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/delete'>delete</a> the message." }}, { "textParagraph": { "text": '💡 <b>Pro tip</b>: To specify the message in other API requests, use its custom name: <i>' + SPACE + '/messages/client-myfirstappmessage</i>.' }} ] } ]} }], "accessoryWidgets": [ { "buttonList": { "buttons": [ { "text": "View documentation", "altText": "Opens a new browser tab and navigates to the Google Chat developer documentation website.", "icon": { "material_icon": { "name": "link" } }, "onClick": { "openLink": { "url": "https://developers.google.com/workspace/chat/create-messages" } } } ] } } ] } ).execute() print(result)
Substitua
SPACE
pelo ID do espaçoname
. Você pode obter o ID chamando o Métodospaces.list()
ou pelo URL do espaço.No diretório de trabalho, crie e execute o exemplo:
python3 chat_create_message_app.py
O app do Chat cria e publica a mensagem no
espaço. Na interface de linha de comando, a API Chat retorna as
instância do novo
Message
.
Adicionar widgets interativos na parte inferior de uma mensagem
No exemplo de código da seção anterior, 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=0000&hl=pt-br)
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"
}
}
Substituir 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:
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 JSON a seguir mostra um exemplo do corpo da solicitação de uma mensagem de texto que
inicia ou responde a uma conversa com a chave helloWorldThread
:
{
'thread': {
'threadKey': 'helloWorldThread',
},
'text': '👋 🌎Hello world!'
}
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.
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.