WhatsApp API frequently asked questions

ActiWAPI is a WhatsApp messaging platform and API for businesses and developers. Connect WhatsApp numbers via QR, send messages over REST, verify numbers before campaigns, manage a unified inbox, run bulk campaigns, receive HMAC-signed webhooks, invite a team, and bill through Razorpay — all from one workspace.

Sign up, complete captcha, then verify mobile and email. Your 14-day trial starts automatically with no credit card. Connect a WhatsApp session by scanning the QR in the dashboard, then send a test message from the session page, inbox, or REST API.

ActiWAPI uses session-based WhatsApp Web connectivity — you connect your own number via QR scan. This is suitable for many SMB and developer use cases without Meta Cloud API / BSP onboarding. You must still comply with WhatsApp Terms of Service, anti-spam rules, and local regulations in India and your operating regions.

Most teams pair the first session and send a test message within about 10 minutes. Production work (webhooks, CSV contacts, number checking, campaigns, API keys) usually takes a few hours depending on your stack.

After 14 days the workspace is moved onto the Free plan with limited quotas. Contacts, campaigns, inbox history, and session configuration are kept. Outbound sending continues only within Free limits — upgrade anytime from Billing to restore paid plan capacity. You will also get an email and in-app notification when this conversion happens.

We accept payments through Razorpay including UPI, credit/debit cards, net banking, and wallets. All listed prices are in INR. Choose monthly billing or pay annually upfront where the pricing page shows an annual option.

Yes. Upgrade or downgrade from Billing in the dashboard. Upgrades take effect immediately with prorated Razorpay billing when applicable. Downgrades apply at the start of the next billing cycle.

Extend your plan with add-ons such as extra WhatsApp numbers, team seats, or white-label branding from Billing — without jumping to the next plan tier. Current add-on prices are on the pricing page and GET /api/billing/addons.

Annual billing is available on eligible plans when you commit to 12 months upfront. Discount percentages are listed on the pricing page. Custom enterprise agreements: sales@actiwapi.com.

Free is the forever plan applied when a trial expires and you have not subscribed. It keeps the workspace usable with smaller session, message, contact, and API quotas. It is not a pause of the account. Check live limits under Billing → usage or GET /api/billing/usage.

Session limits depend on your subscription and extra-number add-ons. See the pricing page and the usage meters in the dashboard.

The dashboard, Socket.io (session_disconnected), in-app notifications, and optional webhooks surface the change. Reconnect from Sessions and scan a new QR if WhatsApp requires pairing again. Keep the phone online; ActiWAPI uses a single socket owner so the linked device is not opened twice.

WhatsApp allows linked devices per account type. The ActiWAPI session is a linked device running on our infrastructure. Review WhatsApp multi-device rules for your account so you do not exceed linked-device limits.

Sends are serialized per session with minimum gaps and humanized delays. Campaigns stagger recipients with jitter and limit overlapping campaigns on one device. Warmth checks warn when a newly linked number is not ready for bulk. Nothing can guarantee WhatsApp will never restrict a number — follow their rules and warm up new devices.

Dashboard APIs use JWT Bearer tokens from POST /api/auth/login (captcha required). Server integrations use API keys with the X-API-Key header on /api/external only. Full reference: /docs and Swagger at /api-docs.

Yes. There is a global HTTP rate limiter plus plan-level monthly API request quotas and daily WhatsApp message caps. Usage meters in the dashboard show consumption. 429 means slow down; 403 LIMIT_EXCEEDED means raise the plan or buy an add-on.

Yes. Register HTTPS URLs for message_received, message_sent, message_delivered, message_read, message_failed, and campaign_progress. Each delivery includes X-Webhook-Signature = HMAC-SHA256(raw body, secret). Retries, test sends, and delivery history are in the dashboard and /docs/webhooks.

Start at /docs (full user guide), then each API chapter (sessions, messages, inbox, campaigns, contacts, number check, webhooks, API keys, external, realtime, team, billing, support). Interactive OpenAPI lives on the API host at /api-docs.

Keys are scoped: messages:send, messages:read, sessions:read, contacts:read, numbers:check. They only work on /api/external. They cannot manage billing, team, inbox assignment, or webhooks. The secret is shown once at create or regenerate.

