وب سرویس پیامک چیست؟ سایت شما چطور خودکار پیامک می‌فرستد

وب سرویس پیامک یک در ارتباطی است که شرکت پیامکی روی اینترنت باز می‌گذارد. برنامه‌ی شما به آن در درخواست می‌فرستد، یعنی شماره و متن، و شرکت پیامکی آن را به اپراتور می‌رساند. نه کسی پنل را باز می‌کند و نه دکمه‌ای زده می‌شود. این صفحه توضیح می‌دهد وب سرویس پیامک دقیقاً چیست، از چه اجزایی ساخته شده، نحوه استفاده از آن چه مراحلی دارد و کجا باید مراقب باشید. نمونه‌کد کامل ورود با کد یکبارمصرف را هم در دو صفحه‌ی جداگانه برای PHP و Node.js آورده‌ایم.

بروزرسانی: زمان مطالعه حدود ۱۱ دقیقه نوشته‌ی تیم فنی فینگت

وب سرویس پیامک چیست؟ تعریف ساده با یک مثال

وب سرویس پیامک یعنی پنل پیامک شما یک نسخه‌ی قابل‌استفاده برای برنامه‌ها هم دارد. در پنل، آدمی متن را تایپ می‌کند و دکمه‌ی ارسال را می‌زند. در وب سرویس، برنامه‌ی شما همین کار را با یک درخواست اینترنتی انجام می‌دهد.

مثال معمولی‌اش یک فروشگاه اینترنتی است. مشتری سفارش می‌دهد. سایت به‌جای این‌که از کسی بخواهد وارد پنل شود، خودش به وب سرویس درخواست می‌دهد: «به این شماره بگو سفارشت ثبت شد». چند ثانیه بعد پیامک روی گوشی مشتری است.

چرا اسمش «وب سرویس» است؟

چون از راه وب و با همان پروتکلی کار می‌کند که مرورگر برای باز کردن سایت‌ها به کار می‌برد. اصطلاح‌های هم‌معنی در مستندات زیاد است: API پیامک، وب‌سرویس، رابط برنامه‌نویسی، و در متن‌های لاتین sms api. همه یک چیز را می‌گویند.

وب سرویس پیامک پنل نیست؛ همان پنل است که به‌جای انسان، با برنامه گفت‌وگو می‌کند.

واژه‌هایی که در مستندات وب سرویس ارسال پیامک می‌بینید

مستندات هر شرکت پیامکی با چند واژه‌ی ثابت پر است. اگر معنی‌شان را بدانید، خواندن مستندات سریع‌تر می‌شود. این فهرست را برای وب سرویس ارسال پیامک به‌صورت عمومی نوشته‌ایم؛ نام دقیق فیلدها را همیشه مستندات خود سرویس‌دهنده تعیین می‌کند.

کلید API
رشته‌ای طولانی که شبیه رمز عبور برنامه‌ی شماست. شرکت پیامکی با آن می‌فهمد درخواست از طرف کدام حساب آمده است.
درخواست و پاسخ
درخواست چیزی است که شما می‌فرستید، مثل شماره و متن. پاسخ جوابی است که برمی‌گردد، مثل «پذیرفته شد» یا «اعتبار کافی نیست».
JSON
قالبی ساده برای نوشتن داده، با نام فیلد و مقدار. بیشتر وب سرویس‌های امروزی داده را به همین شکل می‌گیرند و می‌دهند.
REST و SOAP
دو سبک رایج طراحی وب سرویس. REST سبک‌تر است و با آدرس و JSON کار می‌کند. SOAP قدیمی‌تر است و پیام‌هایش با XML نوشته می‌شود. هر سرویس‌دهنده یکی یا هر دو را دارد.
شماره‌ی خط ارسال‌کننده
خطی که پیامک از آن فرستاده می‌شود. خط خدماتی و خط تبلیغاتی فرق دارند و برای هر کاربرد یکی مناسب است.
شناسه‌ی پیام
عددی که پاسخ وب سرویس برای هر پیامک برمی‌گرداند. بعداً با آن می‌توانید وضعیت همان پیامک را بپرسید.
وضعیت تحویل
اطلاعات این‌که پیامک به گوشی رسید یا نه. معمولاً یا با پرسیدن از وب سرویس به دست می‌آید یا سرویس‌دهنده خودش به آدرسی از سایت شما خبر می‌دهد.
محدودیت نرخ
سقف تعداد درخواست در مدت معین. اگر از آن بگذرید، وب سرویس درخواست‌های اضافه را رد می‌کند.

