Serviço avançado do Chat

Com o serviço avançado de chat, é possível usar a API Google Chat no 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

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 de chat usa os mesmos objetos, métodos e parâmetros que a API pública.

Código de amostra

Esses 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 de 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 de 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 os escopos de autorização em appsscript.json. Para detalhes sobre a autenticação com contas de serviço, consulte Como 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);
  }
}

Acessar os detalhes de um espaço

O exemplo a seguir demonstra como receber informações sobre um espaço de 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 demonstra como listar todos os membros de um espaço de 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, significa que 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 os escopos de autorização usados pelo script ao arquivo de manifesto do projeto do Apps Script. Consulte Como 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 do array oauthScopes. Por exemplo, para chamar o método spaces.messages.create, adicione o seguinte:

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

Limites e considerações

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

Para fazer o download de um anexo de mensagem ou chamar um método de visualização para desenvolvedores, use UrlFetchApp.