HubSpot Connector

HubSpot Connector

เชื่อมต่อ HubSpot CRM กับ Brevo ผ่าน Tajo สำหรับการซิงค์ผู้ติดต่อแบบสองทิศทาง การติดตามดีล ข้อมูลการมีส่วนร่วม และระบบอัตโนมัติทางการตลาดแบบรวมศูนย์บนทั้งสองแพลตฟอร์ม

ภาพรวม

ฟีเจอร์

• การซิงค์ผู้ติดต่อแบบสองทิศทาง - รักษาผู้ติดต่อให้ซิงค์กันระหว่าง HubSpot และ Brevo แบบเรียลไทม์
• การติดตามไปป์ไลน์ดีล - ซิงค์ขั้นตอนและมูลค่าดีลสำหรับการแบ่งกลุ่มตามรายได้
• การซิงค์ข้อมูลบริษัท - เชื่อมโยงผู้ติดต่อกับบันทึกบริษัทและข้อมูลองค์กร
• การผสานรวมตั๋ว - ติดตามตั๋วสนับสนุนสำหรับการให้คะแนนสุขภาพของลูกค้า
• การติดตามการมีส่วนร่วม - ซิงค์การเปิดอีเมล การคลิก การประชุม การโทร และบันทึก
• รองรับอ็อบเจกต์แบบกำหนดเอง - แมป HubSpot custom objects กับแอตทริบิวต์ Brevo
• ทริกเกอร์เวิร์กโฟลว์ - ใช้การเปลี่ยนแปลงขั้นตอนวงจรชีวิต HubSpot เพื่อทริกเกอร์ระบบอัตโนมัติ Brevo
• เหตุการณ์ Webhook - การแจ้งเตือนแบบเรียลไทม์สำหรับการเปลี่ยนแปลงข้อมูล CRM

ข้อกำหนดเบื้องต้น

ก่อนเริ่มต้น ตรวจสอบให้แน่ใจว่าคุณมี:

1. บัญชี HubSpot (Free, Starter, Professional หรือ Enterprise)
2. Private app หรือ OAuth app ของ HubSpot พร้อม scopes ที่จำเป็น
3. บัญชี Brevo ที่มีสิทธิ์เข้าถึง API
4. บัญชี Tajo

การยืนยันตัวตน

Private App Access Token (แนะนำ)

สร้าง private app ใน HubSpot สำหรับการเข้าถึง API โดยตรงพร้อมการควบคุม scope แบบละเอียด

1. ไปที่ HubSpot Settings > Integrations > Private Apps
2. สร้าง private app ใหม่
3. กำหนดค่า scopes ที่จำเป็น
4. คัดลอก access token

curl -X GET "https://api.hubapi.com/crm/v3/objects/contacts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

OAuth 2.0

ใช้ OAuth 2.0 สำหรับการผสานรวมหลายบัญชีที่ต้องการการอนุญาตจากผู้ใช้

# Authorization URL
https://app.hubspot.com/oauth/authorize?client_id={client_id}&scope=crm.objects.contacts.read&redirect_uri={redirect_uri}

Scopes ที่จำเป็น

crm.objects.contacts.read
crm.objects.contacts.write
crm.objects.companies.read
crm.objects.deals.read
crm.objects.deals.write
crm.objects.custom.read
crm.schemas.custom.read

การกำหนดค่า

การตั้งค่าพื้นฐาน

connectors:
  hubspot:
    enabled: true
    access_token: "${HUBSPOT_ACCESS_TOKEN}"

    # Data sync options
    sync:
      contacts: true
      companies: true
      deals: true
      tickets: true
      engagements: true

    # Sync direction
    direction: bidirectional  # or 'hubspot_to_brevo' | 'brevo_to_hubspot'

    # List assignment in Brevo
    lists:
      all_contacts: 10
      qualified_leads: 11
      customers: 12

การแมปฟิลด์

แมปคุณสมบัติ HubSpot กับแอตทริบิวต์ผู้ติดต่อ Brevo:

การแมปคุณสมบัติแบบกำหนดเอง

field_mapping:
  # Standard fields
  email: email
  firstname: FIRSTNAME
  lastname: LASTNAME
  phone: SMS

  # CRM fields
  lifecyclestage: LIFECYCLE_STAGE
  hs_lead_status: LEAD_STATUS
  company: COMPANY_NAME

  # Deal metrics
  hs_total_deal_value: DEAL_VALUE
  num_associated_deals: DEAL_COUNT

  # Custom properties
  preferred_channel: PREFERRED_CHANNEL
  customer_segment: SEGMENT

