Neupa Hosting API Documentation
Send messages, manage sessions, and receive webhooks. All endpoints authenticated with your api_key.
Quick Start
Get sending in 3 steps
- Get your API key — copy it from the Linked Numbers page next to your instance.
- Check status — call
GET /status?api_key=TOKENto confirm connected. - Send a message —
POST /sendwithtoandmessage.
curl 'https://neupa.co.ke/api/v1/whatsapp/send?api_key=YOUR_TOKEN' \
-X POST \
-H 'Content-Type: application/json' \
-d '{"to":"254712345678","message":"Hello from Neupa Hosting!","type":"text"}'
import requests
resp = requests.post(
'https://neupa.co.ke/api/v1/whatsapp/send',
params={'api_key': 'YOUR_TOKEN'},
json={'to': '254712345678', 'message': 'Hello!', 'type': 'text'}
)
print(resp.json())
const res = await fetch('https://neupa.co.ke/api/v1/whatsapp/send?api_key=YOUR_TOKEN', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({to: '254712345678', message: 'Hello!', type: 'text'})
});
console.log(await res.json());
Authentication
All requests require your access token
api_key query parameter on every request.Find it on the Linked Numbers page → your instance row.
/status
Get Instance Status
Returns the current connection state of your WhatsApp instance.
api_key
string
Yes
Your instance access token
Session Management
Start, stop, sync and get QR
/start
Start Session
Starts the WhatsApp session. Call this if the session is disconnected before sending messages.
api_key
string
Yes
Your instance access token
/sync
Sync Session State
Syncs the engine state into the database. Useful to refresh status after reconnection.
api_key
string
Yes
Your instance access token
/qr
Get QR Code
Returns a base64 PNG QR code. Add ?reset=1 to generate a fresh QR.
api_key
string
Yes
Your instance access token
reset
boolean
No
Pass 1 to reset and generate a fresh QR
Send Messages
Text and media to any WhatsApp number
+ — e.g. 254712345678
/send
Send Text Message
Sends a plain text message to the specified phone number.
api_key
string
Yes
Your access token (query param)
to
string
Yes
Recipient phone — e.g. 254712345678
message
string
Yes
Text content of the message
type
string
No
text (default) or media
/send
Send Media Message
Sends an image, document (including PDFs), audio, or other file by public URL. Use multipart/form-data with media_file to upload a file directly (up to 14 MB).
api_key
string
Yes
Your access token (query param)
to
string
Yes
Recipient phone number
type
string
Yes
Must be: media
message
string
No
Optional caption
media.url
string
No
Publicly accessible URL to the file; provide this or media_file
media.mimeType
string
No
e.g. image/jpeg, application/pdf; non-media files are sent as documents
media_file
file
No
Multipart file upload (max 14 MB); provide this or media.url
Broadcast — Bulk Send
One message to many recipients
{name} in your message to auto-personalise with each recipient's name.
/broadcast
Send Broadcast
Send one message to multiple recipients. Supports {name} personalisation. Max 500 recipients per call.
api_key
string
Yes
Your access token (query param)
message
string
Yes
Message text. Use {name} to personalise.
recipients
array
Yes
Array of {phone, name?} objects. Max 500.
label
string
No
Label for your records e.g. "Fee Reminder"
type
string
No
text (default) or media
/broadcast
List Broadcasts
Returns all previous broadcasts with aggregate stats.
api_key
string
Yes
Your access token
page
integer
No
Page number (default: 1)
Webhooks
Real-time event delivery to your server
POST events (new messages, status changes) from your instance.
{"event":"message","instance_id":"YOUR_ENGINE_ID","timestamp":1719230400,
"data":{"from":"[email protected]","body":"Hello!","id":"3EB0C767"}}
/webhooks
List Webhooks
Returns all registered webhook URLs for your instance.
api_key
string
Yes
Your access token
/webhooks
Register Webhook
Registers a new webhook URL to receive events.
api_key
string
Yes
Your access token (query param)
url
string
Yes
Your publicly accessible HTTPS URL
events
array
No
event types: message, status, qr. Default: all
/webhooks/{id}
Delete Webhook
Removes a registered webhook by its ID.
api_key
string
Yes
Your access token (query param)
id
integer
Yes
Webhook ID (path param)
Message Logs
Retrieve sent and received history
/messages
Get Message Logs
Returns paginated message history including sent and received messages.
api_key
string
Yes
Your access token
page
integer
No
Page number (default: 1)
per_page
integer
No
Per page (default: 20, max: 100)
/linked-numbers/{linkedNumber}/messages
Get Logs for a Linked Number
Returns paginated sent and received message history for the linked number in the URL. The API key must belong to that same linked number.
linkedNumber
integer
Yes
Linked number ID
api_key
string
Yes
Access token for this linked number
page
integer
No
Page number (default: 1)
per_page
integer
No
Results per page (default: 50)
direction
string
No
Filter by incoming or outgoing
search
string
No
Search message text, sender, or recipient
GET /linked-numbers/{linkedNumber}/messages
# Example: http://127.0.0.1:8001/linked-numbers/22/messages
Accept: application/json
This root-level dashboard route requires a signed-in account and only returns logs for a linked number owned by that account. Send Accept: application/json to receive JSON; without it, the dashboard renders the HTML log page. For API-key integrations, use GET https://neupa.co.ke/api/v1/whatsapp/linked-numbers/{linkedNumber}/messages and provide that linked number's API key.
Message Bots
Configure automatic replies for this API key's WhatsApp number
/bots
Get Message Bot
Returns the bot configured for the linked number associated with your API key, or null if none exists.
api_key
string
Yes
Access token for the linked number
/bots
Create Message Bot
Creates the single bot for this linked number. A linked number can have only one bot. Keyword phrases are matched case-insensitively; the first matching rule is used.
api_key
string
Yes
Access token for the linked number
/bots/{bot}
Update Message Bot
Updates the bot belonging to the linked number associated with your API key. Send only the fields you want to change; rules are replaced by the supplied list.
bot
integer
Yes
Bot ID
api_key
string
Yes
Access token for the linked number
/bots/{bot}
Delete Message Bot
Deletes the bot belonging to the linked number associated with your API key.
bot
integer
Yes
Bot ID
api_key
string
Yes
Access token for the linked number
Error Codes
HTTP status codes and their meaning
{"success":false,"message":"Your Professional plan's monthly limit of 10000 messages has been reached.","error":"plan_monthly_message_limit_exceeded","retry_after":86400}
WordPress Plugin
Send WhatsApp messages directly from WordPress & WooCommerce
The Neupa WhatsApp plugin connects your WordPress site to this API — no custom code needed. It supports WooCommerce order alerts, Contact Form 7 auto-replies, a floating chat button, shortcodes, and a built-in REST endpoint.
Download neupa-whatsapp.zip from the Linked Numbers page or your account dashboard.
Settings page — how it looks after install
The Quick Start panel at the top walks you through 3 steps. Fill in your Access Token, confirm the Base URL is https://neupa.co.ke, and click Save Configuration.
Quick Setup — 3 steps
- Go to neupa.co.ke/linked-numbers and find your instance — copy the Access Token shown next to your linked number.
- In WordPress go to Settings → Neupa WhatsApp. Paste the token in the Access Token field, set the Base URL to
https://neupa.co.ke, and save. - Enable the toggles you need — WooCommerce notifications, Contact Form 7, or the floating chat button — and click Save Configuration.
$api = neupa_wa_api();
if ( $api ) {
// Send a single message
$api->send_message( '254712345678', 'Hello from my theme!' );
// Broadcast to multiple recipients
$api->broadcast( 'Flash sale on now!', [
['phone' => '254712345678', 'name' => 'Alice'],
['phone' => '254799999999', 'name' => 'Bob'],
], 'Flash sale campaign' );
}
POST /wp-json/neupa-wa/v1/send
{
"to": "254712345678",
"message": "Order shipped! Track: https://…"
}
[neupa_whatsapp_button phone="254712345678" label="Order via WhatsApp" color="#128c7e"]
Need an account? Sign up at neupa.co.ke. Full API docs at neupa.co.ke/docs.
Laravel Integration
Drop-in config for any Laravel 9 / 10 / 11 app
No package to install. Copy three lines into your .env, register a singleton, and you're sending messages. The fields below map 1-to-1 to the settings UI.
Get your credentials from neupa.co.ke/linked-numbers — Instance ID and Access Token are shown next to your linked number.
Settings field → .env key
| Settings UI field | .env key | Notes |
|---|---|---|
| Instance ID * | WAWP_INSTANCE_ID |
From your wawp.net dashboard |
| Access Token * | WAWP_ACCESS_TOKEN |
Keep this secret |
| Default Sender Phone | WAWP_DEFAULT_PHONE |
Country code, no + sign |
| Enable WhatsApp Messaging ✓ | WAWP_ENABLED |
Set false to silence all sends |
| Base URL (advanced) | WAWP_BASE_URL |
Default: https://neupa.co.ke |
Step 1 — Add credentials to .env
# ── Neupa / WAWP WhatsApp ───────────────────────────────── WAWP_INSTANCE_ID=641875F9B856 # from neupa.co.ke/linked-numbers WAWP_ACCESS_TOKEN=your_access_token # keep secret WAWP_DEFAULT_PHONE=254712345678 # optional — no + sign WAWP_ENABLED=true WAWP_BASE_URL=https://neupa.co.ke # leave as-is for hosted service
Step 2 — Publish config
<?php
return [
'instance_id' => env('WAWP_INSTANCE_ID', ''),
'access_token' => env('WAWP_ACCESS_TOKEN', ''),
'default_phone' => env('WAWP_DEFAULT_PHONE', ''),
'enabled' => env('WAWP_ENABLED', true),
'base_url' => env('WAWP_BASE_URL', 'https://neupa.co.ke'),
'timeout' => 30,
];
Step 3 — Drop in the service class
<?php
namespace App\Services;
use Illuminate\Support\Facades\Http;
use Illuminate\Http\Client\Response;
class NeupaWhatsApp
{
private readonly string $instanceId;
private readonly string $accessToken;
private readonly string $baseUrl;
private readonly bool $enabled;
private readonly int $timeout;
public function __construct()
{
$this->instanceId = config('wawp.instance_id', '');
$this->accessToken = config('wawp.access_token', '');
$this->baseUrl = rtrim(config('wawp.base_url', 'https://neupa.co.ke'), '/') . '/api/v1/whatsapp';
$this->enabled = (bool) config('wawp.enabled', true);
$this->timeout = (int) config('wawp.timeout', 30);
}
/** Send a single text message. */
public function send(string $to, string $message): array
{
if (! $this->enabled || ! $this->accessToken) {
return ['success' => false, 'message' => 'WhatsApp messaging is not configured.'];
}
return $this->post('/send', [
'to' => $this->normalisePhone($to),
'message' => $message,
'type' => 'text',
'instance_id' => $this->instanceId,
]);
}
/** Broadcast one message to many recipients (up to 500). */
public function broadcast(string $message, array $recipients, string $label = ''): array
{
$normalised = array_map(fn ($r) => [
'phone' => $this->normalisePhone(is_array($r) ? $r['phone'] : $r),
'name' => is_array($r) ? ($r['name'] ?? '') : '',
], $recipients);
$body = [
'message' => $message,
'recipients' => $normalised,
'type' => 'text',
'instance_id' => $this->instanceId,
];
if ($label) {
$body['label'] = $label;
}
return $this->post('/broadcast', $body);
}
/** Check instance connection status. */
public function status(): array
{
return $this->get('/status', ['instance_id' => $this->instanceId]);
}
// ── Private helpers ───────────────────────────────────────────────────────
/** Strip non-digits; convert 07xx / 01xx → 254xx. */
private function normalisePhone(string $phone): string
{
$digits = preg_replace('/[^0-9]/', '', $phone);
if (strlen($digits) === 10 && str_starts_with($digits, '0')) {
$digits = '254' . substr($digits, 1);
}
return $digits;
}
private function get(string $path, array $query = []): array
{
$response = Http::timeout($this->timeout)
->withToken($this->accessToken)
->acceptJson()
->get($this->baseUrl . $path, $query);
return $this->parse($response);
}
private function post(string $path, array $body = []): array
{
$response = Http::timeout($this->timeout)
->withToken($this->accessToken)
->acceptJson()
->post($this->baseUrl . $path, $body);
return $this->parse($response);
}
private function parse(Response $response): array
{
$json = $response->json() ?? [];
$success = $response->successful() && ($json['success'] ?? true) !== false;
return [
'success' => $success,
'data' => $json['data'] ?? $json ?? null,
'message' => $json['message'] ?? ($success ? 'OK' : 'HTTP ' . $response->status()),
'http_code' => $response->status(),
];
}
}
Step 4 — Register singleton
use App\Services\NeupaWhatsApp;
public function register(): void
{
$this->app->singleton(NeupaWhatsApp::class);
}
Usage examples
use App\Services\NeupaWhatsApp;
class InvoiceController extends Controller
{
public function __construct(private NeupaWhatsApp $wa) {}
public function notify(Invoice $invoice): void
{
$this->wa->send(
$invoice->client_phone,
"Hi {$invoice->client_name}, your invoice #{$invoice->number} " .
"for KES {$invoice->total} is ready."
);
}
}
app(NeupaWhatsApp::class)->broadcast(
'Hi {name}, your term fees are due by Friday.',
[
['phone' => '254712345678', 'name' => 'Alice Wanjiku'],
['phone' => '254799999999', 'name' => 'Bob Kamau'],
],
'Term fees reminder'
);
Automatic notifications — matching the UI toggles
The settings UI has Invoice Generated and Payment Received toggles. Wire those up in Laravel with event listeners:
InvoiceGenerated event → listener calls $wa->send()
PaymentMade event → listener calls $wa->send()
<?php
namespace App\Listeners;
use App\Events\InvoiceGenerated;
use App\Services\NeupaWhatsApp;
class SendInvoiceWhatsApp
{
public function __construct(private NeupaWhatsApp $wa) {}
public function handle(InvoiceGenerated $event): void
{
$invoice = $event->invoice;
$client = $invoice->client;
if (! $client?->phone) return;
$this->wa->send(
$client->phone,
"Hi {$client->name}, invoice #{$invoice->number} " .
"for KES {$invoice->total} has been generated."
);
}
}
<?php
namespace App\Listeners;
use App\Events\PaymentMade;
use App\Services\NeupaWhatsApp;
class SendPaymentWhatsApp
{
public function __construct(private NeupaWhatsApp $wa) {}
public function handle(PaymentMade $event): void
{
$payment = $event->payment;
$client = $payment->client;
if (! $client?->phone) return;
$this->wa->send(
$client->phone,
"Hi {$client->name}, payment of KES {$payment->amount} received. Thank you!"
);
}
}
use App\Events\InvoiceGenerated;
use App\Events\PaymentMade;
use App\Listeners\SendInvoiceWhatsApp;
use App\Listeners\SendPaymentWhatsApp;
protected $listen = [
InvoiceGenerated::class => [SendInvoiceWhatsApp::class],
PaymentMade::class => [SendPaymentWhatsApp::class],
];
Need an account? Sign up at neupa.co.ke and copy your Instance ID & Access Token from Linked Numbers.