اگر هنوز با خود پنل آشنا نیستید، اول پنل پیامک را ببینید. وب سرویس همان توانایی‌های پنل را به‌شکل قابل‌برنامه‌نویسی می‌دهد.

ارسال یک پیامک با API پیامک قدم‌به‌قدم

از لحظه‌ی درخواست تا رسیدن پیامک چند مرحله پشت‌سر هم رخ می‌دهد. دانستن ترتیبشان کمک می‌کند وقتی پیامکی نرسید، بدانید کجا دنبالش بگردید.

  1. ۱

    ساخت درخواست در سایت

    برنامه‌ی شما شماره‌ی گیرنده، متن و کلید API را کنار هم می‌گذارد و به آدرس وب سرویس می‌فرستد. این مرحله کاملاً در کنترل شماست.

  2. ۲

    بررسی در شرکت پیامکی

    شرکت پیامکی کلید را می‌شناسد، اعتبار حساب را می‌بیند و قالب شماره و متن را کنترل می‌کند. اگر مشکلی باشد، همین‌جا پاسخ خطا برمی‌گردد.

  3. ۳

    پاسخ فوری

    پاسخ اولیه فقط می‌گوید درخواست پذیرفته شد یا نه. این به معنای رسیدن پیامک نیست؛ یعنی پیام در صف ارسال قرار گرفت.

  4. ۴

    عبور از اپراتور

    پیام از صف شرکت پیامکی به اپراتور می‌رود. اگر اپراتور آن را مسدود کند یا گوشی خاموش باشد، پیام دیرتر می‌رسد یا نمی‌رسد.

  5. ۵

    گزارش وضعیت

    بعد از چند ثانیه یا دقیقه، وضعیت تحویل مشخص می‌شود. سایت شما می‌تواند آن را بپرسد یا منتظر خبر خودکار بماند.

پاسخ مرحله‌ی سوم را با رسیدن پیامک اشتباه نگیرید؛ بیشتر ماجراهای «پیامک را فرستادیم ولی نرسید» از همین‌جا شروع می‌شوند. علت‌های مرحله‌ی چهارم در علت نرسیدن پیامک جداگانه بررسی شده است.

وب سرویس پیامک به چه کارهایی می‌آید؟

هر جا سایت یا نرم‌افزار شما باید خودکار با کسی تماس بگیرد، وب سرویس پیامک یک گزینه است. اینها رایج‌ترین کاربردها هستند.

کد تأیید و ورود

کاربر شماره‌اش را می‌دهد، سایت کد می‌سازد و با وب سرویس می‌فرستد. جزئیات این منطق در رمز یکبار مصرف otp آمده است.

وضعیت سفارش

پرداخت موفق، ارسال بسته و تحویل سفارش، هر کدام یک پیامک کوتاه خودکار می‌شود.

یادآوری وقت و قسط

کلینیک، آموزشگاه یا باشگاه، روز قبل از موعد نوبت یادآوری می‌فرستد.

هشدار امنیتی

ورود از دستگاه تازه یا تغییر رمز را سریع به صاحب حساب خبر می‌دهد.

اطلاع‌رسانی به مدیر

خطای سرور، موجودی کم انبار یا فرم تماس تازه، مستقیم به گوشی مدیر خبر می‌دهد.

اطلاعیه‌ی گروهی

برای مشتریانی که اجازه‌ی دریافت داده‌اند؛ قواعد پیامک تبلیغاتی در پیامک خدماتی و تبلیغاتی آمده است.

نحوه استفاده از وب سرویس پیامک در پنج مرحله

