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 quali tipi di eventi ti servono, 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. Chiamare l'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 Utilizzare 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.
  • Nuove reazioni o reazioni rimosse a un messaggio.
  • Membri nuovi, aggiornati o rimossi nello spazio.
  • Modifiche allo spazio a cui hai eseguito l'iscrizione, ad esempio un nome o una descrizione aggiornati.
  • Modifiche alla disponibilità dell'utente.
  • Modifiche a spaceReadState o threadReadState dell'utente.

Risorse che puoi monitorare per gli eventi

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

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

Risorsa di destinazione Formato Limitazioni
Spazio

//chat.googleapis.com/spaces/SPACE

dove SPACE è l'ID nel nome risorsa della risorsa space dell'API Chat. Puoi ottenere l'ID dall'URL dello spazio o utilizzando il metodo spaces.list().

 L'utente di Chat o l'app di Chat che autorizza l'iscrizione deve essere membro dello spazio tramite il proprio account Google Workspace o Google. Supporta:
Tutti gli spazi di un utente

//chat.googleapis.com/spaces/-

 L'abbonamento riceve solo eventi per gli spazi in cui l'utente è membro tramite il proprio account Google Workspace o Google. Supporta solo l'autenticazione utente.
Utente

//cloudidentity.googleapis.com/users/USER

dove USER è l'ID nel nome risorsa della risorsa user dell'API Chat. Per maggiori dettagli, vedi Identificare e specificare gli utenti di Google Chat.

L'abbonamento riceve solo eventi relativi all'utente che ha autorizzato l'abbonamento. Un utente non può autorizzare un abbonamento per conto di altri utenti. Supporta solo l'autenticazione utente.
Cliente ( Anteprima per gli sviluppatori)

//admin.googleapis.com/customers/CUSTOMER

dove CUSTOMER è l'ID cliente. Puoi anche utilizzare l'alias my_customer per il dominio cliente dell'app Chat.

L'abbonamento riceve eventi per tutti gli spazi e gli utenti gestiti dal dominio del cliente. Supporta solo l'autenticazione delle app con l'approvazione dell'amministratore.

Tipi di eventi per la creazione di abbonamenti

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

Ad esempio, per ricevere eventi sugli 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 a un determinato utente che entra 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ù su come funzionano gli 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 informazioni sulle eccezioni relative a cosa attiva un evento, consulta Limitazioni.

Tipo di evento Formato Dati delle risorse
Iscrizioni agli spazi  
Viene pubblicato un messaggio.

google.workspace.chat.message.v1.created

space.message
Un messaggio viene aggiornato.

google.workspace.chat.message.v1.updated

space.message
Un messaggio viene eliminato.

google.workspace.chat.message.v1.deleted

space.message
Viene creata una reazione.

google.workspace.chat.reaction.v1.created

space.message.reaction
Una reazione viene eliminata.

google.workspace.chat.reaction.v1.deleted

space.message.reaction
Un membro viene aggiunto allo spazio.

google.workspace.chat.membership.v1.created

space.membership
Un membro viene aggiornato nello spazio.

google.workspace.chat.membership.v1.updated

space.membership
Un membro viene rimosso dallo spazio.

google.workspace.chat.membership.v1.deleted

space.membership
Lo spazio viene aggiornato.

google.workspace.chat.space.v1.updated

space
Lo spazio viene eliminato.

google.workspace.chat.space.v1.deleted

space
Abbonamenti agli utenti  
L'utente diventa membro di uno spazio.

Non tutti i nuovi membri attivano eventi. Per i dettagli, vedi Limitazioni.

google.workspace.chat.membership.v1.created

space.membership
L'iscrizione dell'utente a uno spazio viene aggiornata.

google.workspace.chat.membership.v1.updated

space.membership
L'utente viene rimosso come membro diretto di uno spazio.

google.workspace.chat.membership.v1.deleted

space.membership
Lo stato di lettura dello spazio dell'utente viene aggiornato.

google.workspace.chat.spaceReadState.v1.updated

spaceReadState
Lo stato di lettura del thread dell'utente viene aggiornato.

google.workspace.chat.threadReadState.v1.updated

threadReadState
Abbonamenti per i clienti ( Anteprima per gli sviluppatori)  
Si verifica un evento per qualsiasi spazio, messaggio, reazione, iscrizione o stato di lettura dell'utente all'interno della tua organizzazione Google Workspace.

Supporta tutti i tipi di eventi elencati per gli spazi e gli abbonamenti degli utenti.

Dipende dal tipo di evento (ad esempio, space, space.message, space.membership o spaceReadState).

Tipi di eventi batch (solo output)

Oltre a ricevere i tipi di eventi a cui ti iscrivi, la tua app di chat potrebbe ricevere anche eventi 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 qualsiasi tipo di evento a cui ti iscrivi, quindi non devi specificare gli eventi batch quando crei un abbonamento. Ad esempio, se ti iscrivi a nuove reazioni (google.workspace.chat.reaction.v1.created), la tua app Chat viene configurata automaticamente per ricevere eventi di reazione batch (google.workspace.chat.reaction.v1.batchCreated).

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

Tipo di evento batch Formato
Vengono pubblicati più messaggi.

google.workspace.chat.message.v1.batchCreated
Sono stati aggiornati più messaggi.

google.workspace.chat.message.v1.batchUpdated
Vengono eliminati più messaggi.

google.workspace.chat.message.v1.batchDeleted
Vengono create più reazioni.

google.workspace.chat.reaction.v1.batchCreated
Vengono eliminate più reazioni.

