الگوها و پارامترها
الگو قالب پیامک است. متن الگو در جایگاههای متغیر علامت @ دارد و هر @ به ترتیب با یکی از پارامترهای الگو جایگزین میشود. برای مثال الگویی با متن @ عزیز، کد شما @ است. دو پارامتر دارد: اولی نام و دومی کد.
ویژگیهای هر پارامتر
هر پارامتر در الگو با ویژگیهای زیر تعریف میشود:
| ویژگی | معنا |
|---|---|
key | شناسهی پارامتر که در درخواست ارسال استفاده میشود |
name | عنوان فارسی پارامتر برای نمایش در پنل |
optional | اختیاری بودن پارامتر |
optionText | متنی که در صورت وجود مقدار، همراه آن درج میشود |
optionPlacement | محل متن همراه: 0 قبل از مقدار، 1 بعد از مقدار |
maxLength | حداکثر طول مقدار (پیشفرض ۵۰ کاراکتر) |
regexPattern | مجموعهی نویسههای مجاز برای مقدار |
پارامتر اجباری و اختیاری
اگر پارامتری اجباری باشد و مقدار آن ارسال نشود، درخواست با خطای «پارامتر اجباری مقدار ندارد» (کد 5003) رد میشود. پارامتر اختیاری را میتوان کاملاً حذف کرد یا خالی فرستاد؛ در این حالت جایگاه آن در متن پیامک چیزی درج نمیشود.
مقدار قبل و بعد از مقدار
برای پارامترهای اختیاری میتوان متن همراه تعریف کرد که فقط هنگام وجود مقدار درج شود. فرض کنید پارامتر discount اختیاری است، optionText آن «تخفیف » و optionPlacement آن 0 است:
- با مقدار
20، عبارتتخفیف 20در پیامک درج میشود. - بدون مقدار، هیچ چیزی درج نمیشود و عبارت «تخفیف» هم ظاهر نمیگردد.
اگر optionPlacement برابر 1 باشد، متن همراه پس از مقدار میآید (مانند 20 درصد).
پارامترهای ثابت
برخی مقادیر در همهی پیامهای شما یکساناند؛ مانند نام برند یا آدرس سایت. این مقادیر را یک بار در بخش اطلاعات برند ثبت میکنید و اگر کلید پارامتر الگو با کلید مقدار ثابت یکی باشد، سامانه هنگام ارسال آن را خودکار جایگزین میکند و دیگر لازم نیست در درخواست بفرستید. فهرست مقادیر ثابت شما از طریق مقادیر ثابت قابل دریافت است.
پارامترهای داینامیک
پارامترهایی که کلید آنها با Dy_ شروع میشود را خود سامانه در لحظهی ارسال مقداردهی میکند و نباید در درخواست ارسال شوند:
| کلید | مقدار |
|---|---|
Dy_PersianShortDateString | تاریخ کوتاه شمسی |
Dy_PersianLongDateString | تاریخ شمسی بلند، مانند «سهشنبه ۳۰ تیر ۱۴۰۳» |
Dy_PersianDateTime | تاریخ و ساعت کامل شمسی |
Dy_PersianShortTimeString | ساعت کوتاه شمسی |
Dy_Time / Dy_TimeWithSeconds | ساعت جاری بهصورت ۲۴ ساعته، بدون ثانیه / با ثانیه |
Dy_PersianYear / Dy_PersianMonthName / Dy_PersianDayOfWeek | سال، نام ماه و نام روز هفته به شمسی |
Dy_Year / Dy_GregorianDate | سال میلادی و تاریخ میلادی با قالب yyyy-MM-dd |
Dy_UnixTimestamp | زمان جاری بهصورت Unix Timestamp (ثانیه) |
Dy_Guid / Dy_ShortGuid | شناسهی تصادفی کامل / کوتاه (۸ کاراکتر) |
Dy_Otp4 / Dy_Otp6 | کد تصادفی ۴ یا ۶ رقمی |
Dy_RandomInt100 | عدد تصادفی بین ۱ تا ۱۰۰ |
در ساخت کمپین، پارامترهای Dy_ پشتیبانی نمیشوند. برای کمپینها از مقدار ثابت یا فیلد مخاطب استفاده کنید.
طول مجاز
اگر طول مقدار از maxLength بیشتر باشد، درخواست با خطای «طول مقدار پارامتر از حد مجاز بیشتر است» (کد 5002) رد میشود.
محدودکردن نویسهها با regex
ویژگی regexPattern مجموعهی نویسههای مجاز را تعیین میکند، نه یک الگوی تطبیق کامل. نویسههایی از مقدار که در این مجموعه نباشند حذف میشوند و پیام با مقدار پاکسازیشده ادامه مییابد. مثلاً با مقدار 0-9، ورودی 20% به 20 تبدیل میشود. پاکسازی پیش از بررسی طول و اجباریبودن انجام میگیرد؛ بنابراین مقداری که پس از پاکسازی خالی شود، برای پارامتر اجباری خطا میدهد.
دریافت الگوها از وبسرویس
فهرست الگوهای مجاز شما، گروههای آنها و پارامترهای هر الگو از طریق الگوها و گروههای الگو در دسترس است.