API v1 · Live

API Documentation

Send WhatsApp messages programmatically — text & images — with our simple REST API.

4

Endpoints

40/min

Rate Limit

Text+Image

Message Types

Bearer

Auth Type

Join our Developer Program

Full API access, cashback on every sale you bring, and exclusive developer resources.

Join Now

Authentication

The API uses two different API keys depending on the operation, both sent as a Bearer token.

Message API Key Sending

Required for sending messages. Linked to a specific WhatsApp instance.

Get from WhatsApp Instances — each instance has its own key.

Used for POST /send-message

Authorization: Bearer <MESSAGE_API_KEY>

User API Key Account

Required for reading account data (credits, message history).

Get from your Account Settings.

Used for GET /credits & GET /messages

Authorization: Bearer <USER_API_KEY>

Security: Never expose API keys in client-side code. Always call the API from your server.

Base URL

https://api-messaging.pollenbyte.com/v1

All requests must use HTTPS. POST requests must include Content-Type: application/json.

POST /v1/send-message Message API Key

Send a single WhatsApp message to a phone number. Supports text, image and document messages.

Request Body

Parameter	Type	Required	Description
`phone`	string	Required	Recipient phone with country code. No leading `+` or `0`. E.g. `201012345678`
`message`	string	Optional*	Text message content. Max 1000 chars. When sending an image or document, this becomes the caption.
`file_url`	string	Optional*	Publicly accessible URL for the file (image or document). Max 2048 chars.
`file_name`	string	Optional	The name of the file as it will appear in WhatsApp (mandatory for documents). E.g. `invoice.pdf`
`mimetype`	string	Optional	The MIME type of the file. E.g. `application/pdf`. Auto-detected for common types.
`message_type`	string	Optional	One of: `text`, `image`, or `document`. Auto-detected if omitted.

At least one of message or file_url is required.

Sending Files (Images & Documents)

Provide file_url with a public direct URL. Set message_type to image or document. For documents, providing file_name is highly recommended.

Text Message Example

cURL

curl -X POST "https://api-messaging.pollenbyte.com/v1/send-message" \
  -H "Authorization: Bearer YOUR_MESSAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"201012345678","message":"Hello from API!"}'

PHP

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL            => 'https://api-messaging.pollenbyte.com/v1/send-message',
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode(['phone' => '201012345678', 'message' => 'Hello from API!']),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer YOUR_MESSAGE_API_KEY', 'Content-Type: application/json'],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

JavaScript

const res = await fetch('https://api-messaging.pollenbyte.com/v1/send-message', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_MESSAGE_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ phone: '201012345678', message: 'Hello from API!' }),
});
const data = await res.json();
console.log(data);

Python

import requests
r = requests.post(
    'https://api-messaging.pollenbyte.com/v1/send-message',
    json={'phone': '201012345678', 'message': 'Hello from API!'},
    headers={'Authorization': 'Bearer YOUR_MESSAGE_API_KEY'}
)
print(r.json())

Image Message Example

cURL

curl -X POST "https://api-messaging.pollenbyte.com/v1/send-message" \
  -H "Authorization: Bearer YOUR_MESSAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "201012345678",
    "file_url": "https://example.com/photo.jpg",
    "message": "Check this out!"
  }'

PHP

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL            => 'https://api-messaging.pollenbyte.com/v1/send-message',
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode([
        'phone'     => '201012345678',
        'file_url' => 'https://example.com/photo.jpg',
        'message'   => 'Check this out!', // optional caption
    ]),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer YOUR_MESSAGE_API_KEY', 'Content-Type: application/json'],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

JavaScript

const res = await fetch('https://api-messaging.pollenbyte.com/v1/send-message', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_MESSAGE_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    phone: '201012345678',
    file_url: 'https://example.com/photo.jpg',
    message: 'Check this out!', // optional caption
  }),
});
const data = await res.json();

Python

