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 pour pouvoir le spécifier dans d'autres requêtes de l'API Chat.
La taille maximale d'un message (texte ou cartes inclus) 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 à des 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 de 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 et y répondre avec votre application Google Chat.
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.
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.
Le type d'authentification détermine également les fonctionnalités et interfaces de messagerie que vous pouvez inclure dans le message. Avec l'authentification des applications, les applications Chat peuvent envoyer des messages contenant du texte enrichi, des interfaces basées sur des fiches et des widgets interactifs. Étant donné que les utilisateurs de Chat ne peuvent envoyer que du texte dans leurs messages, vous ne pouvez inclure que du texte lorsque vous créez des messages à l'aide de l'authentification des utilisateurs. Pour en savoir plus sur les fonctionnalités de messagerie disponibles pour l'API Chat, consultez Présentation des messages Google Chat.
Ce guide explique comment utiliser l'un ou l'autre type d'authentification pour envoyer un message avec l'API Chat.
Prérequis
Node.js
- Compte Google Workspace Business ou Enterprise ayant accès à Google Chat.
- Configurez votre environnement :
- Créez un projet Google Cloud.
- Configurez l'écran de consentement OAuth.
- Activez et configurez l'API Google Chat en attribuant un nom, une icône et une description à votre application Chat.
- Installez la bibliothèque cliente Cloud Node.js.
- Créez des identifiants d'accès en fonction de la façon dont vous souhaitez vous authentifier dans votre requête API Google Chat :
- Pour vous authentifier en tant qu'utilisateur Chat, créez des identifiants d'ID client OAuth et enregistrez-les dans un fichier JSON nommé
credentials.json
dans votre répertoire local. - Pour vous authentifier en tant qu'application Chat, créez des identifiants de compte de service et enregistrez-les dans un fichier JSON nommé
credentials.json
.
- Pour vous authentifier en tant qu'utilisateur Chat, créez des identifiants d'ID client OAuth et enregistrez-les dans un fichier JSON nommé
- Choisissez un champ d'application de l'autorisation selon que vous souhaitez vous authentifier en tant qu'utilisateur ou en tant qu'application Chat.
- Un espace Google Chat dont l'utilisateur authentifié ou l'application Chat appelante est membre. Pour vous authentifier en tant qu'application Chat, ajoutez l'application Chat à l'espace.
Python
- Compte Google Workspace Business ou Enterprise ayant accès à Google Chat.
- Configurez votre environnement :
- Créez un projet Google Cloud.
- Configurez l'écran de consentement OAuth.
- Activez et configurez l'API Google Chat en attribuant un nom, une icône et une description à votre application Chat.
- Installez la bibliothèque cliente Cloud Python.
- Créez des identifiants d'accès en fonction de la façon dont vous souhaitez vous authentifier dans votre requête API Google Chat :
- Pour vous authentifier en tant qu'utilisateur Chat, créez des identifiants d'ID client OAuth et enregistrez-les dans un fichier JSON nommé
credentials.json
dans votre répertoire local. - Pour vous authentifier en tant qu'application Chat, créez des identifiants de compte de service et enregistrez-les dans un fichier JSON nommé
credentials.json
.
- Pour vous authentifier en tant qu'utilisateur Chat, créez des identifiants d'ID client OAuth et enregistrez-les dans un fichier JSON nommé
- Choisissez un champ d'application de l'autorisation selon que vous souhaitez vous authentifier en tant qu'utilisateur ou en tant qu'application Chat.
- Un espace Google Chat dont l'utilisateur authentifié ou l'application Chat appelante est membre. Pour vous authentifier en tant qu'application Chat, ajoutez l'application Chat à l'espace.
Java
- Compte Google Workspace Business ou Enterprise ayant accès à Google Chat.
- Configurez votre environnement :
- Créez un projet Google Cloud.
- Configurez l'écran de consentement OAuth.
- Activez et configurez l'API Google Chat en attribuant un nom, une icône et une description à votre application Chat.
- Installez la bibliothèque cliente Cloud Java.
- Créez des identifiants d'accès en fonction de la façon dont vous souhaitez vous authentifier dans votre requête API Google Chat :
- Pour vous authentifier en tant qu'utilisateur Chat, créez des identifiants d'ID client OAuth et enregistrez-les dans un fichier JSON nommé
credentials.json
dans votre répertoire local. - Pour vous authentifier en tant qu'application Chat, créez des identifiants de compte de service et enregistrez-les dans un fichier JSON nommé
credentials.json
.
- Pour vous authentifier en tant qu'utilisateur Chat, créez des identifiants d'ID client OAuth et enregistrez-les dans un fichier JSON nommé
- Choisissez un champ d'application de l'autorisation selon que vous souhaitez vous authentifier en tant qu'utilisateur ou en tant qu'application Chat.
- Un espace Google Chat dont l'utilisateur authentifié ou l'application Chat appelante est membre. Pour vous authentifier en tant qu'application Chat, ajoutez l'application Chat à l'espace.
Apps Script
- Compte Google Workspace Business ou Enterprise ayant accès à Google Chat.
- Configurez votre environnement :
- Créez un projet Google Cloud.
- Configurez l'écran de consentement OAuth.
- Activez et configurez l'API Google Chat en attribuant un nom, une icône et une description à votre application Chat.
- Créez un projet Apps Script autonome et activez le service Chat avancé.
- Dans ce guide, vous devez utiliser l'authentification des utilisateurs ou des applications. Pour vous authentifier en tant qu'application Chat, créez des identifiants de compte de service. Pour connaître la marche à suivre, consultez S'authentifier et autoriser l'accès en tant qu'application Google Chat.
- Choisissez un champ d'application de l'autorisation selon que vous souhaitez vous authentifier en tant qu'utilisateur ou en tant qu'application Chat.
- Un espace Google Chat dont l'utilisateur authentifié ou l'application Chat appelante est membre. Pour vous authentifier en tant qu'application Chat, ajoutez l'application Chat à l'espace.
Envoyer un message avec l'application Chat
Cette section explique comment envoyer des messages contenant du texte, des cartes et des widgets accessoires interactifs à l'aide de l'authentification d'application.
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 de l'autorisation
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 carte (cardsV2
), ou les deux.
Vous pouvez également inclure les éléments suivants :
- Le champ
accessoryWidgets
permet d'inclure des boutons interactifs en bas du message. - Le champ
privateMessageViewer
permet d'envoyer un message privé à un utilisateur spécifique. - Le champ
messageId
, qui vous permet de nommer le message à utiliser dans d'autres requêtes d'API. - Les champs
thread.threadKey
etmessageReplyOption
pour démarrer un fil de discussion ou y répondre. Si l'espace n'utilise pas le threading, ce champ est ignoré.
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
Python
Java
Apps Script
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 composants interactifs au bas d'un message
Dans le premier exemple de code de ce guide, le message de l'application de chat affiche un bouton cliquable en bas du message, appelé widget accessoire. Les widgets accessoires s'affichent après le texte ou les cartes d'un message. Vous pouvez utiliser ces composants pour inciter les utilisateurs à interagir avec votre message de différentes manières, par exemple :
- Évaluez l'exactitude ou la satisfaction d'un message.
- Signalez un problème concernant le message ou l'application Chat.
- Ouvrez un lien vers du contenu associé, comme de la documentation.
- Ignorer ou mettre en veille des messages similaires de l'application Chat pendant une période spécifique.
Pour ajouter des widgets d'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 des widgets accessoires à un message texte afin que les utilisateurs puissent évaluer leur expérience avec l'application Chat.
L'exemple suivant montre le corps de la requête qui crée un message texte avec deux boutons accessoires. 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 de chat peuvent envoyer des messages privés afin qu'ils ne soient visibles que par un utilisateur spécifique dans 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 les utilisateurs Google Chat.
Pour envoyer un message privé, vous devez omettre les éléments suivants dans votre demande :
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. Avec l'authentification des utilisateurs, le contenu du message ne peut contenir que du texte et doit omettre les fonctionnalités de messagerie qui ne sont disponibles que pour les applications Chat, y compris les interfaces de fiches et les widgets interactifs.
Pour appeler la méthode CreateMessage()
à l'aide de l'authentification de l'utilisateur, vous devez spécifier les champs suivants dans la requête :
- Un champ d'application d'autorisation qui permet 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 champtext
.
Vous pouvez également inclure les éléments suivants :
- Le champ
messageId
, qui vous permet de nommer le message à utiliser dans d'autres requêtes d'API. - Les champs
thread.threadKey
etmessageReplyOption
pour démarrer un fil de discussion ou y répondre. Si l'espace n'utilise pas le threading, ce champ est ignoré.
Le code suivant montre comment une application Chat peut envoyer un message texte dans un espace donné au nom d'un utilisateur authentifié :
Node.js
Python
Java
Apps Script
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 indiquer si un nouveau message doit démarrer un fil de discussion ou répondre à un fil 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 demande :
- 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 lethreadKey
que vous avez créé. Sinon, vous devez utiliser lename
du thread. - Spécifiez le paramètre de requête
messageReplyOption
.
Le code suivant montre comment une application Chat peut envoyer un message qui démarre ou répond à un thread donné identifié par la clé d'un espace donné au nom d'un utilisateur authentifié :
Node.js
Python
Java
Apps Script
Pour exécuter cet exemple, remplacez les éléments suivants :
THREAD_KEY
: clé de discussion existante dans l'espace ou, pour créer une discussion, nom unique pour la discussion.SPACE_NAME
: ID du champname
de l'espace. Vous pouvez obtenir l'ID en appelant la méthodeListSpaces()
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 le nommer en définissant le champ messageId
dans votre requête.
Nommer votre message vous permet de 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 ressource pour spécifier le message à récupérer. Le nom de 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 lorsque vous avez créé le 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, maiscustom-name
ne l'est pas. - 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 texte avec un ID à un espace donné au nom d'un utilisateur authentifié :
Node.js
Python
Java
Apps Script
Pour exécuter cet exemple, remplacez les éléments suivants :
SPACE_NAME
: ID du champname
de l'espace. Vous pouvez obtenir l'ID en appelant la méthodeListSpaces()
ou à partir de l'URL de l'espace.MESSAGE-ID
: nom du message qui commence parcustom-
. Doit être unique par rapport aux autres noms de messages créés par l'application Chat dans l'espace spécifié.
Résoudre les problèmes
Lorsqu'une application ou une fiche Google Chat renvoie une erreur, l'interface Chat affiche le message "Une erreur s'est produite". ou "Impossible de traiter votre demande". Il arrive que l'UI de Chat n'affiche aucun message d'erreur, mais que l'application ou la fiche Chat produise un résultat inattendu (par exemple, un message de fiche peut ne pas s'afficher).
Bien qu'un message d'erreur ne s'affiche pas dans l'interface utilisateur de Chat, des messages d'erreur descriptifs et des données de journaux sont disponibles pour vous aider à corriger les erreurs lorsque la journalisation des erreurs pour les applications Chat est activée. Pour obtenir de l'aide concernant l'affichage, le débogage et la résolution des erreurs, consultez Résoudre les problèmes et corriger les erreurs Google Chat.
Articles associés
- Utilisez Card Builder pour concevoir et prévisualiser les messages de carte JSON pour les applications Chat.
- Mettre en forme des messages
- Obtenir des informations sur un message
- Répertoriez les messages d'un espace.
- Modifier un message
- Supprimer un message
- Identifier des utilisateurs dans les messages Google Chat
- Envoyez des messages à Google Chat avec des webhooks entrants.