Questa guida spiega come chiamare l'API Google Chat
messages.create()
per eseguire una delle seguenti operazioni:
- Inviare messaggi che contengono 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 per poterlo specificare in un'altra API Chat richieste.
Oltre a chiamare il metodo messages.create()
, le app di Chat
possono creare e inviare messaggi per rispondere alle interazioni degli utenti, ad esempio la pubblicazione di un
messaggio di benvenuto visualizzato dopo che un utente ha aggiunto l'app Chat a un
spazio. Quando rispondono alle interazioni, le app di chat possono usare
Tipi di funzionalità di messaggistica, incluse finestre di dialogo interattive e anteprima dei link
interfacce. Per rispondere a un utente, l'app Chat restituisce
il messaggio in modo sincrono, senza chiamare l'API Chat. Per ulteriori informazioni
sull'invio di messaggi per rispondere alle interazioni, vedi
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 messages.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 invia il messaggio.
App
accanto al nome.Quando esegui l'autenticazione come utente, l'app Chat invia le 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 in formato RTF, interfacce basate su schede e widget interattivi. Dato che gli utenti di Chat possono inviare solo testo nei loro messaggi, puoi Includere solo testo quando si creano messaggi utilizzando l'autenticazione utente. Per scoprire di più sui messaggi disponibili per l'API Chat, consulta le 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
Python
- 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 il Python Libreria client delle API di Google.
- 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 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.
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 App di chat, incluse interfacce delle schede e widget interattivi.
Per chiamare messages.create()
utilizzando l'autenticazione utente, devi specificare il
seguenti campi della richiesta:
- Un ambito di autorizzazione
che supporta l'autenticazione utente
per questo metodo. Il seguente esempio utilizza
nell'ambito
chat.messages.create
. - La risorsa
Space
in cui vuoi pubblicare il messaggio. L'utente autenticato deve essere membro del spazio. - La
Message
risorsa 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 i thread, questo campo viene ignorato.
Per inviare un messaggio per conto di un utente, procedi nel seguente modo:
Python
- Nella directory di lavoro, crea un file denominato
chat_create_message_user.py
. Includi il seguente codice in
chat_create_message_user.py
:import os.path from google.auth.transport.requests import Request from google.oauth2.credentials import Credentials from google_auth_oauthlib.flow import InstalledAppFlow from googleapiclient.discovery import build from googleapiclient.errors import HttpError # Define your app's authorization scopes. # When modifying these scopes, delete the file token.json, if it exists. SCOPES = ["https://www.googleapis.com/auth/chat.messages.create"] def main(): ''' Authenticates with Chat API via user credentials, then creates a text message in a Chat space. ''' # Start with no credentials. creds = None # Authenticate with Google Workspace # and get user authorization. flow = InstalledAppFlow.from_client_secrets_file( 'client_secrets.json', SCOPES) creds = flow.run_local_server() # Build a service endpoint for Chat API. chat = build('chat', 'v1', credentials=creds) # Use the service endpoint to call Chat API. result = chat.spaces().messages().create( # The space to create the message in. # # Replace SPACE with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. parent='spaces/SPACE', # Optional. Sets custom ID for the message to use in other requests. messageId='client-myfirstusermessage', # The text message to create. body={ 'text': '👋 🌎Hello world! Text messages can contain things like:\n\n' + '* Hyperlinks 🔗\n' + '* Emojis 😄🎉\n' + '* Mentions of other Chat users `@` \n\n' 'For details, see the <https://developers.google.com/workspace/chat/format-messages|Chat API developer documentation>.' } ).execute() # Prints details about the created message. print(result) if __name__ == '__main__': main()
Sostituisci
SPACE
con l'ID dello spazioname
. Puoi ottenere l'ID chiamando il metodo Metodospaces.list()
oppure dall'URL dello spazio.Nella directory di lavoro, crea ed esegui l'esempio:
python3 chat_create_message_user.py
Se viene richiesto un URL, aprilo per autorizzare all'app di chat in base all'ambito utilizzato in richiesta.
L'app Chat crea il messaggio e gli indirizzi
l'utente pubblica il messaggio nello spazio. Nell'interfaccia a riga di comando,
L'API Chat restituisce l'istanza del nuovo
Message
risorsa.
Inviare un messaggio come app Chat
Questa sezione spiega come inviare messaggi contenenti testo, schede e widget accessori interattivi utilizzando autenticazione delle app.
Per chiamare messages.create()
utilizzando l'autenticazione delle app, devi specificare il
seguenti campi della richiesta:
- L'ambito di autorizzazione
chat.bot
. - La risorsa
Space
in cui vuoi pubblicare il messaggio. L'app Chat deve essere membro dello spazio. - La
Message
risorsa 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 i thread, questo campo viene ignorato.
La dimensione massima del messaggio (compreso testo o schede) è di 32.000 byte. Per inviare un messaggio che supera queste dimensioni, l'app Chat ma devono inviare più messaggi.
Per inviare un messaggio pubblicato come app Chat che contiene testo, una scheda e un pulsante cliccabile in fondo al messaggio. procedi nel seguente modo:
Python
- Nella directory di lavoro, crea un file denominato
chat_create_message_app.py
. Includi il seguente codice in
chat_create_message_app.py
:from apiclient.discovery import build from google.oauth2 import service_account # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = service_account.Credentials.from_service_account_file( 'credentials.json', scopes=SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # Specify the Chat space where the message is posted. Obtain the ID # from the resource name, or from the space's URL. SPACE = 'spaces/SPACE' # Create a Chat message. result = chat.spaces().messages().create( # The Chat space. parent=SPACE, # Optional. Sets custom ID for the message to use in other requests. messageId='client-myfirstappmessage', # The message to create with text, a card, and a button at the # bottom of the message. body= { 'text': '👋 🌎Hello world! I created this message by calling the Chat API\'s `messages.create()` method.', 'cardsV2': [{ 'cardId': 'myCardId', 'card': { 'header': { 'title': 'About this message', 'imageUrl': 'https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg', 'imageType': 'CIRCLE' }, "sections": [ { "header": "Contents", "widgets": [ { "textParagraph": { "text": "🔡 <b>Text</b> which can include hyperlinks 🔗, emojis 😄🎉, and @mentions 🗣️." }}, { "textParagraph": { "text": "🖼️ A <b>card</b> to display visual elements and request information such as text 🔤, dates and times 📅, and selections ☑️." }}, { "textParagraph": { "text": "👉🔘 An <b>accessory widget</b> which adds a button to the bottom of a message." }}, ] }, { "header": "What's next", "collapsible": True, "widgets": [ { "textParagraph": { "text": "❤️ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages.reactions/create'>Add a reaction</a>." }}, { "textParagraph": { "text": "🔄 <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/patch'>Update</a> or ❌ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/delete'>delete</a> the message." }}, { "textParagraph": { "text": '💡 <b>Pro tip</b>: To specify the message in other API requests, use its custom name: <i>' + SPACE + '/messages/client-myfirstappmessage</i>.' }} ] } ]} }], "accessoryWidgets": [ { "buttonList": { "buttons": [ { "text": "View documentation", "altText": "Opens a new browser tab and navigates to the Google Chat developer documentation website.", "icon": { "material_icon": { "name": "link" } }, "onClick": { "openLink": { "url": "https://developers.google.com/workspace/chat/create-messages" } } } ] } } ] } ).execute() print(result)
Sostituisci
SPACE
con l'ID dello spazioname
. Puoi ottenere l'ID chiamando il metodo Metodospaces.list()
oppure dall'URL dello spazio.Nella directory di lavoro, crea ed esegui l'esempio:
python3 chat_create_message_app.py
L'app Chat crea e pubblica il messaggio nell'
spazio. Nella tua interfaccia a riga di comando, l'API Chat restituisce il token
del nuovo componente
Message
risorsa.
Aggiungere widget interattivi nella parte inferiore di un messaggio
Nell'esempio di codice della sezione precedente, il valore Il messaggio dell'app di chat mostra un pulsante cliccabile nella parte inferiore del messaggio, noto come widget accessorio. Widget accessori vengono visualizzati dopo un testo o una scheda in un messaggio. Puoi usare questi widget per chiedere agli utenti di interagire con il tuo messaggio in vari modi, inclusi i seguenti:
- Valuta l'accuratezza o la soddisfazione di un messaggio.
- Segnala un problema relativo al messaggio o all'app Chat.
- Apri un link ai contenuti correlati, ad esempio alla documentazione.
- Ignorare o posticipare messaggi simili dall'app Chat per un determinato periodo di tempo.
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 SMS con widget accessori per consentire agli utenti di valutare la loro esperienza con l'app Chat.
![Widget accessorio.](https://developers-dot-devsite-v2-prod.appspot.com/static/workspace/chat/images/message-accessory-widgets-reference.png?authuser=0000&hl=it)
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, viene restituito il codice
(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
la risorsa User
rappresenta l'utente di Chat. Puoi utilizzare anche
name
del
Risorsa User
, come mostrato nell'esempio seguente:
{
"text": "Hello private world!",
"privateMessageViewer": {
"name": "users/USER_ID"
}
}
Sostituisci USER_ID
con un ID univoco per l'utente, ad esempio 12345678987654321
o
hao@cymbalgroup.com
. Per ulteriori informazioni su come specificare gli utenti, consulta
Identificare e specificare gli utenti di Google Chat.
Per inviare un messaggio privatamente, devi omettere quanto segue nella richiesta:
Avviare o rispondere in un thread
Per gli spazi che utilizzano i thread, puoi specificare se un nuovo messaggio avvia un thread o se risponde un thread esistente.
Per impostazione predefinita, i messaggi che crei utilizzando l'API Chat avviano una nuova . Per aiutarti a identificare il thread e a rispondere in un secondo momento, puoi specificare una chiave thread nella tua 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 specificarethreadKey
che hai creato. In caso contrario, devi utilizzarename
del thread. - Specifica il parametro di query
messageReplyOption
.
Il seguente JSON mostra un esempio del corpo della richiesta per un messaggio di testo che
avvia o risponde a un thread con la chiave helloWorldThread
:
{
'thread': {
'threadKey': 'helloWorldThread',
},
'text': '👋 🌎Hello world!'
}
Assegna 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 messages.create()
.
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 con il metodo get()
, devi utilizzare il
il nome della risorsa per specificare quale messaggio 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 assegnare un nome a un messaggio, specifica un ID personalizzato nel
messageId
campo quando crei il messaggio. Il campo messageId
consente di impostare il valore del parametro
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 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.
- Sia univoco all'interno di uno spazio. Un'app di Chat non può utilizzare stesso ID personalizzato per messaggi diversi.
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 con la visualizzazione, il debug e la correzione degli errori, consulta Risolvere i problemi e correggere gli errori di Google Chat.
Argomenti correlati
- Utilizzare il generatore di carte per progettare e visualizzare l'anteprima di messaggi di 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.
- Identificare gli utenti nei messaggi di Google Chat.
- Inviare messaggi a Google Chat con i webhook in arrivo.