الدليل المعماري الشامل: بناء نظام WhatsApp Bot وذكاء اصطناعي مخصص بالكامل عبر Whats360 API وGemini

يواجه مهندسو البرمجيات وفرق التطوير في قطاعات التجارة الإلكترونية والخدمات الرقمية تحدياً حقيقياً عندما يسعون لربط روبوتات الذكاء الاصطناعي التوليدي بتطبيق المحادثات واسع الانتشار عالمياً. فالتطبيق العملي الساذج الذي يعتمد على تمرير الرسائل الخام مباشرة من تطبيق المراسلة إلى النماذج التوليدية يصطدم بجدران من الفشل التشغيلي في بيئات الإنتاج الفعلية؛ بدءاً من بطء الاستجابة واستهلاك الميزانيات في ردود التحيات البسيطة، وصولاً إلى فقدان سياق العميل وانهيار العمليات عند تزامن مئات الطلبات في اللحظة ذاتها.

الحل التقني الجذري لا يكمن في استخدام روبوتات محدودة الإمكانيات أو أكواد سريعة الانهيار، بل في تشييد بنية برمجية تفصل بحزم بين طبقة الاتصال والبروتوكول، وطبقة التحقق والتوجيه المنطقي، وطبقة الذاكرة الدائمة وقواعد البيانات. في هذه المعمارية المعتمدة، تمثل بوابة Whats360 Developer API المحرك الموثوق لنقل الأحداث واستقبالها، في حين يدير خادمك الخاص دفة المعالجة بالتعاون المحسوب مع محرك Gemini API التابع لشركة Google.

تفكيك المنظومة: الفصل الحتمي بين طبقات الاتصال والمنطق وقواعد البيانات

أولى خطوات تصميم النظم المتقدمة هي القضاء على الخلط بين ما تقدمه أدوات الأتمتة المدمجة وما يقع على عاتق خادم المطور المستقل. تتكون منظومتنا الهندسية من ستة أركان لا غنى عنها:

• واجهة المطورين في Whats360: طبقة برمجية وسيطة بمعمارية RESTful تمنح نظامك القدرة على إرسال الرسائل النصية، الصور، المستندات، والتسجيلات الصوتية بصورة آلية وفحص سلامة اتصال الرقم بالشبكة الدولية.
• خدمة الويب هوك الصادر (Outgoing Webhook): آلية تنبيه حية تعتمد على بنية الأحداث، حيث تقوم المنصة بدفع البيانات بصيغة JSON إلى خادمك في أجزاء من الثانية فور استقبال أي تفاعل جديد.
• البوتات المدمجة داخل المنصة: برمجيات محادثة بدون كود موجهة لفرق المبيعات وخدمة العملاء، مثل البوت البسيط ونظام حجز المواعيد التقليدي، وهي أدوات ممتازة لغير التقنيين لكنها محكومة بحدود الواجهة ولا تسمح للمطور ببناء منطق تشغيلي حر أو الاتصال بمصادر بيانات غير قياسية.
• محرك الاستدلال اللغوي في Gemini API: نموذج ذكاء اصطناعي احتمالي يمتلك كفاءة فائقة في إدراك المعنى والسياق واستخراج الكيانات المحددة من لغة المحادثة الحرة، ولكنه معزول بطبيعته عن العالم الخارجي ولا يمكنه تنفيذ عمليات مصرفية أو تحديث أرصدة دون وسيط برمجي.
• خادم التطبيق الخاص بك (Backend Middleware):** المركز الإداري المسؤول عن التحقق الأمني من صلاحية الطلبات، واسترجاع السياق التاريخي، وتطبيق قواعد الأعمال المعقدة قبل اتخاذ أي قرار.
• طبقة قواعد البيانات والتخزين المؤقت: البيئة الحافظة للحقيقة التشغيلية؛ حيث تتكامل قواعد البيانات العلائقية مثل PostgreSQL أو MySQL مع نظم الذاكرة فائقة السرعة مثل Redis لإدارة الجلسات اللحظية.

المعمارية الهندسية الشاملة وتدفق حركة البيانات

لكي نضمن عدم توقف المحرك تحت ضغط الاستخدام المتزامن، يجب أن تتبع حركة البيانات مساراً أحادي الاتجاه غير معتمد على الانتظار المتزامن. يوضح المخطط الهيكلي التالي دورة حياة الرسالة منذ خروجها من هاتف المستخدم وحتى عودة الرد المعتمد إليه:

