Envoyer un message à l'aide de l'API Google Chat

Ce guide explique comment utiliser la méthode create() sur la ressource Message de l'API Google Chat pour effectuer l'une des opérations suivantes :

  • Envoyez des messages contenant du texte, des fiches et des widgets interactifs.
  • Envoyez des messages privés à un utilisateur Chat spécifique.
  • Démarrer un fil de discussion ou y répondre.
  • Nommez un message afin de pouvoir le spécifier dans d'autres requêtes de l'API Chat.

La taille maximale des messages (y compris le texte ou les fiches) est de 32 000 octets. Pour envoyer un message qui dépasse cette taille, votre application Chat doit envoyer plusieurs messages.

En plus d'appeler l'API Chat pour créer des messages, les applications Chat peuvent créer et envoyer des messages pour répondre aux interactions des utilisateurs, par exemple en publiant un message de bienvenue après qu'un utilisateur a ajouté l'application Chat à un espace. Lorsqu'elles répondent aux interactions, les applications Chat peuvent utiliser d'autres types de fonctionnalités de messagerie, y compris des boîtes de dialogue interactives et des interfaces d'aperçu des liens. Pour répondre à un utilisateur, l'application Chat renvoie le message de manière synchrone, sans appeler l'API Chat. Pour savoir comment envoyer des messages en réponse à des interactions, consultez Recevoir des interactions avec votre application Google Chat et y répondre.

Comment Chat affiche et attribue les messages créés avec l'API Chat

Vous pouvez appeler la méthode create() à l'aide de l'authentification de l'application et de l'authentification de l'utilisateur. Chat attribue l'expéditeur du message différemment selon le type d'authentification que vous utilisez.

Lorsque vous vous authentifiez en tant qu'application Chat, l'application Chat envoie le message.

Appel de la méthode create() avec l'authentification de l'application.
Figure 1 : Avec l'authentification de l'application, l'application Chat envoie le message. Pour indiquer que l'expéditeur n'est pas une personne, Chat affiche App à côté de son nom.

Lorsque vous vous authentifiez en tant qu'utilisateur, l'application Chat envoie le message au nom de l'utilisateur. Chat attribue également l'application Chat au message en affichant son nom.

Appel de la méthode create() avec l'authentification des utilisateurs.
Figure 2 : Avec l'authentification des utilisateurs, l'utilisateur envoie le message et Chat affiche le nom de l'application Chat à côté du nom de l'utilisateur.

Le type d'authentification détermine également les fonctionnalités et interfaces de messagerie que vous pouvez inclure dans le message. Avec l'authentification de l'application, les applications Chat peuvent envoyer des messages contenant du texte enrichi, des interfaces basées sur des fiches et des widgets interactifs. Avec l'authentification des utilisateurs, vous pouvez envoyer des messages textuels ou créer des messages avec des fiches, comme indiqué dans Créer et mettre à jour des fiches interactives.

Pour en savoir plus sur les fonctionnalités de messagerie disponibles pour l'API Chat, consultez la présentation des messages Google Chat.

Ce guide explique comment utiliser l'un ou l'autre de ces types d'authentification pour envoyer un message avec l'API Chat.

Prérequis

Node.js

Python

Java

Apps Script

Envoyer un message en tant qu'application Chat

Cette section explique comment envoyer des messages contenant du texte, des fiches et des widgets d'accessoires interactifs à l'aide de l'authentification de l'application.

Message envoyé avec authentification de l'application
Figure 4. Une application Chat envoie un message contenant du texte, une fiche et un bouton accessoire.

Pour appeler la méthode CreateMessage() à l'aide de l'authentification de l'application, vous devez spécifier les champs suivants dans la requête :

  • Le champ d'application des autorisations chat.bot.
  • Ressource Space dans laquelle vous souhaitez publier le message. L'application Chat doit être membre de l'espace.
  • Ressource Message à créer. Pour définir le contenu du message, vous pouvez inclure du texte enrichi (text), une ou plusieurs interfaces de fiches (cardsV2), ou les deux.

Vous pouvez éventuellement inclure les éléments suivants :

Le code suivant montre comment une application Chat peut envoyer un message publié en tant qu'application Chat contenant du texte, une fiche et un bouton cliquable en bas du message :

Node.js

chat/client-libraries/cloud/create-message-app-cred.js
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);
}

await main();

Python

