Enviar uma mensagem usando a API Google Chat (original) (raw)

Neste guia, explicamos como usar o métodocreate()no recurso Message da API Google Chat para fazer o seguinte:

O tamanho máximo da mensagem (incluindo texto ou cards) é de 32.000 bytes. Para enviar uma mensagem que exceda esse tamanho, o app Chat precisa enviar várias mensagens.

Além de chamar a API Chat para criar mensagens, os apps do Chat podem 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 às interações, os apps de chat podem usar outros tipos de recursos de mensagens, incluindo caixas de diálogo interativas e interfaces de visualização de link. Para responder a um usuário, o app Chat retorna a mensagem de forma síncrona, sem chamar a API Chat. Para saber como enviar mensagens para responder a interações, consulteReceber e responder a interações com seu app do Google Chat.

Como o Chat mostra e atribui mensagens criadas com a API Chat

Você pode chamar o método create() usando aautenticação de appe a autenticação do usuário. O Chat atribui o remetente da mensagem de maneira diferente dependendo do tipo de autenticação que você usa.

Quando você se autentica como o app Chat, ele envia a mensagem.

Chamando o método create() com autenticação do app.

Figura 1: com a autenticação do app, o app Chat envia a mensagem. Para indicar que o remetente não é uma pessoa, o Chat mostra App ao lado do nome dele.

Quando você se autentica como um usuário, o app Chat envia a mensagem em nome dele. O Chat também atribui o app Chat à mensagem mostrando o nome dele.

Como chamar o método create() com autenticação do usuário.

Figura 2: com a autenticação do usuário, ele envia a mensagem, e o Chat mostra o nome do app ao lado do nome do usuário.

O tipo de autenticação também determina quais recursos e interfaces de mensagens podem ser incluídos na mensagem. Com a autenticação de apps, os apps do Chat podem enviar mensagens com rich text, interfaces baseadas em cards e widgets interativos. Como os usuários do Chat só podem enviar texto nas mensagens, você só pode incluir texto ao criar mensagens usando a autenticação de usuário. Para saber mais sobre os recursos de mensagens disponíveis para a API Chat, consulte a 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

Python

Java

Apps Script

Enviar uma mensagem como o app Chat

Esta seção explica como enviar mensagens que contêm texto, cards e widgets de acessórios interativos usando aautenticação de app.

Mensagem enviada com autenticação de app

Figura 4. Um app do Chat envia uma mensagem com texto, um card e um botão de acessório.

Para chamar o método CreateMessage() usando a autenticação do app, especifique os seguintes campos na solicitação:

Também é possível incluir o seguinte:

O código a seguir mostra um exemplo de como um app de chat pode enviar uma mensagem postada como o app de chat que contém texto, um card 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 do camponamedo espaço. Para conseguir o ID, chame o métodoListSpaces()ou acesse o URL do espaço.

Adicionar widgets interativos na parte de baixo de uma mensagem

No primeiro exemplo de código deste guia, a mensagem do app de chat mostra um botão clicável na parte de baixo, conhecido como widget acessório. Os widgets de acessórios aparecem depois de qualquer texto ou cards em uma mensagem. Você pode usar esses widgets para pedir aos usuários que interajam com sua mensagem de várias maneiras, incluindo:

Para adicionar widgets de acessórios, inclua o campoaccessoryWidgets[]no corpo da solicitação e especifique 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 do Chat.

Widget de acessórios.

Figura 5: uma mensagem do app de chat com widgets de texto e acessórios.

