ربط Whats360 مع HubSpot CRM برمجياً: دليل عملي لبناء تكامل WhatsApp ثنائي الاتجاه عبر API وWebhooks

إذا كان فريق المبيعات يعتمد على HubSpot لإدارة العملاء والصفقات، بينما تتم المحادثات اليومية عبر WhatsApp، فهناك فجوة واضحة بين النظامين: العميل موجود داخل CRM، لكن التواصل معه يحدث خارج CRM.

الحل الحقيقي ليس مجرد إضافة زر لإرسال رسالة WhatsApp، وإنما بناء تكامل برمجي يجعل البيانات تتحرك بين HubSpot وWhats360 في الاتجاه المناسب.

يمكن أن يبدأ السيناريو من HubSpot: حدث داخل CRM يؤدي إلى إرسال رسالة WhatsApp تلقائياً، أو يبدأ من العميل عندما يرسل رسالة عبر WhatsApp فتصل بياناتها إلى HubSpot لتحديث سجل العميل أو تشغيل إجراء جديد.

هل يمكن ربط Whats360 مع HubSpot؟

نعم، يمكن تصميم التكامل باستخدام API وWebhooks بحيث تتعامل الأنظمة مع بعضها برمجياً.

أبسط صورة للتكامل هي:

HubSpot → Workflow → Whats360 API → WhatsApp

أما في الاتجاه العكسي فيصبح المسار:

WhatsApp → Whats360 Webhook → Middleware → HubSpot API → Contact أو CRM Event

وعند الجمع بين الاتجاهين يمكن تحويل WhatsApp إلى جزء من دورة العميل داخل CRM بدلاً من أن تكون قناة منفصلة عن نظام إدارة المبيعات.

ومن أمثلة السيناريوهات التي يمكن تصميمها:

• إرسال رسالة عند إنشاء عميل جديد.
• إرسال رسالة عند تغيير مرحلة الصفقة.
• إرسال تأكيد حجز أو موعد.
• إرسال تحديث لحالة الطلب.
• استقبال رسالة عميل وإنشاء Contact عند الحاجة.
• تسجيل تفاعل WhatsApp داخل سجل العميل.
• تشغيل Workflow بناءً على حدث قادم من WhatsApp.

اختر اتجاه البيانات قبل كتابة الكود

أحد أهم القرارات في أي Integration هو تحديد اتجاه البيانات قبل البدء في البرمجة.

عندما يكون HubSpot هو مصدر الحدث، يصبح التدفق كالتالي:

HubSpot → Workflow → Custom Code أو HTTP Request → Whats360 API → WhatsApp

مثلاً، عندما تنتقل صفقة من مرحلة إلى أخرى، يمكن أن يعمل Workflow ويجهز بيانات العميل ثم يستدعي API في Whats360 لإرسال رسالة.

أما إذا كان WhatsApp هو مصدر الحدث، فيكون التدفق:

WhatsApp → Whats360 → Webhook → Middleware → HubSpot API

وهذا السيناريو مناسب عندما تريد أن تصل الرسائل الواردة إلى CRM أو عندما تريد إنشاء أو تحديث العميل تلقائياً.

التكامل ثنائي الاتجاه بين HubSpot وWhats360

في المشاريع التي تحتاج إلى ربط حقيقي بين CRM وWhatsApp، يمكن بناء Architecture ثنائية الاتجاه:

HubSpot
   ↓
Workflow
   ↓
Integration Layer
   ↓
Whats360 API
   ↓
WhatsApp
   ↓
Customer Reply
   ↓
Whats360 Webhook
   ↓
Integration Layer
   ↓
HubSpot API
   ↓
Contact / CRM Event

ميزة هذا التصميم أن النظام لا يتعامل مع WhatsApp كأداة إرسال فقط، وإنما كقناة اتصال مرتبطة بدورة العميل داخل CRM.

ما البيانات التي تحتاج إليها من Whats360؟

قبل تنفيذ التكامل، تحتاج إلى الوصول إلى بيانات API من بوابة المطورين في Whats360.

من أهم البيانات التي يجب التحقق منها:

• Access Token.
• Instance ID.
• API URL أو Endpoint.
• مرجع API.
• حالة الجهاز أو Instance.
• إعدادات Webhook عند الحاجة إلى استقبال الأحداث.

يجب التعامل مع هذه البيانات باعتبارها بيانات حساسة، وخصوصاً Access Token. لا تضع Token داخل Frontend أو JavaScript ظاهر للمستخدمين.

ما الذي تحتاج إليه من HubSpot؟

يعتمد ما تحتاج إليه من HubSpot على نوع التكامل الذي تريد بناءه.

في الاتجاه من HubSpot إلى Whats360، تحتاج إلى Workflow قادر على تشغيل الحدث المطلوب، بالإضافة إلى Custom Code أو طريقة مناسبة لإرسال الطلب إلى API.

وعند استخدام HubSpot API من Middleware أو Custom Code، تحتاج إلى طريقة Authentication مناسبة، مثل Private App Token في السيناريوهات التي تعتمد على Private App.

كما يجب تحديد الصلاحيات المطلوبة حسب العمليات التي سيقوم بها التكامل، مثل قراءة Contacts أو إنشاءها أو تحديثها أو التعامل مع Notes أو Objects أخرى.

القاعدة الأفضل هي منح التكامل أقل صلاحيات ممكنة تحقق الوظيفة المطلوبة، بدلاً من إعطائه صلاحيات واسعة لا يحتاج إليها.

إرسال WhatsApp من HubSpot إلى Whats360

لنفترض أن لديك Workflow في HubSpot يعمل عندما تنتقل صفقة إلى مرحلة معينة.

يمكن أن يكون السيناريو:

Deal Stage Changed
        ↓
HubSpot Workflow
        ↓
Read Contact Data
        ↓
Prepare WhatsApp Message
        ↓
Whats360 API
        ↓
WhatsApp

في هذه العملية توجد مجموعة من المهام الأساسية:

• استخراج بيانات العميل من Workflow.
• قراءة رقم الهاتف.
• تنظيف الرقم وتحويله إلى الصيغة المطلوبة.
• إنشاء الرسالة.
• استدعاء Endpoint الصحيح في Whats360.
• معالجة Response.
• التعامل مع الأخطاء.

استخدام Custom Code داخل HubSpot Workflow

عندما تكون العملية بسيطة يمكن استخدام Workflow مع طلب API مناسب، لكن عندما تحتاج إلى Logic إضافي يصبح Custom Code أكثر مرونة.

يمكن أن يقرأ الكود بيانات العميل، ويتحقق من وجود رقم الهاتف، ويجهز الرسالة، ثم يرسل Request إلى Endpoint الخاص بـWhats360.

const axios = require("axios");

exports.main = async (event, callback) => {

  const phone = event.inputFields["phone"];
  const firstName =
    event.inputFields["firstname"] || "عميلنا العزيز";

  if (!phone) {
    throw new Error("Phone number is missing");
  }

  const message =
    `مرحباً ${firstName}، تم تحديث طلبك بنجاح.`;

  const token = process.env.WHATS360_TOKEN;

  const url = "YOUR_CURRENT_WHATS360_ENDPOINT";

  const payload = {
    token: token,
    instance_id: process.env.WHATS360_INSTANCE_ID,
    number: phone,
    message: message
  };

  try {

    const response = await axios.post(
      url,
      payload,
      {
        headers: {
          "Content-Type": "application/json"
        }
      }
    );

    callback({
      outputFields: {
        status: "success",
        response: JSON.stringify(response.data)
      }
    });

  } catch (error) {

    callback({
      outputFields: {
        status: "failed",
        error: error.response?.data
          ? JSON.stringify(error.response.data)
          : error.message
      }
    });
  }
};

هذا الكود يمثل Architecture توضيحية، وليس Endpoint ثابتاً لكل إصدارات Whats360. يجب استبدال URL وMethod وParameters وفق مرجع API الحالي المستخدم في حسابك.

لا تضع Access Token داخل الكود

من الأخطاء الشائعة وضع الـToken مباشرة داخل Source Code.

بدلاً من ذلك، استخدم Secret أو Environment Variable:

