+254722962934 +254141096575 info@mspace.co.ke WhatsApp Portal USSD Portal Customer Portal Staff Portal Affiliates Feedback PC App Mobile App
REST API v2 · JSON

Bulk WhatsApp Business API

Send single and bulk WhatsApp messages, track delivery and campaign progress, list approved templates, check wallet credits, and receive signed webhooks.

Base URL: https://smsgateway.mspace.co.ke/whatsapp Open WhatsApp Portal

1. Authentication

Every /api/v2/** request requires an active WhatsApp-enabled account and API key. Generate or rotate your key in the WhatsApp Portal under API Docs.

Option A — Dedicated Headers (Recommended)
Content-Type: application/json
X-Username: YOUR_USERNAME
X-API-Key: YOUR_API_KEY
Option B — HTTP Bearer Token
Content-Type: application/json
Authorization: Bearer YOUR_USERNAME:YOUR_API_KEY

Notes: GET endpoints also accept ?username=...&apiKey=... query parameters, and POST bodies accept username/apiKey. Parent account API keys can also dispatch on behalf of direct sub-accounts by passing the sub-account username in X-Username.

2. Endpoint Directory

Bulk WhatsApp REST API v2 endpoints
Method Path (prefix: https://smsgateway.mspace.co.ke/whatsapp) Auth Purpose
POST /api/v2/messages/bulk API Key Queue an asynchronous bulk campaign to multiple recipients with per-recipient template variables. Returns 202 Accepted.
POST /api/v2/messages API Key Send a single message (template, text, media, interactive_buttons, or cta_url). Returns 201 Created.
GET /api/v2/messages/{wamid}/status API Key Check delivery status (SENT, DELIVERED, READ, FAILED, OPTOUT) and timestamps for a message ID.
GET /api/v2/campaigns/{campaignId} API Key Get live bulk campaign totals and delivery counters (total, sent, delivered, read_count, failed).
GET /api/v2/templates API Key List approved Meta templates available on your sender number along with variable counts and header types.
GET /api/v2/account/balance API Key Check remaining WhatsApp credits and per-category KES message rates (costPerMarketing, costPerUtility, costPerAuthentication).
POST /api/v2/webhooks/test API Key Send a signed test delivery event to your configured client webhook URL.
GET/POST /api/v2/webhook Meta Verify Meta Cloud API callback endpoint (hub.challenge handshake & X-Hub-Signature-256 delivery/inbound events) for bring-your-own-WABA setups.
GET /health Public Gateway health check. Returns {"status":"UP","service":"whatsapp-portal"}.

3. Endpoints & JSON Schemas

POST /api/v2/messages/bulk Queue a bulk WhatsApp campaign (personalized or broadcast)
POST /api/v2/messages/bulk request fields
Field Type Required Description
recipients array Required Non-empty array of phone strings ("254712345678") or objects ({"to":"254712345678","params":["John","KES 4,500"]}). Accepts 07... or 2547....
type string Optional TEMPLATE (default when templateName is provided), TEXT, MEDIA, INTERACTIVE_BUTTONS, or CTA_URL.
templateName string Template Exact approved Meta template name (alias: template).
language string Optional Template language code (e.g. en, en_US). Auto-detected if omitted.
campaignName string Optional Label for tracking in the portal and campaign status API.
params / paramsCount array / int Optional Shared fallback variables for all recipients and variable placeholder count.
headerType / headerMediaUrl string Optional For media-header templates: IMAGE, DOCUMENT, or VIDEO plus public HTTPS URL.
Request JSON — POST /api/v2/messages/bulk
{
  "campaignName": "Monthly Statement Run",
  "type": "TEMPLATE",
  "templateName": "payment_receipt",
  "language": "en",
  "paramsCount": 2,
  "recipients": [
    { "to": "254712345678", "params": ["John", "KES 4,500"] },
    { "to": "254722111000", "params": ["Mary", "KES 8,200"] }
  ]
}
Response — 202 Accepted
{
  "status": "RUNNING",
  "campaignId": 997,
  "total": 2
}
POST /api/v2/messages Send a single template, text, media, quick-reply, or CTA URL message
24-Hour Window Rule: Use type: "template" to message customers anytime (alerts, OTPs, receipts, promotions). Free-form text, media, interactive_buttons, and cta_url can only be sent within 24 hours of the customer's last reply.
POST /api/v2/messages request fields
Field Type Required Description
to string Required Recipient phone in E.164 (254712345678) or local (0712345678) format (alias: recipient).
type string Optional template, text (default), media, interactive_buttons, or cta_url.
templateName, language, params string / array Template Approved template name, language code, and ordered array of body variables. Optional headerType + headerMediaUrl.
message, previewUrl string / bool Text Plain text body (up to 4,096 chars) and optional link preview flag.
mediaType, mediaUrl, caption, filename string Media image, document, or video with public HTTPS URL, optional caption and PDF filename.
body, buttons / ctaLabel, ctaUrl string / array Interactive Up to 3 quick-reply labels (interactive_buttons) or CTA button text & URL (cta_url), plus optional headerText / footerText.
Request JSON — Template
{
  "to": "254712345678",
  "type": "template",
  "templateName": "order_confirmation",
  "language": "en",
  "params": ["Amina", "INV-9021"],
  "headerType": "IMAGE",
  "headerMediaUrl": "https://cdn.example.com/receipt-banner.png"
}
Response — 201 Created
{
  "status": "SENT",
  "messageId": "wamid.HBgLMjU0NzEyMzQ1Njc4FQIAERgSQk...",
  "recipient": "254712345678",
  "remainingCredits": 603.0
}
GET /api/v2/messages/{wamid}/status Check delivery status and timestamps by message ID
Request — cURL
curl -H "X-Username: YOUR_USERNAME" \
  -H "X-API-Key: YOUR_API_KEY" \
  "https://smsgateway.mspace.co.ke/whatsapp/api/v2/messages/wamid.HBgLMjU0.../status"
Response — 200 OK
{
  "id": 14521,
  "campaign_id": 997,
  "recipient": "254712345678",
  "message_id": "wamid.HBgLMjU0...",
  "template_name": "payment_receipt",
  "status": "READ",
  "error_code": null,
  "error_msg": null,
  "sent_at": "2026-11-20 10:12:04",
  "delivered_at": "2026-11-20 10:12:06",
  "read_at": "2026-11-20 10:12:41"
}
GET /api/v2/campaigns/{campaignId} Retrieve bulk campaign progress and aggregate delivery counters
Request — cURL
curl -H "X-Username: YOUR_USERNAME" \
  -H "X-API-Key: YOUR_API_KEY" \
  "https://smsgateway.mspace.co.ke/whatsapp/api/v2/campaigns/997"
Response — 200 OK
{
  "id": 997,
  "campaign_name": "Monthly Statement Run",
  "template_name": "payment_receipt",
  "message_type": "TEMPLATE",
  "total": 250,
  "sent": 248,
  "delivered": 245,
  "read_count": 198,
  "replied": 14,
  "failed": 2,
  "status": "COMPLETED"
}
GET /api/v2/templates List approved WhatsApp templates for your account
Request — cURL
curl -H "X-Username: YOUR_USERNAME" \
  -H "X-API-Key: YOUR_API_KEY" \
  "https://smsgateway.mspace.co.ke/whatsapp/api/v2/templates"
Response — 200 OK
{
  "whatsappEnabled": true,
  "templates": [
    {
      "name": "payment_receipt",
      "templateName": "payment_receipt",
      "language": "en",
      "category": "UTILITY",
      "status": "APPROVED",
      "body": "Hi {{1}}, we received {{2}}.",
      "paramsCount": 2,
      "headerType": "NONE"
    }
  ]
}
GET /api/v2/account/balance Check WhatsApp credit balance and per-category message rates
Request — cURL
curl -H "X-Username: YOUR_USERNAME" \
  -H "X-API-Key: YOUR_API_KEY" \
  "https://smsgateway.mspace.co.ke/whatsapp/api/v2/account/balance"
Response — 200 OK
{
  "username": "YOUR_USERNAME",
  "whatsappEnabled": true,
  "billingUserId": 1024,
  "credits": 1250.0,
  "costPerUtility": 1.0,
  "costPerMarketing": 4.0,
  "costPerAuthentication": 1.0
}
POST /api/v2/webhooks/test Trigger a live signed test webhook delivery
Request — cURL
curl -X POST \
  -H "X-Username: YOUR_USERNAME" \
  -H "X-API-Key: YOUR_API_KEY" \
  "https://smsgateway.mspace.co.ke/whatsapp/api/v2/webhooks/test"
Response — 200 OK
{
  "success": true,
  "httpStatus": 200,
  "message": "OK"
}

4. Code Examples

Send Bulk Campaign
curl -X POST "https://smsgateway.mspace.co.ke/whatsapp/api/v2/messages/bulk" \
  -H "Content-Type: application/json" \
  -H "X-Username: YOUR_USERNAME" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "campaignName": "Invoice Reminders",
    "type": "TEMPLATE",
    "templateName": "payment_receipt",
    "language": "en",
    "recipients": [
      { "to": "254712345678", "params": ["John", "KES 4,500"] },
      { "to": "254722111000", "params": ["Mary", "KES 8,200"] }
    ]
  }'
Send Single Template Message
curl -X POST "https://smsgateway.mspace.co.ke/whatsapp/api/v2/messages" \
  -H "Content-Type: application/json" \
  -H "X-Username: YOUR_USERNAME" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "to": "254712345678",
    "type": "template",
    "templateName": "order_confirmation",
    "language": "en",
    "params": ["Amina", "INV-9021"]
  }'

5. Signed Outbound Webhooks & Meta Callback

Configure your callback URL, signing secret, and subscribed events inside the WhatsApp Portal under Webhooks.

  • Every callback is an HTTP POST with headers X-MSpace-Event and X-MSpace-Signature: sha256=<hex> (HMAC-SHA256 over the exact UTF-8 JSON body).
  • Subscribed events: SENT, DELIVERED, READ, FAILED, INBOUND, and TEST.
  • Return any HTTP 2xx within 10 seconds. Failed deliveries automatically retry up to 5 times with exponential backoff (60s, 120s, 240s...).
  • Bring-Your-Own Meta App / WABA: Set Meta Developer Console callback URL to https://smsgateway.mspace.co.ke/whatsapp/api/v2/webhook (verifies hub.challenge and X-Hub-Signature-256).
Delivery Status Envelope (SENT / DELIVERED / READ / FAILED)
{
  "event": "DELIVERED",
  "timestamp": 1795171480000,
  "message_id": "wamid.HBgLMjU0NzEyMzQ1Njc4FQIAERgSQk...",
  "data": {
    "recipient": "254712345678",
    "status": "DELIVERED",
    "phone_number_id": "104591827364510",
    "timestamp": "1795171479"
  }
}
Inbound Customer Reply Envelope (INBOUND)
{
  "event": "INBOUND",
  "timestamp": 1795171502000,
  "message_id": "wamid.HBgLMjU0NzEyMzQ1Njc4FQIAERgSQk...",
  "data": {
    "from": "254712345678",
    "contact_name": "John Kamau",
    "type": "text",
    "body": "Confirm Visit",
    "phone_number_id": "104591827364510",
    "is_opt_out": false
  }
}

6. HTTP Status Codes

HTTP status codes returned by Bulk WhatsApp API v2
HTTP Status Meaning When Returned / Action
200 / 201 / 202 Success 200 query/test succeeded, 201 single message sent, 202 bulk campaign queued.
400 Bad Request Missing or invalid to, empty recipients array, or missing required field for the chosen message type.
401 Unauthorized Invalid X-Username / X-API-Key or Bearer token. Verify or rotate your key in the portal.
402 Payment Required Insufficient WhatsApp credits. Recharge via self-service top-up at mspace.co.ke/buy.
403 Forbidden WhatsApp Business API is not yet enabled on the account or sub-account lacks API permission.
404 Not Found Unknown wamid or campaignId for your account.
422 Unprocessable Entity Recipient has opted out in the Opt-Out Registry; message blocked automatically.
502 Bad Gateway Meta rejected the dispatch (credit is automatically refunded) or your webhook test endpoint failed.

7. Key Rules

  • Phone numbers accept local Kenyan format (0712345678) or international E.164 (254712345678) and are normalized automatically.
  • Template variables in params must match the exact number of {{1}}, {{2}}... placeholders in your approved template.
  • Media URLs (mediaUrl and headerMediaUrl) must be publicly reachable over HTTPS.
  • If Meta rejects a single send, the deducted credit is automatically refunded to your WhatsApp balance.
WhatsApp Support
End Chat X

Welcome to MSpace! 😊

We'd love to help you! Kindly share your contact details below so we can serve you better and get back to you promptly.

How are you connecting with us today?
Please fill all required fields.
MSpace AI
MSpace
Ms. Bonga
Ms. Bonga Virtual Assistant • Online
×
Hi! I'm Ms. Bonga 😊
Kindly share your contact details below so our team can assist you better and get back to you promptly.