Inviare un messaggio utilizzando l'API Google Chat

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 un utente di Chat specifico.
• Avvia o rispondi a un thread di messaggi.
• Assegna un nome a un messaggio in modo da poterlo specificare in altre richieste dell'API Chat.

Per altri esempi, consulta Esempi di app Google 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 deve inviare più messaggi.

Oltre a chiamare l'API Chat per creare messaggi, le app di Chat possono creare e inviare messaggi per rispondere alle interazioni degli utenti, ad esempio pubblicare un messaggio di benvenuto dopo che un utente ha aggiunto l'app Chat a 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 Chat restituisce il messaggio in modo sincrono, senza chiamare l'API Chat. Per informazioni sull'invio di messaggi per rispondere alle 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 l'autenticazione dell'app e l'autenticazione utente. Chat attribuisce il mittente del messaggio in modo diverso a seconda del tipo di autenticazione usato.

Quando esegui l'autenticazione come app di Chat, quest'ultima invia il messaggio.

Figura 1: con l'autenticazione delle app, l'app Chat invia il messaggio. Per indicare che il mittente non è una persona, Chat mostra App accanto al nome.

Quando esegui l'autenticazione come utente, l'app Chat invia il messaggio per conto dell'utente. Inoltre, Chat attribuisce l'app Chat al messaggio mostrandone il nome.

Figura 2: con l'autenticazione utente, l'utente invia il messaggio e Chat mostra il nome dell'app 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 contenenti RTF, 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 account Google Workspace Business o Enterprise 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, un'icona e una descrizione per l'app Chat.
  • Installa la libreria client Cloud per Node.js.
  • Crea le credenziali di accesso in base alla modalità di autenticazione nella richiesta dell'API Google Chat:
    • 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 eseguire l'autenticazione come app di Chat, crea le credenziali dell'account di servizio e salva le credenziali come file JSON denominato credentials.json.
• Scegli un ambito di autorizzazione a seconda che tu voglia eseguire l'autenticazione come utente o nell'app Chat.

• Uno spazio di Google Chat di cui l'utente autenticato o l'app Chat di chiamata è membro. Per autenticarti come app Chat, aggiungi l'app Chat allo spazio.

Python

• Un account Google Workspace Business o Enterprise con accesso a Google Chat.

• Configura l'ambiente:
  • Crea 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 Python.
  • Crea le credenziali di accesso in base alla modalità di autenticazione nella richiesta dell'API Google Chat:
    • Per autenticarti come utente di Chat, crea le credenziali dell'ID client OAuth e salva le credenziali come file JSON denominato 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.
• 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 autenticarti come app Chat, aggiungi l'app Chat allo spazio.

Java

• Un account Google Workspace Business o Enterprise 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 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 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.
• 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 autenticarti come app Chat, aggiungi l'app Chat allo spazio.

Apps Script

• Un account Google Workspace Business o Enterprise 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, un'icona e una descrizione per l'app Chat.
  • Crea un progetto Apps Script autonomo e attiva il servizio di chat avanzato.
  • In questa guida, devi utilizzare l'autenticazione dell'utente o dell'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 di cui l'utente autenticato o l'app Chat di chiamata è membro. Per autenticarti come app Chat, aggiungi l'app Chat allo spazio.

Gli esempi di codice in questa pagina utilizzano l'interfaccia dell'API gRPC con le librerie client di Google Cloud. In alternativa, puoi utilizzare l'interfaccia dell'API REST. Per ulteriori informazioni sulle interfacce gRPC e REST, consulta la panoramica dell'API Google Chat.

Inviare un messaggio dall'app Chat

Questa sezione spiega come inviare messaggi contenenti testo, schede e widget di accessori interattivi utilizzando l'autenticazione dell'app.

Figura 4. Un'app di chat invia un messaggio con testo, una scheda e un pulsante accessorio.

Per chiamare il metodo CreateMessage() utilizzando l'autenticazione dell'app, devi specificare i seguenti campi nella richiesta:

• L'chat.bot ambito dell'autorizzazione.
• La risorsa Space 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 testo avanzato (text), una o più interfacce di schede (cardsV2) o entrambe.

Se vuoi, puoi includere quanto segue:

• Il campo accessoryWidgets per includere pulsanti interattivi nella parte inferiore del messaggio.
• Il campo privateMessageViewer per inviare il messaggio in privato a un utente specificato.
• Il campo messageId, che consente di assegnare un nome al messaggio da utilizzare in altre richieste API.
• I campi thread.threadKey e messageReplyOption per avviare o rispondere 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