const token = process.env.WHATS360_TOKEN;

والفكرة نفسها تنطبق على HubSpot Access Token.

في Middleware مستقل، يمكنك استخدام Environment Variables أو Secret Manager حسب بيئة الاستضافة.

بهذه الطريقة تستطيع تغيير المفاتيح دون تعديل الكود نفسه، كما تقلل احتمالية تسريب بيانات المصادقة عند مشاركة المشروع أو رفعه إلى مستودع Git.

تنسيق رقم الهاتف قبل الإرسال

رقم الهاتف من أكثر التفاصيل التي يمكن أن تسبب فشل التكامل رغم أن API نفسه يعمل بشكل صحيح.

قد يكون الرقم مخزناً في CRM بهذا الشكل:

+20 123 456 7890

بينما قد يحتاج Endpoint معين إلى رقم دولي بدون المسافات أو علامة +:

201234567890

يمكن تنظيف الرقم مبدئياً:

const cleanPhone = phone.replace(/\D/g, '');

وفي بعض سيناريوهات WhatsApp قد تحتاج إلى JID مثل:

201234567890@s.whatsapp.net

لكن لا تفترض أن كل Endpoint يحتاج إلى JID. يجب استخدام صيغة الرقم التي يحددها Endpoint المستخدم في مرجع API.

استقبال رسائل WhatsApp داخل HubSpot

الاتجاه العكسي يبدأ عندما يرسل العميل رسالة إلى رقم WhatsApp المرتبط بـWhats360.

بدلاً من ترك الرسالة داخل WhatsApp فقط، يمكن تصميم Webhook يرسل الحدث إلى خادمك.

WhatsApp
   ↓
Whats360
   ↓
Webhook
   ↓
https://api.example.com/webhooks/whats360
   ↓
Middleware
   ↓
HubSpot API

وهنا تبدأ عملية معالجة الرسالة.

لماذا قد تحتاج إلى Middleware؟

إذا كان المطلوب مجرد تمرير بيانات بسيطة من نظام إلى آخر، فقد يكفي الاتصال المباشر.

لكن عندما يصبح لديك منطق مثل:

• تنظيف رقم الهاتف.
• البحث عن Contact.
• إنشاء Contact إذا لم يكن موجوداً.
• تحديث خصائص العميل.
• تسجيل الرسالة.
• منع التكرار.
• تطبيق قواعد Business Logic.
• إدارة الأخطاء.
• إعادة المحاولة.
• تسجيل Logs.

فإن وجود Middleware يصبح أكثر فائدة.

يمكن أن يكون Middleware عبارة عن Node.js وExpress أو Serverless Function أو طبقة Integration مخصصة حسب حجم المشروع.

بناء Webhook باستخدام Node.js وExpress

يمكن أن تبدأ نقطة استقبال Webhook بشكل بسيط:

const express = require("express");

const app = express();

app.use(express.json());

app.post("/webhooks/whats360", async (req, res) => {

  try {

    const {
      phone,
      message,
      sender_name,
      timestamp
    } = req.body;

    if (!phone || !message) {
      return res.status(400).json({
        status: "ignored",
        reason: "Missing phone or message"
      });
    }

    console.log({
      phone,
      message,
      sender_name,
      timestamp
    });

    return res.status(200).json({
      status: "success"
    });

  } catch (error) {

    console.error(error);

    return res.status(500).json({
      status: "error"
    });
  }
});

app.listen(3000);

هذا الجزء هو نقطة الدخول فقط. أما منطق التكامل الحقيقي فيأتي بعد استقبال البيانات.

البحث عن Contact داخل HubSpot

عندما تصل رسالة WhatsApp، لا تقم بإنشاء Contact جديد مباشرة.

المنطق الأفضل هو:

Incoming Phone
      ↓
Normalize
      ↓
Search HubSpot
      ↓
Contact Found?
    ↙       ↘
  Yes        No
   ↓          ↓
Update      Create

البحث قبل الإنشاء مهم جداً لأن نفس العميل قد يرسل أكثر من رسالة، وقد تكون بيانات الهاتف مكتوبة بصيغ مختلفة.

