Enviar uma mensagem usando a API Google Chat

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.

Chamada do método messages.create() com autenticação de app.
Figura 1: com a autenticação do app, o app do Chat envia a mensagem. Para mostrar que o remetente não é uma pessoa, o Chat mostra 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

Chamar o método messages.create() com autenticação de usuário.
Figura 2: com a autenticação do usuário, ele envia a mensagem, e o Chat mostra Nome do app do Chat ao lado do nome do usuário.

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

  • Python 3.6 ou superior
  • a ferramenta de gerenciamento de pacotes PIP;
  • As bibliotecas de cliente mais recentes do Google. Para instalar ou atualizar esses recursos, execute o seguinte comando na interface de linha de comando: 
    pip3 install --upgrade google-api-python-client google-auth-oauthlib

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.

Mensagem enviada com autenticação do usuário
Figura 3. Um app do Chat envia uma mensagem de texto em nome de um usuário.

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 prefixo text .

Opcionalmente, você pode incluir o seguinte:

Para enviar uma mensagem de texto em nome de um usuário, siga estas etapas:

Python

  1. Em seu diretório de trabalho, crie um arquivo chamado chat_create_message_user.py:

  2. 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ço name . Você pode obter o ID chamando o Método spaces.list() ou pelo URL do espaço.

  3. No diretório de trabalho, crie e execute o exemplo:

    python3 chat_create_message_user.py

  4. 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.

Mensagem enviada com a autenticação do app
Figura 4. Um app do Chat envia uma mensagem com texto, um cartão e um botão acessório.

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 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

  1. Em seu diretório de trabalho, crie um arquivo chamado chat_create_message_app.py:

  2. 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ço name . Você pode obter o ID chamando o Método spaces.list() ou pelo URL do espaço.

  3. 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.
Figura 5: uma mensagem do app do Chat com widgets de texto e acessórios.

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 especifique threadKey que você criou. Caso contrário, você deve usar o método name 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, mas custom-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.