---
name: HubSpot CRM
priority: 2
keywords: hubspot, hub spot, هاب سبوت, crm, contacts, leads, deals, pipeline, صفقات, جهات اتصال, عملاء محتملين, marketing, hub, sequence, sequences, campaign, contact list, تواصل
---

# HubSpot CRM Integration

## متى تستخدم / When to use
أي طلب لإنشاء/قراءة/تحديث contacts, deals, companies, tickets في HubSpot، أو استخراج تقارير pipeline، أو دفع leads جديدة من نموذج/WhatsApp إلى HubSpot.

## المصادقة
- **Private App Token** (الأبسط): انشأه من Settings → Integrations → Private Apps. صلاحيات تختار حسب الحاجة.
- خزّنه: `HUBSPOT_TOKEN=pat-na1-...` في `<dataDir>/.env`
- Base URL: `https://api.hubapi.com`

## العمليات الأساسية

### Contacts
```bash
# إنشاء contact
exec_command "curl -s -X POST -H 'Authorization: Bearer $HUBSPOT_TOKEN' -H 'Content-Type: application/json' \
  -d '{\"properties\":{\"email\":\"ahmed@example.com\",\"firstname\":\"Ahmed\",\"lastname\":\"Al-Saudi\",\"phone\":\"+966500000000\",\"company\":\"TaseesAI\"}}' \
  'https://api.hubapi.com/crm/v3/objects/contacts'"

# بحث contact بالإيميل
exec_command "curl -s -X POST -H 'Authorization: Bearer $HUBSPOT_TOKEN' -H 'Content-Type: application/json' \
  -d '{\"filterGroups\":[{\"filters\":[{\"propertyName\":\"email\",\"operator\":\"EQ\",\"value\":\"ahmed@example.com\"}]}],\"properties\":[\"firstname\",\"lastname\",\"phone\",\"lifecyclestage\"]}' \
  'https://api.hubapi.com/crm/v3/objects/contacts/search'"

# تحديث contact
exec_command "curl -s -X PATCH -H 'Authorization: Bearer $HUBSPOT_TOKEN' -H 'Content-Type: application/json' \
  -d '{\"properties\":{\"lifecyclestage\":\"customer\"}}' \
  'https://api.hubapi.com/crm/v3/objects/contacts/$CONTACT_ID'"

# قائمة كل الـcontacts (page 1)
exec_command "curl -s -H 'Authorization: Bearer $HUBSPOT_TOKEN' \
  'https://api.hubapi.com/crm/v3/objects/contacts?limit=20&properties=firstname,lastname,email,phone,createdate'"
```

### Deals (صفقات)
```bash
# إنشاء deal
exec_command "curl -s -X POST -H 'Authorization: Bearer $HUBSPOT_TOKEN' -H 'Content-Type: application/json' \
  -d '{\"properties\":{\"dealname\":\"TaseesAI Q3 Plan\",\"amount\":\"50000\",\"dealstage\":\"qualifiedtobuy\",\"closedate\":\"2026-09-30\",\"pipeline\":\"default\"}}' \
  'https://api.hubapi.com/crm/v3/objects/deals'"

# قائمة deals في pipeline معين
exec_command "curl -s -X POST -H 'Authorization: Bearer $HUBSPOT_TOKEN' -H 'Content-Type: application/json' \
  -d '{\"filterGroups\":[{\"filters\":[{\"propertyName\":\"dealstage\",\"operator\":\"EQ\",\"value\":\"qualifiedtobuy\"}]}],\"properties\":[\"dealname\",\"amount\",\"closedate\",\"hubspot_owner_id\"]}' \
  'https://api.hubapi.com/crm/v3/objects/deals/search'"

# نقل deal لمرحلة جديدة
exec_command "curl -s -X PATCH -H 'Authorization: Bearer $HUBSPOT_TOKEN' -H 'Content-Type: application/json' \
  -d '{\"properties\":{\"dealstage\":\"closedwon\"}}' \
  'https://api.hubapi.com/crm/v3/objects/deals/$DEAL_ID'"
```

### Companies
```bash
# إنشاء شركة
exec_command "curl -s -X POST -H 'Authorization: Bearer $HUBSPOT_TOKEN' -H 'Content-Type: application/json' \
  -d '{\"properties\":{\"name\":\"تأسيس\",\"domain\":\"taseesai.com\",\"city\":\"Jeddah\",\"country\":\"Saudi Arabia\"}}' \
  'https://api.hubapi.com/crm/v3/objects/companies'"
```

### Pipeline reports (Conversion / Velocity)
```bash
# نسبة التحويل بين مرحلتين
exec_command "curl -s -X POST -H 'Authorization: Bearer $HUBSPOT_TOKEN' -H 'Content-Type: application/json' \
  -d '{\"filterGroups\":[{\"filters\":[{\"propertyName\":\"createdate\",\"operator\":\"GTE\",\"value\":\"2026-01-01\"}]}],\"properties\":[\"dealstage\",\"amount\"]}' \
  'https://api.hubapi.com/crm/v3/objects/deals/search?limit=200'"
# ← ثم احسب: count(closedwon) / count(qualifiedtobuy) × 100
```

## أنماط Saudi-context شائعة
- **Form on Salla/Zid → HubSpot lead**: استدعِ `web_fetch` على submission webhook، ثم POST contact.
- **WhatsApp → HubSpot**: لما يجي رسالة WhatsApp جديد من رقم غير مسجّل، أنشئ contact تلقائياً.
- **Owner reassignment**: استخدم `hubspot_owner_id` للتعيين على فريق المبيعات.

## أمثلة / Examples
- "أضف ahmed@example.com إلى HubSpot كـlead" → POST contact with lifecyclestage=lead.
- "كم صفقة في pipeline التأهل" → search deals where dealstage=qualifiedtobuy.
- "اجعل صفقة شركة X مغلقة وفائزة" → search deal بـcompany association، PATCH dealstage=closedwon.
- "تقرير صفقات هذا الشهر" → search deals بـcreatedate ≥ بداية الشهر.

## القواعد الذهبية
- ❌ **ممنوع** حذف contacts/deals بدون تأكيد صريح من المالك ("متأكد؟").
- ❌ **لا تنشئ duplicates** — ابحث بالإيميل/الجوال قبل الإنشاء.
- ✅ **استخدم `hubspot_owner_id`** للتعيين الصحيح بدل ما تترك unassigned.
- ✅ **ربط contact بـcompany** عبر associations API بعد كل إنشاء.
