01 · Definition
What is a WhatsApp API permission?
API permissions are the named scopes that decide what a Meta app's access token may do through the Graph API. For WhatsApp, three matter most. whatsapp_business_messaging lets an app send messages and receive inbound-message and status webhooks on a granted phone number. whatsapp_business_management lets it read and manage the WhatsApp Business Account (WABA): message templates, phone numbers, analytics and account-change webhooks. business_management reaches the business portfolio above the WABA and is needed only for programmatic portfolio work. Meta also lists narrower ones, such as whatsapp_business_manage_events for the Marketing Messages API used with the Conversions API.
A permission alone is not enough: it must also cover the right asset. When a business grants an app access — while generating a system user token, or on the Embedded Signup authorisation screen — it chooses which WABAs the app may touch. These granular scopes appear in the debug_token response as granular_scopes, each pairing a scope with target_ids. A token can hold whatsapp_business_messaging and still fail on a WABA that is not in its target list.
Permissions also have access levels. Business-type apps get Standard Access automatically, which covers assets owned by the app's own business and people with roles on the app — enough for a direct developer sending for its own brand. To act on WABAs owned by other businesses, as Tech Providers and Solution Partners do, the app needs Advanced Access for each permission, granted through Meta App Review. Permissions are what an app may do; App Review is how it earns the right to do it for others.
Key takeaways
- API permissions are the scopes a Meta app holds; a token can only do what they allow, and only on the assets it was granted.
whatsapp_business_messagingsends messages and receives message webhooks;whatsapp_business_managementcovers templates, numbers, analytics and WABA settings.business_managementis only for working with the business portfolio itself, and Meta says it is rarely needed.- Granular scopes tie each permission to specific WABA IDs, listed as
target_idsin a debug_token response. - Acting on other businesses' WABAs needs Advanced Access through App Review; without it, calls fail with error 200.
02 · Specifications
A WhatsApp API permission: key facts and limits
| Send and receive messages | whatsapp_business_messaging |
|---|---|
| Templates, numbers, analytics | whatsapp_business_management |
| Business portfolio | business_management (rarely needed) |
| Marketing Messages API + Conversions API | whatsapp_business_manage_events |
| Standard Access | Automatic for Business apps: own assets and app roles |
| Advanced Access | Through App Review; needed for other businesses' WABAs |
| Missing permission | Error 10 or 200–299 |
| Check grants | debug_token: scopes and granular_scopes |
03 · Code samples
A WhatsApp API permission in code
# Which permissions does this token hold, and on which WABAs?curl -G "https://graph.facebook.com/v26.0/debug_token" \--data-urlencode "input_token={ACCESS_TOKEN}" \--data-urlencode "access_token={APP_ID}|{APP_SECRET}"
Read scopes for the permissions and granular_scopes[].target_ids for the WABAs.
04Playground
A working model of API Permissions. Use its controls to replay it step by step.
Which permission does each task need?
| whatsapp_business_messaging | whatsapp_business_management | business_management | |
|---|---|---|---|
| Send a message | |||
| Receive message webhooks | |||
| Create or edit templates | |||
| List a WABA's phone numbers | |||
| Read analytics | |||
| Manage the business portfolio |
Hover, tap or arrow-key through the cells — a dot in the corner means there is a note.
Manage the business portfolio by whatsapp_business_management
Not enoughInsufficient
WABA-level access does not reach the portfolio above it.
Legend — press one to highlight its cells
Row 6 of 6. Manage the business portfolio × whatsapp_business_management: Not enough. WABA-level access does not reach the portfolio above it.
05 · Operation
How does a WhatsApp API permission work?
Map features to permissions
Sending and receiving messages need
whatsapp_business_messaging. Templates, numbers, analytics and WABA webhooks needwhatsapp_business_management. Portfolio work needsbusiness_management.Grant them to the identity
Direct developers pick permissions when generating a system user token. Partners list them in the Facebook Login for Business configuration that Embedded Signup uses.
Grant the assets
Assign the WABA to the system user, or let the customer choose their WABA during Embedded Signup. A token's reach is the overlap of its permissions and its assets.
Get Advanced Access if you serve others
Submit each permission for App Review with a use-case description and a screen recording. Until it is approved, customers cannot grant that permission through Embedded Signup.
Verify before you rely on it
Run
debug_tokenon the token and comparescopesandgranular_scopes[].target_idswith the WABA and phone number you are about to call.
06 · Rationale
Why does a WhatsApp API permission matter?
Wrong permissions fail in confusing, partial ways: sends work while template sync returns error 200, or one customer's WABA works while another's does not. Asking for too much is also costly — Meta names unnecessary permissions as a common reason App Review rejects a submission, and broad scopes widen the damage a leaked token can do. Mapping each feature to the minimum permission keeps integrations working and reviews short.
07 · Cautions
Common mistakes with a WhatsApp API permission
Requesting every permission
Unnecessary permissions are a common App Review rejection reason and enlarge the blast radius of a leak. Request only what a shipped feature calls.
Forgetting the asset half
A system user with the right permissions but no WABA assignment still gets permission errors. Assign the WABA, with the tasks it needs, before relying on the token.
Testing only on your own WABA
Standard Access works on your own business's assets, so everything passes in testing. Customers' WABAs then fail with error 200 until Advanced Access is approved, so plan App Review before launch.
Assuming management includes messaging
The two WhatsApp permissions are independent. A token with only
whatsapp_business_managementcan create a template but cannot send it.Reading scopes without target IDs
scopessays what a token may do;granular_scopes[].target_idssays where. Check the WABA ID you are about to call.
08 · Worked example: Splitting permissions at a Hyderabad SaaS
Example: Splitting permissions at a Hyderabad SaaS
A Hyderabad appointment-booking SaaS runs two backend services: a sender that dispatches reminders and a template service that syncs and submits templates. Instead of one token with everything, it uses two system users. The sender's token carries only whatsapp_business_messaging; the template service's carries only whatsapp_business_management. When the sender token turned up in a log file attached to a support ticket, the team revoked it knowing the worst case was message sending, not template edits or account changes, and the template service kept running untouched.
09 · Questions and answers
API Permissions FAQs
- Which permissions do I need to send WhatsApp messages through the Cloud API?
- whatsapp_business_messaging, on the WABA that owns the sending phone number. Add whatsapp_business_management if your app also manages templates, phone numbers or analytics.
- Do I need the business_management permission for WhatsApp?
- Usually not. Meta describes it as needed only to access the business portfolio programmatically, and says it is rarely needed because the same tasks can be done in Meta Business Suite.
- Why do I get error 200 when my token has whatsapp_business_management?
- The token probably lacks that specific WABA, or your app lacks Advanced Access for WABAs your business does not own. Check granular_scopes target IDs first, then the permission's access level in the App Dashboard.
- What is the difference between Standard Access and Advanced Access?
- Standard Access, automatic for Business apps, covers your own business's assets and users with a role on the app. Advanced Access, granted through App Review, lets the app use a permission on the assets of businesses it onboards.
10 · Recommended practice
Best practices for a WhatsApp API permission
- Keep a table in your repository mapping each endpoint you call to the permission it needs.
- Give services with different jobs separate system users or tokens, each with the minimum permissions.
- Re-check
granular_scopesafter a customer edits their connected-app settings; a removed WABA shows up there first.