chat/client-libraries/cloud/create_message_app_cred.py
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
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
/**
 * 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);
}

Pour exécuter cet exemple, remplacez SPACE_NAME par l'ID du champ name de l'espace. Vous pouvez obtenir l'ID en appelant la méthode ListSpaces() ou à partir de l'URL de l'espace.

Ajouter des widgets interactifs au bas d'un message

Dans le premier exemple de code de ce guide, le message de l'application Chat affiche un bouton cliquable en bas du message, appelé widget accessoire. Les widgets d'accessoires s'affichent après le texte ou les fiches d'un message. Vous pouvez utiliser ces widgets pour inviter les utilisateurs à interagir avec votre message de différentes manières, par exemple :

  • Évaluer la précision ou la satisfaction d'un message.
  • Signaler un problème concernant le message ou l'application Chat.
  • Ouvrez un lien vers du contenu associé, tel que de la documentation.
  • Ignorer ou répéter les messages similaires de l'application Chat pendant une période spécifique.

Pour ajouter des widgets accessoires, incluez le champ accessoryWidgets[] dans le corps de votre requête et spécifiez un ou plusieurs widgets que vous souhaitez inclure.

L'image suivante montre une application Chat qui ajoute un message texte avec des widgets accessoires pour que les utilisateurs puissent évaluer leur expérience avec l'application Chat.

Widget d'accessoire.
Figure 5 : Message d'une application Chat avec du texte et des widgets accessoires

L'exemple suivant montre le corps de la requête qui crée un message avec deux boutons d'accessoire. Lorsqu'un utilisateur clique sur un bouton, la fonction correspondante (telle que doUpvote) traite l'interaction :

{
  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"
    }}
  }]}}]
}

Envoyer un message privé

Les applications Chat peuvent envoyer des messages privés de sorte qu'ils ne soient visibles que par un utilisateur spécifique de l'espace. Lorsqu'une application Chat envoie un message privé, un libellé indique à l'utilisateur qu'il est le seul à pouvoir le lire.

Pour envoyer un message privé à l'aide de l'API Chat, spécifiez le champ privateMessageViewer dans le corps de votre requête. Pour spécifier l'utilisateur, définissez la valeur sur la ressource User qui représente l'utilisateur Chat. Vous pouvez également utiliser le champ name de la ressource User, comme illustré dans l'exemple suivant :

{
  text: "Hello private world!",
  privateMessageViewer: {
    name: "users/USER_ID"
  }
}

Pour utiliser cet exemple, remplacez USER_ID par un ID unique pour l'utilisateur, tel que 12345678987654321 ou hao@cymbalgroup.com. Pour en savoir plus sur la spécification des utilisateurs, consultez Identifier et spécifier des utilisateurs Google Chat.

Pour envoyer un message en privé, vous devez omettre les éléments suivants dans votre requête :

Envoyer des notifications forcées ou des messages silencieux

Lorsqu'une application Chat envoie un message, elle peut utiliser l'une de ces options pour en informer les utilisateurs :

  • Forcer une notification : Chat envoie toujours une notification push aux destinataires, quels que soient leurs paramètres de notification ou leur état "Ne pas déranger". Dans Chat, le message déclenche un comportement de mise en gras et de mise en avant dans la liste des destinataires ou la liste d'accueil, et affiche un badge.
  • Envoyer un message silencieux : Chat supprime les notifications push pour les destinataires. Dans Chat, le message n'est pas mis en gras ni déplacé vers le haut dans la liste des destinataires ou la liste d'accueil, et aucun badge ne s'affiche. Si le message silencieux est le dernier message d'une conversation, son contenu ne s'affiche pas dans l'extrait de la page d'accueil.

Qu'ils soient forcés ou silencieux, ces messages incluent un indicateur visuel qui informe les destinataires du comportement de notification spécial.

Les notifications forcées et les messages silencieux ne sont disponibles que pour les applications Chat utilisant l'authentification d'application.

Les notifications forcées et les messages silencieux sont soumis aux limites suivantes :

  • Utilisateurs externes : les notifications forcées et les messages silencieux ne s'appliquent pas aux utilisateurs externes (invités) d'un espace. Les utilisateurs externes reçoivent des notifications en fonction de leurs propres paramètres.
  • Mentions : les messages silencieux ne permettent pas de mentionner des utilisateurs. Si vous incluez une mention dans un message silencieux, elle est traitée comme du texte brut.
  • Fils de discussion : vous ne pouvez pas démarrer un fil de discussion ni y répondre avec un message silencieux.
  • Type d'espace : les notifications forcées et les messages silencieux ne sont pas disponibles dans les messages privés ni dans les espaces appartenant à des personnes qui ne possèdent pas de compte Google Workspace.
  • Notifications par e-mail : les messages silencieux ne déclenchent pas de notifications par e-mail. Les messages avec notification forcée ne déclenchent des notifications par e-mail que s'ils incluent également une mention pour un utilisateur spécifique.

Pour forcer une notification ou envoyer un message silencieux, incluez le champ createMessageNotificationOptions dans votre requête et définissez notificationType sur l'une des valeurs suivantes :

Valeur Comportement
NOTIFICATION_TYPE_FORCE_NOTIFY Force une notification.
NOTIFICATION_TYPE_SILENT Envoie le message de manière silencieuse.

L'exemple suivant montre le corps JSON d'une requête d'envoi de message avec une notification forcée :

{
  "text": "Critical update: the server is down!",
  "createMessageNotificationOptions": {
    "notificationType": "NOTIFICATION_TYPE_FORCE_NOTIFY"
  }
}

Envoyer un message au nom d'un utilisateur

Cette section explique comment envoyer des messages au nom d'un utilisateur à l'aide de l'authentification des utilisateurs. L'authentification des utilisateurs vous permet d'envoyer des messages ou de créer des messages avec des fiches au nom d'un utilisateur. Pour en savoir plus sur l'envoi de fiches au nom d'un utilisateur, consultez Créer et mettre à jour des fiches interactives.

Message envoyé avec authentification de l'utilisateur
Figure 3. Une application Chat envoie un message au nom d'un utilisateur.

Pour appeler la méthode CreateMessage() à l'aide de l'authentification des utilisateurs, vous devez spécifier les champs suivants dans la requête :

  • Un champ d'application d'autorisation compatible avec l'authentification des utilisateurs pour cette méthode. L'exemple suivant utilise le champ d'application chat.messages.create.
  • Ressource Space dans laquelle vous souhaitez publier le message. L'utilisateur authentifié doit être membre de l'espace.
  • Ressource Message à créer. Pour définir le contenu du message, vous devez inclure le champ text.

Vous pouvez éventuellement inclure les éléments suivants :

Le code suivant montre comment une application Chat peut envoyer un message dans un espace donné au nom d'un utilisateur authentifié :

Node.js

chat/client-libraries/cloud/create-message-user-cred.js
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);
}

await main();

Python

chat/client-libraries/cloud/create_message_user_cred.py
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
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
/**
 * 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);
}

Pour exécuter cet exemple, remplacez SPACE_NAME par l'ID du champ name de l'espace. Vous pouvez obtenir l'ID en appelant la méthode ListSpaces() ou à partir de l'URL de l'espace.

Démarrer un fil de discussion ou y répondre

Pour les espaces qui utilisent des fils de discussion, vous pouvez spécifier si un nouveau message démarre un fil de discussion ou répond à un fil de discussion existant.

Par défaut, les messages que vous créez à l'aide de l'API Chat lancent un nouveau fil de discussion. Pour vous aider à identifier le fil de discussion et à y répondre ultérieurement, vous pouvez spécifier une clé de fil de discussion dans votre requête :

  • Dans le corps de votre requête, spécifiez le champ thread.threadKey.
  • Spécifiez le paramètre de requête messageReplyOption pour déterminer ce qui se passe si la clé existe déjà.

Pour créer un message qui répond à un fil de discussion existant :

  • Dans le corps de votre requête, incluez le champ thread. Si cette option est définie, vous pouvez spécifier le threadKey que vous avez créé. Sinon, vous devez utiliser l'name du fil de discussion.
  • Spécifiez le paramètre de requête messageReplyOption.

Le code suivant montre comment une application Chat peut envoyer un message qui démarre un fil de discussion donné ou y répond, identifié par la clé d'un espace donné, au nom d'un utilisateur authentifié :

Node.js

chat/client-libraries/cloud/create-message-user-cred-thread-key.js
import {protos} from '@google-apps/chat';
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 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:
      protos.google.chat.v1.CreateMessageRequest.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);
}

await main();

Python

chat/client-libraries/cloud/create_message_user_cred_thread_key.py
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
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
/**
 * 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);
}

Pour exécuter cet exemple, remplacez les éléments suivants :

  • THREAD_KEY : clé de fil de discussion existante dans l'espace ou, pour créer un fil de discussion, nom unique du fil de discussion.
  • SPACE_NAME : ID du champ name de l'espace. Vous pouvez obtenir l'ID en appelant la méthode ListSpaces() ou à partir de l'URL de l'espace.

Nommer un message

Pour récupérer ou spécifier un message dans de futurs appels d'API, vous pouvez nommer un message en définissant le champ messageId dans votre requête. En nommant votre message, vous pouvez le spécifier sans avoir à stocker l'ID attribué par le système à partir du nom de ressource du message (représenté dans le champ name).

Par exemple, pour récupérer un message à l'aide de la méthode get(), vous utilisez le nom de la ressource pour spécifier le message à récupérer. Le nom de la ressource est au format spaces/{space}/messages/{message}, où {message} représente l'ID attribué par le système ou le nom personnalisé que vous avez défini lors de la création du message.

Pour nommer un message, spécifiez un ID personnalisé dans le champ messageId lorsque vous créez le message. Le champ messageId définit la valeur du champ clientAssignedMessageId de la ressource Message.

Vous ne pouvez nommer un message que lorsque vous le créez. Vous ne pouvez pas nommer ni modifier un ID personnalisé pour les messages existants. L'ID personnalisé doit répondre aux exigences suivantes :

  • Commence par client-. Par exemple, client-custom-name est un ID personnalisé valide, mais pas custom-name.
  • Contient jusqu'à 63 caractères et uniquement des lettres minuscules, des chiffres et des traits d'union.
  • Il est unique dans un espace. Une application Chat ne peut pas utiliser le même ID personnalisé pour différents messages.

Le code suivant montre comment une application Chat peut envoyer un message avec un ID à un espace donné au nom d'un utilisateur authentifié :

Node.js

chat/client-libraries/cloud/create-message-user-cred-message-id.js
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 a message with user credentials and a custom
// 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);
}

await main();

Python

chat/client-libraries/cloud/create_message_user_cred_message_id.py
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
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
/**
 * 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);
}

Pour exécuter cet exemple, remplacez les éléments suivants :

  • SPACE_NAME : ID du champ name de l'espace. Vous pouvez obtenir l'ID en appelant la méthode ListSpaces() ou à partir de l'URL de l'espace.
  • MESSAGE-ID : nom du message commençant par custom-. Il doit être différent de tous les autres noms de messages créés par l'application Chat dans l'espace spécifié.

Citer un message

Vous pouvez citer un autre message en appelant CreateMessage() (rpc, rest) et en définissant quotedMessageMetadata (rpc, rest) dans la requête.

Vous pouvez citer des messages dans un fil de discussion ou dans le chat principal, mais pas un message provenant d'un autre fil de discussion.

Le code suivant montre comment créer un message qui cite un autre message :

Node.js

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 a message that quotes another message.
async function main() {

  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {

    // TODO(developer): Replace SPACE_NAME .
    parent: 'spaces/SPACE_NAME',

    message: {
      text: 'I am responding to a quoted message!',

      // quotedMessageMetadata lets Chat apps respond to a message by quoting it.
      quotedMessageMetadata: {

        // TODO(developer): Replace QUOTED_MESSAGE_NAME
        // and QUOTED_MESSAGE_LAST_UPDATE_TIME.
        name: 'QUOTED_MESSAGE_NAME',
        lastUpdateTime: 'QUOTED_MESSAGE_LAST_UPDATE_TIME'
      }
    }
  };

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

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

main().catch(console.error);

Python

from authentication_utils import create_client_with_user_credentials
from google.apps import chat_v1 as google_chat
from google.protobuf.timestamp_pb2 import Timestamp

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

# This sample shows how to create a message that quotes another message.
def create_message_quote_message():
    '''Creates a message that quotes another message.'''

    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Create a timestamp from the RFC-3339 string.
    # TODO(developer): Replace QUOTED_MESSAGE_LAST_UPDATE_TIME.
    last_update_time = Timestamp()
    last_update_time.FromJsonString('QUOTED_MESSAGE_LAST_UPDATE_TIME')

    # Initialize request argument(s)
    request = google_chat.CreateMessageRequest(

        # TODO(developer): Replace SPACE_NAME.
        parent='spaces/SPACE_NAME',

        # Create the message.
        message = google_chat.Message(
            text='I am responding to a quoted message!',

            # quotedMessageMetadata lets Chat apps respond to a message by quoting it.
            quoted_message_metadata=google_chat.QuotedMessageMetadata(

                name='QUOTED_MESSAGE_NAME',
                last_update_time=last_update_time
            )
        )
    )

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

    # Handle the response
    print(response)

create_message_quote_message()

Java

import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMessageRequest;
import com.google.chat.v1.Message;
import com.google.chat.v1.QuotedMessageMetadata;
import com.google.protobuf.util.Timestamps;
import com.google.workspace.api.chat.samples.utils.AuthenticationUtils;
import java.text.ParseException;

// This sample shows how to create a message that quotes another message.
public class CreateMessageQuoteMessage {
  public static void main(String[] args) throws Exception, ParseException {
    // Create a client.
    ChatServiceClient chatClient = AuthenticationUtils.createClientWithUserCredentials();

    // Initialize request argument(s).
    // TODO(developer): Replace SPACE_NAME, QUOTED_MESSAGE_NAME,
    // and QUOTED_MESSAGE_LAST_UPDATE_TIME here.
    String parent = "spaces/SPACE_NAME";
    String quotedMessageName = "QUOTED_MESSAGE_NAME";
    String lastUpdateTime = "QUOTED_MESSAGE_LAST_UPDATE_TIME";

    QuotedMessageMetadata quotedMessageMetadata =
        QuotedMessageMetadata.newBuilder()
            .setName(quotedMessageName)
            .setLastUpdateTime(Timestamps.parse(lastUpdateTime))
            .build();

    Message message = Message.newBuilder()
        .setText("I am responding to a quoted message!")
        .setQuotedMessageMetadata(quotedMessageMetadata)
        .build();

    CreateMessageRequest request =
        CreateMessageRequest.newBuilder()
            .setParent(parent)
            .setMessage(message)
            .build();

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

    // Handle the response.
    System.out.println(response);
  }
}

Apps Script

/**
 * Creates a message that quotes another message.
 *
 * Relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.messages.create'
 * referenced in the manifest file (appsscript.json).
 */
