urmi-ai/docs/META_APP_REVIEW_PERMISSIONS.md
2026-10-12 23:19:09 +05:30

30 KiB
Raw Permalink Blame History

Urmi × Meta App Review — permissions research

Research-only document. Nothing in this file is implemented in the product yet.

It covers the App Review items currently on the Meta dashboard for Urmi, maps each permission to allowed usage, Graph APIs, Urmi product screens, screencast and test-call requirements, and what not to request until the feature actually exists.

Official sources (review these before submitting)


1. What Urmi is today vs what this review is for

Today (WhatsApp Cloud API)

Urmi already talks to Meta Graph for WhatsApp Business: send/receive messages, templates, media, read receipts, webhooks. That product uses:

  • whatsapp_business_messaging
  • whatsapp_business_management

Those permissions are not in the list at the top of this prompt. The existing WhatsApp Business area in admin/console should stay a messaging inbox. It does not justify Pages, Ads, or Marketing API access.

What this App Review list is for

The permissions below belong to Facebook Login for Business + Pages API + Marketing API. They let a customer’s business connect their Business Portfolio, Facebook Pages, and ad accounts so Urmi can list assets, show Page engagement, read ads reports, and (later) create campaigns.

That is a new Meta product section, separate from the WhatsApp inbox.

Tech Provider vs App Review

These are two different gates:

Gate What it unlocks
Business Verification + Tech Provider Other businesses (not just people with a role on URMI AI) can grant pages_show_list, ads_read, ads_management, business_management, etc.
App Review Advanced Access Those permissions can be requested from any app user after the app is live

Meta’s Tech Provider list includes every permission in this document. Without Tech Provider verification, Graph calls from a customer who is not an app admin/developer/tester are rejected.

WhatsApp Tech Provider (Embedded Signup / Cloud API for clients) is related but not the same submission. You can be a WhatsApp Tech Provider and still fail Marketing API App Review if Pages/Ads screens do not exist.


2. Hard App Review rules (apply to every item)

  1. Only request permissions the live product uses today. Meta rejects “we will use this later.” Audiences (Custom Audience upload) and Leads should not be in this submission unless those screens exist and call the APIs.
  2. Allowed usage is narrow. If the written use case or screencast does not match the official allowed usage, that permission is denied.
  3. Screencast is required for almost every item: full Facebook Login for Business, user grants that permission, then the Urmi UI consumes the data.
  4. At least one successful Graph call using that permission in the last 30 days before submit. The “Request advanced access” button stays disabled until Meta logs the call (can take up to 2 days).
  5. Dependencies must be in the same submission. Example: pages_read_engagement requires pages_show_list; ads_management requires pages_read_engagement.
  6. Do not show tokens in UI or recordings. Show granted-permission names, asset names, and metrics only.
  7. Reviewers must be able to reproduce the flow with the test credentials you provide.

Recommended Meta use case to add on the app

For this permission set, customize:

  • Create & manage ads with Marketing API, and/or
  • Measure ad performance data with Marketing API, and/or
  • Manage everything on your Page (for Pages listing + engagement)

Marketing API use cases require (cannot remove): public_profile, ads_management, ads_read, Marketing API Access Tier, business_management, pages_read_engagement, pages_show_list.


3. Permission dependency graph

public_profile
      │
pages_show_list  ─────────────────────────────────────────┐
      │                                                    │
pages_read_engagement  ◄── required by ads_management      │
      │                                                    │
business_management  (also lists pages_show_list +         │
                      pages_read_engagement as deps)       │
      │                                                    │
ads_read  (no Graph permission deps)                       │
      │                                                    │
ads_management  ◄── requires pages_read_engagement         │
      │               (and therefore pages_show_list)      │
Marketing API Access Tier  ◄── requires ads_read           │
                              OR ads_management            │

Submit all of these together if Urmi will both list Pages and run/read ads. Do not submit ads_management without a working Pages + engagement surface.


4. Item-by-item research

Each section is written so it can be pasted into App Review after the product exists. Sentences in Proposed App Review answer are drafts; they must match the shipped UI exactly.


4.1 pages_show_list

