این راهنما مسیر کامل استفاده از افزونه پیامک بوکلیو را توضیح می‌دهد: از نصب و فعال‌سازی افزونه تا انتخاب درگاه، تنظیم وندور، ساخت فید پیامکی در فرم رزرو، بررسی لاگ‌ها و رسیدن به یک سناریوی عملی مثل ارسال پیامک بعد از تایید رزرو.
این افزونه دقیقا چه کاری انجام می‌دهد
افزونه پیامک بوکلیو برای Gravity Forms یک ادآن مستقل برای گرویتی‌فرمز است. این افزونه دو نقش اصلی دارد:
- ارسال پیامک از طریق Feedهای گرویتی‌فرمز
- گوش‌دادن به رویدادهای رزرو بوکلیو مثل ایجاد رزرو، تایید رزرو، لغو رزرو، تغییر زمان و رزرو پیش‌رو
به زبان ساده، خود فرم و رویدادهای رزرو را از بوکلیو می‌گیرد، اما ارسال پیامک را در زیرساخت افزونه پیامک انجام می‌دهد.
پیش‌نیازها قبل از شروع
- وردپرس فعال
- افزونه Gravity Forms فعال
- افزونه بوکلیو فعال، اگر می‌خواهید رویدادهای رزرو بوکلیو را به پیامک وصل کنید
- یک حساب فعال در یکی از درگاه‌های پیامکی پشتیبانی‌شده
- یک فرم رزرو که فیلد رزرو بوکلیو و ترجیحا فیلد موبایل داشته باشد
روش نصب و فعال‌سازی
از روی کد محصول، دو مسیر عملی برای نصب دیده می‌شود:
- نصب به‌عنوان پیش‌نیاز پیشنهادی از مسیر onboarding بوکلیو، اگر بسته نصب از سمت سرور یا تنظیمات داخلی آماده شده باشد
- نصب دستی افزونه و سپس فعال‌سازی آن از بخش افزونه‌های وردپرس
بعد از فعال‌سازی، ادآن پیامک بوکلیو در محیط گرویتی‌فرمز ثبت می‌شود و صفحه تنظیمات و صفحه لاگ آن در همان اکوسیستم Gravity Forms در دسترس قرار می‌گیرد.
بعد از فعال‌سازی، تنظیمات اصلی کجاست
تنظیمات سراسری افزونه از صفحه تنظیمات گرویتی‌فرمز در زیرنمای booklio-gravity-sms باز می‌شود. عنوان این صفحه در رابط کاربری پیکربندی پیامک بوکلیو است.
در این صفحه اول باید درگاه فعال را انتخاب کنید. هر ارسال پیامکی که در Feed خودش override نداشته باشد، از همین درگاه استفاده می‌کند.
درگاه فعال و سرویس پیامکی را چطور انتخاب کنیم
در کد فعلی، افزونه یک فهرست بزرگ از وندورها و درگاه‌های پیامکی را پشتیبانی می‌کند. از جمله IPPanel، کاوه‌نگار، SMS.ir، FarazSMS، Ghasedak، ParsGreen، MeliPayamak و وندورهای متعدد دیگر.
در رابط کاربری چیزی به نام «ایجاد وندور سفارشی» دیده نمی‌شود. مسیر واقعی کار این است که از لیست درگاه فعال یکی از وندورهای موجود را انتخاب کنید؛ بعد از انتخاب، فقط فیلدهای مربوط به همان درگاه نمایش داده می‌شود.
- بعضی درگاه‌ها فقط
API Keyوشماره فرستندهمیخواهند - بعضی درگاه‌ها
نام کاربری،رمز عبوروشماره فرستندهمیخواهند - برای بعضی درگاه‌ها شماره فرستنده در تنظیمات سراسری مهم است و برای بعضی حالت‌های پترن، الزام‌ها متفاوت می‌شود
درگاه Logger چیست و چه زمانی باید از آن استفاده کنیم
در کد افزونه، درگاه پیش‌فرض روی Logger (برای توسعه و تست) قرار دارد. این درگاه پیامک واقعی ارسال نمی‌کند و فقط payload را داخل فایل booklio-sms.log در پوشه uploads وردپرس می‌نویسد.
این حالت برای تست ساختار پیام، بررسی رویداد و اطمینان از اجرای Feed مفید است، اما برای ارسال واقعی به مشتری کافی نیست.
فید پیامک چیست و از کجا ساخته می‌شود
برای هر فرم، افزونه می‌تواند چند Feed جداگانه داشته باشد. چون افزونه روی فریم‌ورک Feed Add-On گرویتی‌فرمز ساخته شده، صفحه ساخت Feed از داخل تنظیمات همان فرم باز می‌شود.
- فرم رزرو را باز کنید
- به تنظیمات فرم بروید
- زیرنمای
booklio-gravity-smsرا باز کنید - یک Feed جدید بسازید
در خود کد، افزونه از چند Feed هم‌زمان پشتیبانی می‌کند و ترتیب آن‌ها هم قابل مدیریت است.
فیلدهای اصلی هر Feed چه هستند
نام Feed
فقط برای مدیریت بهتر در پیشخوان است. مثلا می‌توانید بنویسید: پیامک تایید رزرو.
درگاه این Feed
اگر خالی بماند، از درگاه فعال در تنظیمات سراسری استفاده می‌شود. اگر پر شود، همان Feed از درگاه انتخابی خودش استفاده می‌کند.
زمان ارسال
این مهم‌ترین فیلد برای سناریوهای رزرو است. در این لیست هم رویدادهای استاندارد گرویتی‌فرمز دیده می‌شود و هم رویدادهای رزرو بوکلیو مثل:
رزرو ایجاد شدرزرو تایید شدرزرو لغو شدرزرو تغییر زمان یافترزرو پیش‌رو
نوع گیرنده
دو حالت دارد:
از فیلد فرمبرای وقتی که شماره موبایل را از ورودی کاربر میگیریدشماره ثابتبرای وقتی که می‌خواهید به یک یا چند شماره ثابت پیامک برود
فیلد شماره موبایل یا شماره‌های ثابت
اگر گیرنده از فیلد فرم باشد، باید یک فیلد مناسب از نوع phone، text یا hidden انتخاب کنید. اگر شماره ثابت باشد، می‌توانید چند شماره را با کاما جدا کنید.
شماره فرستنده
اگر این فیلد را خالی بگذارید، افزونه از شماره فرستنده‌ی تنظیمات سراسری همان درگاه استفاده می‌کند.
حالت پیام
دو حالت دارد:
پیام عادیپیام پترن
همه درگاه‌ها هر دو حالت را پشتیبانی نمی‌کنند. افزونه قبل از ذخیره یا ارسال، سازگاری حالت پیام با درگاه انتخابی را بررسی می‌کند.
متن پیام یا کد پترن
در پیام عادی، متن پیام را می‌نویسید و می‌توانید از مرج‌تگ‌های گرویتی‌فرمز و بوکلیو استفاده کنید. در پیام پترن، باید کد پترن و در صورت نیاز متغیرهای پترن را پر کنید.
شرط ارسال
هر Feed می‌تواند شرط خودش را داشته باشد تا پیامک فقط در حالت خاصی ارسال شود.
شماره موبایل‌ها چطور اعتبارسنجی می‌شوند
در خود کد، افزونه شماره‌ها را normalize می‌کند و اعداد فارسی و انگلیسی را می‌پذیرد. همچنین ورودی‌هایی مثل 0912...، 98912... و +98912... را به شکل معتبر تبدیل می‌کند.
در نهایت فقط شماره‌هایی قبول می‌شوند که با الگوی موبایل ایران هم‌خوان باشند: 09xxxxxxxxx یا +989xxxxxxxxx.
تفاوت پیام عادی و پیام پترن چیست
پیام عادی برای متن کامل آزاد است. پیام پترن برای درگاه‌هایی است که الگوی خدماتی یا template دارند و پیام باید با کد الگو و متغیرهای آن ارسال شود.
در کد افزونه، پشتیبانی از pattern به‌صورت per-gateway تعریف شده است. یعنی مثلا بعضی درگاه‌ها فقط پیام عادی دارند، بعضی هر دو حالت را دارند و بعضی فقط روی مسیر pattern متمرکز هستند.
لاگ‌های پیامک را از کجا ببینیم
افزونه یک صفحه مستقل با عنوان لاگ پیامک بوکلیو در منوی گرویتی‌فرمز ثبت می‌کند. این صفحه برای آرشیو مدیریتی ارسال‌هاست و با فایل Logger فرق دارد.
در این لاگ برای هر ارسال، این اطلاعات نگه‌داری می‌شود:
- زمان
- فرم و ورودی
- شناسه Feed
- رویداد ارسال
- درگاه
- شماره فرستنده
- گیرنده یا گیرنده‌ها
- نوع پیام: عادی یا پترن
- وضعیت: موفق، ناموفق یا در انتظار
- توضیح نتیجه
روی این صفحه می‌توانید جستجو کنید، بر اساس وضعیت فیلتر بزنید، لاگ‌های انتخابی را حذف کنید یا همه لاگ‌ها را یک‌جا پاک کنید.
ارتباط این افزونه با خود بوکلیو چطور است
نقطه اتصال اصلی از اینجاست که پلاگین پیامک به actionهای رزرو بوکلیو گوش می‌کند. در کد فعلی این رویدادها مستقیم به Feedهای پیامک وصل شده‌اند:
booklio_reservation_createdبرای رزرو ایجاد شدbooklio_reservation_status_changedبرای رزرو تایید شد یا لغو شدbooklio_reservation_updatedبرای تغییر زمان رزروbooklio_upcoming_notifications_cronبرای رزرو پیش‌رو
پس وقتی در Feed گزینه رزرو تایید شد را انتخاب می‌کنید، افزونه منتظر همین رویدادهای هسته بوکلیو می‌ماند.
سناریوی عملی: ارسال پیامک بعد از تایید رزرو
- افزونه پیامک بوکلیو را نصب و فعال کنید.
- در تنظیمات سراسری، یک درگاه واقعی مثل IPPanel یا کاوه‌نگار را انتخاب و اطلاعات آن را کامل کنید.
- فرم رزرو را باز کنید و مطمئن شوید یک فیلد موبایل معتبر دارد.
- در تنظیمات همان فرم، یک Feed جدید در بخش پیامک بوکلیو بسازید.
- برای نام Feed مثلا بنویسید
پیامک تایید رزرو. - در
زمان ارسالگزینهرزرو تایید شدرا انتخاب کنید. - در
نوع گیرندهگزینهاز فیلد فرمرا بزنید و فیلد موبایل را انتخاب کنید. - در
حالت پیامیکی از دو حالت عادی یا پترن را انتخاب کنید. - اگر حالت عادی است، متن نمونه‌ای مثل این بنویسید:
سلام {bko_customer_name}، رزرو شما برای {bko_service} در {bko_datetime} تایید شد. کد رزرو: {bko_reservation_code} - Feed را ذخیره و فعال کنید.
- یک رزرو تستی بسازید و وضعیت آن را به حالت تاییدشده برسانید.
- نتیجه را در لاگ پیامک بوکلیو و در noteهای ورودی فرم بررسی کنید.
اگر اعلان پیش‌رو هم بخواهیم چه می‌شود
برای رویداد رزرو پیش‌رو، فقط ساخت Feed کافی نیست. باید قابلیت یادآوری پیش‌رو در خود تنظیمات بوکلیو هم فعال باشد و فاصله زمانی آن تنظیم شده باشد. چون این رویداد از کران زمان‌بندی‌شده بوکلیو اجرا می‌شود، نه از تغییر لحظه‌ای وضعیت رزرو.
خطاهای رایج
- درگاه روی Logger مانده و پیامک واقعی ارسال نمی‌شود
- فیلد موبایل فرم خالی یا نامعتبر است
- حالت
پترنبرای درگاهی انتخاب شده که از pattern پشتیبانی نمی‌کند - شماره فرستنده برای درگاهی که به sender نیاز دارد تنظیم نشده است
- رویداد Feed اشتباه انتخاب شده و با سناریوی واقعی رزرو هم‌خوان نیست
- انتظار ارسال برای رویداد
رزرو پیشرووجود دارد اما تنظیمات upcoming در بوکلیو فعال نشده است