[Client on WhatsApp Mobile]
        │
        ▼ (1) Inbound User Message
[Whats360 Cloud Edge Infrastructure]
        │
        ▼ (2) Outgoing Webhook Event (HTTP POST)
[Your Production Application Server]
        │
        ├─── Validate Header Security: X-Hook-Secret
        ├─── Immediate Response: HTTP 200 OK (Fast-Ack)
        │
        ▼ (3) Asynchronous Background Worker Processing
[Intelligent Message Router]
        │
        ├── Match Rule 1: Static Keyword Match ──────> [Return Cached Template]
        ├── Match Rule 2: Transactional Query ───────> [Query PostgreSQL / ERP]
        ├── Match Rule 3: Support Escalation ────────> [Flag Database & Alert Human]
        │
        └── Complex Query / Natural Language ────────> [Invoke Gemini 1.5 API]
                                                              │
        ┌─────────────────────────────────────────────────────┘
        ▼ (4) Deterministic Action Validation & Structured JSON Execution
[Send Dispatcher Service]
        │
        ▼ (5) REST API Call: GET /api/v1/send-text?token=...&jid=...
[Whats360 Developer Engine]
        │
        ▼ (6) End-to-End Encrypted Delivery
[Client on WhatsApp Mobile]

تشريح حمولة البيانات الواردة عبر الويب هوك

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

{
  "instance_id": "YOUR_INSTANCE_ID",
  "phone": "2010XXXXXXXX",
  "sender_name": "Tariq Mahmoud",
  "message": "هل يمكنني معرفة مواعيد الشحن إلى الإسكندرية والأسعار المتاحة؟",
  "message_id": "3EB0FF4829104A76C091",
  "chat_jid": "2010XXXXXXXX@s.whatsapp.net",
  "timestamp": 1774008600,
  "media_url": null
}

يحتوي هذا التركيب على ثمانية حقول محورية تقوم عليها عمليات المعالجة اللاحقة:

• حقل phone: الرقم الصافي للمرسل بالترميز الدولي؛ وهو المعرف الأساسي لربط العميل بملفه في منظومة إدارة علاقات العملاء.
• حقل message: النص المجرد الذي يعبر عن طلب المستخدم، ويمثل المدخل التحليلي لطبقة الذكاء الاصطناعي والموجه المنطقي.
• حقل sender_name: الاسم المعتمد لدى المستخدم في ملفه الشخصي على واتساب، ويستفاد منه في تخصيص الردود بأسلوب ودود.
• حقل instance_id: المعرف الفريد للجهاز المشغل داخل حساب Whats360؛ وله أهمية كبرى عند تشغيل خادم واحد يخدم أرقاماً وهواتف متعددة لمنع تداخل الأحداث.
• حقل message_id: معرف لا يتكرر للرسالة المستلمة؛ ويستخدم كقيمة محورية للتحقق من عدم تكرار المعالجة (Idempotency Key) في حال أعادت الشبكة إرسال الحزمة.
• حقل chat_jid: المعرف الميداني للدردشة المباشرة مع العميل بصيغة البروتوكول الرسمية؛ وهو العنوان الإلزامي الذي يُعاد توجيه الرد إليه لاحقاً.
• حقل timestamp: الطابع الزمني الصادر عن الخادم، ويستخدم للتحقق من عمر الرسالة واستبعاد أي رسائل معلقة قديمة عند إعادة تشغيل الأنظمة.
• حقل media_url: رابط مباشر لتنزيل المرفقات إذا قام العميل بإرسال صورة إيصال سداد أو مستند PDF أو رسالة صوتية.

بيئة العمل والأمان وتأمين المتغيرات الحساسة

تسريب الرموز التعريفية للواجهات البرمجية هو السبب الأول لاختراق قنوات الاتصال المؤسسية وإرسال رسائل سبام تؤدي لحظر أرقام الشركات نهائياً. لذلك، يحظر تماماً تضمين الرموز ومفاتيح الدخول داخل الملفات البرمجية مباشرة، ويجب الاعتماد حصرياً على متغيرات البيئة عبر ملف .env مع تأمينه بإدراجه داخل ملف .gitignore قبل رفعه إلى أي مستودع على منصة GitHub.

إليك النموذج القياسي لملف الإعدادات المعتمد للمشروع تحت اسم .env.example:

