Configurar um espaço com os participantes iniciais

Este guia explica como usar o método setup no recurso Space da API Google Chat para configurar um espaço do Google Chat. A configuração cria um espaço e adiciona usuários especificados a ele.

O recurso Space representa um lugar onde as pessoas e os apps do Chat podem enviar mensagens, compartilhar arquivos e colaborar. Há vários tipos de espaços:

  • As mensagens diretas são conversas entre dois usuários ou um usuário e um app do Chat.
  • Os grupos de chat são conversas entre três ou mais usuários e os apps do Chat.
  • Os espaços nomeados são lugares persistentes onde as pessoas enviam mensagens, compartilham arquivos e colaboram.

Ao configurar um espaço, considere o seguinte:

  • O usuário que fez a chamada (autenticado) é adicionado automaticamente ao espaço. Por isso, não é necessário especificar a associação dele na solicitação.
  • Ao criar uma mensagem direta (DM), se houver uma mensagem direta entre dois usuários, ela será retornada. Caso contrário, um tomador de decisão será criado.
  • Ao criar um chat em grupo, se nenhuma das associações fornecidas na solicitação for adicionada ao chat em grupo (por exemplo, problema de permissão), um chat em grupo vazio (incluindo apenas o usuário que fez a chamada) poderá ser criado.
  • Não é possível configurar espaços com respostas agrupadas ou adicionar pessoas de fora do Google Workspace.
  • As associações duplicadas (incluindo o usuário que fez a chamada) fornecidas na solicitação são filtradas em vez de resultar em um erro de solicitação.

Pré-requisitos

Python

  • Python 3.6 ou superior
  • pip (em inglês)

  • As bibliotecas de cliente mais recentes do Google para Python. Para instalá-los ou atualizá-los, execute o seguinte comando na interface de linha de comando:

    pip3 install --upgrade google-api-python-client google-auth-oauthlib
  • Um projeto do Google Cloud com a API Google Chat ativada e configurada. Para ver as etapas, consulte Criar um app do Google Chat.

  • Autorização configurada para o app do Chat. A configuração de um espaço requer a autenticação do usuário com o escopo de autorização chat.spaces.create ou chat.spaces.

Node.js

  • Node.js e npm

  • As bibliotecas de cliente mais recentes do Google para Node.js. Para instalá-los, execute o seguinte comando em sua interface de linha de comando:

    npm install @google-cloud/local-auth @googleapis/chat
  • Um projeto do Google Cloud com a API Google Chat ativada e configurada. Para ver as etapas, consulte Criar um app do Google Chat.

  • Autorização configurada para o app do Chat. A criação de um espaço requer a autenticação do usuário com o escopo de autorização chat.spaces.create ou chat.spaces.

Configurar um espaço

Para configurar um espaço, transmita o seguinte na sua solicitação:

  • Especifique o escopo de autorização chat.spaces.create ou chat.spaces.
  • Chame o método setup no recurso Space.
  • Para adicionar um usuário humano como participante do espaço, especifique users/{user}, em que {user} é o {person_id} do person da API People ou o ID de um user na API Directory. Por exemplo, se o resourceName da pessoa da API People for people/123456789, será possível adicionar o usuário ao espaço incluindo uma associação com users/123456789 como member.name.
  • Para adicionar um grupo como participante do espaço, especifique groups/{group}, em que {group} é o ID do grupo para o qual você quer criar a associação. O ID do grupo pode ser recuperado usando a API Cloud Identity. Por exemplo, se a API Cloud Identity retornar um grupo com o nome groups/123456789, defina membership.groupMember.name como groups/123456789. Não é possível adicionar Grupos do Google a um chat em grupo ou a uma mensagem direta, apenas a um espaço nomeado.
  • Para criar uma mensagem direta entre o usuário que fez a chamada e outro usuário humano, especifique a associação do usuário humano na solicitação.
  • Para criar uma mensagem direta entre o usuário que fez a chamada e o app de chamada, defina Space.singleUserBotDm como true e não especifique nenhuma assinatura. Esse método só pode ser usado para configurar uma mensagem direta com o app de chamada. Para adicionar o app de chamada como membro de um espaço ou uma mensagem direta entre dois usuários humanos, consulte Criar uma assinatura.

O exemplo a seguir cria um espaço nomeado e cria associações ao espaço para um grupo e três usuários humanos (incluindo o usuário autenticado e dois outros usuários especificados).

Python

  1. No diretório de trabalho, crie um arquivo chamado chat_space_setup.py.

  2. Inclua o seguinte código em chat_space_setup.py:

    from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

# 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.spaces.create"]

def main():
    '''
    Authenticates with Chat API via user credentials,
    then sets up a Chat space by creating a space and adding members.
    '''

    # 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().setup(

      # Details about the space to set up.
      body = {

        # Attributes of the space to set up, like space type and display name.
        'space': {

            # To set up a named space, set spaceType to SPACE.
            'spaceType': 'SPACE',

            # The user-visible name of the space
            'displayName': 'API-setup'
        },

        # The users and groups to add to the space.
        #
        # The authenticated user is automatically added to the space,
        # and doesn't need to be specified in the memberships array.
        'memberships': [
            {
              'member': {
                'name':'users/123456789',
                'type': 'HUMAN'
              }
            },
            {
              'member': {
                'name':'users/987654321',
                'type': 'HUMAN'
              }
            },
            {
              'groupMember': {
                'name': 'groups/11223344'
              }
            }
        ]
      }

      ).execute()

    # Prints details about the created space.
    print(result)

if __name__ == '__main__':
    main()

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

    python3 chat_space_setup.py

Node.js

  1. No diretório de trabalho, crie um arquivo chamado setup-space.js.

  2. Inclua o seguinte código em setup-space.js:

    const chat = require('@googleapis/chat');
const {authenticate} = require('@google-cloud/local-auth');

/**
* Sets up a new Chat space with users.
* @return {!Promise<!Object>}
*/
async function setupSpace() {
  const scopes = [
    'https://www.googleapis.com/auth/chat.spaces.create',
  ];

  const authClient =
      await authenticate({scopes, keyfilePath: 'client_secrets.json'});

  const chatClient = await chat.chat({version: 'v1', auth: authClient});

  return await chatClient.spaces.setup({
    requestBody: {
      space: {
        spaceType: 'SPACE',
        displayName: 'API-made',
      },
      memberships: [
        {member: {name: 'users/123456789', type: 'HUMAN'}},
        {member: {name: 'users/987654321', type: 'HUMAN'}},
        {groupMember: {name: 'groups/11223344'}},
      ]
    }
  });
}

setupSpace().then(console.log);

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

    node setup-space.js

Um espaço de chat nomeado com um grupo e três usuários humanos, incluindo o usuário autenticado, está configurado.

Para acessar o espaço, use o ID do recurso e crie o URL dele. Você pode conferir o ID do recurso do espaço name no corpo da resposta do Google Chat. Por exemplo, se o name do espaço for spaces/1234567, acesse o espaço usando este URL: https://mail.google.com/chat/u/0/#chat/space/1234567.