Connettore Zoom
Collega Zoom a Brevo tramite Tajo per sincronizzare automaticamente i partecipanti ai meeting e i partecipanti ai webinar come contatti, attivare sequenze di follow-up post-meeting e tracciare metriche di engagement per le tue automazioni marketing.
Panoramica
| Proprietà | Valore |
|---|---|
| Piattaforma | Zoom |
| Categoria | Video Conferencing (Custom) |
| Complessità di setup | Media |
| Integrazione ufficiale | No |
| Dati sincronizzati | Partecipanti, Eventi, Webinar, Contatti |
| Metodo di autenticazione | OAuth 2.0 / Server-to-Server OAuth |
Funzionalità
- Sync partecipanti - Crea automaticamente contatti Brevo dai partecipanti ai meeting
- Cattura partecipanti ai webinar - Sincronizza iscritti e partecipanti ai webinar
- Trigger eventi meeting - Attiva automazioni su inizio, fine e registrazione del meeting
- Tracciamento engagement - Traccia la durata di partecipazione e le metriche di partecipazione
- Follow-up webinar - Attiva sequenze email mirate in base alla partecipazione ai webinar
- Notifiche di registrazione - Invia link alle registrazioni tramite campagne email Brevo
Prerequisiti
Prima di iniziare, assicurati di avere:
- Un account Zoom (piano Pro o superiore)
- Un’app Zoom Server-to-Server OAuth o un’app OAuth tramite Zoom App Marketplace
- Un account Brevo con accesso API
- Un account Tajo con permessi sui connettori
Autenticazione
Server-to-Server OAuth (consigliato)
# Crea un'app Server-to-Server OAuth su marketplace.zoom.usexport ZOOM_ACCOUNT_ID=your_account_idexport ZOOM_CLIENT_ID=your_client_idexport ZOOM_CLIENT_SECRET=your_client_secret// Ottiene un access token tramite Server-to-Server OAuthconst tokenResponse = await fetch('https://zoom.us/oauth/token', { method: 'POST', headers: { 'Authorization': `Basic ${Buffer.from( `${process.env.ZOOM_CLIENT_ID}:${process.env.ZOOM_CLIENT_SECRET}` ).toString('base64')}`, 'Content-Type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ grant_type: 'account_credentials', account_id: process.env.ZOOM_ACCOUNT_ID })});
const { access_token } = await tokenResponse.json();OAuth 2.0 (user-level)
// URL di autorizzazione per OAuth user-levelconst authUrl = 'https://zoom.us/oauth/authorize?' + new URLSearchParams({ client_id: process.env.ZOOM_CLIENT_ID, redirect_uri: 'https://your-app.com/callback', response_type: 'code' });
// Scambia il code per i tokenconst tokenResponse = await fetch('https://zoom.us/oauth/token', { method: 'POST', headers: { 'Authorization': `Basic ${Buffer.from( `${process.env.ZOOM_CLIENT_ID}:${process.env.ZOOM_CLIENT_SECRET}` ).toString('base64')}`, 'Content-Type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ grant_type: 'authorization_code', code: authorizationCode, redirect_uri: 'https://your-app.com/callback' })});Configurazione
Setup di base
connectors: zoom: enabled: true account_id: "${ZOOM_ACCOUNT_ID}" client_id: "${ZOOM_CLIENT_ID}" client_secret: "${ZOOM_CLIENT_SECRET}"
sync: participants: true webinars: true recordings: true
webhook: secret_token: "${ZOOM_WEBHOOK_SECRET}" verification_token: "${ZOOM_VERIFICATION_TOKEN}"
lists: meeting_participants: 15 webinar_attendees: 16 webinar_registrants: 17Mapping dei campi
field_mapping: email: email name: FIRSTNAME join_time: MEETING_JOIN_DATE duration: MEETING_DURATION webinar_title: WEBINAR_NAME attendance_status: ATTENDANCE_STATUS registration_source: UTM_SOURCEEndpoint API
| Endpoint | Metodo | Descrizione |
|---|---|---|
https://api.zoom.us/v2/users | GET | Elenca gli utenti |
https://api.zoom.us/v2/users/{userId}/meetings | GET | Elenca i meeting |
https://api.zoom.us/v2/meetings/{meetingId} | GET | Ottieni dettagli meeting |
https://api.zoom.us/v2/past_meetings/{meetingId}/participants | GET | Elenca partecipanti ai meeting passati |
https://api.zoom.us/v2/users/{userId}/webinars | GET | Elenca i webinar |
https://api.zoom.us/v2/webinars/{webinarId}/registrants | GET | Elenca gli iscritti al webinar |
https://api.zoom.us/v2/webinars/{webinarId}/participants | GET | Elenca i partecipanti al webinar |
https://api.zoom.us/v2/meetings/{meetingId}/recordings | GET | Ottieni le registrazioni del meeting |
https://api.zoom.us/v2/webhooks | POST | Sottoscrivi webhook |
Esempi di codice
Inizializzare il connettore
import { TajoClient } from '@tajo/sdk';
const tajo = new TajoClient({ apiKey: process.env.TAJO_API_KEY, brevoApiKey: process.env.BREVO_API_KEY});
await tajo.connectors.connect('zoom', { accountId: process.env.ZOOM_ACCOUNT_ID, clientId: process.env.ZOOM_CLIENT_ID, clientSecret: process.env.ZOOM_CLIENT_SECRET});Sincronizzare i partecipanti ai meeting
// Recupera i partecipanti ai meeting passaticonst response = await fetch( `https://api.zoom.us/v2/past_meetings/${meetingId}/participants`, { headers: { 'Authorization': `Bearer ${accessToken}`, 'Content-Type': 'application/json' } });
const { participants } = await response.json();
for (const participant of participants) { if (participant.user_email) { await tajo.contacts.sync({ email: participant.user_email, attributes: { FIRSTNAME: participant.name, MEETING_DURATION: participant.duration, MEETING_JOIN_DATE: participant.join_time, ATTENDANCE_STATUS: 'attended' }, listIds: [15] }); }}Sincronizzare i partecipanti al webinar
// Recupera i partecipanti al webinar e sincronizzali su Brevoconst attendeesResponse = await fetch( `https://api.zoom.us/v2/past_webinars/${webinarId}/participants`, { headers: { 'Authorization': `Bearer ${accessToken}` } });
const { participants: attendees } = await attendeesResponse.json();
for (const attendee of attendees) { await tajo.contacts.sync({ email: attendee.user_email, attributes: { FIRSTNAME: attendee.name, WEBINAR_NAME: webinarTitle, ATTENDANCE_STATUS: 'attended', MEETING_DURATION: attendee.duration }, listIds: [16] });}Gestire i webhook Zoom
app.post('/webhooks/zoom', async (req, res) => { // Gestisci la challenge di validazione URL di Zoom if (req.body.event === 'endpoint.url_validation') { const hashForValidation = crypto .createHmac('sha256', process.env.ZOOM_WEBHOOK_SECRET) .update(req.body.payload.plainToken) .digest('hex');
return res.json({ plainToken: req.body.payload.plainToken, encryptedToken: hashForValidation }); }
// Verifica la firma del webhook const message = `v0:${req.headers['x-zm-request-timestamp']}:${JSON.stringify(req.body)}`; const hash = crypto .createHmac('sha256', process.env.ZOOM_WEBHOOK_SECRET) .update(message) .digest('hex'); const signature = `v0=${hash}`;
if (req.headers['x-zm-signature'] !== signature) { return res.status(401).send('Unauthorized'); }
const { event, payload } = req.body;
await tajo.connectors.handleWebhook('zoom', { topic: event, payload: payload });
res.status(200).send('OK');});Limiti di rate
| Categoria | Limite | Note |
|---|---|---|
| Chiamate API leggere | 30 req/sec | GET user, info meeting |
| Chiamate API medie | 20 req/sec | Lista partecipanti, webinar |
| Chiamate API pesanti | 10 req/sec | Report, registrazioni |
| Limite giornaliero | 5.000+ | Dipende dal livello del piano |
Header del rate limit
Zoom restituisce gli header X-RateLimit-Limit, X-RateLimit-Remaining e Retry-After. Implementa una logica di backoff basata su questi header per evitare errori 429.
Risoluzione dei problemi
| Problema | Causa | Soluzione |
|---|---|---|
| 401 Unauthorized | Token scaduto | Aggiorna il token Server-to-Server OAuth |
| Partecipanti mancanti | Meeting non terminato | Attendi la fine del meeting per dati completi |
| Validazione webhook fallisce | Secret errato | Verifica il secret del webhook nel Zoom Marketplace |
| Nessun dato email | Partecipanti come ospiti | Abilita la registrazione per catturare le email |
| Rate limit 429 | Troppe richieste | Implementa exponential backoff |
Modalità debug
connectors: zoom: debug: true log_level: verbose log_webhooks: trueBest practice
- Usa Server-to-Server OAuth - Autenticazione più semplice senza interazione utente
- Abilita la registrazione per i webinar - Necessaria per catturare gli indirizzi email dei partecipanti
- Elabora dopo la fine del meeting - I dati dei partecipanti sono completi solo dopo la fine dei meeting
- Segmenta per tipo di evento - Assegna liste Brevo diverse per meeting vs. webinar
- Traccia le metriche di engagement - Usa durata e orario di join per il lead scoring
- Invia follow-up delle registrazioni - Automatizza la consegna del link alle registrazioni tramite Brevo
Sicurezza
- OAuth 2.0 - Autenticazione OAuth Server-to-Server o user-level
- Verifica webhook - Validazione firma HMAC-SHA256
- Validazione URL - Verifica challenge-response per gli endpoint webhook
- Permessi con scope - Richiedi gli scope OAuth minimi necessari
- Rotazione dei token - I token Server-to-Server scadono automaticamente (1 ora)
- Trasporto cifrato - TLS 1.2+ per tutte le comunicazioni API