chat/client-libraries/cloud/create-message-app-cred.js

Visualizza su GitHub

import {createClientWithAppCredentials} from './authentication-utils.js';

// This sample shows how to create message with app credential
async function main() {
  // Create a client
  const chatClient = createClientWithAppCredentials();

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    message: {
      text: '👋🌎 Hello world! I created this message by calling ' +
            'the Chat API\'s `messages.create()` method.',
      cardsV2 : [{ card: {
        header: {
          title: 'About this message',
          imageUrl: 'https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg'
        },
        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."
              }
            }]
          }
        ]
      }}],
      accessoryWidgets: [{ buttonList: { buttons: [{
        text: 'View documentation',
        icon: { materialIcon: { name: 'link' }},
        onClick: { openLink: {
          url: 'https://developers.google.com/workspace/chat/create-messages'
        }}
      }]}}]
    }
  };

  // Make the request
  const response = await chatClient.createMessage(request);

  // Handle the response
  console.log(response);
}

main().catch(console.error);

Python

chat/client-libraries/cloud/create_message_app_cred.py

Visualizza su GitHub

from authentication_utils import create_client_with_app_credentials
from google.apps import chat_v1 as google_chat

# This sample shows how to create message with app credential
def create_message_with_app_cred():
    # Create a client
    client = create_client_with_app_credentials()

    # Initialize request argument(s)
    request = google_chat.CreateMessageRequest(
        # Replace SPACE_NAME here.
        parent = "spaces/SPACE_NAME",
        message = {
            "text": '👋🌎 Hello world! I created this message by calling ' +
                    'the Chat API\'s `messages.create()` method.',
            "cards_v2" : [{ "card": {
                "header": {
                    "title": 'About this message',
                    "image_url": 'https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg'
                },
                "sections": [{
                    "header": "Contents",
                    "widgets": [{ "text_paragraph": {
                            "text": '🔡 <b>Text</b> which can include ' +
                                    'hyperlinks 🔗, emojis 😄🎉, and @mentions 🗣️.'
                        }}, { "text_paragraph": {
                            "text": '🖼️ A <b>card</b> to display visual elements' +
                                    'and request information such as text 🔤, ' +
                                    'dates and times 📅, and selections ☑️.'
                        }}, { "text_paragraph": {
                            "text": '👉🔘 An <b>accessory widget</b> which adds ' +
                                    'a button to the bottom of a message.'
                        }}
                    ]}, {
                        "header": "What's next",
                        "collapsible": True,
                        "widgets": [{ "text_paragraph": {
                                "text": "❤️ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages.reactions/create'>Add a reaction</a>."
                            }}, { "text_paragraph": {
                                "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."
                            }
                        }]
                    }
                ]
            }}],
            "accessory_widgets": [{ "button_list": { "buttons": [{
                "text": 'View documentation',
                "icon": { "material_icon": { "name": 'link' }},
                "on_click": { "open_link": {
                    "url": 'https://developers.google.com/workspace/chat/create-messages'
                }}
            }]}}]
        }
    )

    # Make the request
    response = client.create_message(request)

    # Handle the response
    print(response)

create_message_with_app_cred()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMessageAppCred.java

Visualizza su GitHub

import com.google.apps.card.v1.Button;
import com.google.apps.card.v1.ButtonList;
import com.google.apps.card.v1.Card;
import com.google.apps.card.v1.Icon;
import com.google.apps.card.v1.MaterialIcon;
import com.google.apps.card.v1.OnClick;
import com.google.apps.card.v1.OpenLink;
import com.google.apps.card.v1.TextParagraph;
import com.google.apps.card.v1.Widget;
import com.google.apps.card.v1.Card.CardHeader;
import com.google.apps.card.v1.Card.Section;
import com.google.chat.v1.AccessoryWidget;
import com.google.chat.v1.CardWithId;
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMessageRequest;
import com.google.chat.v1.Message;

