Questa guida spiega come utilizzare il metodo
create()
nella risorsa Message
dell'API Google Chat per eseguire una delle seguenti operazioni:
- Inviare messaggi contenenti testo, schede e widget interattivi.
- Inviare messaggi privati a uno specifico utente di Chat.
- Avviare o rispondere a un thread di messaggi.
- Assegna un nome a un messaggio in modo da poterlo specificare in altre richieste dell'API Chat.
Le dimensioni massime del messaggio (inclusi eventuali testi o schede) sono 32.000 byte. Per inviare un messaggio che supera queste dimensioni, l'app Chat ma devono inviare più messaggi.
Oltre a chiamare l'API Chat per creare messaggi, Le app di chat possono creare e inviare messaggi per rispondere all'utente interazioni, ad esempio la pubblicazione di un messaggio di benvenuto dopo che un utente ha aggiunto Chat in uno spazio. Quando rispondono alle interazioni, le app di chat possono utilizzare altri tipi di funzionalità di messaggistica, tra cui dialoghi interattivi e interfacce di anteprima dei link. Per rispondere a un utente, L'app di chat restituisce il messaggio in modo sincrono, senza chiamata all'API Chat. Per informazioni sull'invio di messaggi a cui rispondere interazioni, consulta Ricevere e rispondere alle interazioni con l'app Google Chat.
In che modo Chat mostra e attribuisce i messaggi creati con l'API Chat
Puoi chiamare il metodo create()
utilizzando
autenticazione app
e autenticazione dell'utente.
Chat attribuisce il mittente del messaggio in modo diverso
a seconda del tipo di autenticazione utilizzato.
Quando esegui l'autenticazione come app Chat, è l'app Chat a inviare il messaggio.
Quando esegui l'autenticazione come utente, l'app Chat invia il messaggio per conto dell'utente. Chat attribuisce inoltre Chat al messaggio visualizzandone il nome.
Il tipo di autenticazione determina anche le funzionalità e le interfacce di messaggistica che puoi includere nel messaggio. Con l'autenticazione delle app, le app di chat possono inviare messaggi contenenti testo avanzato, interfacce basate su schede e widget interattivi. Poiché gli utenti di Chat possono inviare solo testo nei messaggi, puoi includere testo solo quando crei messaggi utilizzando l'autenticazione utente. Per scoprire di più sulle funzionalità di messaggistica disponibili per l'API Chat, consulta la panoramica dei messaggi di Google Chat.
Questa guida spiega come utilizzare entrambi i tipi di autenticazione per inviare un messaggio con l'API Chat.
Prerequisiti
Node.js
- Un'azienda o un'impresa Google Workspace con accesso a Google Chat.
- Configura l'ambiente:
- Creare un progetto Google Cloud.
- Configura la schermata per il consenso OAuth.
- Attiva e configura l'API Google Chat con un nome, un'icona e una descrizione per la tua app di chat.
- Installa la libreria client Cloud per Node.js.
- Crea credenziali di accesso in base a come vuoi autenticarti nell'API Google Chat
richiesta:
- Per autenticarti come utente di Chat,
crea le credenziali dell'ID client OAuth e salvale come file JSON nominato
client_secrets.json
nella tua directory locale. - Per autenticarti come app Chat,
crea le credenziali dell'account di servizio e salvale come file JSON denominato
credentials.json
.
- Per autenticarti come utente di Chat,
crea le credenziali dell'ID client OAuth e salvale come file JSON nominato
- Scegli un ambito di autorizzazione a seconda che tu voglia eseguire l'autenticazione come utente o come App Chat.
- Uno spazio di Google Chat in cui l'utente autenticato o app per le chiamate di Chat è membro. Per autenticarti come app Chat, aggiungi l'app Chat allo spazio.
Python
- Un'azienda o un'impresa Google Workspace con accesso a Google Chat.
- Configura l'ambiente:
- Crea un progetto Google Cloud.
- Configura la schermata per il consenso OAuth.
- Abilita e configura l'API Google Chat con un nome, l'icona e la descrizione dell'app Chat.
- Installa la libreria client Cloud per Python.
- Crea credenziali di accesso in base a come vuoi autenticarti nell'API Google Chat
richiesta:
- Per autenticarti come utente di Chat,
crea ID client OAuth
credenziali e salvale come file JSON denominato
client_secrets.json
alla tua directory locale. - Per autenticarti come app Chat,
crea account di servizio
credenziali e salvale come file JSON denominato
credentials.json
.
- Per autenticarti come utente di Chat,
crea ID client OAuth
credenziali e salvale come file JSON denominato
- Scegli un ambito di autorizzazione a seconda che tu voglia eseguire l'autenticazione come utente o come App Chat.
- Uno spazio di Google Chat di cui l'utente autenticato o l'app Chat di chiamata è membro. Per autenticarsi come Chat, aggiungi Chat nello spazio.
Java
- Un'azienda o un'impresa Google Workspace con accesso a Google Chat.
- Configura l'ambiente:
- Creare un progetto Google Cloud.
- Configura la schermata per il consenso OAuth.
- Abilita e configura l'API Google Chat con un nome, l'icona e la descrizione dell'app Chat.
- Installa la libreria client Cloud per Java.
- Crea le credenziali di accesso in base alla modalità di autenticazione nella richiesta dell'API Google Chat:
- Per autenticarti come utente di Chat,
crea ID client OAuth
credenziali e salvale come file JSON denominato
client_secrets.json
alla tua directory locale. - Per autenticarti come app Chat,
crea le credenziali dell'account di servizio e salvale come file JSON denominato
credentials.json
.
- Per autenticarti come utente di Chat,
crea ID client OAuth
credenziali e salvale come file JSON denominato
- Scegli un ambito di autorizzazione in base a se vuoi autenticarti come utente o come app Chat.
- Uno spazio di Google Chat di cui l'utente autenticato o l'app Chat di chiamata è membro. Per autenticarsi come Chat, aggiungi Chat nello spazio.
Apps Script
- Un'azienda o un'impresa Google Workspace con accesso a Google Chat.
- Configura l'ambiente:
- Creare un progetto Google Cloud.
- Configura la schermata per il consenso OAuth.
- Attiva e configura l'API Google Chat con un nome, un'icona e una descrizione per la tua app di chat.
- Creare un progetto Apps Script autonomo e attivare il Servizio di chat avanzato.
- In questa guida, devi utilizzare o autenticazione delle app. Per autenticarti come app Chat, crea le credenziali dell'account di servizio. Per la procedura, consulta Autenticare e autorizzare come app Google Chat.
- Scegli un ambito di autorizzazione in base a se vuoi autenticarti come utente o come app Chat.
- Uno spazio di Google Chat in cui l'utente autenticato o app per le chiamate di Chat è membro. Per autenticarsi come Chat, aggiungi Chat nello spazio.
Inviare un messaggio come app Chat
Questa sezione spiega come inviare messaggi contenenti testo, schede e widget di accessori interattivi utilizzando l'autenticazione dell'app.
Per chiamare il metodo CreateMessage()
utilizzando l'autenticazione dell'app, devi specificare i seguenti campi nella
richiesta:
- L'
chat.bot
ambito dell'autorizzazione. - La
Space
risorsa in cui vuoi pubblicare il messaggio. L'app Chat deve essere un membro dello spazio. - La risorsa
Message
da creare. Per definire i contenuti del messaggio, puoi includere RTF (text
), una o più interfacce delle schede (cardsV2
), o entrambe le cose.
Se vuoi, puoi includere quanto segue:
- Il campo
accessoryWidgets
da includere pulsanti interattivi nella parte inferiore del messaggio. - Il campo
privateMessageViewer
per inviare il messaggio privatamente a un utente specificato. - Il campo
messageId
, che ti consente assegnare un nome al messaggio da utilizzare in altre richieste API. - I campi
thread.threadKey
emessageReplyOption
da avvia o rispondi a un thread. Se lo spazio non utilizza la funzionalità di threading, questo campo viene ignorato.
Il codice seguente mostra un esempio di come un'app di chat può inviare un messaggio pubblicato come app di chat contenente testo, una scheda e un pulsante cliccabile nella parte inferiore del messaggio:
Node.js
Python
Java
Apps Script
Per eseguire questo esempio, sostituisci SPACE_NAME
con l'ID di
dello spazio
name
. Puoi ottenere l'ID chiamando il metodo
ListSpaces()
o dall'URL dello spazio.
Aggiungere widget interattivi nella parte inferiore di un messaggio
Nel primo esempio di codice di questa guida, Il messaggio dell'app di chat mostra un pulsante cliccabile nella parte inferiore del messaggio, noto come widget accessorio. I widget accessori vengono visualizzati dopo il testo o le schede di un messaggio. Puoi usare questi widget per chiedere agli utenti di interagire con il tuo messaggio in vari modi, inclusi i seguenti:
- Valutare l'accuratezza o la soddisfazione di un messaggio.
- Segnala un problema relativo al messaggio o all'app Chat.
- Aprire un link a contenuti correlati, ad esempio la documentazione.
- Rimuovere o posticipare messaggi simili dall'app Chat per un periodo di tempo specifico.
Per aggiungere widget accessori, includi i
accessoryWidgets[]
nel corpo della richiesta e specificare uno o più widget che desideri
da includere.
L'immagine seguente mostra un'app di chat che aggiunge un messaggio con widget accessori per consentire agli utenti di valutare la propria esperienza con l'app.
Di seguito è riportato il corpo della richiesta che crea un messaggio di testo con
due pulsanti accessori. Quando un utente fa clic su un pulsante, la funzione corrispondente (ad esempio doUpvote
) elabora l'interazione:
{
text: "Rate your experience with this Chat app.",
accessoryWidgets: [{ buttonList: { buttons: [{
icon: { material_icon: {
name: "thumb_up"
}},
color: { red: 0, blue: 255, green: 0 },
onClick: { action: {
function: "doUpvote"
}}
}, {
icon: { material_icon: {
name: "thumb_down"
}},
color: { red: 0, blue: 255, green: 0 },
onClick: { action: {
function: "doDownvote"
}}
}]}}]
}
Inviare un messaggio in privato
Le app di chat possono inviare messaggi privati in modo che è visibile solo a un utente specifico nello spazio. Quando L'app Chat invia un messaggio privato, il messaggio mostra un'etichetta che comunica all'utente che il messaggio è visibile solo a lui.
Per inviare un messaggio privatamente utilizzando l'API Chat, specifica la
privateMessageViewer
nel corpo della richiesta. Per specificare l'utente, imposta il valore su
il
User
risorsa che rappresenta l'utente di Chat. Puoi utilizzare anche
name
della risorsa User
, come mostrato nell'esempio seguente:
{
text: "Hello private world!",
privateMessageViewer: {
name: "users/USER_ID"
}
}
Per utilizzare questo esempio, sostituisci USER_ID
con un ID univoco per l'utente, ad esempio 12345678987654321
o
hao@cymbalgroup.com
. Per saperne di più su come specificare gli utenti, consulta
Identificare e specificare gli utenti di Google Chat.
Per inviare un messaggio in privato, devi omettere quanto segue nella richiesta:
Invia un messaggio per conto di un utente
Questa sezione spiega come inviare messaggi per conto di un utente utilizzando autenticazione degli utenti. Con l'autenticazione utente, i contenuti del messaggio possono contenere solo testo e devono omettere le funzionalità di messaggistica disponibili solo per le app di chat, incluse interfacce delle schede e widget interattivi.
Per chiamare il metodo CreateMessage()
utilizzando l'autenticazione utente, devi specificare
i seguenti campi nella richiesta:
- Un ambito di autorizzazione
che supporta l'autenticazione utente per questo metodo. L'esempio seguente utilizza
l'ambito
chat.messages.create
. - La
Space
risorsa in cui vuoi pubblicare il messaggio. L'utente autenticato deve essere membro dello spazio. - La risorsa
Message
da creare. Per definire i contenuti del messaggio, devi includere la sezionetext
.
Se vuoi, puoi includere quanto segue:
- Il campo
messageId
, che ti consente assegnare un nome al messaggio da utilizzare in altre richieste API. - I campi
thread.threadKey
emessageReplyOption
da avvia o rispondi a un thread. Se lo spazio non utilizza la funzionalità di threading, questo campo viene ignorato.
Il codice seguente mostra un esempio di come un'app Chat può inviare un messaggio in un determinato spazio per conto di un utente autenticato:
Node.js
Python
Java
Apps Script
Per eseguire questo esempio, sostituisci SPACE_NAME
con l'ID del
campo
name
dello spazio. Puoi ottenerlo chiamando il metodo
ListSpaces()
o dall'URL dello spazio.
Avviare o rispondere in un thread
Per gli spazi che utilizzano i thread, puoi specificare se un nuovo messaggio deve avviare un thread o rispondere a un thread esistente.
Per impostazione predefinita, i messaggi creati utilizzando l'API Chat avviano un nuovo thread. Per aiutarti a identificare il thread e rispondere in un secondo momento, puoi specificare una chiave del thread nella richiesta:
- Nel corpo della richiesta, specifica
thread.threadKey
. - Specifica il parametro di query
messageReplyOption
per determinare cosa succede se la chiave esiste già.
Per creare un messaggio che risponda a un thread esistente:
- Nel corpo della richiesta, includi il campo
thread
. Se impostato, puoi specificare il valorethreadKey
che hai creato. In caso contrario, devi utilizzare il pulsantename
del thread. - Specifica il parametro di query
messageReplyOption
.
Il seguente codice mostra un esempio di come un'app Chat può inviare un messaggio che avvia o risponde a un determinato thread identificato dalla chiave di un determinato spazio per conto di un utente autenticato:
Node.js
Python
Java
Apps Script
Per eseguire questo esempio, sostituisci quanto segue:
THREAD_KEY
: una chiave thread esistente nello spazio oppure, per creare un nuovo thread, un nome univoco per il thread.SPACE_NAME
: l'ID della proprietàname
. Puoi ottenerlo chiamando il metodoListSpaces()
o dall'URL dello spazio.
Assegnare un nome a un messaggio
Per recuperare o specificare un messaggio nelle chiamate API future, puoi assegnare un nome al messaggio impostando il campo messageId
nella richiesta.
Assegnando un nome al messaggio puoi specificarlo senza dover archiviare il
assegnato dal sistema dal nome della risorsa del messaggio (rappresentato nel
name
).
Ad esempio, per recuperare un messaggio utilizzando il metodo get()
, utilizza il nome della risorsa per specificare il messaggio da recuperare. Il nome della risorsa è
nel formato spaces/{space}/messages/{message}
, dove {message}
rappresenta
l'ID assegnato dal sistema o il nome personalizzato che hai impostato quando hai creato
per creare un nuovo messaggio email.
Per assegnare un nome a un messaggio, specifica un ID personalizzato nel
messageId
campo quando crei il messaggio. Il campo messageId
imposta il valore per il campo
clientAssignedMessageId
della risorsa Message
.
Puoi assegnare un nome a un messaggio solo quando lo crei. Non puoi assegnare un nome o modificare un ID personalizzato per i messaggi esistenti. L'ID personalizzato deve soddisfare i seguenti requisiti:
- Inizia con
client-
. Ad esempio,client-custom-name
è un'entità personalizzata ID, macustom-name
non lo è. - Contiene fino a 63 caratteri e solo lettere minuscole, numeri e e trattini.
- È univoco all'interno di uno spazio. Un'app di chat non può utilizzare lo stesso ID personalizzato per messaggi diversi.
Il codice seguente mostra un esempio di come un'app di Chat può inviare un messaggio con un ID in un determinato spazio per conto di un utente autenticato:
Node.js
Python
Java
Apps Script
Per eseguire questo sample, sostituisci quanto segue:
SPACE_NAME
: l'ID del camponame
dello spazio. Puoi ottenere l'ID chiamando il metodoListSpaces()
o dall'URL dello spazio.MESSAGE-ID
: un nome per il messaggio che inizia concustom-
. Deve essere univoco rispetto a qualsiasi altro nome di messaggio creato dall'app Chat nello spazio specificato.
Risoluzione dei problemi
Quando un'app Google Chat o card restituisce un errore, L'interfaccia di Chat mostra il messaggio "Si è verificato un problema". o "Impossibile elaborare la richiesta". A volte, l'UI di Chat non mostra alcun messaggio di errore, ma l'app Chat o la scheda restituisce un risultato inaspettato; Ad esempio, il messaggio di una scheda potrebbe non vengono visualizzate.
Anche se un messaggio di errore potrebbe non essere visualizzato nella UI di Chat, messaggi di errore descrittivi e dati di log che ti aiuteranno a correggere gli errori quando il logging degli errori per le app di chat è attivo. Per assistenza su come visualizzare, eseguire il debug e correggere gli errori, consulta la sezione Risolvere gli errori di Google Chat.
Argomenti correlati
- Utilizza lo strumento per la creazione di schede per progettare e visualizzare l'anteprima dei messaggi con schede JSON per le app di chat.
- Formattare i messaggi.
- Visualizzare i dettagli di un messaggio.
- Elenca i messaggi in uno spazio.
- Aggiorna un messaggio.
- Eliminare un messaggio.
- Identifica gli utenti nei messaggi di Google Chat.
- Inviare messaggi a Google Chat con i webhook in arrivo