Send a WhatsApp message

POSThttps://api.9bits.net/whatsapp/ng/v1/sendwhatsapp

Sends a single WhatsApp message to one recipient.

Request

Field	Type	Required	Description
to	string	✅	Recipient MSISDN in international format.
message_type	string	—	template or text. Inferred if omitted — see below.
template_name	string	—	The Meta-approved template. Required for template.
language	string	—	Template language code, e.g. en.
params	array	—	Values for the template’s {{1}}, {{2}}… placeholders, in order.
header_media_url	string	—	Media URL for a template with a media header.
text	string	—	Free-form body. Only valid for text, inside an open window.
wa_account_id	integer	—	Which sender to send from. Defaults to your account default.

`message_type` is inferred if you omit it

Supply text and it’s treated as text. Otherwise it’s treated as template.

Be explicit anyway — a template send that accidentally carries a stray text field will silently become a session message and get rejected outside a window.

Send a template

The only way to start a conversation.

cURL

curl -X POST https://api.9bits.net/whatsapp/ng/v1/sendwhatsapp \
  -H "Authorization: Bearer $NINEBITS_WA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "2348020000000",
    "message_type": "template",
    "template_name": "order_shipped",
    "language": "en",
    "params": ["Jane", "AB123"]
  }'

Node.js

const res = await fetch('https://api.9bits.net/whatsapp/ng/v1/sendwhatsapp', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NINEBITS_WA_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: '2348020000000',
    message_type: 'template',
    template_name: 'order_shipped',
    language: 'en',
    params: ['Jane', 'AB123'], // order matters — {{1}}, {{2}}
  }),
});

const msg = await res.json();
if (!res.ok) throw new Error(msg.error);

console.log(msg.message_id, msg.category, msg.cost);

Python

import os, requests

res = requests.post(
    "https://api.9bits.net/whatsapp/ng/v1/sendwhatsapp",
    headers={"Authorization": f"Bearer {os.environ['NINEBITS_WA_KEY']}"},
    json={
        "to": "2348020000000",
        "message_type": "template",
        "template_name": "order_shipped",
        "language": "en",
        "params": ["Jane", "AB123"],
    },
    timeout=10,
)
res.raise_for_status()
print(res.json()["message_id"])

`params` is positional

params fills the template’s placeholders in array order — params[0] → {{1}}, params[1] → {{2}}, and so on. There are no names.

Get the order wrong and you’ll send “Hi AB123, your order Jane has shipped” to a real customer. Get the count wrong and Meta rejects the message outright.

If your template changes, every call site that fills it has to change with it. This is the most common way WhatsApp integrations break in production — a template gets an extra placeholder and nobody updates the sender.

Template with a media header

{
  "to": "2348020000000",
  "message_type": "template",
  "template_name": "receipt_with_logo",
  "language": "en",
  "params": ["Jane", "12500.00"],
  "header_media_url": "https://cdn.example.com/img/receipt-header.png"
}

header_media_url must be publicly reachable — we fetch it when the message is dispatched.

Send free-form text

Only works inside an open 24-hour window, i.e. after the customer has messaged you.

{
  "to": "2348020000000",
  "message_type": "text",
  "text": "Thanks Jane — your refund is on its way."
}

Outside a window this is rejected. If you’re not certain the window is open, send a template instead.

Response

{
  "message_id": "2d665262-ffca-4289-a6cb-4126910d868b",
  "status": "queued",
  "cost": 19.5,
  "currency": "ngn",
  "category": "utility",
  "sender": "2349060008502"
}

Field	Meaning
message_id	Our id for the message. Store it — it’s how you look the message up in delivery reports.
status	Status at acceptance — normally queued. Delivery happens afterwards.
cost / currency	What this message cost you. Already debited.
category	Meta’s billing category — utility, marketing, authentication, service. Set by the template. Marketing is the expensive one.
sender	The WhatsApp number it went out from.

`message_id` is ours, not WhatsApp's

message_id is a UUID we mint. It is not WhatsApp’s wamid.…, which does not exist yet at this point — Meta assigns one only once it accepts the message, a moment or two later.

The wamid shows up as provider_message_id in delivery reports. Use it when you need to match a message against something in Meta’s own tooling; use message_id for everything on our side.

Log the category

category is the field that explains your WhatsApp bill. If a template gets reclassified by Meta from utility to marketing — which happens — your unit cost jumps and nothing in your code changes.

Log it on every send and alert if a template’s category shifts.

Errors

{ "error": "recipient 'to' is required" }

Status	Cause
400	Missing to, or a text message sent outside an open 24-hour window.
401	Missing or invalid API key.
402	Insufficient balance.

WhatsApp errors aren't structured like SMS

WhatsApp returns { "error": "…" } — a plain string. It does not use the { "error": { "type", "code", "message" } } shape that SMS uses, so you can’t branch on a machine-readable code here.

Don’t share an error parser between the two.