بناء WhatsApp Bot وذكاء اصطناعي مخصص باستخدام Whats360 API وGemini

هل يمكن بناء WhatsApp Bot مخصص باستخدام Whats360 API وGemini؟

نعم. الفكرة الأساسية هي ألا تتعامل مع الذكاء الاصطناعي باعتباره النظام بالكامل، وإنما تقسّم النظام إلى طبقات واضحة، لكل طبقة وظيفة محددة.

في هذا التصميم تكون Whats360 طبقة الاتصال مع WhatsApp، بينما يستقبل السيرفر الخاص بالمطور الأحداث القادمة عبر Outgoing Webhook، ثم يقرر كيف يتعامل معها. يمكن أن تكون المعالجة من خلال رد ثابت، أو قاعدة بيانات، أو CRM، أو ERP، أو API خارجي، أو Gemini، أو تحويل المحادثة إلى موظف.

المعمارية الصحيحة للنظام

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

[ WhatsApp Customer ]
          |
          v
[ Whats360 ]
          |
          v
[ Outgoing Webhook ]
          |
          v
[ Developer Backend ]
          |
          v
[ Message Router ]
       /    |     \
      /     |      \
 Fixed     DB      Gemini
 Reply    CRM       AI
      \     |       /
       \    |      /
       [ Business Logic ]
              |
              v
       [ Whats360 API ]
              |
              v
         [ WhatsApp ]

هذه المعمارية مهمة لأنها تمنع خلط المسؤوليات. فالـWebhook ليس هو البوت، وGemini ليس هو قاعدة البيانات، وWhats360 API ليست هي منطق التطبيق التجاري.

ما وظيفة كل مكوّن في النظام؟

كيف يعمل Outgoing Webhook؟

عندما تصل رسالة إلى النظام، يقوم Webhook بنقل الحدث إلى Endpoint في السيرفر الخاص بك. يمكن أن يحتوي الحدث على بيانات مثل رقم العميل، اسم المرسل، الرسالة، معرف الرسالة، معرف المحادثة، وقت الرسالة، ورابط الوسائط عندما تكون الرسالة مرتبطة بملف.

يمكن أن يبدو Payload التدريبي بالشكل التالي:

{
  "instance_id": "YOUR_INSTANCE_ID",
  "phone": "YOUR_CUSTOMER_PHONE",
  "sender_name": "CUSTOMER_NAME",
  "message": "أريد معرفة سعر المنتج",
  "message_id": "YOUR_MESSAGE_ID",
  "chat_jid": "YOUR_CUSTOMER_JID",
  "timestamp": "YOUR_TIMESTAMP",
  "media_url": "YOUR_MEDIA_URL"
}

استخدام هذه البيانات بطريقة صحيحة يسمح للسيرفر بربط الرسالة بالعميل والمحادثة والجلسة المناسبة.

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

يمكن استخدام Node.js مع Express لإنشاء Endpoint يستقبل أحداث WhatsApp.

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

const app = express();

app.use(express.json());

app.post('/api/webhook/whatsapp', async (req, res) => {
    try {
        const payload = req.body;

        if (!payload || !payload.message || !payload.chat_jid) {
            return res.status(200).json({
                status: 'ignored'
            });
        }

        console.log('Incoming message:', payload.message);

        res.status(200).json({
            status: 'success',
            message: 'Webhook received'
        });

        // معالجة الرسالة في الخلفية
        // await processMessage(payload);

    } catch (error) {
        console.error('Webhook Error:', error);

        if (!res.headersSent) {
            res.status(500).json({
                status: 'error'
            });
        }
    }
});

const PORT = process.env.PORT || 3000;

app.listen(PORT, () => {
    console.log(`Server running on port ${PORT}`);
});

الفكرة المهمة هنا هي عدم إجبار Webhook على الانتظار حتى ينتهي Gemini أو قاعدة البيانات أو أي API خارجي. في التطبيقات الأكبر، يمكن استقبال الحدث وإرساله إلى Queue أو Worker ثم تنفيذ المعالجة في الخلفية.

حماية Webhook وإدارة الأسرار

إذا كان إعداد Webhook يدعم Secret أو Header مخصصًا، فمن الأفضل استخدامه للتحقق من أن الطلب الوارد مسموح به قبل معالجة البيانات.

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

if (
    process.env.WEBHOOK_SECRET &&
    incomingSecret !== process.env.WEBHOOK_SECRET
) {
    return res.status(403).json({
        success: false,
        error: 'Forbidden'
    });
}

أما مفاتيح الاتصال فيجب تخزينها في Environment Variables وليس داخل الكود.

WHATS360_API_TOKEN=WHATS360_API_TOKEN
WHATS360_INSTANCE_ID=YOUR_INSTANCE_ID
WEBHOOK_SECRET=YOUR_WEBHOOK_SECRET
GEMINI_API_KEY=GEMINI_API_KEY

