Quickstart

Five minutes, four steps. You need a BulkNeo account, a phone with WhatsApp on the number you want to send from, and something that can make an HTTP request.

Connect a number

Sign in to the portal and open your numbers screen. Add a number, give it a label you will recognise — Sales, Support, Delivery — and a QR code appears.On the phone that owns that WhatsApp number, open WhatsApp → Settings → Linked devices → Link a device, and scan the QR on screen.The status turns to Connected within a few seconds of a successful scan. The link stays active the same way WhatsApp Web does — you do not need to keep that page open.

Scan with the phone whose number you want to send from. Whatever number you scan is the number your customers will see the messages coming from.

Create an API key

Open the API Keys screen and create a key. Give it a label so you know later which server it lives on.

The key is shown once. Copy it straight into your server’s environment variables or secret store. We keep only a hash of it, so nobody — including us — can show it to you again. If you lose it, revoke it and create another.

Find your instance_id

Every connected number has its own instance_id. It is shown next to the number on your numbers screen, with a copy button.You can also list them from the API:

curl https://api.bulkneo.com/v1/instances \
  -H "apikey: YOUR_API_KEY"

Each entry has an instance_id, your label, and connected — which tells you whether that number can send right now.

Send your first message

Put your key in the apikey header, the instance_id of the number to send from, and the recipient in to.

curl -X POST https://api.bulkneo.com/v1/messages/text \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "YOUR_INSTANCE_ID",
    "to": "919876543210",
    "text": "Hello from our API"
  }'

const res = await fetch("https://api.bulkneo.com/v1/messages/text", {
  method: "POST",
  headers: {
    apikey: process.env.BULKNEO_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    instance_id: process.env.BULKNEO_INSTANCE_ID,
    to: "919876543210",
    text: "Hello from our API",
  }),
});

const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data.message_id);

import os
import requests

res = requests.post(
    "https://api.bulkneo.com/v1/messages/text",
    headers={"apikey": os.environ["BULKNEO_API_KEY"]},
    json={
        "instance_id": os.environ["BULKNEO_INSTANCE_ID"],
        "to": "919876543210",
        "text": "Hello from our API",
    },
    timeout=30,
)

body = res.json()
res.raise_for_status()
print(body["data"]["message_id"])

A success looks like this:

{
  "success": true,
  "data": {
    "instance_id": "3f9c1a2b-7d4e-4c81-9f0a-2b6d5e8c1a34",
    "to": "919876543210",
    "type": "text",
    "status": "sent",
    "message_id": "3EB0C1D2F4A5B6C7D8E9",
    "provider_status": "PENDING"
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

Keep data.message_id. It is what you use later to reply to or react to that message.

One key, many numbers

This is the one idea worth reading slowly, because every example on this site uses both fields and they do different jobs. Your API key identifies your account — it is who you are. Your instance_id identifies one of your connected numbers — it is which of them the message goes out from. Picture a shop with three WhatsApp numbers: one for Sales, one for Support, one for Delivery updates. All three run on one key. Each request names the number it should leave from, so the order confirmation goes out from Sales and “your parcel is on its way” goes out from Delivery.

Sales      instance_id: "3f9c…"   ┐
Support    instance_id: "a1b7…"   ├─ one API key
Delivery   instance_id: "c8e2…"   ┘

No second key, no second account, nothing extra to set up.

Every number keeps its instance_id for life. It does not change when a number drops off and someone re-scans the QR — so there is nothing to redeploy after a reconnect. See If your number disconnects.

Formatting the recipient

to is the recipient’s number with its country code and no leading zero:

You have	Send
`98765 43210` (India)	`919876543210`
`+91 98765-43210`	`919876543210` or `+919876543210`
`098765 43210`	`919876543210`

Spaces, dashes, brackets and a leading + are accepted and stripped for you. What must remain is 6 to 15 digits. A number that fails that check comes back as 422 invalid_recipient.

Sending to numbers that are not on WhatsApp wastes your allowance and is one of the fastest ways to get a number restricted. Check a list first.

Getting started

Guides

Reference

One key, many numbers

Formatting the recipient

Where to go next

Send other message types

Handle errors properly

​One key, many numbers

​Formatting the recipient

​Where to go next

Send other message types

Handle errors properly

One key, many numbers

Formatting the recipient

Where to go next