Send a text message

cURL (Windows)

curl -X POST "https://api.bulkneo.com/v1/messages/text" -H "apikey: YOUR_API_KEY" -H "Content-Type: application/json" -d "{\"instance_id\":\"3f9c1a2b-7d4e-4c81-9f0a-2b6d5e8c1a34\",\"to\":\"919000000000\",\"text\":\"Your order #2043 has shipped.\"}"

const options = {
  method: 'POST',
  headers: {apikey: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    instance_id: '3f9c1a2b-7d4e-4c81-9f0a-2b6d5e8c1a34',
    to: '919000000000',
    text: 'Your order #2043 has shipped.'
  })
};

fetch('https://api.bulkneo.com/v1/messages/text', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.bulkneo.com/v1/messages/text"

payload = {
    "instance_id": "3f9c1a2b-7d4e-4c81-9f0a-2b6d5e8c1a34",
    "to": "919000000000",
    "text": "Your order #2043 has shipped."
}
headers = {
    "apikey": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

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

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Field \"text\" is required and must be a non-empty string."
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid or revoked API key."
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "subscription_expired",
    "message": "Your subscription has expired. Renew it to continue sending messages."
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "trial_quota_exceeded",
    "message": "Trial message quota reached (500 messages). Upgrade to a paid plan to keep sending.",
    "details": {
      "trial_message_limit": 500
    }
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "instance_not_found",
    "message": "Instance not found. Check the instance_id and that it belongs to your account."
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "instance_not_connected",
    "message": "This WhatsApp instance is not connected. Connect it before sending messages."
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "invalid_recipient",
    "message": "The recipient number is not a valid WhatsApp number."
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded, retry in 12s.",
    "details": {
      "retry_after_seconds": 12,
      "limit_per_minute": 20,
      "scope": "messages"
    }
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred."
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "upstream_unavailable",
    "message": "The messaging service is temporarily unavailable. Please retry shortly."
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

POST

messages

text

cURL (Windows)

curl -X POST "https://api.bulkneo.com/v1/messages/text" -H "apikey: YOUR_API_KEY" -H "Content-Type: application/json" -d "{\"instance_id\":\"3f9c1a2b-7d4e-4c81-9f0a-2b6d5e8c1a34\",\"to\":\"919000000000\",\"text\":\"Your order #2043 has shipped.\"}"

const options = {
  method: 'POST',
  headers: {apikey: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    instance_id: '3f9c1a2b-7d4e-4c81-9f0a-2b6d5e8c1a34',
    to: '919000000000',
    text: 'Your order #2043 has shipped.'
  })
};

fetch('https://api.bulkneo.com/v1/messages/text', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.bulkneo.com/v1/messages/text"

payload = {
    "instance_id": "3f9c1a2b-7d4e-4c81-9f0a-2b6d5e8c1a34",
    "to": "919000000000",
    "text": "Your order #2043 has shipped."
}
headers = {
    "apikey": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

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

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Field \"text\" is required and must be a non-empty string."
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid or revoked API key."
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "subscription_expired",
    "message": "Your subscription has expired. Renew it to continue sending messages."
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "trial_quota_exceeded",
    "message": "Trial message quota reached (500 messages). Upgrade to a paid plan to keep sending.",
    "details": {
      "trial_message_limit": 500
    }
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "instance_not_found",
    "message": "Instance not found. Check the instance_id and that it belongs to your account."
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "instance_not_connected",
    "message": "This WhatsApp instance is not connected. Connect it before sending messages."
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "invalid_recipient",
    "message": "The recipient number is not a valid WhatsApp number."
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded, retry in 12s.",
    "details": {
      "retry_after_seconds": 12,
      "limit_per_minute": 20,
      "scope": "messages"
    }
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred."
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "upstream_unavailable",
    "message": "The messaging service is temporarily unavailable. Please retry shortly."
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

The playground on this page is live. There is no test mode and no sandbox: pressing Send authenticates with the key you paste and really calls https://api.bulkneo.com — a send delivers a real WhatsApp message to the number you type, and an instance call really changes your account. Use your own number while you are exploring, and paste a key only from a machine you trust.Your browser remembers what you type into the playground, so a key you paste here is still in the Authorization box on your next visit. Nobody else sees it — it never leaves your machine and it is not part of this site — but on a shared or borrowed computer, clear the site data when you are done.

The one you will use most. Order updates, OTPs, reminders, alerts.

Notes

text must not be blank, and is capped at 4,096 characters. Longer messages are rejected with 400 invalid_request rather than silently truncated.
WhatsApp’s own formatting works inside text: *bold*, _italic_, ~strikethrough~, and ```monospace```.
Line breaks are just \n in the JSON string.
Trailing blank space and newlines are removed before sending, so a message built by string concatenation does not arrive with empty lines at the bottom. Whitespace at the start is kept exactly as you sent it — a price list or order summary aligned with spaces keeps its shape.
Emoji are fine. Send them as normal UTF-8 characters.

Examples

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": "919000000000",
    "text": "Your order #2043 has shipped.\nTrack it: https://example.com/t/2043"
  }'

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\":\"919000000000\",\"text\":\"Your order #2043 has shipped.\nTrack it: https://example.com/t/2043\"}"

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: "919000000000",
    text: "Your order #2043 has shipped.",
  }),
});

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": "919000000000",
        "text": "Your order #2043 has shipped.",
    },
    timeout=30,
)

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

Keep data.message_id from the response. It is what you need to react to this message or quote it in a reply.

Authorizations

apikey

string

header

required

Your API key, sent in an apikey request header. Never in the URL, never as a Bearer token.

Headers

Idempotency-Key

string

OPTIONAL. A unique string you choose, 8-255 characters of letters, digits or . _ : ~ -

Send the same key with the same body again within 24 hours and the ORIGINAL result is returned without sending a second message — which is what makes a network retry safe. A different body on the same key is refused with 422 idempotency_key_reused rather than silently overwriting either result.

Responses carry Idempotency-Replayed: true|false while this is active. If that header is ABSENT, idempotency is not enabled on this deployment and retries will send again.

Required string length: 8 - 255

Pattern: ^[A-Za-z0-9._:~-]{8,255}$

Body

application/json

instance_id

string<uuid>

required

Which of your connected numbers to send FROM. Copy it from your numbers screen in the portal, or from GET /v1/instances. It must belong to your account.

Example:

"3f9c1a2b-7d4e-4c81-9f0a-2b6d5e8c1a34"

string

required

The recipient, with country code and no leading zero — for example 919000000000. Spaces, dashes, brackets and a leading + are accepted and stripped; 6 to 15 digits must remain.

Example:

"919000000000"

text

string

required

The message body. Must not be blank. Up to 4,096 characters. Trailing blank space and newlines are removed before sending; anything at the START of the message is kept exactly as you sent it, so a price list aligned with spaces keeps its shape.

Required string length: 1 - 4096

Example:

"Your order #2043 has shipped."

quoted_message_id

string

Send this message as a reply, quoting an earlier one. Use the data.message_id returned by a previous send.

Maximum string length: 128

Example:

"3EB0C1D2F4A5B6C7D8E9"

quoted_from_me

boolean

default:false

Set true when the quoted message is one you sent from this number. Only valid together with quoted_message_id.

Response

Accepted for delivery. data.type is always text on this endpoint.

success

boolean

data

object

Show child attributes

request_id

string<uuid>

Overview

Messages

Numbers

Instances

Service

Notes

Examples

Authorizations

Headers

Body

Response

​Notes

​Examples

Authorizations

Headers

Body

Response

Notes

Examples