Gérer la disponibilité des utilisateurs pour les applications Chat

Ce guide explique comment utiliser l'API Google Chat pour gérer l'état de disponibilité et l'état personnalisé d'un utilisateur.

Pour lire et modifier la disponibilité d'un utilisateur Chat, votre application doit s'authentifier avec l'utilisateur. Seule la disponibilité de l'utilisateur authentifié peut être consultée ou modifiée.

Prérequis

Node.js

Python

Java

Apps Script

Obtenir la disponibilité d'un utilisateur

Pour lire la disponibilité d'un utilisateur Google Chat, transmettez les éléments suivants dans votre requête :

  • Spécifiez le chat.users.availability.readonly ou chat.users.availability champ d'application d'autorisation.
  • Appelez la GetAvailability méthode.
  • Transmettez le name de la ressource de disponibilité à récupérer. Le nom doit être au format users/{user}/availability. L'adresse e-mail de l'utilisateur ou l'alias me peuvent être utilisés pour faire référence à l'appelant. Par exemple, users/me/availability.

Voici comment obtenir la disponibilité d'un utilisateur :

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

L'API Chat renvoie une instance de Availability qui détaille l'état de présence et l'état personnalisé de l'utilisateur.

Modifier l'état personnalisé

Pour modifier l'état personnalisé d'un utilisateur, transmettez les éléments suivants dans votre requête :

  • Spécifiez le champ d'application d'autorisation chat.users.availability.
  • Appelez la UpdateAvailability méthode.
  • Transmettez la ressource Availability, en spécifiant les nouveaux détails customStatus.
  • Définissez le paramètre update_mask pour inclure le champ custom_status.

Voici comment modifier l'état personnalisé d'un utilisateur :

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

L'API Chat met à jour et renvoie une instance de Availability avec le nouvel état personnalisé.

Pour effacer l'état personnalisé d'un utilisateur, mettez à jour la disponibilité et omettez les détails customStatus.

Modifier l'état de présence

En fonction de l'état de présence cible, vous pouvez modifier la disponibilité d'un utilisateur en appelant l'une des méthodes personnalisées suivantes :

  • Actif : appelez la MarkAsActive méthode pour définir la présence sur "Actif". Des valeurs d'expiration facultatives (ttl ou expireTime) peuvent être fournies.
  • Absent : appelez la MarkAsAway méthode pour définir la présence sur "Absent".
  • Ne pas déranger : appelez la MarkAsDoNotDisturb méthode pour désactiver les notifications.

Pour en savoir plus, y compris sur les descriptions des champs et les modèles de requête, consultez le guide de référence de chaque méthode.

Identifier les modifications de disponibilité à partir d'un événement

Votre application Chat peut s'abonner aux événements google.workspace.chat.availability.v1.updated pour recevoir des notifications lorsque la disponibilité d'un utilisateur change. Lorsqu'une mise à jour de la disponibilité a lieu, l'application reçoit un événement avec une charge utile contenant la ressource Availability.