Trình Kết Nối Intercom

Kết nối Intercom workspace của bạn với Brevo qua Tajo để unified customer messaging, conversation tracking và engagement-driven marketing automation được hỗ trợ bởi dữ liệu support và product của bạn.

Tổng Quan

Tính Năng

• Đồng bộ contact - Đồng bộ hai chiều Intercom users và leads với contacts Brevo
• Theo dõi conversation - Đồng bộ dữ liệu conversation để phân đoạn dựa trên support
• Ánh xạ company - Liên kết contacts với companies cho account-based workflows
• Custom attributes - Ánh xạ Intercom custom attributes sang trường contact Brevo
• Theo dõi event - Đồng bộ custom events và user activities để targeting theo hành vi
• Đồng bộ tag - Ánh xạ Intercom tags sang Brevo list membership hoặc thuộc tính
• Dữ liệu Messenger - Theo dõi in-app messaging engagement và chat interactions
• Tích hợp AI agent - Đồng bộ kết quả conversation AI agent với Brevo

Yêu Cầu

Trước khi bắt đầu, hãy đảm bảo bạn có:

1. Intercom workspace (gói Starter, Pro, hoặc Premium)
2. Intercom app với access token (private app) hoặc OAuth được cấu hình (public app)
3. Tài khoản Brevo với quyền truy cập API
4. Tài khoản Tajo

Xác Thực

Access Token (Private App)

Cho private integrations truy cập dữ liệu workspace của bạn.

1. Vào Developer Hub > Your Apps > Create new app
2. Liên kết với Intercom workspace của bạn
3. Sao chép access token

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

OAuth 2.0 (Public App)

Cho integrations truy cập dữ liệu Intercom của khách hàng khác.

# Authorization URL
https://app.intercom.com/oauth?client_id={client_id}&state={state}

# Đổi token
curl -X POST https://api.intercom.io/auth/eagle/token \
  -d "client_id={client_id}" \
  -d "client_secret={client_secret}" \
  -d "code={auth_code}"

Cấu Hình

Thiết Lập Cơ Bản

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

    # Tùy chọn đồng bộ dữ liệu
    sync:
      contacts: true
      conversations: true
      companies: true
      events: true
      tags: true

    # Hướng đồng bộ
    direction: intercom_to_brevo

    # Gán danh sách Brevo
    lists:
      all_users: 35
      active_conversations: 36
      leads: 37

Ánh Xạ Trường

Ánh xạ dữ liệu contact Intercom sang thuộc tính liên hệ Brevo:

Ánh Xạ Custom Attribute

field_mapping:
  # Trường tiêu chuẩn
  email: email
  name: FULLNAME
  phone: SMS

  # Trường engagement
  signed_up_at: SIGNUP_DATE
  last_seen_at: LAST_ACTIVE
  session_count: SESSION_COUNT
  unsubscribed_from_emails: UNSUBSCRIBED

  # Trường company
  company.name: COMPANY_NAME
  company.plan: COMPANY_PLAN
  company.size: COMPANY_SIZE

  # Custom attributes
  custom_attributes.plan_tier: PLAN_TIER
  custom_attributes.feature_usage: FEATURE_USAGE

API Endpoints

Contacts API

Conversations API

Companies API

Events API

Sự Kiện

Sự Kiện Conversation

Sự Kiện Contact

Sự Kiện User

Ví Dụ Code

Khởi Tạo Trình Kết Nối

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

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

// Kết nối Intercom
await tajo.connectors.connect('intercom', {
  accessToken: process.env.INTERCOM_ACCESS_TOKEN,
  apiVersion: '2.11'
});

Đồng Bộ Contacts Và Conversations

// Full sync contacts và dữ liệu conversation
await tajo.connectors.sync('intercom', {
  type: 'full',
  resources: ['contacts', 'conversations', 'companies'],
  since: '2023-01-01'
});

// Kiểm tra trạng thái sync
const status = await tajo.connectors.status('intercom');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   contactsSynced: 14200,
//   conversationsSynced: 28400,
//   companiesSynced: 2100
// }

Xử Lý Intercom Webhooks

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

Giới Hạn Tốc Độ

Intercom áp dụng giới hạn tốc độ dựa trên gói của bạn:

Giới hạn bổ sung:

• Bulk operations: 15 contacts mỗi bulk request
• Event submissions: 500 events/giây mỗi workspace
• Webhook delivery: Tự động retry trong 24 giờ
• Data export: 1 export đồng thời

Khắc Phục Sự Cố

Sự Cố Phổ Biến

Chế Độ Debug

Bật verbose logging:

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

Kiểm Tra Kết Nối

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

Thực Hành Tốt Nhất

1. Ghim API version - Luôn chỉ định Intercom-Version để tránh breaking changes
2. Dùng search API hiệu quả - Dùng filters và pagination để giảm data transfer
3. Đồng bộ cả users và leads - Capture toàn bộ funnel trong Brevo
4. Ánh xạ conversation tags - Dùng conversation tags cho post-support marketing segments
5. Theo dõi custom events - Gửi key product events sang Intercom để behavioral targeting
6. Xử lý contact merges - Triển khai merge logic cho contacts trùng lặp

Bảo Mật

• Access Token - Xác thực bearer token cho private apps
• OAuth 2.0 - Ủy quyền delegated cho public apps với client secret
• Xác minh Webhook - Xác thực chữ ký HMAC SHA-1 qua X-Hub-Signature
• Mã hóa TLS - Tất cả giao tiếp API được mã hóa qua HTTPS
• Kiểm soát truy cập dữ liệu - Truy cập dữ liệu chi tiết theo cấu hình app

Tài Nguyên Liên Quan

• Tài Liệu Developer Intercom
• Tham Khảo API Intercom
• Trình Kết Nối Zendesk
• Customer Sync Skill
• Brevo Contacts API