Convidar ou adicionar um usuário, um Grupo do Google ou um app do Google Chat a um espaço

Neste guia, explicamos como usar o método create() no recurso Membership da API Google Chat para convidar ou adicionar um usuário, grupo do Google ou app Chat a um espaço, também conhecido como criação de uma assinatura. Ao criar uma assinatura, se o membro especificado tiver a política de aceitação automática desativada, ele vai receber um convite e precisará aceitá-lo antes de entrar no espaço. Caso contrário, a criação de uma assinatura adiciona o membro diretamente ao espaço especificado.

Se você é um administrador do Google Workspace, pode adicionar usuários, Grupos do Google ou apps do Chat a qualquer espaço na sua organização do Google Workspace.

O recurso Membership representa se um usuário humano ou o app do Google Chat foi convidado para um espaço, faz parte dele ou está ausente.

Pré-requisitos

Node.js

Python

Java

Apps Script

Convidar ou adicionar um usuário a um espaço como usuário

Para convidar ou adicionar um usuário a um espaço com autenticação do usuário, transmita o seguinte na sua solicitação:

  • Especifique o escopo de autorização chat.memberships.
  • Chame o método CreateMembership().
  • Transmita parent como o nome do recurso do espaço em que a associação será criada.
  • Transmita membership como uma instância de Membership com o campo member definido da seguinte maneira:
    • O campo type definido como HUMAN.
    • O campo name definido como users/{user}, em que {user} é a pessoa que você quer adicionar ao espaço. Para especificar o usuário do Chat, substitua {user} por uma das seguintes opções:
      • O ID da pessoa na API People. Por exemplo, se a API People person resourceName for people/123456789, use o valor users/123456789.
      • O ID do usuário na API Directory.
      • O endereço de e-mail do usuário. Por exemplo, users/222larabrown@gmail.com ou users/larabrown@cymbalgroup.com. Se o usuário usar uma Conta do Google ou pertencer a uma organização do Google Workspace diferente, use o endereço de e-mail dele.

O exemplo a seguir adiciona um usuário a um espaço com autenticação do usuário:

Node.js

chat/client-libraries/cloud/create-membership-user-cred.js
import {createClientWithUserCredentials} from './authentication-utils.js';

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

// This sample shows how to create membership with user credential for a human user
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    membership: {
      member: {
        // Replace USER_NAME here
        name: 'users/USER_NAME',
        // User type for the membership
        type: 'HUMAN'
      }
    }
  };

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

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

main().catch(console.error);

Python

chat/client-libraries/cloud/create_membership_user_cred.py
from authentication_utils import create_client_with_user_credentials
from google.apps import chat_v1 as google_chat

SCOPES = ["https://www.googleapis.com/auth/chat.memberships"]

# This sample shows how to create membership with user credential for a human
# user
def create_membership_with_user_cred():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.CreateMembershipRequest(
        # Replace SPACE_NAME here
        parent = "spaces/SPACE_NAME",
        membership = {
            "member": {
                # Replace USER_NAME here
                "name": "users/USER_NAME",
                # user type for the membership
                "type_": "HUMAN"
            }
        }
    )

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

    # Handle the response
    print(response)

create_membership_with_user_cred()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMembershipUserCred.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMembershipRequest;
import com.google.chat.v1.Membership;
import com.google.chat.v1.SpaceName;
import com.google.chat.v1.User;

// This sample shows how to create membership with user credential for a human
// user.
public class CreateMembershipUserCred {

  private static final String SCOPE =
    "https://www.googleapis.com/auth/chat.memberships";

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      CreateMembershipRequest.Builder request = CreateMembershipRequest.newBuilder()
        // replace SPACE_NAME here
        .setParent("spaces/SPACE_NAME")
        .setMembership(Membership.newBuilder()
          .setMember(User.newBuilder()
            // replace USER_NAME here
            .setName("users/USER_NAME")
            // user type for the membership
            .setType(User.Type.HUMAN)));
      Membership response = chatServiceClient.createMembership(request.build());

      System.out.println(JsonFormat.printer().print(response));
    }
  }
}

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to create membership with user credential for a human user
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.memberships'
 * referenced in the manifest file (appsscript.json).
 */
function createMembershipUserCred() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';
  const membership = {
    member: {
      // TODO(developer): Replace USER_NAME here
      name: 'users/USER_NAME',
      // User type for the membership
      type: 'HUMAN'
    }
  };

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

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

Para executar a amostra, substitua o seguinte:

  • SPACE_NAME: o ID do name do espaço. Você pode conseguir o ID chamando o método ListSpaces() ou pelo URL do espaço.
  • USER_NAME: um ID de usuário.

A API Chat retorna uma instância de Membership que detalha a associação do usuário que foi criada.

Convidar ou adicionar um grupo do Google a um espaço

Para convidar ou adicionar um Grupo do Google a um espaço com autenticação do usuário (a autenticação de app não oferece suporte a esse recurso), transmita o seguinte na sua solicitação:

  • Especifique o escopo de autorização chat.memberships.
  • Chame o método CreateMembership().
  • Transmita parent como o nome do recurso do espaço em que a associação será criada.
  • Transmita membership como uma instância de Membership com o campo name de groupMember definido como 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.

