كيفية اختبار الرسائل النصية القصيرة بعد إعداد Webhook: دليل خطوة بخطوة

يتطلب إعداد إشعارات فورية لعملك — سواء كنت ترسل تأكيدات مواعيد لعيادة أو تحديثات طلبات لورشة إصلاح — طريقة موثوقة لتتبع حالة التسليم. بمجرد إعداد عنوان URL الخاص بالرد التلقائي (callback URL)، فإن معرفة كيفية اختبار sms بمجرد تكوين webhook هي الخطوة التالية الحاسمة لضمان معالجة نظامك لتقارير التسليم والرسائل الواردة بسلاسة.

الخطوة 1: إعداد مستمع Webhook محلي

قبل أن تتمكن من اختبار كيفية تعامل نظامك مع تقارير تسليم الرسائل النصية القصيرة، فأنت بحاجة إلى عنوان URL عام يمكنه استقبال طلبات HTTP POST من بوابة الرسائل النصية. إذا كنت تقوم بالتطوير محلياً، فإن خادمك الذي يعمل على localhost:3000 لا يمكن الوصول إليه عبر الإنترنت المفتوح. لسد هذه الفجوة، يمكنك استخدام أدوات الأنفاق المحلية مثل ngrok، أو LocalTunnel، أو أدوات اختبار الويب هوك عبر الإنترنت مثل Webhook.site.

لإجراء اختبار سريع بدون تكوين معقد، نوصي بشدة بـ Webhook.site. فهو ينشئ عنوان URL عاماً فريداً ومؤقتاً حيث يمكنك مشاهدة البيانات الواردة في الوقت الفعلي. إذا كنت تفضل الاختبار مباشرة مقابل تطبيقك المحلي، فقم بتشغيل ngrok لفتح المنفذ المحلي الخاص بك:

ngrok http 3000

سيقوم هذا الأمر بإنشاء عنوان URL لإعادة التوجيه HTTPS عام (على سبيل المثال، https://your-subdomain.ngrok-free.app). ستقوم بإضافة مسار الويب هوك الخاص بك إلى هذا العنوان — على سبيل المثال، https://your-subdomain.ngrok-free.app/webhooks/sms — واستخدامه كنقطة نهاية للويب هوك.

كتابة مستقبل Webhook بسيط باستخدام Express.js

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

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

app.post('/webhooks/sms', (req, res) => {
  console.log('Received Webhook Payload:', JSON.stringify(req.body, null, 2));
  // Always return a 200 OK status quickly to acknowledge receipt
  res.status(200).send({ status: 'success' });
});

app.listen(3000, () => console.log('Webhook receiver listening on port 3000'));

الخطوة 2: تكوين عنوان URL للـ Webhook في بوابة الرسائل النصية

بمجرد حصولك على عنوان URL العام للويب هوك، يجب عليك تسجيله في لوحة تحكم بوابة الرسائل النصية الخاصة بك. على عكس المزودين التقليديين مثل Twilio أو Vonage، الذين يتطلبون تسجيلاً معقداً لـ A2P 10DLC، والتحقق من ملف تعريف الأعمال، والموافقة على الحملات قبل أن تتمكن حتى من إرسال رسالة اختبار، يتيح لك MySMSGate توصيل هاتف Android الخاص بك عبر رمز QR بسيط وبدء الاختبار فوراً.

لتكوين الويب هوك الخاص بك في MySMSGate:

1. قم بتسجيل الدخول إلى لوحة التحكم الخاصة بك في MySMSGate.
2. انتقل إلى إعدادات API أو لوحة تكامل المطورين (Developer Integration).
3. قم بلصق عنوان URL الخاص بالويب هوك (على سبيل المثال، عنوان Webhook.site أو عنوان ngrok الخاص بك) في حقل "Webhook URL".
4. اختر الأحداث التي تريد الاشتراك فيها (على سبيل المثال، sms.sent، sms.delivered، sms.failed، أو sms.received).
5. احفظ إعداداتك.

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

الخطوة 3: إرسال رسالة نصية تجريبية للتحقق من وصول الـ Webhook

الطريقة الأكثر موثوقية لاختبار الويب هوك هي إرسال رسالة نصية قصيرة فعلية. مع MySMSGate، لست بحاجة لشراء أرقام افتراضية أو إعداد بيئة تجريبية (sandbox). ولأن المنصة تحول هاتف Android الخاص بك إلى بوابة رسائل نصية، يمكنك إرسال رسائل حقيقية عبر شريحة SIM الخاصة بك إلى رقم هاتفك المحمول للاختبار.

يمكنك إرسال رسالة اختبار مباشرة من لوحة تحكم الويب باستخدام واجهة Web Conversations، أو برمجياً عبر REST API البسيط الخاص بنا. إليك مثال باستخدام curl لإرسال رسالة اختبار:

curl -X POST https://mysmsgate.net/api/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+1234567890",
    "message": "Webhook test message from MySMSGate",
    "sim_slot": 1
  }'

