API Overview & Base Headers
All API requests must be made over HTTP/HTTPS with JSON payloads. Authenticate every call using your Client UID (full UUID) and secret API key.
Base URL:
https://ecwhatsapp.bizws.com/api/v1
Required Headers:
X-Client-UID & X-API-Key
Idempotency & CORS:
Supported
POST
/api/v1/messages
Dispatches a WhatsApp text message to the specified recipient phone number.
Request Headers:
| Header | Type | Required | Description |
|---|---|---|---|
X-Client-UID | String | Yes | Full client UUID (e.g. 550e8400-e29b-41d4-a716-446655440000). |
X-API-Key | String | Yes | Client secret API key (e.g. ec_live_...). |
Idempotency-Key | String (UUID) | Recommended | Unique string preventing duplicate message dispatch. |
Request Body Parameters (JSON):
| Field | Type | Required | Description |
|---|---|---|---|
to | String | Yes | Recipient phone with country code (e.g. 919876543210 without +). |
text | String | Yes | WhatsApp message text content. |
account_uid |
String | Optional |
WhatsApp line account UID (e.g. wa-t16fuun).
If omitted, the API automatically selects a random active account from your client account list.
|
Sample Request:
{
"to": "919876543210",
"text": "Hello! Testing WhatsApp message delivery via EC WhatsApp API."
}Sample Response (202 Accepted):
{
"message_uid": "MSG04C1F1F8AF3F82CCA3C3",
"status": "queued",
"account_uid": "wa-t16fuun"
}
GET
/api/v1/messages/:message_uid
Retrieves real-time message status (queued → sent → delivered → read).
Sample Response (200 OK):
{
"message_uid": "MSG04C1F1F8AF3F82CCA3C3",
"account_uid": "wa-t16fuun",
"destination": "919876543210",
"message_type": "text",
"status": "sent",
"created_at": "2026-11-14T07:13:14.000Z",
"updated_at": "2026-11-14T07:13:15.000Z"
}
GET
/api/v1/accounts
Lists all WhatsApp account lines configured for your client UID with live connection status.
Next.js / React (Client or Server Action)
export async function sendWhatsAppMessage({ to, text }) {
const res = await fetch("http://localhost:3000/api/v1/messages", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Client-UID": process.env.NEXT_PUBLIC_EC_CLIENT_UID, // e.g. full UUID
"X-API-Key": process.env.EC_API_KEY, // e.g. ec_live_...
"Idempotency-Key": crypto.randomUUID()
},
body: JSON.stringify({
to,
text
// account_uid is optional; omitted to automatically pick an active line at random
})
});
const data = await res.json();
if (!res.ok) throw new Error(data.message || data.error);
return data; // { message_uid: "MSG...", status: "queued", account_uid: "wa-..." }
}cURL Command
curl -X POST http://localhost:3000/api/v1/messages \
-H "Content-Type: application/json" \
-H "X-Client-UID: 550e8400-e29b-41d4-a716-446655440000" \
-H "X-API-Key: ec_live_your_api_key_here" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"to": "919876543210",
"text": "Hello from cURL via EC WhatsApp Gateway! 🚀"
}'Node.js Fetch Script
const res = await fetch('http://localhost:3000/api/v1/messages', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Client-UID': '550e8400-e29b-41d4-a716-446655440000',
'X-API-Key': 'ec_live_your_api_key_here',
'Idempotency-Key': 'order-' + Date.now()
},
body: JSON.stringify({
to: '919876543210',
text: 'Your order confirmation from Node.js!'
})
});
const data = await res.json();
console.log('Dispatched message ref:', data.message_uid, 'Line:', data.account_uid);Security & IP Access Control
Super Admin Access
All /admin/* routes (including Super Admin login) are strictly restricted by IP address via admin_ips.json.
- Configured in
admin_ips.json. - Unlisted IPs are blocked with
403 Forbidden - Admin Access Denied. - Localhost (
127.0.0.1) is automatically protected and preserved.
Client API & User IP Restrictions
Clients and individual operators can configure IP access allowlists:
- Empty allowlist: Requests/logins are allowed from ANY IP.
- 1+ allowed IPs: Requests/logins are strictly restricted to the specified IPs or CIDR blocks.
- Supports standard IPv4 (e.g.
192.168.1.100,10.0.0.0/24) and IPv6 (::1).