پرش به مطلب اصلی

الگوها و پارامترها

الگو قالب پیامک است. متن الگو در جایگاه‌های متغیر علامت @ دارد و هر @ به ترتیب با یکی از پارامترهای الگو جایگزین می‌شود. برای مثال الگویی با متن @ عزیز، کد شما @ است. دو پارامتر دارد: اولی نام و دومی کد.

ویژگی‌های هر پارامتر​

هر پارامتر در الگو با ویژگی‌های زیر تعریف می‌شود:

ویژگیمعنا
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 تبدیل می‌شود. پاک‌سازی پیش از بررسی طول و اجباری‌بودن انجام می‌گیرد؛ بنابراین مقداری که پس از پاک‌سازی خالی شود، برای پارامتر اجباری خطا می‌دهد.

دریافت الگوها از وب‌سرویس​

فهرست الگوهای مجاز شما، گروه‌های آن‌ها و پارامترهای هر الگو از طریق الگوها و گروه‌های الگو در دسترس است.