---
title: "Intercom 커넥터"
description: "Tajo를 통해 Intercom의 연락처, 대화, 회사, 참여 이벤트를 Brevo와 동기화하는 완전한 통합 가이드입니다."
url: https://tajo.io/kr/docs/connectors/support/intercom/
markdown: https://tajo.io/kr/docs/connectors/support/intercom.md
lang: ko-KR
robots: noindex
---

Tajo 사전 이용 신청

이름과 회사 이메일 주소를 입력하세요. Tajo 이용 신청을 확인할 수 있는 링크를 이메일로 보내드립니다.

# Intercom 커넥터

커넥터 상태: 예정 아직 구축되지 않았습니다. Tajo는 현재 이 커넥터를 실행하지 않습니다.

| 원본 필드 | 대상 필드 | 예시 값 |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

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

## 개요

| 속성 | 값 |
| --- | --- |
| **플랫폼** | Intercom |
| **카테고리** | Support |
| **설정 복잡도** | 중간 |
| **공식 통합** | 아니오 |
| **동기화 데이터** | 연락처, 대화, 회사, 이벤트 |
| **API Base URL** | `https://api.intercom.io` |

## 기능

- **연락처 동기화** - 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. 액세스 토큰 복사

```bash
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 데이터에 접근하는 통합의 경우.

```bash
# 인증 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}"
```

API 버전 관리

요청에 항상 `Intercom-Version` 헤더를 포함하십시오. Tajo는 기본적으로 API 버전 2.11을 사용합니다. 호환성 손상 변경 사항은 Intercom 변경 로그를 확인하십시오.

## 구성

### 기본 설정

```yaml
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 연락처 속성에 매핑합니다.

#### 기본 매핑

| Parameter | Type | Description |
| --- | --- | --- |
| `email` required | string | 연락처 이메일 주소 (고유 식별자) |
| `name` optional | string | 전체 이름, FIRSTNAME/LASTNAME으로 분할됨 |
| `phone` optional | string | WhatsApp/SMS용 SMS 속성에 매핑 |
| `role` optional | string | 연락처 유형: user 또는 lead |
| `company.name` optional | string | 연결된 회사 이름 |
| `signed_up_at` optional | timestamp | 사용자 가입 날짜 |
| `last_seen_at` optional | timestamp | 마지막 활성 타임스탬프 |
| `custom_attributes` optional | object | 맞춤 속성 키-값 쌍 |

#### 맞춤 속성 매핑

