Chaque application Google Chat que vous créez nécessite son propre projet Google Cloud avec l'API Chat activée et configurée.
Pour effectuer des appels d'API en lecture seule avec l'authentification des utilisateurs, comme l'obtention d'espaces et l'affichage de messages, il vous suffit d'activer l'API et de créer un client OAuth.
Pour effectuer des appels d'API de création, de mise à jour et de suppression, ou pour déployer et tester une application Chat interactive (créée en tant que module complémentaire Google Workspace qui étend Chat), vous devez également configurer l'API Chat. Les paramètres de configuration de l'API Chat vous permettent de spécifier tous les détails de l'application Chat, y compris son nom à afficher, son avatar, ses points de terminaison de déploiement et ses fonctionnalités interactives.
Prérequis
- Compte Google Workspace Business ou Enterprise ayant accès à Google Chat.
- Créez un projet Google Cloud.
- Configurez l'écran de consentement OAuth.
- Activez l'API Google Chat.
Choisir un nom à afficher, un avatar et une description pour votre application Chat
Lorsque vous activez l'API Chat, vous configurez les détails de votre application Chat qui s'affichent pour les utilisateurs dans Chat, y compris un nom à afficher, un avatar et une description. Ces informations ne s'affichent que dans Chat. Pour publier votre application Chat sur Marketplace, vous devez également spécifier les détails qui apparaissent dans la fiche Marketplace de votre application Chat.
Avant de configurer une application Chat, préparez les informations suivantes :
| Champ | Description | Format |
|---|---|---|
| Nom de l'application | Nom à afficher de l'application Chat. | Jusqu'à 25 caractères alphanumériques |
| URL de l'avatar | Image qui s'affiche comme avatar de votre application Chat. | URL HTTPS pointant vers une image graphique carrée (PNG ou JPEG). La taille recommandée est de 256 x 256 pixels ou plus. |
| Description | Courte description de l'application Chat, affichée lorsque les utilisateurs recherchent des applications dans Chat. | Jusqu'à 40 caractères alphanumériques |
| Longue description | Facultatif. Description de ce que l'application Chat peut faire, affichée lorsque les utilisateurs démarrent une conversation avec l'application Chat ou ouvrent la page d'accueil des sessions d'un agent. Actuellement, cette fonctionnalité n'est disponible que lors de la mise à jour de la configuration de l'application à l'aide de la console Google Cloud. Elle n'est pas disponible via l'API Google Workspace Add-ons. | Jusqu'à 250 caractères |
Le nom, l'avatar et la description de l'application Chat sont affichés aux utilisateurs dans l'interface utilisateur de Chat. Pour certaines requêtes d'écriture de l'API Chat, Chat utilise ces informations pour attribuer les actions qu'une application Chat effectue dans Chat.
Par exemple, si vous appelez la méthode spaces.create(), Chat inclut le nom de l'application Chat dans la description de la personne qui a créé l'espace, comme illustré dans l'image suivante :

