هاب‌اسپات

نود HubSpot چیست؟

نود HubSpot امکان اتصال و خودکارسازی فرآیندهای CRM، بازاریابی، فروش و خدمات مشتری را در n8n فراهم می‌کند. HubSpot یک پلتفرم All-in-One است که شامل Marketing Hub، Sales Hub، Service Hub، CMS Hub و Operations Hub می‌شود.

قابلیت‌های کلیدی:

• مدیریت Contacts: ایجاد، ویرایش، حذف، جستجو و لیست مخاطبین
• مدیریت Companies: عملیات CRUD روی شرکت‌ها و سازمان‌ها
• مدیریت Deals: ایجاد و مدیریت معاملات، تغییر مرحله Pipeline
• مدیریت Tickets: سیستم تیکتینگ و پشتیبانی مشتری
• Engagements: ثبت تماس‌ها، ایمیل‌ها، یادداشت‌ها و وظایف
• Forms: دریافت اطلاعات فرم‌ها و ثبت‌نام‌ها
• Lists: مدیریت لیست‌های مخاطبین استاتیک و داینامیک
• Properties: مدیریت فیلدهای سفارشی CRM
• Associations: ارتباط‌دهی بین آبجکت‌های مختلف CRM
• Pipeline Management: مدیریت مراحل فروش و تیکت

HubSpot Trigger:

• دریافت webhook event‌ها هنگام تغییر در contacts، deals و tickets
• Trigger بر اساس form submission
• دریافت رویدادهای مربوط به email marketing
• Polling برای بررسی دوره‌ای تغییرات

محدودیت‌های API:

• Free/Starter: ۱۰۰ درخواست هر ۱۰ ثانیه
• Professional/Enterprise: ۱۵۰ درخواست هر ۱۰ ثانیه
• Search API: ۴ درخواست در ثانیه
• Batch API: ۱۰۰ رکورد در هر درخواست

کاربردهای رایج

۱. ثبت خودکار Lead از فرم وب‌سایت

هر بار که فرمی در سایت پر شود، مخاطب جدید در HubSpot ایجاد و در Pipeline فروش وارد شود.

Webhook (فرم سایت)
  → HubSpot (Create Contact)
    email: {{$json.email}}
    firstname: {{$json.name}}
    phone: {{$json.phone}}
    lifecyclestage: lead
  → HubSpot (Create Deal)
    dealname: "درخواست {{$json.name}}"
    dealstage: appointmentscheduled
    amount: {{$json.estimatedValue}}
  → HubSpot (Create Association)
    contact → deal
  → Telegram (اعلان به تیم فروش)

۲. همگام‌سازی مخاطبین با سایر CRMها

مخاطبین جدید یا ویرایش‌شده HubSpot را با سیستم‌های دیگر sync کنید.

Schedule (هر ۱۵ دقیقه)
  → HubSpot (Search Contacts)
    filter: lastmodifieddate > lastRun
  → Loop
    → IF (exists in other CRM)
      → HTTP Request (Update in other CRM)
    → Else
      → HTTP Request (Create in other CRM)

۳. اتوماسیون Pipeline فروش

وقتی معامله به مرحله خاصی برسد، اقدامات خودکار انجام شود.

HubSpot Trigger (deal.propertyChange: dealstage)
  → Switch (بررسی مرحله)
    Case "qualifiedtobuy":
      → Gmail (ارسال پیشنهاد قیمت)
      → HubSpot (Create Engagement: TASK)
        body: "پیگیری تماس بعد از ارسال پیشنهاد"
    Case "closedwon":
      → HubSpot (Update Contact: lifecyclestage = customer)
      → Gmail (ارسال ایمیل خوشامدگویی)
      → Telegram (تبریک به تیم فروش)
    Case "closedlost":
      → HubSpot (Create Engagement: NOTE)
        body: "معامله از دست رفت"
      → Gmail (ارسال نظرسنجی)

۴. ثبت تیکت پشتیبانی از ایمیل

ایمیل‌های دریافتی را به تیکت HubSpot تبدیل کنید.

IMAP (ایمیل جدید)
  → HubSpot (Search Contact: email)
  → IF (مخاطب وجود دارد)
    → HubSpot (Create Ticket)
      subject: {{$json.subject}}
      content: {{$json.body}}
      hs_pipeline_stage: 1
    → HubSpot (Create Association: ticket → contact)
  → Else
    → HubSpot (Create Contact)
    → HubSpot (Create Ticket)
    → HubSpot (Create Association)

