Cette page explique comment configurer des commandes à barre oblique et y répondre Application Google Chat.
Une commande à barre oblique est un moyen courant pour les utilisateurs d'appeler un objet Application Chat 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 doivent saisir 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 tapant une barre oblique dans
Google Chat, qui affiche une fenêtre répertoriant les commandes disponibles pour
Application de chat:
![Fenêtre de commande à barre oblique](https://developers-dot-devsite-v2-prod.appspot.com/static/workspace/chat/images/slash-command-window.png?authuser=6&hl=fr)
Lorsqu'un utilisateur envoie un message contenant une commande à barre oblique, le message est uniquement visible par l'utilisateur et dans l'application Chat.
Pour décider si vous devez configurer des commandes à barre oblique et comprendre comment concevoir des interactions utilisateur, voir Définissez tous les parcours utilisateur.
Prérequis
Node.js
Une application Google Chat avec des fonctionnalités interactives. Pour créer un une application Chat interactive utilisant un service HTTP, suivez ce guide de démarrage rapide.
Apps Script ;
Une application Google Chat avec des fonctionnalités interactives. Pour créer un application Chat interactive dans Apps Script, suivez ce guide de démarrage rapide.
Python
Une application Google Chat avec des fonctionnalités interactives. Pour créer un une application Chat interactive utilisant un service HTTP, suivez ce guide de démarrage rapide.
Configurer une commande à barre oblique
Cette section explique comment effectuer les étapes suivantes pour configurer une 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 est ce que les utilisateurs saisissent dans un message Chat pour appeler l'application Chat. Une brève description également apparaît sous le nom pour inviter les utilisateurs à en savoir plus sur l'utilisation de la commande:
![Nom et description de la commande à barre oblique](https://developers-dot-devsite-v2-prod.appspot.com/static/workspace/chat/images/slash-command-description.png?authuser=6&hl=fr)
Lorsque vous choisissez un nom et une description pour votre commande à barre oblique, tenez compte de la recommandations suivantes:
Pour nommer votre commande à barre oblique:
- Utilisez des mots ou des expressions courts, descriptifs et exploitables pour faire en sorte que
des commandes claires et simples pour l'utilisateur. Par exemple, au lieu de saisir
/createAReminder
, utilisez/remindMe
. - Si votre commande contient plusieurs mots, aidez les utilisateurs à la lire
en mettant tout en minuscules pour le premier mot, puis en mettant le premier mot en majuscule
ou la lettre de chaque mot supplémentaire. Par exemple, au lieu de
/updatecontact
, utiliser/updateContact
. - Déterminez si vous devez utiliser un nom unique ou courant pour votre commande. Si
votre commande décrit une interaction ou une fonctionnalité typique, vous pouvez utiliser
nom courant que les utilisateurs reconnaissent et attendent, tel que
/settings
ou/feedback
Sinon, essayez d'utiliser des noms de commande uniques, car si votre nom de la commande est identique pour les autres applications Chat, l'utilisateur doit filtrer grâce à des commandes similaires pour trouver et utiliser les vôtres.
- Utilisez des mots ou des expressions courts, descriptifs et exploitables pour faire en sorte que
des commandes claires et simples pour l'utilisateur. Par exemple, au lieu de saisir
Pour décrire votre commande à barre oblique:
- La description doit être courte et claire pour que les utilisateurs sachent à quoi s'attendre lorsqu'ils appellent la commande.
- Indiquez aux utilisateurs s'il existe des exigences de mise en forme pour la commande.
Par exemple, si vous créez une commande
/remindMe
qui nécessite un argument , définissez la description commeRemind me to do [something] at [time]
. - Indiquer aux utilisateurs si l'application Chat répond à
tout le monde dans l'espace, ou en privé à l'utilisateur qui appelle la commande.
Par exemple, vous pouvez décrire la commande à barre oblique
/about
comme suit :Learn about this app (Only visible to you)
Pour répondre en privé à une 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 la concernant 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 : étapes:
Dans la console Google Cloud, cliquez sur Menu > API et Services > API activées et Services > 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:
- Nom:le nom à afficher pour la commande et le type d'utilisateur saisi pour appeler votre application. Doit commencer par une barre oblique, ne contenir que du texte et ne peut ne pas dépasser 50 caractères.
- Description:le texte qui décrit comment utiliser et mettre en forme la commande. Les descriptions peuvent comporter jusqu'à 50 caractères.
- ID de commande:un nombre compris entre 1 et 1 000 que votre L'application de chat utilise pour reconnaître la commande à barre oblique et renvoyer une réponse.
Facultatif: Si vous souhaitez que votre application Chat réponde aux commande avec une boîte de dialogue, sélectionnez 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 slashCommand
et slashCommandMetadata
. Ces champs permettent d'identifier l'ID de commande et de renvoyer un
de réponse.
L'exemple suivant montre la charge utile JSON pour un événement d'interaction MESSAGE
qui inclut 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, renvoie 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.json(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 le code, remplacez les éléments suivants:
ID
: ID de commande que vous spécifiez lorsque vous Configurez la commande à barre oblique dans l'API Google Chat.runFunction
: une fonction qui crée une réponse à la commande à barre oblique.
Facultatif: répondre avec un message privé
Les messages contenant des commandes à barre oblique ne sont visibles que par l'utilisateur qui a envoyé la commande et l'application Chat qui reçoit la commande. Si vous avez configuré votre application Chat pour être ajoutée à des espaces avec plusieurs personnes, vous pouvez envisager de répondre à la commande à barre oblique afin que l'interaction entre l'utilisateur et l'utilisateur Application Chat
Par exemple, si une équipe utilise une application Chat qui gère
un service de support 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 le
Application de chat à un espace (utilisateur utilisant cette commande à barre oblique)
dans l'espace peuvent vouloir que l'application Chat ne réponde qu'aux
de l'IA générative. Pour éviter de publier les demandes d'assistance de l'utilisateur auprès de tous les membres de l'espace,
L'application Chat peut répondre en privé.
Pour répondre à une commande à barre oblique en mode privé, consultez Envoyez 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 à les commandes à barre oblique suivantes:
- La commande
/help
renvoie un message qui explique comment récupérer avec l'application Chat. L'ID de commande est défini à1
. - La commande
/createContact
ouvre une boîte de dialogue dans laquelle les utilisateurs peuvent saisir les détails d'un 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.json(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.json(openDialog(event));
}
if (event.common.invokedFunction === "openSequentialDialog") {
res.json(openSequentialDialog(event));
}
if (event.common.invokedFunction === "confirmDialogSuccess") {
res.json(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) {
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": "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) {
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": "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 {
return {
"actionResponse": {
"type": "DIALOG",
"dialogAction": {
"actionStatus": "OK"
}
}
};
}
}
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.
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!"
}
}
}