Intercom 커넥터

Intercom 워크스페이스를 Tajo를 통해 Brevo에 연결하여 통합된 고객 메시징, 대화 추적, 지원 및 제품 데이터로 구동되는 참여 기반 마케팅 자동화를 구현하십시오.

개요

기능

• 연락처 동기화 - Intercom 사용자 및 리드를 Brevo 연락처와 양방향 동기화
• 대화 추적 - 지원 기반 세그먼테이션을 위한 대화 데이터 동기화
• 회사 매핑 - 계정 기반 워크플로를 위해 연락처를 회사와 연결
• 맞춤 속성 - Intercom 맞춤 속성을 Brevo 연락처 필드에 매핑
• 이벤트 추적 - 행동 타겟팅을 위한 맞춤 이벤트 및 사용자 활동 동기화
• 태그 동기화 - Intercom 태그를 Brevo 목록 멤버십 또는 속성에 매핑
• Messenger 데이터 - 앱 내 메시징 참여 및 채팅 상호작용 추적
• AI 에이전트 통합 - AI 에이전트 대화 결과를 Brevo와 동기화

사전 요구 사항

시작하기 전에 다음이 준비되어 있는지 확인하십시오.

1. Intercom 워크스페이스 (Starter, Pro 또는 Premium 요금제)
2. 액세스 토큰이 있는 Intercom 앱(비공개 앱) 또는 OAuth가 구성된(공개 앱)
3. API 접근이 가능한 Brevo 계정
4. Tajo 계정

인증

액세스 토큰 (비공개 앱)

자신의 워크스페이스 데이터에 접근하는 비공개 통합의 경우.

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 연락처
• 이벤트 제출: 워크스페이스당 500 이벤트/초
• 웹훅 배달: 24시간 동안 자동 재시도
• 데이터 내보내기: 1개 동시 내보내기

문제 해결

일반적인 문제

디버그 모드

자세한 로깅 활성화:

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

연결 테스트

tajo connectors test intercom
# ✓ API 연결 성공
# ✓ 연락처 읽기 가능
# ✓ 대화 읽기 가능
# ✓ 회사 읽기 가능
# ✓ 웹훅 등록됨

모범 사례

1. API 버전 고정 - 호환성 손상 변경을 피하려면 항상 Intercom-Version 지정
2. 검색 API 효율적 사용 - 데이터 전송을 줄이려면 필터 및 페이지네이션 사용
3. 사용자 및 리드 모두 동기화 - Brevo에서 전체 퍼널 캡처
4. 대화 태그 매핑 - 지원 후 마케팅 세그먼트에 대화 태그 사용
5. 맞춤 이벤트 추적 - 행동 타겟팅을 위해 주요 제품 이벤트를 Intercom에 제출
6. 연락처 병합 처리 - 중복 연락처에 대한 병합 로직 구현

보안

• 액세스 토큰 - 비공개 앱을 위한 Bearer 토큰 인증
• OAuth 2.0 - 클라이언트 시크릿이 있는 공개 앱을 위한 위임된 인증
• 웹훅 확인 - X-Hub-Signature를 통한 HMAC SHA-1 서명 검증
• TLS 암호화 - HTTPS를 통해 암호화된 모든 API 통신
• 데이터 접근 제어 - 앱 구성별 세분화된 데이터 접근

관련 리소스

• Intercom 개발자 문서
• Intercom API 레퍼런스
• Zendesk 커넥터
• 고객 동기화 스킬
• Brevo Contacts API