۵. Lead Scoring اتوماتیک

بر اساس رفتار کاربر، امتیاز Lead را به‌روزرسانی کنید.

Webhook (رویداد سایت: page visit, download, etc.)
  → HubSpot (Get Contact)
  → Code (محاسبه امتیاز)
    بازدید صفحه قیمت: +10
    دانلود PDF: +20
    شرکت در وبینار: +30
    باز کردن ایمیل: +5
  → HubSpot (Update Contact)
    hs_lead_status: بر اساس امتیاز
    lead_score: {{$json.newScore}}
  → IF (score > 80)
    → HubSpot (Create Deal: SQL)
    → Telegram (اعلان: Lead داغ!)

۶. گزارش فروش روزانه

هر روز گزارش خلاصه فروش را برای مدیران ارسال کنید.

Schedule (هر روز ساعت ۲۰)
  → HubSpot (Search Deals: امروز closedwon)
  → HubSpot (Search Deals: امروز ایجاد شده)
  → HubSpot (Search Deals: در Pipeline)
  → Code (ساخت گزارش)
    totalWon, totalCreated, totalPipeline
    topSalesRep, averageDealSize
  → Telegram (ارسال گزارش)
  → Gmail (ارسال به مدیران)

۷. Onboarding خودکار مشتری جدید

پس از بسته شدن معامله، فرآیند onboarding خودکار شروع شود.

HubSpot Trigger (deal.closedwon)
  → HubSpot (Get Contact: associated)
  → HubSpot (Update Contact: lifecyclestage = customer)
  → Gmail (ارسال ایمیل خوشامدگویی + راهنما)
  → HubSpot (Create Engagement: TASK)
    body: "تماس onboarding - ۴۸ ساعت"
  → Google Calendar (ایجاد رویداد جلسه معارفه)
  → Slack (اعلان به تیم Customer Success)

۸. ارسال ایمیل‌های بازاریابی هوشمند

بر اساس رفتار و ویژگی‌های مخاطب، ایمیل هدفمند ارسال کنید.

Schedule (هفتگی)
  → HubSpot (Search Contacts)
    filter: lifecyclestage = lead AND
            lastmodifieddate < 7 days ago AND
            hs_email_optout = false
  → Loop
    → IF (industry = "technology")
      → Gmail (ارسال محتوای فناوری)
    → ELSE IF (industry = "retail")
      → Gmail (ارسال محتوای خرده‌فروشی)
    → HubSpot (Create Engagement: EMAIL)
    → Wait (2 seconds)

۹. همگام‌سازی فروشگاه آنلاین با CRM

سفارشات فروشگاه آنلاین را با HubSpot sync کنید.

Webhook (سفارش جدید WooCommerce/Shopify)
  → HubSpot (Search Contact: email)
  → IF (وجود دارد)
    → HubSpot (Update Contact: total_purchases++)
  → Else
    → HubSpot (Create Contact: customer)
  → HubSpot (Create Deal)
    dealname: "سفارش #{{$json.orderId}}"
    amount: {{$json.total}}
    dealstage: closedwon
  → HubSpot (Create Association: contact → deal)

۱۰. اعلان‌های فروش هوشمند

اعلان‌های لحظه‌ای بر اساس فعالیت‌های مهم CRM ارسال کنید.

HubSpot Trigger (contact/deal changes)
  → Switch (نوع رویداد)
    Case "معامله بزرگ ایجاد شده" (amount > 50M):
      → Telegram (اعلان فوری به مدیر فروش)
    Case "مخاطب VIP فعالیت کرد":
      → Telegram (اعلان به account manager)
    Case "تیکت اولویت بالا":
      → Telegram (اعلان به تیم پشتیبانی)
      → Gmail (ایمیل فوری)

۱۱. پاکسازی و بهبود کیفیت داده

به صورت دوره‌ای داده‌های CRM را بررسی و اصلاح کنید.

Schedule (هفتگی)
  → HubSpot (List Contacts)
  → Code (بررسی کیفیت)
    - مخاطبین بدون ایمیل
    - شماره تلفن نامعتبر
    - مخاطبین تکراری
    - فیلدهای خالی مهم
  → HubSpot (Update Contact: تصحیح فرمت)
  → Gmail (گزارش کیفیت داده به ادمین)

نکات حرفه‌ای

۱. از Batch API برای عملیات حجیم استفاده کنید

