Envoyer un message

Ce guide explique les différentes façons dont les applications Google Chat peuvent envoyer des messages messages:

  • Envoyez des messages texte et des cartes en temps réel en répondant à un utilisateur d'interaction.
  • Envoyez des messages texte et des messages de carte de manière asynchrone en appelant la méthode create sur la ressource Message.
  • Démarrez un fil de discussion ou répondez à un message.
  • Envoyez un message et attribuez-lui un nom.

La Ressource Message représente texte ou carte message dans Google Chat. Vous pouvez create, get, update ou delete un message dans l'API Google Chat en appelant méthodes correspondantes. Pour en savoir plus sur les messages texte et les cartes, consultez Présentation des messages Google Chat

La taille maximale des messages (texte ou cartes compris) est de 32 000 octets. Si un message dépasse cette taille, votre application Chat peut envoyer plusieurs messages à la place.

Au lieu d'appeler la méthode create sur la ressource Message de l'API Google Chat pour envoyer un message texte ou une carte de manière asynchrone, Les applications Google Chat peuvent également créer des messages pour répondre aux interactions des utilisateurs dans en temps réel. Les réponses aux interactions des utilisateurs ne nécessitent pas d'authentification et accepter d'autres types de messages, y compris les boîtes de dialogue interactives et les liens des aperçus. Pour en savoir plus, consultez Recevoir des interactions avec l'application Google Chat et y répondre

Prérequis

Node.js

Python

  • Google Workspace ayant accès à Google Chat :
  • Python 3.6 ou version ultérieure
  • La fonction pip outil de gestion des packages

  • Les dernières bibliothèques clientes Google pour Python. 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
  • Un projet Google Cloud dans lequel l'API Google Chat est activée et configurée Pour connaître la procédure à suivre, consultez Créer une application Google Chat

  • Autorisation configurée pour que l'application Chat envoie les messages asynchrones. Aucune configuration d'autorisation n'est requise messages en temps réel.

Apps Script ;

Envoyer des SMS

Cette section explique comment envoyer des messages de deux manières différentes:

  • Envoyez un message en temps réel en répondant à une interaction de l'utilisateur.
  • Envoyez un message en appelant l'API Google Chat de manière asynchrone.

Envoyer un message en temps réel

Dans cet exemple, votre application Chat crée et envoie un SMS chaque fois qu'il est ajouté à un espace. Pour en savoir plus sur les meilleures pratiques pour l'intégration des utilisateurs, consultez Aidez les utilisateurs et les espaces à démarrer grâce à un processus d'intégration utile.

Pour envoyer un message lorsqu'un utilisateur ajoute votre application Chat à un espace, votre application Chat répond à un ADDED_TO_SPACE événement d'interaction. Pour répondre à ADDED_TO_SPACE avec un message, utilisez le code suivant:

Node.js

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app. An onboarding message that
 * introduces the app and helps people get started with it.
 */
exports.onMessage = function onMessage(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send(
      'Hello! This function is meant to be used in a Google Chat space.');
  }

  // Send an onboarding message when added to a Chat space
  if (req.body.type === 'ADDED_TO_SPACE') {
    res.json({
      'text': 'Hi, Cymbal at your service. I help you manage your calendar
      from Google Chat. Take a look at your schedule today by typing
      `/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To
      learn what else I can do, type `/help`.'
    });
  }
};

Apps Script ;

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app. An onboarding message that
 * introduces the app and helps people get started with it.
 */
function onAddToSpace(event) {

  return {
    'text': 'Hi, Cymbal at your service. I help you manage your calendar
    from Google Chat. Take a look at your schedule today by typing
    `/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn
    what else I can do, type `/help`.'
  }
}

L'exemple de code renvoie le message texte suivant:

Exemple de message d'accueil.

Envoyer un SMS de manière asynchrone

La section suivante explique comment envoyer un SMS de manière asynchrone avec l'authentification des applications et l'authentification des utilisateurs.

Pour envoyer un SMS, transmettez les éléments suivants dans votre requête:

  • Avec l'authentification de l'application, spécifiez le champ d'application de l'autorisation chat.bot. Avec l'authentification de l'utilisateur, spécifiez le champ d'application de l'autorisation chat.messages.create.
  • Appelez la méthode Méthode create le Ressource Message.

Envoyer un SMS avec l'authentification par application

Pour envoyer un SMS avec authentification de l'application:

Python

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

  2. Ajoutez le code suivant dans chat_create_text_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)