# Whats360 Platform Credentials
WHATS360_BASE_URL=https://whats360.live
WHATS360_API_TOKEN=YOUR_WHATS360_API_TOKEN
WHATS360_INSTANCE_ID=YOUR_INSTANCE_ID
WEBHOOK_SECRET=YOUR_WEBHOOK_SECRET

# Google Gemini Intelligence Core
GEMINI_API_KEY=YOUR_GEMINI_API_KEY

# Application Deployment Configuration
PORT=3000
NODE_ENV=production
DATABASE_URL=postgresql://app_user:app_password@localhost:5432/bot_production
REDIS_URL=redis://localhost:6379

التنفيذ البرمجي لطبقة الاستقبال عبر الويب هوك

تفرض البروتوكولات الشبكية لخوادم الويب هوك قاعدة ذهبية: الرد الفوري قبل التفكير. عندما يرسل Whats360 إشعار الرسالة الواردة، فإنه يتوقع استلام تأكيد استلام برمز 200 OK في فترة لا تتعدى ثوانٍ معدودة. إذا تأخر خادمك في الرد لأنه ينتظر نموذج Gemini ليصيغ الإجابة، ستفترض المنصة أن خادمك معطل، وتبدأ آلياً بإعادة إرسال نفس الرسالة مرات متتالية، مما يسبب تكرار الردود للعميل واستهلاكاً مضاعفاً للموارد.

لمنع هذه المشكلة، نقوم بتطبيق تقنية Fast-Ack Pattern: نتحقق من الترويسة الأمنية أولاً، ونرسل الرد الإيجابي للشبكة فوراً، ثم نحيل عملية المعالجة بالكامل إلى مهمة خلفية غير متزامنة.

تطبيق كامل باستخدام بيئة Node.js وإطار Express

يمكن تدشين المشروع البرمجي في بيئة Node.js بالاعتماد على إطار العمل الخفيف والمستقر Express مع الحزم المساندة عبر الكود الإنتاجي التالي:

require('dotenv').config();
const express = require('express');
const axios = require('axios');

const app = express();
app.use(express.json());

const ENV = {
    PORT: process.env.PORT || 3000,
    BASE_URL: process.env.WHATS360_BASE_URL || 'https://whats360.live',
    TOKEN: process.env.WHATS360_API_TOKEN || 'YOUR_WHATS360_API_TOKEN',
    INSTANCE: process.env.WHATS360_INSTANCE_ID || 'YOUR_INSTANCE_ID',
    SECRET: process.env.WEBHOOK_SECRET || 'YOUR_WEBHOOK_SECRET'
};

app.post('/api/webhook/whatsapp', (req, res) => {
    const receivedSecret = req.headers['x-hook-secret'];
    
    if (ENV.SECRET && receivedSecret !== ENV.SECRET) {
        return res.status(403).json({ success: false, error: 'Unauthorized: Secret Header Mismatch' });
    }

    const payload = req.body;

    if (!payload || !payload.chat_jid || !payload.message) {
        return res.status(200).json({ status: 'ignored', reason: 'Payload does not contain valid message entity' });
    }

    res.status(200).json({ status: 'success', message: 'Payload acknowledged into queue' });

    setImmediate(async () => {
        try {
            await executeMessagePipeline(payload);
        } catch (pipelineError) {
            console.error('[Async Execution Fault]:', pipelineError.message);
        }
    });
});

async function executeMessagePipeline(eventData) {
    console.log(`[Processing Message] From: ${eventData.sender_name} (${eventData.phone}): ${eventData.message}`);
}

app.listen(ENV.PORT, () => {
    console.log(`Production WhatsApp Worker initialized successfully on port ${ENV.PORT}`);
});

تطبيق كامل باستخدام لغة Python وإطار FastAPI

إذا كانت منظومتك التقنية تعتمد على لغة Python لما توفره من أدوات متقدمة في علوم البيانات ومعالجة اللغات، فإن إطار العمل الحديث FastAPI يوفر أداءً يضاهي أسرع المحركات بفضل دعمه الأصيل للمهام الخلفية (Background Tasks):

import os
from fastapi import FastAPI, Request, Header, HTTPException, BackgroundTasks
import httpx
from dotenv import load_dotenv

load_dotenv()

app = FastAPI(title="WhatsApp Enterprise Bot Gateway")

