Neupa Hosting API Documentation

Send messages, manage sessions, and receive webhooks. All endpoints authenticated with your api_key.

Base URL
https://neupa.co.ke/api/v1/whatsapp
Auth
?api_key=TOKEN
Format
JSON
OpenAPI
Download JSON

Quick Start

Get sending in 3 steps

  1. Get your API key — copy it from the Linked Numbers page next to your instance.
  2. Check status — call GET /status?api_key=TOKEN to confirm connected.
  3. Send a message — POST /send with to and message.
cURL example
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"}'
Python
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())
JavaScript (fetch)
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

Pass your token as the api_key query parameter on every request.
Find it on the Linked Numbers page → your instance row.
GET /status Get Instance Status

Returns the current connection state of your WhatsApp instance.

ParameterTypeReqDescription
api_key string Yes Your instance access token

Session Management

Start, stop, sync and get QR

POST /start Start Session

Starts the WhatsApp session. Call this if the session is disconnected before sending messages.

ParameterTypeReqDescription
api_key string Yes Your instance access token
POST /sync Sync Session State

Syncs the engine state into the database. Useful to refresh status after reconnection.

ParameterTypeReqDescription
api_key string Yes Your instance access token
GET /qr Get QR Code

Returns a base64 PNG QR code. Add ?reset=1 to generate a fresh QR.

ParameterTypeReqDescription
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

Phone numbers must be in international format without + — e.g. 254712345678
POST /send Send Text Message

Sends a plain text message to the specified phone number.

ParameterTypeReqDescription
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
POST /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).

ParameterTypeReqDescription
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

Use {name} in your message to auto-personalise with each recipient's name.
POST /broadcast Send Broadcast

Send one message to multiple recipients. Supports {name} personalisation. Max 500 recipients per call.

ParameterTypeReqDescription
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
GET /broadcast List Broadcasts

Returns all previous broadcasts with aggregate stats.

ParameterTypeReqDescription
api_key string Yes Your access token
page integer No Page number (default: 1)

Webhooks

Real-time event delivery to your server

Register a URL to receive POST events (new messages, status changes) from your instance.
Webhook payload
{"event":"message","instance_id":"YOUR_ENGINE_ID","timestamp":1719230400,
 "data":{"from":"[email protected]","body":"Hello!","id":"3EB0C767"}}
GET /webhooks List Webhooks

Returns all registered webhook URLs for your instance.

ParameterTypeReqDescription
api_key string Yes Your access token
POST /webhooks Register Webhook

Registers a new webhook URL to receive events.

ParameterTypeReqDescription
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
DELETE /webhooks/{id} Delete Webhook

Removes a registered webhook by its ID.

ParameterTypeReqDescription
api_key string Yes Your access token (query param)
id integer Yes Webhook ID (path param)

Message Logs

Retrieve sent and received history

GET /messages Get Message Logs

Returns paginated message history including sent and received messages.

ParameterTypeReqDescription
api_key string Yes Your access token
page integer No Page number (default: 1)
per_page integer No Per page (default: 20, max: 100)
GET /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.

ParameterTypeReqDescription
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
Dashboard URL (signed-in session)
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

GET /bots Get Message Bot

Returns the bot configured for the linked number associated with your API key, or null if none exists.

ParameterTypeReqDescription
api_key string Yes Access token for the linked number
POST /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.

ParameterTypeReqDescription
api_key string Yes Access token for the linked number
PATCH /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.

ParameterTypeReqDescription
bot integer Yes Bot ID
api_key string Yes Access token for the linked number
DELETE /bots/{bot} Delete Message Bot

Deletes the bot belonging to the linked number associated with your API key.

ParameterTypeReqDescription
bot integer Yes Bot ID
api_key string Yes Access token for the linked number

Error Codes

HTTP status codes and their meaning

401 Unauthorized Invalid or missing api_key
400 Bad Request Missing required parameters
404 Not Found Instance or resource not found
429 Too Many Requests Free, plan, daily, or hourly message limit exceeded
503 Service Unavailable WhatsApp engine is unreachable
500 Server Error Unexpected internal error
Rate limit error (HTTP 429)
{"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

Neupa WhatsApp WordPress plugin settings page showing the Quick Start panel, Access Token field, Base URL, and notification toggles

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

  1. Go to neupa.co.ke/linked-numbers and find your instance — copy the Access Token shown next to your linked number.
  2. 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.
  3. Enable the toggles you need — WooCommerce notifications, Contact Form 7, or the floating chat button — and click Save Configuration.
PHP helper (theme / plugin)
$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' );
}
WordPress REST endpoint (POST)
POST /wp-json/neupa-wa/v1/send

{
  "to": "254712345678",
  "message": "Order shipped! Track: https://…"
}
Chat button shortcode
[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

.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

config/wawp.php
<?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

app/Services/NeupaWhatsApp.php
<?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

app/Providers/AppServiceProvider.php
use App\Services\NeupaWhatsApp;

public function register(): void
{
    $this->app->singleton(NeupaWhatsApp::class);
}

Usage examples

Controller — send a single message
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."
        );
    }
}
Broadcast to multiple recipients
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:

Invoice Generated → InvoiceGenerated event → listener calls $wa->send()
Payment Received → PaymentMade event → listener calls $wa->send()
app/Listeners/SendInvoiceWhatsApp.php
<?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."
        );
    }
}
app/Listeners/SendPaymentWhatsApp.php
<?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!"
        );
    }
}
app/Providers/EventServiceProvider.php — register both listeners
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.