Integration Guide
Connect a WhatsApp number to WaCentra Connect API once, then let your own systems send messages through a simple REST API and receive events when things happen. This guide shows how to wire your system up to ours.
Overview#
The integration has four parts:
- Token — generate an API token in a link’s Webhook tab and send it with each request.
- Link — one WhatsApp number per link.
- Pairing — scan a QR code with WhatsApp once; the number stays linked.
- Messages & events — send text through the API and subscribe to event notifications.
| Base URL | https://wacentraconnectapi.com/api/v1 |
|---|---|
| Format | JSON request and response bodies (Content-Type: application/json). |
| Auth | Authorization: Bearer <token> |
| Credentials | Copy your link values into your environment — see environment variables. |
| OpenAPI | openapi.json — import into Postman, Insomnia or a client generator. |
Authentication#
Create a link API key on the Webhook tab of a link (API access), then send it on every request:
Authorization: Bearer YOUR_API_KEY
Generating a key
- Open Links in your dashboard and choose a link.
- Go to its Webhook tab and find the API access section.
- Enter the domain the key will be used from and the IP addresses or CIDR ranges it may be used from (required). Use domain's addresses fills the list from the domain's DNS records; review it before saving.
- Press Generate key and copy it immediately — it is shown only once.
Hardening a key
-
HTTPS only. The API refuses plain HTTP requests with
426 Upgrade Required. The key travels in theAuthorizationheader, so always call thehttps://address. - Expiry. Keys expire after the number of days set by the operator (shown on the API access panel as Expires). Regenerate the key before it expires, or turn expiry off only when you accept a key that never expires.
-
Browser origin. A browser always sends an
Originheader. When one is present it must match the key's domain, so a key embedded in a page on another site is refused. Server-side calls normally send no Origin header. This is a guard against mistakes, not a security boundary, because any caller can send any header. Keep keys out of browser code. - New address alert. For a key without an IP allowlist, the account owner is emailed the first time the key is used from an address it has not used before. Add IP ranges to block other addresses instead of relying on the alert.
Apps can also authenticate end users directly. POST https://wacentraconnectapi.com/api/v1/register or
POST https://wacentraconnectapi.com/api/v1/login emails a one-time code and returns a short-lived
challenge; send both to POST https://wacentraconnectapi.com/api/v1/otp/verify
to receive a Bearer token. Password reset uses POST https://wacentraconnectapi.com/api/v1/password/forgot
(which also returns a challenge) then POST https://wacentraconnectapi.com/api/v1/password/reset. See the
authentication endpoints for full details.
Quick start#
- Create a link API key (locked to your domain) on the Webhook tab of a link (API access) and store it securely.
-
Create a link with
POST https://wacentraconnectapi.com/api/v1/sessions(links). Send adevice_nameandplatform; the response returns the linkuuidused in every URL below. - Pair the device in the dashboard: open the link, go to the Connection tab and scan the QR code. The API never returns the pairing QR, so a leaked token cannot bind a phone to your link.
-
Wait until connected by polling
GET https://wacentraconnectapi.com/api/v1/sessions/{uuid}/whatsappuntilstatusisopen. -
Send a message with
POST https://wacentraconnectapi.com/api/v1/sessions/{uuid}/whatsapp/messages(messages), then track delivery through events.
WordPress & WooCommerce#
If you run WordPress or WooCommerce, use the official plugins instead of building a client from scratch. The authentication add-on handles WhatsApp OTP login and two-factor, and the WooCommerce add-on handles order updates. Both reuse the credentials and webhook setup from this guide.
| WordPress | Add WhatsApp OTP passwordless login, role-based two-factor authentication and phone capture to WordPress. WordPress authentication guide. |
|---|---|
| WooCommerce | Send transactional order status updates, capture checkout consent and attach generated invoice PDFs. WooCommerce setup guide. |
Errors & rate limits#
Every response carries a standard HTTP status. Treat 422 as a field map you can show next to inputs. Treat the others as a single notice with a clear next step.
It landed
The call succeeded. New resources, such as a sent message, return 201.
Queued to send
Accepted, but waiting because the send rate was reached. Poll the message until status is sent.
Done, no body
The action succeeded and there is nothing to return. Do not parse a JSON body.
Sign in first
The token is missing, expired, or not a Bearer key we recognise.
Send Authorization: Bearer YOUR_API_KEY and generate a new key if this one was revoked.
{
"message": "Unauthenticated."
}
Package needs renewing
The trial or paid period has ended, so sends are paused until the package is renewed.
Renew from Packages, then retry the send. The message is not stored while this notice is returned.
{
"message": "Your package has ended. Renew to continue sending messages."
}
This key cannot do that
The account is suspended, the key is not bound to this link, or the request came from an address outside the allowlist.
Use the key created for this link, from an allowed IP. Suspended accounts must appeal before the API will answer.
{
"message": "This API key is not allowed from this address."
}
Nothing here for this key
The resource does not exist, or it belongs to another account. We return 404 in both cases so one tenant cannot probe another.
Check the link ID and that the path matches a resource this key can see.
Link is not connected
The action needs a live WhatsApp session. Pairing is unfinished, the phone logged out, or the link is paused.
Open the link in the dashboard, scan the QR if asked, and wait until status is connected before sending.
{
"message": "Connect the WhatsApp session before sending messages."
}
Fix the fields, then resend
Validation failed. The errors object is keyed by field so you can place each message next to the matching input. This also covers a session that has used its period message allowance.
Read errors.<field>[0] and show that string. Do not retry the same body unchanged.
{
"message": "The given data was invalid.",
"errors": {
"to": ["Enter a valid phone number, or a group JID ending in @g.us."]
}
}
Slow down, then retry
Too many requests in the current window. Authentication endpoints are tighter than the rest of the API.
Wait for Retry-After seconds. Do not tight-loop.
{
"message": "Too Many Attempts."
}
WhatsApp engine is unreachable
The WaCentra Connect API WhatsApp engine did not answer, or it returned an error. Your request did not complete on WhatsApp.
Retry with backoff. If it continues, check the Developer logs and try again after a short wait.
{
"message": "The WhatsApp engine is temporarily unavailable."
}
Rate-limited responses also send these headers, so a client can pace itself without guessing.
- X-RateLimit-Limit
- Requests allowed in the current window.
- X-RateLimit-Remaining
- Requests left in the current window.
- Retry-After
- Seconds to wait after a
429.
Sandbox mode#
Test safely before going live: sandbox links deliver real messages to your test numbers only, outside your quota, up to 10 per 24 hours. Read the full Sandbox guide.
Request logs#
Every API call is recorded with its method, path, response status and server-side latency, keyed to the API key that made it. Open the Developer page for a 24-hour overview and per-key health, or All request logs to filter by key, status family, path and time window. Logs are retained for 3 days.
© 2026 WaCentra Connect API. All rights reserved.