Official purpose Access the list of Pages a person manages.
Allowed usage (1) Show a person the list of Pages they manage. (2) Verify that a person manages a Page.
Dependencies None
Required by pages_read_engagement, and therefore ads_management
Primary APIs GET /me/accounts?fields=id,name,access_token,tasks,link,fan_count
Urmi screen Connections + Facebook Pages
Test call Graph Explorer or app: GET /me/accounts with a user token that includes pages_show_list

What it does

After Facebook Login for Business, Urmi can list Facebook Pages the logged-in admin can act on (name, Page ID, tasks such as MANAGE / ADVERTISE / ANALYZE). That is how Urmi knows which Page belongs to this workspace instead of asking the customer to paste a Page ID.

What it does not do

It does not read posts, insights, ads, or WhatsApp messages. Listing Pages is the entire allowed use.

Compliance

  • Only Pages the user explicitly selected in the login dialog.
  • Do not scrape or store Pages the user did not grant.
  • Page access tokens are secrets (server-side only).
  • Do not use this to browse public Pages the user does not manage.

Urmi business use

A business or agency may manage several brands. In Facebook Pages, they see authorized Pages, pick which Page this Urmi workspace uses, and see connection status. Connections shows “2 Pages connected.”

Proposed App Review answer

Urmi is a communications and marketing platform for businesses. After Facebook Login for Business, we call GET /me/accounts with pages_show_list to show the customer only the Facebook Pages they manage, so they can connect the correct Page to their Urmi workspace. We use this solely to display that list and to verify that the user administers the selected Page before we read Page engagement or attach the Page to ads. We do not use it to access Pages the user does not manage.

Screencast (must show)

  1. Logged-out Urmi → sign in.
  2. Meta → Connections → Connect Meta.
  3. Facebook Login for Business; user grants pages_show_list (and related scopes).
  4. Urmi Facebook Pages lists the real Pages (name, @handle or ID, Connected).
  5. User selects a Page. Stop. Do not skip login or use a pre-connected session only.

Do not request if Connections/Pages UI is still a mock with hardcoded Pages.


4.2 business_management

Official purpose Read/write Business Manager API.
Allowed usage Manage business assets such as an ad account. Claim ad accounts.
Dependencies pages_read_engagement, pages_show_list
Primary APIs GET /me/businesses, GET /{business-id}?fields=name,id, GET /{business-id}/owned_ad_accounts, GET /{business-id}/client_ad_accounts, GET /{business-id}/owned_pages, system users / assigned users (write only if you actually assign assets)
Urmi screen Connections (Business Portfolio) + Ad Accounts + Meta Settings
Test call GET /me/businesses then GET /{business-id}/owned_ad_accounts

What it does

Lets Urmi see which Business Portfolio the user belongs to and which ad accounts and Pages sit under that business—not only Pages from /me/accounts. For a Tech Provider this is how you onboard another company’s assets after they grant access.

Allowed usage trap

The permission reference also asks the screencast to show ads performance data (impressions, conversions, spend, clicks, reach) after grant. Reviewers treat business_management as “manage assets and prove the business can then see ads data in your app.” Pair this screencast with Analytics numbers that came from ads_read, while the Connections screen shows the Business Portfolio and ad accounts discovered via Business Manager API.

If requested as a dependency

If you mainly need it because Marketing API / Pages use cases require it, say so explicitly: “Requested as a required permission for pages_show_list / Create & manage ads with Marketing API, and used to list the customer’s Business Portfolio and ad accounts.”

Compliance

  • Do not claim or reassign ad accounts unless the product has a real “claim / assign asset” flow. Listing owned/client accounts is enough for v1.
  • Do not expose system-user tokens.
  • Write endpoints (assign users, create ad accounts) are high-risk; skip until needed.

Urmi business use

Connections shows:

  • Business Portfolio: genZenith / customer business — Connected
  • Advertising: 1 Ad Account — Connected

Meta Settings lists the connected business, Pages, ad accounts, WABA (WABA still uses WhatsApp permissions, not this one).

Proposed App Review answer