// This sample shows how to create message with app credential.
public class CreateMessageAppCred {

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithAppCredentials()) {
      CreateMessageRequest.Builder request = CreateMessageRequest.newBuilder()
        // Replace SPACE_NAME here.
        .setParent("spaces/SPACE_NAME")
        .setMessage(Message.newBuilder()
          .setText( "👋🌎 Hello world! I created this message by calling " +
                    "the Chat API\'s `messages.create()` method.")
          .addCardsV2(CardWithId.newBuilder().setCard(Card.newBuilder()
            .setHeader(CardHeader.newBuilder()
              .setTitle("About this message")
              .setImageUrl("https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg"))
            .addSections(Section.newBuilder()
              .setHeader("Contents")
              .addWidgets(Widget.newBuilder().setTextParagraph(TextParagraph.newBuilder().setText(
                "🔡 <b>Text</b> which can include " +
                "hyperlinks 🔗, emojis 😄🎉, and @mentions 🗣️.")))
              .addWidgets(Widget.newBuilder().setTextParagraph(TextParagraph.newBuilder().setText(
                "🖼️ A <b>card</b> to display visual elements " +
                "and request information such as text 🔤, " +
                "dates and times 📅, and selections ☑️.")))
              .addWidgets(Widget.newBuilder().setTextParagraph(TextParagraph.newBuilder().setText(
                "👉🔘 An <b>accessory widget</b> which adds " +
                "a button to the bottom of a message."))))
            .addSections(Section.newBuilder()
              .setHeader("What's next")
              .setCollapsible(true)
              .addWidgets(Widget.newBuilder().setTextParagraph(TextParagraph.newBuilder().setText(
                "❤️ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages.reactions/create'>Add a reaction</a>.")))
              .addWidgets(Widget.newBuilder().setTextParagraph(TextParagraph.newBuilder().setText(
                "🔄 <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."))))))
          .addAccessoryWidgets(AccessoryWidget.newBuilder()
            .setButtonList(ButtonList.newBuilder()
              .addButtons(Button.newBuilder()
                .setText("View documentation")
                .setIcon(Icon.newBuilder()
                  .setMaterialIcon(MaterialIcon.newBuilder().setName("link")))
                .setOnClick(OnClick.newBuilder()
                  .setOpenLink(OpenLink.newBuilder()
                    .setUrl("https://developers.google.com/workspace/chat/create-messages")))))));
      Message response = chatServiceClient.createMessage(request.build());

      System.out.println(JsonFormat.printer().print(response));
    }
  }
}

Apps Script

chat/advanced-service/Main.gs

Visualizza su GitHub

/**
 * This sample shows how to create message with app credential
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.bot'
 * used by service accounts.
 */
function createMessageAppCred() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';
  const message = {
    text: '👋🌎 Hello world! I created this message by calling ' +
          'the Chat API\'s `messages.create()` method.',
    cardsV2 : [{ card: {
      header: {
        title: 'About this message',
        imageUrl: 'https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg'
      },
      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."
            }
          }]
        }
      ]
    }}],
    accessoryWidgets: [{ buttonList: { buttons: [{
      text: 'View documentation',
      icon: { materialIcon: { name: 'link' }},
      onClick: { openLink: {
        url: 'https://developers.google.com/workspace/chat/create-messages'
      }}
    }]}}]
  };
  const parameters = {};

  // Make the request
  const response = Chat.Spaces.Messages.create(
    message, parent, parameters, getHeaderWithAppCredentials()
  );

  // Handle the response
  console.log(response);
}

Per eseguire questo esempio, sostituisci SPACE_NAME con l'ID del campo name dello spazio. Puoi ottenere l'ID chiamando il metodo ListSpaces() o dall'URL dello spazio.

Aggiungere widget interattivi in fondo a un messaggio

Nel primo esempio di codice di questa guida, il messaggio dell'app Chat mostra un pulsante cliccabile nella parte inferiore del messaggio, chiamato widget accessori. I widget accessori vengono visualizzati dopo il testo o le schede di un messaggio. Puoi utilizzare questi widget per chiedere agli utenti di interagire con il tuo messaggio in molti modi, tra cui:

• Valutare l'accuratezza o la soddisfazione di un messaggio.
• Segnalare un problema relativo all'app di messaggistica o Chat.
• Apri un link ai contenuti correlati, ad esempio la documentazione.
• Ignora o posticipa messaggi simili dall'app Chat per un periodo di tempo specifico.

Per aggiungere widget accessori, includi il campo accessoryWidgets[] nel corpo della richiesta e specifica uno o più widget 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.

Figura 5: un messaggio dell'app Chat con widget di testo e accessori.

Di seguito è riportato il corpo della richiesta che crea un messaggio 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 privato

Le app di chat possono inviare messaggi in privato in modo che il messaggio sia visibile solo a un utente specifico nello spazio. Quando un'app di chat invia un messaggio privato, viene visualizzata un'etichetta che informa l'utente che il messaggio è visibile solo a lui.