# Create a Chat message.
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',

    # The message to create.
    body={'text': 'Hello, world!'}

).execute()

print(result)

  3. Dans le code, remplacez SPACE par un nom d'espace, ce qui que vous pouvez obtenir Méthode spaces.list() dans l'API Chat ou depuis l'URL d'un espace.

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

    python3 chat_create_text_message_app.py

L'API Chat renvoie une instance de Message qui détaille le message envoyé.

Envoyer un SMS avec authentification de l'utilisateur

Pour envoyer un SMS avec authentification de l'utilisateur:

Python

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

  2. Ajoutez le code suivant dans chat_create_text_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',

        # The message to create.
        body={'text': 'Hello, world!'}

    ).execute()

    # Prints details about the created message.
    print(result)

if __name__ == '__main__':
    main()

  3. Dans le code, remplacez SPACE par un nom d'espace, ce qui que vous pouvez obtenir la méthode spaces.list() dans la l'API Chat ou l'URL d'un espace.

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

    python3 chat_create_text_message_user.py

L'API Chat renvoie une instance de Message qui détaille le message envoyé.

Envoyer des messages de cartes

Cette section décrit comment envoyer des messages de fiches de deux manières:

  • Envoyez un message sous forme de fiche en temps réel en répondant à une interaction de l'utilisateur.
  • Envoyez un message sous forme de fiche en appelant l'API Google Chat de manière asynchrone.

Envoyer un message de carte en temps réel

Les applications de chat peuvent créer des messages sous forme de fiches pour répondre à un utilisateur interaction (par exemple, lorsqu'un utilisateur envoie à l'application Chat un ou ajoute l'application Chat à un espace. Pour en savoir plus sur les réponses aux interactions des utilisateurs, consultez la section Recevoir des réponses et y répondre Interaction avec l'application Chat événements.

Dans cet exemple, un utilisateur envoie un message à une application Chat. et l'application Chat répond en envoyant un message sous forme de fiche qui affiche le nom et l'avatar de l'utilisateur:

Une application Chat qui répond par une fiche présentant le nom à afficher et l'avatar de l'expéditeur l'image.

Node.js

node/avatar-app/index.js
/**
 * Google Cloud Function that responds to messages sent from a
 * Google Chat room.
 *
 * @param {Object} req Request sent from Google Chat room
 * @param {Object} res Response to send back
 */
exports.helloChat = function helloChat(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send('Hello! This function is meant to be used in a Google Chat '  
      'Room.');
  }

  const sender = req.body.message.sender.displayName;
  const image = req.body.message.sender.avatarUrl;

  const data = createMessage(sender, image);

  res.send(data);
};

/**
 * Creates a card with two widgets.
 * @param {string} displayName the sender's display name
 * @param {string} imageUrl the URL for the sender's avatar
 * @return {Object} a card with the user's avatar.
 */
