WhatsApp API Documentation & Integration Guide

Build and integrate WhatsApp automation with the NullChat WhatsApp API. This developer documentation explains how to authenticate API requests, create and manage WhatsApp sessions, connect numbers with QR codes, send messages and media, receive webhook events, and integrate WhatsApp into your applications.

Whether you are building a website, automation system, customer support platform, or custom backend, this guide walks you through the main WhatsApp API integration workflow from your first request to production deployment.

DEVELOPER DOCUMENTATION

From Zero to Your First WhatsApp API Request

The WhatsApp API allows developers to connect their applications with NullChat and automate WhatsApp communication. Start by creating a NullChat account, generating an API key, creating a WhatsApp session, connecting your number with a QR code, and making your first API request.

For development and testing, you can create a sandbox session. Sandbox requests are simulated and do not send real WhatsApp messages.

Create a sandbox session

curl -X POST "http://localhost:3000/api/v1/sessions" \
  -H "Authorization: Bearer YOUR_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Development","mode":"sandbox"}'

i Sandbox requests return simulated: true. They do not send messages to WhatsApp.

If you are new to NullChat, start with our Developers Guide to understand the API structure and integration process.

For additional web development resources and technical guidance, visit MSajjad.io.

WhatsApp API Authentication for Developers

Authenticate your requests using a secret API key. The base URL is https://nullchat.cloud/. Developers must send Authorization: Bearer YOUR_API_KEY in the header of every request. Keys will always begin with wa_sandbox_ or wa_live_.

Keep API keys secure and store them in server-side environment variables. Never place API keys inside HTML, browser-side JavaScript, public repositories, or URLs.Before making API requests, make sure you understand your account and available WhatsApp API plans.

If a key becomes exposed, revoke it and generate a replacement from your NullChat dashboard.

Check your key and limits

curl "http://localhost:3000/api/v1/me" -H "Authorization: Bearer YOUR_API_KEY"

This request can be used to verify your authentication and inspect information associated with the current API environment.

Manage WhatsApp Sessions and QR Connections

WhatsApp sessions allow your application to connect a WhatsApp number to the WhatsApp Web API.

For live messaging, developers must have an active plan, create a live API key, and create a live session. After creating the session, use the connect endpoint to start the connection process.

When a QR code becomes available, scan it using WhatsApp under Linked devices.

Wait until the session reports a connected status before sending live messages.

QR codes can expire and refresh automatically. If your server restarts, use the Connect endpoint to resume a saved session when credentials are available.

Method	Endpoint	Behavior
GET	/sessions	List sessions for the current API environment.
POST	/sessions	Create a new session.
GET	/sessions/id	Read session status and QR information.
POST	/sessions/id/connect	Start a live QR connection or mark sandbox ready.
POST	/sessions/id/disconnect	Stop the connection while retaining credentials.
DELETE	/sessions/id	Log out and remove the session.

This session workflow is one of the core parts of a WhatsApp API integration with NullChat.

Send WhatsApp Messages and Media

Once your WhatsApp session is connected, your application can send messages through the API.

Use an international phone number containing 8–15 digits. Include the country code first and do not include a plus sign or spaces.

A message body can contain up to 4,000 characters.

Nodejs 22+ · built-in fetch

const response = await fetch("http://localhost:3000/api/v1/messages", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.WA_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID()
  },
  body: JSON.stringify({
    session_id: "YOUR_SESSION_ID",
    to: "923001234567",
    body: "Hello from my application!"
  })
});
const data = await response.json();
if (!response.ok) throw new Error(data.error);
console.log(data);

Use the same Idempotency-Key when retrying an uncertain request. If the key and payload remain the same, the API returns the stored result. A different payload with the same idempotency key returns a 409 error.

Media payload · up to 5 MB decoded

{
  "session_id": "YOUR_SESSION_ID",
  "to": "923001234567",
  "body": "Your invoice is attached.",
  "media": {
    "mimetype": "application/pdf",
    "filename": "invoice.pdf",
    "data": "BASE64_ENCODED_FILE"
  }
}

