/setup-zoom-websockets

Référence de base pour les flux d'événements Zoom persistants. Privilégiez d'abord le routage des workflows, puis utilisez ce fichier quand les WebSockets sont plausiblement meilleurs que les webhooks.

WebSockets vs Webhooks

Choisir WebSockets quand :

• Les mises à jour en temps réel à faible latence sont critiques
• La sécurité est primordiale (banque, santé, finance)
• Vous ne voulez pas exposer de point de terminaison public
• Vous avez besoin de communication bidirectionnelle

Choisir Webhooks quand :

• Une configuration plus simple est préférée
• Petit nombre de notifications d'événements
• Infrastructure HTTP existante

Prérequis

• Application OAuth Serveur-à-Serveur dans Zoom Marketplace
• ID du compte, ID client et secret client
• Abonnement WebSocket avec événements activés

Besoin d'aide avec S2S OAuth ? Consultez la compétence zoom-oauth pour les flux d'authentification complets.

Commencez le dépannage rapidement : Utilisez le Runbook 5 minutes avant le débogage approfondi.

Démarrage rapide

1. Créer une application OAuth Serveur-à-Serveur

1. Allez à Zoom Marketplace
2. Créez une application Server-to-Server OAuth
3. Copiez l'ID du compte, l'ID client et le secret client

2. Activer l'abonnement WebSocket

1. Dans votre application, allez à Feature → Event Subscriptions
2. Ajoutez un abonnement aux événements
3. Sélectionnez WebSockets comme type de méthode
4. Sélectionnez les événements auxquels vous abonner (p. ex., meeting.created, meeting.started)
5. Enregistrez - une URL de point de terminaison sera générée

3. Se connecter via WebSocket

const WebSocket = require('ws');
const axios = require('axios');

// Step 1: Get access token
async function getAccessToken() {
  const credentials = Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString('base64');

  const response = await axios.post(
    'https://zoom.us/oauth/token',
    new URLSearchParams({
      grant_type: 'account_credentials',
      account_id: ACCOUNT_ID
    }),
    {
      headers: {
        'Authorization': `Basic ${credentials}`,
        'Content-Type': 'application/x-www-form-urlencoded'
      }
    }
  );

  return response.data.access_token;
}

// Step 2: Connect to WebSocket
async function connectWebSocket() {
  const accessToken = await getAccessToken();

  // WebSocket URL from your subscription settings
  const wsUrl = `wss://ws.zoom.us/ws?subscriptionId=${SUBSCRIPTION_ID}&access_token=${accessToken}`;

  const ws = new WebSocket(wsUrl);

  ws.on('open', () => {
    console.log('WebSocket connection established');
  });

  ws.on('message', (data) => {
    const event = JSON.parse(data);
    console.log('Event received:', event.event);

    // Handle different event types
    switch (event.event) {
      case 'meeting.started':
        console.log(`Meeting started: ${event.payload.object.topic}`);
        break;
      case 'meeting.ended':
        console.log(`Meeting ended: ${event.payload.object.uuid}`);
        break;
      case 'meeting.participant_joined':
        console.log(`Participant joined: ${event.payload.object.participant.user_name}`);
        break;
    }
  });

  ws.on('close', (code, reason) => {
    console.log(`Connection closed: ${code} - ${reason}`);
    // Implement reconnection logic
  });

  ws.on('error', (error) => {
    console.error('WebSocket error:', error);
  });

  return ws;
}

connectWebSocket();

Format des événements

Les événements reçus via WebSocket ont le même format que les événements webhook :

{
  "event": "meeting.started",
  "event_ts": 1706123456789,
  "payload": {
    "account_id": "abcD3ojkdbjfg",
    "object": {
      "id": 1234567890,
      "uuid": "abcdefgh-1234-5678-abcd-1234567890ab",
      "host_id": "xyz789",
      "topic": "Team Standup",
      "type": 2,
      "start_time": "2024-01-25T10:00:00Z",
      "timezone": "America/Los_Angeles"
    }
  }
}

Événements courants

Gestion des connexions

Keep-Alive

Les connexions WebSocket nécessitent des pulsations périodiques. Zoom fermera les connexions inactives.

// Send ping every 30 seconds
setInterval(() => {
  if (ws.readyState === WebSocket.OPEN) {
    ws.ping();
  }
}, 30000);

Reconnexion

Implémentez la reconnexion automatique pour la fiabilité :

function connectWithReconnect() {
  const ws = connectWebSocket();

  ws.on('close', () => {
    console.log('Connection lost. Reconnecting in 5 seconds...');
    setTimeout(connectWithReconnect, 5000);
  });

  return ws;
}

Limite d'une seule connexion

Important : Une seule connexion WebSocket peut être ouverte par abonnement à la fois. Ouvrir une nouvelle connexion fermera celle existante.

Références détaillées

• references/connection.md - Cycle de vie de la connexion, authentification, gestion des erreurs
• references/events.md - Référence complète des types d'événements

Dépannage

• troubleshooting/common-issues.md - Confusion URL d'abonnement, déconnexions, débogage sans événements

Exemples de dépôts

Officiel / Communauté

WebSockets vs RTMS

Ne confondez pas WebSockets avec RTMS (Realtime Media Streams) :

Pour les données audio/vidéo/transcription en temps réel, utilisez plutôt la compétence rtms.

Ressources

• Documentation WebSockets : https://developers.zoom.us/docs/api/websockets/
• Comparaison Webhooks : https://www.zoom.com/en/blog/a-guide-to-webhooks-and-websockets/
• Forum des développeurs : https://devforum.zoom.us/

Variables d'environnement

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