Iscriviti agli eventi di Google Chat

Questa pagina descrive gli eventi di Chat a cui un'app di Chat può iscriversi utilizzando l'API Google Workspace Events. Dopo aver deciso di quali tipi di eventi hai bisogno, crea un abbonamento per iniziare a ricevere eventi da Chat.

Oltre a iscriverti agli eventi, puoi anche eseguire query sugli eventi chiamando l'API Google Chat. La chiamata all'API Chat ti consente di recuperare gli eventi periodicamente o di recuperare gli eventi che potresti aver perso da un abbonamento a causa di un'interruzione. Per scoprire i modi in cui puoi ricevere e rispondere agli eventi di Chat, consulta Utilizza gli eventi di Chat nella documentazione di Chat.

Eventi di Chat supportati

Gli abbonamenti a Google Workspace ti consentono di ricevere eventi relativi ai seguenti tipi di modifiche in Chat:

• Messaggi nuovi, aggiornati o eliminati nello spazio.
• Reazioni nuove o rimosse a un messaggio.
• Membri nuovi, aggiornati o rimossi nello spazio.
• Modifiche allo spazio a cui hai effettuato l'iscrizione, ad esempio un nome o una descrizione dello spazio aggiornati.
• Modifiche alla disponibilità dell'utente.
• Modifiche allo stato spaceReadState o threadReadState dell'utente.

Risorse che puoi monitorare per gli eventi

Per ricevere gli eventi, devi specificare una risorsa Chat da monitorare, chiamata risorsa di destinazione dell'abbonamento.

L'API Google Workspace Events supporta le seguenti risorse di destinazione per Chat:

Tipi di eventi per la creazione di sottoscrizioni

Quando crei una sottoscrizione, utilizza il campo eventTypes[] per specificare i tipi di eventi che vuoi ricevere. I tipi di eventi sono formattati in base alla specifica CloudEvents, ad esempio google.workspace.APPLICATION.RESOURCE.VERSION.ACTION.

Ad esempio, per ricevere eventi relativi agli utenti che partecipano a uno spazio di Chat, specifica lo spazio come risorsa di destinazione e il tipo di evento come google.workspace.chat.membership.v1.created. Per ricevere eventi relativi all'ingresso di un determinato utente in uno spazio, specifica l'utente come risorsa di destinazione e il tipo di evento come google.workspace.chat.membership.v1.created. Per scoprire di più sul funzionamento degli eventi, consulta Struttura degli eventi di Google Workspace.

La tabella seguente mostra i tipi di eventi supportati per gli abbonamenti agli spazi e agli utenti. Per scoprire le eccezioni relative all'attivazione di un evento, consulta Limitazioni.

Tipi di eventi batch (solo output)

Oltre a ricevere i tipi di eventi a cui ti iscrivi, la tua app di Chat potrebbe anche ricevere eventi in batch. Un evento batch è un evento che rappresenta molti eventi dello stesso tipo che si verificano in un breve periodo di tempo. Il payload di un evento batch contiene un elenco di tutte le risorse modificate.

Ad esempio, se un utente aggiunge 20 utenti a uno spazio contemporaneamente, la tua app Chat potrebbe ricevere un evento batch (google.workspace.chat.membership.v1.batchCreated). Il payload dell'evento contiene un elenco di tutte le nuove risorse Membership create quando l'utente ha aggiunto i membri allo spazio.

Ricevi un evento batch per ogni tipo di evento a cui ti iscrivi, quindi non è necessario specificare gli eventi batch quando crei un'iscrizione. Ad esempio, se ti iscrivi alle nuove reazioni (google.workspace.chat.reaction.v1.created), la tua app di Chat viene configurata automaticamente per ricevere eventi di reazione in batch (google.workspace.chat.reaction.v1.batchCreated).

La tabella seguente mostra i possibili eventi batch per un abbonamento:

Dati sugli eventi

Questa sezione descrive i dati sugli eventi e i payload di esempio per gli eventi in Chat.

Quando il tuo abbonamento a Google Workspace riceve un evento da Chat, il campo data contiene il payload dell'evento. Questo payload contiene informazioni sulla risorsa Google Workspace che è stata modificata. Ad esempio, se hai sottoscritto gli eventi di iscrizione in uno spazio, il payload di questi eventi contiene informazioni sulla risorsa spaces.membership che è cambiata.

Dati della risorsa nel payload dell'evento

Quando crei una sottoscrizione, puoi specificare se vuoi che il payload includa i dettagli della risorsa o solo il nome della risorsa. Ad esempio, se vuoi ricevere eventi relativi ai membri di uno spazio di Chat, specifica quali campi di una risorsa di iscrizione vuoi ricevere nel payload dell'evento.

La tabella seguente fornisce esempi di payload JSON per un abbonamento allo spazio di Chat spaces/AAAABBBBBB. Per ogni evento ricevuto dalla sottoscrizione, il payload viene visualizzato nel campo data dell'evento:

{
    "message":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID",
        "sender":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "createTime": "2023-09-07T21:37:36.260127Z",
        "text": "Hello world",
        "thread":
        {
            "name": "spaces/SPACE_ID/threads/THREAD_ID"
        },
        "space":
        {
            "name": "spaces/SPACE_ID"
        },
        "argumentText": "Hello world"
    }
}
      