Read the raw POST body as bytes. Compute HMAC-SHA256 with the webhook secret, hex digest. Compare to X-Webhook-Signature using a constant-time equals. Return 2xx quickly. See /docs/webhooks for the payload shape and a test-send endpoint.

Connect to the API host with socket.io-client and handshake.auth.token = your JWT. The socket joins your tenant and user rooms. Emit subscribe:session with a session UUID to receive qr_generated, session status, and per-session messages. Use webhooks for backend automation; use sockets for live UI. Guide: /docs/realtime.

Include the country code, 8–15 digits. Examples: 919876543210 or +919876543210. Do not send a local number without the country code. The JSON field on send endpoints is phone (not to).

Create a campaign with a session (accountId), a message or uploaded media, and an audience (recipients[] phones, groupId, or groupIds[]). Start now or schedule. ActiWAPI paces recipients, shows device warmth, and tracks sent/failed/delivered. Pause, stop, or retry from the dashboard or Campaigns API.

Yes. Import an .xlsx file from Contacts. Map phone and name columns (format Phone as Text), deduplicate, optionally check WhatsApp registration, and add people to groups for campaigns. Export is available as CSV as well.

Each plan defines daily message limits and campaign counts. Business and Enterprise plans offer the highest throughput. Free after trial is intentionally small. Check Billing usage before a large send.

Device warmth shows whether a newly linked WhatsApp session is ready for bulk campaigns. After pairing, ActiWAPI recommends a short warm-up and light outbound/inbound activity before large campaigns — reducing ban risk on fresh linked devices.

Yes. Recipient warmth (prior chat history) is guidance in the dashboard and contacts list. New numbers can still receive campaigns. Use pacing, number verification, and smaller warm-up batches for safer cold outreach.

Yes. When you create or import contacts with a connected session, ActiWAPI can store WhatsApp registration status. Filter and bulk re-check anytime from Contacts or the Number Check API.

Create groups from Contacts, add members in bulk, and select one or more groups as the campaign audience (groupId / groupIds). Groups are also available when filtering and exporting contacts. REST: /api/contact-groups.

Select a connected session and submit one number or a bulk list (up to 500). ActiWAPI checks whether each number is registered on WhatsApp. Results appear in the dashboard and via POST /api/v1/number-check and /bulk (JWT) or the External API (API key with numbers:check).

Yes. JWT: POST /api/v1/number-check and /bulk. API key: POST /api/external/number-check and /bulk. Pass a connected sessionId and phones with country codes.

Yes. The unified inbox aggregates conversations across connected numbers. Reply, assign a teammate, resolve threads, and load history. Live updates use Socket.io. REST: /api/chats documented at /docs/inbox.

Upload with POST /api/chats/upload, then POST /api/chats/{threadId}/send with mediaUrl, messageType (image, document, audio, video), and optional fileName / mimetype. Text-only replies only need the text field.

Owner (created at signup, full access), admin (team and settings), and member (messaging, inbox, campaigns per RBAC). Seat limits follow the plan and team-seat add-ons. Invite from the dashboard or POST /api/team/invite.

Yes. Every database query, API call, WhatsApp session, webhook, and API key is scoped to your organization. Keys cannot access another tenant.

Yes. Purchase the White Label add-on to remove ActiWAPI branding and apply your logo and colors on customer-facing surfaces. Pricing is on the pricing page.

Admins invite by email. The recipient opens the link, sets a password (POST /api/team/invite/accept), and is logged in. Pending invites can be revoked; accepted members can be removed with DELETE /api/team/members/{id}. Existing accounts cannot be invited to a second workspace with the same email.

Email support@actiwapi.com, open an in-app ticket (dashboard → support, or POST /api/support/tickets), or use the website contact form. Business and Enterprise plans include faster response targets.

We target 99.9% uptime for the REST API and dashboard. Enterprise customers can negotiate custom SLAs with sales. Public status is on /status.

Session disconnects, trial conversion to Free, campaign events, inbox assignments, and similar workspace events. List them with GET /api/notifications; they also arrive over Socket.io as notification_new.