تطوير n8n Community Node لمنصة Whats360: التكامل الكامل مع WhatsApp وSMS وAI Agents

أصبح n8n من أهم منصات أتمتة سير العمل وربط التطبيقات والـ APIs، خصوصًا مع انتشار وكلاء الذكاء الاصطناعي
والـ AI Agents التي تحتاج إلى أدوات اتصال مباشرة بخدمات مثل WhatsApp وSMS والبريد الإلكتروني.
ومن هنا تأتي فكرة تطوير n8n-nodes-whats360 كـ Community Node مخصصة لمنصة
Whats360، بحيث يستطيع المطور أو صاحب النشاط بناء Automation متكاملة دون كتابة طلبات HTTP يدويًا في كل Workflow.

الهدف ليس مجرد توفير Node لإرسال رسالة واتساب، وإنما بناء طبقة تكامل تجعل Whats360 جزءًا طبيعيًا من منظومة
n8n + APIs + AI Agents + CRM + التجارة الإلكترونية.

ما هو n8n-nodes-whats360؟

n8n-nodes-whats360 هي حزمة Community Node مصممة لربط n8n بخدمات Whats360.
وتسمح للمستخدم بتنفيذ عمليات مثل إرسال رسائل WhatsApp، إرسال الصور والفيديوهات والمستندات، إدارة أجهزة WhatsApp،
تشغيل الحملات، إرسال SMS وتنفيذ USSD، إرسال البريد الإلكتروني، بالإضافة إلى استقبال الأحداث الواردة عبر Webhooks.

وبدلًا من أن يقوم المطور بإنشاء HTTP Request Node لكل API Endpoint، وإضافة Token وInstance ID وJID يدويًا،
تقدم الحزمة واجهة موحدة داخل n8n.

لماذا تحتاج Whats360 إلى Community Node خاصة بـ n8n؟

تكمن المشكلة في أن التكامل التقليدي عبر HTTP Request يتطلب من المستخدم معرفة تفاصيل الـ API، مثل:

Endpoint الصحيح.
HTTP Method.
Parameters المطلوبة.
طريقة المصادقة.
صيغة WhatsApp JID.
معالجة الأخطاء.
تنسيق بيانات الـ Webhook.

أما عند استخدام Node مخصصة، فيمكن للمستخدم اختيار:
Message → Send Text
ثم تحديد الجهاز وكتابة رقم العميل والرسالة، بينما تتولى الـ Node باقي التفاصيل.

القيمة المضافة للحزمة

1. Zero-Code Integration

يمكن للمستخدم تنفيذ عمليات Whats360 من خلال واجهة n8n بدلًا من كتابة HTTP Requests يدويًا.
كما يمكن تحميل الأجهزة المتاحة ديناميكيًا وعرضها في قائمة Dropdown.

2. AI-Ready

أحد أهم أهداف المشروع هو جعل عمليات Whats360 قابلة للاستخدام داخل Workflows التي تعتمد على
LangChain وAI Agents.
وهذا يسمح ببناء وكيل ذكاء اصطناعي يستقبل رسالة من WhatsApp، يفهمها، ثم يستخدم Whats360 كأداة لإرسال الرد.

3. Smart JID Formatting

لا ينبغي إجبار المستخدم على معرفة صيغة WhatsApp JID.
لذلك تقوم الدالة الخاصة بالتنسيق بتحويل صيغ مثل:

+201234567890
201234567890
00201234567890
201234567890@s.whatsapp.net

إلى الصيغة المناسبة:

201234567890@s.whatsapp.net

4. Actionable Error Diagnostics

بدلًا من إظهار رقم خطأ فقط، تستطيع الـ Node تحويل الأخطاء المعروفة إلى رسائل مفهومة تساعد المطور على معرفة المشكلة والخطوة التالية.

على سبيل المثال، عند ظهور الخطأ 463 يمكن إظهار رسالة توضح أن جلسة المحادثة أو التشفير تحتاج إلى التهيئة بدل ترك المستخدم أمام HTTP Status غير مفهوم.

العمليات التي تدعمها Whats360 Node

