/build-zoom-team-chat-app

Documentation de référence pour les intégrations Zoom Team Chat. À utiliser après que le workflow soit clair, notamment quand la distinction entre Team Chat API et Chatbot API importe.

À lire en premier (Critique)

Il existe deux types d'intégration différents qui ne sont pas interchangeables :

1. Team Chat API (type utilisateur)

   • Envoie les messages en tant qu'utilisateur authentifié réel
   • Utilise User OAuth (authorization_code)
   • Famille d'endpoints : /v2/chat/users/...

2. Chatbot API (type bot)

   • Envoie les messages en tant qu'identité de votre bot
   • Utilise Client Credentials (client_credentials)
   • Famille d'endpoints : /v2/im/chat/messages

Si vous choisissez le mauvais type au départ, l'authentification/scopes/endpoints ne correspondent pas et l'implémentation échoue.

Documentation officielle : https://developers.zoom.us/docs/team-chat/
Documentation Chatbot : https://developers.zoom.us/docs/team-chat/chatbot/extend/
Référence API : https://developers.zoom.us/docs/api/rest/reference/chatbot/

Liens rapides

Nouveau sur Team Chat ? Suivez ce parcours :

1. Démarrer - Chemin rapide complet (type utilisateur vs type bot)
2. Choisir votre API - Team Chat API vs Chatbot API
3. Configuration d'environnement - Identifiants, scopes, configuration d'app
4. Configuration OAuth - Flux d'authentification complet
5. Envoyer le premier message - Code fonctionnel pour envoyer des messages

Références :

• Cartes de message Chatbot - Référence complète des composants de carte
• Événements Webhook - Tous les types d'événements webhook
• Référence API - Endpoints, méthodes, paramètres
• Exemples d'applications - 10+ applications officielles
• Index intégré - voir la section ci-dessous dans ce fichier

Vous avez des problèmes ?

• Erreurs d'authentification → Dépannage OAuth
• Webhook ne reçoit pas les événements → Guide de configuration Webhook
• Les messages ne s'envoient pas → Problèmes courants
• Commencer par des vérifications rapides → Runbook 5 minutes

Vérification OAuth endpoint :

• URL d'autorisation : https://zoom.us/oauth/authorize
• URL token : https://zoom.us/oauth/token
• Si /oauth/token retourne 404/HTML, utilisez https://zoom.us/oauth/token.

Construire des bots interactifs ?

• Actions bouton - Gérer les clics de bouton
• Soumissions de formulaires - Traiter les données de formulaire
• Commandes slash - Créer des commandes personnalisées

Décision rapide : Quelle API ?

Team Chat API (Niveau utilisateur)

• Les messages apparaissent comme envoyés par un utilisateur authentifié
• Requiert User OAuth (flux authorization_code)
• Endpoint : POST https://api.zoom.us/v2/chat/users/me/messages
• Scopes : chat_message:write, chat_channel:read

Chatbot API (Niveau bot)

• Les messages apparaissent comme envoyés par votre bot
• Requiert le grant Client Credentials
• Endpoint : POST https://api.zoom.us/v2/im/chat/messages
• Scopes : imchat:bot (ajouté automatiquement)
• Cartes enrichies : boutons, formulaires, listes déroulantes, images

Prérequis

Configuration requise

• Compte Zoom
• Propriétaire de compte, administrateur, ou rôle Zoom for developers activé
  • Pour activer : User Management → Roles → Role Settings → Advanced features → Activer Zoom for developers

Créer une app Zoom

1. Allez à Zoom App Marketplace
2. Cliquez sur Develop → Build App
3. Sélectionnez General App (OAuth)

⚠️ N'utilisez PAS Server-to-Server OAuth - Les apps S2S n'ont pas la fonctionnalité Chatbot/Team Chat. Seule General App (OAuth) supporte les chatbots.

Identifiants requis

De Zoom Marketplace → Votre app :

Voir : Guide de configuration d'environnement pour les étapes de configuration complètes.

Démarrage rapide : Team Chat API

