Questa pagina descrive come configurare un webhook per inviare messaggi asincroni in uno spazio Chat utilizzando attivatori esterni. Ad esempio, puoi configurare un'applicazione di monitoraggio per avvisare il personale sempre disponibile su Chat quando un server smette di funzionare. Per inviare un messaggio sincrono con un'app di chat, consulta Inviare un messaggio.
Con questo tipo di progettazione dell'architettura, gli utenti non possono interagire con il webhook o con l'applicazione esterna collegata perché la comunicazione è unidirezionale. I webhook non sono conversazionali. Non possono rispondere o ricevere messaggi dagli utenti o eventi di interazione con l'app Chat. Per rispondere ai messaggi, crea un'app di Chat anziché un webhook.
Sebbene un webhook non sia tecnicamente un'app di Chat, i webhook connettono le applicazioni utilizzando richieste HTTP standard, in questa pagina viene chiamata app di Chat per semplificare la gestione. Ogni webhook funziona solo nello spazio di Chat in cui è registrato. I webhook in arrivo funzionano nei messaggi diretti, ma solo quando tutti gli utenti hanno abilitato le app di chat. Non puoi pubblicare webhook su Google Workspace Marketplace.
Il seguente diagramma mostra l'architettura di un webhook connesso a Chat:
Nel diagramma precedente, un'app di Chat include il seguente flusso di informazioni:
- La logica dell'app Chat riceve informazioni da servizi di terze parti esterni, come un sistema di gestione dei progetti o uno strumento per la gestione dei ticket.
- La logica dell'app Chat è ospitata in un sistema cloud o on-premise che può inviare messaggi utilizzando un URL webhook a uno spazio di Chat specifico.
- Gli utenti possono ricevere messaggi dall'app Chat in quel determinato spazio Chat, ma non sono in grado di interagire con l'app.
Prerequisiti
Python
- Un account Google Workspace Business o Enterprise con accesso a Google Chat. La tua organizzazione Google Workspace deve consentire agli utenti di aggiungere e utilizzare i webhook in arrivo.
- Python 3.6 o versioni successive
- Lo strumento di gestione dei pacchetti pip
La libreria
httplib2
. Per installare la libreria, esegui questo comando nell'interfaccia a riga di comando:pip install httplib2
Uno spazio di Google Chat. Per crearne uno utilizzando l'API Google Chat, consulta Creare uno spazio. Per crearne uno in Chat, consulta la documentazione del Centro assistenza.
Node.js
- Un account Google Workspace Business o Enterprise con accesso a Google Chat. La tua organizzazione Google Workspace deve consentire agli utenti di aggiungere e utilizzare i webhook in arrivo.
- Node.js 14 o versioni successive
- Lo strumento di gestione dei pacchetti npm
- Uno spazio di Google Chat. Per crearne uno utilizzando l'API Google Chat, vedi Creare uno spazio. Per crearne uno in Chat, consulta la documentazione del Centro assistenza.
Java
- Un account Google Workspace Business o Enterprise con accesso a Google Chat. La tua organizzazione Google Workspace deve consentire agli utenti di aggiungere e utilizzare i webhook in arrivo.
- Java 11 o versioni successive
- Lo strumento di gestione dei pacchetti Maven
- Uno spazio di Google Chat. Per crearne uno utilizzando l'API Google Chat, vedi Creare uno spazio. Per crearne uno in Chat, consulta la documentazione del Centro assistenza.
Apps Script
- Un account Google Workspace Business o Enterprise con accesso a Google Chat. La tua organizzazione Google Workspace deve consentire agli utenti di aggiungere e utilizzare i webhook in arrivo.
- Crea un progetto Apps Script autonomo e attiva il servizio Chat avanzato.
- Uno spazio di Google Chat. Per crearne uno utilizzando l'API Google Chat, vedi Creare uno spazio. Per crearne uno in Chat, consulta la documentazione del Centro assistenza.
Creare un webhook
Per creare un webhook, registralo nello spazio di Chat in cui vuoi ricevere i messaggi, quindi scrivi uno script che li invii.
Registra il webhook in arrivo
- Apri Chat in un browser. Gli webhook non sono configurabili dall'app mobile Chat.
- Vai allo spazio in cui vuoi aggiungere un webhook.
- Accanto al titolo dello spazio, fai clic sulla freccia per espandere Altro e poi su App e integrazioni.
Fai clic su
Aggiungi webhook.Nel campo Nome, inserisci
Quickstart Webhook
.Nel campo URL avatar, inserisci
https://developers.google.com/chat/images/chat-product-icon.png
.Fai clic su Salva.
Per copiare l'URL webhook, fai clic su
Altro, quindi su Copia link.
Scrivi lo script del webhook
Lo script webhook di esempio invia un messaggio allo spazio in cui è registrato il webhook
inviando una richiesta POST
all'URL webhook. L'API
Chat risponde con un'istanza di
Message
.
Seleziona una lingua per scoprire come creare uno script webhook:
Python
Nella directory di lavoro, crea un file denominato
quickstart.py
.In
quickstart.py
, incolla il seguente codice:Sostituisci il valore della variabile
url
con l'URL webhook che hai copiato durante la registrazione del webhook.
Node.js
Nella directory di lavoro, crea un file denominato
index.js
.In
index.js
, incolla il seguente codice:Sostituisci il valore della variabile
url
con l'URL del webhook che hai copiato quando hai registrato il webhook.
Java
Nella directory di lavoro, crea un file denominato
pom.xml
.In
pom.xml
, copia e incolla quanto segue:Nella tua directory di lavoro, crea la seguente struttura di directory
src/main/java
.Nella directory
src/main/java
, crea un file denominatoApp.java
.Incolla il codice seguente in
App.java
:Sostituisci il valore della variabile
URL
con l'URL webhook che hai copiato durante la registrazione del webhook.
Apps Script
In un browser, vai ad Apps Script.
Fai clic su Nuovo progetto.
Incolla il seguente codice:
Sostituisci il valore della variabile
url
con l'URL webhook che hai copiato durante la registrazione del webhook.
Esegui lo script webhook
In un'interfaccia a riga di comando, esegui lo script:
Python
python3 quickstart.py
Node.js
node index.js
Java
mvn compile exec:java -Dexec.mainClass=App
Apps Script
- Fai clic su Esegui.
Quando esegui il codice, l'webhook invia un messaggio allo spazio in cui lo hai registrato.
Avviare o rispondere a un thread di messaggi
Specifica
spaces.messages.thread.threadKey
nel corpo della richiesta di messaggio. A seconda che tu stia iniziando o rispondendo a un thread, utilizza i seguenti valori perthreadKey
:Se avvii un thread, imposta
threadKey
su una stringa arbitraria, ma Annota questo valore per pubblicare una risposta al thread.Se rispondi a un thread, specifica il valore
threadKey
impostato al momento dell'avvio del thread. Ad esempio, per pubblicare una risposta al thread in cui il messaggio iniziale ha utilizzatoMY-THREAD
, impostaMY-THREAD
.
Definisci il comportamento del thread se non viene trovato il valore
threadKey
specificato:Rispondi a un thread o avvia un nuovo thread. Aggiungi il parametro
messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD
all'URL webhook. Se passi questo parametro URL, Chat cerca un thread esistente utilizzando il valorethreadKey
specificato. Se viene trovato, il messaggio viene pubblicato come risposta al thread. Se non viene trovato alcun messaggio, il messaggio avvia un nuovo thread corrispondente a quelthreadKey
.Rispondi a un thread o non fare nulla. Aggiungi il parametro
messageReplyOption=REPLY_MESSAGE_OR_FAIL
all'URL webhook. Se passi questo parametro URL, Chat cerca un thread esistente utilizzando il valorethreadKey
specificato. Se ne viene trovata una, il messaggio viene pubblicato come risposta al thread. Se non viene trovato nessuno, il messaggio non viene inviato.
Per scoprire di più, visita la pagina
messageReplyOption
.
Il seguente esempio di codice avvia o risponde a un thread di messaggi:
Python
Node.js
Apps Script
Gestire gli errori
Le richieste webhook possono non riuscire per diversi motivi, tra cui:
- Richiesta non valida.
- Il webhook o lo spazio che ospita il webhook è stato eliminato.
- Problemi intermittenti come connettività di rete o limiti di quota.
Quando crei il webhook, devi gestire in modo appropriato gli errori:
- Registrazione dell'errore.
- Per errori basati sul tempo, sulla quota o sulla connettività di rete, riprova a inviare la richiesta con backoff esponenziale.
- Non fare nulla, che è appropriato se l'invio del messaggio webhook non è importante.
L'API Google Chat restituisce gli errori come google.rpc.Status
, che include un errore HTTP code
che indica il tipo di errore riscontrato: un errore del client (serie 400) o un errore del server (serie 500). Per esaminare tutte le mappature HTTP, consulta google.rpc.Code
.
{
"code": 503,
"message": "The service is currently unavailable.",
"status": "UNAVAILABLE"
}
Per scoprire come interpretare i codici di stato HTTP e gestire gli errori, consulta Errori.
Limitazioni e considerazioni
- Quando crei un messaggio con un webhook nell'API Google Chat, la risposta non contiene il messaggio completo.
La risposta compila solo i campi
name
ethread.name
.
Argomenti correlati
- Scegliere un'architettura dell'app di Chat
- Inviare messaggi relativi alle schede
- Formattare i messaggi