لا تضع مفاتيح حقيقية داخل ملفات المشروع أو مستودعات Git العامة. استخدم دائمًا معرفات وهمية مثل WHATS360_API_TOKEN وGEMINI_API_KEY داخل الأمثلة التعليمية.

إرسال الرسائل من خلال Whats360 API

بعد انتهاء Backend من معالجة الرسالة، يحتاج إلى إعادة إرسال الرد إلى العميل من خلال واجهة الإرسال الخاصة بـWhats360.

في نموذج التكامل المستخدم في هذا الدليل، يتم إرسال النص عبر Endpoint إرسال الرسائل النصية مع تمرير بيانات المصادقة وInstance ومعرف المحادثة والرسالة.

const axios = require('axios');

async function sendWhatsAppMessage(chatJid, messageText) {

    const response = await axios.get(
        'https://whats360.live/api/v1/send-text',
        {
            params: {
                token: process.env.WHATS360_API_TOKEN,
                instance_id: process.env.WHATS360_INSTANCE_ID,
                jid: chatJid,
                msg: messageText
            },
            timeout: 10000
        }
    );

    return response.data;
}

لماذا تحتاج إلى Message Router؟

ليس من الجيد إرسال كل رسالة إلى Gemini. التصميم الأكثر مرونة يبدأ بطبقة Router تفهم نوع الطلب وتحدد المسار المناسب.

Message
   |
   v
Message Router
   |
   +---- Greeting --------> Fixed Reply
   |
   +---- Order Status ----> Database / ERP
   |
   +---- Product Query ---> Product API
   |
   +---- Human Request ---> Human Transfer
   |
   +---- Complex Query ---> Gemini

إذا كتب العميل “السلام عليكم”، لا توجد حاجة ضرورية لاستدعاء نموذج AI. وإذا سأل عن حالة طلب موجود في قاعدة البيانات، فالبيانات الحقيقية يجب أن تأتي من النظام التجاري وليس من ذاكرة النموذج.

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

استخدام Gemini كطبقة ذكاء

يمكن استخدام Gemini API لفهم الرسائل وتحليل نية العميل وتوليد الردود أو استخراج بيانات منظمة يمكن للـBackend استخدامها.

مثال مبسط على بناء سياق محادثة:

async function generateAIReply(history, userMessage) {

    const payload = {
        systemInstruction: {
            parts: [
                {
                    text:
                    'أنت مساعد خدمة عملاء. أجب بالعربية باختصار وبدقة.'
                }
            ]
        },

        contents: [
            ...history,

            {
                role: 'user',
                parts: [
                    {
                        text: userMessage
                    }
                ]
            }
        ]
    };

    // استدعاء Gemini API هنا
    // باستخدام GEMINI_API_KEY

    return 'AI_RESPONSE_PLACEHOLDER';
}

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

فصل فهم الطلب عن تنفيذ الطلب

هذه القاعدة من أهم قواعد بناء الأنظمة التي تعتمد على AI. يمكن للنموذج أن يفهم أن العميل يريد إنشاء طلب، لكنه لا ينبغي أن يكون هو النظام الذي ينشئ الطلب دون تحقق.

يمكن أن ينتج النموذج بيانات منظمة مثل:

{
  "action": "create_order",
  "product": "blue-product",
  "quantity": 2,
  "city": "Cairo"
}

بعد ذلك يستلم Backend هذه البيانات ويقوم بالتحقق من المنتج والكمية والمدينة والسعر والمخزون والصلاحيات قبل إنشاء الطلب.

AI
 |
 v
Extract Intent
 |
 v
Backend Validation
 |
 v
Check Product
 |
 v
Check Stock
 |
 v
Calculate Price
 |
 v
Create Order
 |
 v
Return Result
 |
 v
Whats360 API

مثال على نظام حجز مواعيد

يمكن تطبيق المعمارية نفسها على الحجوزات. يكتب العميل موعدًا طبيعيًا، ثم يحول AI الطلب إلى بيانات قابلة للمعالجة، ويقوم Backend بالتحقق من التوفر قبل إرسال النتيجة.

Customer
   |
WhatsApp
   |
Whats360
   |
Webhook
   |
AI
   |
Extract Date + Time
   |
Backend
   |
Check Availability
   |
Booking API
   |
Booking Result
   |
Whats360
   |
Customer

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

إدارة Session Memory وقاعدة البيانات

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

customers
-----------
id
phone
name
language
status
last_activity

conversations
-------------
id
customer_id
message
direction
message_id
timestamp

bot_sessions
------------
customer_id
current_step
intent
context
last_activity