Urmi acts as a Tech Provider for other businesses. We use business_management to read the customer’s Business Portfolio and the ad accounts and Pages assigned to it (GET /me/businesses, GET /{business-id}/owned_ad_accounts, owned/client Pages). This lets the customer connect those assets to Urmi once, instead of pasting IDs. We do not claim or transfer assets in the current product. We request this both as allowed usage (manage/list business assets) and as a required permission for pages_show_list and Marketing API ads use cases. After connection, the same customer can open Meta Analytics in Urmi to see spend, impressions, clicks, and reach for those ad accounts.

Screencast

Login → grant business_management → Connections shows Business Portfolio + ad accounts → open Analytics and show impressions/spend/clicks (satisfies Meta’s ads-performance screencast note).


4.3 ads_read

Official purpose Ads Insights API reports for ad accounts you own or were granted; also Server-Side API (CAPI) for web events.
Allowed usage Custom dashboards and data analytics. Send web events from your server to Facebook.
Dependencies None (still pair with Login + an ad account)
Primary APIs GET /act_{ad-account-id}/insights?fields=spend,impressions,clicks,reach,cpc,ctr,actions&date_preset=last_7d · GET /act_{id}/campaigns (read) · optional CAPI POST /{pixel-id}/events
Urmi screen Overview, Ad Accounts (spend), Analytics
Test call GET /act_{id}/insights with ads_read

What it does

Read-only performance. Spend, impressions, clicks, CTR, CPC, reach, conversions. This is the cleanest justification for Meta Analytics.

What it does not do

Create, pause, or edit campaigns. That is ads_management.

Compliance

  • Only ad accounts the user granted.
  • Do not resell raw user-level ad data. Aggregated account/campaign metrics in the customer’s own dashboard is the allowed pattern.
  • Server-Side API / CAPI is a separate allowed use. Do not mention CAPI in App Review unless Urmi actually sends purchase/lead events from the backend today.
  • Custom Audience upload is not ads_read.

Urmi business use

Analytics: spend, impressions, clicks, CTR, CPC; filters Today / 7D / 30D; breakdown Campaigns / Ads. Overview tiles the same totals. Ad Accounts shows currency, status, spend.

Proposed App Review answer

Urmi provides a Meta Analytics dashboard so a business can see advertising performance next to their customer-communication workspace. After the customer grants ads_read, we call the Ads Insights API (GET /act_{ad-account-id}/insights) and display spend, impressions, clicks, reach, CTR, and CPC in Urmi, filterable by date and campaign. We use this only for that customer’s authorized ad accounts, for in-product reporting. We do not create or edit ads with this permission.

Screencast

Login → grant ads_read → Analytics with real numbers (Impressions, Conversions/results, Spend, Clicks, Reach). Empty zeros fail review.

Do not justify ads_read with “we might send CAPI events later.”


4.4 pages_read_engagement

Official purpose Read Page-posted content (posts, photos, videos, events); follower name/PSID/picture; Page metadata and insights.
Allowed usage Help a Page admin administer and manage a Page: get content posted by the Page; get names, PSIDs, pictures of Page followers; get metadata about the Page.
Dependencies Must include pages_show_list in the same submission
Primary APIs GET /{page-id}?fields=name,username,fan_count,link,about · GET /{page-id}/posts?fields=id,message,created_time,permalink_url,likes.summary(true),comments.summary(true) · Page insights require read_insights as well (GET /{page-id}/insights) — not in the current request list
Urmi screen Facebook Pages → engagement, recent content, Page information, performance
Test call GET /{page-id}/posts with a Page token from /me/accounts

What it does

After the user picks a Page (pages_show_list), Urmi can show recent posts and basic Page profile so the admin can confirm it is the right brand and see recent content/engagement.

Insights caveat

page_impressions / page_engaged_users typically need read_insights plus ANALYZE on the Page. If the Pages screen shows “Performance” charts, either:

  • request read_insights too, or
  • limit v1 “Performance” to fields available without it (e.g. post like/comment summaries from /posts, fan_count on the Page node).

Do not promise Ads Manager–style Page analytics unless read_insights is approved.

Follower PSIDs

