راه‌اندازی درگاه سفارشی

WSMS به شما امکان می‌دهد هر ارائه‌دهنده SMS مبتنی بر HTTP را که در کتابخانه پیش‌فرض درگاه‌ها وجود ندارد، یکپارچه کنید. درگاه سفارشی هم از APIهای ساده کلید-مقدار (?to=...&message=...) و هم از APIهای مدرن سبک Postman با JSON (شامل اشیاء تو در تو یا آرایه‌هایی مانند recipients: ["+31..."]) پشتیبانی می‌کند.

مرحله 1: انتخاب درگاه سفارشی

1. به WSMS ← تنظیمات ← درگاه بروید
2. از منوی کشویی درگاه، Custom را انتخاب کنید
3. پس از انتخاب Custom، فیلدهای مخصوص ارائه‌دهنده در پایین ظاهر می‌شوند

مرحله 2: آدرس API ارسال SMS

آدرس کامل اندپوینتی که ارائه‌دهنده در اختیار شما گذاشته را وارد کنید، برای مثال:

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

مرحله 3: هدرهای HTTP

در هر خط یک Header-Name: value اضافه کنید. اکثر APIهای JSON به یک نوع محتوا و یک توکن احراز هویت نیاز دارند:

Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

خطوط هدر دقیقاً همان‌طور که نوشته می‌شوند ارسال می‌گردند. مطمئن شوید هر هدر در یک خط جدا قرار دارد و مقدار آن شامل پیشوند کاملی (مانند Bearer ، Basic ، Token و …) است که ارائه‌دهنده انتظار دارد.

مرحله 4: قالب بدنه (Body Format)

نحوه ساخته شدن بدنه درخواست توسط WSMS را انتخاب کنید:

حالت	چه زمانی استفاده شود
Key-Value	ارائه‌دهنده پارامترهای ساده key=value را می‌پذیرد، چه به صورت Query String و چه به صورت بدنه JSON ساده
Raw JSON	ارائه‌دهنده یک Payload کامل JSON سبک Postman را انتظار دارد، به‌خصوص با اشیاء تو در تو یا آرایه‌هایی مانند recipients: ["+31..."]

فیلدهایی که در ادامه نمایش داده می‌شوند، به حالتی که انتخاب می‌کنید بستگی دارند.

مرحله 5-الف: پیکربندی حالت Key-Value

در فیلد پارامترهای HTTP، در هر خط یک key:value بنویسید. WSMS هنگام ارسال، جایگزین‌های زیر را با مقادیر واقعی جایگزین می‌کند:

جایگزین	جایگزین می‌شود با
{from}	شناسه فرستنده پیکربندی شده در فیلد Sender Name
{to}	شماره(های) تلفن گیرنده، جدا شده با کاما
{message}	متن SMS

مثال:

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

ارسال یک مقدار به صورت آرایه JSON. مقدار را داخل کروشه قرار دهید تا به صورت آرایه JSON ارسال شود (با کاما جدا و اطراف هر مقدار trim می‌شود):

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

Send As POST. مقدار Yes پارامترها را به صورت بدنه JSON می‌فرستد و No آن‌ها را به صورت پارامترهای Query در URL ضمیمه می‌کند (GET).

مرحله 5-ب: پیکربندی حالت Raw JSON

در فیلد Request Body (JSON)، Payload کامل JSON را دقیقاً همان‌طور که ارائه‌دهنده مستند کرده است Paste کنید. WSMS جایگزین‌های زیر را داخل Payload در زمان ارسال جایگزین می‌کند:

جایگزین	جایگزین می‌شود با
{from}	شناسه فرستنده پیکربندی شده در فیلد Sender Name
{to}	شماره(های) تلفن گیرنده به صورت رشته جدا شده با کاما
{message}	متن SMS (با escape مخصوص JSON)
{recipients}	شماره(های) تلفن گیرنده به صورت لیست JSON String جدا شده با کاما، آماده قرار گرفتن داخل یک آرایه

هر کلید دیگری در JSON بدون تغییر ارسال می‌شود، بنابراین می‌توانید فیلدهای مخصوص ارائه‌دهنده را اضافه کنید (route، callback_url، reference و …).

نمونه Payload برای APIای که به آرایه recipients نیاز دارد:

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

حالت Raw JSON همیشه به صورت POST ارسال می‌شود و کلید Send As POST تأثیری ندارد.

مرحله 6: رمزگذاری پیام (Encode Message)

تنظیم	چه زمانی استفاده شود
No (پیشنهاد می‌شود برای APIهای JSON)	ارائه‌دهنده پیام را به صورت متن ساده می‌پذیرد. فاصله، دو نقطه و کاراکترهای Unicode بدون تغییر ارسال می‌شوند
Yes	ارائه‌دهنده یک اندپوینت قدیمی GET / form-encoded است که انتظار پیام URL-encode شده را دارد

اگر این گزینه را برای یک API JSON روشن کنید، متن SMS با کاراکترهای URL-encode شده می‌رسد (فاصله به +، : به %3A و …). تا زمانی که ارائه‌دهنده شما به صراحت متن URL-encode شده را نخواهد، آن را روی No بگذارید.

مرحله 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 تغییر دهید و در Payload از [{recipients}] استفاده کنید، یا در حالت Key-Value از recipients:[{to}] استفاده کنید
• پیام با + به جای فاصله یا %3A به جای : می‌رسد - گزینه Encode Message را روی No قرار دهید
• The originator must be a valid format - مقدار Sender Name را به محدوده مجاز ارائه‌دهنده کاهش دهید (معمولاً 11 کاراکتر الفبا-عددی)
• هدرها به اشتباه تفکیک می‌شوند - مطمئن شوید هر هدر در یک خط جداگانه است و مقدار آن شامل پیشوند کامل (مانند Bearer قبل از توکن) است

موارد استفاده

• ارائه‌دهندگان SMS منطقه‌ای که در لیست پیش‌فرض نیستند
• درگاه‌های SMS خصوصی یا سازمانی
• APIهای مدرن JSON / REST که به Payloadهای تو در تو نیاز دارند (Spryng، MessageBird، APIهای داخلی سفارشی)

مرتبط

• پیکربندی درگاه - راه‌اندازی استاندارد درگاه