This is the operator and developer guide for the ActiWAPI WhatsApp API for developers. Learn WhatsApp webhook integration, how to open a workspace, pair a number, send WhatsApp messages via API with the WhatsApp REST API and WhatsApp messaging API, run WhatsApp campaign workflows, and browse the interactive OpenAPI documentation at /api-docs.

Interactive Swagger UI

Try authenticated requests, inspect schemas, and browse tags for Sessions, Messages, Inbox, Campaigns, Contacts, Number Check, Webhooks, API Keys, External API, Team, Billing, Support, and Notifications.

Open Swagger UI

What you get

ActiWAPI connects your own WhatsApp number via QR (WhatsApp Web / linked device), then exposes that session to the dashboard and REST API. It is not Meta Cloud API onboarding. You must still follow WhatsApp Terms of Service, anti-spam rules, and local law.

Sessions — pair, reconnect, warmth, test send
Messages — text, image, document, audio with delivery tracking
Inbox — unified threads across numbers, assign and resolve
Contacts and groups — CSV, WhatsApp registration flags
Number Check — single and bulk “is this number on WhatsApp?”
Campaigns — paced bulk send, schedule, pause, retry
Webhooks — HMAC-signed HTTPS events
External API — API keys for your backend
Realtime — Socket.io for QR and live inbox
Team, billing (Razorpay / INR), support tickets, notifications

Operator guide (dashboard)

Create an account. Complete captcha, mobile OTP, and email verification. A 14-day trial starts automatically — no credit card.
Open Sessions, create a named line, click Connect, and scan the QR from WhatsApp → Linked devices. Keep the phone online.
Send a test message from the session page. Confirm it appears in Inbox. Reply from Inbox to keep the conversation on the same thread.
Import contacts (CSV), run Number Check, put people in groups, then create a campaign. Check device warmth before a large send.
Invite teammates (owner/admin). Create an API key only if you have a server that will call /api/external. Register a webhook URL for automation.
When the trial ends the workspace moves to the Free plan with limited quotas. Data stays. Upgrade from Billing (UPI, cards, net banking via Razorpay, prices in INR).

Developer guide (REST)

Prefer the hosted signup for the first workspace. Direct POST /api/auth/register is the same multi-step flow (captcha → register → mobile OTP → email verify → login).
Login with POST /api/auth/login (captcha required) and send Authorization: Bearer {accessToken} on dashboard routes. Refresh with POST /api/auth/refresh.
Pair a session (Sessions). Listen on Socket.io for qr_generated or poll status.
Send with POST /api/messages/send-text using sessionId, phone (country code), and text. Queued sends return HTTP 202.
For backends, create a key (API Keys) and call only /api/external with X-API-Key.
Subscribe to webhooks and verify X-Webhook-Signature (HMAC-SHA256 of the raw body). Event names use underscores: message_received, campaign_progress, and the others listed in Webhooks.

Base URLs

Most resources exist at both /api/... and /api/v1/.... Socket.io connects to the API host root, not /api.

API v1https://api.actiwapi.com/api/v1

Authenticationhttps://api.actiwapi.com/api/auth

Sessions (WhatsApp)https://api.actiwapi.com/api/v1/whatsapp

Messageshttps://api.actiwapi.com/api/messages

Inboxhttps://api.actiwapi.com/api/chats

External (API key)https://api.actiwapi.com/api/external

Billinghttps://api.actiwapi.com/api/billing

Socket.iohttps://api.actiwapi.com

Authentication

Every authenticated request uses exactly one of:

JWT Bearer

Dashboard, inbox, team, billing, keys, webhooks

Authorization: Bearer {accessToken}

API Key

Only /api/external/*

X-API-Key: {apiKey}

Successful JSON uses { "success": true, "data": ... }. Failures use success: false plus message (see error codes below).

Limits, warmth, and Free plan

Plans cap WhatsApp sessions, contacts, daily messages, campaigns, API requests, seats, and webhooks. Extra capacity is sold as add-ons. ActiWAPI paces outbound traffic per session (gaps, jitter, one socket owner) to reduce ban risk — it cannot guarantee WhatsApp will never restrict a number.

After trial, Free plan quotas apply. Outbound is not wiped; it is limited. Paid plans restore higher throughput immediately after Razorpay verification.

API guides

Each page includes a written guide plus every public endpoint for that area.

Error codes

Failed requests return a JSON envelope with success: false and a human-readable message.

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "phone": "Valid phone number is required"
  }
}

HTTP	Code	Description
400	VALIDATION_ERROR	Request body or query failed validation.
401	UNAUTHORIZED	Missing or invalid JWT / API key.
403	FORBIDDEN	Authenticated but lacking permission or entitlement.
403	SUBSCRIPTION_INACTIVE	Action not allowed on the current plan (including Free after trial). Upgrade or wait for entitlements.
403	LIMIT_EXCEEDED	Plan limit reached (sessions, messages, API requests, etc.).
404	NOT_FOUND	Resource does not exist or is not in your account.
409	CONFLICT	Duplicate resource or invalid state transition.
429	RATE_LIMITED	Too many requests; retry after backoff.
500	INTERNAL_ERROR	Unexpected server error.
502	WHATSAPP_UNAVAILABLE	WhatsApp session disconnected or provider error.