Os Grupos do Google não podem ser adicionados a uma conversa em grupo ou mensagem direta, apenas a um espaço com nome.

O exemplo a seguir adiciona um grupo a um espaço nomeado com autenticação do usuário:

Node.js

chat/client-libraries/cloud/create-membership-user-cred-for-group.js
import {createClientWithUserCredentials} from './authentication-utils.js';

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

// This sample shows how to create membership with user credential for a group
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    membership: {
      groupMember: {
        // Replace GROUP_NAME here
        name: 'groups/GROUP_NAME'
      }
    }
  };

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

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

main().catch(console.error);

Python

chat/client-libraries/cloud/create_membership_user_cred_for_group.py
from authentication_utils import create_client_with_user_credentials
from google.apps import chat_v1 as google_chat

SCOPES = ["https://www.googleapis.com/auth/chat.memberships"]

# This sample shows how to create membership with user credential for a group
def create_membership_with_user_cred_for_group():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.CreateMembershipRequest(
        # Replace SPACE_NAME here
        parent = "spaces/SPACE_NAME",
        membership = {
            "groupMember": {
                # Replace GROUP_NAME here
                "name": "groups/GROUP_NAME"
            }
        }
    )

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

    # Handle the response
    print(response)

create_membership_with_user_cred_for_group()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMembershipUserCredForGroup.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMembershipRequest;
import com.google.chat.v1.Membership;
import com.google.chat.v1.SpaceName;
import com.google.chat.v1.Group;

// This sample shows how to create membership with user credential for a group.
public class CreateMembershipUserCredForGroup {

  private static final String SCOPE =
    "https://www.googleapis.com/auth/chat.memberships";

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      CreateMembershipRequest.Builder request = CreateMembershipRequest.newBuilder()
        // replace SPACE_NAME here
        .setParent("spaces/SPACE_NAME")
        .setMembership(Membership.newBuilder()
          .setGroupMember(Group.newBuilder()
            // replace GROUP_NAME here
            .setName("groups/GROUP_NAME")));
      Membership response = chatServiceClient.createMembership(request.build());

      System.out.println(JsonFormat.printer().print(response));
    }
  }
}

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to create membership with user credential for a group
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.memberships'
 * referenced in the manifest file (appsscript.json).
 */
function createMembershipUserCredForGroup() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';
  const membership = {
    groupMember: {
      // TODO(developer): Replace GROUP_NAME here
      name: 'groups/GROUP_NAME'
    }
  };

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

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

Para executar a amostra, substitua o seguinte:

  • SPACE_NAME: o ID do name do espaço. Para conseguir o ID, chame o método ListSpaces() ou o URL do espaço.
  • GROUP_NAME: um ID de grupo.

A API Chat retorna uma instância de Membership que detalha a associação do usuário que foi criada.

Adicionar um app de chat a um espaço

Um app de chat não pode adicionar outro app como participante de um espaço. Para adicionar um app do Chat a um espaço ou a uma mensagem direta entre dois usuários humanos, transmita o seguinte na sua solicitação com a autenticação do usuário. A autenticação de app não oferece suporte para convidar ou adicionar um app do Chat a um espaço:

  • Especifique o escopo de autorização chat.memberships.app.
  • Chame o método CreateMembership().
  • Transmita parent como o nome do recurso do espaço em que a associação será criada.
  • Transmita membership como uma instância de Membership com o campo member definido da seguinte maneira:
    • O campo type definido como BOT.
    • O campo name definido como users/app, um alias que representa o app que chama a API Chat.

O exemplo a seguir adiciona um app do Chat a um espaço:

Node.js

chat/client-libraries/cloud/create-membership-user-cred-for-app.js
import {createClientWithUserCredentials} from './authentication-utils.js';

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

// This sample shows how to create membership with app credential for an app
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    membership: {
      member: {
        // Member name for app membership, do not change this
        name: 'users/app',
        // User type for the membership
        type: 'BOT'
      }
    }
  };

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

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

main().catch(console.error);

Python

chat/client-libraries/cloud/create_membership_user_cred_for_app.py
from authentication_utils import create_client_with_user_credentials
from google.apps import chat_v1 as google_chat

SCOPES = ["https://www.googleapis.com/auth/chat.memberships.app"]

# This sample shows how to create membership with app credential for an app
def create_membership_with_user_cred_for_app():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.CreateMembershipRequest(
        # Replace SPACE_NAME here
        parent = "spaces/SPACE_NAME",
        membership = {
            "member": {
                # member name for app membership, do not change this.
                "name": "users/app",
                # user type for the membership
                "type_": "BOT"
            }
        }
    )

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

    # Handle the response
    print(response)

create_membership_with_user_cred_for_app()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMembershipUserCredForApp.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMembershipRequest;
import com.google.chat.v1.Membership;
import com.google.chat.v1.SpaceName;
import com.google.chat.v1.User;

// This sample shows how to create membership with user credential for the
// calling app.
public class CreateMembershipUserCredForApp {

