Envoyer un message

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

  • Envoyez des messages texte et des messages sous forme de fiches en temps réel en répondant à une interaction utilisateur.
  • 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-y.
  • Envoyez un message et attribuez-lui un nom.

La ressource Message représente un message texte ou fiche dans Google Chat. Vous pouvez create, get, update ou delete un message dans l'API Google Chat en appelant les méthodes correspondantes. Pour en savoir plus sur les messages texte et ceux sous forme de fiches, consultez Présentation des messages Google Chat.

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

Conditions préalables

Node.js

Python

  • Python 3.6 ou version ultérieure
  • L'outil de gestion des packages pip

  • 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-httplib2 google-auth-oauthlib oauth2client

  • Une application Chat publiée. Pour créer et publier une application Chat, consultez Créer une application Google Chat.

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

Apps Script ;

Envoyer des SMS

Cette section décrit les deux manières suivantes d'envoyer des SMS:

  • 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 message chaque fois qu'elle est ajoutée à un espace. Pour en savoir plus sur les bonnes pratiques d'intégration des utilisateurs, consultez Premiers pas avec les utilisateurs et les espaces grâce à l'intégration utile.

Pour envoyer un message lorsqu'un utilisateur ajoute votre application Chat à un espace, celle-ci répond à un événement d'interaction ADDED_TO_SPACE. Pour répondre à des événements d'interaction ADDED_TO_SPACE par 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'intégration.

Envoyer un message de manière asynchrone

La section suivante explique comment envoyer un message texte de manière asynchrone avec l'authentification de l'application et de l'utilisateur.

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

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

Envoyer un SMS avec l'authentification de l'application

Voici comment envoyer un SMS via l'authentification de l'application:

Python

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

  2. Incluez le code suivant dans chat_create_text_message_app.py:

    from httplib2 import Http
from oauth2client.service_account import ServiceAccountCredentials
from apiclient.discovery import build

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
    'credentials.json', SCOPES)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))

# 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 le nom d'un espace, que vous pouvez obtenir à partir de la méthode spaces.list() de l'API Chat ou de 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

Voici comment envoyer un SMS via l'authentification de l'utilisateur:

Python

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

  2. Incluez 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 membership.
    print(result)

if __name__ == '__main__':
    main()

  3. Dans le code, remplacez SPACE par un nom d'espace, que vous pouvez obtenir à partir de la méthode spaces.list() de l'API Chat ou de 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 liés aux cartes

Cette section explique comment envoyer des messages liés à une carte de deux manières:

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

Envoyez un message avec une carte en temps réel

Les applications Chat peuvent créer des fiches pour répondre à une interaction utilisateur (par exemple, lorsqu'un utilisateur envoie un message à l'application Chat ou ajoute l'application Chat à un espace). Pour savoir comment répondre aux interactions utilisateur, consultez Recevoir des événements d'interaction avec l'application Chat et y répondre.

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

Application Chat répondant par une carte sur laquelle figurent le nom à afficher et l'avatar de l'expéditeur

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 ;

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 avec une carte de manière asynchrone

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

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

Voici un exemple de message de carte:

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

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

Python

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

  2. Incluez le code suivant dans chat_create_card_message.py:

    from httplib2 import Http
from oauth2client.service_account import ServiceAccountCredentials
from apiclient.discovery import build

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
    'credentials.json', SCOPES)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))

# 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 le nom d'un espace, que vous pouvez obtenir à partir de la méthode spaces.list de l'API Chat ou de 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 une conversation ou y répondre

Pour démarrer un fil de discussion, envoyez un message et laissez le champ thread.name vide. Google Chat le renseignera lors de la création du fil de discussion. Si vous souhaitez personnaliser le nom du thread, spécifiez le champ thread.threadKey.

Pour répondre à un fil de discussion, envoyez un message spécifiant le champ threadKey ou name du fil de discussion. Si le fil de discussion a été créé par une personne ou une 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 ne pas être publié en définissant le champ messageReplyOption.

Voici comment démarrer un thread ou y répondre avec le champ threadKey défini sur nameOfThread:

Python

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

  2. Incluez le code suivant dans chat_create_message_thread.py:

    from httplib2 import Http
from oauth2client.service_account import ServiceAccountCredentials
from apiclient.discovery import build

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
    'credentials.json', SCOPES)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))

# 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 le nom d'un espace, que vous pouvez obtenir à partir de la méthode spaces.list de l'API Chat ou de 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é.

Envoyer un message et lui attribuer un nom

Cette section explique comment envoyer un message avec un nom personnalisé. Les noms des messages vous permettent de obtenir, de mettre à jour ou de supprimer des messages. L'attribution d'un nom personnalisé permet également à une application Chat de rappeler le message sans enregistrer le message name à partir du corps de la réponse renvoyé lors de son envoi.

L'attribution d'un nom personnalisé ne remplace pas le champ name généré, qui est le nom de ressource du message. Au lieu de cela, il définit le nom personnalisé en tant que champ clientAssignedMessageId, auquel vous pouvez faire référence lors du traitement des opérations ultérieures, telles que la mise à jour ou la suppression du message.

Les noms personnalisés doivent respecter les exigences suivantes:

  • Commencez par client-. Par exemple, client-custom-name est un nom personnalisé valide, mais pas custom-name.
  • Le nom ne doit contenir que des lettres minuscules, des chiffres et des traits d'union.
  • Ne pas dépasser 63 caractères
  • Si vous spécifiez un nom personnalisé utilisé lors de l'envoi d'un message, une erreur est renvoyée, mais d'autres méthodes telles que update et delete fonctionnent comme prévu.

Pour envoyer un message et lui attribuer un nom, procédez comme suit:

Python

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

  2. Incluez le code suivant dans chat_create_named_message.py:

    from httplib2 import Http
from oauth2client.service_account import ServiceAccountCredentials
from apiclient.discovery import build

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
    'credentials.json', SCOPES)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))

# 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-custom-name',

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

).execute()

print(result)

  3. Dans le code, remplacez SPACE par le nom d'un espace, que vous pouvez obtenir à partir de la méthode spaces.list de l'API Chat ou de l'URL d'un espace.

  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 qui détaille le message envoyé.

Dépannage

Lorsqu'une application ou une fiche Google Chat renvoie une erreur, l'interface Chat affiche un message indiquant "Un problème est survenu" ou "Impossible de traiter votre demande". Parfois, l'interface Chat n'affiche aucun message d'erreur, mais l'application ou la carte Chat produit un résultat inattendu, par exemple un message de fiche n'apparaît pas.

Il est possible qu'aucun message d'erreur ne s'affiche dans l'interface utilisateur Chat. Toutefois, des messages d'erreur descriptifs et des données de journal 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 correction des erreurs, consultez Résoudre les problèmes liés aux erreurs Google Chat.