Integrations

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.

8 min read Updated 15 November 2026 ArabyBot team
The ArabyBot teamOfficial Meta partner · written from our own platform data
On this page 7
  1. The official route, not a WhatsApp Web session
  2. What you need
  3. One function with the built-in fetch
  4. Sending a template and reading its status
  5. A practical example: a shipping notice from an Express server
  6. Common Node.js mistakes
  7. Frequently asked questions

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 the ARABYBOT_API_KEY environment 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 mistakeWhat happensThe fix
The key in front-end codeEvery visitor sees it and can send from your numberThe server only, and process.env
A forgotten awaitYou read a promise, not an answer, so every request looks successfulawait before every call
A body without JSON.stringifyBAD_JSONAs in the function above
Promise.all over thousands of messagesYou pass 600 requests a minute and get 429Send in small consecutive batches
Retrying every refusalUseless requestsRetry TRY_AGAIN only

The same walkthrough in PHP · And in Python · And from n8n with no code

Frequently asked questions

1

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.

2

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.

3

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.

4

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.

The ArabyBot teamOfficial Meta business partner in the Middle East 239 guides Figures from our platform All guides

How we write these guides Figures come from our platform and Meta's actual invoices, dated with their sample; we describe what works today, not what we plan, and say what we do not do and when someone else is the better choice. Reviewed by the ArabyBot team on 15 November 2026.

Share this guide
And you run all of it from your phoneEverything on this page is also run from the ArabyBot mobile app — replies, orders, campaigns and AI reports. Not a web dashboard only.

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.