Administra la disponibilidad de los usuarios para las apps de Chat

En esta guía, se explica cómo usar la API de Google Chat para administrar el estado de disponibilidad y el estado personalizado de un usuario.

Para leer y actualizar la disponibilidad de un usuario de Chat, tu app debe autenticarse con la autenticación de usuario. Solo se puede acceder a la disponibilidad del usuario autenticado o modificarla.

Requisitos previos

Node.js

Python

Java

Apps Script

Obtén la disponibilidad de un usuario

Para leer la disponibilidad de un usuario de Google Chat, pasa lo siguiente en tu solicitud:

  • Especifica el alcance de autorización chat.users.availability.readonly o chat.users.availability.
  • Realiza una llamada al método GetAvailability.
  • Pasa el name del recurso de disponibilidad que se recuperará. El nombre debe tener el formato users/{user}/availability. Se puede usar la dirección de correo electrónico del usuario o el alias me para hacer referencia a la persona que llama. Por ejemplo, users/me/availability

Sigue estos pasos para obtener la disponibilidad de un usuario:

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

La API de Chat devuelve una instancia de Availability que detalla el estado de presencia y el estado personalizado del usuario.

Actualiza el estado personalizado

Para actualizar el estado personalizado de un usuario, pasa lo siguiente en tu solicitud:

  • Especifica el alcance de autorización chat.users.availability.
  • Realiza una llamada al método UpdateAvailability.
  • Pasa el recurso Availability y especifica los nuevos detalles de customStatus.
  • Establece el parámetro update_mask para incluir el campo custom_status.

Sigue estos pasos para actualizar el estado personalizado de un usuario:

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

La API de Chat actualiza y devuelve una instancia de Availability con el nuevo estado personalizado.

Para borrar el estado personalizado de un usuario, actualiza la disponibilidad y omite los detalles de customStatus.

Actualiza el estado de presencia

Según el estado de presencia del objetivo, puedes actualizar la disponibilidad de un usuario llamando a uno de los siguientes métodos personalizados:

  • Activa: Llama al método MarkAsActive para establecer la presencia como activa. Se pueden proporcionar valores de vencimiento opcionales (ttl o expireTime).
  • Ausente: Llama al método MarkAsAway para establecer el estado de presencia como ausente.
  • No interrumpir: Llama al método MarkAsDoNotDisturb para silenciar las notificaciones.

Para obtener detalles, incluidas las descripciones de los campos y las plantillas de consultas, consulta la guía de referencia de cada método.

Identifica los cambios de disponibilidad a partir de un evento

Tu app de Chat puede suscribirse a eventos de google.workspace.chat.availability.v1.updated para recibir notificaciones cuando cambie la disponibilidad de un usuario. Cuando se produce una actualización de disponibilidad, la app recibe un evento con una carga útil que contiene el recurso Availability.