Collegare un'app di chat ad altri servizi e strumenti

In questa pagina viene descritto come collegare un'app Google Chat a un servizio o uno strumento esterno a Google Chat. Sebbene le app di chat siano molto potenti da sole, spesso funzionano insieme ad altri sistemi e richiedono applicazioni companion per collegare gli account, autorizzare l'accesso ai dati, visualizzare dati aggiuntivi o configurare le preferenze dell'utente.

Richiedere la configurazione dell'app di chat a un utente

Se il completamento di una richiesta richiede una configurazione aggiuntiva che non può essere completata direttamente nell'app Chat, restituisci un URL di configurazione all'utente come parte di una normale risposta o presentalo in privato nel seguente modulo:

{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "CONFIGURATION_URL"
  }
}

In questo modo, Google Chat mostrerà all'utente un prompt privato in cui CONFIGURATION_URL è un link che l'utente può visitare per ulteriori autenticazione, autorizzazione o configurazione. Una risposta REQUEST_CONFIG si esclude a vicenda con un messaggio di risposta regolare. Eventuali testi, schede o altri attributi vengono ignorati.

Completa la richiesta di configurazione

Ogni evento di interazione con MESSAGE ricevuto dall'app Chat include anche un parametro configCompleteRedirectUrl. Questo URL deve essere codificato nell'URL di configurazione per essere utilizzato al termine del processo. Il reindirizzamento a questo URL segnala a Google Chat che la richiesta di configurazione è stata soddisfatta.

Quando l'app Chat viene avviata, il flusso dipende dal messaggio specifico ricevuto. In risposta a un messaggio come @app help, un'app Chat deve rispondere con un messaggio senza richiedere una configurazione aggiuntiva.

Quando un utente viene reindirizzato correttamente al configCompleteRedirectUrl fornito nel messaggio originale, Google Chat esegue questi passaggi:

  1. Cancella il prompt visualizzato all'utente che ha avviato l'operazione.
  2. Converti il messaggio originale in pubblico, rendendolo visibile agli altri membri dello spazio.
  3. Inviare una seconda volta il messaggio originale alla stessa app di Chat.

La visita a un configCompleteRedirectUrl interessa un solo messaggio dell'utente. Se un utente ha tentato di inviare messaggi a un'app di Chat più volte e, di conseguenza, ha ricevuto più prompt, il clic su una determinata richiesta e il completamento del processo di autenticazione e configurazione interessa solo quel determinato messaggio. Gli altri messaggi non vengono modificati.

Quando un evento di interazione MESSAGE viene inviato di nuovo in questo modo, dovrebbe essere identico all'evento originale. Tuttavia, esistono alcune situazioni in cui gli eventi di interazione MESSAGE possono differire. Ad esempio, quando un messaggio menziona sia l'app di Chat A che l'app di Chat B, l'utente può modificare il messaggio se l'app di Chat A risponde con un messaggio normale prima di eseguire l'autenticazione con l'app Chat B. In questo caso, l'app Chat B riceve il testo del messaggio modificato dopo che l'utente completa l'autenticazione e la configurazione.

Autentica l'utente di Chat al di fuori di Chat

In alcuni casi, ad esempio per richiedere l'autorizzazione OAuth per un'API, l'app deve collegarsi a un URL esterno a Chat mantenendo l'identità dell'utente. Il modo migliore per identificare l'utente in questi casi è proteggere l'app di destinazione con Accedi con Google.

Utilizza il token di identità emesso durante l'accesso per ottenere l'ID utente. L'attestazione sub contiene l'ID univoco dell'utente e può essere correlata all'ID utente di Google Chat.

Anche se i due ID non sono esattamente identici, possono essere forzati. Per forzare il valore della rivendicazione sub a un users/{user} di Google Chat, anteponi users/ al valore. Ad esempio, il valore dell'attestazione 123 equivale al nome utente users/123 nei messaggi dell'app Chat.