Providers · Meta Cloud API

Connect a Meta Cloud API number

For numbers you manage in Meta Business / WhatsApp Manager. New here? Read Connect WhatsApp first for the shared essentials.

// 01

Prerequisites

RequirementNotes
A WhatsApp Business Account (WABA)With a phone number added under WhatsApp → API Setup.
Phone Number IDThe numeric id from API Setup (not the display number). This is the routing key.
Permanent access tokenFrom Business Settings → System Users, with scopes whatsapp_business_messaging + whatsapp_business_management. A temporary API-Setup token works but expires in 24h.
Admin access to SupportWizeRequires the Channel Manage permission.

// 02

Point the webhook & subscribe

In the Meta App Dashboard → WhatsApp → Configuration:

  1. Set the Callback URL to your Meta webhook URL (shown on Admin → Channels).
  2. Set the Verify token to the value shown on the Channels page. Meta calls the URL once with this token to verify it (the hub.challenge handshake).
  3. Under Webhook fields, click Manage and subscribe the messages field.
Most-missed step

Subscribing the messages field is the #1 reason for “the webhook is set but no messages arrive”. Verification passing is not the same as being subscribed.

// 03

Connect in SupportWize

Option A — One-click (if enabled)

On Admin → Channels with Meta selected, use Connect with Meta. Sign in with the business's Meta account and the number connects automatically — no tokens to copy.

Option B — Manual

  1. Go to Admin → Channels, choose Meta Cloud API.
  2. Enter the Phone Number ID, Business display number, and Permanent access token (WABA ID optional).
  3. Click Connect number — the verify token is applied for you.

Option C — API

POST /api/channels/whatsapp
{
  "provider": "META",
  "phoneNumberId": "123456789012345",
  "displayPhone": "+2348000000000",
  "accessToken": "<permanent-system-user-token>",
  "wabaId": "<optional-waba-id>"
}
Token tip

Prefer a System User token over the 24h API-Setup token — test-number tokens also get rejected by Meta's send API. If sends fail with “cannot parse access token”, swap it via Update token on the channel card.

Then verify end-to-end using Test & go live.