نحوه استفاده از وب سرویس پیامک تقریباً در همه‌ی شرکت‌ها یک مسیر دارد. فقط اسم دکمه‌ها و فیلدها فرق می‌کند.

  1. حساب و خط را آماده کنید

    در پنل شرکت پیامکی ثبت‌نام و احراز هویت کنید، اعتبار بخرید و بپرسید کدام خط برای پیام‌های ورود و سفارش مناسب است. راهنمای خط خدماتی پیامک این انتخاب را توضیح می‌دهد.

  2. کلید API را بگیرید

    در بخش تنظیمات پنل، اگر گزینه‌ی وب سرویس فعال نیست، از پشتیبانی بخواهید. کلید را مثل رمز عبور نگه دارید.

  3. مستندات را بخوانید

    آدرس، نام فیلدها، قالب شماره، کدهای خطا و محدودیت‌ها فقط در مستندات همان شرکت درست‌اند. از روی مثال یک سرویس دیگر حدس نزنید.

  4. اول با یک شماره آزمایش کنید

    قبل از وصل کردن به سایت، یک پیامک را با ابزار ساده‌ای مثل curl یا فایل آزمایشی به شماره‌ی خودتان بفرستید و پاسخ را بخوانید.

  5. در برنامه ادغام و پایش کنید

    ارسال را در یک تابع جدا بگذارید، خطاها را ثبت کنید و گزارش اعتبار پنل را هر چند روز ببینید.

اتصال سایت به وب سرویس در وردپرس ممکن است بدون کدنویسی هم انجام شود؛ بعضی افزونه‌ها همین مراحل را در یک فرم انجام می‌دهند. برای راهنمای تخصصی آن، افزونه‌ی پیامک وردپرس را ببینید.

ساختار کلی تابع ارسال با sms api؛ نمونه با آدرس فرضی

نمونه‌ی زیر فقط شکل کلی یک تابع ارسال را نشان می‌دهد. آدرس و نام فیلدهای آن ساختگی‌اند و به هیچ شرکت واقعی تعلق ندارند. در پروژه‌ی خودتان آدرس، فیلدها و کدهای خطا را از مستندات سرویس‌دهنده بردارید.

نکته‌ی اصلی این است که همه‌ی ارتباط با شرکت پیامکی در یک تابع جمع شود. بعداً اگر سرویس‌دهنده عوض شد، فقط همین یک تابع تغییر می‌کند.

تابع ارسال با زمان‌سنج و کنترل خطا (آدرس و فیلدها فرضی‌اند)
<?php
// فقط الگوی کلی؛ آدرس و فیلدها را از مستندات سرویس‌دهنده بگیرید
function sendSms(string $phone, string $text): bool
{
    $url = 'https://sms-provider.example/api/send';   // آدرس فرضی
    $apiKey = getenv('SMS_API_KEY');                   // کلید در متغیر محیطی، نه در کد

    $body = json_encode(['to' => $phone, 'text' => $text]);   // نام فیلدها فرضی است
    $ctx = stream_context_create(['http' => [
        'method'  => 'POST',
        'header'  => "Content-Type: application/json\r\nAuthorization: Bearer $apiKey\r\n",
        'content' => $body,
        'timeout' => 8,                                // بدون زمان‌سنج، قطعی شبکه سایت را هم می‌خواباند
        'ignore_errors' => true,
    ]]);

    $res = @file_get_contents($url, false, $ctx);
    if ($res === false) {
        error_log('SMS: اتصال برقرار نشد');             // بدون ثبت متن پیام و کد
        return false;
    }
    // نتیجه را مطابق قالب پاسخ مستندات بررسی کنید
    return true;
}

دو چیز در این نمونه مهم است: کلید داخل کد نیست و درخواست زمان‌سنج دارد. اگر دو صفحه‌ی بعدی را بخوانید، همین تابع در ورود با موبایل php و otp node js دوباره به کار می‌آید.

کدام روش اتصال برای سایت شما مناسب است؟

سه راه اصلی برای فرستادن پیامک از یک سایت وجود دارد. انتخاب بین آنها به تعداد پیام و مهارت فنی تیم شما بستگی دارد، نه به این‌که کدام مدرن‌تر است.

معیارارسال دستی از پنلافزونه یا ماژول آمادهوب سرویس با کد خودتان
مناسب چه حجمیچند پیام در هفتهچند ده تا چند هزار پیام در ماههر حجمی، به‌ویژه وقتی منطق خاص دارید
نیاز به برنامه‌نویسنداردمعمولاً ندارددارد
ارسال لحظه‌ای و خودکارممکن نیستبرای رویدادهای از پیش تعریف‌شدهبرای هر رویدادی که بنویسید
کنترل بر محدودیت و سقفکامل، چون آدم می‌فرستدبه امکانات افزونه بستگی داردکامل، ولی خودتان باید بنویسید
نگهداریهیچبه‌روزرسانی افزونهنگهداری کد و پایش خطا

