API Documentation

Authentication

All API requests require an API key in the Authorization header. Generate keys from the dashboard — each key is shown once at creation.

Authorization: Bearer gnm_live_your_api_key_here

POST /api/v1/send

Send a WhatsApp template message. Credits are deducted before the message is sent based on country and message type.

POST /api/v1/send
Authorization: Bearer gnm_live_...
Content-Type: application/json

{
  "to": "+9647701234567",
  "template_name": "order_confirmation",
  "type": "UTILITY",
  "params": ["Ahmed", "ORD-12345"]
}

→ 200 OK
{
  "success": true,
  "message_id": "uuid",
  "credits_remaining": 487
}

type must be one of: AUTH (OTP Codes), UTILITY (Notifications), or MARKETING (Broadcast Campaigns). Broadcast Campaigns require PAYG wallet credits.

POST /api/v1/otp/send

Send a 6-digit OTP code via WhatsApp. Uses the AUTH message type. Code expires in 600 seconds.

POST /api/v1/otp/send
Authorization: Bearer gnm_live_...
Content-Type: application/json

{ "to": "+9647701234567" }

→ 200 OK
{ "success": true, "expires_in": 600 }

POST /api/v1/otp/verify

Verify an OTP code. Maximum 3 attempts per code. Returns valid: true or valid: false.

POST /api/v1/otp/verify
Authorization: Bearer gnm_live_...
Content-Type: application/json

{
  "to": "+9647701234567",
  "code": "482910"
}

→ 200 OK
{ "valid": true }

POST /api/v1/broadcast

Send a Broadcast Campaign template to many recipients in one request. Broadcasts are billed to your marketing wallet only — never to subscription credits. Maximum 1,000 recipients per request.

channel_id is required and names the WhatsApp Business number the campaign sends from. Find the id on the Channels page. It must belong to your account and be connected — a channel id that is unknown, disconnected, or archived is rejected with 400 invalid_channel.

The response returns immediately with 202 Accepted while messages send in the background. Duplicate numbers are removed before pricing, and the entire batch is costed and checked against your wallet up front — if you cannot afford all of it, nothing is sent.

POST /api/v1/broadcast
Authorization: Bearer gnm_live_...
Content-Type: application/json

{
  "channel_id": "3f2a9c81-...",
  "template_name": "summer_promo",
  "recipients": [
    "+9647701234567",
    "+971501234567",
    "+201001234567"
  ],
  "params": ["Ahmed"]
}

→ 202 Accepted
{
  "success": true,
  "broadcast_id": "b7c1e2a4-...",
  "status": "processing",
  "total_recipients": 3,
  "estimated_credits": 18,
  "estimated_completion_seconds": 1
}

GET /api/v1/broadcast/{id}/status

Poll a broadcast for progress. Delivery counts update as WhatsApp confirms each message, so delivered_count continues to rise after the broadcast reaches completed.

GET /api/v1/broadcast/b7c1e2a4-.../status
Authorization: Bearer gnm_live_...

→ 200 OK
{
  "broadcast_id": "b7c1e2a4-...",
  "template_name": "summer_promo",
  "status": "processing",
  "total_recipients": 500,
  "sent_count": 320,
  "delivered_count": 287,
  "failed_count": 4,
  "pending_count": 176
}

WhatsApp messaging tiers

WhatsApp limits every business account to a fixed number of unique recipients per rolling 24 hours. This is set by Meta, not by us, and it rises as your account builds a sending history at a good quality rating.

Broadcasts are checked against your remaining tier capacity before anything is charged or sent. If a request would exceed it, the whole broadcast is rejected with 429 tier_limit_exceeded and no credits are spent — split the list and send the remainder once the 24-hour window rolls forward.

→ 429 Too Many Requests
{
  "error": "tier_limit_exceeded",
  "message": "This broadcast would exceed the WhatsApp messaging tier for the last 24 hours.",
  "current_count": 850,
  "limit": 1000,
  "remaining": 150
}

Broadcast error codes

Every one of these is returned before any message is sent, so a rejected broadcast never costs credits.

Error codes