CONFIG_BASE_URL = os.getenv("WHATS360_BASE_URL", "https://whats360.live")
CONFIG_API_TOKEN = os.getenv("WHATS360_API_TOKEN", "YOUR_WHATS360_API_TOKEN")
CONFIG_INSTANCE_ID = os.getenv("WHATS360_INSTANCE_ID", "YOUR_INSTANCE_ID")
CONFIG_WEBHOOK_SECRET = os.getenv("WEBHOOK_SECRET", "YOUR_WEBHOOK_SECRET")

async def background_message_worker(payload: dict):
    phone_number = payload.get("phone")
    message_content = payload.get("message")
    sender_name = payload.get("sender_name", "Valued Customer")
    chat_jid = payload.get("chat_jid")
    
    print(f"[Worker Active] Handling incoming message from {sender_name} ({phone_number}): {message_content}")

@app.post("/api/webhook/whatsapp")
async def handle_whatsapp_webhook(
    request: Request,
    background_tasks: BackgroundTasks,
    x_hook_secret: str = Header(None)
):
    if CONFIG_WEBHOOK_SECRET and x_hook_secret != CONFIG_WEBHOOK_SECRET:
        raise HTTPException(status_code=403, detail="Forbidden: Security Signature Invalid")

    payload_data = await request.json()

    if not payload_data.get("chat_jid") or not payload_data.get("message"):
        return {"status": "ignored", "reason": "Empty or non-chat payload"}

    background_tasks.add_task(background_message_worker, payload_data)
    return {"status": "success", "message": "Enqueued for asynchronous execution"}

هندسة خدمة الإرسال ومعالجة استثناءات واجهة المطورين

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

• المسار البرمجي المخصص: /api/v1/send-text
• المعامل token: رمز التوثيق السري الخاص بحسابك البرمجي (YOUR_WHATS360_API_TOKEN).
• المعامل instance_id: المعرف الفريد للجهاز المشغل للمحادثة (YOUR_INSTANCE_ID).
• المعامل jid: المعرف الميداني لوجهة الدردشة (YOUR_CUSTOMER_JID بصيغة 2010XXXXXXXX@s.whatsapp.net).
• المعامل msg: النص المراد تسليمه مشفراً بصيغة URL Encoding القياسية.

تحليل وفك شفرة أخطاء الاتصال ورمز الحظر البروتوكولي

لا يمكن بناء نظام إنتاجي دون معالجة الأخطاء المحتملة التي ترجعها الواجهة البرمجية. يوضح الكود التالي دالة الإرسال المتكاملة مع تحليل دقيق لحالات الفشل:

async function dispatchWhatsAppMessage(destinationJid, responseText) {
    const endpoint = `${ENV.BASE_URL}/api/v1/send-text`;
    
    const requestParameters = {
        token: ENV.TOKEN,
        instance_id: ENV.INSTANCE,
        jid: destinationJid,
        msg: responseText
    };

    try {
        const result = await axios.get(endpoint, {
            params: requestParameters,
            timeout: 8000
        });

        if (result.data && result.data.success) {
            return { status: 'delivered', payload: result.data };
        }
        
        throw new Error(result.data?.error || 'Rejected by provider endpoint');
    } catch (apiError) {
        if (apiError.response) {
            const statusCode = apiError.response.status;
            const errorPayload = apiError.response.data;

            switch (statusCode) {
                case 400:
                    console.error('[HTTP 400 - Bad Request]: معاملات غير مكتملة، راجع token و instance_id و jid و msg.');
                    break;
                case 401:
                    console.error('[HTTP 401 - Unauthorized]: التوكن منتهي الصلاحية أو غير صحيح. تحقق من لوحة التحكم.');
                    break;
                case 404:
                    console.error('[HTTP 404 - Device Missing]: الجهاز غير متواجد على السيرفر أو تم حذفه من الحساب.');
                    break;
                case 463:
                    console.warn('[HTTP 463 - Protocol Window Lock]: هذا الرقم غير متاح للمحادثة التلقائية حالياً.');
                    break;
                case 500:
                    console.error('[HTTP 500 - Internal Failure]: عطل داخلي مؤقت في بوابة المطورين. يُنصح بإعادة المحاولة.');
                    break;
                default:
                    console.error(`[HTTP ${statusCode} Unclassified Error]:`, errorPayload);
            }
        } else {
            console.error('[Socket/Network Failure]: انقطع الاتصال كلياً مع بوابة Whats360:', apiError.message);
        }
        
        return { status: 'failed', error: apiError.message };
    }
}

