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 recuperare 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 consentono di specificare tutti i dettagli dell'app di Chat, tra cui il nome visualizzato, l'avatar, gli endpoint di deployment e le funzionalità interattive.

Prerequisiti

• Un account Google Workspace Business o Enterprise con accesso a Google Chat.
• Crea un progetto Google Cloud.
• Configura la schermata per il consenso OAuth.
• Abilita l'API Google Chat.

Scegli un nome visualizzato, un avatar e una descrizione per la tua app di Chat

Quando attivi l'API Chat, configuri i dettagli dell'app Chat che vengono visualizzati dagli utenti in Chat, tra cui un nome visualizzato, un avatar e una descrizione. Questi dettagli vengono visualizzati solo in Chat. Per pubblicare l'app di Chat su Marketplace, devi anche specificare i dettagli che vengono visualizzati nella scheda di Marketplace dell'app di Chat.

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

Il nome, l'avatar e la descrizione dell'app Chat vengono visualizzati dagli utenti nella UI di Chat. Per alcune richieste di scrittura dell'API Chat, Chat utilizza queste informazioni per attribuire le azioni eseguite 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:

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

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

Configura l'app Chat nella console Google Cloud

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

1. Nella console Google Cloud, vai alla pagina 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. (Facoltativo) Dal menu Sintassi di markup, seleziona la sintassi di markup predefinita (Markdown o Chat) per i messaggi dell'app di Chat. Per scoprire di più sulla formattazione del testo e su come Chat determina la sintassi di markup per le richieste API, consulta Formattare i messaggi.

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

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

   1. In Funzionalità:
      • (Facoltativo) Seleziona Supporta la home dell'app 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 di Chat disponibile per l'installazione e l'utilizzo. Per impostazione predefinita, gli utenti possono installare l'app Chat e scambiare messaggi con l'app Chat in uno spazio dedicato tra l'utente e l'app Chat. Gli utenti possono anche aggiungere l'app Chat e interagire con l'app Chat negli spazi con più persone.

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

      • Per utilizzare un servizio HTTP, seleziona URL 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 è attiva): un utente apre la scheda Home in un messaggio diretto 1:1 con l'app Chat.
      • Aggiunta allo spazio: un utente aggiunge l'app di Chat a una conversazione di gruppo o a uno spazio oppure installa l'app di 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.
      • Removed from space (Rimosso dallo spazio): un utente disinstalla o rimuove l'app di Chat da uno spazio.
      • Comando dell'app: un utente richiama un comando rapido, un comando slash o un'azione di 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.

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

6. 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 Testa le funzionalità interattive per le app Google Chat.

Configura l'app di Chat utilizzando l'API Google Workspace Add-ons

Anziché configurare manualmente l'app di Chat nella console Google Cloud, puoi utilizzare il tuo progetto cloud Google Cloud registrato al programma Anteprima per gli sviluppatori di Google Workspace per leggere e aggiornare in modo programmatico la configurazione di un'app di Chat creata come componente aggiuntivo di Google Workspace utilizzando la risorsa chatAppConfig nell'Google Workspace add-ons API.

chatAppConfig è una risorsa singleton che esiste sempre per ogni progetto Cloud. Prima di salvare una configurazione per la prima volta, la risorsa contiene una configurazione vuota (che è anche ciò che GetChatAppConfig restituisce se leggi la risorsa prima del primo salvataggio). Poiché la risorsa esiste già, non è necessario crearla separatamente. Utilizza UpdateChatAppConfig sia per salvare la configurazione iniziale sia per aggiornare una configurazione esistente.

Prerequisiti e autenticazione

Prima di chiamare GetChatAppConfig o UpdateChatAppConfig, completa i seguenti prerequisiti:

1. Registra il tuo progetto Google Cloud nel programma Anteprima per gli sviluppatori di Google Workspace.
2. Abilita l'API Google Workspace Add-ons (gsuiteaddons.googleapis.com) nel tuo progetto Cloud. Facoltativamente, puoi attivare l'API Google Chat (chat.googleapis.com) se vuoi visualizzare o aggiornare la configurazione dell'app Chat nella console Google Cloud o chiamare l'API Chat.
3. Esegui l'autenticazione come utente umano con una credenziale OAuth 2.0 che include l'ambito https://www.googleapis.com/auth/cloud-platform. L'autenticazione del service account non è supportata per i metodi chatAppConfig.
4. Assicurati che l'utente autenticato disponga delle autorizzazioni Identity and Access Management (IAM) richieste per il progetto Cloud di destinazione:
   • gsuiteaddons.chatAppConfigs.get e chat.bots.get per leggere la configurazione (GetChatAppConfig).
   • gsuiteaddons.chatAppConfigs.update e chat.bots.update per aggiornare la configurazione (UpdateChatAppConfig).
5. Se utilizzi una libreria client, scarica la libreria client Anteprima per gli sviluppatori con il tuo account Anteprima per gli sviluppatori registrato.

Aggiorna la configurazione di un'app di Chat

Per configurare un'app di Chat per la prima volta o aggiornare una configurazione esistente, invia una richiesta PATCH (UpdateChatAppConfig) alla risorsa singleton chatAppConfig per il tuo progetto Cloud:

