Verfügbarkeit von Nutzern für Chat-Apps verwalten

In diesem Leitfaden wird beschrieben, wie Sie mit der Google Chat API den Verfügbarkeitsstatus und den benutzerdefinierten Status eines Nutzers verwalten.

Wenn Ihre App die Verfügbarkeit eines Chat-Nutzers lesen und aktualisieren soll, muss sie sich mit der Nutzerauthentifizierung authentifizieren. Nur die Verfügbarkeit des authentifizierten Nutzers kann aufgerufen oder geändert werden.

Vorbereitung

Node.js

Python

Java

Apps Script

Verfügbarkeit eines Nutzers abrufen

Um die Verfügbarkeit eines Google Chat-Nutzers abzurufen, übergeben Sie Folgendes in Ihrer Anfrage:

  • Geben Sie den Autorisierungsbereich chat.users.availability.readonly oder chat.users.availability an.
  • Rufen Sie die Methode GetAvailability auf.
  • Übergeben Sie die name der abzurufenden Verfügbarkeitsressource. Der Name muss als users/{user}/availability formatiert sein. Die E-Mail-Adresse des Nutzers oder der me-Alias kann verwendet werden, um sich auf den Anrufer zu beziehen. Beispiel: users/me/availability.

So rufen Sie die Verfügbarkeit eines Nutzers ab:

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

Die Chat API gibt eine Instanz von Availability zurück, in der der Präsenzstatus und der benutzerdefinierte Status des Nutzers beschrieben werden.

Benutzerdefinierten Status aktualisieren

Wenn Sie den benutzerdefinierten Status eines Nutzers aktualisieren möchten, übergeben Sie Folgendes in Ihrer Anfrage:

  • Geben Sie den chat.users.availability-Autorisierungsbereich an.
  • Rufen Sie die Methode UpdateAvailability auf.
  • Übergeben Sie die Ressource Availability und geben Sie die neuen customStatus-Details an.
  • Legen Sie den Parameter update_mask fest, um das Feld custom_status einzuschließen.

So aktualisieren Sie den benutzerdefinierten Status eines Nutzers:

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

Die Chat API aktualisiert und gibt eine Instanz von Availability mit dem neuen benutzerdefinierten Status zurück.

Wenn Sie den benutzerdefinierten Status eines Nutzers löschen möchten, aktualisieren Sie die Verfügbarkeit und lassen Sie die customStatus-Details weg.

Anwesenheitsstatus aktualisieren

Je nach Anwesenheitsstatus des Ziels können Sie die Verfügbarkeit eines Nutzers aktualisieren, indem Sie eine der folgenden benutzerdefinierten Methoden aufrufen:

  • Aktiv: Rufen Sie die Methode MarkAsActive auf, um den Anwesenheitsstatus auf „Aktiv“ zu setzen. Optionale Ablaufwerte (ttl oder expireTime) können angegeben werden.
  • Abwesend: Rufen Sie die Methode MarkAsAway auf, um den Anwesenheitsstatus auf „Abwesend“ zu setzen.
  • Bitte nicht stören: Rufen Sie die Methode MarkAsDoNotDisturb auf, um Benachrichtigungen stummzuschalten.

Weitere Informationen, einschließlich Feldbeschreibungen und Abfragevorlagen, finden Sie im Referenzleitfaden für die jeweilige Methode.

Verfügbarkeitsänderungen durch ein Ereignis erkennen

Ihre Chat-App kann google.workspace.chat.availability.v1.updated-Ereignisse abonnieren, um Benachrichtigungen zu erhalten, wenn sich die Verfügbarkeit eines Nutzers ändert. Wenn eine Verfügbarkeitsaktualisierung erfolgt, erhält die App ein Ereignis mit einer Nutzlast, die die Availability-Ressource enthält.