WhatsAppDev API

Send WhatsApp messages from your applications, manage connected sessions, track message delivery and receive real-time webhook notifications.

Authentication

Every API request must include your API key using the Bearer authentication scheme.

Authorization: Bearer wapi_live_YOUR_API_KEY

List WhatsApp Sessions

GET /v1/sessions

Returns the WhatsApp accounts connected to your account.

curl -X GET \
  'https://whatsappdev.top/v1/sessions' \
  -H 'Authorization: Bearer wapi_live_YOUR_API_KEY' \
  -H 'Accept: application/json'

Response

{
  "success": true,
  "data": [
    {
      "session": "ses_8bf81995f22c197daec42138",
      "name": "My WhatsApp",
      "phone": "+254771367662",
      "status": "WORKING",
      "connected": true,
      "last_active_at": "2026-10-08 12:20:00"
    }
  ]
}

Get WhatsApp Session

GET /v1/sessions/{session}

Replace {session} with the Public Key from your Sessions table, for example ses_8bf81995f22c197daec42138. You can also get it from the session field in GET /v1/sessions. It is a public identifier, not your secret API key. Use a session owned by the same account as your API key.

curl -X GET \
  'https://whatsappdev.top/v1/sessions/ses_8bf81995f22c197daec42138' \
  -H 'Authorization: Bearer wapi_live_YOUR_API_KEY'

Send Text Message

POST /v1/messages/text

curl -X POST \
  'https://whatsappdev.top/v1/messages/text' \
  -H 'Authorization: Bearer wapi_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "session": "ses_8bf81995f22c197daec42138",
    "to": "0771367662",
    "message": "Your verification code is 482193"
  }'

Response

{
  "success": true,
  "data": {
    "message_id": "msg_e8992052937f46dc8c4fb730",
    "status": "QUEUED",
    "session": "ses_8bf81995f22c197daec42138",
    "to": "254771367662"
  }
}

Get Message Status

GET /v1/messages/{message_id}

curl -X GET \
  'https://whatsappdev.top/v1/messages/msg_e8992052937f46dc8c4fb730' \
  -H 'Authorization: Bearer wapi_live_YOUR_API_KEY'

Replace {message_id} with the data.message_id returned when you send a message (the msg_... value). Save it in your application to track delivery. You can also find it in Messages and its details page. Use an API key from the account that sent the message.

{
  "success": true,
  "data": {
    "message_id": "msg_e8992052937f46dc8c4fb730",
    "type": "text",
    "to": "254771367662",
    "status": "DELIVERED",
    "session": {
      "id": 42,
      "name": "My WhatsApp",
      "phone": "+254771367662"
    },
    "attempts": {
      "current": 1,
      "maximum": 4
    },
    "error": null
  }
}

Webhooks

Instead of repeatedly requesting message status, you can register a webhook endpoint in your developer dashboard.

Example webhook

{
  "id": "evt_07124ad9f9ef71f97bc0b325",
  "event": "message.delivered",
  "created_at": "2026-10-08T09:12:30Z",
  "data": {
    "message_id": "msg_e8992052937f46dc8c4fb730",
    "session": "ses_8bf81995f22c197daec42138",
    "to": "254771367662",
    "status": "DELIVERED"
  }
}

Verify Webhook Signatures

WhatsAppDev signs webhook requests using your webhook signing secret.

The following headers are sent:

X-Webhook-Id: evt_07124ad9f9ef71f97bc0b325
X-Webhook-Event: message.delivered
X-Webhook-Timestamp: 1791444300
X-Webhook-Signature: sha256=...

PHP verification example

Create an endpoint in Webhooks and copy the signing secret shown after creation. Use that whsec_... secret below, not your API key or session public key. Keep it on your server and verify the signature against the unmodified request body.

$secret = 'whsec_YOUR_WEBHOOK_SECRET';

$timestamp =
    $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '';

$signature =
    $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

$body =
    file_get_contents('php://input');

$expected =
    'sha256=' . hash_hmac(
        'sha256',
        $timestamp . '.' . $body,
        $secret
    );

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

$data = json_decode($body, true);

http_response_code(200);

echo 'OK';

Message Statuses

Error Responses

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key."
  }
}

404 Session Not Found

{
  "success": false,
  "error": {
    "code": "SESSION_NOT_FOUND",
    "message": "WhatsApp session not found."
  }
}

409 Session Not Connected

{
  "success": false,
  "error": {
    "code": "SESSION_NOT_CONNECTED",
    "message": "The WhatsApp session is not connected."
  }
}

422 Validation Error

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request contains invalid data.",
    "fields": {
      "to": "A valid phone number is required."
    }
  }
}