بعد تشغيل هذا الطلب، سيقوم هاتف Android المتصل بإرسال الرسالة فوراً عبر شريحة SIM الخاصة به. ومع انتقال حالة الرسالة من "قيد الانتظار" (pending) إلى "تم الإرسال" (sent) وأخيراً "تم التسليم" (delivered)، سيقوم MySMSGate بإرسال طلبات HTTP POST إلى عنوان URL الخاص بالويب هوك الذي قمت بتكوينه.

الخطوة 4: فحص بيانات حالة التسليم

بمجرد إرسال الرسالة التجريبية، تحقق من مستمع الويب هوك الخاص بك (مثل Webhook.site أو محطة الأوامر المحلية التي تشغل ngrok). يجب أن ترى طلب HTTP POST وارداً. يعد فحص هذه البيانات جزءاً حاسماً من تعلم كيفية اختبار sms بمجرد تكوين webhook.

تبدو بيانات الويب هوك النموذجية لحالة التسليم من MySMSGate كالتالي:

{
  "event": "sms.status_changed",
  "message_id": "msg_8f7d6e5c4b3a",
  "to": "+1234567890",
  "status": "delivered",
  "sim_slot": 1,
  "device_id": "dev_android_01",
  "timestamp": "2026-08-05T14:32:01.000Z",
  "error_code": null
}

عند تحليل هذه البيانات، تحقق من الحقول التالية:

• message_id: يتطابق مع المعرف الذي تم إرجاعه بواسطة استدعاء API الأولي.
• status: يؤكد ما إذا كانت الرسالة قد تم إرسالها أو تسليمها بنجاح.
• sim_slot: يحدد شريحة SIM التي تم استخدامها (مفيد بشكل خاص لهواتف Android ثنائية الشريحة).
• error_code: إذا كانت الحالة هي "فشل" (failed)، فسيحتوي هذا الحقل على السبب (مثلاً، لا توجد إشارة، نفاد الرصيد).

الخطوة 5: اختبار الحالات الاستثنائية وإعادة المحاولة

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

1. محاكاة فشل التسليم: أرسل رسالة نصية إلى رقم هاتف غير صالح أو مفصول. راقب بيانات الويب هوك. يجب أن تتحدث الحالة status إلى failed، ويتم ملء error_code. في MySMSGate، يتم استرداد تكلفة أي رسالة نصية فاشلة تلقائياً إلى رصيد حسابك، وهو ما يمكنك التحقق منه في لوحة التحكم.
2. محاكاة توقف الخادم: قم بإيقاف تشغيل خادم استقبال الويب هوك المحلي مؤقتاً وأرسل رسالة نصية. ستقوم بوابة الرسائل النصية الجيدة بوضع تقارير التسليم في قائمة الانتظار وإعادة محاولة إرسالها إذا أرجع خادمك خطأ 5xx أو انتهت مهلة الطلب. تحقق من أن البوابة تعيد محاولة تسليم الويب هوك بمجرد إعادة تشغيل خادمك.
3. التعامل مع الويب هوك المتكرر: في سيناريوهات الشبكة النادرة، قد يتلقى خادمك نفس حدث الويب هوك مرتين. تأكد من أن كود الواجهة الخلفية الخاص بك "idempotent" — مما يعني أنه يتحقق مما إذا كانت حالة message_id قد تم تحديثها بالفعل في قاعدة بياناتك قبل تشغيل أي منطق عمل (مثل إرسال بريد إلكتروني للمتابعة أو تحديث سجل العميل).

مقارنة بيئات اختبار الويب هوك لبوابات الرسائل النصية

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

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

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

الأسئلة الشائعة

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

كيف يمكنني التحقق مما إذا كانت نقطة نهاية الويب هوك الخاصة بي تتلقى حالات تسليم الرسائل؟

يمكنك التحقق من ذلك من خلال مراجعة سجلات الخادم الخاص بك أو استخدام أداة مثل Webhook.site. عند إرسال رسالة نصية، ترسل البوابة طلب HTTP POST إلى عنوان URL الخاص بك. إذا أظهرت سجلات خادمك طلب POST وارداً مع رمز استجابة 200 OK، فهذا يعني أن نقطة النهاية تتلقى حالات التسليم بنجاح.

ما هي الأدوات التي يجب استخدامها لاختبار الويب هوك محلياً؟

أفضل الأدوات لاختبار الويب هوك محلياً هي ngrok (لفتح خادمك المحلي للإنترنت عبر نفق آمن) و Webhook.site (لفحص بيانات JSON الخام بسرعة دون كتابة أي كود). كلتا الأداتين مجانيتان ومستخدمتان على نطاق واسع من قبل المطورين.

لماذا يرجع الويب هوك الخاص بي خطأ 500 أثناء الاختبار؟

يعني خطأ الخادم الداخلي 500 أن كود استقبال الويب هوك الخاص بك قد تعطل أو واجه خطأ أثناء معالجة البيانات الواردة. تحقق من سجلات الخادم الخلفي للعثور على تتبع الخطأ (stack trace). تأكد من أن الكود الخاص بك يقوم بتحليل جسم JSON بشكل صحيح وإرجاع استجابة 200 OK بسرعة، قبل إجراء أي عمليات قاعدة بيانات تستغرق وقتاً طويلاً.

كيف يتعامل MySMSGate مع إعادة محاولة الويب هوك إذا تعطل خادمي؟

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