Mengelola ketersediaan pengguna untuk aplikasi Chat

Panduan ini menjelaskan cara menggunakan Google Chat API untuk mengelola status ketersediaan dan status kustom pengguna.

Untuk membaca dan memperbarui ketersediaan pengguna Chat, aplikasi Anda harus melakukan autentikasi dengan autentikasi pengguna. Hanya ketersediaan pengguna yang diautentikasi yang dapat diakses atau diubah.

Prasyarat

Node.js

Python

Java

Apps Script

Mendapatkan ketersediaan pengguna

Untuk membaca ketersediaan pengguna Google Chat, teruskan hal berikut dalam permintaan Anda:

  • Tentukan chat.users.availability.readonly atau chat.users.availability cakupan otorisasi.
  • Panggil GetAvailability metode.
  • Teruskan name resource ketersediaan yang akan diambil. Nama harus diformat sebagai users/{user}/availability. Alamat email pengguna atau alias me dapat digunakan untuk merujuk ke pemanggil. Misalnya, users/me/availability.

Berikut cara mendapatkan ketersediaan pengguna:

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 menampilkan instance Availability yang menjelaskan status kehadiran dan status kustom pengguna.

Memperbarui status kustom

Untuk memperbarui status kustom pengguna, teruskan hal berikut dalam permintaan Anda:

  • Tentukan cakupan otorisasi chat.users.availability.
  • Panggil metode.UpdateAvailability
  • Teruskan resource Availability, yang menentukan detail customStatus baru.
  • Tetapkan parameter update_mask untuk menyertakan kolom custom_status.

Berikut cara memperbarui status kustom pengguna:

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);
  }
}

Chat API memperbarui dan menampilkan instance Availability dengan status kustom baru.

Untuk menghapus status kustom pengguna, perbarui ketersediaan dan hapus detail customStatus.

Memperbarui status kehadiran

Bergantung pada status kehadiran target, Anda dapat memperbarui ketersediaan pengguna dengan memanggil salah satu metode kustom berikut:

  • Aktif: Panggil MarkAsActive metode untuk menetapkan kehadiran ke aktif. Nilai masa berlaku opsional (ttl atau expireTime) dapat diberikan.
  • Tidak ada: Panggil metode MarkAsAway untuk menetapkan kehadiran ke tidak ada.
  • Jangan ganggu: Panggil metode MarkAsDoNotDisturb untuk menonaktifkan notifikasi.

Untuk mengetahui detailnya, termasuk deskripsi kolom dan template kueri, lihat panduan referensi setiap metode.

Mengidentifikasi perubahan ketersediaan dari suatu peristiwa

Aplikasi Chat Anda dapat berlangganan peristiwa google.workspace.chat.availability.v1.updated untuk mendapatkan notifikasi saat ketersediaan pengguna berubah. Saat pembaruan ketersediaan terjadi, aplikasi akan menerima peristiwa dengan payload yang berisi resource Availability.