Per inviare un messaggio in privato utilizzando l'API Chat, specifica il campo privateMessageViewer nel corpo della richiesta. Per specificare l'utente, imposta il valore sulla risorsa User che rappresenta l'utente di Chat. Puoi anche utilizzare il campo 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 [e-mail]. 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:

• Collegamenti
• Widget per accessori

Invia un messaggio per conto di un utente

Questa sezione spiega come inviare messaggi per conto di un utente utilizzando l'autenticazione dell'utente. 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.

Figura 3. Un'app di Chat invia un messaggio di testo per conto di un utente.

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 un membro dello spazio.
• La risorsa Message da creare. Per definire i contenuti del messaggio, devi includere il campo text.

Se vuoi, puoi includere quanto segue:

• Il campo messageId, che consente di assegnare un nome al messaggio da utilizzare in altre richieste API.
• I campi thread.threadKey e messageReplyOption per avviare o rispondere 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

chat/client-libraries/cloud/create-message-user-cred.js

Visualizza su GitHub

import {createClientWithUserCredentials} from './authentication-utils.js';

const USER_AUTH_OAUTH_SCOPES = ['https://www.googleapis.com/auth/chat.messages.create'];

// This sample shows how to create message with user credential
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    message: {
      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>.'
    }
  };

  // Make the request
  const response = await chatClient.createMessage(request);

  // Handle the response
  console.log(response);
}

main().catch(console.error);

Python

chat/client-libraries/cloud/create_message_user_cred.py

Visualizza su GitHub

from authentication_utils import create_client_with_user_credentials
from google.apps import chat_v1 as google_chat

SCOPES = ["https://www.googleapis.com/auth/chat.messages.create"]

def create_message_with_user_cred():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.CreateMessageRequest(
        # Replace SPACE_NAME here.
        parent = "spaces/SPACE_NAME",
        message = {
            "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>.'
        }
    )

    # Make the request
    response = client.create_message(request)

    # Handle the response
    print(response)

create_message_with_user_cred()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMessageUserCred.java

Visualizza su GitHub

import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMessageRequest;
import com.google.chat.v1.Message;

// This sample shows how to create message with user credential.
public class CreateMessageUserCred {

  private static final String SCOPE =
    "https://www.googleapis.com/auth/chat.messages.create";

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      CreateMessageRequest.Builder request = CreateMessageRequest.newBuilder()
        // Replace SPACE_NAME here.
        .setParent("spaces/SPACE_NAME")
        .setMessage(Message.newBuilder()
          .setText( "👋🌎 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>."));
      Message response = chatServiceClient.createMessage(request.build());

      System.out.println(JsonFormat.printer().print(response));
    }
  }
}

Apps Script

chat/advanced-service/Main.gs

Visualizza su GitHub

/**
 * This sample shows how to create message with user credential
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.messages.create'
 * referenced in the manifest file (appsscript.json).
 */
function createMessageUserCred() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';
  const message = {
    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>.'
  };

  // Make the request
  const response = Chat.Spaces.Messages.create(message, parent);

  // Handle the response
  console.log(response);
}

Per eseguire questo esempio, sostituisci SPACE_NAME con l'ID del campo name dello spazio. Puoi ottenere l'ID chiamando il metodo ListSpaces() o dall'URL dello spazio.

Avviare o rispondere a 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 il campo 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:

• Includi il campo thread nel corpo della richiesta. Se impostato, puoi specificare il valore threadKey che hai creato. In caso contrario, devi utilizzare il pulsante name del thread.
• Specifica il parametro di query messageReplyOption.

Il seguente codice mostra un esempio di come un'app Chat possa 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

chat/client-libraries/cloud/create-message-user-cred-thread-key.js

Visualizza su GitHub

import {createClientWithUserCredentials} from './authentication-utils.js';
const {MessageReplyOption} = require('@google-apps/chat').protos.google.chat.v1.CreateMessageRequest;

const USER_AUTH_OAUTH_SCOPES = ['https://www.googleapis.com/auth/chat.messages.create'];

// This sample shows how to create message with user credential with thread key
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    // Creates the message as a reply to the thread specified by thread_key
    // If it fails, the message starts a new thread instead
    messageReplyOption: MessageReplyOption.REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD,
    message: {
      text: 'Hello with user credential!',
      thread: {
        // Thread key specifies a thread and is unique to the chat app
        // that sets it
        threadKey: 'THREAD_KEY'
      }
    }
  };

  // Make the request
  const response = await chatClient.createMessage(request);

  // Handle the response
  console.log(response);
}

