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

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">
</ph> Appel de la méthode messages.create() avec l&#39;authentification de l&#39;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 au nom de l'utilisateur. Chat attribue également Application de chat au message en affichant son nom

<ph type="x-smartling-placeholder">
</ph> Appel de la méthode messages.create() avec authentification de l&#39;utilisateur
Figure 2: Avec l'authentification de l'utilisateur, celui-ci envoie le message et Chat affiche la 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 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

  • Python 3.6 ou version ultérieure
  • L'outil de gestion de packages pip
  • Les dernières bibliothèques clientes Google Pour les installer ou les mettre à jour, exécutez la commande suivante dans votre interface de ligne de commande: 
    pip3 install --upgrade google-api-python-client google-auth-oauthlib

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

Message envoyé avec authentification de l&#39;utilisateur
Figure 3. Une application Chat envoie un SMS sur pour le compte d'un utilisateur.

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ètre text .

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

Pour envoyer un SMS au nom d'un utilisateur, procédez comme suit:

Python

  1. Dans votre répertoire de travail, créez un fichier nommé chat_create_message_user.py

  2. 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'espace name . Pour obtenir cet identifiant, appelez la méthode Méthode spaces.list() ou depuis l'URL de l'espace.

  3. Dans votre répertoire de travail, créez et exécutez l'exemple:

    python3 chat_create_message_user.py

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

Message envoyé avec l&#39;authentification de l&#39;application
Figure 4. Une application Chat envoie un message avec du texte, une carte et un bouton d'accessoire.

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:

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

  1. Dans votre répertoire de travail, créez un fichier nommé chat_create_message_app.py

  2. 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'espace name . Pour obtenir cet identifiant, appelez la méthode Méthode spaces.list() ou depuis l'URL de l'espace.

  3. 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">
</ph> Widget accessoire
Figure 5: Message de l'application Chat avec les widgets de texte et accessoires.

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 le threadKey que vous avez créé. Sinon, vous devez utiliser la méthode name 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 pas custom-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