موصل Intercom

موصل Intercom

اربط مساحة عمل Intercom الخاصة بك مع Brevo عبر Tajo لرسائل عملاء موحدة، وتتبع المحادثات، وأتمتة تسويق مدفوعة بالتفاعل تعمل ببيانات الدعم والمنتج الخاصة بك.

نظرة عامة

الميزات

• مزامنة جهات الاتصال - مزامنة ثنائية الاتجاه لمستخدمي وعملاء محتملين من Intercom مع جهات اتصال Brevo
• تتبع المحادثات - مزامنة بيانات المحادثات للتقسيم القائم على الدعم
• تعيين الشركات - ربط جهات الاتصال بالشركات لسير عمل قائم على الحسابات
• السمات المخصصة - ربط سمات Intercom المخصصة بحقول جهات اتصال Brevo
• تتبع الأحداث - مزامنة الأحداث المخصصة وأنشطة المستخدم للاستهداف السلوكي
• مزامنة الوسوم - ربط وسوم Intercom بعضوية قوائم أو سمات Brevo
• بيانات Messenger - تتبع تفاعل المراسلة داخل التطبيق وتفاعلات الدردشة
• تكامل وكيل الذكاء الاصطناعي - مزامنة نتائج محادثات وكلاء الذكاء الاصطناعي مع Brevo

المتطلبات الأساسية

قبل البدء، تأكد من توفر ما يلي:

1. مساحة عمل Intercom (خطة Starter أو Pro أو Premium)
2. تطبيق Intercom مع رمز الوصول (تطبيق خاص) أو OAuth مُعَد (تطبيق عام)
3. حساب Brevo مع وصول إلى API
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 لعملاء آخرين.

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

# Token exchange
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"

    # Data sync options
    sync:
      contacts: true
      conversations: true
      companies: true
      events: true
      tags: true

    # Sync direction
    direction: intercom_to_brevo

    # Brevo list assignment
    lists:
      all_users: 35
      active_conversations: 36
      leads: 37

تعيين الحقول

ربط بيانات جهات اتصال Intercom بسمات جهات اتصال Brevo:

تعيين السمات المخصصة

field_mapping:
  # Standard fields
  email: email
  name: FULLNAME
  phone: SMS

  # Engagement fields
  signed_up_at: SIGNUP_DATE
  last_seen_at: LAST_ACTIVE
  session_count: SESSION_COUNT
  unsubscribed_from_emails: UNSUBSCRIBED

  # Company fields
  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

نقاط نهاية واجهة البرمجة

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

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

حدود المعدل

يطبّق Intercom حدود معدل بناءً على خطتك:

حدود إضافية:

• العمليات المجمّعة: 15 جهة اتصال لكل طلب جماعي
• إرسال الأحداث: 500 حدث/ثانية لكل مساحة عمل
• تسليم Webhook: إعادة محاولة تلقائية لمدة 24 ساعة
• تصدير البيانات: تصدير متزامن واحد

استكشاف الأخطاء وإصلاحها

المشاكل الشائعة

وضع التصحيح

تفعيل التسجيل المفصل:

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

اختبار الاتصال

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

أفضل الممارسات

1. ثبّت إصدار API - حدّد دائمًا Intercom-Version لتجنب التغييرات الجذرية
2. استخدم Search API بكفاءة - استخدم عوامل التصفية والتقسيم لتقليل نقل البيانات
3. زامن المستخدمين والعملاء المحتملين معًا - التقط القمع الكامل في Brevo
4. عيّن وسوم المحادثات - استخدم وسوم المحادثات لشرائح التسويق ما بعد الدعم
5. تتبع الأحداث المخصصة - أرسل أحداث المنتج الرئيسية إلى Intercom للاستهداف السلوكي
6. تعامل مع دمج جهات الاتصال - طبّق منطق الدمج لجهات الاتصال المكررة

الأمان

• رمز الوصول - مصادقة Bearer token للتطبيقات الخاصة
• OAuth 2.0 - تفويض مُوكَّل للتطبيقات العامة بسر العميل
• التحقق من Webhook - التحقق من توقيع HMAC SHA-1 عبر X-Hub-Signature
• تشفير TLS - جميع اتصالات API مشفرة عبر HTTPS
• ضوابط الوصول إلى البيانات - وصول دقيق للبيانات لكل إعداد تطبيق

موارد ذات صلة

• وثائق مطوري Intercom
• مرجع Intercom API
• موصل Zendesk
• مهارة مزامنة العملاء
• واجهة جهات اتصال Brevo