قاعده‌ی ساده این است: اگر افزونه‌ی آماده همان چیزی را انجام می‌دهد که می‌خواهید، سراغ کد نروید. وقتی نیاز شما از امکانات افزونه بیرون رفت، یا می‌خواهید پیامک را به یک سیستم داخلی وصل کنید، وب سرویس مسیر درست است. اگر وردپرس دارید، پیش از نوشتن کد صفحه‌ی افزونه‌ی پیامک وردپرس را نگاه کنید.

چه چیزهایی را پیش از انتخاب وب سرویس ارسال پیامک بپرسیم؟

اینجا قرار نیست شرکتی را برتر اعلام کنیم. فهرست زیر سؤال‌هایی است که پیش از خرید یا اتصال باید از هر سرویس‌دهنده‌ای بپرسید. پاسخ‌هایشان را به‌صورت مکتوب بخواهید.

  • مستندات روشن و به‌روز آیا برای زبان یا چارچوب شما نمونه‌کد دارد؟ آیا کدهای خطا یکی‌یکی توضیح داده شده‌اند؟
  • محیط آزمایشی آیا می‌توانید بدون خرج کردن اعتبار واقعی، درخواست‌ها را امتحان کنید؟
  • نوع خط آیا برای پیام‌های ورود، خط مناسب و با مجوز مشخص می‌دهند؟ تفاوت‌ها در انواع خط پیامک آمده است.
  • گزارش تحویل آیا وضعیت هر پیامک را می‌شود از وب سرویس گرفت؟ مدت نگه‌داری گزارش چقدر است؟
  • محدودیت درخواست سقف تعداد درخواست در ثانیه یا دقیقه چقدر است و اگر از آن بگذرید چه می‌شود؟
  • پشتیبانی وقتی ارسال مختل شد، با چه کانال و در چه زمانی جواب می‌گیرید؟
  • شیوه‌ی محاسبه‌ی هزینه هزینه به ازای هر پیام است یا هر صفحه‌ی پیامک؟ پیام فارسی بلند چند واحد حساب می‌شود؟ نرخ را خودتان از خود شرکت بپرسید؛ در هزینه پیامک سایت روش حساب‌کردنش را می‌بینید.
  • امنیت کلید آیا می‌شود کلید را عوض کرد یا فقط از یک IP مشخص پذیرفت؟

اشتباه‌هایی که ارسال خودکار پیامک را پرهزینه می‌کند

اتصال به وب سرویس معمولاً ساده است. دردسرها از جزئیات می‌آیند و بیشترشان با چند عادت درست قابل پیشگیری‌اند.

گذاشتن کلید در کد مرورگر

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

نبودن سقف روی دکمه‌ی ارسال

اگر هر کسی بتواند بی‌نهایت بار «ارسال کد» بزند، اعتبار شما در چند ساعت تمام می‌شود. راهکارش در جلوگیری از sms bombing آمده است.

نداشتن زمان‌سنج

وب سرویس گاهی کند می‌شود. اگر برنامه بی‌پایان منتظر بماند، صفحه‌ی ورود سایت شما هم قفل می‌شود.

تلاش مجدد کورکورانه

اگر پس از خطا خودکار دوباره بفرستید، ممکن است کاربر دو پیامک بگیرد و دو بار هزینه بدهید. تلاش مجدد را محدود کنید و اول وضعیت را بپرسید.

ثبت متن کد در لاگ

لاگ سرور را بیش از انتظار افراد می‌خوانند. کد ورود و کلید API در لاگ نباید دیده شوند.

اعتماد به پاسخ پذیرفته‌شد

پاسخ اولیه یعنی پیام به صف رفت، نه این‌که رسید. برای پیام‌های مهم، وضعیت تحویل را هم ببینید.

نبودن راه جایگزین

اگر پنل یا اپراتور مشکل داشته باشد و تنها راه ورود پیامک باشد، کاربر هیچ راهی ندارد. مثلاً با کد تایید نمیاد روبه‌رو می‌شود.

