Authentication & channels

Authentication & channels

Every WhatsApp API call authenticates with an app key (vai_app_…) carrying the right scope, and targets a channel (a connected WhatsApp number). This page shows how to get a key, which scopes each call needs, and how to look up your channelId.

Get an app key

In the dashboard, install or open your app and create a key (owner/admin only). The secret is shown once — it looks like vai_app_xxxxxxxxxxxxxxxx. Copy it and store it somewhere safe; you can't retrieve it again, only rotate it.

The key must hold the scope each call requires (see below). Scopes are declared in the app manifest and consented at install time.

Send the key

Put the key in the Authorization header as a bearer token on every request:

Authorization: Bearer vai_app_xxxxxxxxxxxxxxxx

The X-App-Key header is also accepted if you prefer:

X-App-Key: vai_app_xxxxxxxxxxxxxxxx

Call these endpoints from your server, never the browser — an app key is a full credential.

Scopes

Each WhatsApp route requires one of three scopes. A missing scope returns 403. See App scopes for the full model.

Which scope a given call needs is noted on each reference page — e.g. Send and Media need whatsapp; Manage templates needs whatsapp:templates; Broadcasts needs whatsapp:campaign.

Find your channelId

Every send targets a channel — one of your connected WhatsApp numbers. List them and read the id:

curl https://api.telenow.ai/api/app-whatsapp/channels \
  -H "Authorization: Bearer vai_app_…"

{
  "success": true,
  "data": {
    "channels": [
      { "id": "b1e2c3d4-…", "label": "Acme Support", "phone": "+14155550100" }
    ]
  }
}

Use that id as the channelId in every send, and in the /channels/{id}/… path segments throughout these docs.

GET /channels requires the whatsapp scope. If it returns an empty list, connect a number first — see the WhatsApp guide. Only native Meta Cloud channels appear here.

Dashboard JWT alternative

The same operations are available under /api/orgs/{orgId} using a user JWT instead of an app key — useful when you're building your own dashboard UI rather than a standalone integration. Send Authorization: Bearer <jwt> plus X-Org-Id: {orgId}; routes live under /api/orgs/{orgId}/whatsapp-hub/* (send & inbox), /whatsapp-cloud/* (onboarding, templates, health) and /whatsapp-campaigns/* (broadcasts). See Authentication for how JWTs and org ids work — see Onboarding API for the connect/registration endpoints.

Related

• WhatsApp overview — the two surfaces, the envelope, message-type index.
• App scopes — the full scope model.
• Authentication — JWTs, API keys and key roles.
• Text messages — your first send.