Conector de Intercom

Conecta tu workspace de Intercom con Brevo a través de Tajo para unificar la mensajería con el cliente, el seguimiento de conversaciones y la automatización de marketing basada en la interacción, impulsada por tus datos de soporte y producto.

Resumen

Funcionalidades

• Sincronización de contactos - Sincronización bidireccional de usuarios y leads de Intercom con contactos de Brevo
• Seguimiento de conversaciones - Sincroniza los datos de conversación para la segmentación basada en soporte
• Mapeo de empresas - Asocia contactos con empresas para flujos basados en cuentas
• Atributos personalizados - Asocia atributos personalizados de Intercom con campos de contacto de Brevo
• Seguimiento de eventos - Sincroniza eventos personalizados y actividades del usuario para segmentación por comportamiento
• Sincronización de etiquetas - Asocia las etiquetas de Intercom con la pertenencia a listas o atributos de Brevo
• Datos de Messenger - Registra la interacción con la mensajería in-app y los chats
• Integración con agentes IA - Sincroniza los resultados de las conversaciones con agentes IA en Brevo

Requisitos previos

Antes de empezar, asegúrate de tener:

1. Un workspace de Intercom (plan Starter, Pro o Premium)
2. Una app de Intercom con access token (app privada) o OAuth configurado (app pública)
3. Una cuenta de Brevo con acceso a la API
4. Una cuenta de Tajo

Autenticación

Access Token (app privada)

Para integraciones privadas que acceden a los datos de tu propio workspace.

1. Ve a Developer Hub > Your Apps > Create new app
2. Asóciala con tu workspace de Intercom
3. Copia el 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 (app pública)

Para integraciones que acceden a los datos de Intercom de otros clientes.

# 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}"

Configuración

Configuración básica

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

Asignación de campos

Asocia los datos de contacto de Intercom con atributos de contacto de Brevo:

Asignación de atributos personalizados

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

Endpoints de la API

API de contactos

API de conversaciones

API de empresas

API de eventos

Eventos

Eventos de conversación

Eventos de contacto

Eventos de usuario

Ejemplos de código

Inicializar el conector

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

Sincronizar contactos y conversaciones

// 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
// }

Gestionar webhooks de 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');
});

Límites de velocidad

Intercom aplica límites de velocidad según tu plan:

Límites adicionales:

• Operaciones en lote: 15 contactos por petición en lote
• Envíos de eventos: 500 eventos/segundo por workspace
• Entrega de webhooks: Reintento automático durante 24 horas
• Exportación de datos: 1 exportación simultánea

Resolución de problemas

Problemas habituales

Modo depuración

Habilita el registro detallado:

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

Probar la conexión

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

Buenas prácticas

1. Fija la versión de la API - Especifica siempre Intercom-Version para evitar cambios incompatibles
2. Usa la API de búsqueda con eficiencia - Usa filtros y paginación para reducir la transferencia de datos
3. Sincroniza usuarios y leads - Captura todo el funnel en Brevo
4. Asocia etiquetas de conversación - Usa las etiquetas de conversación para segmentos de marketing posventa
5. Registra eventos personalizados - Envía los eventos clave de producto a Intercom para segmentación por comportamiento
6. Gestiona las fusiones de contactos - Implementa lógica de fusión para contactos duplicados

Seguridad

• Access Token - Autenticación con Bearer token para apps privadas
• OAuth 2.0 - Autorización delegada para apps públicas con client secret
• Verificación de webhooks - Validación de firma HMAC SHA-1 mediante X-Hub-Signature
• Cifrado TLS - Toda la comunicación con la API se cifra vía HTTPS
• Controles de acceso a datos - Acceso granular a los datos según la configuración de la app

Recursos relacionados

• Documentación para desarrolladores de Intercom
• Referencia de la API de Intercom
• Conector de Zendesk
• Skill de sincronización de clientes
• API de contactos de Brevo