google.workspace.chat.reaction.v1.batchDeleted
Più membri vengono aggiunti allo spazio a cui è stato eseguito l'abbonamento oppure l'utente abbonato è stato aggiunto a più spazi.

google.workspace.chat.membership.v1.batchCreated
Più abbonamenti vengono aggiornati nello spazio a cui è stato effettuato l'abbonamento o per l'utente abbonato.

google.workspace.chat.membership.v1.batchUpdated
Più membri vengono rimossi dallo spazio a cui è stato effettuato l'abbonamento oppure l'utente abbonato è stato rimosso da più spazi.

google.workspace.chat.membership.v1.batchDeleted
Lo spazio ha più aggiornamenti.

google.workspace.chat.space.v1.batchUpdated
Vengono aggiornati più stati di lettura dello spazio per l'utente iscritto.

google.workspace.chat.spaceReadState.v1.batchUpdated
Vengono aggiornati più stati di lettura dei thread per l'utente iscritto.

google.workspace.chat.threadReadState.v1.batchUpdated

Dati sugli eventi

Questa sezione descrive i dati degli 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 modificata. Ad esempio, se hai sottoscritto gli eventi di abbonamento in uno spazio, il payload di questi eventi contiene informazioni sulla risorsa spaces.membership che è stata modificata.

Dati delle risorse nel payload dell'evento

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

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

Esempio Tipo di evento Payload JSON

Un utente pubblica un messaggio nello spazio che dice "Hello world".

google.workspace.chat.message.v1.created

Include i dati delle risorse:

{
    "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"
    }
}

Esclude i dati delle risorse:

{
    "message":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID"
    }
}
Un utente diventa gestore dello spazio.

google.workspace.chat.membership.v1.updated

Include i dati delle risorse:

{
    "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"
    }
}

Esclude i dati delle risorse:

{
    "membership":
    {
        "name": "spaces/SPACE_ID/members/MEMBER_ID"
    }
}
Un utente aggiorna la descrizione dello spazio in "Team di vendita di Cymbal Labs". google.workspace.chat.space.v1.updated

Include i dati delle risorse:

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

Esclude i dati delle risorse:

{
    "space":
    {
        "name": "spaces/SPACE_ID"
    }
}
Due utenti di Chat sono stati aggiunti allo spazio contemporaneamente. google.workspace.chat.membership.v1.batchCreated

Include i dati delle risorse:

{
    "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"
          }
        }
    ]
}

Esclude i dati delle risorse:

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        },
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        }
    ]
}
Un utente reagisce a un messaggio con l'emoji 😊. google.workspace.chat.reaction.v1.created

Include i dati delle risorse:

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

Esclude i dati delle risorse:

{
    "reaction":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
    }
}
Gli utenti reagiscono a un messaggio con le emoji 😊 e 😸. google.workspace.chat.reaction.v1.batchCreated

Include i dati delle risorse:

{
    "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": "😸"
            }
          }
        }
    ]
}

Esclude i dati delle risorse:

{
    "reactions": [
      {
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
        },
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
        }
      }
    ]
}
Un utente visita uno spazio non letto, che aggiorna lo stato di lettura dello spazio. google.workspace.chat.spaceReadState.v1.updated

Include i dati delle risorse:

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

Esclude i dati delle risorse:

{
  "spaceReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/spaceReadState"
  }
}
Un utente legge un messaggio in un thread, che aggiorna lo stato di lettura del thread. google.workspace.chat.threadReadState.v1.updated

Include i dati delle risorse:

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

Esclude i dati delle risorse:

{
  "threadReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/threads/THREAD_ID/threadReadState"
  }
}
Un utente diventa disponibile in Chat. google.workspace.chat.availability.v1.updated

Include i dati delle risorse:

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

Esclude i dati delle risorse:

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
Un utente diventa inattivo in Chat. google.workspace.chat.availability.v1.updated

Include i dati delle risorse:

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

Esclude i dati delle risorse:

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
Un utente imposta la propria disponibilità su Away in Chat. google.workspace.chat.availability.v1.updated

Include i dati delle risorse:

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

Esclude i dati delle risorse:

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
Un utente imposta la propria disponibilità su Do not disturb in Chat. google.workspace.chat.availability.v1.updated

Include i dati delle risorse:

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

Esclude i dati delle risorse:

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
Un utente imposta uno stato personalizzato su Chat. google.workspace.chat.availability.v1.updated

Include i dati delle risorse:

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

Esclude i dati delle risorse:

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

Limitazioni e comportamenti di pubblicazione

Limitazioni generali

  • Per ricevere eventi di appartenenza, l'utente o l'app 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 ai gruppi Google, consulta la pagina Aggiungere 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 ( anteprima per gli sviluppatori)

Per gli abbonamenti dei clienti si applicano le seguenti limitazioni:

  • L'organizzazione Google Workspace deve disporre di almeno una licenza SKU Enterprise. Tieni presente che questo requisito non è applicato rigorosamente durante la fase del Programma Anteprima per gli sviluppatori, ma verrà applicato in futuro (l'annuncio verrà pubblicato separatamente).
  • 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 cliente in totale (creati da diverse app di chat).

Per gli abbonamenti dei clienti, la pubblicazione degli eventi segue queste regole generali:

  • Eventi dello spazio: 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 da spazi gestiti dalla tua organizzazione sia da spazi gestiti da organizzazioni esterne, ma la modalità di ricezione dipende dall'organizzazione che gestisce lo spazio:

Spazi gestiti dalla tua organizzazione Google Workspace

Se si verifica una modifica dell'abbonamento 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 personale esterno 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}