WhatsApp Gateway API
For WA Starter, WA Business and WA Scale customers. The base URL, API key and Session ID for your workspace are on the service page in the billing panel.
Important: this gateway runs a WhatsApp Web session on your own number, not Meta's official WhatsApp Cloud API. Messages are sent from the number you link by scanning a QR code. WhatsApp gives no delivery guarantee and there is no automatic OTP autofill, for critical OTPs, provide a fallback channel (SMS or email).
1. Authentication
Every API call uses the host https://wa-api.instantserver.dev.
The gateway's admin dashboard lives on a different host and is internal-only, you do not need access to it.
Each request carries an Authorization header with your workspace API key.
The key only covers the numbers in your workspace; requests for another customer's number
are rejected with 403.
Authorization: Bearer YOUR_API_KEY
Never put the API key in frontend code or a public repository. Store it as an environment variable on your server.
2. Linking a number (QR)
A number is linked once, from the service page in the billing panel:
open Services → WhatsApp → Connect, then scan the QR with
WhatsApp on your phone (Linked devices → Link a device).
Once the status reads ready, the number is usable through the API.
You can read a number's status at any time:
GET/api/sessions/{sessionId}
{
"id": "b0370086-9050-40ff-aa45-3f0034e26738",
"name": "is27-my-business-1",
"status": "ready",
"phone": "6281234567890",
"pushName": "My Store"
}
3. Sending messages
POST/api/sessions/{sessionId}/messages/send-text
curl -X POST "https://wa-api.instantserver.dev/api/sessions/<SESSION_ID>/messages/send-text" \
-H "Authorization: Bearer $OPENWA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"chatId":"6281234567890@c.us","text":"Hello from Instant Server"}'
The response contains a messageId and a timestamp:
{"messageId":"3EB0A1B2C3D4E5F6","timestamp":1761150000}
chatId format
- Personal number:
62xxxxxxxxxx@c.us(country code without the+) - Group:
xxxxxxxxxx@g.us, take it from a webhook or the group list
WhatsApp sometimes sends the sender ID as
<digits>@lid, which is not a phone number. For two-way conversations,
always store the chatId you receive from the webhook, do not rebuild it from the phone number.
Node.js example
const res = await fetch(
`https://wa-api.instantserver.dev/api/sessions/${process.env.WA_SESSION_ID}/messages/send-text`,
{
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.WA_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ chatId: '6281234567890@c.us', text: 'Hello!' }),
}
);
console.log(await res.json());
PHP example
$ch = curl_init("https://wa-api.instantserver.dev/api/sessions/{$sessionId}/messages/send-text");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'chatId' => '6281234567890@c.us',
'text' => 'Hello!',
]),
]);
echo curl_exec($ch);
4. Reading inbound messages
GET/api/sessions/{sessionId}/messages?limit=50
Returns the latest messages for that session. For real-time processing, use the webhook described in the next section.
5. Webhooks
Webhooks are configured per workspace by us. Send us your receiver URL and we register it on your session. Every delivery carries a signature:
X-OpenWA-Signature: sha256=<hex>
X-OpenWA-Idempotency-Key: <uuid>
The signature is an HMAC-SHA256 of the raw body using your webhook secret. Verify it before processing, and dedupe on the idempotency key.
const crypto = require('crypto');
function verify(rawBody, header, secret) {
const expected = 'sha256=' + crypto
.createHmac('sha256', secret)
.update(rawBody)
.digest('hex');
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}
The data payload is the message from the WhatsApp engine, not a row from the gateway database.
Use fromMe and isGroup to determine message direction,
there is no direction field in the payload.
6. Usage statistics
GET/api/stats/sessions/{sessionId}
{
"session": { "id": "...", "name": "is27-my-business-1", "status": "ready" },
"messages": { "sent": 128, "received": 96, "today": 14, "failed": 2 }
}
7. Error codes
| Code | Meaning | What to do |
|---|---|---|
| 401 | API key is invalid or missing | Check the Authorization header |
| 403 | The key has no rights to that session | Use the Session ID from your workspace |
| 400 | Invalid body, or the session is not ready | Make sure the number status is ready |
| 404 | Session not found | Check the Session ID |
| 429 | Too many requests | Back off and retry |
Limits worth knowing
- No monthly message cap on our side, but WhatsApp applies its own limits to new numbers. Warm a new number up gradually.
- One number, one session. Do not link the same number twice, the previously linked device can be revoked.
- The first message to a new contact may not arrive even when the API answers successfully; that is WhatsApp policy, not a gateway fault.
- Do not use your main number. Use a number dedicated to this service.
Need help? Email support@instantserver.dev.