A seguir, mostramos o corpo da solicitação que cria uma mensagem de texto com dois botões de acessórios. Quando um usuário clica em um botão, a função correspondente (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 particular

Os apps de chat podem enviar mensagens particulares para que elas fiquem visíveis apenas para um usuário específico no espaço. Quando um app do Chat envia uma mensagem privada, ela mostra um indicador que notifica o usuário de que a mensagem só está visível para ele.

Para enviar uma mensagem particular usando a API Chat, especifique o campoprivateMessageViewerno corpo da solicitação. Para especificar o usuário, defina o valor como o recursoUserque representa o usuário do chat. Você também pode usar o camponamedo recurso User, como mostrado no exemplo a seguir:

{
  text: "Hello private world!",
  privateMessageViewer: {
    name: "users/USER_ID"
  }
}

Para usar essa amostra, substitua USER_ID por um ID exclusivo do usuário, como 12345678987654321 ou hao@cymbalgroup.com. Para mais informações sobre como especificar usuários, consulteIdentificar e especificar usuários do Google Chat.

Para enviar uma mensagem particular, omita o seguinte na sua solicitação:

Enviar uma mensagem de texto em nome de um usuário

Nesta seção, explicamos como enviar mensagens em nome de um usuário usando aautenticação de usuário. Com a autenticação do usuário, o conteúdo da mensagem só pode conter texto e precisa omitir recursos de mensagens disponíveis apenas para apps do Chat, incluindo interfaces de card 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 o método CreateMessage() usando a autenticação do usuário, especifique os seguintes campos na solicitação:

Também é possível incluir o seguinte:

O código a seguir mostra um exemplo de como um app do Chat pode 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 do camponamedo espaço. Para conseguir o ID, chame o métodoListSpaces()ou acesse o URL do espaço.

Iniciar ou responder em uma conversa

Para espaços que usam conversas, é possível especificar se uma nova mensagem inicia uma conversa ou responde a uma conversa existente.

Por padrão, as mensagens criadas com a API Chat iniciam uma nova conversa. Para ajudar a identificar e responder à conversa depois, especifique uma chave de conversa na sua solicitação:

Para criar uma mensagem que responda a uma conversa:

O código a seguir mostra um exemplo de como um app de chat pode enviar uma mensagem de texto que inicia ou responde a uma determinada conversa identificada pela chave de um determinado espaço em nome de um usuário autenticado:

Node.js

Python

Java

Apps Script

Para executar esta amostra, substitua o seguinte:

Nomear uma mensagem

Para recuperar ou especificar uma mensagem em chamadas de API futuras, nomeie uma mensagem definindo o campo messageId na sua solicitação. Ao nomear a mensagem, você pode especificá-la sem precisar armazenar o ID atribuído pelo sistema do nome do recurso da mensagem (representado no campo name).

Por exemplo, para extrair uma mensagem usando o método get(), use o nome do recurso para especificar qual mensagem extrair. O nome do recurso é formatado como spaces/{space}/messages/{message}, em que {message} representa o ID atribuído pelo sistema ou o nome personalizado definido ao criar a mensagem.

Para nomear uma mensagem, especifique um ID personalizado no campomessageIdao criar a mensagem. O campo messageId define o valor do campo clientAssignedMessageId do recurso Message.

Só é possível nomear uma mensagem ao criá-la. Não é possível nomear ou modificar um ID personalizado para mensagens atuais. O ID personalizado precisa atender aos seguintes requisitos:

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 espaço específico em nome de um usuário autenticado:

Node.js

Python

Java

Apps Script

Para executar esta amostra, substitua o seguinte:

Citar uma mensagem

Você pode citar outra mensagem chamandoCreateMessage()(rpc,rest) e definindo quotedMessageMetadata(rpc,rest) na solicitação.

Você pode citar mensagens em uma conversa ou no chat principal, mas não é possível citar uma mensagem de outra conversa.

O código a seguir mostra como criar uma mensagem que cita outra:

Node.js

import {createClientWithUserCredentials} from './authentication-utils.js';

const USER_AUTH_OAUTH_SCOPES = ['https://www.googleapis.com/auth/chat.messages.create'];

// This sample shows how to create a message that quotes another message.
async function main() {

  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {

    // TODO(developer): Replace SPACE_NAME .
    parent: 'spaces/SPACE_NAME',

    message: {
      text: 'I am responding to a quoted message!',

      // quotedMessageMetadata lets chat apps respond to a message by quoting it.
      quotedMessageMetadata: {

        // TODO(developer): Replace QUOTED_MESSAGE_NAME
        // and QUOTED_MESSAGE_LAST_UPDATE_TIME.
        name: 'QUOTED_MESSAGE_NAME',
        lastUpdateTime: 'QUOTED_MESSAGE_LAST_UPDATE_TIME'
      }
    }
  };

  // Make the request
  const response = await chatClient.createMessage(request);

  // Handle the response
  console.log(response);
}

main().catch(console.error);

Python

from authentication_utils import create_client_with_user_credentials
from google.apps import chat_v1 as google_chat
from google.protobuf.timestamp_pb2 import Timestamp

SCOPES = ['https://www.googleapis.com/auth/chat.messages.create']

# This sample shows how to create a message that quotes another message.
def create_message_quote_message():
    '''Creates a message that quotes another message.'''

    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Create a timestamp from the RFC-3339 string.
    # TODO(developer): Replace QUOTED_MESSAGE_LAST_UPDATE_TIME.
    last_update_time = Timestamp()
    last_update_time.FromJsonString('QUOTED_MESSAGE_LAST_UPDATE_TIME')

    # Initialize request argument(s)
    request = google_chat.CreateMessageRequest(

        # TODO(developer): Replace SPACE_NAME.
        parent='spaces/SPACE_NAME',

        # Create the message.
        message = google_chat.Message(
            text='I am responding to a quoted message!',

            # quotedMessageMetadata lets chat apps respond to a message by quoting it.
            quoted_message_metadata=google_chat.QuotedMessageMetadata(

                name='QUOTED_MESSAGE_NAME',
                last_update_time=last_update_time
            )
        )
    )

    # Make the request
    response = client.create_message(request)

    # Handle the response
    print(response)

create_message_quote_message()

Java

import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMessageRequest;
import com.google.chat.v1.Message;
import com.google.chat.v1.QuotedMessageMetadata;
import com.google.protobuf.util.Timestamps;
import com.google.workspace.api.chat.samples.utils.AuthenticationUtils;
import java.text.ParseException;

// This sample shows how to create a message that quotes another message.
public class CreateMessageQuoteMessage {
  public static void main(String[] args) throws Exception, ParseException {
    // Create a client.
    ChatServiceClient chatClient = AuthenticationUtils.createClientWithUserCredentials();

    // Initialize request argument(s).
    // TODO(developer): Replace SPACE_NAME, QUOTED_MESSAGE_NAME,
    // and QUOTED_MESSAGE_LAST_UPDATE_TIME here.
    String parent = "spaces/SPACE_NAME";
    String quotedMessageName = "QUOTED_MESSAGE_NAME";
    String lastUpdateTime = "QUOTED_MESSAGE_LAST_UPDATE_TIME";

    QuotedMessageMetadata quotedMessageMetadata =
        QuotedMessageMetadata.newBuilder()
            .setName(quotedMessageName)
            .setLastUpdateTime(Timestamps.parse(lastUpdateTime))
            .build();

    Message message = Message.newBuilder()
        .setText("I am responding to a quoted message!")
        .setQuotedMessageMetadata(quotedMessageMetadata)
        .build();

    CreateMessageRequest request =
        CreateMessageRequest.newBuilder()
            .setParent(parent)
            .setMessage(message)
            .build();

    // Make the request.
    Message response = chatClient.createMessage(request);

    // Handle the response.
    System.out.println(response);
  }
}

Apps Script

/**
 * Creates a message that quotes another message.
 *
 * Relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.messages.create'
 * referenced in the manifest file (appsscript.json).
 */
function createMessageQuoteMessage() {

  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';

  const message = {

    // The text content of the message.
    text: 'I am responding to a quoted message!',

    // quotedMessageMetadata lets chat apps respond to a message by quoting it.
    //
    // TODO(developer): Replace QUOTED_MESSAGE_NAME
    // and QUOTED_MESSAGE_LAST_UPDATE_TIME .
    quotedMessageMetadata: {
      name: 'QUOTED_MESSAGE_NAME',
      lastUpdateTime: 'QUOTED_MESSAGE_LAST_UPDATE_TIME',
    }
  };

  // Make the request
  const response = Chat.Spaces.Messages.create(message, parent);

  // Handle the response
  console.log(response);
}

Para executar esta amostra, substitua o seguinte:

Resolver problemas

Quando um app ou card do Google Chat retorna um erro, a interface do Chat mostra a mensagem "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 do card pode não aparecer.

Embora 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 você a corrigir erros quando o registro de erros para apps do Chat está ativado. Para ajuda com a visualização, depuração e correção de erros, consulteSolucionar e corrigir erros do Google Chat.