دریافت پیامک با webhook و اتصال سایت به پنل پیامکی
ارسال پیامک فقط نیمی از ماجراست. بسیاری از کسب‌وکارها می‌خواهند پاسخ مشتری را هم به‌صورت خودکار دریافت و پردازش کنند؛ مثلاً تأیید رزرو با ارسال عدد ۱، شرکت در نظرسنجی یا ثبت درخواست پشتیبانی. از طرف دیگر، بیشتر فروشگاه‌های اینترنتی پیامک را از طریق افزونه‌های آماده به سایت خود وصل می‌کنند. در این مقاله هر دو موضوع را بررسی می‌کنیم: دریافت پیامک با webhook و تنظیم درست افزونه‌ها و ماژول‌های سایت.
کدام خط پیامک دریافت می‌کند؟
فقط خطوط اختصاصی قابلیت دریافت پیامک دارند؛ خطوط اشتراکی این امکان را ندارند. پیامکی که به خط اختصاصی شما ارسال شود، معمولاً در عرض چند ثانیه تا چند دقیقه در گزارش پیام‌های دریافتی پنل ثبت می‌شود. اگر سناریوی شما به پاسخ مشتری وابسته است، پیش از هر چیز مطمئن شوید از خط اختصاصی استفاده می‌کنید.
webhook چیست و چه کاری انجام می‌دهد؟
به جای این‌که برنامهٔ شما مدام از سامانه بپرسد «پیام جدیدی رسیده؟»، با webhook خود سامانه هر پیام دریافتی را بلافاصله به نشانی‌ای که شما تعیین کرده‌اید ارسال می‌کند. نشانی webhook را در بخش برنامه‌نویسان پنل ثبت می‌کنید و از آن به بعد، هر پیامک دریافتی با یک درخواست POST به سرور شما فرستاده می‌شود.
نکتهٔ کلیدی: بدنهٔ درخواست JSON خام است
دادهٔ پیامک به‌صورت JSON خام در بدنهٔ درخواست ارسال می‌شود، نه به شکل فرم استاندارد HTML. این مهم‌ترین نکته‌ای است که برنامه‌نویسان از قلم می‌اندازند. اگر در کد خود مقادیر را مثل فیلدهای یک فرم بخوانید، با داده‌های خالی روبه‌رو می‌شوید. باید بدنهٔ خام درخواست را بخوانید و سپس JSON را decode کنید. برای مثال در PHP به جای آرایهٔ $_POST از php://input و سپس json_decode استفاده کنید؛ در فریمورک‌هایی مثل لاراول هم محتوای خام درخواست یا خروجی JSON آن را بخوانید، نه مقادیر فرم.
اشتباه رایج: گزارش این‌که «webhook داده نمی‌فرستد» در حالی که داده می‌رسد ولی کد سمت شما آن را به‌شکل فرم می‌خواند. پیش از هر چیز، بدنهٔ خام درخواست ورودی را لاگ کنید تا ببینید دقیقاً چه چیزی دریافت می‌شود.
پاسخ سرور شما مهم است
اگر سرور شما در پاسخ به webhook خطای HTTP 500 برگرداند، سامانه پیام را ارسال کرده اما آن را ناموفق ثبت می‌کند. پس اگر در گزارش‌ها ارسال‌های ناموفق webhook می‌بینید، اول لاگ خطای سرور خودتان را بررسی کنید. چند توصیه:
- درخواست را سریع دریافت و ذخیره کنید و پاسخ موفق بدهید؛ پردازش سنگین را به صف یا کار پس‌زمینه بسپارید.
- نشانی webhook را روی https قرار دهید.
- محافظ CSRF فریمورک را برای این مسیر مشخص غیرفعال کنید؛ چون درخواست از بیرون سایت می‌آید.
- با ثبت شناسهٔ هر پیام، از پردازش تکراری جلوگیری کنید.
اتصال سایت با افزونه‌ها و ماژول‌ها
اگر از وردپرس، ووکامرس، WHMCS یا سامانه‌های مشابه استفاده می‌کنید، معمولاً با یک افزونه یا ماژول پیامکی، پیام‌هایی مثل ثبت سفارش، تغییر وضعیت سفارش یا کد تأیید ورود را خودکار ارسال می‌کنید. تقریباً همهٔ این ابزارها دو اطلاعات اصلی از شما می‌خواهند:
- کلید API: که در بخش برنامه‌نویسان پنل قرار دارد. در برخی ماژول‌ها، مثلاً WHMCS، فیلدی با عنوان شناسه یا api id وجود دارد که معمولاً باید همین کلید را در آن وارد کنید.
- شمارهٔ درگاه یا شمارهٔ خط: شمارهٔ خطی که پیامک از آن ارسال می‌شود، با ارقام لاتین.
برای جابه‌جایی بین خط خدماتی و تبلیغاتی، فقط کافی است شمارهٔ خط را در تنظیمات افزونه عوض کنید.
رفع مشکلات رایج افزونه‌ها
پیامک ارسال نمی‌شود
اگر پیامی ارسال نمی‌شود یا خطایی شبیه «شمارهٔ گیرنده یا تنظیمات را بررسی کنید» می‌بینید، معمولاً یکی از این‌هاست:
- کلید API اشتباه یا همراه با فاصلهٔ اضافه وارد شده است.
- شمارهٔ درگاه اشتباه است یا با ارقام فارسی ثبت شده.
- محدودیت آی‌پی مجاز فعال است و آی‌پی هاست سایت در فهرست نیست.
- محتوای پیام قالب خدماتی ندارد و در انتظار تأیید مانده است.
به جای متن، کدهای عددی نامفهوم ارسال می‌شود
این مشکل معمولاً وقتی رخ می‌دهد که چند افزونه یا ماژول پیامکی هم‌زمان نصب‌اند؛ مثلاً نسخهٔ قدیمی و جدید یک افزونه کنار هم. راه‌حل این است که همهٔ افزونه‌های پیامکی را کامل حذف کنید و فقط نسخهٔ به‌روز یک افزونه را دوباره نصب و تنظیم کنید.
نکته: اگر حسابتان را عوض کرده‌اید یا کلید API تغییر کرده، افزونه‌ها و سرویس‌هایی که از کلید قبلی استفاده می‌کردند دیگر کار نمی‌کنند و باید با کلید جدید دوباره تنظیم شوند.
چک‌لیست راه‌اندازی
- برای دریافت پیام، خط اختصاصی دارید.
- نشانی webhook ثبت شده و بدنهٔ JSON خام را می‌خواند.
- سرور شما به webhook پاسخ موفق می‌دهد.
- کلید API و شمارهٔ درگاه با ارقام لاتین در افزونه وارد شده‌اند.
- فقط یک افزونهٔ پیامکی فعال است.
جمع‌بندی
webhook امکان ساخت سناریوهای تعاملی را فراهم می‌کند و افزونه‌ها اتصال سایت را بی‌نیاز از کدنویسی می‌کنند؛ به شرط این‌که چند نکتهٔ ساده رعایت شود. اگر پس از بررسی این موارد همچنان مشکل داشتید، با ثبت تیکت پشتیبانی جزئیات خطا و تنظیمات (بدون کلید API) را برای کارشناسان فنی وب‌سرویس بفرستید.
