WhatsApp API in Node.js: send a WhatsApp message from Node.js and Express, a complete example
Sending a WhatsApp message from Node.js through the official API: one function with the built-in fetch, sending an approved template and reading its status, an Express route that sends a shipping notice, and the common mistakes.
On this page 7
The short answer
To send a WhatsApp message from Node.js the fetch built into version 18 and later is enough: a call to POST https://app.arabybot.com/api/v1/messages/template with your key in the Authorization header and a JSON body holding the recipient's number, the approved template's name and its variables. The call goes from the server only, never from the browser. This is the official route; WhatsApp Web session libraries are unofficial and put the number at risk of a ban.
Also asked as: «whatsapp api node js» · «ارسال رسالة واتساب node js» · «ارسال واتساب جافاسكربت» · «whatsapp api javascript» · «nodejs send whatsapp message» · «express whatsapp api»
The official route, not a WhatsApp Web session
The best-known thing a search for WhatsApp in Node.js turns up is libraries that run a WhatsApp Web session and send from it. Easy at first, then comes what nobody planned for: WhatsApp restricts accounts whose activity looks automated, then bans them, and the session drops and needs the code scanned again. The code here sends through the official WhatsApp Business Platform from your number connected to ArabyBot, with no session and no code to scan.
How long a WhatsApp ban lasts, and its kinds · The WhatsApp Business app or the WhatsApp API?
What you need
- A WhatsApp number connected to ArabyBot with at least one approved template.
- A plan that includes «Developer tools»: WhatsApp Pro, WhatsApp Premium, Complete Plan or Ultimate Plan.
- A key from the «Developer tools» page; it starts with
abk_and is shown once. Put it in theARABYBOT_API_KEYenvironment variable on the server.
One function with the built-in fetch
// arabybot.mjs — Node.js 18 or newer: fetch is built in, nothing to install.
const BASE = 'https://app.arabybot.com/api/v1';
const KEY = process.env.ARABYBOT_API_KEY;
export async function arabybot(method, path, body) {
try {
const res = await fetch(`${BASE}/${path}`, {
method,
headers: {
Authorization: `Bearer ${KEY}`,
...(body ? { 'Content-Type': 'application/json' } : {}),
},
body: body ? JSON.stringify(body) : undefined,
signal: AbortSignal.timeout(20000),
});
return await res.json();
} catch {
return { success: false, error_code: 'NETWORK' };
}
}
const me = await arabybot('GET', 'me'); // does the key work, and from which numbers?
const templates = await arabybot('GET', 'templates'); // each template has a ready body in "example" The file has the .mjs extension so await works at the top level. AbortSignal.timeout cuts the request after twenty seconds instead of leaving it hanging.
Sending a template and reading its status
import { arabybot } from './arabybot.mjs';
const sent = await arabybot('POST', 'messages/template', {
to: '201012345678', // with the country code
template: 'order_shipped',
language: 'ar',
variables: ['Ahmed', '1042'], // the template's {{1}}, {{2}} in order
reference: 'order-1042-shipped', // the same reference is never sent twice
});
if (sent.success) {
await saveMessageId(orderId, sent.id); // "accepted", or "queued": it goes out by itself
} else if (['TRY_AGAIN', 'NETWORK'].includes(sent.error_code)) {
await retryLater(orderId); // same request, same reference
} else if (sent.error_code === 'UNCERTAIN') {
await checkLater(sent.id); // ask GET messages/{id} before sending again
} else {
console.error(sent.error_code, sent.message_en);
}
const status = await arabybot('GET', 'messages/512'); // queued · accepted · sent · delivered · read · failed A successful answer has the status accepted or queued. The second is not an error: it means your number's messages leave at the pace WhatsApp accepts and this one waits its turn for moments. reference protects you when your server repeats the request after a drop: the answer returns the first message with duplicate: true.
Every field, refusal code and limit, in the send API reference
A practical example: a shipping notice from an Express server
import express from 'express';
import { arabybot } from './arabybot.mjs';
const app = express();
app.use(express.json());
// your shop calls this when an order ships
app.post('/orders/:id/shipped', async (req, res) => {
const { phone, name } = req.body;
const sent = await arabybot('POST', 'messages/template', {
to: phone,
template: 'order_shipped',
language: 'ar',
variables: [name, req.params.id],
reference: `order-${req.params.id}-shipped`,
});
res.status(sent.success ? 200 : 502).json({ ok: Boolean(sent.success), code: sent.error_code ?? null });
});
app.listen(3000); Your shop's system calls this route when the order ships, and the route sends the template from your number. If your shop is on Shopify, WooCommerce, Easy Orders or LightFunnels you do not need this code at all: order confirmation and status messages work from the ready connection.
Common Node.js mistakes
| The mistake | What happens | The fix |
|---|---|---|
| The key in front-end code | Every visitor sees it and can send from your number | The server only, and process.env |
A forgotten await | You read a promise, not an answer, so every request looks successful | await before every call |
A body without JSON.stringify | BAD_JSON | As in the function above |
Promise.all over thousands of messages | You pass 600 requests a minute and get 429 | Send in small consecutive batches |
| Retrying every refusal | Useless requests | Retry TRY_AGAIN only |
The same walkthrough in PHP · And in Python · And from n8n with no code
Frequently asked questions
Should I use WhatsApp Web libraries in Node.js?
We do not recommend them for a business number. These libraries run a WhatsApp Web session and send from it automatically, and they are unofficial: WhatsApp treats automated sending from the app as a violation that ends in a restricted or banned account. The code on this page sends through the official WhatsApp Business Platform.
Can I call the API from the browser or a React app?
No. The key sends from your number, and any code that runs in the browser is visible to the visitor. Call the API from your server, and let the front end ask your own server.
Which Node.js version do I need?
Version 18 or newer, which has fetch and AbortSignal.timeout built in. On an older version use a request library you know: the API is ordinary HTTP calls.
How do I know the message arrived without asking every time?
Ask for the status only when you need it, such as when the order page is opened in your panel. The message also shows in the live chat inside ArabyBot with its delivered and read marks.
Read next
Try the agent before you pay anything
The agent that will answer your customers is the one answering you now: ask it from the chat button here or on WhatsApp. Your account is free with no credit card, and the free trial on your own number or page is activated after you contact our team on customer-service WhatsApp.