API Endpoints

CRM Objects

Associations

Engagements

เหตุการณ์

เหตุการณ์ผู้ติดต่อ

เหตุการณ์ดีล

เหตุการณ์บริษัท

ตัวอย่างโค้ด

เริ่มต้น Connector

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

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

// Connect HubSpot
await tajo.connectors.connect('hubspot', {
  accessToken: process.env.HUBSPOT_ACCESS_TOKEN
});

รันการซิงค์ผู้ติดต่อ

// Full bidirectional sync
await tajo.connectors.sync('hubspot', {
  type: 'full',
  resources: ['contacts', 'companies', 'deals'],
  direction: 'bidirectional',
  since: '2023-01-01'
});

// Check sync status
const status = await tajo.connectors.status('hubspot');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   contactsSynced: 34200,
//   companiesSynced: 5100,
//   dealsSynced: 2340
// }

จัดการเหตุการณ์ Webhook

// Handle HubSpot webhook notifications
app.post('/webhooks/hubspot', async (req, res) => {
  const signature = req.get('X-HubSpot-Signature-v3');

  // Verify webhook signature
  if (!verifyHubSpotSignature(req.body, signature)) {
    return res.status(401).send('Unauthorized');
  }

  for (const event of req.body) {
    await tajo.connectors.handleWebhook('hubspot', {
      eventType: event.subscriptionType,
      objectId: event.objectId,
      propertyName: event.propertyName,
      propertyValue: event.propertyValue
    });
  }

  res.status(200).send('OK');
});

ขีดจำกัดอัตรา

HubSpot ใช้ขีดจำกัดอัตราต่อ private app หรือ OAuth app:

ขีดจำกัดเพิ่มเติม:

• Search API: 5 คำขอ/วินาทีต่อ app
• การดำเนินการแบบ Batch: 100 รายการต่อคำขอ batch
• ขีดจำกัดรายวัน: 500,000 คำขอ/วัน (OAuth apps)

การแก้ไขปัญหา

ปัญหาทั่วไป

โหมด Debug

เปิดใช้การบันทึกข้อมูลแบบละเอียด:

connectors:
  hubspot:
    debug: true
    log_level: verbose
    log_webhooks: true

ทดสอบการเชื่อมต่อ

tajo connectors test hubspot
# ✓ API connection successful
# ✓ Contacts readable
# ✓ Companies readable
# ✓ Deals readable
# ✓ Webhooks registered

แนวทางปฏิบัติที่ดีที่สุด

1. ใช้ private apps แทน API keys - API keys เลิกใช้แล้ว ใช้ private apps เพื่อความปลอดภัยที่ดีกว่า
2. ใช้การซิงค์สองทิศทางอย่างระมัดระวัง - หลีกเลี่ยงลูปอนันต์โดยการติดตามแหล่งซิงค์
3. แมปขั้นตอนวงจรชีวิต - ใช้ขั้นตอนวงจรชีวิต HubSpot เพื่อแบ่งกลุ่มผู้ติดต่อใน Brevo
4. ส่งคำขอ API เป็น Batch - ใช้ batch endpoints สำหรับการดำเนินการจำนวนมากเพื่ออยู่ภายในขีดจำกัดอัตรา
5. ตรวจสอบการส่ง webhook - ตั้งค่าตรรกะการลองใหม่และการจัดการ dead letter
6. ใช้การซิงค์แบบเพิ่มทีละน้อย - ซิงค์เฉพาะบันทึกที่เปลี่ยนแปลงโดยใช้คุณสมบัติ lastmodifieddate

ความปลอดภัย

• Private App Tokens - Access tokens แบบกำหนดขอบเขตพร้อมสิทธิ์แบบละเอียด
• OAuth 2.0 - การอนุญาตตามมาตรฐานอุตสาหกรรมพร้อมการหมุนเวียน refresh token
• ลายเซ็น Webhook - การตรวจสอบลายเซ็นตาม HMAC (v3)
• การเข้ารหัส TLS - การสื่อสาร API ทั้งหมดเข้ารหัสระหว่างส่งผ่าน
• สิทธิ์แบบกำหนดขอบเขต - การเข้าถึง scope ขั้นต่ำที่จำเป็นต่อการผสานรวม

แหล่งข้อมูลที่เกี่ยวข้อง

• HubSpot API Documentation
• HubSpot Authentication Guide
• Salesforce Connector
• Customer Sync Skill
• Brevo Contacts API