```yaml
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

| 메서드 | 엔드포인트 | 설명 |
| --- | --- | --- |
| `GET` | `/contacts` | 모든 연락처 목록 |
| `POST` | `/contacts` | 연락처 생성 |
| `PUT` | `/contacts/{id}` | 연락처 업데이트 |
| `GET` | `/contacts/{id}` | 연락처 가져오기 |
| `POST` | `/contacts/search` | 연락처 검색 |
| `DELETE` | `/contacts/{id}` | 연락처 아카이브 |

### Conversations API

| 메서드 | 엔드포인트 | 설명 |
| --- | --- | --- |
| `GET` | `/conversations` | 대화 목록 |
| `GET` | `/conversations/{id}` | 대화 가져오기 |
| `POST` | `/conversations` | 대화 생성 |
| `POST` | `/conversations/{id}/reply` | 대화에 응답 |
| `POST` | `/conversations/{id}/parts` | 대화 부분 추가 |

### Companies API

| 메서드 | 엔드포인트 | 설명 |
| --- | --- | --- |
| `GET` | `/companies` | 회사 목록 |
| `POST` | `/companies` | 회사 생성 또는 업데이트 |
| `GET` | `/companies/{id}` | 회사 가져오기 |
| `GET` | `/companies/{id}/contacts` | 회사 연락처 목록 |

### Events API

| 메서드 | 엔드포인트 | 설명 |
| --- | --- | --- |
| `POST` | `/events` | 이벤트 제출 |
| `GET` | `/events?type=user&intercom_user_id={id}` | 사용자 이벤트 목록 |

## 이벤트

### 대화 이벤트

| 이벤트 | 트리거 | 사용 사례 |
| --- | --- | --- |
| `conversation.created` | 새 대화 시작됨 | 지원 티켓 알림 |
| `conversation.closed` | 대화 해결됨 | CSAT 설문 트리거 |
| `conversation.rating.added` | 평가 제출됨 | 만족도 추적 |
| `conversation.snoozed` | 대화 일시 중지됨 | 후속 조치 일정 |

### 연락처 이벤트

| 이벤트 | 트리거 | 사용 사례 |
| --- | --- | --- |
| `contact.created` | 새 연락처 추가됨 | 환영 시퀀스 |
| `contact.updated` | 연락처 데이터 변경됨 | 속성 동기화 |
| `contact.deleted` | 연락처 아카이브됨 | 정리 |
| `contact.tag.created` | 연락처에 태그 추가됨 | 세그먼트 업데이트 |

### 사용자 이벤트

| 이벤트 | 트리거 | 사용 사례 |
| --- | --- | --- |
| `user.created` | 새 사용자 가입 | 온보딩 플로 |
| `user.email.updated` | 이메일 변경됨 | 연락처 병합 |
| `user.unsubscribed` | 이메일 구독 취소됨 | 선호도 업데이트 |

## 코드 예제

### 커넥터 초기화

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

### 연락처 및 대화 동기화

```javascript
// 연락처 및 대화 데이터 전체 동기화
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 웹훅 처리

```javascript
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은 요금제에 따라 속도 제한을 적용합니다.

| 요금제 | 속도 제한 | 세부 사항 |
| --- | --- | --- |
| Starter | 20 요청/10초 | 앱당 |
| Pro | 50 요청/10초 | 앱당 |
| Premium | 100 요청/10초 | 앱당 |
| 검색 엔드포인트 | 1 요청/초 | 앱당 |
| 스크롤 엔드포인트 | 1 요청/분 | 앱당 |

추가 제한:

- **Bulk 작업**: 대량 요청당 15 연락처
- **이벤트 제출**: 워크스페이스당 500 이벤트/초
- **웹훅 배달**: 24시간 동안 자동 재시도
- **데이터 내보내기**: 1개 동시 내보내기

속도 제한 응답

Intercom은 `Retry-After` 헤더와 함께 `429 Too Many Requests`를 반환합니다. 지수 백오프를 구현하고 재시도 기간을 준수하십시오.

## 문제 해결

### 일반적인 문제

| 문제 | 원인 | 해결 방법 |
| --- | --- | --- |
| 401 Unauthorized | 잘못되거나 만료된 토큰 | Developer Hub에서 액세스 토큰 재생성 |
| 연락처가 동기화되지 않음 | 이메일 필드 누락 | Intercom 리드는 이메일이 없을 수 있음; 역할별 필터링 |
| 대화 데이터 비어 있음 | 앱에 대화 범위가 없음 | 대화 읽기 권한으로 재인증 |
| 웹훅이 수신되지 않음 | 웹훅이 등록되지 않음 | Developer Hub 설정에서 웹훅 구성 |
| API 버전 불일치 | 새 버전의 호환성 손상 변경 | `Intercom-Version` 헤더로 API 버전 고정 |

### 디버그 모드

자세한 로깅 활성화:

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

### 연결 테스트

```bash
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 개발자 문서](https://developers.intercom.com/docs)
- [Intercom API 레퍼런스](https://developers.intercom.com/docs/references/introduction)
- [Zendesk 커넥터](https://tajo.io/kr/docs/connectors/support/zendesk)
- [고객 동기화 스킬](https://tajo.io/kr/docs/skills/data-sync/customer-sync)
- [Brevo Contacts API](https://tajo.io/kr/docs/contact-management)