يمكن استخدام HubSpot CRM Search API للبحث عن Contact باستخدام خاصية الهاتف، ثم استخدام Contact الموجود أو إنشاء Contact جديد عند عدم العثور عليه.

const searchResponse = await axios.post(
  "https://api.hubapi.com/crm/v3/objects/contacts/search",
  {
    filterGroups: [
      {
        filters: [
          {
            propertyName: "phone",
            operator: "EQ",
            value: formattedPhone
          }
        ]
      }
    ]
  },
  {
    headers: {
      Authorization: `Bearer ${HUBSPOT_ACCESS_TOKEN}`,
      "Content-Type": "application/json"
    }
  }
);

إذا أعاد البحث نتيجة، استخدم Contact ID الموجود. وإذا لم توجد نتيجة، يمكنك إنشاء Contact وفق البيانات المتاحة والخصائص المطلوبة.

منع إنشاء Contacts مكررة

تكرار العملاء مشكلة خطيرة في أي CRM لأن البيانات المكررة تؤثر على المتابعة والتقارير والأتمتة.

تخيل أن نفس الرقم وصل بثلاث صيغ:

+201234567890
201234567890
00201234567890

إذا تعامل النظام مع كل قيمة على أنها عميل مختلف، فقد ينشئ ثلاث سجلات للشخص نفسه.

لذلك يجب بناء قاعدة:

Normalize → Search → Match → Create أو Update

وهذه القاعدة يجب تنفيذها قبل إنشاء Contact جديد.

تسجيل رسالة WhatsApp داخل CRM

بعد العثور على Contact، يمكن تسجيل التفاعل داخل HubSpot باستخدام نوع السجل المناسب للسيناريو.

إذا كان المطلوب الاحتفاظ بنص الرسالة داخل سجل العميل، يمكن استخدام Note أو آلية CRM مناسبة ثم ربطها بالـContact.

يصبح المسار:

WhatsApp Message
      ↓
Whats360 Webhook
      ↓
Normalize Phone
      ↓
Search Contact
      ↓
Contact ID
      ↓
Create CRM Record
      ↓
Associate With Contact

بهذا لا تكون الرسالة مجرد Payload عابر، وإنما تصبح جزءاً من سجل العميل.

تصميم التكامل ثنائي الاتجاه

عند جمع المسارين، يصبح النظام أكثر قوة:

                    ┌─────────────────┐
                    │     HubSpot     │
                    │ CRM + Workflows │
                    └────────┬────────┘
                             │
                          Trigger
                             │
                             ▼
                    ┌─────────────────┐
                    │ Integration     │
                    │ Layer           │
                    └────────┬────────┘
                             │
                          API Call
                             │
                             ▼
                    ┌─────────────────┐
                    │    Whats360     │
                    └────────┬────────┘
                             │
                         WhatsApp
                             │
                         Customer
                             │
                           Reply
                             │
                             ▼
                    ┌─────────────────┐
                    │ Whats360        │
                    │ Webhook         │
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │ Middleware      │
                    │ Normalize       │
                    │ Search          │
                    │ Create / Update │
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │     HubSpot     │
                    └─────────────────┘

هذا التصميم يسمح بأن يصبح WhatsApp جزءاً من عملية المبيعات وليس مجرد تطبيق يستخدمه الموظف بشكل منفصل.

Authentication وإدارة Secrets

في التكامل الكامل ستتعامل عادةً مع بيانات مصادقة تخص النظامين.

من جهة Whats360 لديك Token، ومن جهة HubSpot لديك Access Token أو آلية مصادقة مناسبة.

لا تضع الأسرار في:

• Frontend.
• JavaScript عام.
• Git Repository عام.
• رسائل البريد.
• ملفات إعدادات يتم مشاركتها مع العملاء.

بدلاً من ذلك استخدم:

Environment Variables
        ↓
Integration Application
        ↓
API Requests

ويجب أيضاً فصل مفاتيح بيئة الاختبار عن مفاتيح الإنتاج عندما يكون ذلك ممكناً.

اختبار التكامل قبل تشغيله على العملاء

