Context
Dualhook operates as an official Meta Tech Partner onboarding layer for WhatsApp Cloud API features. WhatsApp Business API permissions in this context mean the customer has granted the required Meta access so Dualhook can configure and operate those features on their behalf.
There are two layers of access that both have to be in place:
- Graph API permissions — the OAuth scopes the access token carries (e.g.
whatsapp_business_messaging). - Business asset task scopes — what the system user behind that token is allowed to do on the specific WABA (e.g.
MANAGE_TEMPLATES).
A token with the right OAuth scopes will still fail with error 200 if the underlying system user has not been granted the required business asset access on the WABA being queried.
What Permissions Enable
With proper permissions, Dualhook can:
- Configure webhook subscription and override
- Sync and manage templates
- Read health and account signals
- Perform phone-number-level operations needed for setup
Graph API Permissions (OAuth Scopes)
Dualhook requests these Graph API permissions during Embedded Signup:
| Permission | Why Dualhook needs it |
|---|---|
whatsapp_business_management | Account metadata, template management, phone-number listing, analytics, account-level webhook subscriptions |
whatsapp_business_messaging | Send messages and receive incoming-message + status webhooks |
business_management is not requested by default. It is only relevant if Dualhook needs to programmatically read or modify your Meta Business Portfolio directly, which is not part of the standard onboarding flow.
The token Dualhook stores after Embedded Signup is a Business Integration System User access token, scoped to the customer that completed onboarding. It is encrypted server-side and never exposed through the dashboard or API. A per-connection dh_live_... key authorizes the allowlisted Runtime API for messages, media, templates, health/status, profiles, safe phone settings, and QR codes. If Meta reports an expiry for an existing token, reauthorization is required; Dualhook does not apply the ordinary System User refresh flow to BISU tokens.
Business Asset Task Scopes
In addition to OAuth permissions, the system user behind the token must hold task-level access on the specific WABA. In Dualhook-managed onboarding, required task scopes typically include:
| Scope | Purpose |
|---|---|
MANAGE | General WABA management |
DEVELOP | Development and testing access |
MANAGE_PHONE | Phone number configuration |
MANAGE_PHONE_ASSETS | Phone number asset operations |
MANAGE_TEMPLATES | Template CRUD operations |
MESSAGING | Send and receive messages |
Checking Access
You can confirm access in three places:
In Dualhook
- Connection is active
- Sync and health checks succeed
- Template operations are allowed
- The connection's Health tab lists the granted OAuth scopes under its "Permissions & token" check
Via Dualhook diagnostics
The connection Health tab reports the granted OAuth scopes and WABA target IDs. Dualhook obtains these through Meta's server-side token debugger during Embedded Signup without revealing either the BISU token or the app credential.
In Meta Business Settings
- The correct app or system user is assigned to the target WABA
- Required task scopes are present
Navigate to Meta Business Settings > Accounts > WhatsApp Accounts > select your WABA > Assigned People/Apps to verify.
If Access Is Missing
Symptoms usually include:
- Subscription or override setup fails
- Template sync, create, or update fails
- Health checks return authorization errors (code
10or200— see API Error Reference)
Resolution
- Re-run the delegated onboarding/authorization flow (Embedded Signup).
- Ensure the correct Business Portfolio and WABA are selected.
- Confirm required task scopes are granted before retrying operations.
- If using a system user, verify it has the correct role and asset assignments.
For onboarding details, see Embedded Signup. For troubleshooting connection issues, see Troubleshooting.