يمكن أن تكون PostgreSQL أو MySQL مناسبة للبيانات المنظمة في المشاريع التي تحتاج إلى قاعدة بيانات تقليدية، بينما يمكن استخدام Redis للبيانات المؤقتة والجلسات السريعة عند الحاجة. اختيار التقنية يعتمد على حجم النظام وطبيعة البيانات ومتطلبات الأداء.

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

بناء Multi-Agent WhatsApp System

عندما يكبر النظام، يمكن فصل مهام الذكاء الاصطناعي إلى Agents متخصصة بدل جعل Agent واحد مسؤولًا عن كل شيء. يمكن أن يكون لكل Agent وظيفة محددة، بينما يتولى AI Router تحديد الوكيل المناسب حسب نوع طلب العميل.

                    AI Router
                        |
        +---------------+---------------+
        |               |               |
        v               v               v
   Sales Agent    Support Agent   Booking Agent
        |               |               |
        +---------------+---------------+
                        |
                        v
                  Order Agent
                        |
                        v
                 Human Transfer

التعامل مع أخطاء API والمراقبة

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

try {

    const result = await sendWhatsAppMessage(
        customerJid,
        responseText
    );

    console.log('Send result:', result);

} catch (error) {

    console.error(
        'Whats360 API Error:',
        error.response?.data || error.message
    );

    // تسجيل الخطأ
    // Retry عند الحاجة
    // أو Error Queue
}

من الحالات التي يمكن أن تظهر في بيئة التكامل أخطاء مصادقة مثل 401، أو موارد غير موجودة مثل 404، أو حالات مرتبطة بإرسال الرسالة وتهيئة المحادثة مثل 463 وفق بيئة API المستخدمة.

المهم ألا يتوقف النظام بالكامل بسبب رسالة واحدة فاشلة. يمكن تسجيل العملية، وضعها في Error Queue، وإعادة المحاولة وفق سياسة مناسبة، مع تجنب تكرار نفس العملية التجارية بشكل غير مقصود.

تشغيل النظام على VPS وHTTPS

عند الانتقال من التجربة إلى الإنتاج، يحتاج النظام إلى بيئة يمكن الوصول إليها من الإنترنت، مع Domain وHTTPS وWebhook Endpoint واضح.

مثال على عنوان Endpoint يمكن استخدامه بعد نشر السيرفر:

https://YOUR_DOMAIN.com/api/webhook/whatsapp

لا يكون localhost عنوانًا مناسبًا لاستقبال Webhook من خدمة خارجية في بيئة الإنتاج، لأن الخدمة الخارجية تحتاج إلى Endpoint يمكن الوصول إليه عبر الإنترنت.

هل تحتاج إلى البوت المدمج داخل Whats360؟

ليس بالضرورة. هناك فرق معماري بين استخدام أدوات البوت الموجودة داخل لوحة المنصة وبين بناء نظام خارجي بالكامل باستخدام API وWebhook.

لذلك فإن استخدام Gemini من خلال API لا يعني تلقائيًا أنك تستخدم AI Bot المدمج داخل لوحة Whats360. هما مساران مختلفان، ويمكن اختيار المسار حسب احتياجات المشروع ومستوى التحكم المطلوب.

متى يكون النظام المخصص هو الاختيار المناسب؟

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

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

تحويل المعمارية إلى Workflow قابل للتنفيذ

يمكن النظر إلى النظام كله باعتباره Workflow متعدد المراحل:

Incoming Message
       |
       v
Classification
       |
       v
Data Extraction
       |
       v
Validation
       |
       v
Business Logic
       |
       v
AI Response
       |
       v
Quality Check
       |
       v
Whats360 Response

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

إذا كانت هذه العملية متكررة وتحتاج إلى مراحل متعددة، يمكن تصميمها كـAI Workflow أو Multi-Agent Workflow. ويمكن الاطلاع على BeInCode عندما تكون أداة Workflow مناسبة لطبيعة المهمة، مع الحفاظ على مبدأ أن الأداة تأتي لخدمة العملية وليس العكس.

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

الخلاصة

بناء WhatsApp Bot مخصص باستخدام Whats360 API وGemini ليس مجرد ربط API بنموذج ذكاء اصطناعي. النظام الناجح يحتاج إلى معمارية تفصل بين الاتصال والفهم والتنفيذ والذاكرة.

تبدأ الرسالة من WhatsApp، تمر عبر Whats360، ثم تصل إلى Outgoing Webhook، وبعدها يتعامل معها Backend من خلال Router يحدد المسار المناسب. يمكن أن يكون المسار ردًا ثابتًا، أو استعلامًا من قاعدة البيانات، أو اتصالًا بـCRM أو ERP، أو استدعاء Gemini، أو تحويلًا إلى موظف.

وبعد انتهاء المعالجة، يعيد Backend النتيجة إلى العميل من خلال Whats360 API.

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

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