يستحق كود الخطأ 463 عناية هندسية فائقة؛ فهو خطأ بروتوكولي صادر من بنية واتساب المشفرة (End-to-End Encryption) عندما يحاول الخادم إرسال رسالة إلى هاتف لم يسبق له بدء محادثة مع جهازك، أو عند عدم اكتمال مفاتيح جلسة التشفير بين الطرفين.
التعامل الخاطئ مع هذا الكود عبر تكرار محاولة الإرسال آلياً وبصورة متتابعة يعرض رقمك للحظر السريع من قبل خوارزميات مكافحة الإزعاج في شركة واتساب. الإجراء السليم هو إيقاف محاولة الإرسال الآلي للرقم، أو فتح نافذة محادثة يدوية من الهاتف المشغل للمرة الأولى لتأسيس قناة التشفير بنجاح.

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

يمثل Message Router صمام الأمان المالي والتقني في منظومتنا؛ وتتمثل وظيفته في تقييم نص العميل وتوجيهه عبر أربعة مسارات محددة تمنع إهدار الموارد:

• مسار الردود النصية السريعة: الكلمات الشائعة مثل “مرحبا”، “مواعيد العمل”، “أين عنوانكم” لا تحتاج ذكاءً اصطناعياً؛ إذ يتم الرد عليها مباشرة بنصوص من الذاكرة اللحظية بزمن استجابة أقل من 25 ميلي ثانية وتكلفة توكنز صفرية.
• مسار الاستعلامات الحتمية (Deterministic Queries): أسئلة متابعة الشحنات وأرصدة الحسابات تُمرر إلى قواعد بيانات المتجر أو أتمتة العمليات عبر الـ ERP للحصول على بيانات دقيقة حسابياً لا تحتمل الهلوسة.
• مسار الإسناد والتحويل البشري: عند ورود عبارات مثل “أريد تقديم شكوى” أو “أحتاج موظفاً”، يُعطل الخادم الرد الآلي للعميل فوراً، ويرسل إشعاراً لفريق الدعم للتدخل البشري الفوري.
• مسار التحليل الاستشاري المعقد: يُحال إلى نموذج Gemini فقط عندما يعجز النظام عن تصنيف الرسالة ضمن القواعد السابقة، أو عندما يتطلب الاستفسار صياغة استشارية مخصصة.

استخراج البيانات المهيكلة لحالات الشراء وحجز المواعيد

عند رغبة العميل في الشراء أو حجز موعد، تنص القاعدة الهندسية على: لا تمنح الذكاء الاصطناعي سلطة التنفيذ المباشر. إذا قال العميل: “أريد حجز كشف يوم الخميس الساعة 7 مساءً في عيادة الأسنان”، فإننا نلزم Gemini باستخراج النية والمحددات في هيئة كائن JSON مهيكل فقط، كما يلي:

{
  "action": "reserve_appointment",
  "category": "dental",
  "preferred_day": "Thursday",
  "preferred_time": "19:00",
  "confidence_score": 0.98
}

يتسلم خادمك هذا الكائن البرمجي، ويقوم بالخطوات التالية حتمياً:

• فحص جدول المواعيد في قاعدة البيانات للتأكد من شغور موعد الساعة 7 مساء يوم الخميس.
• إذا كان الموعد شاغراً، يُثبت الحجز برمجياً، ويُسجل في جدول المواعيد مع تخصيص كود حجز فريد.
• إذا كان الموعد محجوزاً، يستخرج السيرفر أقرب موعدين متاحين (مثلاً: 6:00 أو 8:30).
• صياغة الرد البشري الدقيق وإرساله للمستخدم عبر Whats360.

إدارة سياق المحادثة والذاكرة المؤقتة للعملاء

تعتمد مكتبة @google/generative-ai الرسمية على تمرير تاريخ المحادثة التراكمي لتمكين النموذج من فهم سياق الردود التتابعية. إليك كود استدعاء نموذج Gemini 1.5 مع الحفاظ على نافذة الحوار:

const { GoogleGenerativeAI } = require('@google/generative-ai');
const geminiClient = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);