function createMessage(displayName, imageUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`,
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '},
  };

  const avatarImageWidget = {
    image: {imageUrl},
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget,
    ],
  };

  return {
    text: 'Here\'s your avatar',
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

Python

python/avatar-app/main.py
from typing import Any, Mapping

import flask
import functions_framework


# Google Cloud Function that responds to messages sent in
# Google Chat.
#
# @param {Object} req Request sent from Google Chat.
# @param {Object} res Response to send back.
@functions_framework.http
def hello_chat(req: flask.Request) -> Mapping[str, Any]:
  if req.method == "GET":
    return "Hello! This function must be called from Google Chat."

  request_json = req.get_json(silent=True)

  display_name = request_json["message"]["sender"]["displayName"]
  avatar = request_json["message"]["sender"]["avatarUrl"]

  response = create_message(name=display_name, image_url=avatar)

  return response


# Creates a card with two widgets.
# @param {string} name the sender's display name.
# @param {string} image_url the URL for the sender's avatar.
# @return {Object} a card with the user's avatar.
def create_message(name: str, image_url: str) -> Mapping[str, Any]:
  avatar_image_widget = {"image": {"imageUrl": image_url}}
  avatar_text_widget = {"textParagraph": {"text": "Your avatar picture:"}}
  avatar_section = {"widgets": [avatar_text_widget, avatar_image_widget]}

  header = {"title": f"Hello {name}!"}

  cards = {
      "text": "Here's your avatar",
      "cardsV2": [
          {
              "cardId": "avatarCard",
              "card": {
                  "name": "Avatar Card",
                  "header": header,
                  "sections": [avatar_section],
              },
          }
      ]
  }

  return cards

Apps Script ;

Cet exemple envoie un message de carte en renvoyant fichier JSON de la carte. Vous pouvez également utiliser Service de fiches Apps Script.

apps-script/avatar-app/hello-chat.gs
/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {
  const displayName = event.message.sender.displayName;
  const avatarUrl = event.message.sender.avatarUrl;

  return createMessage(displayName, avatarUrl);
}

/**
 * Creates a card with two widgets.
 * @param {string} displayName the sender's display name
 * @param {string} avatarUrl the URL for the sender's avatar
 * @return {Object} a card with the sender's avatar.
 */
function createMessage(displayName, avatarUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '}
  };

  const avatarImageWidget = {
    image: {imageUrl: avatarUrl}
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget
    ],
  };

  return {
    text: 'Here\'s your avatar',
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

Envoyer un message de fiche de manière asynchrone

Pour envoyer un message sous forme de fiche, transmettez les éléments suivants dans votre requête:

  • Avec l'authentification de l'application, spécifiez le champ d'application de l'autorisation chat.bot. Vous ne pouvez pas d'envoyer un message sous forme de carte avec authentification de l'utilisateur.
  • Appelez la méthode Méthode create le Ressource Message.

Voici un exemple de message de fiche:

Message sous forme de fiche envoyé avec l'API Chat.

Voici comment envoyer un message sous forme de carte avec l'authentification d'application:

Python

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

  2. Ajoutez le code suivant dans chat_create_card_message.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)

# Create a Chat message.
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',

    # The message to create.
    body=
    {
      'cardsV2': [{
        'cardId': 'createCardMessage',
        'card': {
          'header': {
            'title': 'A card message!',
            'subtitle': 'Created with the Chat API',
            'imageUrl': 'https://developers.google.com/chat/images/chat-product-icon.png',
            'imageType': 'CIRCLE'
          },
          'sections': [
            {
              'widgets': [
                {
                  'buttonList': {
                    'buttons': [
                      {
                        'text': 'Read the docs!',
                        'onClick': {
                          'openLink': {
                            'url': 'https://developers.google.com/chat'
                          }
                        }
                      }
                    ]
                  }
                }
              ]
            }
          ]
        }
      }]
    }

).execute()

print(result)

  3. Dans le code, remplacez SPACE par un nom d'espace, ce qui que vous pouvez obtenir Méthode spaces.list dans l'API Chat ou depuis l'URL d'un espace.

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

    python3 chat_create_card_message.py

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

Pour démarrer une conversation, envoyez un message et quittez thread.name empty; Google Chat les renseigne lorsque vous créez le fil de discussion. Éventuellement, pour personnaliser le nom du thread, spécifier thread.threadKey .

Pour répondre à un fil de discussion, envoyez un message précisant Champ threadKey ou name. Si le fil de discussion a été créé par une personne ou un autre Application Chat, vous devez utiliser le champ thread.name.

Si aucun fil de discussion correspondant n'est trouvé, vous pouvez spécifier si un message doit démarrer un nouveau fil de discussion ou s'il ne peut pas être publié en définissant messageReplyOption .

Si messageReplyOption est défini, vous devez également définir thread.name ou thread.threadKey.

Voici comment démarrer un fil de discussion ou y répondre avec le champ threadKey défini comme nameOfThread:

Python

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

  2. Ajoutez le code suivant dans chat_create_message_thread.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)

# Create a Chat message.
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',

    # Whether to start a thread or reply to an existing one.
    #
    # Required when threading is enabled in a space unless starting a
    # thread.  Ignored in other space types. Threading is enabled when
    # space.spaceThreadingState is THREADED_MESSAGES.
    #
    # REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD replies to an existing thread
    # if one exists, otherwise it starts a new one.
    messageReplyOption='REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD',

    # The message body.
    body={

        # The message to create.
        'text': 'Start or reply to another message in a thread!',

        # The thread to start or reply to.
        'thread': {
            'threadKey': 'nameOfThread'
        }
    }

).execute()

print(result)

  3. Dans le code, remplacez SPACE par un nom d'espace, ce qui que vous pouvez obtenir Méthode spaces.list dans l'API Chat ou depuis l'URL d'un espace.

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

    python3 chat_create_message_thread.py

L'API Chat renvoie une instance de Message qui détaille le message envoyé.

Attribuer un nom à un message

Cette section explique comment nommer un message en définissant un ID personnalisé pour le . Vous pouvez utiliser des ID personnalisés pour obtenir, mettre à jour ou supprimer des messages. ID personnalisés vous permettent de spécifier un message sans avoir à stocker l'ID attribué par le système le nom de ressource du message (représenté dans le champ name) ; La ressource est généré dans le corps de la réponse lorsque vous créez le message.

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'identifiant attribué par le système. Si vous avez attribué un nom au message, vous pouvez remplacer la valeur de {message} par l'ID personnalisé.

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.

Pour envoyer un message avec un ID personnalisé:

Python

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

  2. Ajoutez le code suivant dans chat_create_named_message.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)

# Create a Chat message with a custom name.
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',

    # Custom name for the message used to facilitate later operations.
    messageId='client-NAME',

    # The message to create.
    body={'text': 'Hello, world!'}

).execute()

print(result)

  3. Dans le code, remplacez les éléments suivants:

    • SPACE: ID de l'espace dans lequel vous souhaitez publiez le message. Vous pouvez l'obtenir Méthode spaces.list dans l'API Chat ou depuis l'URL d'un espace.
    • NAME: nom personnalisé du message

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

    python3 chat_create_named_message.py

L'API Chat renvoie une instance de Message

Ajouter des widgets interactifs au bas d'un message

Vous avez la possibilité d'ajouter des widgets accessoires aux messages. Les widgets accessoires s'affichent après le texte ou les cartes dans un message. Vous pouvez utiliser ces des widgets pour inviter les utilisateurs à interagir avec votre message de différentes manières, notamment : les éléments suivants:

  • Évaluez l'exactitude ou la satisfaction d'un message.
  • Signalez un problème concernant le message ou l'application Chat.
  • Ouvrez un lien vers un contenu associé, tel que 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 message et spécifiez un ou plusieurs AccessoryWidgets que vous souhaitez inclure. Le message doit être visible par tous les membres de l'espace (Vous ne pouvez pas ajouter de widgets accessoires aux messages privés.)

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.

Exemples de widgets d'accessoires

L'exemple de code suivant montre le code JSON de ce message. Lorsqu'un utilisateur clique sur l'un des boutons, l'interaction déclenche la fonction correspondante (par exemple, doUpvote) qui traite la note.


 "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 des messages en mode privé

Les applications de chat peuvent envoyer des messages texte et des cartes en privé, afin que le message n'est visible que par un seul utilisateur de l'espace. Pour envoyer un message en mode privé, spécifiez le champ privateMessageViewer dans le message. Uniquement Les applications de chat peuvent envoyer des messages privés. Pour envoyer un message privé : de manière asynchrone, vous devez utiliser l'authentification d'application.

Pour en savoir plus, consultez Envoyer des messages privés à Google Chat utilisateurs.

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