function createMessageQuoteMessage() {

  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';

  const message = {

    // The text content of the message.
    text: 'I am responding to a quoted message!',

    // quotedMessageMetadata lets Chat apps respond to a message by quoting it.
    //
    // TODO(developer): Replace QUOTED_MESSAGE_NAME
    // and QUOTED_MESSAGE_LAST_UPDATE_TIME .
    quotedMessageMetadata: {
      name: 'QUOTED_MESSAGE_NAME',
      lastUpdateTime: 'QUOTED_MESSAGE_LAST_UPDATE_TIME',
    }
  };

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

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

Pour exécuter cet exemple, remplacez les éléments suivants :

  • SPACE_NAME : ID du champ name de l'espace. Vous pouvez obtenir l'ID en appelant la méthode ListSpaces() (rpc, rest) ou à partir de l'URL de l'espace.
  • QUOTED_MESSAGE_NAME : ressource de message name (rpc, rest) du message à citer, au format spaces/{space}/messages/{message}.
  • QUOTED_MESSAGE_LAST_UPDATE_TIME : heure de la dernière mise à jour du message que vous souhaitez citer. Si le message n'a jamais été modifié, correspond à createTime (rpc, rest). Si le message a été modifié, correspond à lastUpdateTime (rpc, rest).

Résoudre les problèmes

Lorsqu'une application Chat ou une fiche Google Chat renvoie une erreur, l'interface Chat affiche le message "Un problème est survenu". ou "Impossible de traiter votre demande." Il arrive que l'UI de Chat n'affiche aucun message d'erreur, mais que l'application Chat ou la fiche produise un résultat inattendu. Par exemple, un message de fiche peut ne pas s'afficher.

Même si aucun message d'erreur ne s'affiche dans l'UI de Chat, des messages d'erreur descriptifs et des données de journal sont disponibles pour vous aider à corriger les erreurs lorsque la journalisation des erreurs est activée pour les applications Chat. Pour savoir comment afficher, déboguer et corriger les erreurs, consultez Résoudre les problèmes liés à Google Chat.