اگر فقط برای ورود وب سرویس می‌خواهید

بخش بزرگی از مصرف وب سرویس پیامک در سایت‌ها صرف کدهای ورود می‌شود. این مصرف هر ماه با تعداد ورودها زیاد می‌شود و پیچیدگی‌اش هم کم نیست: انقضا، شمارنده‌ی تلاش، سقف درخواست و جلوگیری از سوءاستفاده. اگر خودتان کد می‌نویسید، همین منطق را در دو نمونه‌ی PHP و Node.js آورده‌ایم.

راه دوم این است که اصلاً برای هر ورود پیامک نفرستید. در ورود با فینگت، سایت شما کاربر را به finget.ir می‌فرستد، کاربر در اپ فینگت ورود را تأیید می‌کند، و سایت با یک درخواست سروربه‌سرور نام، شماره‌ی موبایل تأییدشده و شناسه‌ی ثابت کاربر را می‌گیرد. شماره‌ی کاربر فقط یک بار، هنگام ثبت‌نام در خود اپ فینگت، با پیامک تأیید می‌شود. پس برای هر ورود نه خرج پیامکی دارید و نه منتظر رسیدنش می‌مانید.

فینگت پنل پیامک یا وب سرویس پیامک نیست و جای آن را برای پیام‌هایی مثل تبلیغ انبوه نمی‌گیرد. فقط حجم پیامک‌های ورود را کم می‌کند. ثبت‌نام صاحبان سایت و اتصال رایگان است و اپ فعلاً برای اندروید است. اگر می‌خواهید پیامک را هم برای بقیه‌ی کارها نگه دارید، بهترین پنل پیامک راهنمای مقایسه‌ی عمومی گزینه‌هاست و صفحه‌ی راهکارها بقیه‌ی راهنماهای فینگت را در یک جا جمع کرده است.

پرسش‌های متداول درباره وب سرویس پیامک

وب سرویس پیامک با پنل پیامک چه فرقی دارد؟

پنل برای استفاده‌ی انسان است: وارد می‌شوید، متن می‌نویسید و ارسال می‌زنید. وب سرویس همان توانایی را برای برنامه‌ها باز می‌کند تا سایت شما بدون دخالت آدم پیامک بفرستد. اغلب هر دو روی یک حساب و یک اعتبار کار می‌کنند.

برای استفاده از وب سرویس باید برنامه‌نویس باشم؟

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

کلید API را کجا نگه دارم؟

در متغیر محیطی یا فایل تنظیمات سرور که بیرون از پوشه‌ی عمومی سایت و بیرون از مخزن کد باشد. هرگز در جاوااسکریپت صفحه یا اپ موبایل نگذارید. اگر مطمئن نیستید لو رفته یا نه، همان لحظه کلید را عوض کنید.

چرا وب سرویس «پذیرفته شد» می‌گوید ولی پیامک نرسیده؟

چون این پاسخ فقط یعنی پیام وارد صف شد. بعد از آن اپراتور، خط، وضعیت گوشی و فیلترها دخیل‌اند. وضعیت تحویل را جداگانه از وب سرویس بپرسید.

هزینه‌ی وب سرویس ارسال پیامک چقدر است؟

خود وب سرویس معمولاً هزینه‌ی جدا ندارد و هزینه به پیام‌های فرستاده‌شده مربوط است. تعرفه‌ها را از سرویس‌دهنده بپرسید و برای برآورد، تعداد پیام ماهانه را در تعرفه‌ی هر پیام و تعداد صفحه‌ی پیام ضرب کنید.

می‌شود به جای وب سرویس از پنل و فایل اکسل استفاده کرد؟

برای ارسال گروهی یا گاه‌به‌گاه بله. ولی برای پیام‌هایی که باید همان لحظه برسند، مثل کد ورود و وضعیت سفارش، دستی بودن عملی نیست و باید از وب سرویس استفاده شود.

آیا فینگت وب سرویس پیامک می‌دهد؟

نه. فینگت پنل یا وب سرویس پیامک نیست. ورود بدون رمز و بدون پیامک برای هر ورود را فراهم می‌کند و اعلان‌های سایت را به اپ کاربر می‌فرستد. جزئیات فنی آن در صفحه‌ی دانلود و پنل سرویس‌دهندگان آمده است.