Messages de format

Cette page explique comment les applications Google Chat peuvent mettre en forme du texte pour envoyer des messages contenant l'un des éléments suivants :

• Texte enrichi contenant des liens hypertextes ou des @mentions d'un ou de tous les utilisateurs d'un espace Chat.
• Texte qui apparaît dans une interface de fiche, y compris sous forme de texte de paragraphe ou de texte d'interface utilisateur qui s'affiche à côté d'une icône, comme un bouton.

Mettre en forme un message

Chat vous permet d'ajouter une mise en forme de base à un message, y compris le gras, l'italique et le barré. La mise en forme du texte est différente dans les messages textuels et les messages de fiches, car les messages textuels sont mis en forme avec la même syntaxe que celle utilisée par les utilisateurs de Chat.

Pour les messages envoyés ou récupérés à l'aide de l'API Chat, vous pouvez utiliser la syntaxe Markdown standard (MARKUP_SYNTAX_MARKDOWN) ou la syntaxe de balisage Chat (MARKUP_SYNTAX_CHAT). Vous pouvez configurer une syntaxe de balisage par défaut au niveau de l'application dans la console Google Cloud (voir Configurer l'API Google Chat) :

• Markdown : syntaxe Markdown standard (MARKUP_SYNTAX_MARKDOWN), basée sur la spécification CommonMark avec des extensions supplémentaires. Les applications Chat nouvellement créées utilisent par défaut le format Markdown.
• Chat : syntaxe de balisage Chat (MARKUP_SYNTAX_CHAT). Les applications Chat existantes utilisent par défaut Chat pour préserver la rétrocompatibilité.

Vous pouvez également spécifier markup_syntax sur des requêtes API Chat individuelles pour remplacer la valeur par défaut au niveau de l'application. Lorsque markup_syntax n'est pas spécifié dans une requête API, le balisage est défini en fonction de la manière dont vous appelez l'API Chat :

• Applications Chat configurées : utilise la syntaxe de balisage enregistrée sur la page de configuration de l'API Chat.
• Projets Cloud non configurés (sans configuration) : si votre projet Cloud appelle l'API Chat sans configuration d'application Chat enregistrée, les requêtes sont définies par défaut sur MARKUP_SYNTAX_MARKDOWN.
• Webhooks entrants : la valeur par défaut est MARKUP_SYNTAX_CHAT. Consultez Envoyer des messages à l'aide de webhooks entrants.

Pour mettre en forme les messages, utilisez la syntaxe suivante :

Prenons l'exemple du code JSON suivant :

    {
      "text": "Your pizza delivery *has arrived*!\nThank you for using _Cymbal Pizza!_"
    }

Ce message texte mis en forme s'affiche comme suit dans un espace Chat :

Afficher la mise en forme du texte envoyé dans un message

Lorsqu'un utilisateur envoie un message, le corps du message en texte brut se trouve dans le champ text. Une mise en forme est appliquée au message texte à l'aide de la syntaxe Markdown, dans le champ text. Une mise en forme supplémentaire est disponible dans le champ formattedText en sortie uniquement, y compris les éléments suivants :

• Syntaxe Markdown supplémentaire pour le texte
• Mentions des utilisateurs
• Liens hypertextes personnalisés
• Emoji personnalisés

Prenons l'exemple du texte suivant envoyé par un utilisateur :

Si le message a été mis en forme à l'aide du menu Format de l'interface utilisateur de Chat, le champ text ne contient que le texte, tandis que le champ formattedText contient les balises, le texte et le lien hypertexte. L'exemple suivant montre le brouillon d'un message contenant un mot avec un lien hypertexte, des éléments dans une liste et un mot en gras :

Le message est reçu au format suivant :

    {
      "text": "I can meet there at:\nNoon\n3 pm\n5 pm\nWhat time works for you?",
      "formattedText": "I can meet <http://example.com|there> at:\n* Noon\n* 3 pm\n* 5 pm\nWhat time works for *you*?",
    }

Liens de format

Si vous incluez une URL de lien brut dans le texte de votre message, par exemple http://www.example.com/, Google Chat l'utilise comme texte du lien et crée automatiquement un lien hypertexte vers l'URL spécifiée.

Pour fournir un texte de lien alternatif pour votre lien, utilisez la syntaxe suivante :

