إعداد بوابة مخصصة

يتيح لك WSMS دمج أي مزود SMS يعتمد على HTTP وغير موجود في مكتبة البوابات المدمجة. تدعم البوابة المخصصة كلاً من واجهات API المسطحة بصيغة مفتاح-قيمة (?to=...&message=...) وواجهات JSON الحديثة بأسلوب Postman (مع كائنات متداخلة أو مصفوفات مثل recipients: ["+31..."]).

الخطوة 1: اختر البوابة المخصصة

1. انتقل إلى WSMS ← الإعدادات ← البوابة
2. من القائمة المنسدلة للبوابة، اختر Custom
3. تظهر الحقول الخاصة بالمزود في الأسفل بمجرد اختيار Custom

الخطوة 2: عنوان URL لإرسال SMS

أدخل عنوان URL الكامل الذي قدمه لك المزود، على سبيل المثال:

https://api.example.com/v1/send

الخطوة 3: ترويسات HTTP

أضف ترويسة واحدة بصيغة Header-Name: value في كل سطر. تحتاج معظم واجهات JSON إلى نوع المحتوى ورمز التفويض:

Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

تُرسل أسطر الترويسات كما هي تماماً. تأكد من أن كل ترويسة في سطر منفصل وأن قيمتها تتضمن البادئة الكاملة (Bearer أو Basic أو Token …) التي يتوقعها المزود.

الخطوة 4: تنسيق الجسم (Body Format)

اختر كيف يبني WSMS جسم الطلب:

الوضع	متى يُستخدم
Key-Value	عندما يقبل المزود معاملات key=value المسطحة، إما كسلسلة استعلام أو كجسم JSON بسيط
Raw JSON	عندما يتوقع المزود حمولة JSON كاملة بأسلوب Postman، خاصة مع الكائنات المتداخلة أو المصفوفات مثل recipients: ["+31..."]

تعتمد الحقول المعروضة أدناه على الوضع الذي تختاره.

الخطوة 5-أ: تكوين وضع Key-Value

في حقل معاملات HTTP، اكتب key:value واحداً في كل سطر. يستبدل WSMS العناصر النائبة التالية بالقيم الفعلية وقت الإرسال:

العنصر النائب	يُستبدل بـ
{from}	معرف المرسل المُعد في حقل Sender Name
{to}	رقم/أرقام هاتف المستلم، مفصولة بفواصل
{message}	نص الرسالة القصيرة

مثال:

to:{to}
message:{message}
sender:{from}

إرسال قيمة كمصفوفة JSON. ضع القيمة بين قوسين مربعين لإرسالها كمصفوفة JSON (تُقسم بفواصل وتُزال المسافات حول كل عنصر):

recipients:[{to}]
tags:[otp,verify]

الإرسال كـ POST. اضبطه على Yes لإرسال المعاملات كجسم JSON، أو No لإلحاقها بعنوان URL كمعاملات استعلام (GET).

الخطوة 5-ب: تكوين وضع Raw JSON

في حقل Request Body (JSON)، الصق حمولة JSON الكاملة كما يوثقها المزود تماماً. يستبدل WSMS العناصر النائبة التالية داخل الحمولة وقت الإرسال:

العنصر النائب	يُستبدل بـ
{from}	معرف المرسل المُعد في حقل Sender Name
{to}	رقم/أرقام هاتف المستلم كسلسلة مفصولة بفواصل
{message}	نص الرسالة القصيرة (مع escape مخصص لـ JSON)
{recipients}	رقم/أرقام هاتف المستلم كقائمة من سلاسل JSON مفصولة بفواصل، جاهزة للوضع داخل مصفوفة

تمر أي مفاتيح أخرى في JSON دون تغيير، لذا يمكنك إضافة الحقول الخاصة بالمزود (route، callback_url، reference …).

مثال على حمولة لواجهة API تتطلب مصفوفة recipients:

{
  "body": "{message}",
  "originator": "{from}",
  "recipients": [{recipients}],
  "route": "business",
  "reference": "wsms-order-42"
}

يُرسل وضع Raw JSON دائماً كـ POST، ولا يؤثر مفتاح Send As POST عليه.

الخطوة 6: ترميز الرسالة (Encode Message)

الإعداد	متى يُستخدم
No (مُوصى به لواجهات JSON)	يقبل المزود الرسالة كنص عادي. تمر المسافات والنقطتان وحروف Unicode دون تغيير
Yes	المزود نقطة نهاية قديمة بصيغة GET / form-encoded تتوقع نص الرسالة بترميز URL

إذا فعّلت هذا الخيار مع واجهة API بصيغة JSON، فستصل الرسالة بترميز URL (تتحول المسافات إلى +، وتتحول : إلى %3A …). اتركه على No ما لم يطلب المزود صراحةً نص رسالة بترميز URL.

الخطوة 7: اسم المرسل (Sender Name)

أدخل معرف المرسل الذي يجب أن يظهر على هاتف المستلم. تُستخدم هذه القيمة في كل مكان كتبت فيه العنصر النائب {from}.

تفرض معظم المزودات قيوداً على هذا الحقل. القواعد الشائعة:

• معرف مرسل أبجدي-رقمي: عادةً 11 حرفاً كحد أقصى، بدون مسافات أو رموز
• معرف مرسل رقمي: عادةً 14 رقماً كحد أقصى

إذا رفض المزود رسائلك بخطأ مثل “originator must be a valid format”، فتحقق أولاً من تنسيق sender ID المسموح به في وثائق المزود.

الخطوة 8: الحفظ والاختبار

1. انقر على Save Changes
2. انتقل إلى WSMS ← Send SMS
3. أرسل رسالة اختبارية للتحقق من التكوين

مشاكل شائعة

• The recipients must be an array - بدّل Body Format إلى Raw JSON واستخدم [{recipients}] داخل حمولة JSON، أو في وضع Key-Value استخدم recipients:[{to}]
• تصل الرسالة بـ + بدلاً من المسافات أو %3A بدلاً من : - اضبط Encode Message على No
• The originator must be a valid format - قصّر Sender Name إلى الحد الذي يسمح به المزود (غالباً 11 حرفاً أبجدي-رقمي)
• تُقسم الترويسات بشكل خاطئ - تأكد من أن كل ترويسة في سطر منفصل وأن قيمتها تتضمن البادئة الكاملة (مثل Bearer قبل الرمز)

حالات الاستخدام

• مقدمو خدمات SMS إقليميون غير موجودين في القائمة الافتراضية
• بوابات SMS خاصة أو مؤسسية
• واجهات JSON / REST الحديثة التي تتطلب حمولات متداخلة (Spryng، MessageBird، واجهات API داخلية مخصصة)

ذات صلة

• تكوين البوابة - إعداد البوابة القياسي