IS Instant Server

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.

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

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

CodeMeaningWhat to do
401API key is invalid or missingCheck the Authorization header
403The key has no rights to that sessionUse the Session ID from your workspace
400Invalid body, or the session is not readyMake sure the number status is ready
404Session not foundCheck the Session ID
429Too many requestsBack off and retry

Limits worth knowing

Need help? Email support@instantserver.dev.