Technical reference

Quickstart: API key, QR session, first request

Page updated: 2026-04-03

Summary

End-to-end path: workspace → API key → QR-linked device → authenticated HTTP call. Free tier does not include API keys; developer access starts at Starter ($29/mo).

Canonical reference: Hostnames, path prefixes, JSON field names, and changelog are maintained on docs.waping.app. Examples below are illustrative — align your integration with the live OpenAPI/reference there.

Connection model: WAPing links WhatsApp through a QR session (similar in concept to WhatsApp Web). This is not Meta’s WhatsApp Business Cloud API product, and you do not complete Meta BSP / Cloud API onboarding inside WAPing for this path.

Key definitions

Term	Definition
Workspace	Your tenant in WAPing: API keys, linked devices, and billing attach here. Not the same as a Meta Business Portfolio.
API key	Secret used as `Authorization: Bearer` on HTTP calls. Created in the dashboard on tiers that include developer access—not available on Free.
deviceId	Identifier for one QR-linked WhatsApp session. Outbound sends target a device; session health affects delivery.
Idempotency-Key	Client header so safe retries do not create duplicate logical sends when you reuse the same key + body.

Purpose

Validate that your environment, credentials, and linked WhatsApp session are healthy before building automation.

Best for

Teams on Starter or higher proving an HTTP integration before production traffic.
Operators who can scan QR on the handset when pairing or reconnecting a device.

Not for

Free-tier accounts that require REST API keys (not included on Free—see pricing table below).
Programs that mandate Meta Cloud API template governance as the only acceptable path—WAPing’s model is QR-linked, not BSP-hosted Cloud API.

Prerequisites

WAPing account at app.waping.app.
Paid tier with API access (Starter ($29/mo) or higher). Free tier has no API keys.
Physical access to the phone running WhatsApp to scan the QR in the dashboard.

Workflow

1) Create an API key

In the dashboard, open the developer/API keys area (exact menu labels may change). Create a key and store it in a secret manager. Never ship keys in browser bundles or mobile apps.

2) Link a device (QR)

In device management, add a device and scan the QR with WhatsApp on the phone. Until the session is linked and healthy, outbound calls that require an active session will fail with session-related errors (see Errors, QR session lifecycle).

3) Call the API

Use Authorization: Bearer and a unique Idempotency-Key for each logical outbound send (see Send a message).

Request example

Illustrative — confirm path and body on docs.waping.app

POST /v1/messages HTTP/1.1
Host: api.waping.app
Authorization: Bearer {WAPING_API_KEY{'}'}
Content-Type: application/json
Idempotency-Key: 7a2f1c9e-4b0d-4d1a-9f2e-3c6b8c1d0e2f

{
  "deviceId": "dev_123",
  "to": "+15551234567",
  "type": "text",
  "text": { "body": "Hello from WAPing" }
}

Response example

200 OK (shape may vary)

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "msg_abc123",
  "status": "queued",
  "deviceId": "dev_123",
  "to": "+15551234567"
}

Errors

401 / 403: missing or invalid key, or plan without API entitlement — see Authentication.
409 / 429: idempotency conflict or throttling — see Errors, Rate limits.
4xx with session code: QR session disconnected — see QR session lifecycle.

Plan quotas vs HTTP throttling

Monthly outbound quotas (below) are plan entitlements shown on Pricing. HTTP 429 throttling is separate: short-term request pacing to protect infrastructure and linked WhatsApp accounts—see Rate limits.

Plan	WhatsApp devices (linked)	Outbound messages / month	REST API & webhooks
Free	1	500	Not included
Starter	1	3,000	Included
Growth	5	30,000	Included
Pro	15	300,000	Included
Enterprise	50	1,000,000	Included

Source: published plan cards (reviewed 2026-04-03). Retention, storage, and team seats have additional caps—see full feature lists on /pricing.

Caveats

WAPing does not expose Meta’s Cloud API template approval or BSP onboarding — your integration is against WAPing’s HTTP API and the linked WhatsApp client capabilities.
Do not use Meta’s “phone number ID” / Cloud API concepts interchangeably with WAPing’s deviceId — map fields using the canonical reference.