The API supports various MIME types including image/jpeg, image/png, application/pdf, audio/ogg, and video/mp4. Attachments are forwarded directly to WhatsApp, supporting files up to 5 MB.

GET /messages?page=1 returns 30 history records per page. History includes inbound messages from live sessions while the server is connected. A sent status means WhatsApp accepted the request, not a guarantee of delivery or reading.

Receive and Verify WhatsApp Webhook Events

Webhooks allow your application to receive real-time events from the WhatsApp API.

Create a public HTTPS endpoint in the NullChat Webhooks settings. You will receive a one-time signing secret that can be used to verify incoming webhook requests.Available events include: message.sent, message.received, session.updated.

Verify the X-WA-Signature using HMAC-SHA256 over timestamp + ‘.’ + rawBody. Reject timestamps older than 5 minutes to prevent replay attacks. Ensure your server returns a 2xx response within 10 seconds to prevent automatic retries.

If your endpoint returns another response, the webhook delivery can be retried up to five times using exponential delays.

Only public HTTPS endpoints on port 443 are supported. Redirects and private network destinations are blocked.

Updating your webhook endpoint rotates its signing secret and cancels previous pending deliveries.

Add a WhatsApp Chat Widget to Your Website

NullChat also provides a website chat widget that allows visitors to start a WhatsApp conversation directly from your website. In the Website Widget settings, configure: Business name, WhatsApp number, Default message, Widget color.

After saving the configuration, copy the generated embed code and place it before the closing body tag of your website.

HTML · public ID, no secret API key

<script src="http://localhost:3000/embed.js" data-widget="YOUR_WIDGET_ID" defer></script>

The widget securely opens a WhatsApp conversation using a wa.me link.

It does not automatically send messages on behalf of website visitors.

For website integration questions, you can also contact NullChat support for assistance.You can also explore NullChat’s WhatsApp automation solutions for additional integration options.

WhatsApp API Plans and NayaPay Payments

NullChat offers both monthly and lifetime WhatsApp API plans.

Choose the plan that matches your expected API usage, create an order, transfer the exact PKR amount to the displayed NayaPay account, and submit your transaction reference for approval.

Monthly access lasts for one calendar month from the time of approval. Message limits automatically reset on the first day of each month at 00:00 UTC. Developers can combine multiple active purchases to increase their available limits. For current plan information and payment details, visit the NullChat WhatsApp API service page.

WhatsApp API Limits and Error Handling

Understanding API errors is important when building a reliable WhatsApp API integration.

Status	Meaning
400	Invalid request fields. Check the error property.
401	Missing, invalid, revoked key, or expired sign-in.
402	A paid plan is required or access has expired.
403	Access denied, domain restriction, or session limit.
404	Resource not found in the current account or environment.
409	Conflicting request, disconnected session, or duplicate reference.
429	Message quota or request rate limit reached.
502	Provider result is uncertain. Check message history before retrying.
503	Required server integration is not configured.

Sandbox accounts allow up to three sessions and 100 simulated requests per UTC day.

Live API limits depend on your active purchases.

For example, a 401 response normally indicates an invalid or revoked API key, while a 429 response indicates that your request or message limit has been reached.

If a key is revoked or a plan expires, API access is removed immediately.

Self-Hosted Server Setup for Advanced Developers

Use Node.js 22.13 or newer on a persistent server. Install dependencies with npm install, copy .env.example to .env, and run npm start. The terminal will print a one-time link to create the first administrator.

In Platform settings, enter your NayaPay account title and ID or IBAN. Set a USD-to-PKR checkout rate, or edit all plans to use PKR pricing. Plan prices and the Enterprise monthly default must be reviewed before launch.

For live messaging, set WHATSAPP_ENABLED=true and point CHROME_PATH to a Chrome or Chromium executable. Restart the server and scan the real WhatsApp QR code.

For production environments, developers must use HTTPS, set NODE_ENV=production, and generate a random APP_SECRET of at least 32 characters. Keep your data directory completely private and persistent.

This is an independent integration built on whatsapp-web.js. It is not the official WhatsApp Business Platform. Read the upstream project documentation before operating live accounts.