ارسال پیامک node js؛ نوشتن ماژولی کوچک که وقتی سرویسدهنده لنگ بزند هم درست رفتار کند
ارسال پیامک node js در سادهترین حالت فقط یک درخواست HTTP است، و برای همین هم بیشتر پروژهها آن را همانطور ساده مینویسند: یک fetch بدون مهلت، بدون بررسی وضعیت و بدون فکر به اینکه اگر پاسخ نیامد چه میشود. مشکل از روزی شروع میشود که سرویسدهنده کند شود، کلید در لاگ بیفتد یا یک حلقه هزار پیامک را همزمان بفرستد. این صفحه یک ماژول کوچک و مستقل میسازد که مهلت زمانی دارد، فقط خطای موقت را دوباره امتحان میکند، با صف و سقف همزمانی کار میکند و بدون ارسال واقعی قابل آزمایش است. آخرش هم میبینید چه بخشی از اعلانهایتان را میشود اصلاً با پیامک نفرستاد.
ارسال پیامک node js؛ یک درخواست ساده و چند تصمیم پنهان
تقریباً همهی شرکتهای پیامکی یک وبسرویس HTTP دارند: شما آدرس، کلید، شمارهی خط فرستنده، شمارهی گیرنده و متن را میفرستید و یک شناسه یا کد خطا پس میگیرید. در Node.js این یعنی یک فراخوانی fetch. اما بین «کار میکند» و «در تولید قابلاعتماد است» چند تصمیم پنهان وجود دارد که معمولاً وسط یک اتفاق ناخوشایند کشف میشوند.
اولین تصمیم این است که تا چه زمانی منتظر پاسخ بمانید. fetch بهطور پیشفرض مهلت مشخصی ندارد و یک سرویسدهندهی کند میتواند درخواستهای ورودی سرور شما را پشت خودش معطل کند. دومی این است که با خطا چه کنید: خطای شبکه و خطای ۵۰۰ موقتاند، ولی شمارهی نامعتبر یا اعتبار تمامشده با تکرار درست نمیشود. سومی اینکه کلید API کجا نگهداری شود و در کدام لاگ دیده نشود. و چهارمی اینکه اگر ده هزار پیامک یکجا خواستید، چطور سرور خودتان و سرویسدهنده را زیر فشار نگذارید.
نمونههای این صفحه عمداً آدرس و نام فیلد واقعی هیچ شرکتی را ندارند. قالب دقیق درخواست و کدهای خطا را فقط مستندات سرویسدهندهی شما تعیین میکند؛ اینجا ساختار ماژول را یاد میگیرید و جزئیات را خودتان جایگزین میکنید.
اگر هنوز نمیدانید یک وبسرویس پیامکی از چه اجزایی ساخته میشود، پیش از ادامه وب سرویس پیامک چیست را مرور کنید. بقیهی این صفحه فرض میکند یک حساب و کلید آماده دارید.
ارسال پیامک با fetch؛ ماژول پایه و خطای دستهبندیشده
نمونهی زیر یک فایل ESM است. سه کار میکند: شماره را به قالب استاندارد درمیآورد، با مهلت زمانی درخواست میفرستد و خطا را به دو دسته تقسیم میکند، «موقت» و «دائمی». همین تقسیمبندی پایهی بخش بعد، یعنی تلاش دوباره، است.
ارسال پیامک با fetch بدون هیچ بستهای انجام میشود. اگر axios یا got را ترجیح میدهید منطق عوض نمیشود؛ فقط محل تنظیم مهلت زمانی فرق میکند.
// آدرس، کلید و خط فرستنده از متغیر محیطی؛ مقدارشان را مستندات سرویسدهندهی شما میگوید
const API_URL = process.env.SMS_API_URL
const API_KEY = process.env.SMS_API_KEY
const SENDER = process.env.SMS_SENDER
export class SmsError extends Error {
constructor(message, { status = 0, retryable = false } = {}) {
super(message)
this.name = 'SmsError'
this.status = status
this.retryable = retryable
}
}
const FA = { '۰': '0', '۱': '1', '۲': '2', '۳': '3', '۴': '4', '۵': '5', '۶': '6', '۷': '7', '۸': '8', '۹': '9' }
// ورودی هر شکلی که باشد، خروجی 09xxxxxxxxx یا null است
export function normalizePhone(raw) {
let d = String(raw).replace(/[۰-۹]/g, (c) => FA[c]).replace(/\D+/g, '')
if (d.startsWith('98')) d = '0' + d.slice(2)
return /^09\d{9}$/.test(d) ? d : null
}
async function attempt(body, timeoutMs) {
const res = await fetch(API_URL, {
method: 'POST',
headers: { 'Content-Type': 'application/json', Authorization: 'Bearer ' + API_KEY },
body: JSON.stringify(body),
signal: AbortSignal.timeout(timeoutMs), // بدون این، یک سرویسدهندهی کند سرور شما را معطل میکند
})
if (res.ok) return res.json().catch(() => ({}))
// 429 و 5xx موقتاند؛ 400 و 401 و 403 با تکرار درست نمیشوند
throw new SmsError('HTTP ' + res.status, { status: res.status, retryable: res.status === 429 || res.status >= 500 })
}
export async function sendSms(phone, text, { retries = 2, timeoutMs = 8000 } = {}) {
const to = normalizePhone(phone)
if (!to) throw new SmsError('شماره نامعتبر است')
const body = { sender: SENDER, to, text }
for (let i = 0; ; i++) {
try {
return await attempt(body, timeoutMs)
} catch (err) {
// خطای شبکه و تایماوت (غیر SmsError) موقت حساب میشود
const retryable = err instanceof SmsError ? err.retryable : true
if (!retryable || i >= retries) throw err
await new Promise((r) => setTimeout(r, 400 * 2 ** i + Math.random() * 200))
}
}
}دقت کنید خود کلید فقط در هدر درخواست رفته و در هیچ پیام خطا یا لاگی چاپ نمیشود. اگر روزی خواستید بدنهی درخواست را لاگ کنید، شماره را جزئی ماسک کنید و متنهای حاوی کد ورود را اصلاً ننویسید.
تلاش دوباره پیامک؛ چه وقت امن است و چه وقت پیامک دوبار میرود؟
تلاش دوباره پیامک ظاهراً بدیهی است: درخواست شکست خورد، دوباره بفرست. اما یک تفاوت مهم هست. اگر پاسخ ۵۰۳ گرفتید، سرویسدهنده صریحاً گفته پیامکی ثبت نشده و تکرار بیخطر است. ولی اگر مهلت زمانی تمام شد، شما نمیدانید درخواست اصلاً به سرویسدهنده رسیده، پردازش شده و فقط پاسخش دیر آمده است یا نه. تکرار در این حالت ممکن است همان پیامک را دو بار برای مشتری بفرستد.
برای متنهای بیضرر مثل «سفارش شما ثبت شد» دو بار رسیدن بدترین حالتش یک کمحواسی است. ولی برای کد ورود، دو کد متفاوت پشت سر هم گیجکننده است و برای پیامهای مالی ممکن است گران تمام شود. سه راه برای مهار این خطر هست.
- اگر سرویسدهندهی شما فیلدی برای شناسهی یکتای درخواست دارد، همان را با یک مقدار ثابت برای هر پیام بفرستید تا تکرار را خودش تشخیص دهد.
- برای کد ورود، بهجای تلاش دوبارهی همان کد، اجازه دهید کاربر خودش دکمهی «ارسال مجدد» را بزند و کد قبلی را باطل کنید.
- تعداد تلاش را پایین نگه دارید، دو یا سه بار، و فاصله را افزایشی بگذارید تا یک سرویسدهندهی در حال بازیابی زیر فشار تازه نرود.
فاصلهی افزایشی با کمی تصادف
در نمونهی بالا فاصله بین تلاشها ۴۰۰ میلیثانیه، بعد ۸۰۰ و بعد ۱۶۰۰ است، بهعلاوهی عددی تصادفی تا ۲۰۰ میلیثانیه. بخش تصادفی کوچک است ولی مهم: اگر صدها درخواست همزمان شکست بخورند، همه در یک لحظهی واحد دوباره نمیآیند و سرویسدهنده فرصت نفس کشیدن دارد.
ارسال اس ام اس با node js برای هزاران شماره؛ صف و سقف همزمانی
وقتی ارسال اس ام اس با node js برای یک فهرست بلند لازم است، Promise.all روی کل آرایه سادهترین کار و بدترین کار است: هزاران اتصال همزمان باز میشود، سرویسدهنده با ۴۲۹ جواب میدهد و نیمی از پیامها شکست میخورند. چیزی که لازم دارید یک صف ساده با تعداد مشخصی کارگر است.
نمونهی زیر بدون هیچ بستهای یک «استخر» میسازد. هر کارگر یک آیتم برمیدارد، میفرستد، نتیجه را ثبت میکند و سراغ بعدی میرود. شکست یک پیام جلوی بقیه را نمیگیرد و در پایان فهرست موفقها و ناموفقها جدا در دست شماست.
import { sendSms } from './sms.mjs'
export async function sendMany(items, { concurrency = 5 } = {}) {
const ok = []
const failed = []
let next = 0
async function worker() {
while (next < items.length) {
const item = items[next++] // در Node.js اجرای همین خط یکپارچه است و دو کارگر یک آیتم نمیگیرند
try {
const res = await sendSms(item.phone, item.text)
ok.push({ phone: item.phone, res })
} catch (err) {
failed.push({ phone: item.phone, reason: err.message, retryable: Boolean(err.retryable) })
}
}
}
await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, worker))
return { ok, failed }
}
// نمونهی استفاده
const { ok, failed } = await sendMany(
[{ phone: '09120000001', text: 'نمونه' }, { phone: '09120000002', text: 'نمونه' }],
{ concurrency: 3 },
)
console.log('موفق:', ok.length, 'ناموفق:', failed.length)عدد مناسب برای concurrency را آزمایش و از مستندات سرویسدهنده معلوم کنید؛ بسیاری از آنها سقف درخواست در ثانیه دارند. برای فهرستهای واقعاً بزرگ، بهجای ماندن در حافظهی یک فرایند، پیامها را در یک صف پایدار بگذارید تا با راهاندازی دوبارهی سرور گم نشوند. اگر هدف شما تبلیغ و ارسال گروهی است، قوانین و ساعت مجاز در ارسال پیامک انبوه و قوانین ارسال پیامک تبلیغاتی را هم ببینید.
sms api در node js؛ چهار خطای رایج در تولید
کار با sms api در node js معمولاً در آزمایش درست است و در تولید به چند جای تکراری گیر میکند. این چهار مورد بیشترین تماس پشتیبانی را میسازند.
ارسال پیامک داخل مسیر پاسخ به کاربر
اگر فراخوانی پیامک را قبل از res.send بگذارید و سرویسدهنده هشت ثانیه کند باشد، کاربر هم هشت ثانیه صفحهی خالی میبیند. پیام را در پسزمینه یا از یک صف بفرستید و جواب HTTP را زودتر بدهید؛ فقط برای کد ورود مسیر را طوری بنویسید که اگر ارسال شکست خورد کاربر پیام قابلفهمی ببیند.
نبودن مهلت زمانی
بدون signal یا timeout، یک اتصال نیمهباز میتواند ساعتها باز بماند. هر درخواست خروجی در سرور شما باید مهلت داشته باشد.
لاگکردن کل پاسخ و بدنه
کلید، شمارهی کامل کاربران و متنهای حاوی کد ورود نباید در لاگ بمانند. شناسهی پیام و آخر شماره کافی است.
فرض کردن «۲۰۰ یعنی رسید»
پاسخ موفق یعنی سرویسدهنده پیام را پذیرفته، نه اینکه به گوشی رسیده. اگر رسیدن مهم است، گزارش تحویل سرویسدهنده را بررسی کنید و بدانید ممکن است با تأخیر بیاید. دلایل نرسیدن در پیامک نمیرسه جمع شده است.
تست ارسال پیامک بدون فرستادن حتی یک پیامک واقعی
تست ارسال پیامک نباید از سرویسدهندهی واقعی استفاده کند: هم پول خرج میشود و هم نتیجه به شبکه بستگی پیدا میکند. سادهترین راه در Node.js این است که یک سرور HTTP محلی بالا بیاورید که رفتار سرویسدهنده را تقلید میکند، مثلاً یک بار ۵۰۳ بدهد و بار دوم ۲۰۰، و آدرس آن را به ماژول بدهید. ماژول ما آدرس را از متغیر محیطی میخواند و برای همین جداسازی ساده است.
نمونهی زیر با اجراکنندهی تست داخلی Node نوشته شده، پس بستهی اضافه نمیخواهد. با دستور node --test اجرایش کنید.
import test from 'node:test'
import assert from 'node:assert/strict'
import http from 'node:http'
test('بعد از 503 دوباره میفرستد و موفق میشود', async () => {
let calls = 0
const server = http.createServer((req, res) => {
calls++
res.statusCode = calls < 2 ? 503 : 200
res.setHeader('Content-Type', 'application/json')
res.end('{"id":"t1"}')
})
await new Promise((r) => server.listen(0, r))
// پیش از import باید متغیرها مقدار بگیرند، چون ماژول آنها را در بالای فایل میخواند
process.env.SMS_API_URL = 'http://127.0.0.1:' + server.address().port
process.env.SMS_API_KEY = 'test-key'
process.env.SMS_SENDER = '1000'
const { sendSms } = await import('./sms.mjs')
const res = await sendSms('09120000000', 'نمونه')
assert.equal(res.id, 't1')
assert.equal(calls, 2)
server.closeAllConnections?.()
server.close()
})
test('شمارهی نامعتبر اصلاً درخواستی نمیفرستد', async () => {
const { sendSms } = await import('./sms.mjs')
await assert.rejects(() => sendSms('123', 'نمونه'), { name: 'SmsError' })
})همین الگو را برای حالتهای دیگر هم میشود تکرار کرد: سرور محلیای که هرگز جواب نمیدهد تا مهلت زمانی را آزمایش کنید، یا یکی که همیشه ۴۰۱ برمیگرداند تا مطمئن شوید ماژول بیخود تکرار نمیکند. چنین تستهایی چند ثانیه طول میکشند و در هر تغییر ماژول جلوی برگشت خطاهای قدیمی را میگیرند.
کلید و تنظیمات؛ کجا نگه دارید و چطور بچرخانید
کلید پیامک مستقیماً پول شما را خرج میکند و کسی که آن را داشته باشد میتواند با اعتبار شما پیام بفرستد. چند عادت ساده خطرش را کم میکند.
- فقط در متغیر محیطی یا مدیر رازها کلید را در مخزن کد، فایل پیکربندی عمومی و کد فرانتاند نگذارید. فایل env را در gitignore بگذارید و در سرور از مدیر رازهای همان بستر استفاده کنید.
- کلید جدا برای هر محیط برای توسعه، آزمایش و تولید کلید جدا بگیرید. اگر سرویسدهنده اجازه میدهد، کلید توسعه را به یک سقف اعتبار پایین محدود کنید.
- امکان تعویض بدون بازنویسی کد شما فقط باید process.env را بخواند. وقتی کلید لو رفت، تعویض آن یک تغییر تنظیمات است، نه یک انتشار تازه.
- هشدار اعتبار اگر سرویسدهنده ماندهی اعتبار را از طریق API میدهد، یک بررسی روزانه بنویسید. اتمام اعتبار نیمهشب، یعنی نرسیدن کد ورود به همهی کاربران.
- سقف داخلی خودتان مستقل از سقف سرویسدهنده، برای هر شماره و هر ساعت سقفی بگذارید تا یک حمله یا یک باگ حلقهای حساب شما را خالی نکند. جزئیات حمله در sms bombing آمده است.
کدام پیامها را باید پیامک کرد و کدام را نه؟
ارسال پیامک node js یک هزینهی تکرارشونده است. اگر کلاً پیامک در نود را بیحساب صدا بزنید، قبض آخر ماه غافلگیرتان میکند. هر پیام پول دارد، ممکن است دیر برسد و در برخی موارد فیلتر شود. برای همین پیش از اینکه تابع sendSms را در همهجای برنامه صدا بزنید، ارزش دارد هر پیام را بسنجید.
پیامی که حتماً باید پیامک باشد، معمولاً پیامی است که گیرنده را وقتی اپ شما را ندارد یا هیچ راه دیگری برای رسیدن به او نیست خبردار میکند: کد تأیید شماره در اولین ثبتنام، هشدار پرداخت یا کد رهگیری برای کسی که فقط شمارهاش را دارید. اما بخش بزرگی از پیامکهای متداول، مثل «ورود شما موفق بود»، «سفارش ارسال شد» و یادآوریهای تکراری، به کانالی نیاز دارند که ارزانتر است و به اپ و مرورگر کاربر دسترسی دارد.
تفاوت پیامهای تراکنشی و تبلیغاتی در پیامک تراکنشی و تبلیغاتی توضیح داده شده و هزینهی هر نوع در هزینه پیامک سایت قابلحساب است.
فینگت کجای این تصویر قرار میگیرد؟
فینگت یک سرویس پیامک نیست و خط یا پنل ارسال پیامک نمیفروشد. این صفحه برای ارسال پیامک از طریق سرویسدهندهی خودتان است. چیزی که فینگت میدهد دو کار است که پیامکهای لازم شما را کمتر میکنند.
کار اول ورود بدون رمز و بدون کد پیامکی است. کاربری که اپ فینگت دارد، ورود را در گوشی تأیید میکند و سایت شما هیچ کدی نمیسازد و هیچ پیامکی نمیفرستد. شمارهی او هنگام ساخت حساب در اپ فینگت تأیید شده و سرور شما آن را همراه با نام و یک شناسهی ثابت میگیرد. کار دوم اعلان از طریق اپ است برای کاربرانی که آن را نصب کردهاند؛ مفهوم کلیاش در پیامک یا نوتیفیکیشن مقایسه شده است. اپ فعلاً فقط برای اندروید است، پس پیامک شما برای بقیهی کاربران سر جایش میماند.
نمونهی زیر همان ورود را در Node.js نشان میدهد. در عمل بهجای ساختن کد، جدول و حساب هزینهی هر ورود، دو مسیر کوتاه دارید. کلید API و شناسهی سایت را از پنل سرویسدهندگان میگیرید و آدرس بازگشت را هم همانجا ثبت میکنید.
نمونهی ورود با فینگت در Node.js با Express
این نمونه فرض میکند express و express-session را نصب کردهاید. لینک ورود یک مقدار تصادفی state میسازد و در بازگشت همان را مقایسه میکند، سپس کد کوتاهعمر را با کلید سرور به اطلاعات کاربر تبدیل میکند.
import express from 'express'
import session from 'express-session'
import crypto from 'node:crypto'
const app = express()
app.use(session({ secret: process.env.SESSION_SECRET, resave: false, saveUninitialized: false }))
app.get('/login/finget', (req, res) => {
req.session.fgState = crypto.randomBytes(16).toString('hex')
res.redirect('https://finget.ir/auth?client_id=' + process.env.FINGET_SITE_ID + '&state=' + req.session.fgState)
})
// همین آدرس را در پنل سرویسدهندگان بهعنوان آدرس بازگشت ثبت کنید
app.get('/login/finget/callback', async (req, res) => {
const expected = req.session.fgState
delete req.session.fgState
if (!expected || req.query.state !== expected) return res.sendStatus(400)
const r = await fetch('https://finget.ir/api/v1/auth/token', {
method: 'POST',
headers: { 'Content-Type': 'application/json', Authorization: 'Bearer ' + process.env.FINGET_API_KEY },
body: JSON.stringify({ code: String(req.query.code || '') }),
signal: AbortSignal.timeout(8000),
})
const data = await r.json().catch(() => null)
if (!data?.user?.id) return res.sendStatus(401)
// data.user شامل id، name و phone است؛ data.isNew میگوید کاربر تازه است
req.session.regenerate(() => {
req.session.fingetId = data.user.id
res.redirect('/')
})
})
app.listen(3000)کد بالا نه sendSms دارد، نه صف و نه تلاش دوباره، چون پیامکی در کار نیست. این روش را کنار ورود پیامکی فعلی بگذارید و کاربران اپ را از هزینهی هر کد معاف کنید. مفهوم کلیاش در ورود بدون رمز عبور و مقایسهی آن با کد پیامکی در جایگزین otp پیامکی آمده است. اگر میخواهید خود ورود پیامکی را هم در Node بسازید، otp node js کد کامل آن را دارد؛ برای دیدن اپ هم صفحهی دانلود را ببینید.
پرسشهای متداول درباره ارسال پیامک node js
برای ارسال پیامک node js حتماً باید از کتابخانهی سرویسدهنده استفاده کنم؟
نه. در ارسال پیامک node js اگر سرویسدهندهی شما وبسرویس HTTP دارد، یک فراخوانی fetch کافی است و همینطور کنترل بیشتری روی مهلت و تلاش دوباره دارید. کتابخانهی رسمی فقط وقتی ارزش دارد که ویژگیهای اضافه مثل بررسی خودکار امضا یا قالبها را بدهد و خودتان نخواهید آنها را بنویسید.
تلاش دوباره پیامک میتواند پیام را دوبار بفرستد؟
بله، مخصوصاً اگر مهلت زمانی تمام شود و شما ندانید درخواست رسیده بود یا نه. برای کد ورود تلاش خودکار نکنید و اجازه دهید کاربر ارسال مجدد را بزند؛ برای پیامهای کماهمیت، تعداد تلاش را پایین نگه دارید و اگر سرویسدهنده شناسهی یکتای درخواست میپذیرد از آن استفاده کنید.
چند پیامک را همزمان بفرستم؟
عدد قطعی ندارد و به سقف درخواست در ثانیهی سرویسدهندهی شما بستگی دارد. با پنج یا ده همزمانی شروع کنید، نرخ خطای ۴۲۹ را ببینید و مطابق مستندات خودشان تنظیم کنید.
پاسخ ۲۰۰ از سرویسدهنده یعنی پیامک به گوشی رسیده؟
نه. معمولاً یعنی پیام را برای ارسال پذیرفته است. رسیدن واقعی به اپراتور و گوشی بعداً و ممکن است با تأخیر یا شکست انجام شود. اگر رسیدن برایتان حیاتی است از گزارش تحویل سرویسدهنده کمک بگیرید.
تست ارسال پیامک را چطور بدون هزینه انجام دهم؟
یک سرور HTTP محلی بسازید که پاسخ سرویسدهنده را تقلید میکند و آدرس آن را از طریق متغیر محیطی به ماژول بدهید. اینطور هیچ پیام واقعی نمیرود و میتوانید حالتهای خطا، کندی و موفقیت را هر بار با همان نتیجه تکرار کنید.
فینگت میتواند جای سرویسدهندهی پیامکی من را بگیرد؟
نه. فینگت پنل یا خط پیامک نمیدهد. فقط برای کاربرانی که اپ دارند، ورود بدون پیامک و اعلان از طریق اپ را فراهم میکند و همین، تعداد پیامکهای لازم را کم میکند. چون اپ فعلاً اندروید است، پیامک برای بقیهی کاربران میماند.
کلید API فینگت را کجا نگه دارم؟
فقط سمت سرور و در متغیر محیطی. کلید را به مرورگر یا کد فرانتاند نفرستید و فقط شناسهی سایت را در لینک ورود بگذارید.