async function consultGeminiAgent(destinationJid, promptContent, historicalContext = []) {
    try {
        const generationModel = geminiClient.getGenerativeModel({
            model: "gemini-1.5-flash",
            systemInstruction: `أنت مستشار مبيعات ودعم فني لشركة تجارية مرموقة. 
            تحدث بلغة عربية مهذبة وموجزة. 
            إذا رغب المستخدم في الشراء أو حجز موعد، استخرج المحددات في هيئة JSON فقط دون أي مقدمات نصية:
            {"action": "create_order", "item": "...", "qty": 1, "city": "..."}`
        });

        const conversationSession = generationModel.startChat({
            history: historicalContext
        });

        const executionResult = await conversationSession.sendMessage(promptContent);
        const textPayload = executionResult.response.text();

        return textPayload;
    } catch (modelFault) {
        console.error('[Gemini AI Invocation Failure]:', modelFault.message);
        return 'أهلاً بك، أواجه ضغطاً لحظياً في استيعاب استفسارك وسيقوم أحد ممثلينا بالتواصل معك في أقرب وقت.';
    }
}

جاهزية بيئة الإنتاج وقابلية التوسع الهندسي

انهيار الذاكرة اللحظية والحلول البديلة

من الأخطاء البرمجية الشائعة حفظ محادثات المستخدمين في متغير محلي بالذاكرة مثل new Map() أو كائن تخزين عام. ينهار هذا النهج تماماً في بيئات العمل الحقيقية للأسباب التالية:

• تعدد مسارات المعالجة (Cluster Multi-Processing): عند استخدام مديري العمليات مثل PM2 لتشغيل التطبيق على كافة أنوية المعالج، لا تتشارك المسارات نفس الذاكرة؛ فإذا وصلت الرسالة الأولى للنواة رقم 1 والثانية للنواة رقم 2، ستفقد المحادثة سياقها كلياً.
• إعادة تشغيل الخادم وتحديث النسخ: تضيع كافة بيانات الذاكرة اللحظية بمجرد إعادة تشغيل التطبيق أو تحديث الكود.
• تسريب الذاكرة (Memory Leaks): بقاء آلاف المحادثات في الذاكرة العشوائية دون تفريغ تلقائي يؤدي حتماً إلى امتلاء الذاكرة وتوقف الخادم فجأة (OOM Crash).

الحل القياسي هو توزيع المهام: نستخدم Redis كذاكرة فائقة السرعة لإدارة الجلسات اللحظية مع تفعيل خاصية انتهاء الصلاحية التلقائي (TTL) لتفريغ الذاكرة بعد ساعتين من انقطاع المحادثة، ونستخدم PostgreSQL لتخزين السجل التاريخي الدائم للعملاء والمعاملات المالية.

مخطط قواعد البيانات العلائقية الموصى به

يوفر التصميم الهيكلي التالي في قواعد بيانات PostgreSQL مرونة هائلة لتسجيل العملاء وسير العمليات:

-- جدول حفظ الهوية الثابتة للعملاء
CREATE TABLE IF NOT EXISTS customers (
    id BIGSERIAL PRIMARY KEY,
    phone_number VARCHAR(32) UNIQUE NOT NULL,
    chat_jid VARCHAR(128) UNIQUE NOT NULL,
    display_name VARCHAR(255),
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

-- جدول متابعة حالة الجلسة النشطة
CREATE TABLE IF NOT EXISTS bot_sessions (
    id BIGSERIAL PRIMARY KEY,
    customer_id BIGINT REFERENCES customers(id) ON DELETE CASCADE,
    current_state VARCHAR(64) DEFAULT 'IDLE',
    detected_intent VARCHAR(64) DEFAULT 'NONE',
    state_context JSONB DEFAULT '{}'::jsonb,
    is_escalated BOOLEAN DEFAULT FALSE,
    last_interaction TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

-- جدول سجل الرسائل والتدقيق المحاسبي
CREATE TABLE IF NOT EXISTS interaction_logs (
    id BIGSERIAL PRIMARY KEY,
    customer_id BIGINT REFERENCES customers(id) ON DELETE CASCADE,
    direction VARCHAR(8) CHECK (direction IN ('IN', 'OUT')),
    message_content TEXT NOT NULL,
    whats360_reference_id VARCHAR(128),
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX IF NOT EXISTS idx_customers_phone ON customers(phone_number);
CREATE INDEX IF NOT EXISTS idx_sessions_customer ON bot_sessions(customer_id);

المعمارية متعددة الوكلاء وتنظيم تدفق العمل الذكي

في المنظومات التجارية المتقدمة، لا نوكل جميع المهام لوكيل ذكاء اصطناعي عام، بل يتم تقسيم المهام إلى وكلاء متخصصين (Specialized AI Sub-Agents)؛ حيث يتولى وكيل المبيعات استعراض المنتجات والكتالوجات، في حين يختص وكيل الدعم بحل المشكلات الفنية، ويتولى وكيل الحجوزات فحص المواعيد وتأكيدها.

إذا كنت بحاجة إلى بناء وتنسيق مسارات العمل المعقدة التي تربط بين عدة وكلاء ذكاء اصطناعي وأتمتة المهام المشتركة دون التورط في تعقيدات الكود المجهدة، فإن منصة Beincode تقدم بيئة عمل استثنائية لتشييد وإدارة سلاسل الوكلاء الأذكياء (AI Workflows). يمكنك متابعة سلسلة شروحات BeInCode AI Workflows المتخصصة على YouTube للاطلاع على كيفية بناء خطوط إنتاج برمجية ذكية تتكامل مع الأنظمة السحابية والواجهات البرمجية بمنتهى السلاسة.

خطوات النشر على خادم عام وتفعيل التشفير والربط النهائي

لكي يستقبل خادمك أحداث الويب هوك بنجاح من Whats360، يجب نشر التطبيق على خادم سحابي عام (VPS) يمتلك نطاقاً رقمياً مفعلاً بتشفير HTTPS رسمي:

• حجز الخادم الافتراضي: استأجر خادماً بنظام تشغيل Ubuntu 24.04 LTS، وثبت بيئة التشغيل المناسبة (Node.js LTS أو Python 3.12).
• إدارة العمليات المستمرة: شغل الكود عبر أداة PM2 لضمان استمرارية التطبيق وإعادة تشغيله تلقائياً في حال حدوث أي خطأ مفاجئ.
• تثبيت الخادم العكسي Nginx: اضبط خادم Nginx ليعمل كـ Reverse Proxy لاستقبال طلبات المنفذ 443 الخارجية وتوجيهها للمنفذ المحلي 3000.
• تأمين الاتصال بشهادة SSL مجانية: استخدم أدوات مؤسسة Let’s Encrypt لتثبيت شهادة أمان مشفرة ومعتمدة بنقرة واحدة عبر أداة Certbot.
• الربط النهائي داخل منصة Whats360: ادخل إلى حسابك في لوحة تحكم Whats360 وانتقل إلى قسم الويب هوك (HookURL)، ثم أنشئ رابطاً جديداً بالصيغة المعتمدة: https://YOUR_DOMAIN.com/api/webhook/whatsapp، وحدد الترويسة الأمنية الخاصة بك X-Hook-Secret: YOUR_WEBHOOK_SECRET، ثم اختر تفعيل أحداث “رسالة واردة”.

الأسئلة الشائعة التي يجيب عنها المقال

الخلاصة المعمارية وخطوات الانطلاق

إن بناء محرك واتساب مدعوم بالذكاء الاصطناعي يلبي طموحات الشركات لا يتحقق عبر السكريبتات البسيطة، بل يتطلب رؤية معمارية شاملة ترتكز على مبدأ فصل المسؤوليات البرمجية (Separation of Concerns). إن الجمع الاستراتيجي بين منصة Whats360 Developer API كطبقة اتصال وبنية تحتية موثوقة للشبكة، ونموذج Gemini 1.5 كعقل تحليلي، مع إدارة دقيقة للبيانات عبر PostgreSQL وRedis، يمنحك منظومة متماسكة لا تنهار تحت الضغط وتحقق أعلى مستويات الرضا لعملائك بأقل كلفة تشغيلية ممكنة.

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

مركز المعرفة الدلالية وهندسة الاسترجاع الذكي (SEO & AEO Architecture Hub)

يلخص هذا القسم المرجع الهيكلي ومصفوفة الكيانات الدلالية للنظام؛ حيث يجمع مؤشرات البحث الهندسية ونوايا الاسترجاع التقنية لنماذج البحث بالذكاء الاصطناعي (AI Search Engines) لتسهيل الفهرسة الدقيقة والاستشهاد البرمجي بالدليل.

استعلامات البحث وأسئلة الاسترجاع التوليدي (AEO Retrieval Queries)

يجيب هذا الدليل البرمجي بشكل مباشر وموثق عن استفسارات البحث الأساسية التالية:

خريطة الكيانات الدلالية والتقنية (Semantic Entity Graph)