اختبار API مرة واحدة لا يعني أن التكامل أصبح جاهزاً للإنتاج.

اختبر مسارات النجاح والفشل معاً.

اختبار API

تأكد من أن الطلب يصل إلى Endpoint الصحيح وأن Response يمكن قراءته بشكل صحيح.

اختبار رقم صحيح

استخدم رقماً تجريبياً وتأكد من وصول الرسالة فعلياً.

اختبار رقم غير صحيح

راقب Response وتأكد أن النظام لا يعتبر العملية ناجحة إذا فشل الإرسال.

اختبار Contact موجود

يجب أن يعثر النظام على العميل الموجود بدلاً من إنشاء سجل جديد.

اختبار Contact غير موجود

يجب أن يعمل منطق إنشاء Contact حسب قواعد المشروع.

اختبار Webhook

أرسل رسالة إلى WhatsApp وتأكد من وصول الحدث إلى Middleware ومعالجته بشكل صحيح.

اختبار الرسائل العربية

تأكد من أن الحروف العربية والمسافات والرموز تصل بشكل صحيح ولا تتحول إلى نص مشوه.

اختبار فشل API

افصل الخدمة أو استخدم حالة فشل مناسبة وتأكد من أن النظام يسجل الخطأ ولا يعتبر العملية ناجحة.

اختبار التكرار

اختبر وصول نفس Webhook أكثر من مرة وتأكد من عدم إنشاء Contact أو تسجيل الرسالة مرتين بدون داعٍ.

أخطاء Endpoint وHTTP Method

من أكثر الأخطاء شيوعاً الاعتماد على مثال برمجي قديم ثم افتراض أنه يمثل كل API.

قد تستخدم عملية معينة GET، بينما تستخدم عملية أخرى POST. وقد تختلف أسماء Parameters بين Endpoint وآخر.

لذلك لا تعتمد على اسم العملية وحده، ولا على Snippet من مصدر قديم.

افتح مرجع API الخاص بالعملية المطلوبة وتحقق من:

• Endpoint.
• HTTP Method.
• Authentication.
• Headers.
• Parameters.
• Request Body.
• Response.
• Error Codes.

وهذه النقطة مهمة بشكل خاص عند تحويل مثال تجريبي إلى كود Production.

مشكلة Instance وحالة الجهاز

حتى إذا كان الكود صحيحاً والـToken صحيحاً، يجب التأكد من أن Instance المستخدم في العملية متاح ومتصل وفق متطلبات الخدمة.

إذا كان التكامل يعتمد على Instance معين، فراجع:

• Instance ID.
• حالة الاتصال.
• الرقم المرتبط.
• البيانات المستخدمة في Request.

لا تنتقل مباشرة إلى تعديل الكود إذا كانت المشكلة الأساسية مرتبطة بحالة Instance.

ماذا يعني الخطأ 463؟

إذا ظهر Error Code مثل 463 أثناء إرسال رسالة، فلا يجب بناء تشخيص نهائي اعتماداً على الرقم وحده.

ابدأ بمراجعة:

• Endpoint المستخدم.
• HTTP Method.
• Instance.
• الرقم المستهدف.
• حالة المحادثة.
• تفاصيل Response.
• مرجع API الحالي.

إذا كان توثيق إصدار Whats360 المستخدم يربط الخطأ بحالة معينة في فتح المحادثة أو تهيئة الاتصال، فطبّق الإجراء المحدد في ذلك التوثيق.

المهم ألا يتم تحويل تفسير Error Code من إصدار أو سيناريو معين إلى قاعدة عامة لكل الحالات.

الرسائل العربية وURL Encoding

عند التعامل مع الرسائل العربية، يجب الانتباه إلى طريقة إرسال البيانات.

إذا كان Endpoint يعتمد على Query Parameters، يجب التعامل مع URL Encoding بشكل صحيح.

أما عند استخدام JSON، فيجب إرسال البيانات كـJSON مع Content-Type مناسب:

{
  "message": "مرحباً محمد، تم استلام طلبك بنجاح."
}

ولا تحتاج عادةً إلى بناء Encoding يدوياً عندما يقوم HTTP Client بتحويل JSON إلى Request بشكل صحيح.

