در این راهنما، اطلاعات اتصال، الگوها، متغیرها و خطاهای پیام‌رسان را بررسی می‌کنیم. برای انتخاب روش و اتصال مشترک، انتخاب پنل، برای تنظیم اعلان سفارش، مدیریت رویدادها و برای تشخیص خطاهای عمومی، عیب‌یابی پیامک را ببینید.
برای اتصال پیام‌رسان به جم پک، کلید API حساب را وارد می‌کنید. سپس می‌توانید پیام‌های فروشگاه را به‌صورت مستقیم یا با الگوهای تعریف‌شده در پنل بفرستید. در این اتصال، نام کاربری و رمز ورود پنل جایگزین کلید API نیستند.
در روش الگویی، دو موضوع اهمیت بیشتری دارند: کلید درست الگو و ترتیب داده‌هایی که جای متغیرهای آن قرار می‌گیرند. شماره‌گذاری متغیرهای پیام‌رسان از {1} شروع می‌شود؛ بنابراین تنظیمات الگویی پنل‌هایی مانند فراپیامک را نباید بدون تطبیق به آن منتقل کنید.
این راهنما مخصوص اتصال PayamResan با وب‌سرویس sms-webservice.com است. برای انتخاب رویدادهای ارسال، دریافت‌کنندگان و تنظیمات مشترک، راهنمای مرکز پیامک ووکامرس را هم مطالعه کنید.
این راهنما چه مواردی را پوشش می‌دهد؟
- آماده‌کردن کلید اتصال و خط فرستنده؛
- انتخاب پیام‌رسان در تنظیمات جم پک؛
- آزمون ارسال مستقیم؛
- آماده‌کردن الگو و ثبت کلید آن؛
- تنظیم ترتیب متغیرهای سفارش؛
- آزمون اعلان الگویی با سفارش آزمایشی؛
- بررسی خطاهای اتصال، آی‌پی، پاسخ سرویس و نگاشت متغیرها؛
- تشخیص تفاوت پذیرش پیام و تحویل آن به گوشی.
اطلاعات موردنیاز اتصال
| عنوان در جم پک | مقدار موردنیاز | کاربرد |
|---|---|---|
| کلید API | کلید ساخته‌شده در حساب پیام‌رسان | احراز هویت در ارسال مستقیم و الگویی |
| شماره فرستنده | خط مجاز ارسال پیامک حساب | ارسال مستقیم و تست عمومی |
| شناسه الگو | کلید الگو یا TemplateKey | ارسال الگویی همان رویداد |
دو فیلد اول در تنظیمات اتصال پیام‌رسان قرار دارند. «شناسه الگو» مربوط به پیام و رویداد موردنظر است؛ یک مقدار عمومی برای تمام اعلان‌ها نیست.
کلید API را با کلید الگو اشتباه نگیرید. اولی مشخص می‌کند درخواست از طرف کدام حساب است؛ دومی مشخص می‌کند کدام متن الگویی باید استفاده شود.
در این اتصال، کلید الگو به عدد تبدیل نمی‌شود. همان TemplateKey ثبت‌شده در پنل را وارد کنید؛ به‌جای آن شماره ردیف یک فهرست یا شناسه متعلق به پنل دیگر را ننویسید.
آماده‌کردن حساب پیام‌رسان
- وارد حساب پیام‌رسان خود شوید.
- بخش مربوط به کلید وب‌سرویس را پیدا کنید و کلید API حساب را بردارید.
- فعال‌بودن دسترسی وب‌سرویس و اعتبار حساب را بررسی کنید.
- اگر ارسال مستقیم می‌خواهید، خط مجاز حساب را مشخص کنید.
- اگر محدودیت آی‌پی دارید، آی‌پی عمومی خروجی سرور سایت را با فهرست مجاز تطبیق دهید.
- کلید را بدون فاصله اضافی در محل امن نگه دارید تا در تنظیمات جم پک وارد کنید.
محل دقیق منوهای پنل پیام‌رسان در این راهنما تأیید نشده است. برای پیدا کردن کلید یا بررسی وضعیت خط، از راهنمای داخل حساب یا پشتیبانی همان سرویس استفاده کنید.
آی‌پی خروجی درخواست‌های سایت لزوماً همان آی‌پی رایانه مدیر، دامنه یا CDN نیست. در صورت ابهام، آن را از پشتیبانی هاست بخواهید. پس از جابه‌جایی هاست هم ممکن است لازم باشد فهرست مجاز حساب را دوباره بررسی کنید.
انتخاب پیام‌رسان در جم پک
- وارد پیشخوان وردپرس شوید.
- از بخش جم پک، «اعلان‌های پیامکی» را باز کنید.
- وارد «تنظیمات اصلی» شوید.
- «فعال‌سازی پیامک» را روشن کنید.
- در «درگاه پیامک»، گزینه
PayamResanرا انتخاب کنید. - تنظیمات را ذخیره و صفحه را دوباره باز کنید.
- «کلید API» را وارد کنید.
- برای ارسال مستقیم، «شماره فرستنده» را هم تکمیل کنید.
- تنظیمات را دوباره ذخیره کنید.
پیش از تنظیم الگوها، انتخاب درگاه را ذخیره کنید. نگاشت یعنی تعیین کنید هر متغیر الگو با کدام داده پر شود. راهنمای آن بر اساس درگاه ذخیره‌شده نمایش داده می‌شود.
برای شروع، فقط یک رویداد موردنیاز را فعال کنید. این کار تشخیص نتیجه و کنترل تعداد پیام‌های آزمایشی را ساده‌تر می‌کند.
انتخاب بین ارسال مستقیم و الگویی
پیامک مستقیم
در این روش، متن پیام در جم پک ساخته و همراه شماره فرستنده برای پیام‌رسان ارسال می‌شود. برای استفاده از آن، هم کلید API و هم خط فرستنده لازم است.
برای نمونه، در متن اعلان سفارش می‌توانید از متغیرهای قابل‌استفاده همان بخش کمک بگیرید:
سفارش {order_number} شما ثبت شد.
جم پک شماره سفارش را جای متغیر قرار می‌دهد و متن نهایی را می‌فرستد. مجازبودن متن و خط ارسال همچنان به وضعیت حساب و ضوابط سرویس بستگی دارد.
الگو/قالب
در این روش، متن پایه در پنل پیام‌رسان تعریف می‌شود و جم پک کلید الگو و مقدار متغیرهای آن را می‌فرستد. فیلد شماره فرستنده جم پک در این درخواست قرار نمی‌گیرد.
طبق راهنمای رسمی وب‌سرویس پیام‌رسان، ارسال الگویی با الگوی تأییدشده انجام می‌شود و انتخاب خط خدماتی در سمت سرویس است. این موضوع تضمین تحویل پیام در زمان مشخص نیست؛ نتیجه را باید با آزمون بررسی کنید.
نوشتن متن دلخواه در جم پک جای تعریف و تأیید الگو در پنل را نمی‌گیرد.
آزمون اولیه ارسال مستقیم
پس از ذخیره اطلاعات اتصال:
- در «تنظیمات اصلی»، بخش تست پیامک را پیدا کنید.
- شماره متعلق به خودتان را در «شماره موبایل تست» وارد کنید. برای جلوگیری از ابهام، از رقم‌های انگلیسی و قالب معمول شماره همراه ایران استفاده کنید.
- روی «ارسال پیامک تست» بزنید.
- تا مشخص‌شدن نتیجه، دکمه را دوباره نزنید.
- نتیجه روی صفحه را بخوانید و دریافت پیام در گوشی را بررسی کنید.
- اگر پیام دریافت نشد، وضعیت درخواست را در پنل پیام‌رسان هم بررسی کنید.
این دکمه متن آزمایشی آماده جم پک را از مسیر مستقیم ارسال می‌کند؛ آزمون الگوی سفارش نیست و فیلدی برای انتخاب الگو در همین تست ندارد.
پیامک تست در تاریخچه معمول اعلان‌های سفارش ثبت نمی‌شود. نبودن آن در تاریخچه، به‌تنهایی نشانه ارسال‌نشدن نیست. نتیجه همان کادر تست، پنل پیام‌رسان و گوشی را با هم بررسی کنید.
اگر خط فرستنده ندارید و هدف شما فقط ارسال الگویی است، به بخش آزمون الگو بروید. برای موفق‌کردن تست مستقیم، شماره فرستنده نامرتبط یا غیرمجاز وارد نکنید.
آماده‌کردن الگو در پیام‌رسان
ابتدا یک پیام ساده و مرتبط با سفارش انتخاب کنید. برای مثال:
سفارش {1} شما ثبت شد.
در این نمونه، جایگاه اول باید شماره سفارش را دریافت کند. این متن فقط نمونه آموزشی است و به معنی وجود یا تأیید آن در حساب شما نیست.
- الگوی موردنظر را در حساب پیام‌رسان تعریف کنید.
- جایگاه‌های متغیر را طبق روش پیام‌رسان بنویسید؛ شماره‌گذاری از
{1}آغاز می‌شود. - وضعیت تأیید و آماده‌بودن الگو برای ارسال را بررسی کنید.
- کلید همان الگو، یعنی
TemplateKey، را بردارید. - ترتیب اطلاعات موردنیاز هر جایگاه را یادداشت کنید.
برای الگوی چندمتغیره، پیش از ادامه مشخص کنید جایگاه اول، دوم و سوم دقیقاً چه مقداری می‌گیرند. شباهت ظاهری متن‌ها کافی نیست؛ ترتیب باید در پنل و جم پک یکسان باشد.
ثبت الگو و نگاشت متغیرها در جم پک
مراحل مشترک انتخاب مخاطب، رویداد، روش ارسال و ذخیره در مدیریت رویدادها و الگوهای پیامکی آمده است. در اجرای این مراحل، نکته اختصاصی این پنل را رعایت کنید:
کلید الگوی پیام‌رسان را ثبت کنید؛ اولین ردیف نگاشت، جایگاه نخست الگو را پر می‌کند.
برای نمونه تک‌متغیره بالا، ردیف اول نگاشت باید مقدار شماره سفارش را بگیرد. نیازی نیست p1 را به‌عنوان مقدار متغیر وارد کنید؛ جم پک شماره‌گذاری پارامترهای درخواست را انجام می‌دهد.
تنظیم روش ارسال مدیر و مشتری جداست. شناسه و نگاشت رویدادهای فعال هر گروه را بررسی کنید؛ تکمیل الگوی یک وضعیت به معنی آماده‌بودن تمام وضعیت‌ها نیست.
ترتیب متغیرها: از یک شروع کنید
فرض کنید متن الگویی شما چنین باشد:
{1} عزیز، سفارش {2} شما در وضعیت {3} قرار گرفت.
نگاشت موردنیاز:
| ترتیب ردیف در جم پک | مقدار انتخابی | جایگاه در متن پیام‌رسان | پارامتر فنی |
|---|---|---|---|
| اول | نام مشتری — customer_name | {1} | p1 |
| دوم | شماره سفارش — order_number | {2} | p2 |
| سوم | وضعیت سفارش — order_status | {3} | p3 |
اگر نام مشتری «سارا احمدی»، شماره سفارش «1250» و مقدار وضعیت «در حال انجام» باشد، نتیجه موردانتظار این نمونه چنین است:
سارا احمدی عزیز، سفارش 1250 شما در وضعیت در حال انجام قرار گرفت.
این یک نمونه فرضی برای بررسی نگاشت است، نه گزارش ارسال واقعی.
در پیام‌رسان، ترتیب ردیف‌ها تعیین‌کننده است، نه نام‌گذاری دلخواه جایگاه‌ها. ردیف اول همیشه برای {1} فرستاده می‌شود. اگر از پنلی با شماره‌گذاری {0} مهاجرت می‌کنید، الگو و نگاشت را از ابتدا تطبیق دهید.
ردیف خالی یا متغیر نامعتبر می‌تواند هنگام ساخت پارامترها کنار گذاشته شود و جایگاه ردیف‌های بعدی را تغییر دهد. نگاشت را بدون ردیف ناقص ذخیره کنید.
اگر نگاشت خالی باشد، مسیر اعلان سفارش می‌تواند متغیرها را از متن ذخیره‌شده پیام استخراج کند. برای کنترل دقیق ترتیب داده‌ها، همه ردیف‌های نگاشت را مشخص و کامل کنید تا ترتیب به متن قبلی وابسته نماند.
متغیر پنل با متغیر جم پک فرق دارد
{1}و{2}جایگاه‌های متن در پنل پیام‌رسان هستند.order_numberوcustomer_nameمشخص می‌کنند داده از کدام بخش سفارش برداشته شود.p1وp2نام پارامترهای فنی درخواست هستند و جم پک آن‌ها را می‌سازد.
در فهرست نگاشت، داده موردنیاز را انتخاب کنید؛ کلید API، کلید الگو یا نام پارامتر درخواست را به‌جای مقدار سفارش قرار ندهید.
آزمون اعلان الگویی با سفارش
تست عمومی پیامک برای این بخش کافی نیست. یک رویداد واقعی را در محیط آزمایشی، با اطلاعات متعلق به خودتان، اجرا کنید:
- فقط اعلان موردنظر را برای مدیر یا مشتری فعال کنید.
- کلید الگو و نگاشت همان رویداد را دوباره کنترل کنید.
- در صورت نیاز به بررسی تاریخچه، ثبت گزارش پیامک را فعال کنید.
- شماره آزمایشی را در محل دریافت‌کننده همان اعلان قرار دهید؛ شماره صورتحساب برای پیام مشتری و شماره مدیر برای پیام مدیر.
- برای آزمون اعلان ثبت سفارش، سفارش تازه‌ای از مسیر خرید آزمایشی ثبت کنید.
- برای آزمون تغییر وضعیت، سفارش آزمایشی را به وضعیتی ببرید که اعلان آن را تنظیم کرده‌اید.
- پیام دریافت‌شده، نتیجه پنل پیام‌رسان و تاریخچه جم پک را با هم مقایسه کنید.
- صحت نام، شماره سفارش و وضعیت را با اطلاعات همان سفارش تطبیق دهید.
در تاریخچه ارسال الگویی، ممکن است شناسه الگو و مقادیر ارسالی را ببینید، نه متن نهایی کامل پیام. برای دیدن متن نهایی، پیام دریافتی را هم بررسی کنید.
اگر نتیجه نامشخص بود، پیش از اجرای دوباره رویداد، پنل و گوشی را بررسی کنید. خطای شبکه همیشه ثابت نمی‌کند که سرویس هیچ پیامی نپذیرفته است؛ تکرار بی‌بررسی می‌تواند پیام تکراری ایجاد کند.
این آزمون را برای گروه دیگر دریافت‌کنندگان یا الگوهای مهم دیگر نیز جدا انجام دهید. موفقیت یک نمونه، تمام رویدادهای فروشگاه را تأیید نمی‌کند.
موفقیت درخواست چه معنایی دارد؟
جم پک پاسخ پیام‌رسان را بررسی می‌کند و وجود شناسه پیام در ساختارهای شناخته‌شده پاسخ را نشانه موفقیت درخواست می‌داند. دریافت یک پاسخ HTTP به‌تنهایی کافی نیست.
بااین‌حال، وضعیت موفق در جم پک به معنی تأیید تحویل پیام به گوشی نیست. اتصال بررسی‌شده وضعیت نهایی تحویل را از سرویس استعلام نمی‌کند. برای اطمینان، گزارش سرویس و دریافت واقعی را بررسی کنید.
در ارسال به چند گیرنده نیز موفقیت کلی درخواست را تأیید مستقل تک‌تک شماره‌ها در نظر نگیرید. آزمون اولیه را با یک شماره انجام دهید و در استفاده واقعی، گزارش هر گیرنده را در پنل بررسی کنید.
خطاهای رایج و روش بررسی آن‌ها
کلید API تنظیم نشده است
ابتدا ذخیره‌شدن فیلد «کلید API» را بررسی کنید. رمز ورود پنل و کلید الگو جایگزین آن نیستند.
اگر کلید وارد شده ولی سرویس آن را نمی‌پذیرد، تعلق کلید به حساب صحیح، فعال‌بودن دسترسی وب‌سرویس و پیام خطای خود سرویس را بررسی کنید. از روی این وضعیت، بدون خواندن پاسخ، علت را تمام‌شدن اعتبار فرض نکنید.
شماره فرستنده تنظیم نشده است
این خطا به مسیر ارسال مستقیم مربوط است. یک خط مجاز حساب را در «شماره فرستنده» وارد و ذخیره کنید.
اگر قصد ارسال الگویی دارید ولی این خطا را می‌بینید، بررسی کنید آیا از دکمه تست عمومی استفاده کرده‌اید یا شناسه الگوی رویداد خالی مانده است.
پیام مربوط به مجازنبودن آی‌پی
اگر پاسخ سرویس عبارت IP address not allowed دارد، آی‌پی خروجی سرور را با فهرست مجاز حساب تطبیق دهید.
متن خطا ممکن است آی‌پی مشاهده‌شده توسط سرویس را هم نشان دهد. پیش از ارسال تصویر یا متن خطا در فضای عمومی، اطلاعات حساس را حذف کنید. مجازکردن آی‌پی رایانه خودتان معمولاً جای مجازکردن سرور سایت را نمی‌گیرد.
خطای 502، 504 یا پایان زمان انتظار
این خطاها را الزاماً به کلید اشتباه نسبت ندهید. مسیر شبکه سرور، سرویس واسط یا پاسخ‌گویی سرویس پیامکی هم می‌تواند درگیر باشد.
- زمان دقیق خطا و متن آن را ثبت کنید.
- اگر
req،sidیاtimingدر پیام وجود دارد، آن‌ها را برای پیگیری خصوصی نگه دارید. - از هاست بخواهید دسترسی خروجی HTTPS به دامنه سرویس را بررسی کند.
- پاسخ ثبت‌شده را، پس از حذف کلید و اطلاعات شخصی، برای پشتیبانی پیام‌رسان بفرستید.
- پیش از ارسال مجدد، وضعیت پیام قبلی را بررسی کنید.
برای رفع این خطاها، نشانی اتصال را به HTTP تغییر ندهید و بررسی امنیت گواهی را خاموش نکنید.
پاسخ نامشخص از وب‌سرویس
این پیام یعنی جم پک نتوانسته پاسخ را با ساختار موفقیت شناخته‌شده تطبیق دهد. لزوماً به معنی رد قطعی پیام نیست.
متن پاسخ، کد HTTP و شناسه‌های پیگیری احتمالی را نگه دارید. پاسخ HTML یا صفحه خطای واسط با پاسخ عادی سرویس یکسان نیست. برای تشخیص نهایی، گزارش پنل را هم بررسی کنید.
جم پک در این وضعیت بخشی از پاسخ خوانا را نمایش می‌دهد؛ جدول کد خطای یک پنل دیگر را برای تفسیر آن استفاده نکنید.
تست مستقیم موفق است ولی الگو ارسال نمی‌شود
موفقیت مستقیم، صحت کلید و یک مسیر ارسال را نشان می‌دهد؛ کلید الگو و نگاشت را تأیید نمی‌کند. این موارد را بررسی کنید:
- روش ارسال گروه موردنظر روی «الگو/قالب» باشد.
- کلید متعلق به همان حساب و همان متن باشد.
- وضعیت الگو برای استفاده آماده باشد.
- شناسه الگوی همان رویداد، نه رویداد دیگری، تکمیل شده باشد.
- ترتیب و تعداد داده‌های ارسالی با متن الگو هماهنگ باشد.
- پاسخ سرویس در تاریخچه خوانده شود.
اطلاعات داخل پیام جابه‌جا هستند
متن پنل را کنار فهرست نگاشت بگذارید و از ردیف اول بررسی کنید. در پیام‌رسان، ردیف اول برای {1} است.
وجود ردیف ناقص، انتخاب متغیر نادرست یا کپی‌کردن ترتیب پنل قبلی را بررسی کنید. اضافه‌کردن نام‌هایی مانند p2 در متن داده، ترتیب ردیف‌ها را اصلاح نمی‌کند.
اعلان الگویی به‌صورت مستقیم ارسال می‌شود
کلید الگوی همان رویداد را بررسی کنید. در مسیر اعلان سفارش، اگر حالت الگویی انتخاب شده ولی شناسه خالی باشد، کد به ارسال مستقیم برمی‌گردد.
کلید و نگاشت تمام رویدادهای فعال آن گروه را تکمیل کنید. صرف انتخاب «الگو/قالب» برای جلوگیری از این وضعیت کافی نیست.
امنیت اطلاعات اتصال
- کلید API را داخل متن پیام، نام الگو، فایل عمومی یا تصویر آموزشی قرار ندهید.
- شماره کامل مشتریان و محتوای سفارش را در گزارش عمومی نمایش ندهید.
- پیش از ارسال گزارش فنی، نشانی کامل درخواست را بررسی و پارامترهای حساس را حذف کنید.
- اگر کلید افشا شد، آن را از پنل سرویس تعویض و مقدار جدید را در جم پک ذخیره کنید.
- پس از آزمون، اعلان‌های آزمایشی غیرضروری را خاموش و دریافت‌کنندگان را برای استفاده واقعی بازبینی کنید.
در این اتصال، پارامترهای ارسال در نشانی درخواست HTTPS قرار می‌گیرند. نشانی کامل ممکن است کلید API، شماره گیرنده و متن یا متغیرهای پیام را داشته باشد؛ آن را برای عیب‌یابی در کانال عمومی کپی نکنید.
چک‌لیست پایان راه‌اندازی
- پیام‌رسان به‌عنوان درگاه فعال ذخیره شده است.
- کلید API صحیح حساب وارد شده است.
- خط مجاز، در صورت استفاده از ارسال مستقیم، ثبت شده است.
- آزمون مستقیم و الگویی با هم اشتباه گرفته نشده‌اند.
- کلید الگو برای هر رویداد فعال تکمیل شده است.
- نگاشت‌ها از جایگاه
{1}شروع می‌شوند و ردیف ناقص ندارند. - یک سفارش آزمایشی اجرا و نتیجه آن با گوشی و گزارش سرویس بررسی شده است.
- پیام موفق با تحویل قطعی یکسان فرض نشده است.
- داده‌های حساس از تصاویر و گزارش‌های آموزشی حذف شده‌اند.
جمع‌بندی
برای راه‌اندازی پیام‌رسان، ابتدا کلید API را ثبت کنید و در صورت نیاز به ارسال مستقیم، خط فرستنده را هم وارد کنید. سپس برای هر اعلان الگویی، کلید درست و ترتیب متغیرهای شروع‌شونده از {1} را تنظیم کنید.
پیش از فعال‌کردن اعلان‌ها برای مشتریان، متن یک پیام آزمایشی را با داده‌های سفارش مقایسه کنید و دریافت آن را در گوشی بررسی کنید.
قدم‌های بعدی
- تنظیم اعلان‌های مدیر، مشتری و موجودی در مرکز پیامک ووکامرس
- آشنایی با محیط جم پک و مدیریت ماژول‌ها
- معرفی مرکز پیامک ووکامرس