Cette page explique comment configurer des commandes à barre oblique pour votre application Google Chat et y répondre.
Une commande à barre oblique est un moyen courant pour les utilisateurs d'appeler une application Chat et d'interagir avec elle. Les commandes à barre oblique aident également les utilisateurs à découvrir et à utiliser les principales fonctionnalités d'une application Chat.
Pour utiliser une commande à barre oblique, les utilisateurs saisissent une barre oblique (/), puis une commande de texte courte, comme /about, pour obtenir des informations sur l'application Chat. Les utilisateurs peuvent découvrir les commandes à barre oblique disponibles en saisissant une barre oblique dans Google Chat, qui affiche une fenêtre qui répertorie les commandes disponibles pour l'application Chat:
Lorsqu'un utilisateur envoie un message contenant une commande à barre oblique, le message n'est visible que par l'utilisateur et l'application Chat.
Pour déterminer si vous devez configurer des commandes à barre oblique et comprendre comment concevoir des interactions utilisateur, consultez Définir tous les parcours utilisateur.
Prérequis
Node.js
- Compte Google Workspace ayant accès à Google Chat.
- Une application Chat. Pour créer une application Chat, suivez ce quickstart.
Apps Script ;
- Compte Google Workspace ayant accès à Google Chat.
- Une application Chat. Pour créer une application Chat, suivez ce quickstart.
Python
- Compte Google Workspace ayant accès à Google Chat.
- Une application Chat. Pour créer une application Chat, suivez ce quickstart.
Configurer une commande à barre oblique
Cette section explique comment effectuer les étapes suivantes pour configurer une commande à barre oblique:
- Créez un nom pour votre commande à barre oblique.
- Configurez la commande à barre oblique dans l'API Google Chat.
Nommez votre commande à barre oblique
Le nom d'une commande à barre oblique correspond à ce que les utilisateurs saisissent dans un message Chat pour appeler l'application Chat. Une brève description apparaît également sous le nom pour inviter les utilisateurs à en savoir plus sur l'utilisation de la commande:
Lorsque vous choisissez un nom et une description pour votre commande à barre oblique, tenez compte des recommandations suivantes:
Pour nommer votre commande à barre oblique:
- Utilisez des mots ou des expressions courts, descriptifs et exploitables pour rendre les commandes claires et simples pour l'utilisateur. Par exemple, au lieu d'indiquer
/createAReminder, utilisez/remindMe. - Si votre commande contient plusieurs mots, aidez les utilisateurs à la lire en mettant le premier mot en minuscules, puis la première lettre des mots supplémentaires. Par exemple, au lieu d'
/updatecontact, utilisez/updateContact. - Déterminez si vous devez utiliser un nom unique ou commun pour votre commande. Si votre commande décrit une interaction ou une fonctionnalité type, vous pouvez utiliser un nom commun que les utilisateurs reconnaissent et attendent, tel que
/settingsou/feedback. Sinon, essayez d'utiliser des noms de commandes uniques, car si votre nom de commande est le même pour les autres applications Chat, l'utilisateur doit filtrer les commandes similaires pour trouver et utiliser le vôtre.
- Utilisez des mots ou des expressions courts, descriptifs et exploitables pour rendre les commandes claires et simples pour l'utilisateur. Par exemple, au lieu d'indiquer
Pour décrire votre commande à barre oblique:
- La description doit être courte et claire afin que les utilisateurs sachent à quoi s'attendre lorsqu'ils appelleront la commande.
- Indiquez aux utilisateurs si des exigences de mise en forme s'appliquent à la commande.
Par exemple, si vous créez une commande
/remindMenécessitant un texte d'argument, définissez la description surRemind me to do [something] at [time]. - Indiquez aux utilisateurs si l'application Chat répond à tous les membres de l'espace, ou en privé à l'utilisateur qui appelle la commande.
Par exemple, pour la commande à barre oblique
/about, vous pouvez la décrire comme suit :Learn about this app (Only visible to you). Pour répondre en privé à une commande à barre oblique, consultez la section Répondre avec un message privé.
Configurer votre commande à barre oblique dans l'API Google Chat
Pour créer une commande à barre oblique, vous devez spécifier des informations sur la commande dans la configuration de votre application Chat pour l'API Google Chat.
Pour configurer une commande à barre oblique dans l'API Google Chat, procédez comme suit:
Dans la console Google Cloud, cliquez sur Menu > API et services > API et services activés > API Google Chat.
Cliquez sur Configuration
Sous Commandes à barre oblique, cliquez sur Ajouter une commande à barre oblique.
Saisissez un nom, un ID de commande et une description pour la commande:
- Name (Nom) : nom à afficher pour la commande et texte saisi par les utilisateurs pour appeler votre application. Il doit commencer par une barre oblique, ne contenir que du texte et comporter jusqu'à 50 caractères.
- Description:le texte décrivant comment utiliser et mettre en forme la commande. Les descriptions peuvent comporter jusqu'à 50 caractères.
- ID de commande:nombre compris entre 1 et 1 000 que votre application Chat utilise pour reconnaître la commande à barre oblique et renvoyer une réponse.
Facultatif: Si vous souhaitez que votre application Chat réponde à la commande par une boîte de dialogue, cochez la case Ouvrir une boîte de dialogue.
Cliquez sur Enregistrer.
La commande à barre oblique est maintenant configurée pour l'application Chat.
Répondre à une commande à barre oblique
Lorsque les utilisateurs créent un message Chat contenant une commande à barre oblique, votre application Chat reçoit un événement d'interaction MESSAGE.
La charge utile de l'événement contient des informations sur la commande à barre oblique, y compris les champs slashCommand et slashCommandMetadata. Vous utilisez ces champs pour identifier l'ID de commande et renvoyer une réponse personnalisée.
L'exemple suivant montre la charge utile JSON pour un événement d'interaction MESSAGE incluant la commande à barre oblique /vote:
{
...
"message": {
...
"text": "/vote yes",
"argumentText": " yes",
"slashCommand": {
"commandId": 2
},
"annotations": [
{
"length": 5,
"startIndex": 0,
"type": "SLASH_COMMAND",
"slashCommand": {
"commandName":"/vote",
"commandId":1,
"type": "INVOKE",
"bot": {
"avatarUrl": "https://www.example.com/images/vote-app-icon.png",
"displayName": "Voter Chat App",
"name": "users/1234567890987654321",
"type": "BOT"
}
}
}
]
}
}
Pour répondre à une commande à barre oblique, vous pouvez détecter si le champ slashCommand est présent dans la charge utile de l'événement et, le cas échéant, renvoyer une réponse à la commande.
L'exemple de code suivant montre comment répondre à un événement d'interaction MESSAGE contenant une commande à barre oblique:
Node.js
/**
* Responds to a MESSAGE event in Google Chat.
*
* @param {Object} event the event object from Chat API.
*
* @return {object} function in response to a slash command.
*/
exports.onMessage = function onMessage(req, res) {
// Stores the Google Chat event as a variable.
var event = req.body;
// Checks for the presence of event.message.slashCommand.
if (event.message.slashCommand) {
switch (event.message.slashCommand.commandId) {
case ID: // The ID for your slash command
res.runFunction; // The response to the slash command.
}
}
Apps Script ;
/**
* Responds to a MESSAGE event in Google Chat.
*
* @param {Object} event the event object from Chat API.
*
* @return {object} function in response to a slash command.
*/
function onMessage(event) {
// Checks for the presence of event.message.slashCommand
if (event.message.slashCommand) {
switch (event.message.slashCommand.commandId) {
case ID: // The ID for your slash command
return runFunction; // The response to the slash command.
}
}
}
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 that includes a slash command.
Args:
req (flask.Request): the event object from Chat API.
Returns:
Mapping[str, Any]: function in response to a slash command.
"""
if req.method == 'GET':
return 'Sorry, this function must be called from a Google Chat.'
request = req.get_json(silent=True)
if slash_command := request.get('message', dict()).get('slashCommand'):
command_id = slash_command['commandId']
if command_id == ID:
return runFunction
Pour utiliser ce code, remplacez le code suivant:
ID: ID de commande que vous spécifiez lorsque vous configurez la commande à barre oblique dans l'API Google Chat.runFunction: fonction qui crée une réponse à la commande à barre oblique.
Facultatif: répondre par un message privé
Les messages contenant des commandes à barre oblique ne sont visibles que par l'utilisateur qui a envoyé le message et par l'application Chat qui reçoit la commande. Si vous avez configuré votre application Chat pour qu'elle soit ajoutée aux espaces comptant plusieurs personnes, vous pouvez envisager de répondre à la commande à barre oblique en privé afin de préserver la confidentialité de l'interaction entre l'utilisateur et l'application Chat.
Par exemple, si une équipe utilise une application Chat qui gère un service de service client, les utilisateurs peuvent appeler une commande à barre oblique telle que /myCases pour afficher les demandes d'assistance qui leur sont attribuées. Si l'équipe ajoute l'application Chat à un espace, un utilisateur qui utilise cette commande à barre oblique dans l'espace peut souhaiter que l'application Chat ne réponde qu'à lui. Pour éviter de publier les demandes d'assistance de l'utilisateur à tous les membres de l'espace, l'application Chat peut répondre en privé.
Pour répondre à une commande à barre oblique en privé, consultez Envoyer des messages privés aux utilisateurs de Google Chat.
Exemple complet: Configurer des contacts à l'aide de l'application de chat Rolodex
L'exemple suivant montre une application Chat qui répond aux commandes à barre oblique suivantes:
- La commande
/helprenvoie un message expliquant comment obtenir de l'aide avec l'application Chat. L'ID de la commande est défini sur1. - La commande
/createContactouvre une boîte de dialogue dans laquelle les utilisateurs peuvent saisir des informations sur le contact. L'ID de commande est défini sur2.
Avant d'exécuter cet exemple, suivez les étapes pour configurer les commandes à barre oblique dans l'API Google Chat.
Node.js
/**
* Responds to messages that have links whose URLs
* match URL patterns configured for link previews.
*
* @param {Object} event The event object from Chat
* API.
*
* @return {Object} Response from the Chat app
* attached to the message with the previewed link.
*/
exports.onMessage = function onMessage(req, res) {
// Store the Google Chat event as a variable.
const event = req.body;
if (req.method === "GET" || !event.message) {
res.send("Hello! This function is meant to be used in a Google Chat " +
"Space.");
}
// Checks for the presence of event.message.slashCommand.
// If the slash command is "/help", responds with a text message.
// If the slash command is "/createContact", opens a dialog.
if (event.message.slashCommand) {
switch (event.message.slashCommand.commandId) {
case 1: // /help
res.json({"text": "Contact bot helps you update your address book!"});
case 2: // /createContact
res.openDialog(event);
}
}
// If the Chat app doesn"t detect a slash command, it responds
// with a card that prompts the user to add a contact
else {
res.json({
"cardsV2": [{
"cardId": "addContact",
"card": {
"header": {
"title": "Rolodex",
"subtitle": "Manage your contacts!",
"imageUrl": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"imageType": "CIRCLE"
},
"sections": [
{
"widgets": [
{
"buttonList": {
"buttons": [
{
"text": "Add Contact",
"onClick": {
"action": {
"function": "openDialog",
"interaction": "OPEN_DIALOG"
}
}
}
]
}
}
]
}
]
}
}]
});
}
// Respond to button clicks on attached cards
if (event.type === "CARD_CLICKED") {
if (event.common.invokedFunction === "openDialog") {
res.openDialog(event);
}
if (event.common.invokedFunction === "openSequentialDialog") {
res.openSequentialDialog(event);
}
if (event.common.invokedFunction === "confirmDialogSuccess") {
res.confirmDialogSuccess(event);
}
}
};
/**
* Opens and starts a dialog that lets users add details about a contact.
*
* @param {object} event the event object from Google Chat.
*
* @return {object} open a dialog.
*/
function openDialog(event) {
res.json({
"action_response": {
"type": "DIALOG",
"dialog_action": {
"dialog": {
"body": {
"sections": [
{
"header": "Add new contact",
"widgets": [
{
"textInput": {
"label": "Name",
"type": "SINGLE_LINE",
"name": "name"
}
},
{
"textInput": {
"label": "Address",
"type": "MULTIPLE_LINE",
"name": "address"
}
},
{
"decoratedText": {
"text": "Add to favorites",
"switchControl": {
"controlType": "SWITCH",
"name": "saveFavorite"
}
}
},
{
"decoratedText": {
"text": "Merge with existing contacts",
"switchControl": {
"controlType": "SWITCH",
"name": "mergeContact",
"selected": true
}
}
},
{
"buttonList": {
"buttons": [
{
"text": "Next",
"onClick": {
"action": {
"function": "openSequentialDialog"
}
}
}
]
}
}
]
}
]
}
}
}
}
});
};
/**
* Opens a second dialog that lets users add more contact details.
*
* @param {object} event the event object from Google Chat.
*
* @return {object} open a dialog.
*/
function openSequentialDialog(event) {
res.json({
"action_response": {
"type": "DIALOG",
"dialog_action": {
"dialog": {
"body": {
"sections": [
{
"header": "Add new contact",
"widgets": [
{
"textInput": {
"label": "Notes",
"type": "MULTIPLE_LINE",
"name": "notes"
}
},
{
"selectionInput": {
"type": "RADIO_BUTTON",
"label": "Contact type",
"name": "contactType",
"items": [
{
"text": "Work",
"value": "Work",
"selected": false
},
{
"text": "Personal",
"value": "Personal",
"selected": false
}
]
}
},
{
"buttonList": {
"buttons": [
{
"text": "Submit",
"onClick": {
"action": {
"function": "confirmDialogSuccess",
"parameters": [
{
"key": "confirmDialogSuccess",
"value": "confirmDialogSuccess"
}
]
}
}
}
]
},
"horizontalAlignment": "END"
}
]
}
]
}
}
}
}
});
}
/**
* Checks for a form input error, the absence of
* a "name" value, and returns an error if absent.
* Otherwise, confirms successful receipt of a dialog.
*
* Confirms successful receipt of a dialog.
*
* @param {Object} event the event object from Chat API.
*
* @return {object} open a Dialog in Google Chat.
*/
function receiveDialog(event) {
// Checks to make sure the user entered a name
// in a dialog. If no name value detected, returns
// an error message.
if (event.common.formInputs.contactName.stringInputs.value[0] === "") {
return {
"actionResponse": {
"type": "DIALOG",
"dialogAction": {
"actionStatus": {
"statusCode": "OK",
"userFacingMessage": "Don't forget to name your new contact!"
}
}
}
};
// Otherwise the app indicates that it received
// form data from the dialog. Any value other than "OK"
// gets returned as an error. "OK" is interpreted as
// code 200, and the dialog closes.
} else {
res.json({
"actionResponse": {
"type": "DIALOG",
"dialogAction": {
"actionStatus": "OK"
}
}
});
}
}
Apps Script ;
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 that includes the /createContact
slash command by opening a dialog.
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 'Sorry, this function must be called from a Google Chat.'
request = req.get_json(silent=True)
if request.get('type') == 'CARD_CLICKED':
invoked_function = request.get('common', dict()).get('invokedFunction')
if invoked_function == 'open_dialog':
return open_dialog(request)
elif invoked_function == 'open_sequential_dialog':
return open_dialog(request)
elif invoked_function == "receive_dialog":
return receive_dialog(request)
else:
return {
'cardsV2': [{
'cardId': 'addContact',
'card': {
'header': {
'title': 'Rolodex',
'subtitle': 'Manage your contacts!',
'imageUrl': 'https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png',
'imageType': 'CIRCLE'
},
'sections': [
{
'widgets': [
{
'buttonList': {
'buttons': [
{
'text': 'Add Contact',
'onClick': {
'action': {
'function': 'open_dialog',
'interaction': 'OPEN_DIALOG'
}
}
}
]
}
}
]
}
]
}
}]
}
def open_dialog(request: Mapping[str, Any]) -> Mapping[str, Any]:
"""Opens a dialog in Google Chat.
Args:
request (Mapping[str, Any]): the event object from Chat API.
Returns:
Mapping[str, Any]: open a Dialog in response to a card's button click.
"""
return {
'action_response': {
'type': 'DIALOG',
'dialog_action': {
'dialog': {
'body': {
'sections': [
{
'header': 'Add new contact',
'widgets': [
{
'textInput': {
'label': 'Name',
'type': 'SINGLE_LINE',
'name': 'name'
}
},
{
'textInput': {
'label': 'Address',
'type': 'MULTIPLE_LINE',
'name': 'address'
}
},
{
'decoratedText': {
'text': 'Add to favorites',
'switchControl': {
'controlType': 'SWITCH',
'name': 'saveFavorite'
}
}
},
{
'decoratedText': {
'text': 'Merge with existing contacts',
'switchControl': {
'controlType': 'SWITCH',
'name': 'mergeContact',
'selected': True
}
}
},
{
'buttonList': {
'buttons': [
{
'text': 'Next',
'onClick': {
'action': {
'function': 'open_sequential_dialog'
}
}
}
]
}
}
]
}
]
}
}
}
}
}
def open_sequential_dialog(request: Mapping[str, Any]) -> Mapping[str, Any]:
"""Opens a second dialog that lets users add more contact details.
Args:
request (Mapping[str, Any]): the event object from Chat API.
Returns:
Mapping[str, Any]: open a Dialog in response to a card's button click.
"""
return {
'action_response': {
'type': 'DIALOG',
'dialog_action': {
'dialog': {
'body': {
'sections': [
{
'header': 'Add new contact',
'widgets': [
{
'textInput': {
'label': 'Notes',
'type': 'MULTIPLE_LINE',
'name': 'notes'
}
},
{
'selectionInput': {
'type': 'RADIO_BUTTON',
'label': 'Contact type',
'name': 'contactType',
'items': [
{
'text': 'Work',
'value': 'Work',
'selected': False
},
{
'text': 'Personal',
'value': 'Personal',
'selected': False
}
]
}
},
{
'buttonList': {
'buttons': [
{
'text': 'Submit',
'onClick': {
'action': {
'function': 'receive_dialog',
'parameters': [
{
'key': 'receiveDialog',
'value': 'receiveDialog'
}
]
}
}
}
]
},
'horizontalAlignment': 'END'
}
]
}
]
}
}
}
}
}
def receive_dialog(event: Mapping[str, Any]) -> Mapping[str, Any]:
"""Checks for a form input error, the absence of a "name" value, and returns
an error if absent. Otherwise, confirms successful receipt of a dialog.
Args:
event (Mapping[str, Any]): the event object from Chat API.
Returns:
Mapping[str, Any]: the response.
"""
if event.get('common', dict()) \
.get('formInputs', dict()).get('contactName', dict()) \
.get('stringInputs').get('value', list()):
return {
'actionResponse': {
'type': 'DIALOG',
'dialogAction': {
'actionStatus': 'OK'
}
}
}
else:
return {
'actionResponse': {
'type': 'DIALOG',
'dialogAction': {
'actionStatus': "Don't forget to name your new contact!"
}
}
}