Configurer l'API Google Chat

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

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. Disponible dans le cadre du programme Preview développeur. 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 des modules complémentaires Google Workspace. 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 :

L'application Google Chat crée un espace pour un utilisateur.
Figure 1. Message d'attribution que Chat affiche lorsque la méthode 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 :

  1. Dans la console Google Cloud, accédez à la page de l'API Chat, puis cliquez sur la page Configuration :

    Accéder à la page de configuration de l'API Chat

  2. Sous Informations sur l'application, renseignez les champs Nom de l'application, URL de l'avatar et Description.

  3. Facultatif : Remplissez le champ Description longue (disponible dans le cadre du programme Preview développeur Google Workspace).

  4. 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.

  5. 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 :

    1. 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.

    2. 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.

    3. (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.

    4. 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.

    5. 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.

  6. 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.

  7. 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 l'API Google Workspace Add-ons

Au lieu de configurer manuellement votre application Chat dans la console Google Cloud, vous pouvez utiliser votre projet Google Cloud inscrit au programme Preview développeur Google Workspace pour 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 :

  1. Enregistrez votre projet Google Cloud dans le programme Preview développeur Google Workspace.
  2. 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.
  3. 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éthodes chatAppConfig.
  4. Assurez-vous que l'utilisateur authentifié dispose des autorisations IAM (Identity and Access Management) requises sur le projet Cloud cible :
    • gsuiteaddons.chatAppConfigs.get et chat.bots.get pour lire la configuration (GetChatAppConfig).
    • gsuiteaddons.chatAppConfigs.update et chat.bots.update pour mettre à jour la configuration (UpdateChatAppConfig).
  5. Si vous utilisez une bibliothèque cliente, téléchargez la bibliothèque cliente de la Preview développeur avec votre compte Preview développeur enregistré.

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 chatAppConfig vide, displayName (3 à 25 caractères) et description (1 à 40 caractères) sont requis. Si vous omettez interactiveFeatureConfig lors 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 updateMask pour spécifier les champs à mettre à jour, séparés par une virgule (ou omettez updateMask pour mettre à jour tous les champs fournis). La mise à jour d'un champ répété (appCommands, urlPatterns ou allowlistedTestingPrincipals) 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'application https://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, avatarUri et interactiveFeatureConfig, 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 REST projects.chatAppConfig et projects.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 sans interactiveFeatureConfig.
  • FULL : renvoie tous les champs de configuration, y compris interactiveFeatureConfig.

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)

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.common du 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 :
  • 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.deployments que 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 ou à l'aide de la ressource chatAppConfig dans 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.

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 :

  1. Dans la console Google Cloud, accédez à la page Configuration de l'API Chat :

    Accéder à la page de configuration de l'API Chat

  2. Sous Fonctionnalités interactives, activez l'option Activer les fonctionnalités interactives.

  3. 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.

  4. 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.

  5. 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).

  6. Configurez les commandes, 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.