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 mettre à jour la disponibilité d'un utilisateur Chat, votre application doit s'authentifier avec l'authentification utilisateur. Seule la disponibilité de l'utilisateur authentifié peut être consultée ou modifiée.

Prérequis

Node.js

Python

Java

Apps Script

Afficher la disponibilité d'un utilisateur

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

  • Indiquez le champ d'application de l'autorisation chat.users.availability.readonly ou chat.users.availability.
  • Appelez la méthode GetAvailability.
  • 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 détaillant l'état de présence et le statut personnalisé de l'utilisateur.

Modifier l'état personnalisé

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

  • Spécifiez le champ d'application de l'autorisation chat.users.availability.
  • Appelez la méthode UpdateAvailability.
  • 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 supprimer l'état personnalisé d'un utilisateur, mettez à jour sa disponibilité et omettez les détails customStatus.

Mettre à jour l'état de présence

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

  • Actif : appelez la méthode MarkAsActive pour définir la présence sur "actif". Des valeurs d'expiration facultatives (ttl ou expireTime) peuvent être fournies.
  • Absent : appelez la méthode MarkAsAway pour définir l'état de présence sur "Absent".
  • Ne pas déranger : appelez la méthode MarkAsDoNotDisturb pour couper le son des notifications.

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

Identifier les changements 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é se produit, l'application reçoit un événement avec une charge utile contenant la ressource Availability.