Envoyer un message en tant qu'utilisateur :

// 1. Obtenir le token d'accès via OAuth
const accessToken = await getOAuthToken(); // Voir examples/oauth-setup.md

// 2. Envoyer un message au canal
const response = await fetch('https://api.zoom.us/v2/chat/users/me/messages', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: 'Hello from CI/CD pipeline!',
    to_channel: 'CHANNEL_ID'
  })
});

const data = await response.json();
// { "id": "msg_abc123", "date_time": "2024-01-15T10:30:00Z" }

Exemple complet : Guide d'envoi de message

Démarrage rapide : Chatbot API

Construire un chatbot interactif :

// 1. Obtenir le token du chatbot (client_credentials)
async function getChatbotToken() {
  const credentials = Buffer.from(
    `${CLIENT_ID}:${CLIENT_SECRET}`
  ).toString('base64');

  const response = await fetch('https://zoom.us/oauth/token', {
    method: 'POST',
    headers: {
      'Authorization': `Basic ${credentials}`,
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: 'grant_type=client_credentials'
  });

  return (await response.json()).access_token;
}

// 2. Envoyer un message chatbot avec boutons
const response = await fetch('https://api.zoom.us/v2/im/chat/messages', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    robot_jid: process.env.ZOOM_BOT_JID,
    to_jid: payload.toJid,           // From webhook
    account_id: payload.accountId,   // From webhook
    content: {
      head: {
        text: 'Build Notification',
        sub_head: { text: 'CI/CD Pipeline' }
      },
      body: [
        { type: 'message', text: 'Deployment successful!' },
        {
          type: 'fields',
          items: [
            { key: 'Branch', value: 'main' },
            { key: 'Commit', value: 'abc123' }
          ]
        },
        {
          type: 'actions',
          items: [
            { text: 'View Logs', value: 'view_logs', style: 'Primary' },
            { text: 'Dismiss', value: 'dismiss', style: 'Default' }
          ]
        }
      ]
    }
  })
});

Exemple complet : Guide de configuration Chatbot

Fonctionnalités principales

Team Chat API

Chatbot API

Événements Webhook (Chatbot API)

Voir : Référence des événements Webhook

Composants de carte de message

Construire des messages interactifs enrichis avec ces composants :

Voir : Référence des cartes de message pour le catalogue complet des composants

Modèles d'architecture

Cycle de vie du Chatbot

L'utilisateur tape /command → Webhook reçoit bot_notification
                            ↓
                     payload.cmd = "entrée de l'utilisateur"
                            ↓
                     Traiter la commande
                            ↓
                     Envoyer la réponse via sendChatbotMessage()

Modèle d'intégration LLM

case 'bot_notification': {
  const { toJid, cmd, accountId } = payload;

  // 1. Appeler votre LLM
  const llmResponse = await callClaude(cmd);

  // 2. Envoyer la réponse
  await sendChatbotMessage(toJid, accountId, {
    body: [{ type: 'message', text: llmResponse }]
  });
}

Voir : Guide d'intégration LLM

Exemples d'applications

Voir : Guide des exemples d'applications pour l'analyse de tous les 10 exemples

Opérations courantes

Envoyer un message au canal

