Configurare l'API Google Chat

Ogni app Google Chat che crei richiede un proprio progetto Google Cloud con l'API Chat abilitata e configurata.

Per eseguire chiamate API di sola lettura con l'autenticazione utente, ad esempio per ottenere spazi ed elencare messaggi, devi solo attivare l'API e creare un client OAuth.

Per eseguire chiamate API di creazione, aggiornamento ed eliminazione o per eseguire il deployment e testare un'app di chat interattiva (creata come componente aggiuntivo di Google Workspace che estende Chat), devi anche configurare l'API Chat. Le impostazioni di configurazione dell'API Chat sono il punto in cui specifichi tutti i dettagli dell'app Chat, tra cui nome visualizzato, avatar, endpoint di deployment e funzionalità interattive.

Prerequisiti

Scegliere un nome visualizzato, un avatar e una descrizione per l'app Chat

Quando abiliti l'API Chat, configuri i dettagli della tua app Chat che vengono visualizzati dagli utenti in Chat, inclusi nome visualizzato, avatar e descrizione. Questi dettagli vengono visualizzati solo in Chat. Per pubblicare la tua app di chat su Marketplace, devi anche specificare i dettagli che vengono visualizzati nella scheda del Marketplace della tua app di chat.

Prima di configurare un'app di chat, prepara le seguenti informazioni:

Campo Descrizione Formato
Nome dell'app Il nome visualizzato dell'app Chat. Fino a 25 caratteri alfanumerici
URL avatar L'immagine visualizzata come avatar dell'app Chat. Un URL HTTPS che rimanda a un'immagine grafica quadrata (PNG o JPEG). Le dimensioni consigliate sono 256 x 256 pixel o superiori.
Descrizione Una breve descrizione dello scopo dell'app Chat. Fino a 40 caratteri alfanumerici

Il nome, l'avatar e la descrizione dell'app Chat vengono visualizzati agli utenti nell'interfaccia utente di Chat. Per alcune richieste di scrittura dell'API Chat, Chat utilizza queste informazioni per attribuire le azioni intraprese da un'app di Chat in Chat.

Ad esempio, se chiami il metodo spaces.create(), Chat include il nome dell'app Chat nella descrizione di chi ha creato lo spazio, come mostrato nell'immagine seguente:

L'app Google Chat crea uno spazio per un utente.
Figura 1. Il messaggio di attribuzione visualizzato da Chat quando viene utilizzato il metodo spaces.create() per creare uno spazio per conto di un utente.

Per interagire con le app di chat, gli utenti visualizzano o utilizzano queste informazioni anche nei seguenti modi:

  • @menziona l'app Chat per aggiungerla a uno spazio o inviarle un messaggio.
  • Trova e avvia un messaggio diretto con l'app Chat. Nel menu App, i messaggi diretti mostrano il nome e l'avatar dell'app Chat.
  • Dalla barra di scrittura, gli utenti possono sfogliare le app di chat e visualizzare il nome, l'avatar e la descrizione.

Configurare l'app Chat nella console Google Cloud

Una volta ottenuti i dettagli dell'app Chat, apri il progetto cloud e configura l'API Chat:

  1. Nella console Google Cloud, vai alla pagina dell'API Chat e fai clic sulla pagina Configurazione:

    Vai alla pagina di configurazione dell'API Chat

  2. In Informazioni sull'applicazione, compila i campi Nome app, URL avatar e Descrizione.

  3. In Funzionalità interattive, configura se la tua app di chat risponde alle interazioni degli utenti:

    Per creare un'app di chat interattiva, attiva Abilita funzionalità interattive e completa i seguenti passaggi:

    1. In Funzionalità:
      • (Facoltativo) Seleziona Home dell'app di assistenza per visualizzare una scheda della home page nella scheda Home dei messaggi diretti 1:1 con l'app Chat.
      • Seleziona Partecipa a spazi e conversazioni di gruppo per rendere la tua app Chat disponibile per l'installazione e l'utilizzo. Per impostazione predefinita, gli utenti possono installare l'app Chat e inviare messaggi in uno spazio dedicato tra l'utente e l'app Chat. Gli utenti possono anche aggiungere e interagire con l'app Chat in spazi con più persone.

    2. Nella sezione Impostazioni di connessione, seleziona l'architettura che vuoi utilizzare per ricevere oggetti evento da Chat:

      • Per utilizzare un servizio HTTP, seleziona URL dell'endpoint HTTP e fornisci un URL.
      • Per utilizzare un progetto Google Apps Script, seleziona Apps Script e fornisci un ID deployment per il progetto.
      • Per utilizzare un agente Dialogflow, seleziona Dialogflow, seleziona Dialogflow CX o Dialogflow ES e fornisci il nome della risorsa dell'agente.
      • Per utilizzare Pub/Sub, seleziona Cloud Pub/Sub e inserisci il nome dell'argomento.

    3. (Facoltativo) Per indirizzare gli oggetti evento a endpoint o funzioni specifici, vai a Impostazioni di connessione > Trigger e fornisci o aggiorna gli endpoint o le funzioni di callback per i seguenti trigger di chat:

      • Home dell'app (se l'opzione Supporta la home dell'app è attivata): un utente apre la scheda Home in un messaggio diretto 1:1 con l'app Chat.
      • Aggiunta allo spazio: un utente aggiunge l'app Chat a una conversazione di gruppo o a uno spazio oppure installa l'app Chat per i messaggi 1:1.
      • Messaggio: un utente invia un messaggio all'app Chat. Ad esempio, un utente invia un messaggio diretto all'app Chat o menziona l'app Chat in uno spazio con più persone.
      • Rimosso dallo spazio: un utente disinstalla o rimuove l'app Chat da uno spazio.
      • Comando dell'app: un utente richiama un comando rapido, un comando slash o un'azione del messaggio dall'app Chat.

    4. (Facoltativo) Aggiungi altre funzionalità interattive come prompt iniziali, comandi (comandi rapidi, comandi slash e azioni sui messaggi) o anteprime dei link.

    5. In Visibilità, specifica il tuo indirizzo email in modo da poter installare e testare l'app di chat prima di pubblicarla su Google Workspace Marketplace. Puoi specificare fino a cinque persone o uno o più gruppi Google della tua organizzazione Google Workspace.

  4. (Facoltativo) In Log, seleziona la casella di controllo Registra errori in Logging per utilizzare Google Cloud Logging. Per saperne di più, consulta Eseguire query sui log degli errori per le app di chat.

  5. Fai clic su Salva.