main().catch(console.error);

Python

chat/client-libraries/cloud/create_message_user_cred_thread_key.py

Visualizza su GitHub

from authentication_utils import create_client_with_user_credentials
from google.apps import chat_v1 as google_chat

import google.apps.chat_v1.CreateMessageRequest.MessageReplyOption

SCOPES = ["https://www.googleapis.com/auth/chat.messages.create"]

# This sample shows how to create message with user credential with thread key
def create_message_with_user_cred_thread_key():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.CreateMessageRequest(
        # Replace SPACE_NAME here
        parent = "spaces/SPACE_NAME",
        # Creates the message as a reply to the thread specified by thread_key.
        # If it fails, the message starts a new thread instead.
        message_reply_option = MessageReplyOption.REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD,
        message = {
            "text": "Hello with user credential!",
            "thread": {
                # Thread key specifies a thread and is unique to the chat app
                # that sets it.
                "thread_key": "THREAD_KEY"
            }
        }
    )

    # Make the request
    response = client.create_message(request)

    # Handle the response
    print(response)

create_message_with_user_cred_thread_key()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMessageUserCredThreadKey.java

Visualizza su GitHub

import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMessageRequest;
import com.google.chat.v1.CreateMessageRequest.MessageReplyOption;
import com.google.chat.v1.Message;
import com.google.chat.v1.Thread;

// This sample shows how to create message with a thread key with user
// credential.
public class CreateMessageUserCredThreadKey {

  private static final String SCOPE =
    "https://www.googleapis.com/auth/chat.messages.create";

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      CreateMessageRequest.Builder request = CreateMessageRequest.newBuilder()
        // Replace SPACE_NAME here.
        .setParent("spaces/SPACE_NAME")
        // Creates the message as a reply to the thread specified by thread_key.
        // If it fails, the message starts a new thread instead.
        .setMessageReplyOption(
          MessageReplyOption.REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD)
        .setMessage(Message.newBuilder()
          .setText("Hello with user credentials!")
          // Thread key specifies a thread and is unique to the chat app
          // that sets it.
          .setThread(Thread.newBuilder().setThreadKey("THREAD_KEY")));
      Message response = chatServiceClient.createMessage(request.build());

      System.out.println(JsonFormat.printer().print(response));
    }
  }
}

Apps Script

chat/advanced-service/Main.gs

Visualizza su GitHub

/**
 * This sample shows how to create message with user credential with thread key
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.messages.create'
 * referenced in the manifest file (appsscript.json).
 */
function createMessageUserCredThreadKey() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';
  // Creates the message as a reply to the thread specified by thread_key
  // If it fails, the message starts a new thread instead
  const messageReplyOption = 'REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD';
  const message = {
    text: 'Hello with user credential!',
    thread: {
      // Thread key specifies a thread and is unique to the chat app
      // that sets it
      threadKey: 'THREAD_KEY'
    }
  };

  // Make the request
  const response = Chat.Spaces.Messages.create(message, parent, {
    messageReplyOption: messageReplyOption
  });

  // Handle the response
  console.log(response);
}

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 del campo name dello spazio. Puoi ottenere l'ID chiamando il metodo ListSpaces() 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. Assegnare un nome al messaggio ti consente di specificarlo senza dover memorizzare l'ID assegnato dal sistema dal nome della risorsa del messaggio (rappresentato nel campo 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 è formato come spaces/{space}/messages/{message}, dove {message} rappresenta l'ID assegnato dal sistema o il nome personalizzato impostato durante la creazione del messaggio.

Per assegnare un nome a un messaggio, specifica un ID personalizzato nel campo messageId quando lo crei. Il campo messageId imposta il valore del campo clientAssignedMessageId della risorsa Message.

Puoi assegnare un nome a un messaggio solo al momento della creazione. 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 ID personalizzato valido, ma custom-name non lo è.
• Deve contenere fino a 63 caratteri e solo lettere minuscole, numeri e trattini.
• Deve essere univoco all'interno di uno spazio. Un'app di chat non può utilizzare lo stesso ID personalizzato per messaggi diversi.

Il seguente codice mostra un esempio di come un'app Chat può inviare un messaggio con un ID a un determinato spazio per conto di un utente autenticato:

Node.js

chat/client-libraries/cloud/create-message-user-cred-message-id.js

Visualizza su GitHub

import {createClientWithUserCredentials} from './authentication-utils.js';

const USER_AUTH_OAUTH_SCOPES = ['https://www.googleapis.com/auth/chat.messages.create'];

// This sample shows how to create message with user credential with message id
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    // Message id lets chat apps get, update or delete a message without needing
    // to store the system assigned ID in the message's resource name
    messageId: 'client-MESSAGE-ID',
    message: { text: 'Hello with user credential!' }
  };

  // Make the request
  const response = await chatClient.createMessage(request);

  // Handle the response
  console.log(response);
}