// Team Chat API
await fetch('https://api.zoom.us/v2/chat/users/me/messages', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${token}` },
  body: JSON.stringify({
    message: 'Hello!',
    to_channel: 'CHANNEL_ID'
  })
});

Gérer le clic de bouton

// Gestionnaire webhook
case 'interactive_message_actions': {
  const { actionItem, toJid, accountId } = payload;

  if (actionItem.value === 'approve') {
    await sendChatbotMessage(toJid, accountId, {
      body: [{ type: 'message', text: '✅ Approved!' }]
    });
  }
}

Vérifier la signature Webhook

function verifyWebhook(req) {
  const message = `v0:${req.headers['x-zm-request-timestamp']}:${JSON.stringify(req.body)}`;
  const hash = crypto.createHmac('sha256', process.env.ZOOM_VERIFICATION_TOKEN)
    .update(message)
    .digest('hex');
  return req.headers['x-zm-signature'] === `v0=${hash}`;
}

Déploiement

ngrok pour développement local

# Installer ngrok
npm install -g ngrok

# Exposer le serveur local
ngrok http 4000

# Utiliser l'URL HTTPS comme Bot Endpoint URL dans Zoom Marketplace
# Exemple : https://abc123.ngrok.io/webhook

Déploiement en production

Voir : Guide de déploiement pour :

• Configuration du reverse proxy Nginx
• Configuration du chemin de base
• Configuration de l'URI de redirection OAuth

Limitations

Bonnes pratiques de sécurité

1. Vérifier les signatures webhook - Toujours valider en utilisant l'en-tête x-zm-signature
2. Assainir les messages - Limiter à 4 096 caractères, supprimer les caractères de contrôle
3. Valider les JIDs - Vérifier le format : user@domain ou channel@domain
4. Variables d'environnement - Ne jamais coder en dur les identifiants
5. Utiliser HTTPS - Requis pour les webhooks de production

Voir : Bonnes pratiques de sécurité

Bibliothèque de documentation complète

Concepts fondamentaux (À commencer !)

• Guide de sélection API - Choisir Team Chat API vs Chatbot API
• Configuration d'environnement - Guide des identifiants complet
• Flux d'authentification - OAuth vs Client Credentials
• Architecture Webhook - Comment fonctionnent les webhooks
• Structure de carte de message - Hiérarchie des composants de carte

Exemples complets

• Configuration OAuth - Implémentation OAuth complète
• Envoyer un message - Envoi de messages Team Chat API
• Configuration Chatbot - Chatbot complet avec webhooks
• Actions bouton - Gérer les boutons interactifs
• Soumissions de formulaires - Traiter les données de formulaire
• Commandes slash - Créer des commandes personnalisées
• Intégration LLM - Intégration Claude/GPT
• Alertes planifiées - Cron + webhooks entrants
• Gestion de canaux - Créer/gérer les canaux

Références

• Référence API - Tous les endpoints et méthodes
• Événements Webhook - Référence complète des événements
• Cartes de message - Tous les composants de carte
• Exemples d'applications - Analyse des 10 exemples officiels
• Codes d'erreur - Guide de gestion d'erreur

Dépannage

• Problèmes OAuth - Échecs d'authentification
• Problèmes Webhook - Débogage webhook
• Problèmes courants - Diagnostics rapides

Ressources

• Docs officielles : https://developers.zoom.us/docs/team-chat/
• Référence API : https://developers.zoom.us/docs/api/rest/reference/chatbot/
• Forum développeur : https://devforum.zoom.us/
• App Marketplace : https://marketplace.zoom.us/

Besoin d'aide ? Commencez par la section Index intégré ci-dessous pour une navigation complète.

Index intégré

Cette section a été migrée depuis SKILL.md.

Guide de navigation complète pour la skill Zoom Team Chat.

Parcours de démarrage rapide

• Commencez ici : Démarrer
• Dépannage rapide d'abord : Runbook 5 minutes

Chemin 1 : Team Chat API (Messaging au niveau utilisateur)

Pour envoyer des messages en tant que compte utilisateur.

1. Guide de sélection API - Confirmer que Team Chat API est appropriée
2. Configuration d'environnement - Obtenir les identifiants
3. Exemple de configuration OAuth - Implémenter l'authentification
4. Exemple d'envoi de message - Envoyer votre premier message

Chemin 2 : Chatbot API (Bots interactifs)

Pour construire des chatbots interactifs avec des messages enrichis.

1. Guide de sélection API - Confirmer que Chatbot API est appropriée
2. Configuration d'environnement - Obtenir les identifiants (y compris Bot JID)
3. Architecture Webhook - Comprendre les événements webhook
4. Exemple de configuration Chatbot - Construire votre premier bot
5. Référence des cartes de message - Créer des messages enrichis

Concepts fondamentaux

Compréhension essentielle pour les deux APIs.

Exemples complets

Code fonctionnel pour les scénarios courants.

Authentification

Opérations de base

Fonctionnalités interactives (Chatbot API)

Intégration avancée

Références

Documentation API

Exemples d'applications

Guides spécialisés

Dépannage

Modèles d'architecture

Cycle de vie du Chatbot

Action utilisateur → Webhook → Traitement → Réponse

Modèle d'intégration LLM

Entrée utilisateur → Chatbot reçoit → Appel LLM → Envoyer réponse

Modèle de workflow d'approbation

Demande → Envoyer carte avec boutons → Utilisateur clique → Mettre à jour le statut → Notifier

Cas d'usage courants

Notifications

• Notifications de build CI/CD
• Alertes de monitoring de serveur
• Rapports planifiés
• Vérifications de santé du système

Workflows

• Demandes d'approbation
• Affectation de tâches
• Mises à jour de statut
• Soumissions de formulaires

Intégrations

• Assistants alimentés par LLM
• Requêtes de base de données
• Intégration API externe
• Partage de fichiers/images

Automatisation

• Messages planifiés
• Réponses automatiques
• Collecte de données
• Génération de rapports

Liens de ressources

Documentation officielle

• Docs Team Chat - Aperçu officiel
• Docs Chatbot - Guide Chatbot
• Référence API - Docs API REST
• App Marketplace - Créer et gérer les apps

Exemples de code

• Chatbot Quickstart - Tutoriel officiel
• Claude Chatbot - Intégration IA
• Unsplash Chatbot - Bot de recherche d'images
• ERP Chatbot - Intégration d'entreprise
• Task Manager - Application CRUD complète

Outils

• Card Builder - Concepteur visuel de cartes
• ngrok - Test webhook local
• Postman - Test API

Communauté

• Forum développeur - Poser des questions
• GitHub Discussions - Support communautaire
• Support développeur - Support officiel

Statut de la documentation

✅ Complète

• Entrée principale skill.md
• Guide de sélection API
• Configuration d'environnement
• Architecture Webhook
• Exemple de configuration Chatbot (code fonctionnel complet)
• Référence des cartes de message
• Dépannage des problèmes courants

📝 En attente (Priorité haute)

• Exemple de configuration OAuth
• Exemple d'envoi de message
• Exemple d'actions bouton
• Exemple d'intégration LLM
• Référence des événements Webhook
• Référence API
• Analyse des exemples d'applications

📋 Planifiée (Priorité plus basse)

• Exemple de soumissions de formulaires
• Exemples de gestion de canaux
• Exemple d'intégration de base de données
• Référence des codes d'erreur
• Guide des limites de taux
• Dépannage du déploiement

Checklist de démarrage

Pour Team Chat API

• [ ] Lire Guide de sélection API
• [ ] Compléter Configuration d'environnement
• [ ] Obtenir Client ID, Client Secret
• [ ] Ajouter les scopes requis
• [ ] Implémenter le flux OAuth
• [ ] Envoyer le premier message

Pour Chatbot API

• [ ] Lire Guide de sélection API
• [ ] Compléter Configuration d'environnement
• [ ] Obtenir Client ID, Client Secret, Bot JID, Secret Token, Account ID
• [ ] Activer Team Chat dans Features
• [ ] Configurer Bot Endpoint URL et Slash Command
• [ ] Configurer ngrok pour le test local
• [ ] Implémenter le gestionnaire webhook
• [ ] Envoyer le premier message chatbot

Historique des versions

• v1.0 (2026-02-09) - Documentation complète initiale
  • Concepts fondamentaux (sélection API, configuration d'environnement, webhooks)
  • Exemple de configuration chatbot complet
  • Référence des cartes de message
  • Dépannage des problèmes courants

Support

Utilisez ce SKILL.md comme hub de navigation pour la sélection Team Chat API, la configuration, les exemples et le dépannage.

Variables d'environnement

• Voir references/environment-variables.md pour les clés .env standardisées et où trouver chaque valeur.