بناء أداة إرسال رسائل واتساب الصادرة

1. اختيار الأداة المناسبة: لماذا Twilio؟

كما رأينا في الدرس السابق، يمكن إعداد واجهة برمجة تطبيقات واتساب الرسمية مباشرة عبر منصة Meta، لكن العملية قد تكون معقدة وتتطلب تحققاً كاملاً من النشاط التجاري ورقم هاتف مخصص. لتسهيل عملية التعلم والتركيز على منطق الوكيل، سنستخدم خدمة تُعرف باسم "مزود حلول الأعمال" (Business Solution Provider - BSP)، والتي تبسط هذه العملية بشكل كبير.

لهذا الدرس، اخترنا Twilio، وهي واحدة من أشهر المنصات التي توفر واجهات برمجية للتواصل. أهم ميزة تقدمها Twilio للمطورين هي "بيئة الاختبار" (Sandbox).

ما هي بيئة الاختبار (Sandbox)؟
تخيلها كملعب آمن ومجاني. تسمح لك بيئة الاختبار بتجربة إرسال واستقبال رسائل واتساب باستخدام رقم هاتف توفره Twilio، دون الحاجة إلى شراء رقم جديد أو المرور بعملية الموافقة الرسمية الطويلة. ستكون قادراً على إرسال الرسائل من رقم Twilio إلى رقمك الشخصي الذي قمت بالتحقق منه. هذا مثالي لمرحلة البناء والتجربة.

2. الخطوة الأولى: إعداد بيئة الاختبار (Sandbox) في Twilio

قبل كتابة أي كود، نحتاج إلى تجهيز حسابنا على Twilio وتفعيل بيئة الاختبار الخاصة بواتساب. الفيديو التالي من قناة Code Jana سيأخذك خطوة بخطوة خلال هذه العملية.

بعد إتمام الخطوات في الفيديو، يجب أن تكون قد استلمت رسالة تأكيد على هاتفك من Twilio. الآن أصبحت بيئة الاختبار جاهزة، ولدينا رقم هاتف (رقم Twilio) يمكنه إرسال الرسائل، ورقم مستقبِل تم التحقق منه (رقمك الشخصي).

3. الخطوة الثانية: كتابة كود بايثون لإرسال الرسالة

الآن بعد أن أصبحت البنية التحتية جاهزة، حان وقت البرمجة. سنستخدم مكتبة بايثون الرسمية من Twilio لتسهيل عملية التواصل مع الواجهة البرمجية الخاصة بهم.

شاهد الأجزاء التالية من نفس الفيديو، والتي تغطي الجانب البرمجي.

تجميع الكود وتوضيحه

بناءً على ما شاهدته في الفيديو، هذا هو الكود الأساسي لإرسال رسالة واتساب باستخدام Twilio في بايثون:

import os
from twilio.rest import Client

# بيانات الاعتماد الخاصة بك من لوحة تحكم Twilio
# من الأفضل دائماً تحميلها من متغيرات البيئة بدلاً من كتابتها مباشرة في الكود
account_sid = os.environ.get("TWILIO_ACCOUNT_SID")
auth_token = os.environ.get("TWILIO_AUTH_TOKEN")

# رقم Twilio Sandbox الخاص بك
twilio_number = 'whatsapp:+14155238886'  # هذا هو رقم Twilio Sandbox القياسي

# رقم هاتفك الشخصي الذي تحققت منه (مع رمز البلد)
my_number = 'whatsapp:+966XXXXXXXXX' # استبدل برقمك الفعلي

# إنشاء كائن العميل (Client)
client = Client(account_sid, auth_token)

# إنشاء وإرسال الرسالة
try:
    message = client.messages.create(
                              body='مرحباً من وكيل الذكاء الاصطناعي الخاص بي!',
                              from_=twilio_number,
                              to=my_number
                          )

    print(f"تم إرسال الرسالة بنجاح!")
    print(f"Message SID: {message.sid}") # طباعة المعرف الفريد للرسالة

except Exception as e:
    print(f"حدث خطأ أثناء إرسال الرسالة: {e}")

تذكير هام بالأمان: كما تعلمنا في الوحدة الثانية، لا تقم أبداً بكتابة بيانات حساسة مثل account_sid و auth_token مباشرة في الكود. استخدم دائماً متغيرات البيئة (Environment Variables) لحفظها واستدعائها باستخدام os.environ.get(). هذا يحمي حسابك عند مشاركة الكود الخاص بك.

4. الخطوة الثالثة: تحويل الكود إلى "أداة" قابلة لإعادة الاستخدام