Allowed usage includes follower names/PSIDs. That is sensitive. For App Review, showing Page posts and Page metadata is enough. Do not build a follower-export CRM from this permission unless you have a clear admin-management use and privacy policy coverage.

Compliance

  • Page admin administering their Page only.
  • Do not publish, comment, or moderate (those are pages_manage_*).
  • Do not use PSIDs to message people except through approved messaging products.

Urmi business use

Facebook Pages card: Page name, @handle, Connected, recent posts, engagement on those posts, Page about/link. Supports choosing which Page this workspace advertises or represents.

Proposed App Review answer

After a customer connects a Facebook Page with pages_show_list, Urmi uses pages_read_engagement so the Page admin can administer that Page from Urmi: we load Page metadata (GET /{page-id}) and recent posts (GET /{page-id}/posts) and show engagement on that content (reactions/comments summaries). This helps them confirm the correct brand Page and monitor recent content without leaving Urmi. We do not post, comment, or message followers with this permission.

Screencast (Meta is strict here)

Login → grant permission → open Facebook Pages → open a Page → visible post content from that Page inside Urmi (text/image, timestamp). If you only show Page name and “Connected,” reviewers often reject pages_read_engagement.


4.5 public_profile

Official purpose Default public profile fields on the User node. Automatically granted to apps.
Allowed usage Authenticate app users and provide a personalized in-app experience.
Dependencies None
Primary APIs GET /me?fields=id,name,picture
Urmi screen Connections / Meta Settings — “Connected as {name}”
Screencast Often not required the same way; still describe use. Login flow in other screencasts covers it.
Test call Usually not required for Advanced Access the same way; still used on every Login.

What it does

Identifies who connected Meta: name and profile photo in Meta Settings → Connected user. Used only to personalize the connection, not as a consumer social graph.

Proposed App Review answer

Urmi uses public_profile during Facebook Login for Business to authenticate the Meta user and show their name (and profile picture) as the connected operator in Meta Settings, so the workspace knows who granted access. We do not use friends lists or any data beyond the default public profile fields.


4.6 ads_management

Official purpose Read and manage ad accounts the app owns or was granted.
Allowed usage Programmatically create campaigns, manage ads, and fetch metrics. Build ad management tools that provide differentiated value for advertisers.
Dependencies pages_read_engagement (and therefore pages_show_list)
Primary APIs POST /act_{id}/campaigns · POST /act_{id}/adsets · POST /act_{id}/adcreatives · POST /act_{id}/ads · POST /{campaign-id} (status PAUSED/ACTIVE) · plus read insights
Urmi screen Campaigns, Ads & Creatives
Test call Create or update at least one campaign/ad in a sandbox / real test ad account, then list it in Urmi

What it does

This is the write path: create campaign, set budget, attach Page + creative, publish, pause. For Urmi the differentiated value Meta wants to see is messaging-oriented ads (Click-to-WhatsApp / click-to-message) sitting next to the WhatsApp inbox—not a clone of Ads Manager with no extra value.

Click-to-WhatsApp extra permissions

Embedded Signup v4 / CTWA on Marketing API also lists pages_manage_ads. That is not in the current prompt. If Create Campaign publishes a WhatsApp destination ad, confirm whether pages_manage_ads is required for your objective; if Graph returns permission errors, add it in a later App Review rather than claiming CTWA without the permission.

Compliance

  • Advertising Policies + Special Ad Categories (housing, credit, politics).
  • Customer must be able to pause/stop from Urmi.
  • Do not run ads on accounts the user did not select.
  • Creative (image/video/text) stored only as needed to render/manage that ad.
  • “Differentiated value”: communication + ads in one product (WhatsApp destination) is the honest story. A thin wrapper of Ads Manager is a common rejection.

Urmi business use

Campaigns: list status, budget, spend; Create Campaign wizard: Objective → Destination → Page → Budget → Audience (saved/core, not Custom Audience upload) → Creative → Review → Publish. Ads & Creatives: headline, CTA, destination, delivery state.

Proposed App Review answer

