Коннектор Intercom

Подключите рабочее пространство Intercom к Brevo через Tajo для единого клиентского мессенджинга, отслеживания диалогов и маркетинговой автоматизации на основе данных поддержки и продукта.

Обзор

Возможности

• Синхронизация контактов, двунаправленная синхронизация пользователей и лидов Intercom с контактами Brevo
• Отслеживание диалогов, синхронизация данных диалогов для сегментации на основе поддержки
• Маппинг компаний, привязка контактов к компаниям для аккаунт-ориентированных рабочих процессов
• Пользовательские атрибуты, маппинг пользовательских атрибутов Intercom на поля контактов Brevo
• Трекинг событий, синхронизация пользовательских событий и активности для поведенческого таргетинга
• Синхронизация тегов, маппинг тегов Intercom в членство в списках или атрибуты Brevo
• Данные мессенджера, трекинг вовлечённости в чате и взаимодействий
• Интеграция AI-агента, синхронизация результатов диалогов AI-агента с Brevo

Предварительные требования

Прежде чем начать, убедитесь, что у вас есть:

1. Рабочее пространство Intercom (план Starter, Pro или Premium)
2. Приложение Intercom с токеном доступа (private app) или настроенным OAuth (public app)
3. Аккаунт Brevo с доступом к API
4. Аккаунт Tajo

Аутентификация

Access Token (приватное приложение)

Для приватных интеграций, обращающихся к данным вашего рабочего пространства.

1. Перейдите в Developer Hub > Your Apps > Create new app
2. Привяжите к рабочему пространству Intercom
3. Скопируйте токен доступа

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

OAuth 2.0 (публичное приложение)

Для интеграций, получающих доступ к данным Intercom других клиентов.

# URL авторизации
https://app.intercom.com/oauth?client_id={client_id}&state={state}

# Обмен токена
curl -X POST https://api.intercom.io/auth/eagle/token \
  -d "client_id={client_id}" \
  -d "client_secret={client_secret}" \
  -d "code={auth_code}"

Конфигурация

Базовая настройка

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

    # Параметры синхронизации данных
    sync:
      contacts: true
      conversations: true
      companies: true
      events: true
      tags: true

    # Направление синхронизации
    direction: intercom_to_brevo

    # Назначение листов Brevo
    lists:
      all_users: 35
      active_conversations: 36
      leads: 37

Сопоставление полей

Сопоставьте данные контактов Intercom с атрибутами контактов Brevo:

Маппинг пользовательских атрибутов

field_mapping:
  # Стандартные поля
  email: email
  name: FULLNAME
  phone: SMS

  # Поля вовлечённости
  signed_up_at: SIGNUP_DATE
  last_seen_at: LAST_ACTIVE
  session_count: SESSION_COUNT
  unsubscribed_from_emails: UNSUBSCRIBED

  # Поля компании
  company.name: COMPANY_NAME
  company.plan: COMPANY_PLAN
  company.size: COMPANY_SIZE

  # Пользовательские атрибуты
  custom_attributes.plan_tier: PLAN_TIER
  custom_attributes.feature_usage: FEATURE_USAGE

Эндпоинты API

Contacts API

Conversations API

Companies API

Events API

События

События диалогов

События контактов

События пользователей

Примеры кода

Инициализация коннектора

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

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

// Подключение Intercom
await tajo.connectors.connect('intercom', {
  accessToken: process.env.INTERCOM_ACCESS_TOKEN,
  apiVersion: '2.11'
});

Синхронизация контактов и диалогов

// Полная синхронизация контактов и данных диалогов
await tajo.connectors.sync('intercom', {
  type: 'full',
  resources: ['contacts', 'conversations', 'companies'],
  since: '2023-01-01'
});

// Проверка статуса синхронизации
const status = await tajo.connectors.status('intercom');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   contactsSynced: 14200,
//   conversationsSynced: 28400,
//   companiesSynced: 2100
// }

Обработка вебхуков 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');
});

Ограничения скорости

Intercom устанавливает лимиты скорости в зависимости от плана:

Дополнительные ограничения:

• Bulk-операции: 15 контактов на bulk-запрос
• Отправка событий: 500 событий/сек на рабочее пространство
• Доставка вебхуков: автоматические повторные попытки в течение 24 часов
• Экспорт данных: 1 параллельный экспорт

Устранение неполадок

Частые проблемы

Режим отладки

Включение подробного логирования:

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

Проверка подключения

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

Лучшие практики

1. Закрепляйте версию API, всегда указывайте Intercom-Version во избежание критических изменений
2. Эффективно используйте Search API, применяйте фильтры и пагинацию для уменьшения передаваемых данных
3. Синхронизируйте пользователей и лидов, охватывайте всю воронку в Brevo
4. Маппируйте теги диалогов, используйте теги диалогов для сегментов постпокупочного маркетинга
5. Отслеживайте пользовательские события, отправляйте ключевые события продукта в Intercom для поведенческого таргетинга
6. Обрабатывайте объединение контактов, реализуйте логику слияния для дублирующихся контактов

Безопасность

• Access Token, аутентификация через Bearer-токен для приватных приложений
• OAuth 2.0, делегированная авторизация для публичных приложений с client secret
• Верификация вебхуков, валидация подписи HMAC SHA-1 через X-Hub-Signature
• TLS-шифрование, все API-коммуникации зашифрованы через HTTPS
• Контроль доступа к данным, гранулярный доступ к данным на конфигурацию приложения

Связанные ресурсы

• Документация Intercom Developer
• Справочник Intercom API
• Коннектор Zendesk
• Скилл синхронизации клиентов
• Brevo Contacts API