- \n
- Executive Summary<\/a><\/li>\n\n\n\n
- TL;DR<\/a><\/li>\n\n\n\n
- Prerequisites and Project Setup<\/a><\/li>\n\n\n\n
- Your First Send: Native fetch<\/a><\/li>\n\n\n\n
- Timeouts: The Footgun Nobody Mentions<\/a><\/li>\n\n\n\n
- A Reusable Client with Keep-Alive and Types<\/a><\/li>\n\n\n\n
- Concurrency: The Part Node Developers Get Wrong<\/a><\/li>\n\n\n\n
- Message Length, Encoding and Segments<\/a><\/li>\n\n\n\n
- India Specific: DLT Entity IDs, Templates and Pre-Send Validation<\/a><\/li>\n\n\n\n
- OTP in Node.js: Generate and Verify<\/a><\/li>\n\n\n\n
- Receiving Delivery Reports in Express<\/a><\/li>\n\n\n\n
- Polling Delivery Reports with Async Iterators<\/a><\/li>\n\n\n\n
- Errors, Retries and Idempotency<\/a><\/li>\n\n\n\n
- Queue Workers with BullMQ and Graceful Shutdown<\/a><\/li>\n\n\n\n
- Testing Without Sending Real SMS<\/a><\/li>\n\n\n\n
- Observability and Scaling Notes<\/a><\/li>\n\n\n\n
- Production Readiness Checklist<\/a><\/li>\n\n\n\n
- Common Mistakes and How to Fix Them<\/a><\/li>\n\n\n\n
- FAQs<\/a><\/li>\n<\/ol>\n\n\n\n
\n\n\n\n1. Executive Summary<\/h2>\n\n\n\n
Sending an SMS from Node.js is one
fetch<\/code> call. Running an SMS integration in Node.js without waking up to a duplicated OTP, an exhausted socket pool or a queue that silently dropped four hundred messages during a deploy is a different exercise entirely.<\/p>\n\n\n\nNode makes two specific problems worse than most runtimes. The first is that concurrency is effectively free, so it is trivially easy to open two hundred simultaneous connections to a gateway and get throttled, which is a mistake a synchronous language makes you work for. The second is that
fetch<\/code> has no default timeout, so a stalled request hangs until the operating system gives up, and the promise you awaited simply never settles. Both are avoidable and both are absent from every Node SMS tutorial currently ranking.<\/p>\n\n\n\nThis guide covers the full path against real endpoints on the SMSGatewayCenter API. Every URL, method and parameter is taken verbatim from the live developer API documentation<\/a>. If you want the language-agnostic orientation first, read the SMS API getting started guide<\/a>. If your stack is PHP rather than Node, the sibling walkthrough is SMS API in PHP: full integration tutorial<\/a>.<\/p>\n\n\n\n
![\"Diagram](\"https:\/\/www.smsgatewaycenter.com\/blog\/wp-content\/uploads\/2026\/08\/sms-api-in-node-js.webp\")
<\/a><\/figure>\n\n\n\n2. TL;DR<\/h2>\n\n\n\n
POST to
https:\/\/unify.smsgateway.center\/SMSApi\/send<\/code> withapplication\/x-www-form-urlencoded<\/code> body containinguserid<\/code> andpassword<\/code> (or send anapikey<\/code> HTTP header instead), plussendMethod=quick<\/code>,mobile<\/code>,msg<\/code>,senderid<\/code>,msgType=text<\/code> andoutput=json<\/code>. For Indian recipients adddltEntityId<\/code> anddltTemplateId<\/code>. ReadtransactionId<\/code> from the JSON response and persist it. Treat the 200 as accepted, not delivered.<\/p>\n\n\n\nThree Node-specific things to do immediately: attach an
AbortSignal.timeout()<\/code> to every request, because fetch will otherwise hang indefinitely; set anundici<\/code> Agent with keep-alive so you are not renegotiating TLS per message; and bound your concurrency with a limiter rather than handing an array of a thousand promises toPromise.all<\/code>.<\/p>\n\n\n\n
\n\n\n\n3. Prerequisites and Project Setup<\/h2>\n\n\n\n
Node.js 20 LTS or newer.<\/strong> Node 18 introduced global
fetch<\/code>, Node 20 stabilised it, andAbortSignal.timeout()<\/code> is available from 17.3. Everything below runs on 20 and 22 without a polyfill. On Node 16 or older<\/a> you neednode-fetch<\/code> oraxios<\/code>, and Node 16 has been end of life since September 2023.<\/p>\n\n\n\nAn SMSGatewayCenter account with an approved sender ID.<\/strong> India headers are alphanumeric and capped at six characters. Create one in the panel or via
POST https:\/\/unify.smsgateway.center\/SMSApi\/senderid\/create<\/code>, documented at Create Sender ID<\/a>. Approval takes time, so start it before you write code.<\/p>\n\n\n\nFor Indian traffic, a registered DLT entity and approved templates.<\/strong> Not optional. The DLT hub page<\/a> covers registration; section 9 covers the API side.<\/p>\n\n\n\n
Dependencies<\/h3>\n\n\n\n
The core integration needs zero runtime dependencies on Node 20. These are for the parts around it:<\/p>\n\n\n\n
npm init -y\nnpm pkg set type=module\nnpm i undici p-limit bullmq ioredis express libphonenumber-js pino zod\nnpm i -D typescript tsx vitest nock @types\/node @types\/express\n<\/code><\/pre>\n\n\n\nundici<\/code> is Node’s own HTTP client, the one that backs globalfetch<\/code>. You install it explicitly only to configure the connection pool.p-limit<\/code> is four lines of logic you could write yourself, but it is correct and battle-tested.zod<\/code> is for validating the gateway response shape at the boundary rather than trusting it.<\/p>\n\n\n\nThe developer docs publish PHP<\/a> and Python SDKs plus a Postman collection<\/a>, and there is a Node example using
unirest<\/code> on the enterprise docs site. No official Node package is listed alongside the PHP and Python SDKs in the developer-api sidebar, so this guide builds against the HTTP API directly, which is the right call anyway: you own the timeout, retry and observability behaviour instead of inheriting someone else’s.<\/p>\n\n\n\nEnvironment<\/h3>\n\n\n\n
# .env\nSGC_BASE_URL=https:\/\/unify.smsgateway.center\nSGC_API_KEY=your_api_key_here\nSGC_SENDER_ID=SMSGAT\nSGC_DLT_ENTITY_ID=1201159xxxxxxxxxxx\nREDIS_URL=redis:\/\/127.0.0.1:6379\n<\/code><\/pre>\n\n\n\nLoad with
node --env-file=.env app.js<\/code> on Node 20.6+ and skip thedotenv<\/code> dependency entirely.<\/p>\n\n\n\n
\n\n\n\n4. Your First Send: Native fetch<\/h2>\n\n\n\n
\/\/ send-once.js\nconst params = new URLSearchParams({\n sendMethod: 'quick',\n mobile: '919999999999',\n msg: 'Your order 4821 has shipped. Track it at https:\/\/example.com\/t\/4821',\n senderid: process.env.SGC_SENDER_ID,\n msgType: 'text',\n duplicatecheck: 'true',\n output: 'json',\n});\n\nconst response = await fetch(`${process.env.SGC_BASE_URL}\/SMSApi\/send`, {\n method: 'POST',\n headers: {\n 'Content-Type': 'application\/x-www-form-urlencoded',\n apikey: process.env.SGC_API_KEY,\n },\n body: params,\n signal: AbortSignal.timeout(15_000),\n});\n\nconst result = await response.json();\nconsole.log(response.status, result);\n<\/code><\/pre>\n\n\n\nA successful response:<\/p>\n\n\n\n
{\n \"status\": \"success\",\n \"mobile\": \"919999999999\",\n \"invalidMobile\": \"\",\n \"transactionId\": \"a1b2c3d4-...\",\n \"statusCode\": \"200\",\n \"reason\": \"success\"\n}\n<\/code><\/pre>\n\n\n\nThree details in that snippet are load-bearing.<\/p>\n\n\n\n
URLSearchParams<\/code> passed directly asbody<\/code> makes fetch set the form-encoded content type and handle escaping. If you build the body by string concatenation, a message containing&<\/code> or a password containing+<\/code> silently corrupts the request, and the failure looks exactly like bad credentials. Do not hand-roll it.<\/p>\n\n\n\nThe
apikey<\/code> header replacesuserid<\/code> andpassword<\/code> in the body. Prefer it. It rotates independently of your panel password, can be issued per service so a leak has a bounded blast radius, and headers are far less likely to end up in an access log than a body or query string.<\/p>\n\n\n\nAbortSignal.timeout(15_000)<\/code> is the line most tutorials omit, and section 5 explains why it matters more than it looks.<\/p>\n\n\n\nThe Equivalent cURL<\/h3>\n\n\n\n
curl -X POST 'https:\/\/unify.smsgateway.center\/SMSApi\/send' \\\n -H 'Content-Type: application\/x-www-form-urlencoded' \\\n -H 'apikey: YOUR_API_KEY' \\\n --data-urlencode 'sendMethod=quick' \\\n --data-urlencode 'mobile=919999999999' \\\n --data-urlencode 'msg=Test message from cURL' \\\n --data-urlencode 'senderid=SMSGAT' \\\n --data-urlencode 'msgType=text' \\\n --data-urlencode 'output=json'\n<\/code><\/pre>\n\n\n\nUse POST, not GET. A GET request puts credentials and the full message body into the URL, where they land in web server logs, proxy logs and any CDN on the path. If the message is an OTP, that is a data leak as well as a credential leak.<\/p>\n\n\n\n
\n\n\n\n5. Timeouts: The Footgun Nobody Mentions<\/h2>\n\n\n\n
fetch<\/code> in Node has no default timeout.<\/strong> Not a long one. None. If the far end accepts your connection and then stops responding, the promise never settles. In a request handler that means a hung HTTP request. In a queue worker it means a job that occupies a slot forever, and with enough of them your worker stops processing anything at all.<\/p>\n\n\n\n\/\/ Wrong. This can hang until the OS gives up, which may be minutes.\nconst r = await fetch(url, { method: 'POST', body: params });\n\n\/\/ Right.\nconst r = await fetch(url, {\n method: 'POST',\n body: params,\n signal: AbortSignal.timeout(15_000),\n});\n<\/code><\/pre>\n\n\n\nCatch the abort specifically, because it is a different failure class from a rejection by the gateway:<\/p>\n\n\n\n
try {\n const r = await fetch(url, { method: 'POST', body: params, signal: AbortSignal.timeout(15_000) });\n} catch (err) {\n if (err.name === 'TimeoutError') {\n \/\/ Request may or may not have been accepted upstream. Retryable, but only\n \/\/ with an idempotency key, because the message might already be in flight.\n }\n if (err.name === 'AbortError') {\n \/\/ Someone aborted deliberately, for example a shutdown signal.\n }\n throw err;\n}\n<\/code><\/pre>\n\n\n\nThat comment on
TimeoutError<\/code> is the important one. A timeout is ambiguous: the gateway may have accepted and dispatched the message before the response was lost. Retrying without an idempotency key is how customers receive the same OTP twice. Section 13 handles it.<\/p>\n\n\n\nTo combine a timeout with your own cancellation signal, for example a shutdown handler<\/a>, use
AbortSignal.any<\/code>:<\/p>\n\n\n\nconst signal = AbortSignal.any([AbortSignal.timeout(15_000), shutdownController.signal]);\n<\/code><\/pre>\n\n\n\n
\n\n\n\n6. A Reusable Client with Keep-Alive and Types<\/h2>\n\n\n\n
Per-call fetch is fine for a script. For a service you want one client that owns the connection pool, timeouts, auth and response parsing.<\/p>\n\n\n\n
\/\/ src\/sms\/client.ts\nimport { Agent, request } from 'undici';\nimport { z } from 'zod';\n\nconst SendResponse = z.object({\n status: z.string(),\n mobile: z.string().optional(),\n invalidMobile: z.string().optional().default(''),\n transactionId: z.union([z.string(), z.number()]).optional(),\n statusCode: z.union([z.string(), z.number()]),\n reason: z.string().optional().default(''),\n});\n\nexport type SendResponse = z.infer<typeof SendResponse>;\n\nexport class SmsTransportError extends Error {\n readonly retryable = true;\n constructor(message: string, options?: ErrorOptions) {\n super(message, options);\n this.name = 'SmsTransportError';\n }\n}\n\nexport class SmsApiError extends Error {\n readonly retryable = false;\n constructor(message: string, readonly statusCode: string) {\n super(message);\n this.name = 'SmsApiError';\n }\n}\n\nexport class SmsClient {\n #agent: Agent;\n\n constructor(\n private readonly baseUrl: string,\n private readonly apiKey: string,\n opts: { connections?: number; timeoutMs?: number } = {},\n ) {\n this.#agent = new Agent({\n connections: opts.connections ?? 16,\n keepAliveTimeout: 30_000,\n keepAliveMaxTimeout: 60_000,\n headersTimeout: opts.timeoutMs ?? 15_000,\n bodyTimeout: opts.timeoutMs ?? 15_000,\n });\n }\n\n async post(path: string, fields: Record<string, string | number>): Promise<SendResponse> {\n const body = new URLSearchParams(\n Object.entries({ ...fields, output: 'json' }).map(([k, v]) => [k, String(v)]),\n ).toString();\n\n let res;\n try {\n res = await request(`${this.baseUrl}${path}`, {\n method: 'POST',\n dispatcher: this.#agent,\n headers: {\n 'content-type': 'application\/x-www-form-urlencoded',\n apikey: this.apiKey,\n },\n body,\n });\n } catch (cause) {\n throw new SmsTransportError(`Could not reach the SMS gateway: ${(cause as Error).message}`, { cause });\n }\n\n const text = await res.body.text();\n\n if (res.statusCode >= 500) {\n throw new SmsTransportError(`Gateway returned HTTP ${res.statusCode}`);\n }\n\n let json: unknown;\n try {\n json = JSON.parse(text);\n } catch {\n throw new SmsTransportError(`Gateway returned a non-JSON body: ${text.slice(0, 200)}`);\n }\n\n return SendResponse.parse(json);\n }\n\n async close() {\n await this.#agent.close();\n }\n}\n<\/code><\/pre>\n\n\n\nTwo things here are worth more than they look.<\/p>\n\n\n\n
Keep-alive.<\/strong> Without a configured agent, every message can pay a fresh TCP handshake plus a TLS negotiation. Over a batch of ten thousand that is a large amount of latency and CPU spent on nothing. Setting
connections<\/code> also caps how many sockets you will ever open to this host, which is a second safety net under the concurrency limiter in section 7.<\/p>\n\n\n\nParsing at the boundary with zod.<\/strong> Note
transactionId<\/code> is typed asstring | number<\/code>. Real APIs return\"0\"<\/code> in one endpoint and200<\/code> unquoted in another, and this one does exactly that: the send endpoint returns\"statusCode\": \"200\"<\/code> as a string while the WhatsApp endpoint returns\"statusCode\": 200<\/code> as a number. Coercing at the edge means the rest of your code does not carry defensiveString()<\/code> calls forever.<\/p>\n\n\n\nDo not throw on 4xx before reading the body.<\/strong> A rejection from this API arrives as JSON with a specific
statusCode<\/code> andreason<\/code> that you need in order to decide whether to retry. Any client that throws on non-2xx before parsing discards the diagnosis.<\/p>\n\n\n\nIf You Prefer axios<\/h3>\n\n\n\n
import axios from 'axios';\nimport { Agent } from 'https';\n\nexport const http = axios.create({\n baseURL: process.env.SGC_BASE_URL,\n timeout: 15_000,\n httpsAgent: new Agent({ keepAlive: true, maxSockets: 16 }),\n headers: { apikey: process.env.SGC_API_KEY },\n validateStatus: () => true, \/\/ parse the body yourself, do not throw on 4xx\n});\n<\/code><\/pre>\n\n\n\nvalidateStatus: () => true<\/code> is the axios equivalent of the “read the body before deciding” rule. Note that axiostimeout<\/code> covers response headers, not the full body download, which is usually fine for this API since the payloads are tiny.<\/p>\n\n\n\n
\n\n\n\n7. Concurrency: The Part Node Developers Get Wrong<\/h2>\n\n\n\n
Here is the code that appears in almost every Node SMS tutorial and should not survive contact with production:<\/p>\n\n\n\n
\/\/ Do not do this.\nawait Promise.all(recipients.map((r) => sendSms(r)));\n<\/code><\/pre>\n\n\n\nTwo independent failures. First, with ten thousand recipients this opens ten thousand concurrent requests, which will exhaust sockets, trigger throttling and quite possibly get your traffic treated as abusive. Second,
Promise.all<\/code> rejects on the first failure and abandons the results of everything else that was in flight, so one invalid number destroys your record of the nine thousand that succeeded.<\/p>\n\n\n\nUse a bounded limiter and
allSettled<\/code>:<\/p>\n\n\n\nimport pLimit from 'p-limit';\n\nexport async function sendBatch(client, messages, { concurrency = 8 } = {}) {\n const limit = pLimit(concurrency);\n\n const settled = await Promise.allSettled(\n messages.map((m) => limit(() => sendOne(client, m))),\n );\n\n const accepted = [];\n const failed = [];\n\n settled.forEach((outcome, i) => {\n if (outcome.status === 'fulfilled' && outcome.value.status === 'success') {\n accepted.push({ mobile: messages[i].mobile, transactionId: outcome.value.transactionId });\n } else {\n const reason =\n outcome.status === 'rejected'\n ? outcome.reason.message\n : `${outcome.value.statusCode}: ${outcome.value.reason}`;\n failed.push({ mobile: messages[i].mobile, reason });\n }\n });\n\n return { accepted, failed };\n}\n<\/code><\/pre>\n\n\n\n<\/blockquote>\n\n\n\n
![\"Illustration](\"https:\/\/www.smsgatewaycenter.com\/blog\/wp-content\/uploads\/2026\/08\/concurrency.webp\")
<\/a><\/figure>\n\n\n\nPick
concurrency<\/code> conservatively. The right ceiling depends on the throughput provisioned on your account, so start low, watch your acceptance rate and latency, and raise it deliberately. If you find yourself needing high sustained concurrency to keep up, HTTP is the wrong transport and you want a persistent SMPP bind instead. The tuning considerations are covered in SMPP rate limits and throughput tuning<\/a>, and connectivity requirements in the SMPP connectivity docs<\/a>.<\/p>\n\n\n\nBatch Sends Versus Per-Message Sends<\/h3>\n\n\n\n
- TL;DR<\/a><\/li>\n\n\n\n