Iscriviti agli eventi di Google Chat

In questa pagina vengono descritti gli eventi di Google Chat a cui un'app Google Chat può iscriversi utilizzando l'API Eventi di Google Workspace. Dopo aver deciso i tipi di eventi che ti servono, crea un abbonamento per iniziare a ricevere eventi da Google Chat.

Oltre a iscriverti agli eventi, puoi anche eseguire query sugli eventi chiamando l'API Chat. Chiamare l'API Chat ti consente di recuperare gli eventi su base periodica o di recuperare gli eventi che potresti aver perso da un abbonamento a causa di un'interruzione. Per scoprire di più su come ricevere e rispondere agli eventi di Chat, vedi Lavorare con gli eventi di Google Chat nella documentazione di Chat.

Risorse di destinazione di Chat supportate

L'API Google Workspace Eventi supporta gli abbonamenti a:

• Spazi, rappresentati come risorse space
• Utenti, rappresentati come risorse user dell'API Cloud Identity

Eventi di Chat supportati

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

• Messaggi nuovi, aggiornati o eliminati nello spazio.
• Le reazioni nuove o rimosse a un messaggio.
• Membri nuovi, aggiornati o rimossi nello spazio.
• Le modifiche allo spazio a cui hai effettuato l'iscrizione, ad esempio un nome o una descrizione aggiornati dello spazio.

Tipi di eventi per la creazione di sottoscrizioni

Quando crei un abbonamento, utilizza il campo eventTypes[] per specificare quali tipi di eventi 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 sugli utenti che entrano in uno spazio di Chat, devi specificare 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 partecipa a uno spazio, devi specificare 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 le sottoscrizioni agli spazi e per gli utenti. Per scoprire di più sulle eccezioni relative a ciò che attiva un evento, consulta Limitazioni.

Tipi di eventi batch (solo output)

Oltre a ricevere i tipi di eventi a cui ti abboni, la tua app Chat potrebbe anche ricevere 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 contemporaneamente 20 utenti a uno spazio, l'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 abboni, quindi non devi specificare gli eventi batch quando crei una sottoscrizione. Ad esempio, se ti abboni a nuove reazioni (google.workspace.chat.reaction.v1.created), la tua app Chat è configurata automaticamente per ricevere eventi di reazione batch (google.workspace.chat.reaction.v1.batchCreated).

La tabella seguente mostra i possibili eventi batch per una sottoscrizione:

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 per l'evento. Questo payload contiene informazioni sulla risorsa Google Workspace che è stata modificata. Ad esempio, se hai effettuato la sottoscrizione agli eventi di appartenenza in uno spazio, il payload per questi eventi contiene informazioni sulla risorsa spaces.membership che è stata modificata.

Dati delle risorse 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 sui membri in uno spazio di Chat, puoi specificare quali campi di una risorsa di appartenenza vuoi ricevere nel payload degli eventi.

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

{
    "message":
    {
        "name": "spaces/AAAABBBBBB/messages/CCCCCCCCC.DDDDDDDDD",
        "sender":
        {
            "name": "users/1234567890987654321",
            "type": "HUMAN"
        },
        "createTime": "2023-09-07T21:37:36.260127Z",
        "text": "Hello world",
        "thread":
        {
            "name": "spaces/AAAABBBBBB/threads/EEEEEEEEEEEE"
        },
        "space":
        {
            "name": "spaces/AAAABBBBBB"
        },
        "argumentText": "Hello world"
    }
}
      

{
    "message":
    {
        "name": "spaces/AAAABBBBBB/messages/CCCCCCCCC.DDDDDDDDD"
    }
}
      

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

{
    "membership":
    {
        "name": "spaces/AAAABBBBBB/members/1234567890987654321"
    }
}
      

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

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

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

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/AAAABBBBBB/members/1234567890987654321"
          }
        },
        {
          "membership": {
            "name": "spaces/AAAABBBBBB/members/98765432123456789019"
          }
        }
    ]
}
      

{
    "reaction":
    {
        "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222",
        "user":
        {
            "name": "users/1234567890987654321",
            "type": "HUMAN"
        },
        "emoji":
        {
            "unicode": "😊"
        }
    }
}
      

{
    "reaction":
    {
        "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222"
    }
}
      

{
    "reactions": [
        {
          "reaction": {
            "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222",
            "user":
            {
                "name": "users/1234567890987654321",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😊"
            }
          }
        },
        {
          "reaction": {
            "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/3333333333333333.444444444444444",
            "user":
            {
                "name": "users/98765431234564321",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😸"
            }
          }
        }
    ]
}
      

{
    "reactions": [
      {
        "reaction": {
            "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222"
        },
        "reaction": {
            "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/3333333333333333.444444444444444",
        }
      }
    ]
}
      

• Per le iscrizioni agli utenti, gli eventi relativi ai nuovi membri in messaggi diretti o chat di gruppo senza nome (google.workspace.chat.membership.v1.created) si attivano solo dopo la pubblicazione del primo messaggio.
• Le modifiche alla cronologia dello spazio non attivano gli eventi dello spazio aggiornati (tipo di evento: google.workspace.chat.spaces.v1.updated).
• Per ricevere eventi di appartenenza, l'utente deve essere un membro diretto dello spazio. Se un utente è stato aggiunto, aggiornato o rimosso indirettamente in uno spazio tramite un gruppo Google, l'abbonamento non riceve questi eventi di appartenenza. Per informazioni su come funzionano le iscrizioni ai gruppi Google, vedi Aggiungere un gruppo Google a uno spazio.

Argomenti correlati

• Struttura degli eventi di Google Workspace
• Scegliere gli ambiti OAuth
• Crea un abbonamento per ricevere eventi di Chat