كيفية إرسال رسائل SMS برمجياً عبر API لمواقع PHP وWordPress في مصر

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

في هذه الحالة يمكن استخدام نموذج SMS Gateway API بحيث يرسل الموقع أمرًا برمجيًا إلى بوابة الرسائل، بينما تتولى البوابة تنفيذ الإرسال من خلال جهاز Android متصل بالخدمة. هذا الأسلوب يتيح للمطور بناء التكامل داخل PHP أو WordPress دون أن يضطر إلى إعادة تصميم نظام الموقع بالكامل.

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

ما المقصود بـ SMS Gateway API؟

SMS Gateway API هي واجهة برمجية تسمح للنظام بإرسال أمر إلى خدمة مسؤولة عن إرسال رسالة SMS إلى رقم هاتف محدد. بدلًا من أن يكتب الموظف الرسالة ويرسلها يدويًا من الهاتف، يقوم الموقع بإرسال البيانات المطلوبة برمجياً.

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

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

كيف تعمل خدمة SMS Gateway مع موقع PHP أو WordPress؟

تعتمد الفكرة على وجود طرفين رئيسيين: النظام البرمجي الذي يحتاج إلى الإرسال، وبوابة SMS التي تنفذ عملية الإرسال. الموقع لا يحتاج إلى التحكم اليدوي في الهاتف في كل مرة؛ بل يرسل أمرًا منظمًا عبر API.

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

ما الذي يحتاجه المطور لبدء الربط؟

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

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

ما هو Endpoint الخاص بإرسال SMS؟

نقطة الإرسال المذكورة للخدمة هي:

POST https://whats360.live/api/v1/sms/send

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

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

مثال PHP لإرسال رسالة عبر API

يمكن لمطور PHP استخدام طلب HTTP من خلال cURL لإرسال البيانات إلى Endpoint. المثال التالي توضيحي فقط، ويستخدم معرفات عامة بدل مفاتيح حقيقية.

<?php

$apiToken = 'WHATS360_API_TOKEN';
$deviceId = 'WHATS360_DEVICE_ID';

$data = [
    'device_id' => $deviceId,
    'phone'     => '201000000000',
    'message'   => 'رمز التحقق الخاص بك هو: 123456'
];

$ch = curl_init('https://whats360.live/api/v1/sms/send');

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $apiToken
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);

echo $response;
?>

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

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

كيف يمكن استخدام SMS API في مواقع PHP؟

PHP مناسبة لهذا النوع من التكامل لأن الموقع يستطيع تنفيذ طلبات HTTP إلى خدمات خارجية. وبالتالي يمكن ربط SMS API مع الوظائف الموجودة بالفعل في الموقع.

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

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

استخدام SMS API مع WordPress

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

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

في مشاريع WordPress، من الأفضل عدم وضع Token مباشرة داخل ملفات الإضافة إذا كان بالإمكان تخزينه في إعدادات مناسبة. كما ينبغي توفير صفحة إعدادات تسمح للمسؤول بإدخال معرف الجهاز والبيانات المطلوبة بدل تعديل ملفات PHP يدويًا.

إرسال أكواد OTP عبر SMS API

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

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

إرسال تنبيهات الطلبات من المتجر

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

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

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

مقارنة بين الإرسال اليدوي والإرسال عبر API

لماذا يحتاج المطور إلى Device ID؟

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

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

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

كيف تربط الهاتف بمنصة SMS Gateway؟

وفق الآلية الموضحة للخدمة، يبدأ المطور أو المستخدم بتحميل تطبيق SMS Gateway على هاتف Android، ثم ربط الهاتف بالمنصة باستخدام QR Code. بعد اكتمال الربط يصبح الهاتف هو بوابة الإرسال التي تستخدم شريحة الاتصال الموجودة داخله.

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

هل يمكن استخدام API مع أي مشروع PHP؟

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

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

هذا التصميم يجعل المشروع أكثر تنظيمًا، ويتيح للمطور تعديل طريقة الاتصال مستقبلًا دون تغيير كل الأماكن التي تستدعي إرسال SMS.

هل يمكن ربط WordPress دون تعديل النظام بالكامل؟

في كثير من حالات WordPress يمكن بناء التكامل داخل إضافة أو طبقة مخصصة بدل تعديل الملفات الأساسية للنظام. هذه الطريقة أفضل من تعديل Core WordPress لأن التحديثات المستقبلية قد تستبدل الملفات المعدلة.

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

ما الذي يجب تسجيله عند إرسال الرسائل؟

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

عند التعامل مع OTP، ينبغي الانتباه بصورة خاصة إلى عدم تسجيل رموز التحقق نفسها في سجلات يمكن الوصول إليها بسهولة.

كيف تتعامل مع أخطاء API؟

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

