Copy your API key from the Console, create a session, scan the QR, send this curl. wpp-engine is a thin REST API over a managed WhatsApp engine — no SDK required.
base url https://wpp-api.oneclient.tech
current version v1
auth Bearer wae_live_…
openapi /v1/docs
region br-sa-east-1
→
API pública V2 (ADR-005) em desenvolvimento. Esta página documenta o motor /v1 real. Conta: /signup com aprovação. O contrato de cobrança automática chega no ADR-005.
This page is the shortest path from zero to sending on the live engine. Every curl on the right is copy-paste-ready against https://wpp-api.oneclient.tech. Full reference: Swagger UI at https://wpp-api.oneclient.tech/v1/docs.
Authentication
Every request must include Authorization: Bearer wae_live_…. Keys are scoped per tenant. Get yours from Console → API Keys — shown once at first login; after that only prefix + last 4 digits.
→
Keys are shown once at creation. We store only a hash and last4. If you lose a key, contact support — we cannot recover plaintext. This is by design.
GET/v1/sessionssmoke auth — empty list is OK
Create session & QR
Create a WhatsApp session with POST /v1/sessions and the E.164 phone of the line you will connect. The response includes session_id and an initial qr_code (data URL). Poll GET /v1/sessions/:id/qr every few seconds until status becomes connected after scanning.
POST/v1/sessionsbody: phone, display_name
GET/v1/sessions/:id/qrrefresh QR if expired
Send a message
Once the session is connected, send with POST /v1/sessions/:id/messages. Pass to (E.164) and content with type: text for the first message.
POST/v1/sessions/:id/messagessession must be connected
Body parameters
field
type
description
to required
string
Destination phone in E.164 — start with +, no spaces. With + the engine keeps the full country code (no auto +55). Examples: +5511987654321, +15617650750.
content required
object
Discriminated by type. For text:
textimageaudiovideodocument
content.text required
string
When content.type = text. Up to 4096 chars.
idempotency_key
string
Optional dedupe key (8–120 chars).
Response
Returns data.id (UUID), data.status, and external_message_id. Delivery updates arrive via webhook (message.delivered, etc.).
→
Áudio / TTS: upload POST /v1/media/upload (MP3 ok) → send with content.type = "audio" and media_id. Delivers as WhatsApp voice note (PTT). The engine converts non-OGG to OGG/Opus so mobile can download. Inbound voice notes expose media_id on message.received — renew URL via GET /v1/media/{id}.
Configure webhook
Register your HTTPS endpoint with PATCH /v1/tenants/me and a webhook_secret you choose (min 8 chars). Omit webhook_secret to let the engine generate one — store it immediately; only a prefix is returned.
PATCH/v1/tenants/mebody: webhook_url
Receive via webhook
The engine POSTs JSON to your webhook_url for events like message.received and session.connected. Always verify HMAC before trusting the body.
Event types (v1)
message.received
Incoming WhatsApp message persisted for the session.
message.sent
Outbound message accepted by the carrier pipeline.
message.delivered
Outbound message delivered to the device.
message.read
Outbound message read (blue checks).
message.failed
Outbound delivery failed — see data payload.
session.connected
QR scanned; session is live.
session.disconnected
Connection lost.
HMAC verification
Every webhook delivery includes:
X-WPP-Engine-Signature — HMAC-SHA256 hex of the raw body
X-WPP-Engine-Event-Id — same as payload.id (e.g. evt_…)
X-WPP-Engine-Timestamp — ISO8601, same as payload.timestamp
⚠
Verify before parse. Recompute HMAC on raw bytes with your webhook_secret, compare with timingSafeEqual, then JSON.parse.
Errors
Errors return { data: null, error: { code, message } } with a meaningful HTTP status.
status
code
what
401
INVALID_API_KEY
Missing or invalid Bearer token. Copy a fresh key from the Console.