• Per il salvataggio iniziale di un progetto cloud con un chatAppConfig vuoto, sono obbligatori displayName (da 3 a 25 caratteri) e description (da 1 a 40 caratteri). Se ometti interactiveFeatureConfig al momento del salvataggio iniziale, l'app di Chat viene configurata come non interattiva.
• Per gli aggiornamenti successivi, utilizza il parametro di query facoltativo updateMask per specificare i campi separati da virgole da aggiornare (oppure ometti updateMask per aggiornare tutti i campi forniti). L'aggiornamento di un campo ripetuto (appCommands, urlPatterns o allowlistedTestingPrincipals) sostituisce l'intero elenco.

PATCH https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?updateMask=displayName,description,avatarUri,state,errorLoggingEnabled,markupSyntax,interactiveFeatureConfig
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "name": "projects/PROJECT_NUMBER/chatAppConfig",
  "displayName": "Cymbal Assistant",
  "description": "Helps manage tasks and schedules",
  "avatarUri": "https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png",
  "state": "ACTIVE",
  "errorLoggingEnabled": true,
  "markupSyntax": "MARKUP_SYNTAX_MARKDOWN",
  "interactiveFeatureConfig": {
    "supportsMultiuserSpaces": false,
    "connectionConfig": {
      "httpEndpointConfig": {
        "commonUrl": "https://example.com/chat"
      }
    },
    "appCommands": [
      {
        "commandType": "SLASH_COMMAND",
        "commandId": 1,
        "command": "/help",
        "description": "Show available commands",
        "dialogEnabled": false
      }
    ],
    "urlPatterns": [
      {
        "hostPattern": "example.com",
        "pathPrefix": "tasks/"
      }
    ],
    "allowlistedTestingPrincipals": [
      "USER_EMAIL"
    ]
  }
}

Sostituisci quanto segue nell'URL, nell'intestazione e nel corpo della richiesta:

• PROJECT_NUMBER: il numero di progetto numerico del progetto cloud che ospita la tua app di Chat.
• ACCESS_TOKEN: un token di accesso OAuth 2.0 dell'utente autorizzato con l'ambito https://www.googleapis.com/auth/cloud-platform.
• USER_EMAIL: un indirizzo email o un gruppo Google della tua organizzazione Google Workspace da inserire nella lista consentita per testare l'app di Chat (ad esempio, il tuo indirizzo email).
• I campi di configurazione di esempio nel corpo della richiesta (come displayName, description, avatarUri e interactiveFeatureConfig, inclusi la configurazione dell'endpoint, i comandi, i pattern URL di anteprima dei link e le entità di test) con i valori per la tua app Chat. Per informazioni dettagliate su tutti i campi e le opzioni degli endpoint supportati, consulta il riferimento REST projects.chatAppConfig e projects.chatAppConfig.patch.

Recupera la configurazione di un'app di Chat

Per leggere la configurazione attuale dell'app di Chat per un progetto Cloud, chiama GetChatAppConfig. Puoi passare il parametro di query facoltativo view (ChatAppConfigView):

• BASIC (predefinito): restituisce i metadati di base senza interactiveFeatureConfig.
• FULL: restituisce tutti i campi di configurazione, incluso interactiveFeatureConfig.

Se la configurazione dell'app di Chat non è ancora stata salvata per il progetto Cloud, il metodo restituisce un oggetto ChatAppConfig vuoto.

GET https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?view=FULL
Authorization: Bearer ACCESS_TOKEN

const {GSuiteAddOnsClient} = require('@google-cloud/gsuiteaddons').v1;

const client = new GSuiteAddOnsClient();

async function getChatAppConfig() {
  const [response] = await client.getChatAppConfig({
    name: 'projects/PROJECT_NUMBER/chatAppConfig',
    view: 'FULL',
  });
  console.log(JSON.stringify(response, null, 2));
}

getChatAppConfig();

from google.cloud import gsuiteaddons_v1

client = gsuiteaddons_v1.GSuiteAddOnsClient()

request = gsuiteaddons_v1.GetChatAppConfigRequest(
    name="projects/PROJECT_NUMBER/chatAppConfig",
    view=gsuiteaddons_v1.GetChatAppConfigRequest.ChatAppConfigView.FULL,
)
response = client.get_chat_app_config(request=request)
print(response)

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 dal Marketplace. Puoi configurare queste impostazioni di installazione nell'SDK 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 è immediatamente disponibile per tutti gli utenti esistenti. Per aggiornare la tua scheda del Marketplace, puoi creare una bozza prima di inviare eventuali modifiche.
• Se hai creato il componente aggiuntivo utilizzando Apps Script:
  • Devi utilizzare lo stesso ID deployment di Apps Script che utilizzi per il resto della configurazione del componente aggiuntivo.
  • Non puoi utilizzare l'editor di Apps Script per installare i deployment di test in Chat. Devi invece installarle direttamente dalla UI di Chat.
• Se hai creato il componente aggiuntivo utilizzando un servizio HTTP, ometti i dettagli di configurazione dell'app di Chat nel manifest projects.deployments 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. Configura invece l'app di Chat nella console Google Cloud o utilizzando la risorsa chatAppConfig nell'API dei componenti aggiuntivi di Google Workspace.

Concedi 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 assegnando loro il ruolo Google Cloud Identity Access Management (IAM) Chat apps Owner o Chat apps Viewer. 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 andando alla console Google Cloud per il progetto cloud host dell'app di Chat come segue:

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

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

Argomenti correlati

• Scegli un'architettura per l'app di Chat
• Ricevere e rispondere alle interazioni degli utenti
• Testa le funzionalità interattive per le app Google Chat