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

Este guia explica como usar o método create() no recurso Membership da API Google Chat para convidar ou adicionar um usuário, um grupo do Google ou um app Chat a um espaço, também conhecido como criar uma associação. 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á aceitar o convite do espaço antes de participar. Caso contrário, a criação de uma assinatura adiciona o membro diretamente ao espaço especificado.

Se você for administrador do Google Workspace, poderá 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 um app do Google Chat foi convidado para um espaço, faz parte dele ou não está presente.

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 de 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 assinatura será criada.
  • Transmita membership como uma instância de Membership com o campo member definido com o seguinte:
    • 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 o person resourceName da API People 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 outra organização do Google Workspace, use o endereço de e-mail dele.

O exemplo a seguir adiciona um usuário a um espaço com autenticação de 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 no 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 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 de usuário (a autenticação de app não permite convidar ou adicionar um Grupo do Google a um espaço), 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 assinatura 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 uma associação. O ID do grupo pode ser recuperado usando a API Cloud Identity.

Os grupos do Google não podem ser adicionados a um chat em grupo ou mensagem direta, apenas a um espaço nomeado.

O exemplo a seguir adiciona um grupo a um espaço nomeado com autenticação de 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. Você pode conseguir o ID chamando o método ListSpaces() ou no 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 criada.

Adicionar um app do Chat a um espaço

Um app do Chat não pode adicionar outro app como participante de um espaço. Para adicionar um app do Chat a um espaço ou uma mensagem direta entre dois usuários humanos, transmita o seguinte na sua solicitação com autenticação de usuário (a autenticação de app não permite 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 assinatura será criada.
  • Transmita membership como uma instância de Membership com o campo member definido com o seguinte:
    • 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 a amostra, substitua SPACE_NAME pelo ID do name do espaço. Você pode conseguir o ID chamando o método ListSpaces() ou no URL do espaço.

A API Chat retorna uma instância de Membership que detalha a associação do usuário 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 uma assinatura e é:
    • O ID da pessoa na API People. Por exemplo, se o resourceName person da API People 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 usa uma Conta do Google ou pertence a outra organização do Google Workspace, use o endereço de e-mail dele.

Escrever um script que chama a API Chat

O exemplo a seguir adiciona um usuário a um espaço com autenticação do 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)

    # 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:

    • SPACE: o nome de um espaço, que pode ser obtido com o 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 a amostra:

    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 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 app, um app do Chat pode convidar ou adicionar usuários, mas não o Google Grupos ou apps do Chat. Para se adicionar, um app de chat precisa usar autenticação de usuário com o escopo de autorização chat.memberships.