Skip to content
Meta Business PartnerDeveloper how-to

WhatsApp API with Node.js: send messages and receive webhooks

Node.js 18 and later ship with fetch, so sending WhatsApp messages needs no packages at all. This guide builds a small client for InfiQ's API, which takes the same message bodies as Meta's WhatsApp Cloud API, then receives replies and delivery updates in Express and in a Next.js route handler.

18 or later (built-in fetch)
Node.js
None to send; express for the receiver
Packages
POST https://api.infiq.in/v1/messages
Endpoint
express.raw() or await req.arrayBuffer()
Raw body
crypto.timingSafeEqual
Comparison
process.env.INFIQ_API_KEY, server only
Key

In short

Call fetch with a POST to https://api.infiq.in/v1/messages, your key in X-INFIQ-API-KEY from process.env and the message JSON as the body. Wrap it in a send() that adds an Idempotency-Key and retries on 429 and server errors. For webhooks, keep the raw body (express.raw() or await req.arrayBuffer()), verify X-InfiQ-Signature with crypto.timingSafeEqual and answer quickly.

A send() client with safe retries

One function adds the key, a stable Idempotency-Key, a wait on 429 until X-RateLimit-Reset and backoff on server errors. Other 4xx errors are thrown, because sending the same body again won't fix them.

// Node 18+ (global fetch)
import { randomUUID } from "node:crypto";
const API = "https://api.infiq.in/v1/messages";
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
export async function send(body, { idempotencyKey = randomUUID(), attempts = 5 } = {}) {
for (let attempt = 1; attempt <= attempts; attempt++) {
const res = await fetch(API, {
method: "POST",
headers: {
"X-INFIQ-API-KEY": process.env.INFIQ_API_KEY,
"Content-Type": "application/json",
"Idempotency-Key": idempotencyKey,
},
body: JSON.stringify(body),
});
const data = await res.json();
if (res.ok) return data.messages[0].id; // wamid…
if (res.status === 429) {
const reset = Number(res.headers.get("X-RateLimit-Reset")) * 1000;
await sleep(Math.max(reset - Date.now(), 1000));
} else if (res.status >= 500) {
await sleep(2 ** attempt * 500);
} else {
throw new Error(`${data.error?.code}: ${data.error?.message} (${data.InfiQ_traceid})`);
}
}
throw new Error(`gave up after ${attempts} attempts`);
}

Send a template, then buttons

Each message type is its Cloud API body. The template, with an image header, works at any time; reply buttons are an interactive message and need an open 24-hour window. Button titles can be up to 20 characters, and a message can carry up to three.

import { send } from "./infiq.js";
const to = "919820000001";
await send({
messaging_product: "whatsapp",
to,
type: "template",
template: {
name: "shipment_update",
language: { code: "en" },
components: [
{ type: "header", parameters: [{ type: "image", image: { link: "https://www.infiq.in/media/box.jpg" } }] },
{ type: "body", parameters: [{ type: "text", text: "INF-3091" }] },
],
},
}, { idempotencyKey: "INF-3091-shipped" });
// Inside the 24-hour window: reply buttons
await send({
messaging_product: "whatsapp",
to,
type: "interactive",
interactive: {
type: "button",
body: { text: "Confirm your appointment for 18 Jul, 10:30 AM?" },
action: {
buttons: [
{ type: "reply", reply: { id: "confirm_1030", title: "Confirm" } },
{ type: "reply", reply: { id: "reschedule", title: "Reschedule" } },
],
},
},
});

Receive webhooks in Express or Next.js

Both receivers keep the raw body for the signature check, then parse it. In Express that means express.raw() on the route; in a Next.js route handler, read the body as bytes before parsing. The check itself is in the third tab.

import express from "express";
import { verifyInfiqSignature } from "./verify.js";
const app = express();
app.post("/webhooks/infiq", express.raw({ type: "application/json" }), (req, res) => {
if (!verifyInfiqSignature(req.get("X-InfiQ-Signature"), req.body)) {
return res.sendStatus(401);
}
const event = JSON.parse(req.body.toString("utf8"));
if (event.type === "message.received") {
const { from, content } = event.data.message;
console.log(from, content.text);
}
res.sendStatus(200);
});
app.listen(3000);

Keep the key on the server

The API key can send messages from your number, so treat it like a password:

  • Never give it a NEXT_PUBLIC_ or VITE_ prefix, and never call the API from React or any other browser code.
  • Use a sandbox key (isk_test_…) in development and CI, and a live key only in production.
  • Rotate keys from the dashboard if one leaks. InfiQ posts apikey.rotated and apikey.revoked webhooks, so other systems learn about it.

Get your InfiQ API key

Frequently asked questions

Do I need a WhatsApp npm package to use the API from Node.js?+
No. Meta's official Node.js SDK for the Cloud API was archived in 2023, and plain fetch is enough for InfiQ's API: one POST per message with your API key.
Can I use whatsapp-web.js or Baileys instead?+
They automate the WhatsApp app through WhatsApp Web; they aren't the official Business API. WhatsApp doesn't allow automated or bulk business messaging that way, and numbers used for it get banned.
Why is my Express webhook signature always invalid?+
express.json() has already parsed the body, and the check needs the exact bytes. Use express.raw({ type: "application/json" }) on the webhook route and pass the Buffer to the check.
Can I call the WhatsApp API from React in the browser?+
No. The API key would be visible to anyone who opens the page. Call your own backend or a Next.js route handler, and let that call InfiQ.