بجای ارسال تک‌تک، تا ۱۰۰ رکورد را در یک درخواست ارسال کنید:

Split In Batches (100)
  → HTTP Request (POST /crm/v3/objects/contacts/batch/create)
    Body: { inputs: [...] }

۲. از Search API بجای List استفاده کنید

Search API بسیار قدرتمندتر از List است و فیلترهای پیچیده را پشتیبانی می‌کند:

{
  "filterGroups": [{
    "filters": [
      {"propertyName": "lifecyclestage", "operator": "EQ", "value": "lead"},
      {"propertyName": "createdate", "operator": "GT", "value": "2024-01-01"}
    ]
  }]
}

۳. Pipeline Stages را بشناسید

مراحل Pipeline فروش پیش‌فرض HubSpot:

appointmentscheduled → قرار ملاقات
qualifiedtobuy → واجد شرایط خرید
presentationscheduled → ارائه زمان‌بندی شده
decisionmakerboughtin → تصمیم‌گیرنده موافقت کرد
contractsent → قرارداد ارسال شده
closedwon → بسته شده - موفق
closedlost → بسته شده - ناموفق

۴. Lifecycle Stages را رعایت کنید

ترتیب مراحل چرخه حیات مخاطب:

subscriber → lead → marketingqualifiedlead → salesqualifiedlead → opportunity → customer → evangelist → other

HubSpot اجازه نمی‌دهد مرحله را به عقب برگردانید (مگر با API).

۵. از Associations حداکثر استفاده را ببرید

ارتباط بین آبجکت‌ها قدرت CRM را چند برابر می‌کند:

Contact → Company: مخاطب متعلق به شرکت
Contact → Deal: مخاطب مرتبط با معامله
Deal → Company: معامله مرتبط با شرکت
Ticket → Contact: تیکت مرتبط با مخاطب

۶. از Workflow‌های HubSpot + n8n ترکیبی استفاده کنید

HubSpot Workflows برای اقدامات داخلی و n8n برای یکپارچه‌سازی خارجی:

• HubSpot Workflow: تغییر lifecycle stage
• n8n: ارسال پیام تلگرام، sync با سیستم دیگر

۷. Property‌های سفارشی بسازید

برای نیازهای خاص کسب‌وکار، property سفارشی تعریف کنید:

Settings > Properties > Create Property
  Name: source_campaign
  Type: Single-line text
  Group: Contact Information

۸. Error Handling حرفه‌ای

همیشه خطاهای HubSpot را handle کنید:

HubSpot (Create Contact)
  → Success: ادامه workflow
  → Error 409: HubSpot (Update Contact)
  → Error 429: Wait → Retry
  → Error 400: Log Error → Telegram Alert

۹. از Timestamp Milliseconds استفاده کنید

HubSpot تاریخ‌ها را به صورت Unix timestamp milliseconds ذخیره می‌کند:

// تبدیل تاریخ به HubSpot format
const timestamp = new Date('2024-01-01').getTime();
// → 1704067200000

// تبدیل از HubSpot
const date = new Date(1704067200000);

۱۰. Pagination برای دریافت همه داده‌ها

HubSpot حداکثر ۱۰۰ رکورد در هر درخواست برمی‌گرداند:

Set (after = null, allContacts = [])
  → Loop
    → HubSpot (List Contacts: after={{$json.after}})
    → Code (اضافه به allContacts)
    → IF (paging.next.after exists)
      → Set (after = next.after)
      → Back to Loop
    → Else: خروج

۱۱. Import/Export با CSV

برای Import حجیم، داده‌ها را از CSV بخوانید و batch ارسال کنید:

Read CSV → Split In Batches (100) → HubSpot (Batch Create) → Wait (1s)

۱۲. Lead Source Tracking

منبع ورود هر lead را ثبت کنید برای تحلیل ROI:

// property‌های tracking
hs_analytics_source: "ORGANIC_SEARCH"
hs_analytics_source_data_1: "google"
hs_analytics_first_url: "https://example.com/landing"

۱۳. از Owner ID برای Assign خودکار استفاده کنید

معاملات و تیکت‌ها را خودکار به تیم assign کنید:

IF (deal.amount > 100M)
  → HubSpot (Update Deal: hubspot_owner_id = seniorSalesId)
ELSE
  → HubSpot (Update Deal: hubspot_owner_id = juniorSalesId)

۱۴. Webhook Subscriptions را مدیریت کنید