أما عند وضع الرسالة داخل URL، فيجب التأكد من ترميز الأحرف والمسافات والرموز الخاصة قبل إرسال الطلب.

تجهيز Integration للاستخدام في الإنتاج

هناك فرق كبير بين كود ينجح في اختبار بسيط وبين Integration يمكن الاعتماد عليه داخل شركة.

Logging

سجل المعلومات التي تساعدك على معرفة ماذا حدث:

• Request ID.
• Event ID.
• وقت التنفيذ.
• حالة العملية.
• Error Code.
• Response Status.

لكن لا تسجل Access Tokens أو Secrets داخل Logs.

Error Handling

يجب التعامل مع حالات مثل:

• Invalid Request.
• Authentication Failure.
• Timeout.
• 4xx Response.
• 5xx Response.
• Invalid Webhook Payload.

Retry

ليس كل خطأ يحتاج إلى Retry.

خطأ Authentication مثلاً لا يتم حله بإعادة إرسال الطلب عشر مرات، بينما بعض أخطاء الشبكة المؤقتة قد تستفيد من إعادة المحاولة وفق سياسة مناسبة.

Idempotency

إذا وصل نفس Webhook مرتين، يجب ألا ينتج عن ذلك بالضرورة إنشاء Contact مرتين أو تسجيل نفس الرسالة مرتين.

لهذا يجب أن يكون لديك Event ID أو آلية مناسبة لاكتشاف التكرار عندما تتوفر البيانات اللازمة لذلك.

Monitoring

راقب المسار الكامل:

Webhook Received
       ↓
Processed
       ↓
HubSpot Success
       ↓
Whats360 Success

وأي مرحلة تفشل يجب أن تكون قابلة للتشخيص.

متى تستخدم Direct Integration ومتى تحتاج Middleware؟

الاحتياج	المسار المناسب	درجة التعقيد
إرسال رسالة بسيطة	Workflow + API	منخفضة
رسالة ديناميكية مع شروط	Custom Code	متوسطة
استقبال Webhooks	Webhook Endpoint	متوسطة
بحث وإنشاء وتحديث Contacts	Middleware	متوسطة إلى مرتفعة
عدة أنظمة وقواعد معقدة	Integration Layer	مرتفعة

لا توجد Architecture واحدة مناسبة لكل مشروع. الأفضل هو استخدام أقل مستوى من التعقيد يحقق المتطلبات الحالية، مع ترك مساحة للتوسع عندما ينمو المشروع.

أمثلة عملية لاستخدام التكامل

تغيير مرحلة الصفقة

Deal Stage Changed
       ↓
HubSpot Workflow
       ↓
Whats360 API
       ↓
WhatsApp Message

يمكن استخدام هذا السيناريو لإرسال إشعار للعميل عند وصول الصفقة إلى مرحلة معينة، وفق قواعد العمل التي يحددها المشروع.

تأكيد حجز أو موعد

Appointment Created
       ↓
HubSpot Workflow
       ↓
Whats360 API
       ↓
WhatsApp Confirmation

هنا يصبح WhatsApp جزءاً من عملية التواصل بعد تسجيل الحدث داخل CRM.

عميل جديد على WhatsApp

Customer Message
       ↓
Whats360
       ↓
Webhook
       ↓
Search Contact
       ↓
Create if Needed
       ↓
HubSpot

هذا السيناريو مناسب عندما تريد تحويل الرسائل الواردة إلى بيانات قابلة للإدارة داخل CRM.

رسالة واردة تحتاج إلى متابعة

Customer Message
       ↓
Whats360
       ↓
Webhook
       ↓
Middleware
       ↓
HubSpot Contact
       ↓
CRM Workflow

بهذا يمكن أن تتحول رسالة العميل إلى Trigger داخل دورة المبيعات بدلاً من أن تظل منفصلة عن النظام.

هل تحتاج إلى برمجة كاملة؟

ليس بالضرورة.

إذا كان المطلوب بسيطاً، يمكن أن يكفي Workflow يطلق API Request.

إذا كان المطلوب يحتوي على منطق مخصص، يمكن استخدام Custom Code.

