Connettore Slack

Collega il tuo workspace Slack a Brevo tramite Tajo per notifiche marketing in real-time, alert di team sugli eventi cliente e automazione di workflow attivata da interazioni Slack.

Panoramica

Funzionalità

• Alert marketing - Invia notifiche in real-time per eventi di campagna, nuovi iscritti e milestone di revenue
• Notifiche eventi cliente - Avverti i team sulle azioni dei clienti high-value da Brevo
• Trigger di workflow - Usa interazioni Slack (click sui pulsanti, invio form) per attivare automazioni Brevo
• Routing per canale - Instrada le notifiche verso canali specifici in base al tipo di evento o segmento cliente
• Sync utenti - Mappa gli utenti del workspace Slack sui contatti Brevo per comunicazioni interne
• Messaggi interattivi - Invia messaggi ricchi con pulsanti e azioni per i workflow del team
• Messaggi pianificati - Pianifica notifiche per riepiloghi marketing giornalieri/settimanali
• Supporto thread - Raggruppa notifiche correlate nei thread per una comunicazione organizzata

Prerequisiti

Prima di iniziare, assicurati di avere:

1. Un workspace Slack con accesso admin
2. Un’app Slack creata su api.slack.com/apps
3. Un bot token con gli scope richiesti
4. Un account Brevo con accesso API
5. Un account Tajo

Autenticazione

Bot Token (consigliato)

Installa un’app Slack sul tuo workspace e usa il bot token per l’accesso API.

1. Crea l’app su api.slack.com/apps
2. Aggiungi gli scope OAuth richiesti sotto “OAuth & Permissions”
3. Installa l’app nel workspace
4. Copia il Bot User OAuth Token (xoxb-...)

curl -X POST "https://slack.com/api/chat.postMessage" \
  -H "Authorization: Bearer xoxb-YOUR-BOT-TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"channel": "C01234567", "text": "Ciao da Tajo!"}'

OAuth 2.0

Per distribuire la tua integrazione Slack su più workspace:

# URL di autorizzazione
https://slack.com/oauth/v2/authorize?
  client_id={client_id}&
  scope=chat:write,channels:read,users:read&
  redirect_uri={redirect_uri}

# Scambio del token
curl -X POST "https://slack.com/api/oauth.v2.access" \
  -d "client_id={client_id}" \
  -d "client_secret={client_secret}" \
  -d "code={auth_code}"

Scope bot richiesti

chat:write           # Invia messaggi
channels:read        # Elenca canali
channels:history     # Leggi i messaggi del canale
users:read           # Elenca gli utenti del workspace
users:read.email     # Leggi gli indirizzi email degli utenti
reactions:write      # Aggiungi reazioni ai messaggi
files:write          # Carica file

Configurazione

Setup di base

connectors:
  slack:
    enabled: true
    bot_token: "${SLACK_BOT_TOKEN}"
    signing_secret: "${SLACK_SIGNING_SECRET}"

    # Canali di notifica
    channels:
      marketing: "C01234567"
      sales: "C01234568"
      support: "C01234569"
      alerts: "C01234570"

    # Routing eventi
    notifications:
      new_subscriber:
        channel: marketing
        template: subscriber_alert
      high_value_order:
        channel: sales
        template: order_alert
      support_ticket:
        channel: support
        template: ticket_alert

Mapping dei campi

Mappa i dati utente Slack sugli attributi dei contatti Brevo:

Metodi API

Messaggistica

Canali

Utenti

Interazioni

Eventi

Notifiche Brevo-Slack

Trigger Slack-Brevo

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
});

// Collega Slack
await tajo.connectors.connect('slack', {
  botToken: process.env.SLACK_BOT_TOKEN,
  signingSecret: process.env.SLACK_SIGNING_SECRET
});

Inviare notifiche marketing

// Invia una notifica quando viene effettuato un ordine high-value
await tajo.slack.notify({
  channel: 'sales',
  event: 'order_placed',
  data: {
    customerEmail: '[email protected]',
    orderValue: '$1,250.00',
    products: ['Premium Widget', 'Pro Service'],
    isFirstOrder: true
  },
  template: {
    blocks: [
      {
        type: 'header',
        text: { type: 'plain_text', text: 'Nuovo ordine high-value' }
      },
      {
        type: 'section',
        fields: [
          { type: 'mrkdwn', text: '*Cliente:*\n[email protected]' },
          { type: 'mrkdwn', text: '*Importo:*\n$1,250.00' }
        ]
      },
      {
        type: 'actions',
        elements: [
          {
            type: 'button',
            text: { type: 'plain_text', text: 'Vedi in Brevo' },
            url: 'https://app.brevo.com/contacts'
          }
        ]
      }
    ]
  }
});

Gestire le interazioni Slack

import crypto from 'crypto';

app.post('/slack/interactions', async (req, res) => {
  // Verifica la firma della richiesta Slack
  const timestamp = req.headers['x-slack-request-timestamp'];
  const signature = req.headers['x-slack-signature'];
  const sigBasestring = `v0:${timestamp}:${req.rawBody}`;
  const mySignature = 'v0=' + crypto
    .createHmac('sha256', process.env.SLACK_SIGNING_SECRET)
    .update(sigBasestring)
    .digest('hex');

  if (signature !== mySignature) {
    return res.status(401).send('Unauthorized');
  }

  const payload = JSON.parse(req.body.payload);

  // Gestisci le azioni sui pulsanti
  if (payload.type === 'block_actions') {
    await tajo.connectors.handleWebhook('slack', {
      type: 'interaction',
      action: payload.actions[0].action_id,
      userId: payload.user.id,
      payload
    });
  }

  res.status(200).send();
});

Limiti di rate

I rate limit dell’API Slack usano un sistema a tier:

Limiti aggiuntivi:

• Web API: Limite di burst con throttle a breve termine
• Events API: 3 retry di consegna
• Incoming Webhooks: 1 messaggio/secondo per URL webhook
• Block Kit: Massimo 50 block per messaggio

Risoluzione dei problemi

Problemi comuni

Modalità debug

Abilita il logging verboso:

connectors:
  slack:
    debug: true
    log_level: verbose
    log_events: true

Testare la connessione

tajo connectors test slack
# ✓ Bot token valido
# ✓ Workspace accessibile
# ✓ Canali leggibili
# ✓ Pubblicazione messaggi abilitata
# ✓ Event subscription attive

Best practice

1. Usa Block Kit - Costruisci messaggi ricchi e interattivi con il framework Block Kit di Slack
2. Rispondi rapidamente - Acknowledging delle interazioni entro 3 secondi, elabora in modo asincrono
3. Metti in thread i messaggi correlati - Raggruppa le notifiche correlate nei thread per ridurre il rumore
4. Instrada per canale - Invia tipi di evento diversi ai canali di team appropriati
5. Includi pulsanti d’azione - Aggiungi pulsanti “Vedi in Brevo” per accesso rapido ai dati cliente
6. Implementa l’unfurling - Mostra anteprime ricche per i link Brevo condivisi in Slack

Sicurezza

• Bot Token - Access token OAuth con scope e permessi granulari
• Request signing - Verifica firma HMAC SHA-256 per le richieste in ingresso
• OAuth 2.0 - Autorizzazione standard di settore per distribuzione multi-workspace
• Cifratura TLS - Tutte le comunicazioni API cifrate via HTTPS
• Rotazione token - Rotazione automatica dei token per maggiore sicurezza

Risorse correlate

• Documentazione Slack API
• Slack Block Kit Builder
• Slack Events API
• Connettore Brevo
• Skill Customer Sync