يمكن تقسيم التعامل مع الأخطاء إلى مستويات: خطأ في بيانات المصادقة، خطأ في Device ID، خطأ في رقم الهاتف، خطأ في البيانات المطلوبة، أو مشكلة اتصال مؤقتة. ويجب أن يتعامل التطبيق مع كل حالة وفق طبيعتها.

كيف تصمم التكامل بطريقة قابلة للتوسع؟

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

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

Application Event
        |
        v
    SmsService
        |
        v
    SMS API
        |
        v
 Android Gateway
        |
        v
    Recipient

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

هل SMS Gateway مناسبة للـOTP فقط؟

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

الفرق المهم هو أن API لا تحدد وحدها نوع الرسالة. التطبيق هو الذي يقرر متى يتم الإرسال ولماذا، بينما تقوم بوابة SMS بتنفيذ طلب الإرسال وفق البيانات التي يقدمها النظام.

ماذا عن تكلفة الخدمة؟

السعر المذكور ضمن المعلومات المتاحة للخدمة هو أن هناك باقات تبدأ من 350 جنيهًا شهريًا تسمح بربط جهازين وإرسال حتى 5,000 رسالة. هذه المعلومة مرتبطة بالبيانات المتاحة في سياق الخدمة، ولذلك يُفضل التحقق من صفحة الأسعار أو الحساب قبل اتخاذ قرار شراء، لأن الأسعار والباقات قد تتغير.

ما الفرق بين API وبين إرسال SMS يدويًا؟

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

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

ما الذي يحتاجه المطور قبل البدء؟

• مشروع PHP أو WordPress يمكنه تنفيذ طلبات HTTP.
• حساب في Whats360 وفق الخدمة المستخدمة.
• جهاز Android يتم ربطه بالمنصة.
• شريحة اتصال مناسبة للإرسال.
• معرف الجهاز Device ID.
• بيانات المصادقة الخاصة بالـAPI.
• رقم مستلم للاختبار.
• بيئة اختبار قبل تشغيل التكامل على النظام الإنتاجي.

Workflow عملي لربط SMS بالموقع

يمكن النظر إلى التكامل باعتباره Workflow بسيطًا يبدأ من الحدث وينتهي بتسجيل النتيجة. هذا الأسلوب يساعد المطور على فهم مكان وضع الكود داخل المشروع.

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

ما الأخطاء التي يجب تجنبها في تكامل SMS API؟

الخطأ الأول هو وضع مفتاح API الحقيقي داخل الكود المنشور. هذا قد يعرض حساب الخدمة للاستخدام غير المصرح به. استخدم دائمًا معرفًا مثل WHATS360_API_TOKEN في الأمثلة العامة.

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

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

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

هل يحتاج المشروع إلى إضافة WordPress مخصصة؟

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

المهم أن يكون التصميم مناسبًا للمشروع بدل بناء نظام أكبر من الحاجة. الهدف من API هو تسهيل التكامل، وليس تحويل عملية إرسال الرسالة إلى مشروع منفصل دون داعٍ.

كيف تبدأ اختبار التكامل؟

ابدأ دائمًا ببيئة اختبار ورقم مخصص للاختبار. لا تبدأ بإرسال رسائل إلى قاعدة العملاء مباشرة قبل التأكد من أن الطلب البرمجي يعمل وأن البيانات صحيحة.

اختبر حالة النجاح، وحالة بيانات المصادقة غير الصحيحة، وحالة Device ID غير الصحيح، وحالة الرقم غير المناسب، وحالة فشل الاتصال. كما اختبر ما يحدث عندما تكون الخدمة غير متاحة مؤقتًا.

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

هل SMS Gateway مناسبة لكل مشروع؟

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

أما قرار استخدام الخدمة في مشروع فعلي فيجب أن يعتمد على المتطلبات الفنية الفعلية، وحجم الرسائل، وطريقة التشغيل المطلوبة، والباقات المتاحة وقت التنفيذ.

أسئلة شائعة حول SMS API لمواقع PHP وWordPress

الخلاصة

إرسال رسائل SMS برمجيًا من مواقع PHP وWordPress لا يحتاج بالضرورة إلى بناء منظومة رسائل من الصفر. يمكن استخدام SMS Gateway API كطبقة تربط الموقع بخدمة الإرسال، بحيث يرسل النظام طلبًا برمجيًا عند حدوث الحدث المطلوب.

في النموذج الموضح هنا، يتم ربط جهاز Android بمنصة Whats360، ثم يستخدم الموقع Endpoint الخاص بـSMS لإرسال البيانات اللازمة. ويمكن توظيف هذا الأسلوب في OTP وتنبيهات الطلبات والإشعارات المرتبطة بالأحداث البرمجية.

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

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

التسويق الإلكتروني

التجارة الإلكترونية

التسويق بالعمولة

الكلمات المفتاحية

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