إذا كان المطلوب استقبال Webhooks وإجراء عمليات متعددة، يكون Middleware أكثر ملاءمة.

أما إذا كان المشروع يحتوي على عدة أنظمة وقواعد معقدة، فقد تحتاج إلى Integration Layer كاملة تتولى إدارة البيانات بين الأنظمة.

الفكرة الأساسية هي عدم بناء نظام أكبر من احتياج المشروع، وفي الوقت نفسه عدم بناء تكامل بسيط جداً يصعب توسيعه بعد زيادة حجم العمليات.

كيف يمكن استخدام Whats360 كطبقة WhatsApp Integration؟

بعد تحديد المشكلة وبناء Architecture، يأتي اختيار طبقة WhatsApp التي ستنفذ الاتصال البرمجي.

إذا كان المشروع يحتاج إلى API وWebhooks وربط WhatsApp بأنظمة CRM أو المتاجر أو البرمجيات، يمكن دراسة Whats360 كطبقة WhatsApp Integration ضمن هذه البنية.

الفكرة هنا ليست أن يصبح المنتج محور المقال، وإنما أن يكون الحل متوافقاً مع المشكلة التي يحاول المطور حلها: توفير قناة WhatsApp قابلة للربط برمجياً مع النظام الموجود بالفعل.

والخطوة العملية للمطور هي البدء من Developer Portal، تحديد الـEndpoint المطلوب، اختبار Request بسيط، ثم بناء التكامل تدريجياً بدلاً من نقل نظام كامل إلى الإنتاج دفعة واحدة.

استفسر عن ربط Whats360 مع HubSpot

مقالات ذات صلة

دليل WhatsApp API وWebhooks

ربط WhatsApp مع أنظمة CRM

أتمتة WhatsApp باستخدام API

أتمتة HubSpot CRM

أسئلة شائعة حول ربط Whats360 مع HubSpot

هل يمكن ربط Whats360 مع HubSpot؟

نعم، يمكن تصميم التكامل باستخدام API وWebhooks بحيث يرسل HubSpot أحداثاً إلى Whats360 لإرسال رسائل WhatsApp، ويمكن في الاتجاه العكسي استقبال أحداث WhatsApp ومعالجتها ثم إرسالها إلى HubSpot.

هل يمكن إرسال WhatsApp تلقائياً من HubSpot Workflow؟

يمكن تصميم Workflow يطلق عملية إرسال إلى Whats360 عبر API. وتختلف طريقة التنفيذ حسب أدوات HubSpot المتاحة في الحساب وEndpoint المستخدم في Whats360.

هل يمكن استقبال رسائل WhatsApp داخل HubSpot؟

يمكن بناء هذا السيناريو عبر Webhook يستقبل الرسالة من Whats360، ثم Middleware يعالج البيانات ويستخدم HubSpot API للبحث عن Contact أو إنشائه وتسجيل التفاعل وفق التصميم المطلوب.

هل أحتاج إلى Middleware؟

ليس دائماً. إذا كان المطلوب إرسالاً بسيطاً فقد يكفي الربط المباشر. أما إذا احتجت إلى استقبال Webhooks، وتنظيف البيانات، والبحث عن العملاء، ومنع التكرار، وتطبيق Business Logic، فوجود Middleware يصبح أكثر فائدة.

ما الفرق بين API وWebhook في التكامل؟

API يستخدم عادةً عندما تريد أن يطلب نظام من نظام آخر تنفيذ عملية أو إرجاع بيانات. أما Webhook فيستخدم لإرسال إشعار أو حدث إلى نظام آخر عندما يحدث شيء معين.

أين أحصل على Whats360 Access Token؟

يتم الحصول على بيانات التكامل من بوابة المطورين في Whats360 وفق الإعدادات المتاحة للحساب ومرجع API الحالي.

ما هو Instance ID؟

هو معرف الـInstance أو الجهاز الذي يعتمد عليه التكامل في السيناريو المستخدم. يجب استخدام القيمة الصحيحة كما تظهر في إعدادات الخدمة ومرجع API.

كيف يتم تنسيق رقم الهاتف؟