الآن لدينا كود يعمل، لكنه ليس مرناً. لإدراجه في وكيلنا الذكي، نحتاج إلى تحويله إلى "أداة" (Tool)، وهي في الأساس دالة (function) يمكن استدعاؤها بسهولة عند الحاجة.

هذه الدالة يجب أن تقبل متغيرات مثل رقم المستلم ونص الرسالة، وتتولى هي بقية التفاصيل.

import os
from twilio.rest import Client
from twilio.base.exceptions import TwilioRestException

def send_whatsapp_message(recipient_number, message_text):
    """
    ترسل رسالة واتساب إلى رقم محدد باستخدام Twilio.

    Args:
        recipient_number (str): رقم هاتف المستلم بالتنسيق الدولي (e.g., '+966...').
        message_text (str): نص الرسالة المراد إرسالها.

    Returns:
        bool: True إذا تم إرسال الرسالة بنجاح، False بخلاف ذلك.
        str: معرف الرسالة (SID) في حال النجاح، أو رسالة الخطأ في حال الفشل.
    """
    try:
        account_sid = os.environ.get("TWILIO_ACCOUNT_SID")
        auth_token = os.environ.get("TWILIO_AUTH_TOKEN")
        twilio_number = 'whatsapp:+14155238886'

        if not all([account_sid, auth_token]):
            return False, "بيانات اعتماد Twilio غير موجودة في متغيرات البيئة."

        client = Client(account_sid, auth_token)

        # إضافة البادئة المطلوبة لرقم المستلم
        formatted_recipient_number = f'whatsapp:{recipient_number}'

        message = client.messages.create(
            body=message_text,
            from_=twilio_number,
            to=formatted_recipient_number
        )

        return True, message.sid

    except TwilioRestException as e:
        return False, f"خطأ من Twilio: {e}"
    except Exception as e:
        return False, f"خطأ غير متوقع: {e}"

# --- مثال على الاستخدام ---
# تأكد من أنك قمت بتعيين متغيرات البيئة TWILIO_ACCOUNT_SID و TWILIO_AUTH_TOKEN

# استبدل بالرقم الذي قمت بالتحقق منه في Twilio Sandbox
RECIPIENT_PHONE_NUMBER = "+966XXXXXXXXX" 

success, result = send_whatsapp_message(
    recipient_number=RECIPIENT_PHONE_NUMBER,
    message_text="هذه رسالة من أداتنا الجديدة!"
)

if success:
    print(f"تم إرسال الرسالة بنجاح. معرف الرسالة: {result}")
else:
    print(f"فشل إرسال الرسالة. السبب: {result}")

لقد قمنا الآن ببناء دالة قوية وقابلة لإعادة الاستخدام. لاحظ كيف أضفنا معالجة للأخطاء (try...except) ونقوم بإرجاع حالة النجاح والنتيجة. هذا التصميم يجعل من السهل على وكيلنا الذكي استدعاء هذه الأداة ومعرفة ما إذا كانت المهمة قد تمت بنجاح أم لا.

خلاصة الدرس

لقد قمت اليوم بخطوة عملية هائلة! نجحت في بناء مكون برمجي حقيقي يمكنه إرسال رسائل عبر واتساب. لنلخص ما أنجزناه:

• اخترنا Twilio كبوابة مبسطة لعالم واتساب API، واستخدمنا بيئة الاختبار (Sandbox) المجانية الخاصة بهم.
• قمنا بإعداد البيئة عبر إنشاء حساب وربط رقم هاتفنا الشخصي.
• كتبنا كود بايثون باستخدام مكتبة twilio، وتعلمنا كيفية المصادقة باستخدام Account SID و Auth Token.
• أتقنا التفاصيل المهمة مثل التنسيق الصحيح لأرقام الهواتف (whatsapp:+...).
• قمنا ببناء "أداة" متكاملة على شكل دالة بايثون (send_whatsapp_message)، جاهزة ليستخدمها وكيلنا الذكي، مع تضمين معالجة للأخطاء.

أنت الآن تمتلك نصف القدرات المطلوبة لوكيل محادثة: القدرة على التحدث.

ماذا بعد؟

الآن بعد أن أصبح وكيلنا قادراً على إرسال الرسائل، ما هي الخطوة المنطقية التالية؟ بالطبع، هي أن يكون قادراً على الاستماع أو استقبال الردود.

في درسنا القادم، سنتناول الجانب الآخر من المحادثة: استقبال الرسائل الواردة. سنتعرف على مفهوم تقني بالغ الأهمية يسمى Webhooks، وهو الآلية التي تستخدمها خدمات مثل Twilio لإعلام تطبيقنا فور وصول رسالة جديدة. استعد لفتح قناة الاتصال في كلا الاتجاهين