Resource	Operation	Method	Endpoint
Message	Send Text	GET	/api/v1/send-text
Message	Send Image	GET	/api/v1/send-image
Message	Send Video	GET	/api/v1/send-video
Message	Send Audio	GET	/api/v1/send-audio
Message	Send Document	GET	/api/v1/send-doc
Instance	List / Create / Connect / Disconnect / Status / QR / Delete	GET	/api/v1/instances/*
Campaign	Create / Start / Pause / Resume / Stop / Delete	POST	/api/v1/campaigns/*
Campaign	List / Status	GET	/api/v1/campaigns*
VCash	SMS	POST	/api/v1/vcash/sms/send
VCash	USSD	POST	/api/v1/vcash/ussd/execute
VCash	Devices / Balance / Transactions	GET	/api/v1/vcash/*
Email	Send Email	POST	/api/v1/email/send
Trigger	Incoming Webhook	POST	Custom Hook URL

العمليات المؤجلة إلى الإصدارات القادمة

هناك عمليات لا ينبغي إضافتها إلى الحزمة إلا بعد التأكد من وجود Endpoints رسمية لها في API، ومنها:

إنشاء وتحديث جهات الاتصال.
تصدير تاريخ المحادثات.
إرسال Interactive Buttons.
إرسال Interactive Lists.

هذه النقطة مهمة للحفاظ على استقرار الحزمة وعدم بناء Features على Endpoints غير موثقة أو غير مستقرة.

تصميم Credentials داخل n8n

تعتمد الحزمة على Credential موحدة باسم:

whats360Api

وتحتوي على:

Base URL: القيمة الافتراضية https://whats360.live
API Token: Token محمي بكلمة مرور.

ويسمح وجود Base URL قابل للتعديل باستخدام نفس الـ Node مع بيئات خاصة أو Self-Hosted إذا كانت المنصة تدعم ذلك.

كود Credential

import {
    ICredentialType,
    INodeProperties,
} from 'n8n-workflow';

export class Whats360Api implements ICredentialType {
    name = 'whats360Api';
    displayName = 'Whats360 API';
    documentationUrl = 'https://whats360.live';

    properties: INodeProperties[] = [
        {
            displayName: 'Base URL',
            name: 'baseUrl',
            type: 'string',
            default: 'https://whats360.live',
            required: true,
            description: 'The base URL of the Whats360 API instance',
        },
        {
            displayName: 'API Token',
            name: 'apiToken',
            type: 'string',
            typeOptions: {
                password: true,
            },
            default: '',
            required: true,
            description:
                'Your Whats360 API Token from Developers Portal / Settings',
        },
    ];
}

طبقة الاتصال الموحدة مع Whats360 API

بدل تكرار كود الاتصال والمصادقة داخل كل عملية، تستخدم الحزمة دالة مركزية باسم
whats360ApiRequest.

هذه الطبقة مسؤولة عن:

قراءة Credentials.
تحديد Base URL.
إضافة API Token.
إرسال Authorization Header.
إضافة Query Parameters.
إرسال POST Body عند الحاجة.
التقاط أخطاء API.
تحويل الأخطاء المعروفة إلى رسائل مفهومة.

تنسيق رقم WhatsApp تلقائيًا

export function formatToJid(recipient: string): string {
    if (!recipient) {
        throw new NodeOperationError(
            {} as any,
            'Recipient phone number or JID cannot be empty.',
        );
    }

    let cleaned = recipient.trim();

    if (
        cleaned.includes('@s.whatsapp.net') ||
        cleaned.includes('@g.us')
    ) {
        return cleaned;
    }

    cleaned = cleaned.replace(/[^\d]/g, '');

    if (cleaned.startsWith('00')) {
        cleaned = cleaned.substring(2);
    }

    return `${cleaned}@s.whatsapp.net`;
}

الميزة هنا أن المستخدم يتعامل مع رقم الهاتف بصيغته الطبيعية، بينما تتولى طبقة التكامل إنشاء JID قبل إرسال الطلب إلى Whats360.

معالجة أخطاء API بطريقة قابلة للتنفيذ

من أهم أجزاء الـ Node ألا تكتفي بإرجاع HTTP Status Code، وإنما تقدم تفسيرًا عمليًا للمشكلة.

if (statusCode === 463) {
    customMessage =
        'WhatsApp Error [463]: The recipient has not opened a conversation window yet, or encryption is uninitialized. Solution: Send a direct message from the phone to this number first to initiate the session.';
} else if (statusCode === 401) {
    customMessage =
        'Authentication Error [401]: The API Token provided is invalid or expired. Check your Whats360 credentials.';
} else if (statusCode === 404) {
    customMessage =
        'Not Found [404]: The specified Instance or Device ID was not found on your Whats360 account.';
} else if (statusCode === 403) {
    customMessage =
        'Limit Exceeded [403]: Your account plan limit for messages or instances has been reached.';
}

هذا الأسلوب يجعل الـ Node أكثر ملاءمة للمطورين، وكذلك للـ AI Agents التي تحتاج إلى فهم سبب فشل Tool Call بدل الحصول على رسالة تقنية غامضة.

إرسال رسالة WhatsApp من داخل n8n

بعد إعداد Credentials يستطيع المستخدم اختيار:

Resource: Message (WhatsApp)
Operation: Send Text
اختيار Instance.
إدخال رقم العميل.
إدخال نص الرسالة.

ويتم داخليًا تنفيذ الطلب:

responseData = await whats360ApiRequest.call(
    this,
    'GET',
    '/api/v1/send-text',
    {},
    {
        instance_id: instanceId,
        jid,
        msg,
    },
);

وبذلك يصبح إرسال WhatsApp جزءًا طبيعيًا من أي Workflow داخل n8n.

إرسال الصور والفيديو والصوت والمستندات

لا تقتصر الـ Node على الرسائل النصية، بل توفر واجهة موحدة للوسائط.

الصورة

await whats360ApiRequest.call(
    this,
    'GET',
    '/api/v1/send-image',
    {},
    {
        instance_id: instanceId,
        jid,
        imageurl,
        caption,
    },
);

الفيديو

await whats360ApiRequest.call(
    this,
    'GET',
    '/api/v1/send-video',
    {},
    {
        instance_id: instanceId,
        jid,
        videourl,
        caption,
    },
);

الصوت

await whats360ApiRequest.call(
    this,
    'GET',
    '/api/v1/send-audio',
    {},
    {
        instance_id: instanceId,
        jid,
        audiourl,
    },
);

المستند

await whats360ApiRequest.call(
    this,
    'GET',
    '/api/v1/send-doc',
    {},
    {
        instance_id: instanceId,
        jid,
        docurl,
        caption,
    },
);

Dynamic Dropdown لاختيار أجهزة WhatsApp

من أهم عناصر تجربة الاستخدام أن لا يضطر المستخدم إلى نسخ Instance ID من لوحة التحكم.
لذلك توفر الـ Node وظيفة getInstances لتحميل الأجهزة ديناميكيًا.

async getInstances(
    this: ILoadOptionsFunctions
): Promise<INodePropertyOptions[]> {
    try {
        const response = await whats360ApiRequest.call(
            this,
            'GET',
            '/api/v1/instances'
        );

        const returnData: INodePropertyOptions[] = [];
        const instances =
            response.response ||
            response.data ||
            response.instances ||
            [];

        if (Array.isArray(instances)) {
            for (const inst of instances) {
                returnData.push({
                    name: `${inst.name || inst.id} (${inst.status || 'active'})`,
                    value: inst.id || inst.instance_id,
                });
            }
        }

        return returnData;
    } catch (error) {
        return [];
    }
}

ويتم استدعاؤها من الحقل:

typeOptions: {
    loadOptionsMethod: 'getInstances',
}

وهكذا تظهر الأجهزة داخل n8n بطريقة أقرب إلى تجربة التطبيقات الأصلية بدل إدخال المعرفات يدويًا.

إدارة أجهزة WhatsApp

توفر Resource الخاصة بالـ Instance مجموعة من العمليات الأساسية:

Get All Instances
Create Instance
Get Status
Get QR Code
Connect Instance
Disconnect Instance
Delete Instance

وهذا يسمح ببناء Workflows إدارية، مثل مراقبة حالة الأجهزة أو تنفيذ إجراءات تلقائية عند تغير حالة الاتصال.

أتمتة حملات WhatsApp

تدعم الحزمة أيضًا Campaign Resource، والتي تسمح بإدارة دورة حياة الحملة من داخل Workflow.

وتشمل:

إنشاء الحملة.
إضافة المستلمين.
بدء الحملة.
إيقاف مؤقت.
استئناف.
إيقاف.
الحصول على الحالة.
حذف الحملة.

مثال إنشاء حملة:

const name =
    this.getNodeParameter('campaignName', i) as string;

const message_content =
    this.getNodeParameter('messageContent', i) as string;

responseData = await whats360ApiRequest.call(
    this,
    'POST',
    '/api/v1/campaigns/create',
    {
        name,
        message_content,
    },
    {
        instance_id: instanceId,
    },
);

إضافة المستلمين للحملة

تستقبل العملية بيانات المستلمين بصيغة JSON، وهو ما يجعلها مناسبة جدًا للبيانات القادمة من Google Sheets أو قواعد البيانات أو CRM أو أي Node أخرى داخل n8n.

[
    {
        "phone": "201234567890",
        "name": "Ahmed"
    }
]

ثم يتم تمرير البيانات إلى Endpoint الخاص بالمستلمين:

responseData = await whats360ApiRequest.call(
    this,
    'POST',
    '/api/v1/campaigns/recipients',
    body,
    {
        instance_id: instanceId,
        campaign_id: campaignId,
    },
);

دمج VCash لإرسال SMS وتنفيذ USSD

الميزة المهمة في التصميم أن Whats360 Node لا تتوقف عند WhatsApp، وإنما يمكنها الوصول إلى خدمات VCash المتعلقة بالأجهزة المحمولة.

ومن العمليات المتاحة:

إرسال SMS.
عرض الأجهزة.
تنفيذ USSD.
قراءة الرصيد.
قراءة المعاملات.

مثال إرسال SMS:

responseData = await whats360ApiRequest.call(
    this,
    'POST',
    '/api/v1/vcash/sms/send',
    {
        device_id,
        recipient,
        message,
        sim_slot,
    },
);

إرسال البريد الإلكتروني من نفس Workflow

توفر Email Resource نقطة أخرى مهمة في المنظومة، حيث يمكن تنفيذ إرسال البريد الإلكتروني من خلال:

responseData = await whats360ApiRequest.call(
    this,
    'POST',
    '/api/v1/email/send',
    {
        from,
        to,
        subject,
        body,
    },
);

وبذلك يمكن بناء Workflow متعدد القنوات يبدأ من حدث واحد ثم يرسل WhatsApp وSMS وEmail وفق قواعد العمل.

Whats360 Trigger: استقبال الرسائل والأحداث في n8n

جانب الإرسال وحده لا يكفي لبناء Automation حقيقية.
لذلك تتضمن الحزمة عقدة Trigger باسم:

Whats360 Trigger

وتستقبل أحداث Whats360 عبر Webhook.
ومن الأحداث المقترحة:

Incoming WhatsApp Message.
Outgoing Message.
Message Send Failure.
Subscription Expiry.

كما يمكن حماية الـ Webhook باستخدام Secret Header.

تطبيع بيانات Webhook

حتى لو اختلف اسم الحقل القادم من API، تقوم الـ Trigger بتحويل البيانات إلى بنية موحدة:

const normalized = {
    sender_phone: bodyData.phone || bodyData.from || '',
    sender_name: bodyData.sender_name || bodyData.name || '',
    message:
        bodyData.message ||
        bodyData.msg ||
        bodyData.body ||
        '',
    message_id:
        bodyData.message_id ||
        bodyData.id ||
        '',
    chat_jid: bodyData.chat_jid || '',
    instance_id: bodyData.instance_id || '',
    timestamp:
        bodyData.timestamp ||
        Date.now(),
    media_url:
        bodyData.media_url || null,
    raw: bodyData,
};

هذه الطبقة مهمة جدًا لأنها تجعل بقية الـ Workflow تتعامل مع Schema موحد بدل التعامل مع اختلافات Payload.

بناء AI Agent يرد على العملاء عبر WhatsApp

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

[Whats360 Trigger]
        ↓
[AI Agent / LangChain]
        ↓
[Whats360 - Send Text]
        ↓
[Customer WhatsApp]

عند وصول رسالة:

تلتقط Whats360 Trigger الرسالة.
يتم استخراج رقم العميل ونص الرسالة.
يمرر n8n البيانات إلى AI Agent.
يقوم الوكيل بتحليل الطلب.
يولد الرد المناسب.
تستخدم Whats360 Node لإرسال الرد.

وهنا تتحول Whats360 من مجرد API لإرسال الرسائل إلى قناة اتصال يمكن لوكيل الذكاء الاصطناعي استخدامها كـ Tool.

ربط WooCommerce أو Shopify مع WhatsApp

يمكن استخدام نفس البنية لبناء نظام إشعارات للمتاجر الإلكترونية.

[WooCommerce Trigger]
        ↓
[Set / Code]
        ↓
[Extract Customer Phone]
        ↓
[Whats360]
        ↓
[Send WhatsApp Message]

مثلًا عند إنشاء طلب جديد يمكن إرسال رسالة تحتوي على:

اسم العميل.
رقم الطلب.
قيمة الطلب.
حالة الطلب.
رابط المتابعة.

ويمكن تطبيق الفكرة نفسها على Shopify أو أي متجر لديه Webhook أو API.

تحويل Meta Leads إلى فريق المبيعات

سيناريو آخر عملي هو استقبال Lead جديد ثم تشغيل أكثر من قناة في نفس الوقت:

[Facebook Lead Ads]
        ↓
[Extract Lead Data]
        ↓
[Whats360 → WhatsApp Welcome]
        ↓
[Whats360 VCash → SMS Sales Alert]

بهذه الطريقة يمكن للـ Automation إرسال رسالة ترحيب للعميل، وفي الوقت نفسه تنبيه مندوب المبيعات عبر SMS.

هيكل مشروع n8n-nodes-whats360

n8n-nodes-whats360/
├── package.json
├── tsconfig.json
├── .eslintrc.js
├── .gitignore
├── README.md
├── LICENSE
├── assets/
│   ├── whats360.png
│   └── whats360.svg
├── credentials/
│   └── Whats360Api.credentials.ts
└── nodes/
    ├── Whats360/
    │   ├── Whats360.node.json
    │   ├── Whats360.node.ts
    │   ├── GenericFunctions.ts
    │   └── descriptions/
    │       ├── MessageDescription.ts
    │       ├── InstanceDescription.ts
    │       ├── CampaignDescription.ts
    │       ├── VcashDescription.ts
    │       └── EmailDescription.ts
    └── Whats360Trigger/
        ├── Whats360Trigger.node.json
        └── Whats360Trigger.node.ts

لماذا تقسيم الـ Node إلى ملفات Description؟

بدل وضع جميع الحقول والعمليات داخل ملف واحد ضخم، يتم فصل كل Resource في ملف مستقل.

مثلًا:

MessageDescription.ts: WhatsApp Messages.
InstanceDescription.ts: الأجهزة والـ Instances.
CampaignDescription.ts: الحملات.
VcashDescription.ts: SMS وUSSD.
EmailDescription.ts: البريد الإلكتروني.

هذا التصميم يسهل إضافة Features مستقبلية دون تحويل الملف الرئيسي إلى كتلة يصعب صيانتها.

package.json للحزمة

{
  "name": "n8n-nodes-whats360",
  "version": "1.0.0",
  "description": "n8n community node for Whats360 WhatsApp, SMS, and Campaign Automation",
  "keywords": [
    "n8n-community-node-package",
    "n8n",
    "whats360",
    "whatsapp",
    "sms",
    "vcash",
    "automation",
    "ai-agent"
  ],
  "license": "MIT",
  "homepage": "https://whats360.live",
  "author": {
    "name": "Whats360 Team",
    "email": "support@whats360.live"
  },
  "main": "index.js",
  "scripts": {
    "build": "tsc && gulp build:icons",
    "dev": "tsc --watch",
    "lint": "eslint nodes credentials --ext .ts",
    "lintfix": "eslint nodes credentials --ext .ts --fix",
    "prepublishOnly": "npm run build"
  },
  "files": [
    "dist"
  ],
  "n8n": {
    "n8nNodesApiVersion": 1,
    "credentials": [
      "dist/credentials/Whats360Api.credentials.js"
    ],
    "nodes": [
      "dist/nodes/Whats360/Whats360.node.js",
      "dist/nodes/Whats360Trigger/Whats360Trigger.node.js"
    ]
  }
}

تثبيت وبناء الحزمة محليًا

بعد إنشاء المشروع، تبدأ عملية تثبيت الاعتمادات:

npm install

ثم بناء TypeScript:

npm run build

ويمكن تشغيل وضع التطوير أثناء تعديل الكود:

npm run dev

أما فحص الكود فيتم باستخدام:

npm run lint

اختبار Community Node داخل n8n

يمكن ربط الحزمة محليًا مع نسخة n8n أثناء التطوير باستخدام:

npm link /path/to/n8n-nodes-whats360

وهذه الخطوة مهمة قبل النشر النهائي للتأكد من أن الـ Node تعمل فعليًا داخل بيئة n8n وليس فقط أنها تُترجم بنجاح في TypeScript

بعد التأكد من عمل الحزمة محليًا، يمكن الانتقال إلى خطوة النشر على npm، بحيث تصبح الحزمة متاحة للتثبيت داخل خوادم n8n المختلفة.

النشر على npm Registry

بعد الانتهاء من الاختبارات المحلية والتأكد من عدم وجود أخطاء في البناء أو التشغيل، يتم تسجيل الدخول إلى npm ثم نشر الحزمة باسمها الرسمي:

npm login
npm publish --access public

بعد نجاح عملية النشر، تصبح الحزمة متاحة للمستخدمين لتثبيتها مباشرة من خلال Community Nodes في n8n.

ويتم تثبيت الحزمة داخل خادم n8n من خلال:

Settings -> Community Nodes -> Install a community node

ثم يتم إدخال اسم الحزمة:

n8n-nodes-whats360

وبذلك يمكن للمستخدم إضافة عقدة Whats360 إلى أي Workflow جديد دون الحاجة إلى كتابة طلبات HTTP يدويًا.

مسارات العمل الجاهزة باستخدام Whats360 داخل n8n

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

1. إنشاء وكيل ذكاء اصطناعي يتفاعل مع العملاء عبر WhatsApp

يمكن بناء وكيل دعم أو مبيعات يعمل بصورة آلية بمجرد وصول رسالة جديدة من العميل. يبدأ المسار باستقبال الرسالة من Whats360 Trigger، ثم تمرير محتوى الرسالة إلى عقدة AI Agent، وبعد توليد الرد يتم إرساله تلقائيًا إلى نفس رقم العميل باستخدام Whats360 Node.

[Whats360 Trigger]
        ↓
[AI Agent / LangChain]
        ↓
[Whats360 Node - Send Text]
        ↓
[Customer WhatsApp]

ويستطيع الـ AI Agent استخدام البيانات القادمة من Webhook، مثل رقم العميل ونص الرسالة واسم المرسل ومعرف المحادثة، ثم بناء الرد المناسب وفق التعليمات الخاصة بالشركة.

ومن أهم النقاط هنا أن رقم العميل لا يحتاج إلى تحويل يدوي إلى WhatsApp JID، لأن الدالة formatToJid() تقوم بهذه المهمة تلقائيًا قبل إرسال الرسالة.

const rawRecipient = this.getNodeParameter('recipient', i) as string;
const jid = formatToJid(rawRecipient);

وبالتالي يمكن أن تصل قيمة العميل بالشكل:

01012345678

أو:

+201012345678

وتقوم العقدة بتحويلها إلى:

201012345678@s.whatsapp.net

وهذا يقلل الأخطاء الناتجة عن اختلاف تنسيقات أرقام الهاتف القادمة من النماذج أو المتاجر أو أنظمة CRM.

2. إرسال إشعارات الطلبات من المتاجر الإلكترونية

يمكن ربط WooCommerce أو Shopify مع Whats360 بحيث يتم إرسال رسالة WhatsApp تلقائيًا عند إنشاء طلب جديد.

[WooCommerce Trigger]
        ↓
[Set / Code]
        ↓
[Whats360 - Send Text]
        ↓
[Customer WhatsApp]

يمكن أن يحتوي نص الرسالة على رقم الطلب، اسم العميل، إجمالي الطلب، وحالة الطلب، مع استخدام Expressions الخاصة بـ n8n للحصول على البيانات مباشرة من الـ Workflow.

مرحبًا {{$json.customer_name}}

تم استلام طلبك رقم {{$json.order_id}} بنجاح.

إجمالي الطلب: {{$json.total}}

سنقوم بالتواصل معك لتأكيد تفاصيل الشحن.

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

3. تحويل العملاء المحتملين من Meta Leads إلى فريق المبيعات

يمكن أيضًا استخدام Whats360 كحلقة اتصال بين إعلانات Meta وفريق المبيعات.

[Facebook Lead Ads Trigger]
        ↓
[Extract Lead Data]
        ↓
[Whats360 - Send Text]
        ↓
[Whats360 - Send Document]
        ↓
[VCash - Send SMS]

عند وصول Lead جديد يمكن إرسال رسالة ترحيبية مباشرة إلى العميل عبر WhatsApp، ثم إرسال كتالوج أو ملف PDF، وفي الوقت نفسه إرسال تنبيه SMS إلى موظف المبيعات.

بهذه الطريقة يتحول الـ Workflow من مجرد استقبال Lead إلى نظام متابعة آلي يمكنه تنفيذ عدة إجراءات في ثوانٍ.

التعامل مع أخطاء WhatsApp بصورة عملية

من أهم مميزات الحزمة المقترحة أنها لا تكتفي بإرجاع رسالة الخطأ التقنية القادمة من الخادم، وإنما تحاول تحويل الأخطاء المعروفة إلى رسائل مفهومة تساعد المطور أو مسؤول الـ Workflow على اتخاذ الإجراء المناسب.

فعلى سبيل المثال، إذا أعادت الخدمة الخطأ 463، تقوم الدالة المركزية بتحويله إلى رسالة تشخيصية واضحة:

WhatsApp Error [463]: The recipient has not opened a conversation window yet, or encryption is uninitialized. Solution: Send a direct message from the phone to this number first to initiate the session.

كما يتم التعامل مع بعض الأخطاء الأساسية الأخرى:

401: مشكلة في API Token أو انتهاء صلاحيته.
403: تجاوز حدود الخطة أو عدد الرسائل أو الأجهزة المسموح بها.
404: معرف Instance أو Device غير موجود.

وتتم معالجة هذه الأخطاء داخل الدالة المركزية whats360ApiRequest()، مما يعني أن جميع العمليات تستفيد من نفس طبقة التشخيص بدل تكرار منطق معالجة الأخطاء في كل Operation.

أمان Webhook الخاص بـ Whats360

لا ينبغي التعامل مع Webhook على أنه مجرد عنوان URL يستقبل البيانات، خصوصًا عندما يكون الـ Workflow متصلًا بأنظمة ذكاء اصطناعي أو CRM أو قواعد بيانات.

ولهذا يوفر Whats360 Trigger إمكانية استخدام Secret Header اختياري للتحقق من مصدر الطلب.

const incomingSecret =
	req.headers['x-hook-secret'] || req.headers['x-secret-key'];

if (incomingSecret !== secretHeader) {
	return {
		webhookResponse: {
			status: 'error',
			message: 'Unauthorized: Invalid Secret Header',
		},
	};
}

وفي حالة عدم تطابق المفتاح، يتم رفض الطلب بدل تمريره إلى بقية الـ Workflow.

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

const normalized = {
	sender_phone: bodyData.phone || bodyData.from || '',
	sender_name: bodyData.sender_name || bodyData.name || '',
	message: bodyData.message || bodyData.msg || bodyData.body || '',
	message_id: bodyData.message_id || bodyData.id || '',
	chat_jid: bodyData.chat_jid || '',
	instance_id: bodyData.instance_id || '',
	timestamp: bodyData.timestamp || Date.now(),
	media_url: bodyData.media_url || null,
	raw: bodyData,
};

وهذا يجعل البيانات التي تصل إلى AI Agent أو Code Node أو CRM أكثر اتساقًا.

لماذا تم فصل GenericFunctions عن ملف العقدة الرئيسي؟

فصل الوظائف المشتركة في ملف GenericFunctions.ts يجعل المشروع أسهل في الصيانة والتطوير. فبدل تكرار كود المصادقة والطلبات HTTP ومعالجة الأخطاء داخل كل عملية، يتم استدعاء دالة واحدة مسؤولة عن الاتصال بالـ API.

responseData = await whats360ApiRequest.call(
	this,
	'GET',
	'/api/v1/send-text',
	{},
	{
		instance_id: instanceId,
		jid,
		msg,
	},
);

ويتم تمرير الـ Token تلقائيًا من Credentials:

const credentials = await this.getCredentials('whats360Api');

const baseUrl =
	((credentials.baseUrl as string) || 'https://whats360.live')
		.replace(/\/$/, '');

const token = credentials.apiToken as string;

ثم يتم بناء الطلب باستخدام عنوان الخدمة وبيانات المصادقة:

const query: IDataObject = {
	token,
	...qs,
};

const options: IHttpRequestOptions = {
	method,
	url: `${baseUrl}${endpoint}`,
	headers: {
		'Accept': 'application/json',
		'Authorization': `Bearer ${token}`,
	},
	qs: query,
	json: true,
};

هذا التصميم يحقق مبدأ مهمًا في بناء Community Node احترافية: توحيد طبقة الاتصال بالـ API حتى تصبح إضافة Endpoint جديدة عملية بسيطة بدل إعادة بناء آلية الاتصال من الصفر.

التعامل مع Dynamic Dropdowns

من أهم عناصر تجربة المستخدم في العقدة توفير قائمة ديناميكية للأجهزة وInstances الموجودة في حساب Whats360 بدل إجبار المستخدم على نسخ Instance ID يدويًا.

methods = {
	loadOptions: {
		async getInstances(
			this: ILoadOptionsFunctions,
		): Promise<INodePropertyOptions[]> {
			try {
				const response = await whats360ApiRequest.call(
					this,
					'GET',
					'/api/v1/instances',
				);

				const returnData: INodePropertyOptions[] = [];
				const instances =
					response.response ||
					response.data ||
					response.instances ||
					[];

				if (Array.isArray(instances)) {
					for (const inst of instances) {
						returnData.push({
							name: `${inst.name || inst.id} (${inst.status || 'active'})`,
							value: inst.id || inst.instance_id,
						});
					}
				}

				return returnData;
			} catch (error) {
				return [];
			}
		},
	},
};

وبذلك تظهر الأجهزة في واجهة n8n كقائمة اختيار، بينما يتم تمرير المعرف الحقيقي إلى الـ API في الخلفية.

تصميم الحزمة ليكون مناسبًا للـ AI Agents

أحد الأهداف الرئيسية للحزمة هو ألا تكون مجرد HTTP Wrapper، وإنما Node يمكن استخدامها ضمن Workflows التي تعتمد على الذكاء الاصطناعي.

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

[Incoming WhatsApp Message]
              ↓
        [AI Agent]
        ↙    ↓     ↘
 [CRM Tool] [Whats360] [Database]
              ↓
       [WhatsApp Reply]

هذا التصميم يسمح ببناء وكلاء مبيعات ودعم فني قادرين على تنفيذ إجراءات فعلية بدل الاكتفاء بإنتاج النصوص.

ويمكن لاحقًا توسيع العقدة لتقديم عمليات إضافية كأدوات للـ Agent، مثل قراءة حالة الجهاز أو الحصول على بيانات الحملات أو تنفيذ إجراءات مرتبطة بالـ CRM، بشرط أن تكون الـ Endpoints المطلوبة مدعومة رسميًا من API.

العمليات التي يجب عدم إضافتها قبل تأكيد الـ API

رغم إمكانية تنفيذ العديد من الوظائف مستقبلًا، يجب عدم اختراع Endpoints غير موجودة في وثائق Whats360 الرسمية بهدف زيادة عدد Features في الإصدار الأول.

ومن العمليات التي ينبغي إبقاؤها ضمن خارطة الطريق حتى يتم اعتماد الـ API رسميًا:

إنشاء وتحديث جهات الاتصال.
تصدير سجل المحادثات.
إرسال Interactive Buttons.
إرسال Interactive Lists.
مزامنة المحادثات مع أنظمة CRM الخارجية.

هذا الفصل بين العمليات المؤكدة والعمليات المستقبلية مهم للحفاظ على استقرار الحزمة ومنع المستخدم من الاعتماد على وظائف غير مستقرة أو غير موثقة.

خريطة الطريق المقترحة

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

الإصدار v1.0.0

إرسال رسائل WhatsApp النصية.
إرسال الصور والفيديو والصوت والمستندات.
إدارة WhatsApp Instances.
إدارة الحملات.
إرسال SMS.
تنفيذ USSD.
قراءة الرصيد والمعاملات.
إرسال البريد الإلكتروني.
Whats360 Trigger لاستقبال Webhooks.
Dynamic Instance Dropdowns.
Smart JID Formatting.
معالجة أخطاء API بصورة تشخيصية.

الإصدار v1.1.0

بعد توفير Endpoint رسمي للرسائل التفاعلية، يمكن إضافة دعم Buttons وLists، مما يسمح ببناء محادثات أكثر تفاعلية داخل Workflows.

الإصدار v1.2.0

يمكن إضافة مزامنة جهات الاتصال وسجل المحادثات وربطها بأنظمة CRM خارجية، بما يسمح باستخدام Whats360 كطبقة اتصال داخل منظومة CRM وأتمتة متكاملة.

استراتيجية إطلاق وتسويق Community Node

نجاح الحزمة لا يعتمد فقط على نشرها في npm، وإنما على جعل المطور يصل إليها ويعرف كيفية استخدامها في أول Workflow له.

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

قوالب مقترحة للإطلاق

AI WhatsApp Customer Support Agent.
WooCommerce Order Notification via WhatsApp.
Shopify Order Notification via WhatsApp.
Meta Lead Ads to WhatsApp Sales Team.
WhatsApp Customer Follow-up Automation.
Payment Confirmation via WhatsApp.
Appointment Confirmation via WhatsApp.
WhatsApp + SMS Sales Notification.

ويُفضل أن يكون لكل Template ملف Workflow جاهز للاستيراد مع شرح قصير يوضح Credentials المطلوبة والخطوات اللازمة لتشغيله.

الخلاصة

تطوير n8n-nodes-whats360 يحول Whats360 من مجرد API يمكن استدعاؤه برمجيًا إلى مكوّن قابل للاستخدام داخل منظومة أتمتة واسعة، ويختصر على المطورين الكثير من العمل المتكرر في كتابة HTTP Requests وإدارة Authentication وتحويل أرقام الهاتف ومعالجة الأخطاء.

وتزداد أهمية هذا التكامل مع انتشار n8n كطبقة Automation وAI Agent، لأن Whats360 يمكن أن يصبح قناة اتصال فعلية للوكلاء الذكيين، وليس مجرد خدمة لإرسال الرسائل.

ومن الناحية التقنية، فإن أفضل نقطة بداية هي الحفاظ على الإصدار الأول بسيطًا ومستقرًا، والاعتماد فقط على Endpoints المؤكدة، مع بناء طبقة اتصال مركزية قابلة للتوسع، وواجهة استخدام تعتمد على Dynamic Dropdowns، وWebhook Trigger آمن، ومعالجة واضحة للأخطاء.

وبعد إطلاق الإصدار الأول، يمكن توسيع المنظومة تدريجيًا بإضافة الرسائل التفاعلية، جهات الاتصال، سجل المحادثات، تكاملات CRM، وقوالب AI Agents، لتصبح Whats360 جزءًا من البنية التحتية للأتمتة والتواصل داخل الشركات والمتاجر الرقمية.

ملاحظات مهمة قبل اعتبار الكود Production-Ready

الكود السابق يمثل أساسًا قويًا لبناء Community Node، ولكن قبل نشره كحزمة إنتاجية رسمية يجب إجراء اختبار فعلي لكل Endpoint مقابل نسخة API المستخدمة في Whats360، لأن نجاح TypeScript في الترجمة لا يعني بالضرورة تطابق جميع أسماء الحقول أو استجابات API مع التنفيذ المتوقع.

كما يجب اختبار الحالات التالية قبل الإصدار النهائي:

API Token صحيح وخاطئ.
Base URL مع وبدون / في النهاية.
عدم وجود Instances.
Instance غير متصل.
رقم هاتف مصري محلي ودولي.
JID جاهز مسبقًا.
إرسال Media URL غير صالح.
فشل API أثناء تنفيذ Workflow.
تفعيل Continue On Fail.
وصول Webhook بدون Secret.
وصول Webhook باستخدام Secret خاطئ.
تشغيل أكثر من Item داخل نفس Workflow.
استجابات API المختلفة في عمليات Instances وCampaigns.

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

الوسوم

محمد فارس

0 699 16 دقائق