spaces.create() est utilisée pour créer un espace au nom d'un utilisateur.
Pour interagir avec les applications Chat, les utilisateurs voient ou utilisent également ces informations de la manière suivante :
- @mentionnez l'application Chat pour l'ajouter à un espace ou lui envoyer un message.
- Recherchez l'application Chat et démarrez un message privé avec elle. Dans le menu Applications, les messages privés affichent le nom et l'avatar de l'application Chat.
- Dans la barre de rédaction, les utilisateurs peuvent parcourir les applications Chat et voir leur nom, leur avatar et leur description.
Configurer votre application Chat dans la console Google Cloud
Une fois que vous disposez des détails de votre application Chat, ouvrez votre projet Cloud et configurez l'API Chat :
Dans la console Google Cloud, accédez à la page de l'API Chat, puis cliquez sur la page Configuration :
Sous Informations sur l'application, renseignez les champs Nom de l'application, URL de l'avatar et Description.
(Facultatif) Remplissez le champ Description longue.
Facultatif : dans le menu Syntaxe de balisage, sélectionnez la syntaxe de balisage par défaut (Markdown ou Chat) pour les messages de votre application Chat. Pour en savoir plus sur la mise en forme du texte et sur la façon dont Chat détermine la syntaxe de balisage des requêtes API, consultez Mettre en forme les messages.
Sous Fonctionnalités interactives, indiquez si votre application Chat doit répondre aux interactions des utilisateurs :
Pour créer une application Chat interactive, activez l'option Activer les fonctionnalités interactives et procédez comme suit :
- Sous Fonctionnalité :
- (Facultatif) Sélectionnez Prendre en charge l'accueil de l'application pour afficher une fiche de page d'accueil dans l'onglet Accueil des messages privés (1:1) avec l'application Chat.
- Sélectionnez Rejoindre des espaces et des conversations de groupe pour que votre application Chat puisse être installée et utilisée. Par défaut, les utilisateurs peuvent installer l'application Chat et échanger des messages avec elle dans un espace dédié entre l'utilisateur et l'application Chat. Les utilisateurs peuvent également ajouter l'application Chat et interagir avec elle dans des espaces comptant plusieurs personnes.
Sous Paramètres de connexion, sélectionnez l'architecture que vous souhaitez utiliser pour recevoir des objets d'événement de Chat :
- Pour utiliser un service HTTP, sélectionnez URL du point de terminaison HTTP et indiquez une URL.
- Pour utiliser un projet Google Apps Script, sélectionnez Apps Script et indiquez un ID de déploiement pour le projet.
- Pour utiliser un agent Dialogflow, sélectionnez Dialogflow, sélectionnez Dialogflow CX ou Dialogflow ES, puis indiquez le nom de ressource de l'agent.
- Pour utiliser Pub/Sub, sélectionnez Cloud Pub/Sub, puis saisissez le nom du sujet.
(Facultatif) Pour acheminer les objets d'événement vers des points de terminaison ou des fonctions spécifiques, accédez à Paramètres de connexion > Déclencheurs, puis fournissez ou mettez à jour les points de terminaison ou les fonctions de rappel pour les déclencheurs Chat suivants :
- Page d'accueil de l'application (si l'option Prendre en charge la page d'accueil de l'application est activée) : un utilisateur ouvre l'onglet Accueil dans un message privé avec l'application Chat.
- Ajouté à l'espace : un utilisateur ajoute l'application Chat à une conversation de groupe ou à un espace, ou installe l'application Chat pour les messages privés.
- Message : un utilisateur envoie un message à l'application Chat. Par exemple, un utilisateur envoie un message privé à l'application Chat ou mentionne l'application Chat dans un espace avec plusieurs personnes.
- Supprimé de l'espace : un utilisateur désinstalle ou supprime l'application Chat d'un espace.
- Commande d'application : un utilisateur appelle une commande rapide, une commande à barre oblique ou une action de message depuis l'application Chat.
Facultatif : Ajoutez d'autres fonctionnalités interactives telles que des sessions, des prompts de démarrage, des commandes (commandes rapides, commandes à barre oblique et actions de message) ou des aperçus de liens.
Sous Visibilité, sélectionnez Rendre cette application Chat accessible à certains utilisateurs et groupes, puis saisissez les adresses e-mail des personnes ou des groupes Google de votre organisation Google Workspace :
- Pour installer et tester votre application vous-même, saisissez votre propre adresse e-mail.
- Pour partager une application Chat interne avec une équipe ou l'ensemble de votre organisation sans la publier sur Marketplace, saisissez un ou plusieurs groupes Google. Le nombre de membres dans un groupe n'est pas limité. Si votre application demande des champs d'application
chat.app.*, vous devez toujours publier l'application pour qu'elle soit approuvée par l'administrateur. - Si votre administrateur limite les installations Marketplace aux applications d'une liste d'autorisation, la console Google Cloud limite ce champ à cinq adresses e-mail d'utilisateurs individuels pour le développement. La visibilité du groupe ne s'applique qu'une fois que l'administrateur a ajouté l'application à la liste d'autorisation.
- Sous Fonctionnalité :
Facultatif : sous Journaux, cochez la case Consigner les erreurs dans Logging pour utiliser Google Cloud Logging. Pour en savoir plus, consultez Interroger les journaux d'erreurs des applications Chat.
Cliquez sur Enregistrer.
Une fois la configuration enregistrée, toute personne que vous avez spécifiée dans le paramètre Visibilité de l'API Chat peut installer, tester ou utiliser l'application Chat. Pour commencer à tester et à déboguer votre application Chat, consultez Tester les fonctionnalités interactives des applications Google Chat.
Configurer votre application Chat à l'aide de la Google Cloud CLI
Au lieu d'utiliser la console Google Cloud, vous pouvez afficher et mettre à jour la configuration d'une application Chat à partir de la ligne de commande avec la Google Cloud CLI (gcloud CLI). Par exemple, vous pouvez configurer une application Chat à partir d'un script ou conserver sa configuration dans un fichier que vous stockez avec votre code.
Le groupe de commandes gcloud beta workspace-add-ons chat-app-config comporte les commandes suivantes :
describe: affiche la configuration.update: configure une application Chat pour la première fois ou modifie sa configuration.
Les commandes utilisent la ressource chatAppConfig de l'API Google Workspace Add-ons.
Avant de commencer
- Installez gcloud CLI. Si vous avez déjà installé la gcloud CLI, assurez-vous de disposer de la dernière version en exécutant la commande
gcloud components update. Connectez-vous à la gcloud CLI avec votre compte utilisateur. Les commandes ne sont pas compatibles avec les comptes de service.
gcloud auth loginDéfinissez le projet Cloud de votre application Chat comme projet par défaut de gcloud CLI. Utilisez l'ID du projet, car les commandes n'acceptent pas de numéro de projet.
gcloud config set project PROJECT_IDVous pouvez également ajouter l'option
--projectà chaque commande.Activez l'API Google Workspace Add-ons dans le projet Cloud :
gcloud services enable gsuiteaddons.googleapis.comAssurez-vous de disposer des rôles IAM (Identity and Access Management) suivants sur le projet Cloud :
- Développeur de modules complémentaires Google Workspace (
roles/gsuiteaddons.developer) pour afficher et modifier la configuration, ou Lecteur de modules complémentaires Google Workspace (roles/gsuiteaddons.reader) pour l'afficher uniquement. Ces rôles incluent les autorisations listées dans Prérequis et authentification. - Consommateur Service Usage (
roles/serviceusage.serviceUsageConsumer). La gcloud CLI utilise le projet Cloud comme projet de quota pour ses requêtes, ce qui nécessite l'autorisationserviceusage.services.use.
Les rôles Propriétaire et Éditeur incluent toutes ces autorisations. Les rôles Propriétaire d'applications Chat et Lecteur d'applications Chat, qui permettent d'accéder à la page de configuration dans la console Google Cloud, ne sont pas suffisants.
- Développeur de modules complémentaires Google Workspace (
Afficher la configuration
Pour afficher la configuration de votre application Chat, exécutez la commande describe :
gcloud beta workspace-add-ons chat-app-config describeLe résultat ressemble à ce qui suit :
avatarUri: https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png
description: Helps manage tasks and schedules
displayName: Cymbal Assistant
errorLoggingEnabled: true
interactiveFeatureConfig:
allowlistedTestingPrincipals:
- user@example.com
appCommands:
- command: /help
commandId: 1
commandType: SLASH_COMMAND
description: Show available commands
connectionConfig:
httpEndpointConfig:
commonUrl: https://example.com/chat
supportsMultiuserSpaces: true
urlPatterns:
- hostPattern: example.com
pathPrefix: tasks/
name: projects/123456789012/chatAppConfig
state: ACTIVE
Si le projet Cloud ne dispose pas encore d'une application Chat, la commande réussit et n'affiche que le champ name de la configuration :
name: projects/123456789012/chatAppConfig
Pour modifier le résultat, ajoutez l'un des indicateurs suivants :
--format=json: affiche la configuration au format JSON.--view=basic: omet les paramètres des fonctionnalités interactives (interactiveFeatureConfig).--format="value(displayName)": n'affiche que le nom à afficher, ou une ligne vide si le projet Cloud n'a pas encore d'application Chat. Une application Chat configurée possède toujours un nom à afficher. Vous pouvez donc utiliser cet indicateur dans un script pour vérifier si une application Chat existe.
Mettre à jour la configuration
Pour configurer une application Chat pour la première fois ou pour modifier sa configuration, exécutez la commande update. Spécifiez les paramètres à l'aide d'options ou dans un fichier de configuration. Vous ne pouvez pas combiner les deux dans une même commande.
La première fois que vous exécutez la commande pour un projet Cloud, vous devez spécifier au moins un nom à afficher et une description. Sauf si vous définissez l'état sur "Désactivé", l'application Chat est active dès que la commande est terminée. Les personnes que vous listez comme testeurs peuvent alors la trouver et l'utiliser.
Utiliser des options
L'exemple suivant configure une application Chat qui reçoit des événements sur un point de terminaison HTTP :
gcloud beta workspace-add-ons chat-app-config update \
--display-name="Quickstart App" \
--description="Quickstart app" \
--avatar-uri=https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png \
--http-endpoint-url=HTTP_ENDPOINT_URL \
--supports-multiuser-spaces \
--add-allowlisted-testing-principals=USER_EMAIL \
--error-logging-enabledRemplacez les éléments suivants :
HTTP_ENDPOINT_URL: URL HTTPS qui reçoit les objets d'événement de Chat.USER_EMAIL: adresse e-mail d'une personne ou d'un groupe de votre organisation Google Workspace qui peut installer et tester l'application Chat, par exemple votre propre adresse e-mail.
La commande affiche la configuration mise à jour.
Le tableau suivant liste les options des paramètres de la page Configuration de l'API Chat dans la console Google Cloud. Pour en savoir plus sur chaque option, consultez la documentation de référence sur la commande update.
| Paramètre dans la console Google Cloud | Drapeaux |
|---|---|
| Nom de l'application | --display-name |
| URL de l'avatar | --avatar-uri par l'URL HTTPS d'une image qui répond aux exigences concernant les avatars, ou --clear-avatar-uri pour utiliser l'avatar par défaut. |
| Description | --description |
| État de l'application | --state=active ou --state=disabled |
| Syntaxe de balisage | --markup-syntax=markdown ou --markup-syntax=chat |
| Rejoindre des espaces et des conversations de groupe | --supports-multiuser-spaces ou --no-supports-multiuser-spaces |
| Paramètres de connexion | Voici les différents types de visibilité :
|
| Visibilité | --add-allowlisted-testing-principals, --remove-allowlisted-testing-principals et --clear-allowlisted-testing-principals |
| Consigner les erreurs dans Logging | --error-logging-enabled ou --no-error-logging-enabled |
Les commandes, les aperçus de liens et les points de terminaison distincts pour chaque déclencheur n'ont pas d'indicateurs. Pour les configurer, utilisez un fichier de configuration.
Par exemple, pour désactiver votre application Chat sans modifier ses autres paramètres, exécutez la commande suivante. Pour le réactiver, utilisez --state=active.
gcloud beta workspace-add-ons chat-app-config update --state=disabledUtiliser un fichier de configuration
Pour conserver la configuration dans un fichier ou pour configurer des paramètres qui n'ont pas d'options, transmettez un fichier YAML ou JSON à la commande update. Le fichier utilise les champs de la ressource chatAppConfig, qui sont les mêmes que ceux affichés par la commande describe.
Créez un fichier contenant les paramètres à mettre à jour. Par exemple, créez un fichier nommé
chat_app_config.yamlavec le contenu suivant :displayName: Cymbal Assistant description: Helps manage tasks and schedules avatarUri: https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png state: ACTIVE errorLoggingEnabled: true interactiveFeatureConfig: supportsMultiuserSpaces: true connectionConfig: httpEndpointConfig: commonUrl: https://example.com/chat appCommands: - commandId: 1 commandType: SLASH_COMMAND command: /help description: Show available commands urlPatterns: - hostPattern: example.com pathPrefix: tasks/ allowlistedTestingPrincipals: - USER_EMAILRemplacez
USER_EMAILpar l'adresse e-mail d'une personne ou d'un groupe de votre organisation Google Workspace qui peut installer et tester l'application Chat.Exécutez la commande
updateavec l'option--config-file.gcloud beta workspace-add-ons chat-app-config update \ --config-file=chat_app_config.yaml
Pour partir de la configuration actuelle d'une application Chat, enregistrez le résultat de la commande describe dans un fichier :
gcloud beta workspace-add-ons chat-app-config describe > chat_app_config.yamlEnsuite, modifiez le fichier, supprimez les champs que vous ne souhaitez pas modifier et transmettez le fichier à la commande update. Si le fichier contient un paramètre que la commande ne peut pas mettre à jour, la commande échoue. Pour en savoir plus, consultez la section Limites.
La commande update ignore le champ name du fichier. Il met toujours à jour le projet Cloud que vous avez défini dans gcloud CLI. Vous pouvez donc utiliser le même fichier pour configurer une application Chat dans un autre projet Cloud.
Comment la commande applique vos modifications
- Seuls les paramètres que vous spécifiez sont modifiés. Avec des options, la commande modifie les paramètres des options que vous transmettez. Avec un fichier de configuration, elle modifie les champs qui se trouvent dans le fichier. Le fichier n'a donc pas besoin de contenir l'intégralité de la configuration. Les paramètres de connexion constituent une exception : le type de connexion que vous définissez remplace le type actuel, et l'édition Dialogflow que vous définissez remplace l'intégralité de la configuration Dialogflow.
- Les listes sont remplacées dans leur intégralité. Si le fichier contient le champ
appCommands,urlPatternsouallowlistedTestingPrincipals, la liste du fichier remplace la liste actuelle. Pour ajouter ou supprimer des testeurs individuellement, utilisez plutôt les options--add-allowlisted-testing-principalset--remove-allowlisted-testing-principals. - Une valeur vide efface un paramètre. Par exemple, un fichier contenant
urlPatterns: []sousinteractiveFeatureConfigsupprime tous les formats d'URL d'aperçu de lien. - Une commande qui échoue ne modifie rien. Si une valeur n'est pas valide, la commande affiche l'erreur et laisse la configuration telle quelle.
- Les requêtes sont soumises à une limitation du débit. L'API limite le nombre de requêtes de lecture et de mise à jour par minute, pour chaque projet Cloud et pour chaque organisation. Chaque commande
updateenvoie une requête de mise à jour. Si vous ajoutez ou supprimez des testeurs avec des options, la commande envoie également une requête de lecture. Pour modifier plusieurs paramètres, transmettez-les dans une seule commande ou un seul fichier au lieu d'exécuter une commande pour chaque paramètre.
Limites
- Les commandes ne sont compatibles qu'avec les applications Chat créées en tant que modules complémentaires Google Workspace.
- Les commandes ne sont pas compatibles avec les comptes de service ni l'emprunt d'identité d'un compte de service. Vous devez vous connecter à la gcloud CLI avec un compte utilisateur.
- Un projet Cloud ne comporte qu'une seule configuration d'application Chat, et les commandes ne peuvent pas la supprimer. Pour empêcher les utilisateurs d'utiliser l'application Chat, désactivez-la ou supprimez le projet Cloud.
- Une mise à jour s'applique à l'application Chat en direct. Les commandes ne disposent pas d'un mode brouillon ou dry run.
- Lorsqu'une application Chat est publiée ou en cours d'examen sur Google Workspace Marketplace, les commandes ne peuvent pas modifier son nom à afficher, son avatar, sa description, ses commandes ni les formats d'URL des aperçus de liens.
- Les commandes sont compatibles avec les paramètres de la ressource
chatAppConfig. Pour configurer un paramètre que la ressource n'inclut pas, utilisez la console Google Cloud.
Résoudre les problèmes
Si une commande échoue, recherchez le texte du message d'erreur dans le tableau suivant. Si le message commence par un état tel que INVALID_ARGUMENT, l'API des modules complémentaires Google Workspace a rejeté la requête, et le texte après l'état décrit le problème.
| Le message d'erreur contient | Cause | Solution |
|---|---|---|
Invalid choice: 'chat-app-config' ou Invalid choice: 'workspace-add-ons' |
La commande n'inclut pas beta, ou votre version de la gcloud CLI n'inclut pas les commandes. |
Commencez la commande par gcloud beta workspace-add-ons chat-app-config. Si l'erreur persiste, mettez à jour la gcloud CLI vers la dernière version. |
PROJECT ID |
Le projet est défini sur un numéro de projet. | Définissez le projet sur l'ID du projet. |
Failed to parse value(s) in protobuf |
Le fichier de configuration contient un champ que la gcloud CLI ne reconnaît pas. Le message d'erreur indique le nom du champ. | Comparez le nom du champ avec le résultat de la commande describe. Si le champ est nouveau, mettez à jour la gcloud CLI vers la dernière version. |
does not have permission to access projects instance |
L'API a refusé la requête. Le texte qui suit ce message en indique la raison. par exemple :
|
Vérifiez les exigences dans la section Avant de commencer. |
INVALID_ARGUMENT |
Une valeur n'est pas valide. Par exemple, le nom à afficher doit comporter entre 3 et 25 caractères, et la description entre 1 et 40 caractères. Si le message contient not found or deleted, l'ID du projet n'est pas correct. |
Corrigez la valeur décrite dans le message d'erreur, puis exécutez à nouveau la commande. |
FAILED_PRECONDITION |
L'application Chat n'autorise pas la requête. Par exemple, elle n'est pas conçue comme un module complémentaire Google Workspace ou elle est publiée sur Google Workspace Marketplace et le paramètre ne peut pas être modifié. | Suivez les instructions du message d'erreur. Pour configurer une application Chat qui n'est pas un module complémentaire Google Workspace, utilisez la console Google Cloud ou convertissez-la. |
RESOURCE_EXHAUSTED ou 429 |
L'API a reçu trop de requêtes pour le projet Cloud ou pour votre organisation en peu de temps. | Patientez une minute, puis exécutez à nouveau la commande. |
Configurer votre application Chat à l'aide de l'API Google Workspace Add-ons
Au lieu de configurer manuellement votre application Chat dans la console Google Cloud, vous pouvez lire et mettre à jour de manière programmatique la configuration d'une application Chat créée en tant que module complémentaire Google Workspace à l'aide de la ressource chatAppConfig dans l'Google Workspace add-ons API.
chatAppConfig est une ressource singleton qui existe toujours pour chaque projet Cloud. Avant d'enregistrer une configuration pour la première fois, la ressource contient une configuration vide (qui est également ce que GetChatAppConfig renvoie si vous lisez la ressource avant le premier enregistrement). Comme la ressource existe déjà, vous n'avez pas besoin de la créer séparément. Utilisez UpdateChatAppConfig pour enregistrer la configuration initiale et mettre à jour une configuration existante.
Prérequis et authentification
Avant d'appeler GetChatAppConfig ou UpdateChatAppConfig, remplissez les conditions préalables suivantes :
- Activez l'API Google Workspace Add-ons (
gsuiteaddons.googleapis.com) dans votre projet Cloud. Vous pouvez éventuellement activer l'API Google Chat (chat.googleapis.com) si vous souhaitez afficher ou mettre à jour la configuration de l'application Chat dans la console Google Cloud ou appeler l'API Chat. - S'authentifier en tant qu'utilisateur humain avec un identifiant OAuth 2.0 incluant le champ d'application
https://www.googleapis.com/auth/cloud-platform. L'authentification par compte de service n'est pas compatible avec les méthodeschatAppConfig. - Assurez-vous que l'utilisateur authentifié dispose des autorisations IAM (Identity and Access Management) requises sur le projet Cloud cible :
gsuiteaddons.chatAppConfigs.getetchat.bots.getpour lire la configuration (GetChatAppConfig).gsuiteaddons.chatAppConfigs.update,chat.bots.updateetchat.bots.getpour mettre à jour la configuration (UpdateChatAppConfig).
- Si vous utilisez une bibliothèque cliente, installez la dernière version de la bibliothèque cliente de l'API Google Workspace Add-ons pour votre langage. Pour obtenir la liste des bibliothèques clientes, consultez la documentation de référence de l'API des modules complémentaires Google Workspace.
Mettre à jour la configuration d'une application Chat
Pour configurer une application Chat pour la première fois ou mettre à jour une configuration existante, envoyez une requête PATCH (UpdateChatAppConfig) à la ressource singleton chatAppConfig de votre projet Cloud :
- Pour l'enregistrement initial d'un projet cloud avec un
chatAppConfigvide,displayName(3 à 25 caractères) etdescription(1 à 40 caractères) sont requis. Si vous omettezinteractiveFeatureConfiglors de l'enregistrement initial, l'application Chat est configurée comme non interactive. - Pour les mises à jour ultérieures, utilisez le paramètre de requête facultatif
updateMaskpour spécifier les champs à mettre à jour, séparés par une virgule (ou omettezupdateMaskpour mettre à jour tous les champs fournis). La mise à jour d'un champ répété (appCommands,urlPatternsouallowlistedTestingPrincipals) remplace l'intégralité de la liste.
PATCH https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?updateMask=displayName,description,avatarUri,state,errorLoggingEnabled,markupSyntax,interactiveFeatureConfig
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
{
"name": "projects/PROJECT_NUMBER/chatAppConfig",
"displayName": "Cymbal Assistant",
"description": "Helps manage tasks and schedules",
"avatarUri": "https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png",
"state": "ACTIVE",
"errorLoggingEnabled": true,
"markupSyntax": "MARKUP_SYNTAX_MARKDOWN",
"interactiveFeatureConfig": {
"supportsMultiuserSpaces": false,
"connectionConfig": {
"httpEndpointConfig": {
"commonUrl": "https://example.com/chat"
}
},
"appCommands": [
{
"commandType": "SLASH_COMMAND",
"commandId": 1,
"command": "/help",
"description": "Show available commands",
"dialogEnabled": false
}
],
"urlPatterns": [
{
"hostPattern": "example.com",
"pathPrefix": "tasks/"
}
],
"allowlistedTestingPrincipals": [
"USER_EMAIL"
]
}
}
Remplacez les éléments suivants dans l'URL, l'en-tête et le corps de la requête :
PROJECT_NUMBER: numéro du projet Cloud hébergeant votre application Chat.ACCESS_TOKEN: jeton d'accès OAuth 2.0 d'un utilisateur autorisé avec le champ d'applicationhttps://www.googleapis.com/auth/cloud-platform.USER_EMAIL: adresse e-mail ou groupe Google de votre organisation Google Workspace à ajouter à la liste d'autorisation pour tester l'application Chat (par exemple, votre propre adresse e-mail).- Les exemples de champs de configuration dans le corps de la requête (tels que
displayName,description,avatarUrietinteractiveFeatureConfig, y compris la configuration de votre point de terminaison, les commandes, les formats d'URL d'aperçu des liens et les comptes principaux de test) avec les valeurs de votre application Chat. Pour en savoir plus sur tous les champs et options de point de terminaison compatibles, consultez la documentation de référence RESTprojects.chatAppConfigetprojects.chatAppConfig.patch.
Obtenir la configuration d'une application Chat
Pour lire la configuration actuelle de l'application Chat pour un projet Cloud, appelez GetChatAppConfig.
Vous pouvez transmettre le paramètre de requête facultatif view (ChatAppConfigView) :
BASIC(par défaut) : renvoie les métadonnées de base sansinteractiveFeatureConfig.FULL: renvoie tous les champs de configuration, y comprisinteractiveFeatureConfig.
Si la configuration de l'application Chat n'a pas encore été enregistrée pour le projet Cloud, la méthode renvoie un objet ChatAppConfig vide.
HTTP
GET https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?view=FULL
Authorization: Bearer ACCESS_TOKEN
Node.js
const {GSuiteAddOnsClient} = require('@google-cloud/gsuiteaddons').v1;
const client = new GSuiteAddOnsClient();
async function getChatAppConfig() {
const [response] = await client.getChatAppConfig({
name: 'projects/PROJECT_NUMBER/chatAppConfig',
view: 'FULL',
});
console.log(JSON.stringify(response, null, 2));
}
getChatAppConfig();
Python
from google.cloud import gsuiteaddons_v1
client = gsuiteaddons_v1.GSuiteAddOnsClient()
request = gsuiteaddons_v1.GetChatAppConfigRequest(
name="projects/PROJECT_NUMBER/chatAppConfig",
view=gsuiteaddons_v1.GetChatAppConfigRequest.ChatAppConfigView.FULL,
)
response = client.get_chat_app_config(request=request)
print(response)
Limites d'utilisation
Les méthodes chatAppConfig sont soumises à des quotas par projet. Si vous dépassez un quota, la requête échoue avec un code d'état HTTP 429: Too many requests. Pour connaître les limites de quota, consultez Limites d'utilisation de l'API Google Workspace Add-ons.
Résoudre les erreurs
Si une requête chatAppConfig échoue, vérifiez le code d'état HTTP et le champ message dans la réponse d'erreur. Le tableau suivant liste les erreurs courantes, leurs causes et la manière de les résoudre.
| Code d'état HTTP | Causes courantes | Solution |
|---|---|---|
400: Bad Request (INVALID_ARGUMENT) |
|
Vérifiez le champ message pour identifier le champ non valide, puis corrigez la requête. Pour connaître les champs et les valeurs acceptés, consultez la documentation de référence sur projects.chatAppConfig. |
400: Bad Request (FAILED_PRECONDITION) |
|
|
403: Forbidden (PERMISSION_DENIED) |
|
|
404: Not Found (NOT_FOUND) |
Le projet Cloud indiqué dans le nom de la ressource n'existe pas, ou l'utilisateur authentifié ne peut pas y accéder. | Vérifiez que le nom de la ressource utilise le bon numéro de projet au format projects/PROJECT_NUMBER/chatAppConfig et que l'utilisateur a accès au projet Cloud. |
429: Too Many Requests (RESOURCE_EXHAUSTED) |
Le quota par projet est dépassé. | Patientez et réessayez d'envoyer la requête ultérieurement. Pour connaître les limites, consultez Limites d'utilisation. |
Remarques concernant les modules complémentaires Google Workspace existants
Les applications Chat nécessitent une configuration différente de celle des modules complémentaires Google Workspace qui étendent d'autres applications Google Workspace. Si votre module complémentaire étend d'autres applications Google Workspace, tenez compte des exigences suivantes pour configurer l'application Chat :
- Les utilisateurs individuels et les administrateurs Google Workspace doivent pouvoir installer votre module complémentaire depuis Marketplace. Vous configurez ces paramètres d'installation dans le SDK Marketplace.
- Les applications Chat n'utilisent pas le nom ni le logo que vous configurez pour les autres applications Google Workspace dans l'objet
addons.commondu fichier manifeste. - Pour les modules complémentaires publiés sur Google Workspace Marketplace, vous ne pouvez pas enregistrer de brouillon des modifications apportées aux paramètres de configuration de l'API Google Chat. Une fois que vous avez mis à jour et enregistré les paramètres de configuration de l'API Chat, l'application Chat mise à jour est immédiatement disponible pour tous les utilisateurs existants. Pour mettre à jour votre fiche Marketplace, vous pouvez créer un brouillon avant d'envoyer des modifications.
- Si vous avez créé votre module complémentaire à l'aide d'Apps Script :
- Vous devez utiliser le même ID de déploiement Apps Script que celui que vous utilisez pour le reste de la configuration de votre module complémentaire.
- Vous ne pouvez pas utiliser l'éditeur Apps Script pour installer des déploiements de test dans Chat. Vous devez plutôt les installer directement depuis l'interface utilisateur de Chat.
- Si vous avez créé votre module complémentaire à l'aide d'un service HTTP, omettez les détails de configuration de l'application Chat dans le fichier manifeste
projects.deploymentsque vous créez à l'aide de l'API des modules complémentaires Google Workspace. Les déploiements HTTP que vous spécifiez dans le SDK Google Workspace Marketplace ne sont utilisés que pour d'autres applications Google Workspace. Configurez plutôt votre application Chat dans la console Google Cloud, avec la gcloud CLI ou à l'aide de la ressourcechatAppConfigdans l'API Google Workspace Add-ons.
Autoriser d'autres personnes à configurer l'API Chat
Vous pouvez accorder à des utilisateurs spécifiques l'accès à la page de configuration de l'application Chat en leur attribuant le rôle IAM (Identity and Access Management) Google Cloud Propriétaire d'applications Chat ou Lecteur d'applications Chat. Les utilisateurs disposant de ces rôles ne peuvent pas accéder à la page de configuration des applications Chat à l'aide du tableau de bord API et services, mais ils peuvent accéder à la page de configuration en accédant à la console Google Cloud pour le projet Cloud hôte de l'application Chat comme suit :
https://console.developers.google.com/apis/api/chat.googleapis.com/hangouts-chat?project=PROJECT_ID
où PROJECT_ID est l'ID du projet Google Cloud hébergeant l'application Chat.
Articles associés
- Choisir une architecture d'application Chat
- Recevoir des interactions utilisateur et y répondre
- Tester les fonctionnalités interactives des applications Google Chat
Applications Chat qui ne sont pas des modules complémentaires : configurer l'API Google Chat
Si vous gérez une application Chat qui n'est pas un module complémentaire Google Workspace, votre configuration utilise un seul point de terminaison pour tous les événements d'interaction, plutôt que des déclencheurs par événement :
Dans la console Google Cloud, accédez à la page Configuration de l'API Chat :
Sous Fonctionnalités interactives, activez l'option Activer les fonctionnalités interactives.
Décochez l'option Créer cette application Chat en tant que module complémentaire Google Workspace. Une boîte de dialogue s'ouvre pour vous demander de confirmer. Dans la boîte de dialogue, cliquez sur Désactiver.
Sous Fonctionnalité, sélectionnez Prise en charge de l'accueil de l'application ou Rejoindre des espaces et des conversations de groupe, selon vos besoins.
Sous Paramètres de connexion, spécifiez un seul point de terminaison pour votre application Chat (URL du point de terminaison HTTP, ID de déploiement Apps Script, nom du sujet Cloud Pub/Sub ou Dialogflow).
Configurez les commandes, les prompts de démarrage, les aperçus des liens, la visibilité et les journaux (facultatif), puis cliquez sur Enregistrer.
Pour transformer une application Chat qui n'est pas un module complémentaire en module complémentaire Google Workspace qui étend Google Chat, consultez Convertir une application Google Chat en module complémentaire Google Workspace.