main().catch(console.error);

Python

chat/client-libraries/cloud/create_message_user_cred_message_id.py

Visualizza su GitHub

from authentication_utils import create_client_with_user_credentials
from google.apps import chat_v1 as google_chat

SCOPES = ["https://www.googleapis.com/auth/chat.messages.create"]

# This sample shows how to create message with user credential with message id
def create_message_with_user_cred_message_id():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.CreateMessageRequest(
        # Replace SPACE_NAME here
        parent = "spaces/SPACE_NAME",
        # Message id let chat apps get, update or delete a message without needing
        # to store the system assigned ID in the message's resource name.
        message_id = "client-MESSAGE-ID",
        message = {
            "text": "Hello with user credential!"
        }
    )

    # Make the request
    response = client.create_message(request)

    # Handle the response
    print(response)

create_message_with_user_cred_message_id()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMessageUserCredMessageId.java

Visualizza su GitHub

import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMessageRequest;
import com.google.chat.v1.Message;

// This sample shows how to create message with message id specified with user
// credential.
public class CreateMessageUserCredMessageId {

  private static final String SCOPE =
    "https://www.googleapis.com/auth/chat.messages.create";

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      CreateMessageRequest.Builder request = CreateMessageRequest.newBuilder()
        // Replace SPACE_NAME here.
        .setParent("spaces/SPACE_NAME")
        .setMessage(Message.newBuilder()
          .setText("Hello with user credentials!"))
        // Message ID lets chat apps get, update or delete a message without
        // needing to store the system assigned ID in the message's resource
        // name.
        .setMessageId("client-MESSAGE-ID");
      Message response = chatServiceClient.createMessage(request.build());

      System.out.println(JsonFormat.printer().print(response));
    }
  }
}

Apps Script

chat/advanced-service/Main.gs

Visualizza su GitHub

/**
 * This sample shows how to create message with user credential with message id
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.messages.create'
 * referenced in the manifest file (appsscript.json).
 */
function createMessageUserCredMessageId() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';
  // Message id lets chat apps get, update or delete a message without needing
  // to store the system assigned ID in the message's resource name
  const messageId = 'client-MESSAGE-ID';
  const message = { text: 'Hello with user credential!' };

  // Make the request
  const response = Chat.Spaces.Messages.create(message, parent, {
    messageId: messageId
  });

  // Handle the response
  console.log(response);
}

Per eseguire questo esempio, sostituisci quanto segue:

• SPACE_NAME: l'ID del campo name dello spazio. Puoi ottenere l'ID chiamando il metodo ListSpaces() o dall'URL dello spazio.
• MESSAGE-ID: un nome per il messaggio che inizia con custom-. Deve essere univoco rispetto a tutti gli altri nomi di messaggi creati dall'app Chat nello spazio specificato.

Risoluzione dei problemi

Quando un'app o una scheda di Google Chat restituisce un errore, l'interfaccia di Chat mostra il messaggio "Si è verificato un problema". o "Impossibile elaborare la tua richiesta". A volte nella UI di Chat non viene visualizzato alcun messaggio di errore, ma l'app o la scheda Chat produce un risultato imprevisto. Ad esempio, il messaggio di una scheda potrebbe non essere visualizzato.

Sebbene un messaggio di errore potrebbe non essere visualizzato nell'interfaccia utente di Chat, sono disponibili messaggi di errore descrittivi e dati di log per aiutarti a correggere gli errori quando la registrazione degli errori per le app Chat è attivata. Per informazioni su visualizzazione, debug e correzione degli errori, vedi Risolvere i problemi e correggere 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.
• Aggiornare un messaggio.
• Eliminare un messaggio.
• Identificare gli utenti nei messaggi di Google Chat.
• Inviare messaggi a Google Chat con webhook in arrivo.