Dopo aver salvato la configurazione, chiunque tu abbia specificato nell'impostazione Visibilità dell'API Chat può installare, testare o utilizzare l'app Chat. Per iniziare a testare ed eseguire il debug dell'app Chat, consulta Testare le funzionalità interattive per le app Google Chat.

Considerazioni per i componenti aggiuntivi di Google Workspace esistenti

Le app di chat richiedono una configurazione diversa rispetto ai componenti aggiuntivi di Google Workspace che estendono altre applicazioni Google Workspace. Se il tuo componente aggiuntivo estende altre applicazioni Google Workspace, tieni presente i seguenti requisiti per la configurazione dell'app di Chat:

  • Sia i privati che gli amministratori di Google Workspace devono essere in grado di installare il tuo componente aggiuntivo da Marketplace. Configura queste impostazioni di installazione nell'SDK di Google Workspace Marketplace.
  • Le app di chat non utilizzano il nome e il logo che configuri per altre applicazioni Google Workspace nell'oggetto addons.common del manifest.
  • Per i componenti aggiuntivi pubblicati su Google Workspace Marketplace, non puoi salvare una bozza delle modifiche alle impostazioni di configurazione dell'API Google Chat. Dopo aver aggiornato e salvato le impostazioni di configurazione dell'API Chat, l'app di Chat aggiornata sarà immediatamente disponibile per tutti gli utenti esistenti. Per aggiornare la scheda del marketplace, puoi creare una bozza prima di inviare le modifiche.
  • Se hai creato il componente aggiuntivo utilizzando Apps Script:
  • Se hai creato il componente aggiuntivo utilizzando un servizio HTTP, ometti i dettagli di configurazione dell'app Chat nel manifest e nei deployment che crei utilizzando l'API Google Workspace Add-ons. I deployment HTTP specificati nell'SDK di Google Workspace Marketplace vengono utilizzati solo per altre applicazioni Google Workspace.

Concedere ad altre persone l'autorizzazione per configurare l'API Chat

Puoi concedere l'accesso a utenti specifici alla pagina di configurazione dell'app di chat concedendo loro il ruolo IAM (Identity and Access Management) di proprietario o visualizzatore delle app di chat di Google Cloud. Gli utenti con questi ruoli non possono accedere alla pagina di configurazione delle app di chat utilizzando la dashboard API e servizi, ma possono accedere alla pagina di configurazione accedendo alla console Google Cloud per il progetto Cloud host dell'app di chat nel seguente modo:

https://console.developers.google.com/apis/api/chat.googleapis.com/hangouts-chat?project=PROJECT_ID

dove PROJECT_ID è l'ID progetto del progetto Google Cloud che ospita l'app Chat.

App di chat che non sono componenti aggiuntivi: configura l'API Google Chat

Se gestisci un'app di Chat che non è un componente aggiuntivo di Google Workspace, la tua configurazione utilizza un singolo endpoint per tutti gli eventi di interazione anziché trigger per evento:

  1. Nella console Google Cloud, vai alla pagina Configurazione dell'API Chat:

    Vai alla pagina di configurazione dell'API Chat

  2. In Funzionalità interattive, attiva Abilita funzionalità interattive.

  3. Deseleziona Crea questa app di Chat come componente aggiuntivo di Google Workspace. Si apre una finestra di dialogo in cui ti viene chiesto di confermare. Nella finestra di dialogo, fai clic su Disattiva.

  4. Nella sezione Funzionalità, seleziona Supporta la home page dell'app o Partecipa a spazi e conversazioni di gruppo in base alle esigenze.

  5. In Impostazioni di connessione, specifica un singolo endpoint per la tua app di chat (URL dell'endpoint HTTP, ID deployment di Apps Script, nome argomento Cloud Pub/Sub o Dialogflow).

  6. Configura Comandi, Anteprime dei link, Visibilità e Log facoltativi, quindi fai clic su Salva.

Per eseguire l'upgrade di un'app di Chat che non è un componente aggiuntivo a un componente aggiuntivo di Google Workspace che estende Google Chat, consulta Convertire un'app di Google Chat in un componente aggiuntivo di Google Workspace.