• Pour les messages d'API configurés avec Markdown, utilisez la syntaxe de lien Markdown standard :

  Exemple de syntaxe	Texte affiché dans Google Chat
  [Example website](https://example.com)	Example website

• Pour les messages en texte brut standards, utilisez la syntaxe avec une barre verticale :

  Exemple de syntaxe	Texte affiché dans Google Chat
  <https://example.com|Example website>	Example website

  La barre verticale et le texte du lien sont facultatifs. Ainsi, <https://example.com> et https://example.com sont équivalents.

Utiliser un emoji personnalisé dans un message

Les applications Chat peuvent envoyer des messages avec des emoji personnalisés pour personnaliser les messages. Les emoji personnalisés ne sont disponibles que pour les organisations Google Workspace, et l'administrateur doit les activer pour l'organisation. Pour en savoir plus, consultez À propos des emoji personnalisés dans Google Chat et Gérer les autorisations pour les emoji personnalisés.

Pour créer des messages avec des emoji personnalisés, votre application doit utiliser l'authentification des utilisateurs. Les emoji personnalisés ne sont pas compatibles avec les messages créés en tant que webhook ni avec les messages créés avec l'authentification de l'application.

Pour ajouter un emoji personnalisé au texte d'un message, spécifiez le name ou le emoji_name de la ressource customEmoji :

{
    "text": "Hello <customEmojis/CUSTOM_EMOJI_ID>."
}

Pour utiliser cet exemple, remplacez CUSTOM_EMOJI_ID par l'ID de l'emoji personnalisé. Vous trouverez cet ID dans le champ name ou emoji_name de la ressource customEmoji.

Si votre application envoie des messages à l'aide de la syntaxe Markdown, vous pouvez spécifier des emoji personnalisés au format de balise HTML à l'aide de l'ID d'emoji personnalisé :

{
  "text": "Hello <chat-emoji data-custom-emoji=\"customEmojis/CUSTOM_EMOJI_ID\">."
}

Vous pouvez également spécifier le nom de l'emoji personnalisé :

{
  "text": "Hello <chat-emoji data-emoji-name=\"CUSTOM_EMOJI_NAME\">."
}

Pour utiliser ces exemples, remplacez CUSTOM_EMOJI_ID par l'ID de l'emoji personnalisé et CUSTOM_EMOJI_NAME par le nom du shortcode de l'emoji personnalisé.

Mentionner des utilisateurs dans un message

Les applications Chat peuvent envoyer des messages qui @mentionnent un ou tous les utilisateurs d'un espace Chat. Les applications Chat peuvent également mentionner des utilisateurs qui n'ont pas rejoint l'espace ou qui sont membres d'un espace en mode importation.

Les messages silencieux ne permettent pas de mentionner des utilisateurs. L'inclusion d'une mention dans un message silencieux renvoie une erreur.

@mentionner des utilisateurs spécifiques

Pour @mentionner un utilisateur spécifique, ajoutez <users/{user}> au message, où {user} est l'ID de l'utilisateur. Prenons l'exemple du message suivant, où 123456789012345678901 représente l'ID de l'utilisateur Mahan S.:

{
    "text": "A customer has reported an issue. Assigning ticket #942 to <users/123456789012345678901>."
}

Si votre application envoie des messages à l'aide de la syntaxe Markdown, utilisez le format de balise HTML chat-user pour spécifier l'ID utilisateur :

{
  "text": "Assigning ticket #942 to <chat-user data-user=\"users/123456789012345678901\">."
}

Vous pouvez également spécifier par e-mail :

{
  "text": "Assigning ticket #942 to <chat-user data-email=\"mahan@example.com\">."
}

Le message s'affiche comme suit :

Vous pouvez spécifier la valeur users/{user} comme suit :

• Si votre application Google Chat répond à un message envoyé par l'utilisateur, vous pouvez utiliser le champ message.sender.name de l'événement d'interaction MESSAGE.

• Si votre application Google Chat crée un message texte asynchrone, vous pouvez spécifier la valeur de users/{user} de l'une des manières suivantes :

  • Utilisez le champ name de la ressource Google Chat User, par exemple users/123456789012345678901.
  • Utilisez l'adresse e-mail de l'utilisateur comme alias pour la valeur {user}. Par exemple, si l'adresse e-mail est mahan@example.com, vous pouvez spécifier l'utilisateur en tant que users/mahan@example.com. Pour utiliser un alias d'adresse e-mail, votre application Google Chat doit s'authentifier en tant qu'utilisateur.

• Si vous utilisez l'API People, vous pouvez également utiliser la méthode people.get pour identifier l'ID utilisateur.

@mentionner tous les utilisateurs

Pour créer un message qui @mentionne tous les membres d'un espace, remplacez {user} par all. L'exemple JSON suivant mentionne tous les utilisateurs dans un message :

{
    "text": "Important message for <users/all>: Code freeze starts at midnight tonight!"
}

Si votre application envoie des messages à l'aide de la syntaxe Markdown, spécifiez la mention au format de balise HTML chat-user :

{
  "text": "Important message for <chat-user data-user=\"users/all\">: Code freeze starts at midnight tonight!"
}

Ajouter des citations à un message

Les applications Chat peuvent inclure des citations dans les messages pour fournir aux utilisateurs des informations détaillées sur les sources. Vous pouvez fournir des sources de deux manières :

• Citations intégrées : ajoutez des fiches interactives qui s'affichent lorsque les utilisateurs pointent sur des parties spécifiques du texte de votre message.
• Sources en pied de page : affichez une liste de sources au bas du message sous forme de liens en pied de page.

Les citations ne sont acceptées que lorsque le champ markupSyntax du message est défini sur MARKUP_SYNTAX_MARKDOWN. Cette fonctionnalité n'est disponible que via la création de messages asynchrones à l'aide de l'API Chat.

Pour ajouter des citations intégrées à un message :

1. Fournissez les sources dans la liste citations du message elements, en attribuant un id unique à chaque objet Citation.
2. Dans le corps du message, placez le texte que vous souhaitez citer entre les balises HTML chat-citation : <chat-citation data-id="{id}">{text}</chat-citation>. Assurez-vous que l'{id} correspond à l'ID que vous avez défini dans le elements. Les citations non référencées (celles sans balise correspondante) sont ignorées.

{
  "text": "This is a <chat-citation data-id=\"cite_1\">cited</chat-citation> text.",
  "markupSyntax": "MARKUP_SYNTAX_MARKDOWN",
  "elements": {
    "citations": [
      {
        "id": "cite_1",
        "citedSources": [
          {
            "title": "Example Source",
            "uri": "https://example.com"
          }
        ]
      }
    ]
  }
}

Pour ajouter des sources en pied de page à un message, fournissez-les dans la liste citedSources du message elements. Toutes les sources fournies ici s'affichent automatiquement sous le message sous forme de liens de pied de page et ne nécessitent aucune balise intégrée dans le texte du message.

{
  "text": "This is a message with a footer source.",
  "markupSyntax": "MARKUP_SYNTAX_MARKDOWN",
  "elements": {
    "citedSources": [
      {
        "title": "Example Source",
        "uri": "https://example.com"
      }
    ]
  }
}

Mettre en forme le texte qui apparaît dans les fiches

Dans les fiches, la plupart des champs de texte sont compatibles avec la mise en forme de base du texte à l'aide d'un petit sous-ensemble de balises HTML. La mise en forme du texte dans les messages de fiches est différente de celle des messages textuels, car les messages textuels sont mis en forme avec la même syntaxe que celle utilisée par les utilisateurs de Chat.

Utilisez Card Builder pour concevoir et prévisualiser les messages et les interfaces utilisateur des applications Chat :

Mettre en forme le texte d'un paragraphe

Les balises acceptées et leur objectif sont indiqués dans le tableau suivant :

Pour définir des listes et des blocs de code, utilisez les balises suivantes :

This is a code block.

Markdown

Lorsque la syntaxe Markdown est activée, vous pouvez utiliser la syntaxe suivante :

Ajouter des icônes au texte

Pour afficher des icônes à côté du texte dans une fiche, vous pouvez utiliser les widgets DecoratedText et ButtonList.

Les sections suivantes expliquent comment utiliser des icônes intégrées, des icônes Google Material ou des icônes personnalisées dans du texte ou des boutons décorés.

Utiliser des icônes de Chat

Pour utiliser l'une des icônes intégrées disponibles dans Chat, spécifiez l'une des options suivantes :

Le tableau suivant liste les icônes intégrées disponibles pour les messages de fiche :

Voici un exemple de carte avec une icône d'e-mail :

Utiliser les icônes Google Material

Vous pouvez utiliser les icônes Material de Google pour choisir parmi plus de 2 500 options d'icônes et personnaliser l'épaisseur, le remplissage et le grade des icônes.

Voici un exemple de fiche avec une icône Material Google :

Utiliser des icônes personnalisées

Pour ajouter une icône personnalisée, incluez le champ iconUrl et spécifiez l'URL correspondante de l'icône.

Voici un exemple d'icône personnalisée :