Conector de Customer.io

Conecta tu plataforma de mensajería Customer.io con Brevo para unificar los datos de cliente, coordinar campañas entre plataformas y consolidar la analítica de engagement.

Resumen

Funcionalidades

• Sincronización de personas - Sincronización bidireccional de perfiles de cliente con contactos de Brevo
• Reenvío de eventos - Registra eventos conductuales y reenvíalos a Brevo como triggers de automatización
• Analítica de campañas - Sincroniza métricas de rendimiento de campañas para un reporting unificado
• Datos de workflow - Replica los estados de workflow de Customer.io en atributos de contacto de Brevo
• Replicación de segmentos - Replica los segmentos de Customer.io como listas de Brevo
• Sincronización de objetos - Sincroniza objetos distintos de personas y datos de relación

Requisitos previos

Antes de empezar, asegúrate de tener:

1. Una cuenta de Customer.io con acceso a la API
2. Tu Site ID y Track API Key (en Settings > API Credentials)
3. Una App API Key para leer datos de campañas y segmentos
4. Una cuenta de Brevo con acceso a la API
5. Una cuenta de Tajo con suscripción activa

Autenticación

Customer.io usa dos APIs separadas con métodos de autenticación diferentes:

Track API (datos conductuales)

Se usa para enviar personas, eventos y datos de dispositivo. Se autentica con Site ID y clave API mediante Basic Auth.

# Basic Auth: Site ID as username, API Key as password
curl -X POST https://track.customer.io/api/v1/customers/user123 \
  -u "$SITE_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

App API (lectura de datos)

Se usa para obtener campañas, segmentos y datos de clientes. Se autentica con un token Bearer.

curl -X GET https://api.customer.io/v1/campaigns \
  -H "Authorization: Bearer $APP_API_KEY"

Conectar con Tajo

tajo connectors install customerio \
  --site-id $CIO_SITE_ID \
  --track-api-key $CIO_TRACK_API_KEY \
  --app-api-key $CIO_APP_API_KEY

Configuración

Configuración básica

connectors:
  customerio:
    enabled: true
    region: "us"  # or "eu" for EU data center

    sync:
      people: true
      events: true
      campaigns: true
      segments: true
      objects: false

    lists:
      all_contacts: 12
      active_subscribers: 13
      churned: 14

Asignación de campos

Asocia los atributos de persona de Customer.io con los atributos de contacto de Brevo:

field_mapping:
  # Standard fields
  id: CIO_ID
  email: email
  first_name: FIRSTNAME
  last_name: LASTNAME
  phone: SMS

  # Engagement metrics
  created_at: SIGNUP_DATE
  last_activity: LAST_ACTIVE
  plan: PLAN_NAME

  # Custom attributes
  company: COMPANY
  role: JOB_TITLE
  mrr: MONTHLY_REVENUE
  lifecycle_stage: LIFECYCLE_STAGE

Asignación de eventos

event_mapping:
  # Customer.io event -> Brevo event
  purchase_completed: ORDER_PLACED
  subscription_started: SUBSCRIPTION_START
  feature_activated: FEATURE_USED
  support_ticket_opened: SUPPORT_REQUEST

Endpoints de la API

Tajo se integra con los siguientes endpoints de la API de Customer.io:

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

await tajo.connectors.connect('customerio', {
  siteId: process.env.CIO_SITE_ID,
  trackApiKey: process.env.CIO_TRACK_API_KEY,
  appApiKey: process.env.CIO_APP_API_KEY,
  region: 'us'
});

Sincronizar personas con Brevo

// Incremental sync of Customer.io people
await tajo.connectors.sync('customerio', {
  type: 'incremental',
  resources: ['people'],
  since: '2024-01-01',
  batchSize: 100
});

const status = await tajo.connectors.status('customerio');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-03-15T14:20:00Z',
//   peopleCount: 32500,
//   campaignsTracked: 18,
//   eventsProcessed: 87000
// }

Reenviar eventos

// Forward Customer.io reporting webhook events to Brevo
app.post('/webhooks/customerio', async (req, res) => {
  const events = req.body;

  for (const event of events) {
    await tajo.connectors.handleEvent('customerio', {
      type: event.metric,
      payload: {
        customerId: event.data.customer_id,
        campaignId: event.data.campaign_id,
        timestamp: event.timestamp
      }
    });
  }

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

Exportar un segmento

const result = await tajo.connectors.exportSegment('customerio', {
  segmentId: 42,
  targetList: 13,
  includeAttributes: ['email', 'first_name', 'last_name', 'plan']
});

console.log(`Exported ${result.count} people to Brevo list 13`);

Límites de velocidad

Customer.io aplica límites de velocidad distintos por cada API:

Resolución de problemas

Problemas habituales

Modo depuración

connectors:
  customerio:
    debug: true
    log_level: verbose
    log_api_calls: true

Probar la conexión

tajo connectors test customerio
# ✓ Track API connection successful
# ✓ App API connection successful
# ✓ People accessible
# ✓ Campaigns readable
# ✓ Segments listable

Buenas prácticas

1. Usa la Pipelines API para datos en volumen - La nueva Pipelines API está optimizada para ingestión de alto volumen
2. Configura reporting webhooks - Reenvía los eventos de email de Customer.io a Tajo en tiempo real
3. Asocia las etapas del ciclo de vida - Sincroniza la pertenencia a segmentos de Customer.io con atributos de Brevo
4. Usa identificadores coherentes - Haz coincidir los campos id entre Customer.io y Brevo
5. Sincroniza de forma incremental - Evita exportaciones completas; aprovecha los timestamps de last_activity
6. Monitoriza la entrega de webhooks - Configura alertas para entregas fallidas de webhook

Seguridad

• Basic Auth - La Track API se autentica con Site ID y clave API
• Token Bearer - La App API usa tokens bearer estilo OAuth
• Solo HTTPS - Toda la comunicación con la API se cifra vía TLS 1.2+
• Centros de datos regionales - Opción de centro de datos en la UE para cumplimiento con el RGPD
• Almacenamiento cifrado - Todas las credenciales se cifran en reposo en Tajo
• Firmas de webhook - Verifica los payloads de webhook con firmas HMAC

Recursos relacionados

• Conector de Braze
• Conector de Iterable
• Skill de sincronización de clientes
• API de contactos de Brevo