Gestire la disponibilità degli utenti per le app di chat

Questa guida spiega come utilizzare l'API Google Chat per gestire lo stato di disponibilità e lo stato personalizzato di un utente.

Per leggere e aggiornare la disponibilità di un utente di Chat, la tua app deve autenticarsi con l'autenticazione utente. È possibile accedere o modificare solo la disponibilità dell'utente autenticato.

Prerequisiti

Node.js

Python

Java

Apps Script

Visualizzare la disponibilità di un utente

Per leggere la disponibilità di un utente di Google Chat, passa quanto segue nella tua richiesta:

  • Specifica l'ambito di autorizzazione chat.users.availability.readonly o chat.users.availability.
  • Chiama il metodo GetAvailability.
  • Trasmetti il name della risorsa di disponibilità da recuperare. Il nome deve essere nel formato users/{user}/availability. L'indirizzo email dell'utente o l'alias me può essere utilizzato per fare riferimento al chiamante. Ad esempio users/me/availability.

Ecco come ottenere la disponibilità di un utente:

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 restituisce un'istanza di Availability che descrive in dettaglio lo stato di presenza e lo stato personalizzato dell'utente.

Aggiornare lo stato personalizzato

Per aggiornare lo stato personalizzato di un utente, passa quanto segue nella richiesta:

  • Specifica l'ambito di autorizzazione chat.users.availability.
  • Chiama il metodo UpdateAvailability.
  • Passa la risorsa Availability, specificando i nuovi dettagli customStatus.
  • Imposta il parametro update_mask in modo da includere il campo custom_status.

Ecco come aggiornare lo stato personalizzato di un utente:

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 aggiorna e restituisce un'istanza di Availability con il nuovo stato personalizzato.

Per cancellare lo stato personalizzato di un utente, aggiorna la disponibilità e ometti i dettagli di customStatus.

Aggiornare lo stato di presenza

A seconda dello stato di presenza di destinazione, puoi aggiornare la disponibilità di un utente chiamando uno dei seguenti metodi personalizzati:

  • Attivo: chiama il metodo MarkAsActive per impostare lo stato di presenza su attivo. È possibile fornire valori di scadenza facoltativi (ttl o expireTime).
  • Assente: chiama il metodo MarkAsAway per impostare lo stato di presenza su assente.
  • Non disturbare: chiama il metodo MarkAsDoNotDisturb per disattivare le notifiche.

Per maggiori dettagli, tra cui descrizioni dei campi e modelli di query, consulta la guida di riferimento di ogni metodo.

Identificare le modifiche alla disponibilità da un evento

La tua app Chat può iscriversi agli eventi google.workspace.chat.availability.v1.updated per ricevere notifiche quando la disponibilità di un utente cambia. Quando si verifica un aggiornamento della disponibilità, l'app riceve un evento con un payload contenente la risorsa Availability.