Envoyer des messages privés aux utilisateurs de Google Chat

Cette page explique comment créer et envoyer des messages privés en tant qu'application Google Chat.

Un message privé est un message d'application Chat visible uniquement par un utilisateur Chat spécifié. Vous pouvez utiliser des messages privés dans des espaces avec plusieurs personnes afin qu'elles puissent interagir en privé avec les applications Chat. Par exemple, votre application Chat peut envoyer des messages en mode privé pour effectuer l'une des opérations suivantes:

  • Répondez à une commande à barre oblique. Par exemple, si un utilisateur appelle la commande à barre oblique /about de votre application Chat dans un espace, celle-ci peut répondre par un message privé expliquant ce qu'elle fait et comment l'utiliser.
  • notifier ou envoyer des informations qui ne concernent qu'un seul utilisateur ; Par exemple, informez un utilisateur qu'une tâche lui a été attribuée ou rappelez-lui de la terminer.
  • Envoyez un message d'erreur. Par exemple, si un utilisateur omet le texte d'argument requis pour une commande à barre oblique, l'application Chat peut envoyer un message privé pour expliquer l'erreur et aider l'utilisateur à mettre en forme la commande.

Lorsqu'une application Chat envoie un message privé, celui-ci affiche un libellé qui informe l'utilisateur que le message n'est visible que par lui:

Message privé pour l'application Chat Cymbal Labs. Il indique que l'application Chat a été créée par Cymbal Labs et partage un lien vers la documentation et un lien permettant de contacter l'équipe d'assistance.
Figure 1: Lorsqu'une application Chat envoie un message privé, l'utilisateur voit un message portant le libellé Only visible to you.

Prérequis

Node.js

Remarque:Les exemples de code Node.js de ce guide sont écrits pour s'exécuter en tant que fonction Google Cloud.

Python

Remarque:Les exemples de code Python présentés dans ce guide sont écrits pour s'exécuter en tant que fonction Google Cloud, à l'aide de Python 3.10.

Apps Script ;

Envoyer un message privé

Pour envoyer un message en mode privé en tant qu'application Chat, vous devez spécifier le champ privateMessageViewer dans le message lorsque vous le créez. Pour créer des messages privés, procédez comme n'importe quel message: soit en répondant à une interaction utilisateur, soit en appelant de manière asynchrone la méthode create() de l'API Google Chat sur la ressource Message. Pour savoir comment envoyer des SMS ou des messages envoyés sous forme de carte, consultez Envoyer un message.

L'exemple suivant montre le code JSON d'un message texte privé indiquant Hello private world!:

{
    "text": "Hello private world!",
    "privateMessageViewer": "USER"
}

Dans cet exemple, USER représente l'utilisateur de Chat qui peut afficher le message, mis en forme en tant que ressource User. Si vous répondez à une interaction utilisateur, vous pouvez spécifier l'objet User de l'événement d'interaction. Pour obtenir un exemple, consultez la section Répondre en privé à une commande à barre oblique.

Sinon, pour spécifier le lecteur pour un message privé, vous pouvez utiliser le champ name de la ressource User:

{
    "text": "Hello private world!",
    "privateMessageViewer": {
      "name": "users/USER_ID"
    }
}

Dans cet exemple, vous utilisez le champ name pour spécifier le nom de la ressource User du lecteur dans Google Chat. 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 des utilisateurs Google Chat.

Répondre en privé à une commande à barre oblique

Le code suivant montre un exemple d'application Chat qui répond à une commande à barre oblique avec un message privé.

L'application Chat traite un événement d'interaction MESSAGE et répond à la commande à barre oblique /help par un message texte privé expliquant comment l'utiliser:

Node.js 

/**
* Responds to a MESSAGE event in Google Chat.
*
* @param {!Object} req Request sent from Google Chat app
* @param {!Object} res Response to send back
*
* @return {!Object} respond to slash command
*/
exports.onMessage = function onMessage(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    return res.send('Hello! This function is meant to be used in Google Chat app.');
  }

  const event = req.body;

  // Checks for the presence of event.message.slashCommand.
  // If the slash command is "/help", responds with a private text message.
  if (event.message.slashCommand) {
    switch (event.message.slashCommand.commandId) {
      case '1':  // /help
        return res.json({
          privateMessageViewer: event.user,
          text: 'This Chat app was created by Cymbal Labs. To get help with this app, <https://cymbalgroup.com/docs|see our documentation> or <https://cymbalgroup.com/support|contact our support team>.'
        });
    }
  }

  // If the Chat app doesn't detect a slash command, it responds
  // with a private text message
  return res.json({
    privateMessageViewer: event.user,
    text: 'Try a slash command.'
  });
};

Apps Script ; 

/**
* Responds to a MESSAGE event in Google Chat.
*
* @param {Object} event the event object from Google Chat
*/
function onMessage(event) {
  if (event.message.slashCommand) {
    switch (event.message.slashCommand.commandId) {
      case 1: // Responds to /help
        return {
          "privateMessageViewer": event.user,
          "text": "This Chat app was created by Cymbal Labs. To get help with this app, <https://cymbalgroup.com/docs|see our documentation> or <https://cymbalgroup.com/support|contact our support team>."
        };
    }
  }
  else {
    return { "text": "Try a slash command.", "privateMessageViewer": event.user };
  }
}

Python 

from typing import Any, Mapping

import flask
import functions_framework

@functions_framework.http
def main(req: flask.Request) -> Mapping[str, Any]:
  """Responds to a MESSAGE event in Google Chat.

  Args:
      req (flask.Request): the event object from Chat API.

  Returns:
      Mapping[str, Any]: open a Dialog in response to a card's button click.
  """
  if req.method == 'GET':
    return 'Hello! This function must be called from Google Chat.'

  request = req.get_json(silent=True)

  # Checks for the presence of event.message.slashCommand.
  # If the slash command is "/help", responds with a private text message.
  if request.get('message', {}).get('slashCommand'):
    command_id = request.get('message', {}).get('slashCommand').get('commandId')
    if command_id == '1':  # /help
      return {
          'privateMessageViewer': request.get('user'),
          'text': (
              'This Chat app was created by Cymbal Labs. To get help with this'
              ' app, <https://cymbalgroup.com/docs|see our documentation> or'
              ' <https://cymbalgroup.com/support|contact our support team>.'
          ),
      }

  return {
      'privateMessageViewer': request.get('user'),
      'text': 'Try a slash command.',
  }

Limites

Pour envoyer un message privé, celui-ci ne peut pas contenir ni utiliser les éléments suivants:

  • Pièces jointes :
  • Actions accessoires :
  • Messages partiellement privés. Par exemple, une application Chat ne peut pas envoyer de message contenant du texte et une fiche où le texte n'est visible que par un seul utilisateur, mais que la fiche est visible par tous les membres de l'espace.
  • Authentification des utilisateurs : Seules les applications Chat peuvent envoyer des messages privés. Votre application Chat ne peut donc pas s'authentifier en tant qu'utilisateur pour envoyer un message en privé.

Mettre à jour ou supprimer des messages privés

Pour mettre à jour ou supprimer les messages Google Chat, vous devez appeler l'API Chat. Vous ne pouvez pas modifier le lecteur du message privé ni le rendre public. Par conséquent, lorsque vous mettez à jour des messages privés, vous devez omettre le champ privateMessageViewer dans l'appel d'API (le champ est uniquement en sortie).

Pour mettre à jour un message privé, consultez Mettre à jour un message. Pour supprimer un message privé, consultez l'article Supprimer un message.