Ce guide explique comment appeler l'API Google Chat
messages.create()
pour effectuer l'une des opérations suivantes:
- Envoyez des messages contenant du texte, des cartes et des widgets interactifs.
- Envoyez des messages en mode privé à un utilisateur Chat spécifique.
- Démarrez un fil de discussion ou répondez à un message.
- Nommez un message de façon à pouvoir le spécifier dans d'autres API Chat requêtes.
<ph type="x-smartling-placeholder">
En plus d'appeler la méthode messages.create()
, les applications Chat
peuvent créer et envoyer des messages pour répondre aux interactions des utilisateurs, comme publier un
message de bienvenue une fois qu'un utilisateur a ajouté l'application Chat à un
l'espace de stockage. Lorsqu'elles répondent aux interactions, les applications Chat peuvent utiliser d'autres
Types de fonctionnalités de messagerie, y compris les boîtes de dialogue interactives et l'aperçu des liens
de commande. Pour répondre à un utilisateur, l'application Chat renvoie
le message de manière synchrone, sans appeler l'API Chat. Pour apprendre
sur l'envoi de messages pour répondre à des interactions, consultez
Recevoir des interactions avec l'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 messages.create()
à l'aide de
authentification des applications
et l'authentification des utilisateurs.
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.
<ph type="x-smartling-placeholder">App
à côté de son nom.Lorsque vous vous authentifiez en tant qu'utilisateur, l'application Chat envoie le au nom de l'utilisateur. Chat attribue également Application de chat au message en affichant son nom.
<ph type="x-smartling-placeholder">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 de 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 peuvent uniquement envoyer du texte dans leurs messages, vous pouvez n'inclure du texte que lors de la création de messages à l'aide de l'authentification de l'utilisateur. Pour en savoir plus sur la messagerie disponibles pour l'API Chat, consultez la 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
Python
- Une entreprise Un compte Google Workspace ayant accès à Google Chat :
- Configurez votre environnement:
<ph type="x-smartling-placeholder">
- </ph>
- Créez un projet Google Cloud.
- Configurer l'écran de consentement OAuth
- activer et configurer l'API Google Chat à l'aide d'un nom ; et la description de votre application Chat.
- Installez la Python Bibliothèque cliente des API Google.
- Créez des identifiants d'accès en fonction de la manière dont vous souhaitez vous authentifier dans votre API Google Chat.
requête:
<ph type="x-smartling-placeholder">
- </ph>
- Pour vous authentifier en tant
qu'utilisateur de Chat,
créer un ID client OAuth
identifiants et enregistrez-les dans un fichier JSON nommé
client_secrets.json
dans votre répertoire local. - Pour vous authentifier en tant qu'application Chat,
créer un compte de service
identifiants et enregistrez-les dans un fichier JSON nommé
credentials.json
- Pour vous authentifier en tant
qu'utilisateur de Chat,
créer un ID client OAuth
identifiants et enregistrez-les dans un fichier JSON nommé
- <ph type="x-smartling-placeholder"></ph> Choisissez un champ d'application d'autorisation selon que vous souhaitez vous authentifier en tant qu'utilisateur Application Chat
- Un espace Google Chat dans lequel l'utilisateur authentifié ou l'application Chat appelant est membre. Pour s'authentifier en tant que l'application de chat, ajoutez l'icône Chat avec l'espace
Envoyer un SMS au nom d'un utilisateur
Cette section explique comment envoyer des messages au nom d'un utilisateur en utilisant authentification des utilisateurs. Avec l'authentification de l'utilisateur, le contenu du message ne peut contenir que du texte et doit omettre les fonctionnalités de messagerie qui ne sont disponibles Applications de chat, y compris les interfaces de fiches et les widgets interactifs
Pour appeler messages.create()
à l'aide de l'authentification de l'utilisateur, vous devez spécifier le
les champs suivants dans la requête:
- Un champ d'application de l'autorisation
qui prend en charge l'authentification
de l'utilisateur pour cette méthode. L'exemple suivant utilise
le champ d'application
chat.messages.create
. - La ressource
Space
dans laquelle où vous voulez publier le message. L'utilisateur authentifié doit être membre du l'espace de stockage. Message
ressource à créer. Pour définir le contenu du message, vous devez inclure le paramètretext
.
Vous pouvez également inclure les éléments suivants:
- Le champ
messageId
, qui vous permet Nommez le message à utiliser dans d'autres requêtes API. - Les champs
thread.threadKey
etmessageReplyOption
pour créer un fil de discussion ou y répondre. Si l’espace ne utilisez le threading, ce champ est ignoré.
Pour envoyer un SMS au nom d'un utilisateur, procédez comme suit:
Python
- Dans votre répertoire de travail, créez un fichier nommé
chat_create_message_user.py
Ajoutez le code suivant dans
chat_create_message_user.py
:import os.path from google.auth.transport.requests import Request from google.oauth2.credentials import Credentials from google_auth_oauthlib.flow import InstalledAppFlow from googleapiclient.discovery import build from googleapiclient.errors import HttpError # Define your app's authorization scopes. # When modifying these scopes, delete the file token.json, if it exists. SCOPES = ["https://www.googleapis.com/auth/chat.messages.create"] def main(): ''' Authenticates with Chat API via user credentials, then creates a text message in a Chat space. ''' # Start with no credentials. creds = None # Authenticate with Google Workspace # and get user authorization. flow = InstalledAppFlow.from_client_secrets_file( 'client_secrets.json', SCOPES) creds = flow.run_local_server() # Build a service endpoint for Chat API. chat = build('chat', 'v1', credentials=creds) # Use the service endpoint to call Chat API. result = chat.spaces().messages().create( # The space to create the message in. # # Replace SPACE with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. parent='spaces/SPACE', # Optional. Sets custom ID for the message to use in other requests. messageId='client-myfirstusermessage', # The text message to create. body={ 'text': '👋 🌎Hello world! Text messages can contain things like:\n\n' + '* Hyperlinks 🔗\n' + '* Emojis 😄🎉\n' + '* Mentions of other Chat users `@` \n\n' 'For details, see the <https://developers.google.com/workspace/chat/format-messages|Chat API developer documentation>.' } ).execute() # Prints details about the created message. print(result) if __name__ == '__main__': main()
Remplacez
SPACE
par l'ID de l'espacename
. Pour obtenir cet identifiant, appelez la méthode Méthodespaces.list()
ou depuis l'URL de l'espace.Dans votre répertoire de travail, créez et exécutez l'exemple:
python3 chat_create_message_user.py
Si vous y êtes invité, ouvrez l'URL pour autoriser le Application de chat en fonction du champ d'application que vous avez utilisé dans votre requête.
L'application Chat crée le message, et l'objet authentifié
l'utilisateur publie le message dans l'espace. Dans votre interface de ligne de commande,
L'API Chat renvoie l'instance de la nouvelle
Message
.
Envoyer un message depuis l'application Chat
Cette section explique comment envoyer des messages contenant du texte, des cartes et des widgets accessoires interactifs avec authentification des applications.
Pour appeler messages.create()
à l'aide de l'authentification de l'application, vous devez spécifier le
les champs suivants dans la requête:
- Le champ d'application de l'autorisation
chat.bot
. - La ressource
Space
dans laquelle où vous voulez publier le message. L'application Chat doit être un membre de l'espace. Message
ressource à créer. Pour définir le contenu du message, vous pouvez inclure texte enrichi (text
), une ou plusieurs interfaces de carte (cardsV2
), ou les deux.
Vous pouvez également inclure les éléments suivants:
- Le champ
accessoryWidgets
à inclure boutons interactifs au bas du message. - Le champ
privateMessageViewer
pour envoyer le message en mode privé à un utilisateur donné. - Le champ
messageId
, qui vous permet Nommez le message à utiliser dans d'autres requêtes API. - Les champs
thread.threadKey
etmessageReplyOption
pour créer un fil de discussion ou y répondre. Si l’espace ne utilisez le threading, ce champ est ignoré.
La taille maximale des messages (texte ou cartes compris) est de 32 000 octets. Pour envoyer un message qui dépasse cette taille, votre application Chat doit envoyer plusieurs messages à la place.
Pour envoyer un message publié via l'application Chat contenant une fiche et un bouton cliquable au bas du message, procédez comme suit:
Python
- Dans votre répertoire de travail, créez un fichier nommé
chat_create_message_app.py
Ajoutez le code suivant dans
chat_create_message_app.py
:from apiclient.discovery import build from google.oauth2 import service_account # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = service_account.Credentials.from_service_account_file( 'credentials.json', scopes=SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # Specify the Chat space where the message is posted. Obtain the ID # from the resource name, or from the space's URL. SPACE = 'spaces/SPACE' # Create a Chat message. result = chat.spaces().messages().create( # The Chat space. parent=SPACE, # Optional. Sets custom ID for the message to use in other requests. messageId='client-myfirstappmessage', # The message to create with text, a card, and a button at the # bottom of the message. body= { 'text': '👋 🌎Hello world! I created this message by calling the Chat API\'s `messages.create()` method.', 'cardsV2': [{ 'cardId': 'myCardId', 'card': { 'header': { 'title': 'About this message', 'imageUrl': 'https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg', 'imageType': 'CIRCLE' }, "sections": [ { "header": "Contents", "widgets": [ { "textParagraph": { "text": "🔡 <b>Text</b> which can include hyperlinks 🔗, emojis 😄🎉, and @mentions 🗣️." }}, { "textParagraph": { "text": "🖼️ A <b>card</b> to display visual elements and request information such as text 🔤, dates and times 📅, and selections ☑️." }}, { "textParagraph": { "text": "👉🔘 An <b>accessory widget</b> which adds a button to the bottom of a message." }}, ] }, { "header": "What's next", "collapsible": True, "widgets": [ { "textParagraph": { "text": "❤️ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages.reactions/create'>Add a reaction</a>." }}, { "textParagraph": { "text": "🔄 <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/patch'>Update</a> or ❌ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/delete'>delete</a> the message." }}, { "textParagraph": { "text": '💡 <b>Pro tip</b>: To specify the message in other API requests, use its custom name: <i>' + SPACE + '/messages/client-myfirstappmessage</i>.' }} ] } ]} }], "accessoryWidgets": [ { "buttonList": { "buttons": [ { "text": "View documentation", "altText": "Opens a new browser tab and navigates to the Google Chat developer documentation website.", "icon": { "material_icon": { "name": "link" } }, "onClick": { "openLink": { "url": "https://developers.google.com/workspace/chat/create-messages" } } } ] } } ] } ).execute() print(result)
Remplacez
SPACE
par l'ID de l'espacename
. Pour obtenir cet identifiant, appelez la méthode Méthodespaces.list()
ou depuis l'URL de l'espace.Dans votre répertoire de travail, créez et exécutez l'exemple:
python3 chat_create_message_app.py
L'application Chat crée et publie le message
l'espace de stockage. Dans votre interface de ligne de commande, l'API Chat renvoie le
de la nouvelle instance
Message
.
Ajouter des widgets interactifs au bas d'un message
Dans l'exemple de code de la section précédente, Le message de l'application Chat affiche un bouton cliquable en bas du message. C'est ce que l'on appelle un widget accessoire. Widgets d'accessoires s'affichent après le texte ou les cartes d'un message. Vous pouvez utiliser ces widgets aux utilisateurs d'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 le contenu associé, par exemple la documentation.
- Ignorer ou mettre en attente des messages similaires dans l'application Chat pendant une période donnée.
Pour ajouter des widgets accessoires, incluez le
accessoryWidgets[]
dans le corps de votre requête et spécifiez un ou plusieurs widgets
à inclure.
L'image suivante montre une application Chat qui ajoute Un message texte avec des widgets accessoires afin que les utilisateurs puissent évaluer leur expérience avec l'application Chat.
<ph type="x-smartling-placeholder">![Widget accessoire](https://developers-dot-devsite-v2-prod.appspot.com/static/workspace/chat/images/message-accessory-widgets-reference.png?authuser=4&hl=fr)
Voici le corps de la requête qui crée un message texte avec
deux boutons d'accessoires. Lorsqu'un utilisateur clique sur un bouton,
(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 en mode privé
Les applications de chat peuvent envoyer des messages en mode privé afin que le message n'est visible que par un utilisateur spécifique de l'espace. Lorsqu'un L'application Chat envoie un message privé, le message affiche un libellé indiquant à l'utilisateur que le message est lui seul visible.
Pour envoyer un message en mode privé à l'aide de l'API Chat, spécifiez le paramètre
privateMessageViewer
dans le corps de votre requête. Pour spécifier l'utilisateur, vous définissez la valeur sur
la ressource User
qui
représente l'utilisateur Chat. Vous pouvez également utiliser
Champ name
de
User
, comme illustré dans l'exemple suivant:
{
"text": "Hello private world!",
"privateMessageViewer": {
"name": "users/USER_ID"
}
}
Remplacer USER_ID
avec un identifiant unique pour l'utilisateur, tel que 12345678987654321
ou
hao@cymbalgroup.com
Pour en savoir plus sur la spécification des utilisateurs, consultez
Identifiez et spécifiez les utilisateurs de Google Chat.
Pour envoyer un message en mode privé, vous devez omettre les éléments suivants dans votre demande:
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 génèrent une nouvelle thread. Pour vous aider à identifier le fil de discussion et à y répondre plus tard, vous pouvez spécifier un dans votre requête:
- Dans le corps de votre requête, spécifiez la
thread.threadKey
. - Spécifier 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 elle est définie, vous pouvez spécifiez lethreadKey
que vous avez créé. Sinon, vous devez utiliser la méthodename
du fil de discussion. - Spécifiez le paramètre de requête
messageReplyOption
.
Le code JSON suivant montre un exemple de corps de requête pour un message texte qui
démarre un fil de discussion avec la clé helloWorldThread
ou y répond:
{
'thread': {
'threadKey': 'helloWorldThread',
},
'text': '👋 🌎Hello world!'
}
Attribuer un nom à 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 messages.create()
.
L'attribution d'un nom à votre message vous permet de le préciser sans avoir à stocker la
attribué par le système à partir du nom de ressource du message (représenté dans le
name
).
Par exemple, pour récupérer un message à l'aide de la méthode get()
, vous devez utiliser
nom de 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
.
Pour nommer un message, indiquez un ID personnalisé dans le champ
messageId
lorsque vous créez le message. Le champ messageId
définit la valeur du paramètre
clientAssignedMessageId
de la ressource Message
.
Vous ne pouvez nommer un message qu'au moment de sa création. Vous ne pouvez pas nommer ou modifier un ID personnalisé pour les messages existants. L'ID personnalisé doit respecter les critères suivants : configuration requise:
- Commence par
client-
. Par exemple,client-custom-name
est une valeur personnalisée valide ID, mais pascustom-name
. - Il peut contenir jusqu'à 63 caractères, et uniquement des lettres minuscules, des chiffres et et des traits d'union.
- est unique dans un espace ; Une application Chat ne peut pas utiliser les le même ID personnalisé pour différents messages.
Résoudre les problèmes
Lorsqu'une application ou card renvoie une erreur, la L'interface Chat affiche le message "Une erreur s'est produite". ou "Impossible de traiter votre demande." Parfois, l'interface utilisateur de Chat n'affiche aucun message d'erreur, mais que l'application ou la carte produit un résultat inattendu. Par exemple, un message de fiche peut ne pas s'affichent.
Même s'il est possible qu'aucun message d'erreur ne s'affiche 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 est activée pour les applications Chat. Pour obtenir de l'aide, le débogage et la correction des erreurs, consultez Résoudre les problèmes liés à Google Chat
Articles associés
- Utiliser Card Builder pour : Concevoir et prévisualiser des messages de fiches JSON pour les applications Chat
- Mettre en forme des messages
- En savoir plus sur un message
- Lister les messages d'un espace
- Modifier un message
- Supprimer un message
- Identifiez les utilisateurs dans les messages Google Chat.
- Envoyer des messages à Google Chat avec des webhooks entrants