Urmi is an ad management tool for businesses that already use Urmi to talk to customers on WhatsApp. With ads_management we create and manage Meta campaigns and ads on ad accounts the customer has authorized (POST /act_{id}/campaigns, ad sets, creatives, ads; pause/activate). Typical flow: choose objective and destination (including WhatsApp where supported), select their connected Facebook Page, set budget, attach creative and CTA, then publish. We also fetch delivery metrics for those campaigns. This keeps advertising and customer messaging in one product. We do not manage ads for accounts the user did not grant.

Screencast

Login → grant ads_management → Campaigns → Create Campaign (or pause/edit an existing one) → resulting ad/campaign visible in Urmi and ads performance (impressions, spend, clicks) on Analytics or the campaign row. Reviewers want create/manage, not only a metrics table (metrics alone is ads_read).

Do not submit ads_management if Create Campaign is UI-only and never calls Graph.


4.7 Marketing API Access Tier (feature, not a permission)

Official purpose Higher Marketing API rate limits, unlimited ad accounts, higher system-user limits, Business Manager API access.
Minimum ads_read or ads_management
Allowed usage Scale marketing ops; read reports (ads_read); read and manage ads (ads_management); pull reports for some clients and manage ads for others (both permissions). Aggregated de-identified analytics to improve the app is also listed.
Tiers Adding Marketing API product → Limited (dev). Full needs App Review plus, to maintain/upgrade: ~500 successful Marketing API calls in 15 days and <15% errors on last 500 calls. Only live /act_{ad-account-id}/… calls count (insights, campaigns, ad sets, ads). Standard Graph (/me, /me/accounts, /me/businesses, Page posts) does not count.
Test call Any successful Marketing API call (/insights, /campaigns, etc.). For Full tier, volume matters after approval.

Relation to “Ads Management Standard Access”

Older docs used “Ads Management Standard Access.” Current dashboard language is Marketing API Access Tier. Same idea: rate limits + many ad accounts.

Urmi business use

Urmi as Tech Provider will operate many customer ad accounts. Limited tier (~300 write units/hour class limits) is not enough once several workspaces publish campaigns. Overview/Analytics polling insights for many accounts also needs Full tier.

Proposed App Review answer

Urmi is a Tech Provider. Each customer workspace may connect one or more ad accounts. We use Marketing API Access Tier so those customers can scale: we read insights (ads_read) and create/manage campaigns (ads_management) across authorized accounts without hitting Limited-tier rate limits, and so we can use Business Manager APIs to list their business assets. We only operate on accounts the customer granted to Urmi.

Screencast

Often covered by ads_read + ads_management recordings. Still describe the feature in text. Show more than one ad account on Ad Accounts if you can.


5. Map to the proposed Urmi Meta sidebar

Sidebar Permissions that must be live Ship for this App Review?
Overview business_management, pages_show_list, ads_read Yes
Connections Login, public_profile, pages_show_list, business_management Yes (onboarding + screencast backbone)
Facebook Pages pages_show_list, pages_read_engagement Yes
Ad Accounts business_management, ads_read Yes
Campaigns ads_management (+ Page perms) Yes if you request ads_management
Ads & Creatives ads_management Yes if you request ads_management
Analytics ads_read Yes
Meta Settings all granted scopes (display only) Yes
Audiences Custom/lookalike APIs, often extra terms Design only — do not request extra perms
Leads leads_retrieval, pages_manage_ads Not this submission

Keep WhatsApp (inbox, templates, webhooks) as its own area. Meta Overview may link to WABA connection health; it should not replace the inbox.


6. Graph calls to log before submit

Use Graph API Explorer or the future Urmi backend. App-role user is enough for Standard Access testing. Log success (HTTP 200) within 30 days:

Permission / feature Minimum successful call
public_profile GET /me?fields=id,name
pages_show_list GET /me/accounts?fields=id,name,tasks
pages_read_engagement GET /{page-id}/posts?fields=id,message,created_time
business_management GET /me/businesses
ads_read GET /act_{id}/insights?fields=impressions,spend,clicks,reach&date_preset=last_7d
ads_management POST /act_{id}/campaigns (or a status update POST /{campaign-id}) and a read of /campaigns
Marketing API Access Tier Same Marketing API calls as ads_read/management

Wait up to 2 days for App Review UI to show the test-call check.