import requests
r = requests.post(
    'https://api-messaging.pollenbyte.com/v1/send-message',
    json={
        'phone': '201012345678',
        'file_url': 'https://example.com/photo.jpg',
        'message': 'Check this out!',
    },
    headers={'Authorization': 'Bearer YOUR_MESSAGE_API_KEY'}
)
print(r.json())

Document Message Example

cURL

curl -X POST "https://api-messaging.pollenbyte.com/v1/send-message" \
  -H "Authorization: Bearer YOUR_MESSAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "201012345678",
    "message_type": "document",
    "file_url": "https://example.com/invoice.pdf",
    "file_name": "Invoice-123.pdf",
    "message": "Here is your invoice"
  }'

PHP

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL            => 'https://api-messaging.pollenbyte.com/v1/send-message',
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode([
        'phone'        => '201012345678',
        'message_type' => 'document',
        'file_url'    => 'https://example.com/invoice.pdf',
        'file_name'    => 'Invoice-123.pdf',
        'message'      => 'Here is your invoice'
    ]),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer YOUR_MESSAGE_API_KEY', 'Content-Type: application/json'],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

JavaScript

const res = await fetch('https://api-messaging.pollenbyte.com/v1/send-message', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_MESSAGE_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    phone: '201012345678',
    message_type: 'document',
    file_url: 'https://example.com/invoice.pdf',
    file_name: 'Invoice-123.pdf',
    message: 'Here is your invoice'
  }),
});
const data = await res.json();

Python

import requests
r = requests.post(
    'https://api-messaging.pollenbyte.com/v1/send-message',
    json={
        'phone': '201012345678',
        'message_type': 'document',
        'file_url': 'https://example.com/invoice.pdf',
        'file_name': 'Invoice-123.pdf',
        'message': 'Here is your invoice'
    },
    headers={'Authorization': 'Bearer YOUR_MESSAGE_API_KEY'}
)
print(r.json())

Responses

201 CreatedMessage queued

{
  "success": true,
  "message": "Message scheduled successfully",
  "data": {
    "message_id": 42,
    "phone": "201012345678"
  }
}

422 UnprocessableMissing message and file_url

{"message": "The message or file_url field is required."}

401 UnauthorizedBad API key

{"success": false, "error": {"code": "INVALID_API_KEY", "message": "Invalid API Key provided"}}

GET /v1/credits User API Key

Returns your current credit balance, along with monthly statistics for credits gained and spent.

Query Parameters

Parameter	Type	Default	Description
`all`	boolean	`0`	Set to `1` to get all-time historical statistics instead of the current month.

Examples

cURL

curl -X GET "https://api-messaging.pollenbyte.com/v1/credits" \
  -H "Authorization: Bearer YOUR_USER_API_KEY"

PHP

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL            => 'https://api-messaging.pollenbyte.com/v1/credits',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer YOUR_USER_API_KEY'],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

JavaScript

const res = await fetch('https://api-messaging.pollenbyte.com/v1/credits', {
  headers: { 'Authorization': 'Bearer YOUR_USER_API_KEY' },
});
const data = await res.json();

Python

import requests
r = requests.get(
    'https://api-messaging.pollenbyte.com/v1/credits',
    headers={'Authorization': 'Bearer YOUR_USER_API_KEY'}
)
print(r.json())

Response

200 OK

{
  "success": true,
  "data": {
    "free_credits": 50,
    "charged_credits": 900,
    "total_credits": 950,
    "credits_gained": 1200.0,
    "credits_spent": 250.0,
    "period": "current_month"
  }
}

GET /v1/messages User API Key

Returns a paginated list of messages sent from your account. By default, it only shows messages from the current month.

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	`10`	Number of messages per page.
`all`	boolean	`0`	Set to `1` to see messages and statistics from all time.

Examples

cURL

curl -X GET "https://api-messaging.pollenbyte.com/v1/messages?limit=20" \
  -H "Authorization: Bearer YOUR_USER_API_KEY"

PHP

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL            => 'https://api-messaging.pollenbyte.com/v1/messages?limit=20',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer YOUR_USER_API_KEY'],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

JavaScript

