Connettore Intercom

Collega il tuo workspace Intercom a Brevo tramite Tajo per messaggistica cliente unificata, tracciamento delle conversazioni e marketing automation guidata dall’engagement, alimentata dai tuoi dati di supporto e di prodotto.

Panoramica

Funzionalità

• Sync dei contatti - Sync bidirezionale di utenti e lead Intercom con i contatti Brevo
• Tracciamento conversazioni - Sincronizza i dati delle conversazioni per la segmentazione guidata dal supporto
• Mappatura aziende - Associa i contatti alle aziende per workflow account-based
• Attributi personalizzati - Mappa gli attributi personalizzati Intercom ai campi di contatto Brevo
• Tracciamento eventi - Sincronizza eventi personalizzati e attività utente per il targeting comportamentale
• Sync dei tag - Mappa i tag Intercom ad appartenenze a liste o attributi Brevo
• Dati Messenger - Traccia l’engagement della messaggistica in-app e le interazioni chat
• Integrazione AI agent - Sincronizza gli esiti delle conversazioni dell’AI agent con Brevo

Prerequisiti

Prima di iniziare, assicurati di avere:

1. Un workspace Intercom (piano Starter, Pro o Premium)
2. Un’app Intercom con access token (private app) o OAuth configurato (public app)
3. Un account Brevo con accesso API
4. Un account Tajo

Autenticazione

Access Token (Private App)

Per integrazioni private che accedono ai dati del tuo workspace.

1. Vai in Developer Hub > Your Apps > Create new app
2. Associa con il tuo workspace Intercom
3. Copia l’access token

curl https://api.intercom.io/contacts \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "Intercom-Version: 2.11"

OAuth 2.0 (Public App)

Per integrazioni che accedono ai dati Intercom di altri clienti.

# Authorization URL
https://app.intercom.com/oauth?client_id={client_id}&state={state}

# Token exchange
curl -X POST https://api.intercom.io/auth/eagle/token \
  -d "client_id={client_id}" \
  -d "client_secret={client_secret}" \
  -d "code={auth_code}"

Configurazione

Setup di base

connectors:
  intercom:
    enabled: true
    access_token: "${INTERCOM_ACCESS_TOKEN}"
    api_version: "2.11"

    # Data sync options
    sync:
      contacts: true
      conversations: true
      companies: true
      events: true
      tags: true

    # Sync direction
    direction: intercom_to_brevo

    # Brevo list assignment
    lists:
      all_users: 35
      active_conversations: 36
      leads: 37

Mappatura dei campi

Mappa i dati di contatto Intercom agli attributi di contatto Brevo:

Mappatura attributi personalizzati

field_mapping:
  # Standard fields
  email: email
  name: FULLNAME
  phone: SMS

  # Engagement fields
  signed_up_at: SIGNUP_DATE
  last_seen_at: LAST_ACTIVE
  session_count: SESSION_COUNT
  unsubscribed_from_emails: UNSUBSCRIBED

  # Company fields
  company.name: COMPANY_NAME
  company.plan: COMPANY_PLAN
  company.size: COMPANY_SIZE

  # Custom attributes
  custom_attributes.plan_tier: PLAN_TIER
  custom_attributes.feature_usage: FEATURE_USAGE

Endpoint API

API Contatti

API Conversazioni

API Aziende

API Eventi

Eventi

Eventi conversazione

Eventi contatto

Eventi utente

Esempi di codice

Inizializza il connettore

import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

// Connect Intercom
await tajo.connectors.connect('intercom', {
  accessToken: process.env.INTERCOM_ACCESS_TOKEN,
  apiVersion: '2.11'
});

Sincronizza contatti e conversazioni

// Full sync of contacts and conversation data
await tajo.connectors.sync('intercom', {
  type: 'full',
  resources: ['contacts', 'conversations', 'companies'],
  since: '2023-01-01'
});

// Check sync status
const status = await tajo.connectors.status('intercom');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   contactsSynced: 14200,
//   conversationsSynced: 28400,
//   companiesSynced: 2100
// }

Gestisci i webhook Intercom

import crypto from 'crypto';

app.post('/webhooks/intercom', async (req, res) => {
  const signature = req.get('X-Hub-Signature');
  const expectedSig = 'sha1=' + crypto
    .createHmac('sha1', process.env.INTERCOM_CLIENT_SECRET)
    .update(JSON.stringify(req.body))
    .digest('hex');

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

  await tajo.connectors.handleWebhook('intercom', {
    topic: req.body.topic,
    data: req.body.data
  });

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

Limiti di velocità

Intercom applica limiti di velocità in base al tuo piano:

Limiti aggiuntivi:

• Operazioni bulk: 15 contatti per richiesta bulk
• Invio eventi: 500 eventi/secondo per workspace
• Consegna webhook: Retry automatico per 24 ore
• Esportazione dati: 1 esportazione concorrente

Risoluzione dei problemi

Problemi comuni

Modalità debug

Abilita il logging dettagliato:

connectors:
  intercom:
    debug: true
    log_level: verbose
    log_webhooks: true

Testa la connessione

tajo connectors test intercom
# ✓ API connection successful
# ✓ Contacts readable
# ✓ Conversations readable
# ✓ Companies readable
# ✓ Webhooks registered

Best practice

1. Fissa la versione API - Specifica sempre Intercom-Version per evitare breaking change
2. Usa la search API in modo efficiente - Usa filtri e paginazione per ridurre il trasferimento dati
3. Sincronizza sia utenti che lead - Cattura l’intero funnel in Brevo
4. Mappa i tag delle conversazioni - Usa i tag delle conversazioni per segmenti marketing post-supporto
5. Traccia eventi personalizzati - Invia eventi prodotto chiave a Intercom per il targeting comportamentale
6. Gestisci il merge dei contatti - Implementa logica di merge per contatti duplicati

Sicurezza

• Access Token - Autenticazione bearer token per private app
• OAuth 2.0 - Autorizzazione delegata per public app con client secret
• Verifica webhook - Convalida firma HMAC SHA-1 tramite X-Hub-Signature
• Cifratura TLS - Tutte le comunicazioni API cifrate via HTTPS
• Controlli accesso ai dati - Accesso ai dati granulare per configurazione app

Risorse correlate

• Documentazione Intercom Developer
• Riferimento API Intercom
• Connettore Zendesk
• Skill Customer Sync
• API Contatti Brevo