Authenticate to the AvenPing API ​

Get an API token from Settings → API Settings, send it as Bearer or X-API-Token, and use Premium or Enterprise with an active plan. Call GET /v2/me to list valid phoneNumberId values.

This page explains what you need before calling the API and how to authenticate. Endpoint detail is organized by topic: start at HTTP API v2 Overview, then use the sidebar or Developer API capability map.

Prerequisites ​

  • An AvenPing workspace on Premium or Enterprise with an active (not expired) plan
  • A WhatsApp Business account linked in AvenPing (valid Meta access token)
  • Access to the app at app.avenping.com

Step-by-step ​

  1. Sign in to AvenPing
    Open app.avenping.com and sign in to the workspace that owns the WhatsApp line.

  2. Open API Settings
    Go to Settings → API Settings.

  3. Copy your API access token
    Generate or copy the token. Treat it like a password: store it in secrets management, never commit it, and never expose it in browser-side code. Regenerating the token invalidates the previous value immediately.

  4. Confirm the API is reachable
    Call GET https://api.avenping.com/v2/health with no token. You should receive { "success": true, "data": { "ok": true } }.

  5. List valid phoneNumberId values
    Call GET https://api.avenping.com/v2/me with Authorization: Bearer YOUR_TOKEN (or X-API-Token). Copy a phoneNumberId from phoneNumbers, or use defaultPhoneNumberId when it is set.

  6. Make an authenticated request
    For example, GET /v2/templates with the same token. Missing or invalid tokens return 401 UNAUTHORIZED. A non-Premium/Enterprise plan returns 403 DEVELOPER_PLAN_REQUIRED.

Base URL and version ​

EnvironmentBase URL
Productionhttps://api.avenping.com

All documented REST routes use the /v2 prefix (for example GET https://api.avenping.com/v2/health).

Send the token on every protected request ​

You can use either form (same token value):

http
Authorization: Bearer YOUR_TOKEN_HERE
http
X-API-Token: YOUR_TOKEN_HERE

Missing or invalid tokens receive 401 with error code UNAUTHORIZED.

Token revocation

Regenerating the token in the dashboard invalidates the previous token immediately.

Subscription and plan rules ​

After the token is validated, the API enforces:

  1. Active plan — your primary subscription must not be expired (403 PLAN_EXPIRED if it is).
  2. Premium or Enterprise — API access is limited to these plans (403 DEVELOPER_PLAN_REQUIRED otherwise).
  3. Linked WhatsApp Business account — your user must have a WhatsApp account with a valid Meta access token in AvenPing (404 NOT_FOUND if the account is missing).

The only v2 routes that work without a token are GET /v2/health and GET /v2/version.

Phone number ID (phoneNumberId) ​

For messages, template send, and media upload, you must send phoneNumberId: the Meta Phone number ID for the WhatsApp number you use with AvenPing. That ID must belong to a line linked to your token (403 FORBIDDEN if it does not). Call GET /v2/me to list valid IDs (including every linked WABA). Upload accepts the id as a multipart field or X-Phone-Number-Id header.

Success and error format ​

Successful JSON responses typically look like:

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

Errors:

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

See the reference overview — Error response shape for all application error codes.

First request (health check) ​

No authentication:

bash
curl -s https://api.avenping.com/v2/health

Example response:

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

Discover phone number IDs (GET /v2/me) ​

Replace YOUR_TOKEN:

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

Use each object’s phoneNumberId (Meta) in message, template send, and media upload requests. If defaultPhoneNumberId is set, use that as the usual sender id (single line, or the workspace primary line).

First authenticated request (example) ​

List templates (requires Premium/Enterprise and linked WhatsApp account):

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

FAQ ​

Can I send the token as either Bearer or X-API-Token?

Yes. Use Authorization: Bearer <token> or X-API-Token: <token> with the same value from Settings → API Settings. Missing or invalid tokens return 401 UNAUTHORIZED. Regenerating the token in the dashboard invalidates the previous token immediately.

Why do I get 403 DEVELOPER_PLAN_REQUIRED?

API access is limited to Premium or Enterprise with an active (not expired) plan. Other plans receive 403 DEVELOPER_PLAN_REQUIRED. An expired primary plan returns 403 PLAN_EXPIRED.

Why do I get 404 WhatsApp account not found?

The token is valid, but the user has no linked WhatsApp account with a Meta access token in AvenPing. Link a WABA in the app, then call GET /v2/me again.

When do I need phoneNumberId?

JSON body phoneNumberId is required on all /v2/messages/* routes, POST /v2/templates/send, POST /v2/templates/:name/test-send, and POST /v2/media/upload. If it is missing you get 400 VALIDATION_ERROR. If it is not linked to your token you get 403 FORBIDDEN.