Inviare un messaggio utilizzando l'API Google Chat

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.

Chiamata del metodo messages.create() con l'autenticazione dell'app.
Figura 1: con l'autenticazione app, l'app Chat invia il messaggio. Per indicare che il mittente non è una persona, in Chat viene visualizzato App accanto al nome.

Quando esegui l'autenticazione come utente, l'app Chat invia le per conto dell'utente. Chat attribuisce inoltre app di Chat al messaggio visualizzandone il nome

Chiamata del metodo messages.create() con l'autenticazione utente.
Figura 2: con l'autenticazione utente, l'utente invia il messaggio e Chat visualizza Il nome dell'app di chat accanto al nome dell'utente.

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

  • Python 3.6 o versioni successive
  • Lo strumento di gestione dei pacchetti pip
  • Le librerie client di Google più recenti. Per installarle o aggiornarle, esegui questo comando nell'interfaccia a riga di comando: 
    pip3 install --upgrade google-api-python-client google-auth-oauthlib

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.

Messaggio inviato con autenticazione utente
. Figura 3. Un'app di Chat invia un messaggio su per conto di un utente.

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 sezione text .

Se vuoi, puoi includere quanto segue:

Per inviare un messaggio per conto di un utente, procedi nel seguente modo:

Python

  1. Nella directory di lavoro, crea un file denominato chat_create_message_user.py.

  2. 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 spazio name . Puoi ottenere l'ID chiamando il metodo Metodo spaces.list() oppure dall'URL dello spazio.

  3. Nella directory di lavoro, crea ed esegui l'esempio:

    python3 chat_create_message_user.py

  4. 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.

Messaggio inviato con autenticazione delle app
. Figura 4. Un'app di Chat invia un messaggio con testo, una carta e un pulsante accessorio.

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:

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

  1. Nella directory di lavoro, crea un file denominato chat_create_message_app.py.

  2. 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 spazio name . Puoi ottenere l'ID chiamando il metodo Metodo spaces.list() oppure dall'URL dello spazio.

  3. 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.
Figura 5: un messaggio dell'app Chat con widget di testo e accessori.

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:

Per creare un messaggio che risponda a un thread esistente:

  • Nel corpo della richiesta, includi il campo thread. Se impostato, puoi specificare threadKey che hai creato. In caso contrario, devi utilizzare name 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, ma custom-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.