Send an image

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

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/receipt-2043.png',
    caption: 'Your receipt'
  })
};

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

import requests

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

payload = {
    "instance_id": "3f9c1a2b-7d4e-4c81-9f0a-2b6d5e8c1a34",
    "to": "919876543210",
    "url": "https://example.com/receipt-2043.png",
    "caption": "Your receipt"
}
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

image

Send an image

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

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/receipt-2043.png',
    caption: 'Your receipt'
  })
};

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

import requests

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

payload = {
    "instance_id": "3f9c1a2b-7d4e-4c81-9f0a-2b6d5e8c1a34",
    "to": "919876543210",
    "url": "https://example.com/receipt-2043.png",
    "caption": "Your receipt"
}
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"
}

Product photos, receipts, screenshots, QR codes for a booking.

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

Notes

url must be a public http(s) link directly to the image file — not a Google Drive preview page, not a share link that shows a viewer.
caption is shown under the image and is capped at 1,024 characters.
mime_type is an optional hint such as image/png. It is checked for the shape type/subtype only; we do not verify it matches the file. You can normally leave it out.
A link that passes validation but cannot actually be downloaded comes back as 422 media_fetch_failed.

Examples

curl -X POST https://api.bulkneo.com/v1/messages/image \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "YOUR_INSTANCE_ID",
    "to": "919876543210",
    "url": "https://example.com/receipt-2043.png",
    "caption": "Your receipt"
  }'

const res = await fetch("https://api.bulkneo.com/v1/messages/image", {
  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/receipt-2043.png",
    caption: "Your receipt",
  }),
});

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/image",
    headers={"apikey": os.environ["BULKNEO_API_KEY"]},
    json={
        "instance_id": os.environ["BULKNEO_INSTANCE_ID"],
        "to": "919876543210",
        "url": "https://example.com/receipt-2043.png",
        "caption": "Your receipt",
    },
    timeout=30,
)

res.raise_for_status()

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"

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 an image

Notes

Examples

Authorizations

Body

Response

​Notes

​Examples

Authorizations

Body

Response

Notes

Examples