Send a document

curl --request POST \
  --url https://api.bulkneo.com/v1/messages/document \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --data '
{
  "instance_id": "3f9c1a2b-7d4e-4c81-9f0a-2b6d5e8c1a34",
  "to": "919876543210",
  "url": "https://example.com/invoice-2043.pdf",
  "filename": "invoice-2043.pdf",
  "caption": "April invoice"
}
'

const options = {
  method: 'POST',
  headers: {apikey: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    instance_id: '3f9c1a2b-7d4e-4c81-9f0a-2b6d5e8c1a34',
    to: '919876543210',
    url: 'https://example.com/invoice-2043.pdf',
    filename: 'invoice-2043.pdf',
    caption: 'April invoice'
  })
};

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

import requests

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

payload = {
    "instance_id": "3f9c1a2b-7d4e-4c81-9f0a-2b6d5e8c1a34",
    "to": "919876543210",
    "url": "https://example.com/invoice-2043.pdf",
    "filename": "invoice-2043.pdf",
    "caption": "April invoice"
}
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": "919876543210",
    "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": "media_fetch_failed",
    "message": "The media at that URL could not be downloaded. Check the link is public, direct, and still valid."
  },
  "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

document

Send a document

curl --request POST \
  --url https://api.bulkneo.com/v1/messages/document \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --data '
{
  "instance_id": "3f9c1a2b-7d4e-4c81-9f0a-2b6d5e8c1a34",
  "to": "919876543210",
  "url": "https://example.com/invoice-2043.pdf",
  "filename": "invoice-2043.pdf",
  "caption": "April invoice"
}
'

const options = {
  method: 'POST',
  headers: {apikey: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    instance_id: '3f9c1a2b-7d4e-4c81-9f0a-2b6d5e8c1a34',
    to: '919876543210',
    url: 'https://example.com/invoice-2043.pdf',
    filename: 'invoice-2043.pdf',
    caption: 'April invoice'
  })
};

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

import requests

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

payload = {
    "instance_id": "3f9c1a2b-7d4e-4c81-9f0a-2b6d5e8c1a34",
    "to": "919876543210",
    "url": "https://example.com/invoice-2043.pdf",
    "filename": "invoice-2043.pdf",
    "caption": "April invoice"
}
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": "919876543210",
    "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": "media_fetch_failed",
    "message": "The media at that URL could not be downloaded. Check the link is public, direct, and still valid."
  },
  "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"
}

Invoices, receipts, statements, tickets, price lists. Anything that is a file.

There is no file upload. You host the file at a public link and we fetch it from there. See Sending media.

Notes

Set filename. It is the name the recipient sees and the name they get if they save the file. Without it the name is taken from the link, which is often something like download.php or a long signed-URL blob.
filename is capped at 255 characters. Slashes (/ and \) and control characters are rejected, as are . and .. on their own. Nothing is silently rewritten — an unsafe name comes back as 400 invalid_request.
caption is shown with the file and capped at 1,024 characters.
mime_type is an optional hint such as application/pdf.

Example — an invoice

curl -X POST https://api.bulkneo.com/v1/messages/document \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "YOUR_INSTANCE_ID",
    "to": "919876543210",
    "url": "https://example.com/files/inv-2043.pdf",
    "filename": "Invoice-2043.pdf",
    "caption": "April invoice — due 15 May"
  }'

const res = await fetch("https://api.bulkneo.com/v1/messages/document", {
  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",
    url: `https://example.com/files/inv-${invoiceNo}.pdf`,
    filename: `Invoice-${invoiceNo}.pdf`,
    caption: "April invoice — due 15 May",
  }),
});

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

import os
import requests

res = requests.post(
    "https://api.bulkneo.com/v1/messages/document",
    headers={"apikey": os.environ["BULKNEO_API_KEY"]},
    json={
        "instance_id": os.environ["BULKNEO_INSTANCE_ID"],
        "to": "919876543210",
        "url": f"https://example.com/files/inv-{invoice_no}.pdf",
        "filename": f"Invoice-{invoice_no}.pdf",
        "caption": "April invoice — due 15 May",
    },
    timeout=30,
)

res.raise_for_status()

If your invoice link is a signed URL that expires, make sure it is still valid at the moment you call this endpoint — we fetch the file during the request, not later. An expired link comes back as 422 media_fetch_failed.

Authorizations

apikey

string

header

required

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

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 919876543210. Spaces, dashes, brackets and a leading + are accepted and stripped; 6 to 15 digits must remain.

Example:

"919876543210"

url

string

required

A public http(s) link to the file. There is no upload endpoint — we fetch the file from this link, so it must be reachable from the internet and be a direct link to the file itself, not a preview or share page. Private, internal and loopback addresses are refused, as are links containing a username or password.

Maximum string length: 2048

Example:

"https://example.com/receipt-2043.png"

filename

string

The name the recipient sees, for example invoice-2043.pdf. Up to 255 characters. Slashes and control characters are rejected, as are . and ... If you omit it, the name is taken from the link.

Maximum string length: 255

Example:

"invoice-2043.pdf"

caption

string

Text shown with the file. Up to 1,024 characters.

Maximum string length: 1024

Example:

"Your receipt"

mime_type

string

Optional content-type hint such as application/pdf. It is checked for the shape type/subtype only — we do not verify it matches the file. Usually you can leave it out.

Maximum string length: 128

Example:

"application/pdf"

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.

success

boolean

data

object

Show child attributes

request_id

string<uuid>

⌘I

Overview

Messages

Numbers

Instances

Service

Send a document

Notes

Example — an invoice

Authorizations

Body

Response

​Notes

​Example — an invoice

Authorizations

Body

Response

Notes

Example — an invoice