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.
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 buttonsawait 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.