01 · Definition
What is the whatsapp_business_messaging permission?
The WhatsApp Business Messaging Permission, whatsapp_business_messaging, is the Graph API permission that lets an app send messages through the WhatsApp Cloud API. Meta's permission reference groups four abilities under it: sending WhatsApp messages, uploading and retrieving the media in messages, managing and reading the WhatsApp business profile, and registering the business's phone numbers with Meta. In API terms it covers POST /{PHONE_NUMBER_ID}/messages — including mark-as-read and typing indicators — the media endpoints, the business profile and POST /{PHONE_NUMBER_ID}/register.
Like all API permissions, it is granted to an app on a token and scoped to specific accounts. A system user access token gets it when you tick it at generation; a Tech Provider gets it when a customer completes Embedded Signup. debug_token lists it in scopes and, under granular_scopes, the WABA IDs whose phone numbers the app may use. A token that lacks the permission gets a permissions error (code 10 or 200) on the messages endpoint, and a valid token whose grant does not include the WABA that owns the number cannot send from it either.
It deliberately stops short of management. Creating or editing templates, listing a WABA's phone numbers, reading analytics and subscribing an app to webhooks all need whatsapp_business_management. Inbound messages and statuses are not fetched with this permission at all: they arrive on your webhook once an app with management access has subscribed to the WABA. A send-only service, such as an OTP sender or a notification worker, can run on this permission alone.
Key takeaways
- whatsapp_business_messaging is the permission an app needs to send WhatsApp messages through the Cloud API on the numbers it has been granted.
- Meta's reference also puts media upload and retrieval, the business profile and phone number registration under it.
- It cannot create templates, list a WABA's numbers or subscribe webhooks; those need whatsapp_business_management.
- debug_token shows whether a token holds it and for which WABA IDs, under granular_scopes.
- Sending for your own business works with standard access; sending for other businesses needs advanced access through App Review.
02 · Specifications
The whatsapp_business_messaging permission: key facts and limits
| Scope name | whatsapp_business_messaging |
|---|---|
| Main endpoint | POST /{PHONE_NUMBER_ID}/messages |
| Also covers | Media, business profile, number registration |
| Does not cover | Templates, number lists, webhook subscriptions |
| Granted per | WABA (granular_scopes.target_ids) |
| Sending for other businesses | Advanced access through App Review |
03 · Code samples
The whatsapp_business_messaging permission in code
curl -X POST "https://graph.facebook.com/v26.0/{PHONE_NUMBER_ID}/messages" \-H "Authorization: Bearer {ACCESS_TOKEN}" \-H "Content-Type: application/json" \-d '{"messaging_product": "whatsapp","to": "919812345678","type": "template","template": {"name": "login_otp","language": { "code": "en" },"components": [{ "type": "body", "parameters": [{ "type": "text", "text": "482913" }] },{ "type": "button", "sub_type": "url", "index": "0","parameters": [{ "type": "text", "text": "482913" }] }]}}'
Needs only whatsapp_business_messaging for the WABA that owns {PHONE_NUMBER_ID}.
04Playground
A working model of whatsapp_business_messaging. Use its controls to replay it step by step.
Can this token send? Run the pre-flight
7/7
ticked
- Required
- 4 / 4
- Optional
- 3 / 3
Ready to send
Every item ticked.
Ready to send. 7 of 7 ticked.
05 · Operation
How does the whatsapp_business_messaging permission work?
Confirm the job only sends
OTPs, notifications and inbox replies need this permission. Template, number-list and subscription work needs the management permission as well.
Pick the access level
Standard access covers your own business's numbers. To send for other businesses, request advanced access in Meta App Review with a screencast of your app sending a message.
Put it on the token
Generate a system user access token with
whatsapp_business_messagingfor the app and WABA, or receive it through Embedded Signup.Check the grant
Run
debug_tokenor the Access Token Debugger: the scope must be listed, and itsgranular_scopesentry must include the WABA that owns your phone number.Send and verify
Call
POST /{PHONE_NUMBER_ID}/messages. A 200 response with awamidmeans the permission, the asset and the registered number all line up.
06 · Cautions
Common mistakes with the whatsapp_business_messaging permission
Adding management just in case
A send-only service that also holds
whatsapp_business_managementcan edit and delete templates. Issue it a messaging-only token.Expecting it to fetch messages
There is no inbox endpoint. Inbound messages and statuses arrive by webhook once the app has been subscribed to the WABA with a management-capable token.
Granting the scope but not the asset
If the system user lacks the WABA, or Embedded Signup did not share it, sends fail despite the scope. Check the WABA ID in
granular_scopes.Launching before advanced access
A Tech Provider's app without advanced access can send only for its own business. Start App Review early and record the screencast on a test number.
07 · Rationale
Why does the whatsapp_business_messaging permission matter?
This is the permission behind every message a business sends through the API, so it is the one most worth getting exactly right. Missing, it blocks go-live; granted alongside management when it is not needed, it leaves a simple sender able to rewrite templates. For Tech Providers it is also a launch gate: without advanced access through App Review, the app can send for its own business but not for the customers it onboards, a delay worth planning for.
08 · Worked example: A one-permission OTP service in Noida
Example: A one-permission OTP service in Noida
A Noida edtech company moves its login OTPs to WhatsApp. Its security team wants the narrowest credential possible, so an admin creates a system user, assigns it the app and the WABA, and generates a token with only whatsapp_business_messaging; debug_token confirms the scope and the WABA ID. Six months later a penetration test recovers the token from a misconfigured log. The testers can send messages until it is revoked, but they cannot read or delete templates, list the company's other numbers or point its webhooks elsewhere.
09 · Recommended practice
Best practices for the whatsapp_business_messaging permission
- Give each sending service its own messaging-only token so it can be rotated alone.
- Alert on permissions errors (codes 10 and 200) separately from delivery failures; they mean configuration, not recipients.
- Re-check granular_scopes whenever a customer adds a new WABA or number.
10 · Questions and answers
whatsapp_business_messaging FAQs
- What permission do I need to send WhatsApp messages through the API?
- whatsapp_business_messaging, granted for the WABA that owns your sending number. Template management and webhook subscriptions also need whatsapp_business_management.
- Does whatsapp_business_messaging let me create templates?
- No. It can send approved templates, but creating, editing or deleting them needs whatsapp_business_management.
- Do I need App Review for whatsapp_business_messaging?
- Only if your app sends on behalf of other businesses. That requires advanced access, granted through App Review with a screencast; your own business's numbers work with standard access.
- Why do I get a permissions error when sending with a valid token?
- The token is valid but either lacks whatsapp_business_messaging or its grant does not cover the WABA that owns the phone number. Check both with debug_token.