Quản lý trạng thái hoạt động của người dùng đối với các ứng dụng nhắn tin

Hướng dẫn này giải thích cách sử dụng Google Chat API để quản lý trạng thái rảnh/bận và trạng thái tuỳ chỉnh của người dùng.

Để đọc và cập nhật trạng thái rảnh/bận của người dùng Chat, ứng dụng của bạn phải xác thực bằng quy trình xác thực người dùng. Chỉ có thể truy cập hoặc sửa đổi trạng thái rảnh/bận của người dùng đã xác thực.

Điều kiện tiên quyết

Node.js

Python

Java

Apps Script

Xem tình trạng rảnh/bận của người dùng

Để đọc trạng thái hoạt động của người dùng Google Chat, hãy truyền các thông tin sau trong yêu cầu của bạn:

  • Chỉ định phạm vi uỷ quyền chat.users.availability.readonly hoặc chat.users.availability.
  • Gọi phương thức GetAvailability.
  • Truyền name của tài nguyên về tình trạng còn phòng để truy xuất. Tên phải có định dạng là users/{user}/availability. Bạn có thể dùng địa chỉ email của người dùng hoặc email đại diện me để đề cập đến người gọi. Ví dụ: users/me/availability.

Sau đây là cách lấy thông tin về trạng thái rảnh/bận của người dùng:

Node.js

const { ChatServiceClient } = require('@google-apps/chat').v1;

// Instantiates a client
const chatServiceClient = new ChatServiceClient();

async function getAvailability() {
  const request = {
    // The name of the availability resource to retrieve.
    // Format: users/{user}/availability
    // The 'me' alias can be used to refer to the calling user.
    name: 'users/me/availability',
  };

  try {
    const response = await chatServiceClient.getAvailability(request);
    console.log(response);
  } catch (err) {
    console.error('Error retrieving availability:', err);
  }
}

getAvailability();

Python

from google.apps import chat_v1 as google_chat

def get_availability():
    # Instantiates a client
    client = google_chat.ChatServiceClient()

    # Prepare request
    request = google_chat.GetAvailabilityRequest(
        # Format: users/{user}/availability
        # The 'me' alias refers to the calling user.
        name="users/me/availability",
    )

    # Call the API
    try:
        response = client.get_availability(request=request)
        print(response)
    except Exception as e:
        print(f"Error retrieving availability: {e}")

get_availability()

Java

import com.google.chat.v1.Availability;
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.GetAvailabilityRequest;

public class GetAvailability {
  public static void main(String[] args) throws Exception {
    // Instantiates a client
    try (ChatServiceClient chatServiceClient = ChatServiceClient.create()) {
      GetAvailabilityRequest request = GetAvailabilityRequest.newBuilder()
          // Format: users/{user}/availability
          // The 'me' alias refers to the calling user.
          .setName("users/me/availability")
          .build();

      Availability response = chatServiceClient.getAvailability(request);
      System.out.println(response);
    }
  }
}

Apps Script

/**
 * Retrieves the calling user's availability details.
 */
function getUserAvailability() {
  const name = 'users/me/availability';
  try {
    const availability = Chat.Users.Availability.get(name);
    console.log(availability);
  } catch (err) {
    console.error('Failed to get availability: ' + err.message);
  }
}

Chat API trả về một phiên bản Availability, trong đó nêu chi tiết trạng thái hiện diện và trạng thái tuỳ chỉnh của người dùng.

Cập nhật trạng thái tuỳ chỉnh

Để cập nhật trạng thái tuỳ chỉnh của người dùng, hãy truyền các thông tin sau trong yêu cầu của bạn:

  • Chỉ định phạm vi uỷ quyền chat.users.availability.
  • Gọi phương thức UpdateAvailability.
  • Truyền tài nguyên Availability, chỉ định thông tin chi tiết mới về customStatus.
  • Đặt tham số update_mask để thêm trường custom_status.

Sau đây là cách cập nhật trạng thái tuỳ chỉnh của người dùng:

Node.js

const { ChatServiceClient } = require('@google-apps/chat').v1;

// Instantiates a client
const chatServiceClient = new ChatServiceClient();

async function updateCustomStatus() {
  const request = {
    // The Availability resource to update.
    availability: {
      name: 'users/me/availability',
      customStatus: {
        text: 'In a meeting',
        emoji: {
          unicode: '📅'
        }
      }
    },
    // The fields to update. Must contain 'custom_status'.
    updateMask: {
      paths: ['custom_status']
    }
  };

  try {
    const response = await chatServiceClient.updateAvailability(request);
    console.log(response);
  } catch (err) {
    console.error('Error updating status:', err);
  }
}