const res = await fetch('https://api-messaging.pollenbyte.com/v1/messages?limit=20', {
  headers: { 'Authorization': 'Bearer YOUR_USER_API_KEY' },
});
const data = await res.json();

Python

import requests
r = requests.get(
    'https://api-messaging.pollenbyte.com/v1/messages',
    params={'limit': 20},
    headers={'Authorization': 'Bearer YOUR_USER_API_KEY'}
)
print(r.json())

Response

200 OK

{
  "success": true,
  "report_period": "current_month",
  "total_send_messages": 142,
  "total_sent_messages": 138,
  "total_failed_messages": 3,
  "total_pending_messages": 1,
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": 42,
        "recipient_phone": "201012345678",
        "body": "Hello!",
        "message_type": "text",
        "file_url": null,
        "status": "sent",
        "send_type": "single",
        "created_at": "2026-03-01T10:00:00.000000Z"
      }
    ],
    "next_page_url": "https://api-messaging.pollenbyte.com/v1/messages?cursor=xxx",
    "prev_page_url": null
  }
}

GET /v1/messages/{id} User API Key

Returns the full details of a specific message by its ID.

Path Parameters

Parameter	Type	Required	Description
`id`	integer	Required	The message ID returned when the message was sent.

Examples

cURL

curl -X GET "https://api-messaging.pollenbyte.com/v1/messages/42" \
  -H "Authorization: Bearer YOUR_USER_API_KEY"

PHP

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL            => 'https://api-messaging.pollenbyte.com/v1/messages/42',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer YOUR_USER_API_KEY'],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

JavaScript

const res = await fetch('https://api-messaging.pollenbyte.com/v1/messages/42', {
  headers: { 'Authorization': 'Bearer YOUR_USER_API_KEY' },
});
const data = await res.json();

Python

import requests
r = requests.get(
    'https://api-messaging.pollenbyte.com/v1/messages/42',
    headers={'Authorization': 'Bearer YOUR_USER_API_KEY'}
)
print(r.json())

Responses

200 OK

{
  "success": true,
  "data": {
    "id": 42,
    "recipient_phone": "201012345678",
    "body": "Hello!",
    "message_type": "text",
    "file_url": null,
    "status": "sent",
    "send_type": "single",
    "created_at": "2026-03-01T10:00:00.000000Z",
    "updated_at": "2026-03-01T10:00:05.000000Z"
  }
}

404 Not FoundMessage not found or belongs to another account

{"message": "No query results for model [App\\Models\\Message] 42"}

Error Codes

All errors return a consistent JSON structure. Use the HTTP status code and error.code to handle them programmatically.

401MISSING_API_KEY

No Authorization header provided.

401INVALID_API_KEY

API key doesn't match any active instance or user account.

422VALIDATION_ERROR

One or more request fields failed validation.

403INSUFFICIENT_CREDITS

Account doesn't have enough credits to send the message.

429TOO_MANY_REQUESTS

Rate limit exceeded (40 req/min). Wait before retrying.

500INTERNAL_SERVER_ERROR

Unexpected server error. Retry or contact support.

Error Response Shape

{
  "success": false,
  "error": {
    "code": "ERROR_CODE_HERE",
    "message": "Human-readable description"
  }
}

Rate Limiting

Endpoint	Limit	Window
`POST /send-message`	40 requests	per minute
`GET /credits`, `GET /messages`, `GET /messages/{id}`	No hard limit	—

When exceeded: 429 Too Many Requests. Retry after 1 minute.

Messages are queued asynchronously. The API responds immediately with 201 and a message_id. Actual WhatsApp delivery happens within seconds.

Credit Refund Policy

We value your credits. Our system includes an automated mechanism to ensure you only pay for messages that have a fair chance of delivery.

Stuck Messages

Any message that remains in pending or processing status for more than 2 hours is considered "stuck". These messages are automatically cancelled and their credits are fully refunded to your balance.

Failed Deliveries

Messages that immediately reach a failed status due to system errors or carrier issues are eligible for automatic refunds. Our background process verifies these daily.

Auto-Processing: The refund system runs automatically every day at 00:00 (Midnight).