7. Screencast production notes

From Meta’s screen recordings guide:

  • 1080p or higher, entire screen, no jump-cuts through Login.
  • Start logged out of Urmi and Meta when possible.
  • Use Facebook Login for Business (not personal Login) for business assets.
  • One recording per permission is safer than one giant video; each must still include Login + grant + that feature.
  • Show real Page posts and real ads metrics, not lorem ipsum.
  • Provide reviewer login to Urmi + a Meta test user / business they can use.

Suggested recording set:

  1. Connections + Pages list → pages_show_list, public_profile, business_management (asset list).
  2. Page detail with posts → pages_read_engagement.
  3. Analytics dashboard → ads_read (+ business_management ads-data requirement).
  4. Create or pause campaign + creative → ads_management (+ Marketing API Access Tier narrative).

8. What not to build or request in this round

Topic Why
Custom Audiences / lookalikes from Urmi CRM Extra Custom Audience terms, hashing, consent, often ads_management plus policy review. Easy App Review rejection if you cannot demo a lawful upload.
Meta Lead Ads inbox Needs leads_retrieval (and usually pages_manage_ads). Request when the Leads UI exists.
Page posting / comments pages_manage_posts, pages_manage_engagement — not in the current list.
Follower lists / PSID export Allowed under pages_read_engagement but privacy-hostile; skip for v1.
CAPI / Server-Side API Allowed under ads_read only if you actually send events.
Dummy Pages/campaigns in the customer UI Reviewers test live Graph. Mock data will fail.
Exposing Page/ad tokens Security + brand guidelines.

9. Privacy, data handling, and Tech Provider

Expect Data Use Checkup questions for Pages and ads data:

  • What you collect: Meta user id/name; Page ids/names/posts metadata; ad account ids; campaign/ad objects; aggregated insights (spend, impressions, clicks).
  • Why: Provide the customer’s own dashboard and ad tooling.
  • Sharing: Not sold; not used to build unrelated profiles; subprocessors only as in Privacy Policy.
  • Retention: Until the customer disconnects Meta or deletes the workspace; then delete tokens and cached insights.
  • User control: Disconnect Meta in Settings; revoke also from facebook.com/settings.

Update Privacy Policy URLs on the app dashboard so they mention Meta Login, Pages, and ads data—not only WhatsApp Cloud API.


Ship in this order so each App Review item has a real screen:

  1. Facebook Login for Business + token storage (server-only) + Meta Settings (connected user, scopes, reconnect/disconnect).
  2. Connections — Business, Pages count, Ad accounts count, WABA status (WABA may stay on existing WhatsApp token).
  3. Facebook Pages — list from /me/accounts; detail with /posts (this unlocks pages_show_list + pages_read_engagement).
  4. Ad Accounts + Analytics — insights (ads_read, business_management screencast).
  5. Campaigns + Ads & Creatives — only then submit ads_management and Marketing API Access Tier.
  6. Overview — compose the above (no new permissions).

Until step 3 exists, do not submit this App Review list. Until step 5 exists, remove ads_management and Marketing API Access Tier from the submission rather than describing a future wizard.


11. Checklist before clicking Submit

  • Business Verification complete
  • Tech Provider verification in progress or complete
  • Privacy Policy updated for Pages + ads
  • Facebook Login for Business works on production URL reviewers can reach
  • Each permission has a successful Graph call < 30 days old
  • Screencasts: login + grant + in-app use, 1080p
  • No dummy Pages/ads in the demo workspace
  • pages_show_list included if requesting pages_read_engagement
  • pages_read_engagement included if requesting ads_management
  • Audiences/Leads extra permissions not requested
  • WhatsApp inbox remains separate; Meta section is the review surface

12. Current Urmi codebase (gap)

As of this research, Urmi Graph usage is WhatsApp-only (WhatsAppGraphClient, admin WhatsApp inbox, webhooks). There is no Facebook Login, no /me/accounts, no Ads Insights, no campaign create. The permissions in this document cannot be honestly submitted until the Meta section is built and those APIs are called with customer (or test) tokens.

This document is the product/compliance spec for that work. Implementation is a follow-up.