updateCustomStatus();

Python

from google.apps import chat_v1 as google_chat
from google.protobuf import field_mask_pb2

def update_custom_status():
    # Instantiates a client
    client = google_chat.ChatServiceClient()

    # Define custom status and emoji
    custom_status = google_chat.CustomStatus(
        text="In a meeting",
        emoji=google_chat.Emoji(unicode="📅")
    )

    # Initialize availability object
    availability = google_chat.Availability(
        name="users/me/availability",
        custom_status=custom_status
    )

    # Specify update mask
    update_mask = field_mask_pb2.FieldMask(paths=["custom_status"])

    # Prepare request
    request = google_chat.UpdateAvailabilityRequest(
        availability=availability,
        update_mask=update_mask
    )

    # Call the API
    try:
        response = client.update_availability(request=request)
        print(response)
    except Exception as e:
        print(f"Error updating status: {e}")

update_custom_status()

Java

import com.google.chat.v1.Availability;
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CustomStatus;
import com.google.chat.v1.Emoji;
import com.google.chat.v1.UpdateAvailabilityRequest;
import com.google.protobuf.FieldMask;

public class UpdateCustomStatus {
  public static void main(String[] args) throws Exception {
    // Instantiates a client
    try (ChatServiceClient chatServiceClient = ChatServiceClient.create()) {
      CustomStatus customStatus = CustomStatus.newBuilder()
          .setText("In a meeting")
          .setEmoji(Emoji.newBuilder().setUnicode("📅"))
          .build();

      Availability availability = Availability.newBuilder()
          .setName("users/me/availability")
          .setCustomStatus(customStatus)
          .build();

      FieldMask updateMask = FieldMask.newBuilder()
          .addPaths("custom_status")
          .build();

      UpdateAvailabilityRequest request = UpdateAvailabilityRequest.newBuilder()
          .setAvailability(availability)
          .setUpdateMask(updateMask)
          .build();

      Availability response = chatServiceClient.updateAvailability(request);
      System.out.println(response);
    }
  }
}

Apps Script

/**
 * Updates the calling user's custom status message.
 */
function updateCustomStatus() {
  const name = 'users/me/availability';
  const availability = {
    customStatus: {
      text: 'In a meeting',
      emoji: {
        unicode: '📅'
      }
    }
  };
  const updateMask = 'custom_status';

  try {
    const response = Chat.Users.Availability.patch(availability, name, {
      updateMask: updateMask
    });
    console.log(response);
  } catch (err) {
    console.error('Failed to update status: ' + err.message);
  }
}

API Chat sẽ cập nhật và trả về một phiên bản của Availability với trạng thái tuỳ chỉnh mới.

Để xoá trạng thái tuỳ chỉnh của người dùng, hãy cập nhật trạng thái rảnh và bỏ qua thông tin chi tiết về customStatus.

Cập nhật trạng thái hiện diện

Tuỳ thuộc vào trạng thái hiện diện mục tiêu, bạn có thể cập nhật trạng thái rảnh/bận của người dùng bằng cách gọi một trong các phương thức tuỳ chỉnh sau:

  • Đang hoạt động: Gọi phương thức MarkAsActive để đặt trạng thái hiện diện thành đang hoạt động. Bạn có thể cung cấp các giá trị hết hạn không bắt buộc (ttl hoặc expireTime).
  • Vắng mặt: Gọi phương thức MarkAsAway để đặt trạng thái hiện diện thành vắng mặt.
  • Không làm phiền: Gọi phương thức MarkAsDoNotDisturb để tắt tiếng thông báo.

Để biết thông tin chi tiết, bao gồm cả nội dung mô tả trường và mẫu truy vấn, hãy xem hướng dẫn tham khảo của từng phương thức.

Xác định các thay đổi về tình trạng còn chỗ của một sự kiện

Ứng dụng Chat của bạn có thể đăng ký nhận các sự kiện google.workspace.chat.availability.v1.updated để nhận thông báo khi trạng thái rảnh/bận của người dùng thay đổi. Khi có thông tin cập nhật về tình trạng còn hàng, ứng dụng sẽ nhận được một sự kiện có tải trọng chứa tài nguyên Availability.