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 Webhook の処理

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 はプランに基づいてレート制限を適用します。

追加の制限:

• 一括操作: 一括リクエストあたり 15 連絡先
• イベント送信: ワークスペースあたり 500 イベント/秒
• Webhook 配信: 24 時間の自動リトライ
• データエクスポート: 同時エクスポート 1 件

トラブルシューティング

一般的な問題

デバッグモード

詳細ロギングを有効化:

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

接続テスト

tajo connectors test intercom
# ✓ API 接続成功
# ✓ 連絡先読み取り可能
# ✓ 会話読み取り可能
# ✓ 企業読み取り可能
# ✓ Webhook 登録済み

ベストプラクティス

1. API バージョンを固定する - 破壊的変更を避けるため常に Intercom-Version を指定
2. Search API を効率的に使用する - フィルタとページネーションを使用してデータ転送を削減
3. ユーザーとリードの両方を同期する - ファネル全体を Brevo でキャプチャ
4. 会話タグをマッピングする - サポート後のマーケティングセグメントに会話タグを使用
5. カスタムイベントをトラッキングする - 行動ターゲティングのため主要な製品イベントを Intercom に送信
6. 連絡先のマージを処理する - 重複連絡先のマージロジックを実装

セキュリティ

• アクセストークン - プライベートアプリ用の Bearer トークン認証
• OAuth 2.0 - パブリックアプリ用の委任認可(クライアントシークレット付き)
• Webhook 検証 - X-Hub-Signature による HMAC SHA-1 署名検証
• TLS 暗号化 - すべての API 通信は HTTPS で暗号化
• データアクセス制御 - アプリ設定ごとの細かいデータアクセス

関連リソース

• Intercom Developer ドキュメント
• Intercom API リファレンス
• Zendesk コネクタ
• 顧客同期スキル
• Brevo Contacts API