AvenPing HTTP API v2 reference ​

This is the main API reference hub for AvenPing v2: authentication, plan rules, phoneNumberId ownership, and JSON error codes. Endpoint details live on focused pages linked below.

Endpoint details are split into focused pages so the table of contents stays usable.

Prerequisites ​

  • An API token from Settings → API Settings (Authentication)
  • Premium or Enterprise with an active plan
  • A linked WhatsApp Business account (except for public health/version routes)

Step-by-step ​

  1. Send the auth header
    Use Authorization: Bearer YOUR_TOKEN or X-API-Token: YOUR_TOKEN on every protected request. Missing or invalid tokens return 401 UNAUTHORIZED.

  2. Pick a phoneNumberId from GET /v2/me
    Call GET /v2/me and copy a Meta phoneNumberId from phoneNumbers (or defaultPhoneNumberId when set). Ownership is checked against every linked WABA.

  3. Call the resource
    Use https://api.avenping.com plus the /v2/... path for the group you need. JSON bodies require Content-Type: application/json and are limited to 2 MB.

  4. Read success and error envelopes
    Success is { "success": true, "data": ... }. Zod schema failures return 400 VALIDATION_ERROR with details set to the issue list. A blocked contact returns 403 FORBIDDEN. Meta Graph 4xx (other than 401/403/404) is mapped to VALIDATION_ERROR with the Graph payload in details.

TopicPage
Root URL, health, version (no token)Public & meta
Current user, WABA id, phone number IDsAccount
Message templatesTemplates
Flows (Meta) + DB searchForms (flows)
Download media by Meta media idMedia
Send messages (text, media, interactive, smart /send)Messages
Outbound webhook URL (dashboard parity)Webhooks

For setup and your first calls, see Authentication & requirements. For Postman, see Postman collection.

Conventions ​

  • Replace https://api.avenping.com with your environment’s base URL if different.
  • Replace YOUR_TOKEN with your API token (Settings → API Settings).
  • data from WhatsApp Graph (messages, templates list, flows from Meta, etc.) is largely a pass-through of Meta’s Cloud API. Exact fields vary by API version and resource; examples on each page are illustrative.

Base path: all v2 routes are under /v2.
Content-Type: use application/json for request bodies (when applicable).
Body size limit: 2 MB per JSON body.

Authentication ​

Send the same secret you see in the AvenPing app under Settings → API Settings (API access token).

MethodHow
BearerHeader Authorization: Bearer <token>
HeaderX-API-Token: <token>

If the token is missing or invalid, the API responds with 401 and code UNAUTHORIZED.

Example (Bearer):

bash
curl -sS "https://api.avenping.com/v2/me" \
  -H "Authorization: Bearer YOUR_TOKEN"

More detail: Authentication & requirements.

Access rules (after auth) ​

Middleware order matters:

  1. requireAuthToken — valid user, linked WhatsApp account with Meta accessToken. If the user has no WhatsApp account configured, you may see 404 NOT_FOUND with message WhatsApp account not found.
  2. requireActivePlan — primary (non–add-on) plan must not be past its end date. Otherwise 403 PLAN_EXPIRED.
  3. requirePremiumOrEnterprise — primary plan name must be Premium or Enterprise. Otherwise 403 DEVELOPER_PLAN_REQUIRED.

These apply to every /v2/* route except the routes on Public & meta (GET /v2/health, GET /v2/version).

Phone number ownership ​

These routes require a JSON body field phoneNumberId (Meta Phone number ID). The server checks that this ID belongs to any WhatsApp account linked to your token (not only the default WABA on GET /v2/me):

  • All routes under /v2/messages/*
  • POST /v2/templates/send
  • POST /v2/templates/:name/test-send
  • POST /v2/media/upload (form field or X-Phone-Number-Id header)

Optional query phoneNumberId or accountId on list routes (GET /v2/templates, GET /v2/forms, media download) selects which linked WABA to use.

Use GET /v2/me to list valid phoneNumberId values for your token.

If phoneNumberId is missing: 400 VALIDATION_ERROR.
If it is not linked to your account: 403 FORBIDDEN (phoneNumberId does not belong to this account).

Success response shape ​

Most JSON endpoints return:

json
{
  "success": true,
  "data": {}
}

The data object (or array) is endpoint-specific. Message send and template send endpoints usually return Meta’s send-message response inside data (e.g. messaging_product, contacts, messages with id / WAMID). See Messages for a typical send payload.

Error response shape ​

Structured errors use:

json
{
  "success": false,
  "error": "ERROR_CODE",
  "message": "Human-readable message",
  "details": null
}

details is omitted when empty; some errors may attach structured details.

Example (401):

json
{
  "success": false,
  "error": "UNAUTHORIZED",
  "message": "Missing API token"
}

Error codes (application) ​

HTTPerrorTypical cause
401UNAUTHORIZEDMissing/invalid token, deleted user
403FORBIDDENphoneNumberId / accountId not owned, or contact is blocked on the line
403PLAN_EXPIREDSubscription ended
403DEVELOPER_PLAN_REQUIREDPlan is not Premium/Enterprise
400VALIDATION_ERRORBad input, missing required fields, Zod parse failure, or Meta 4xx
404NOT_FOUNDResource missing (template, media URL, unknown route)
500INTERNAL_ERRORUnexpected failure, upstream/Graph failure surfaced as generic error
502INTERNAL_ERRORMedia download proxy failed (message: Failed to download media)

Note: Zod schema failures return 400 VALIDATION_ERROR with details set to the issue list. Malformed JSON (not parsed into an object) still fails as 500 INTERNAL_ERROR from the body parser in some cases.

FAQ ​

Which routes skip authentication?

Only GET /v2/health and GET /v2/version (plus the non-versioned GET / landing). Every other /v2/* route needs a valid token, an active plan, and Premium or Enterprise.

When is phoneNumberId required?

JSON body phoneNumberId is required on all /v2/messages/*, POST /v2/templates/send, POST /v2/templates/:name/test-send, and POST /v2/media/upload. List routes accept optional phoneNumberId or accountId to pick a linked WABA. Missing id: 400 VALIDATION_ERROR. Not owned: 403 FORBIDDEN.

How are Zod and Graph errors returned?

Zod schema failures return 400 VALIDATION_ERROR with details set to the issue list. Malformed JSON (not parsed into an object) can still fail as 500 INTERNAL_ERROR from the body parser. Meta Graph 401/403/404 keep those statuses; other Graph 4xx map to VALIDATION_ERROR with the Graph payload in details.

What does 403 FORBIDDEN mean on a send?

Either phoneNumberId / accountId is not linked to your token, or the WhatsApp contact is blocked on that line (Contact is blocked on this WhatsApp line). Blocked sends do not call Meta.