Serviço avançado do Chat

Com o serviço avançado de chat, é possível usar a API Google Chat no Apps Script. Com ela, os scripts encontram, criam e mudam os espaços do Chat, adicionam ou removem participantes e leem ou postam mensagens com texto, cards, anexos e reações.

Pré-requisitos

Referência

Para mais informações sobre esse serviço, consulte a documentação de referência da API Chat. Assim 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.

Código de amostra

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. Usar o serviço avançado do Chat com uma conta de serviço não exige que você especifique escopos de autorização em appsscript.json. Para 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);
  }
}

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

O exemplo a seguir mostra como listar todos os membros 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;
          }
          response.memberships.forEach((membership) => console.log(
              'Member resource name: %s (type: %s)',
              membership.name,
              membership.member.type));
          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 do Chat, é necessário adicionar manualmente ao arquivo de manifesto do projeto do Apps Script os escopos de autorização que o script usa. Consulte Definir escopos explícitos.

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

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

Limitações e considerações

O serviço Advanced Chat não é compatível com:

Para baixar um anexo de mensagem ou chamar um método de prévia para desenvolvedores, use UrlFetchApp.