{
    "message":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID"
    }
}
      

{
    "membership":
    {
        "name": "spaces/SPACE_ID/members/MEMBER_ID",
        "state": "JOINED",
        "member":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "createTime": "1970-01-01T00:00:00Z",
        "role": "ROLE_MANAGER"
    }
}
      

{
    "membership":
    {
        "name": "spaces/SPACE_ID/members/MEMBER_ID"
    }
}
      

{
    "space":
    {
        "name": "spaces/SPACE_ID",
        "displayName": "Cymbal Sales",
        "spaceThreadingState": "THREADED_MESSAGES",
        "spaceType": "SPACE",
        "spaceDetails":
        {
            "description": "Sales team for Cymbal Labs."
        },
        "spaceHistoryState": "HISTORY_ON"
    }
}
      

{
    "space":
    {
        "name": "spaces/SPACE_ID"
    }
}
      

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID",
            "state": "JOINED",
            "member":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        },
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID",
            "state": "JOINED",
            "member":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        }
    ]
}
      

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        },
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        }
    ]
}
      

{
    "reaction":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
        "user":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "emoji":
        {
            "unicode": "😊"
        }
    }
}
      

{
    "reaction":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
    }
}
      

{
    "reactions": [
        {
          "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
            "user":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😊"
            }
          }
        },
        {
          "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
            "user":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😸"
            }
          }
        }
    ]
}
      

{
    "reactions": [
      {
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
        },
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
        }
      }
    ]
}
      

{
  "spaceReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/spaceReadState",
    "lastReadTime": "2026-04-14T14:03:46.431760Z"
  }
}
      

{
  "spaceReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/spaceReadState"
  }
}
      

{
  "threadReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/threads/THREAD_ID/threadReadState",
    "lastReadTime": "2026-04-14T14:03:46.431760Z"
  }
}
      

{
  "threadReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/threads/THREAD_ID/threadReadState"
  }
}
      

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "ACTIVE"
    }
}
      

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
      

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "IDLE",
    }
}
      

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
      

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "AWAY",
    }
}
      

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
      

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "DO_NOT_DISTURB",
        "doNotDisturbMetadata": {
          "expirationTime": "2026-03-24T18:36:31.337Z"
        }
    }
}
      

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
      

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "ACTIVE",
        "customStatus": {
          "text": "Be right back",
          "emoji": {
            "unicode": "👟"
          },
          "expireTime": "2026-03-24T18:38:05.583655Z"
        }
    }
}
      

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
      

Limitazioni generali

• Per ricevere eventi di iscrizione, l'utente o l'app di Chat deve essere un membro diretto dello spazio. Se sono stati aggiunti, aggiornati o rimossi indirettamente da uno spazio tramite un gruppo Google, l'abbonamento non riceve questi eventi di iscrizione. Per capire come funzionano le iscrizioni a Google Gruppi, consulta Aggiungi un gruppo Google a uno spazio.

Abbonamenti utente

• Per gli abbonamenti agli utenti, gli eventi relativi ai nuovi membri nei messaggi diretti o nelle chat di gruppo senza nome (google.workspace.chat.membership.v1.created) vengono attivati solo dopo la pubblicazione del primo messaggio.

Abbonamenti dei clienti

Per gli abbonamenti dei clienti si applicano le seguenti limitazioni:

• L'organizzazione Google Workspace deve avere almeno una licenza SKU Enterprise.
• Un'app di Chat può creare un solo abbonamento cliente per una determinata organizzazione Google Workspace. Un'organizzazione Google Workspace può avere fino a cinque abbonamenti dei clienti in totale (creati da diverse app di Chat).

Per gli abbonamenti dei clienti, l'invio degli eventi segue queste regole generali:

• Eventi dello spazio: vengono inviati solo se l'evento si verifica in uno spazio gestito dalla tua organizzazione Google Workspace.
• Eventi utente: vengono inviati solo se l'evento si verifica per un utente che appartiene alla tua organizzazione Google Workspace.

L'unica eccezione a queste regole riguarda gli eventi per gli abbonati. Il tuo abbonamento può ricevere eventi di iscrizione sia dagli spazi gestiti dalla tua organizzazione sia da quelli gestiti da organizzazioni esterne, ma il modo in cui vengono recapitati dipende dall'organizzazione che gestisce lo spazio:

Spazi gestiti dalla tua organizzazione Google Workspace

Se si verifica una modifica dell'iscrizione in uno spazio gestito dall'organizzazione Google Workspace, viene inviata come evento dello spazio.

Il nome della risorsa di un evento dello spazio utilizza il seguente formato:

spaces/{spaceId}/spaceEvents/{spaceEventId}

Spazi gestiti da organizzazioni esterne

Se l'appartenenza di un utente gestito dalla tua organizzazione Google Workspace cambia in uno spazio gestito da un'organizzazione esterna (ad esempio, uno spazio esterno con nome o un messaggio diretto creato da un utente esterno), il tuo abbonamento riceve questo evento come evento utente.

Il nome della risorsa di un evento utente utilizza il seguente formato:

users/{userId}/userEvents/{userEventId}

Argomenti correlati

• Struttura degli eventi di Google Workspace
• Scegli gli ambiti OAuth
• Crea una sottoscrizione per ricevere gli eventi di Chat