  private static final String SCOPE =
    "https://www.googleapis.com/auth/chat.memberships.app";

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      CreateMembershipRequest.Builder request = CreateMembershipRequest.newBuilder()
        // replace SPACE_NAME here
        .setParent("spaces/SPACE_NAME")
        .setMembership(Membership.newBuilder()
          .setMember(User.newBuilder()
            // member name for app membership, do not change this.
            .setName("users/app")
            // user type for the membership
            .setType(User.Type.BOT)));
      Membership response = chatServiceClient.createMembership(request.build());

      System.out.println(JsonFormat.printer().print(response));
    }
  }
}

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to create membership with app credential for an app
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.memberships.app'
 * referenced in the manifest file (appsscript.json).
 */
function createMembershipUserCredForApp() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';
  const membership = {
    member: {
      // Member name for app membership, do not change this
      name: 'users/app',
      // User type for the membership
      type: 'BOT'
    }
  };

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

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

Para executar o exemplo, substitua SPACE_NAME pelo ID do name do espaço. Você pode conseguir o ID chamando o método ListSpaces() ou pelo URL do espaço.

A API Chat retorna uma instância de Membership que detalha a associação do usuário que foi criada.

Convidar ou adicionar um usuário a um espaço como um app do Chat

A autenticação do app exige uma única aprovação do administrador.

Para convidar ou adicionar um usuário a um espaço com autenticação de app, transmita o seguinte na sua solicitação:

  • Especifique o escopo de autorização chat.app.memberships.
  • Chame o método create no recurso membership.
  • Defina parent como o nome do recurso do espaço em que a associação será criada.
  • Defina member como users/{user}, em que {user} é a pessoa para quem você quer criar a associação, e é:
    • O ID da pessoa na API People. Por exemplo, se a API People person resourceName for people/123456789, defina membership.member.name como users/123456789.
    • O ID do usuário na API Directory.
    • O endereço de e-mail do usuário. Por exemplo, users/222larabrown@gmail.com ou users/larabrown@cymbalgroup.com. Se o usuário usar uma Conta do Google ou pertencer a uma organização do Google Workspace diferente, use o endereço de e-mail dele.

crie uma chave de API

Para chamar um método da prévia para desenvolvedores da API, use uma versão não pública da prévia para desenvolvedores do documento de descoberta da API. Para autenticar a solicitação, é necessário transmitir uma chave de API.

Para criar a chave de API, abra o projeto do Google Cloud do app e siga estas etapas:

  1. No console do Google Cloud, acesse Menu > APIs e serviços > Credenciais.

    Ir para Credenciais

  2. Clique em Criar credenciais > Chave de API.
  3. Sua nova chave de API vai aparecer.
    • Clique em Copiar para copiar a chave de API e usá-la no código do app. A chave de API também pode ser encontrada na seção "Chaves de API" das credenciais do projeto.
    • Clique em Restringir chave para atualizar as configurações avançadas e limitar o uso da chave de API. Para mais detalhes, consulte Como aplicar restrições de chave de API.

Programar um script que chame a API Chat

O exemplo a seguir adiciona um usuário a um espaço com autenticação de app:

Python

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

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

    from google.oauth2 import service_account
from apiclient.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.app.memberships"]

def main():
    '''
    Authenticates with Chat API using app authentication,
    then adds a user to a Chat space by creating a membership.
    '''

    # Specify service account details.
    creds = (
        service_account.Credentials.from_service_account_file('credentials.json')
        .with_scopes(SCOPES)
    )

    # Build a service endpoint for Chat API.
    chat = build('chat', 'v1', credentials=creds, discoveryServiceUrl='https://chat.googleapis.com/$discovery/rest?version=v1&labels=DEVELOPER_PREVIEW&key=API_KEY')

    # Use the service endpoint to call Chat API.
    result = chat.spaces().members().create(

        # The space in which to create a membership.
        parent = 'spaces/SPACE',

        # Specify which user the membership is for.
        body = {
          'member': {
            'name':'users/USER',
            'type': 'HUMAN'
          }
        }

    ).execute()

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

if __name__ == '__main__':
    main()

  3. No código, substitua o seguinte:

    • API_KEY: a chave de API criada para criar o endpoint de serviço da API Chat.

    • SPACE: um nome de espaço, que pode ser encontrado no método spaces.list na API Chat ou no URL de um espaço.

    • USER: um ID de usuário.

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

    python3 chat_membership_app_create.py

Adicionar usuários ou grupos do Google a um espaço como administrador do Google Workspace

Se você for um administrador do Google Workspace, poderá chamar o método create() para adicionar usuários, grupos do Google ou apps do Chat a qualquer espaço na sua organização do Google Workspace.

Para chamar esse método como administrador do Google Workspace, faça o seguinte:

Para mais informações e exemplos, consulte Gerenciar espaços do Google Chat como administrador do Google Workspace.

Limitações e considerações

  • Com a autenticação de apps, um app de chat pode convidar ou adicionar usuários, mas não grupos do Google ou apps de chat. Para adicionar a si mesmo, um app de chat precisa usar a autenticação do usuário com o escopo de autorização chat.memberships.