رویدادهای مورد نظر:

contact.creation     → ایجاد مخاطب
contact.propertyChange → تغییر property
deal.creation        → ایجاد معامله
deal.propertyChange  → تغییر مرحله deal
ticket.creation      → ایجاد تیکت

۱۵. از HubSpot CRM Cards استفاده کنید

با ساخت CRM Cards، اطلاعات سیستم‌های خارجی را مستقیماً در HubSpot نمایش دهید. n8n می‌تواند endpoint مورد نیاز CRM Card را serve کند.

۱۶. Test با Sandbox Account

HubSpot Developer Account شامل یک Sandbox اکانت رایگان است. همیشه ابتدا workflow‌ها را در Sandbox تست کنید و سپس به Production منتقل کنید.

رفع مشکلات رایج

❌ خطای 401 Unauthorized

علت: Token نامعتبر یا منقضی شده

راه‌حل

• Private App Token خود را بررسی کنید
• اگر از OAuth2 استفاده می‌کنید، ممکن است Refresh Token منقضی شده باشد
• در n8n، Credential را مجدداً connect کنید
• مطمئن شوید که Private App حذف نشده است
• Token جدید generate کنید

❌ خطای 403 Forbidden

علت: دسترسی (Scope) کافی تنظیم نشده

راه‌حل

• Scopes مورد نیاز عملیات را بررسی کنید:
• خواندن مخاطب: crm.objects.contacts.read
• نوشتن مخاطب: crm.objects.contacts.write
• خواندن معامله: crm.objects.deals.read
• نوشتن معامله: crm.objects.deals.write
• برای Private App، به Settings > Private Apps بروید و scopes را اضافه کنید
• بعد از تغییر scopes، Token جدید ساخته می‌شود

❌ خطای 409 Conflict (Contact already exists)

علت: مخاطبی با این ایمیل وجود دارد

راه‌حل

• ابتدا با Search بررسی کنید آیا مخاطب وجود دارد
• از عملیات "Create or Update" استفاده کنید:

HubSpot (Search Contact: email)
    → IF (exists) → Update Contact
    → Else → Create Contact

• یا از Batch API با idProperty: email استفاده کنید

❌ خطای 429 Too Many Requests

علت: محدودیت Rate Limit

راه‌حل

• محدودیت‌ها: ۱۰۰-۱۵۰ req/10sec
• Wait node بین درخواست‌ها اضافه کنید
• از Batch API برای عملیات حجیم استفاده کنید (تا ۱۰۰ رکورد در هر درخواست)
• header Retry-After را بخوانید و منتظر بمانید
• در حلقه‌ها حتماً delay بگذارید:

Loop → HubSpot → Wait (200ms) → Next

❌ خطای 400 Bad Request

علت: داده‌های ارسالی نامعتبر

راه‌حل

• فرمت property name‌ها باید lowercase و underscore-separated باشد
• مقادیر enum (مثل lifecycle stage) باید exact match باشند
• تاریخ‌ها باید ISO 8601 یا Unix timestamp milliseconds باشند
• مقادیر عددی نباید string ارسال شوند
• property مورد نظر باید در HubSpot تعریف شده باشد

❌ Property پیدا نمی‌شود

علت: نام property اشتباه یا وجود ندارد

راه‌حل

• نام‌های property در HubSpot به صورت internal name هستند (مثل hs_lead_status نه "Lead Status")
• در HubSpot به Settings > Properties بروید و internal name را ببینید
• property‌های سفارشی با پیشوند خاصی ساخته نمی‌شوند
• از endpoint /properties/contacts برای دریافت لیست کامل properties استفاده کنید

❌ Association ایجاد نمی‌شود

علت: نوع Association اشتباه

راه‌حل

• از نام‌های صحیح association type استفاده کنید:
• contact_to_company
• contact_to_deal
• deal_to_company
• ticket_to_contact
• هر دو آبجکت باید قبل از association وجود داشته باشند
• شناسه‌ها باید numeric ID باشند (نه email یا نام)

❌ Webhook/Trigger دریافت نمی‌شود

علت: تنظیمات Webhook نادرست

راه‌حل

• مطمئن شوید n8n شما publicly accessible است
• آدرس webhook باید HTTPS باشد
• Subscription‌های مورد نظر را در HubSpot App فعال کنید
• در Developer Account > App > Webhooks بررسی کنید
• از n8n Webhook URL صحیح استفاده کنید