يجب استخدام صيغة الرقم التي يطلبها Endpoint المستخدم. بعض العمليات قد تعتمد على رقم دولي بدون علامة +، بينما قد تتطلب عمليات أخرى معرفاً مختلفاً مثل JID.

لماذا قد يفشل الإرسال رغم صحة Token؟

هناك أسباب محتملة متعددة، منها Endpoint غير صحيح، Method غير مناسب، Instance غير متصل، رقم غير صحيح، Parameters غير مطابقة، أو مشكلة في حالة المحادثة. لذلك يجب قراءة Response والتحقق من التوثيق الحالي قبل تغيير الكود.

كيف أمنع إنشاء Contacts مكررة؟

طبّق عملية Normalize لرقم الهاتف، ثم Search داخل HubSpot، ثم استخدم Contact الموجود أو أنشئ سجلاً جديداً فقط عند عدم وجود نتيجة مناسبة.

هل يمكن تنفيذ التكامل باستخدام Node.js؟

نعم، Node.js مناسب لبناء Middleware يستقبل Webhooks ويستدعي HubSpot API وWhats360 API، مع إمكانية إضافة Logging وRetry وValidation وقواعد Business Logic.

هل يمكن جعل التكامل ثنائي الاتجاه؟

نعم. يمكن أن يرسل HubSpot أحداثاً إلى Whats360، وفي الوقت نفسه يرسل Whats360 Webhooks إلى Middleware لمعالجة الرسائل والأحداث الواردة ثم تحديث HubSpot.

أين يجب تخزين Tokens؟

يجب تخزينها في Secrets أو Environment Variables أو نظام Secret Management مناسب، وعدم تضمينها داخل Frontend أو Source Code مكشوف.

كيف أختبر التكامل قبل إطلاقه؟

ابدأ باختبار API، ثم رقم تجريبي، ثم Workflow، ثم Webhook، ثم Contact موجود وغير موجود، ثم حالات الخطأ والرسائل العربية والتكرار. لا تعتمد على اختبار مسار نجاح واحد فقط.

ماذا أفعل إذا تغير Endpoint أو API Method؟

ارجع إلى مرجع API الحالي في بوابة مطوري Whats360، ثم حدّث الـEndpoint والـMethod والـParameters وفق التوثيق الجديد بدلاً من الاعتماد على Snippet قديم.

الخلاصة

ربط Whats360 مع HubSpot يمكن أن يبدأ من سيناريو بسيط جداً: Workflow داخل HubSpot يرسل طلباً إلى Whats360 ثم تصل الرسالة إلى العميل عبر WhatsApp.

لكن عندما يصبح المطلوب Integration حقيقية، فإن الصورة تتغير إلى:

HubSpot
   ↕
Middleware
   ↕
Whats360
   ↕
WhatsApp

وهنا يجب التفكير في البيانات قبل الكود.

ما الحدث الذي سيبدأ العملية؟

إلى أين ستذهب البيانات؟

كيف ستتم المصادقة؟

كيف سيتم تحديد Contact الصحيح؟

ماذا سيحدث إذا لم يكن العميل موجوداً؟

ماذا سيحدث إذا فشل API؟

كيف ستمنع تكرار Webhook؟

وكيف ستراقب التكامل بعد تشغيله؟

هذه الأسئلة هي التي تفرق بين API Call يعمل مرة واحدة وبين Integration يمكن الاعتماد عليه داخل نظام مبيعات حقيقي.

إذا كان احتياجك مجرد إرسال رسائل من HubSpot، ابدأ بالمسار المباشر.

أما إذا كنت تريد مزامنة العملاء والرسائل والأحداث في الاتجاهين، فالأفضل تصميم Integration Layer واضحة من البداية.

والقاعدة الأهم قبل كتابة أي كود خاص بـWhats360: لا تعتمد على Endpoint أو Method من مثال قديم. افتح مرجع API الحالي، حدد العملية المطلوبة، اختبر Request بسيطاً، ثم ابنِ التكامل تدريجياً حتى يصبح جاهزاً للإنتاج.

ابدأ تكامل Whats360 مع HubSpot