Serviço avançado do Chat

Gerenciar espaços, participantes e mensagens do Chat.

O Serviço avançado de chat permite usar a API Google Chat no Google Apps Script. Essa API permite que os scripts encontrem, criem e modifiquem espaços do Chat, adicionem ou removam participantes e leiam ou postem mensagens com texto, cards, anexos e reações.

Pré-requisitos

Esse é um serviço avançado que você precisa ativar antes de usar.

Referência

Para mais informações sobre esse serviço, consulte a documentação de referência da API Chat. Como todos os serviços avançados no Apps Script, o serviço Chat usa os mesmos objetos, métodos e parâmetros da API pública.

Exemplo de código

Estes exemplos mostram como realizar ações comuns da API Google Chat usando o serviço avançado.

Postar uma mensagem com credenciais de usuário

O exemplo a seguir demonstra como postar uma mensagem em um espaço do Chat em nome do usuário.

  1. Adicione o escopo de autorização chat.messages.create ao arquivo appsscript.json do projeto do Apps Script:

    "oauthScopes": [
  "https://www.googleapis.com/auth/chat.messages.create"
]

  2. Adicione uma função como esta ao código do projeto do Apps Script:

    advanced/chat.gs
    /**
 * Posts a new message to the specified space on behalf of the user.
 * @param {string} spaceName The resource name of the space.
 */
function postMessageWithUserCredentials(spaceName) {
  try {
    const message = { text: "Hello world!" };
    Chat.Spaces.Messages.create(message, spaceName);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log("Failed to create message with error %s", err.message);
  }
}

Postar uma mensagem com credenciais do app

O exemplo a seguir demonstra como postar uma mensagem em um espaço do Chat em nome do app. O uso do serviço avançado de chat com uma conta de serviço não exige que você especifique escopos de autorização em appsscript.json. Para mais detalhes sobre a autenticação com contas de serviço, consulte Autenticar como um app do Google Chat.

advanced/chat.gs
/**
 * Posts a new message to the specified space on behalf of the app.
 * @param {string} spaceName The resource name of the space.
 */
function postMessageWithAppCredentials(spaceName) {
  try {
    // See https://developers.google.com/chat/api/guides/auth/service-accounts
    // for details on how to obtain a service account OAuth token.
    const appToken = getToken_();
    const message = { text: "Hello world!" };
    Chat.Spaces.Messages.create(
      message,
      spaceName,
      {},
      // Authenticate with the service account token.
      { Authorization: `Bearer ${appToken}` },
    );
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log("Failed to create message with error %s", err.message);
  }
}

Receber um espaço

O exemplo a seguir demonstra como receber informações sobre um espaço do Chat.

  1. Adicione o escopo de autorização chat.spaces.readonly ao arquivo appsscript.json do projeto do Apps Script:

    "oauthScopes": [
  "https://www.googleapis.com/auth/chat.spaces.readonly"
]

  2. Adicione uma função como esta ao código do projeto do Apps Script:

    advanced/chat.gs
    /**
 * Gets information about a Chat space.
 * @param {string} spaceName The resource name of the space.
 */
function getSpace(spaceName) {
  try {
    const space = Chat.Spaces.get(spaceName);
    console.log("Space display name: %s", space.displayName);
    console.log("Space type: %s", space.spaceType);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log("Failed to get space with error %s", err.message);
  }
}

Criar um espaço

O exemplo a seguir demonstra como criar um espaço do Chat.

  1. Adicione o escopo de autorização chat.spaces.create ao arquivo appsscript.json do projeto do Apps Script:

    "oauthScopes": [
  "https://www.googleapis.com/auth/chat.spaces.create"
]

  2. Adicione uma função como esta ao código do projeto do Apps Script:

    advanced/chat.gs
    /**
 * Creates a new Chat space.
 */
function createSpace() {
  try {
    const space = { displayName: "New Space", spaceType: "SPACE" };
    Chat.Spaces.create(space);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log("Failed to create space with error %s", err.message);
  }
}

Listar associações

O exemplo a seguir demonstra como listar todos os participantes de um espaço do Chat.

  1. Adicione o escopo de autorização chat.memberships.readonly ao arquivo appsscript.json do projeto do Apps Script:

    "oauthScopes": [
  "https://www.googleapis.com/auth/chat.memberships.readonly"
]

  2. Adicione uma função como esta ao código do projeto do Apps Script:

    advanced/chat.gs
    /**
 * Lists all the members of a Chat space.
 * @param {string} spaceName The resource name of the space.
 */
function listMemberships(spaceName) {
  let response;
  let pageToken = null;
  try {
    do {
      response = Chat.Spaces.Members.list(spaceName, {
        pageSize: 10,
        pageToken: pageToken,
      });
      if (!response.memberships || response.memberships.length === 0) {
        pageToken = response.nextPageToken;
        continue;
      }
      for (const membership of response.memberships) {
        console.log(
          "Member: %s, Role: %s",
          membership.member.displayName,
          membership.role,
        );
      }
      pageToken = response.nextPageToken;
    } while (pageToken);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log("Failed with error %s", err.message);
  }
}

Resolver problemas

Se você encontrar Error 400: invalid_scope com a mensagem de erro Some requested scopes cannot be shown, isso significa que você não especificou nenhum escopo de autorização no arquivo appsscript.json do projeto do Apps Script. Na maioria dos casos, o Apps Script determina automaticamente quais escopos um script precisa, mas, ao usar o serviço avançado de chat, é necessário adicionar manualmente os escopos de autorização que o script usa ao arquivo de manifesto do projeto do Apps Script. Consulte Definir escopos explícitos.

Para resolver o erro, adicione os escopos de autorização apropriados ao arquivo appsscript.json do projeto do Apps Script como parte da matriz oauthScopes. Por exemplo, para chamar o spaces.messages.create método, adicione o seguinte:

"oauthScopes": [
  "https://www.googleapis.com/auth/chat.messages.create"
]

Limites e considerações

O Serviço avançado de chat não oferece suporte a:

Para fazer o download de um anexo de mensagem ou chamar um método de prévia para desenvolvedores, use UrlFetchApp em vez disso.