Meta App Review · round 3 — Meta Ads

The Meta Ads permissions

Every organic permission is approved. This round asks for the four permissions and the one feature the Marketing API needs before Socialyfy can run real campaigns on a customer's own ad account. For each: the text to paste into the “Please provide a detailed description…” box, and a screencast script detailed to the click — what to set up first, what you will see, where to press, what to caption, and what must stay out of that video.

Where we stand — 11 November 2026

The rules that won round 2 — they still apply

Before you submit — one-time setup

Meta app dashboard + Socialyfy serverDo these in order
In the Meta app dashboard
  1. Confirm Business verification still reads “Verified”. App dashboard → App settings → Basic → the verification panel (it was completed for WhatsApp). Meta requires it before it grants Advanced access to the ads permissions, and before any business can run ads through the app.
  2. Add the ads use case to the existing app. App dashboard → Use cases → Add use case → “Create & manage ads with Marketing API” → Add. Meta adds Facebook Login for Business and Webhooks to it automatically. Open the use case's Customize page: ads_management, ads_read, business_management, pages_read_engagement, pages_show_list and public_profile are listed as required. Click Add beside the optional pages_manage_ads. Use the same app the organic connect uses: its verification and its App Review history carry over. A second app is supported (META_ADS_APP_ID + META_ADS_APP_SECRET) but starts App Review from zero.
  3. Create the ads login configuration. Facebook Login for Business → Configurations → Create configuration. Name it Socialyfy Ads. Login variation: General. Access token: User access token, not system-user: the publisher acts in real time on the person's own grant. Assets: Ad accounts and Pages. Permissions: tick exactly ads_management, ads_read, business_management, pages_show_list, pages_read_engagement and pages_manage_ads. Save, then copy the numeric Configuration ID. Keep this configuration separate from the organic one in FACEBOOK_LOGIN_CONFIG_ID. A configuration grants every permission it lists, so adding the ads permissions to the organic one would ask every customer who connects a Page for access to their ad accounts.
  4. Register the redirect URI. Facebook Login for Business → Settings → Valid OAuth Redirect URIs: add <OAUTH_CALLBACK_BASE_URL>/api/ad-connections/callback/meta_ads. Use the same base as the Facebook Page callback that already works. A mismatch fails the connect with no useful message.
On the Socialyfy server (socialyfy/backend/.env, then restart api and the Celery workers)
  1. META_ADS_LOGIN_CONFIG_ID=<the Configuration ID>. With it set, the ads dialog sends config_id and the scope list in META_ADS_OAUTH_SCOPES is ignored.
  2. META_ADS_GRAPH_VERSION=v25.0 (the default). The Marketing API retires versions much faster than Graph: v23 retired on 9 Jun 2026 and v24 on 10 Nov 2026, and v25 is available until 23 Feb 2027. Do not point it at META_GRAPH_VERSION.
  3. Leave META_ADS_APP_ID / META_ADS_APP_SECRET blank to reuse the main app. The Ad accounts page then shows Connect Meta Ads instead of “Not available on this server”.
Test assets the videos need
  1. A Business Portfolio (the one that owns the Mediflow Page) holding one ad account with a payment method and a currency you can read on screen. The Facebook user you record with needs full control of that ad account and of the Mediflow Page: Business settings → Users → People → assign both assets.
  2. A Socialyfy workspace on a plan that includes advertising (the sidebar group Advertising must not show a lock), with your user as Owner or Admin: only admins see Ad accounts.
  3. The Socialyfy admin credentials (ADMIN_USERNAME / ADMIN_PASSWORD), because a campaign only reaches Meta after an admin approves it.
  4. A live web page you own to use as the ad's link (Meta pulls its preview image). The business site is ideal.
Make the test calls, then qualify for Full access
  1. Each permission needs a successful test call before Meta lets you request it. One run-through does it: connect the ad account (business_management, pages_show_list), publish one campaign (ads_management, pages_manage_ads, pages_read_engagement), and let one hourly insights read pass (ads_read, at 35 minutes past each hour). In development mode this works for anyone with a role on the app.
  2. Marketing API Access Tier → Full access needs 500+ Marketing API calls in the past 15 days and an error rate under 15 % across the last 500 calls. Socialyfy reads each connected ad account once an hour, which is 24 calls a day and about 360 in 15 days. Connect two ad accounts (each in its own workspace) to clear 500 in about 11 days, or let one run for three weeks. Progress shows under App Review → Permissions and Features → Marketing API Access Tier. A revoked connection stops syncing on its own, so it does not count against the error rate.
How to set up the recordingApplies to all four videos
Two browser profiles, three windows
  • Profile A (your normal profile): tab 1 is Socialyfy at https://socialyfy.com/login. Tab 2 is Meta Ads Manager at https://adsmanager.facebook.com, signed in as the same Facebook user, with the test ad account picked in the account switcher (top left) and the Campaigns tab open.
  • Profile B (a separate profile or an InPrivate / Incognito window): the Socialyfy admin dashboard at https://socialyfy.com/admin/login, signed in before you start recording so the admin password never appears on camera. It has to be a separate profile: the user app sends any browser holding an admin session straight to /admin.
  • 1920 × 1080, browser zoom 100 %, bookmarks bar hidden, notifications off. Add captions in editing, as a lower third, using the exact wording each script gives.
Record in this order — it matters
  1. business_management: creates no campaign.
  2. ads_management: creates Review — traffic and leaves it running at a small daily budget, so ads_read has something to read.
  3. pages_manage_ads: creates its own campaign, Review — Page ad. Pause it in Ads Manager as soon as you stop recording.
  4. ads_read: at least 24 hours after video 2, so the account has delivery to read. Start recording at about 25 past the hour, because the read runs at 35 past. Pause every review campaign in Ads Manager when you finish.
Every video starts with Disconnect → Connect Meta Ads so the grant is recorded from scratch. Disconnecting deletes the Socialyfy connection, and campaigns made under it can no longer be paused from Socialyfy afterwards (they keep running on Meta). That is why each campaign is created inside the video that needs it, and why the ads_read script reads the four account totals rather than one campaign's row.

Round 3 — the Meta Ads permissions

ads_managementNew — submit now
Socialyfy is a social media management tool for small businesses. This permission is used for one feature: running a paid ad campaign that the business wrote in Socialyfy, on the business's own ad account, after a human has reviewed it.

How we use the permission: in Socialyfy the person opens Ad campaigns, picks the ad account they connected, and fills in a campaign name, an objective, a daily budget and the ad itself - a link, the primary text, an optional headline, a button, the countries and the age range. Saving creates a draft inside Socialyfy and "Send for approval" queues it; nothing is sent to Meta at either step. A Socialyfy reviewer then approves the campaign in our admin dashboard, and only that approval starts publishing. Publishing makes these calls with the person's token, in this order: POST /act_{ad-account-id}/campaigns (created PAUSED, with special_ad_categories and the daily budget), POST /act_{ad-account-id}/adsets (the countries and ages they chose, created PAUSED), POST /act_{ad-account-id}/adcreatives (their link ad, run as their own Facebook Page), POST /act_{ad-account-id}/ads (PAUSED, pointing at that creative), and finally POST /{campaign-id} with status ACTIVE. Every object is created paused and switched on in one last step, so nothing can spend money until the whole campaign exists. Afterwards the person can pause and resume the campaign from the same screen, which is POST /{campaign-id} with status PAUSED or ACTIVE.

How it adds value: a small business plans its organic posts and its paid campaigns in one place, in the same brand voice, and every budget is reviewed before it goes live. Running a simple traffic campaign no longer means learning Ads Manager.

Why it is necessary: creating campaigns, ad sets, creatives and ads, and changing a campaign's status, all require ads_management - no other permission authorizes writing to an ad account. We act only on the ad account the person chose when they connected. We never create anything the person did not write, and an edit to the budget, targeting or ad of an approved campaign goes back through review before it reaches Meta.

Note for the reviewer on the screencast: Socialyfy makes these API calls server-side. Publishing runs in a background worker using the access token stored when the person connected their ad account, so no Meta login dialog is on screen at the moment the calls are made. The recording therefore shows the person granting this permission first, then writing the campaign in Socialyfy, then the same campaign, ad set and ad appearing in Meta Ads Manager, and finally the campaign being paused and resumed from Socialyfy.

Screencast — record this fresh, on its own (video 2 of 4)

Before you press record
  • Profile A tab 2 (Ads Manager, Campaigns tab) shows no campaign called Review — traffic. If one is left over from a rehearsal, delete it there first.
  • Profile B (admin) is signed in and sitting on the admin Overview.
  • Have the ad's text ready on paper. You will type it, not paste it: the reviewer needs to see a person writing the ad.
The take
  1. Start on the signed-out login page. Profile A, tab 1: https://socialyfy.com/login. You will see the Socialyfy logo, an Email field (placeholder you@example.com), a Password field and a dark Sign in button. Start recording before you type anything.
  2. Sign in. Type the test account's email and password (the same ones you gave Meta in the submission's test-user fields) and click Sign in. The page redirects to /dashboard/ with the sidebar on the left.
  3. Open Advertising. In the sidebar click the group heading Advertising to expand it. It holds three entries: Ads, Ad campaigns and Ad accounts. Click Ad accounts.
  4. Read the page in. The heading is Ad accounts, with the subtitle “Connect the Google Ads, Meta, LinkedIn or X ad account your campaigns should run on. Nothing is charged to it until an admin approves a campaign.” Below it is one card per platform: Google Ads, Meta Ads, LinkedIn Ads, X Ads. Hold for two seconds.
  5. Disconnect, so the grant is recorded from scratch. If the Meta Ads card shows an account name, click Disconnect on it. A dialog titled Disconnect says “We'll forget this account and stop syncing its numbers…”; click Disconnect in the dialog. The toast “Ad account disconnected.” appears and the card now shows a Connect Meta Ads button.
  6. Start the Meta login. Click Connect Meta Ads. The button shows a spinner and a Meta popup (about 640 × 760) opens over Socialyfy. Keep the whole popup in frame. Do not resize or minimise it.
  7. Step through Meta's dialog without skipping a screen. Continue as yourself. When Meta asks which business and which ad accounts Socialyfy may use, choose the portfolio and tick the test ad account. When it asks for Pages, tick Mediflow. On the screen that lists what Socialyfy will be able to do, stop and hold for at least four seconds with the line about managing your ads readable. ads_management — Socialyfy may create and manage ads on the ad account you choose.
  8. Finish and pick the account. Click through Save / Done. The popup closes by itself. A panel headed Choose an ad account appears under the cards. Each row shows the account name, then ID · currency · time zone, and a Use this account button. Click Use this account on the test ad account. The toast “Ad account connected.” appears, and the Meta Ads card shows the account name and ID · currency.
  9. Open Ad campaigns. In the sidebar click Ad campaigns. The heading is Ad campaigns, with the subtitle “Build a campaign, send it for review, and track what it spends once it's live.” Below it are four tiles (SPEND, IMPRESSIONS, CLICKS, REACH) and a box headed New campaign. Do not point at the tiles: they belong to the ads_read video.
  10. Fill in the campaign, typing every value. Platform: open the dropdown and choose the test ad account by name. Campaign name: Review — traffic. Objective: traffic. The dropdown also lists leads, sales, awareness and engagement; use traffic, which needs no pixel or lead form. Budget: 500 (a daily amount in the account's currency). Use about 5 on a USD account; it must clear Meta's minimum.
  11. Fill in the ad. As soon as a Meta account is chosen, a section headed The ad appears, with the note “Meta runs the ad as the Facebook Page picked when this account was connected, and shows your link's preview image. Nothing is created on Meta until an admin approves the campaign.” Link: your business page, e.g. https://mediflow.in. Primary text: Our new season list is out - tap to see prices. Headline (optional): New season at Mediflow. Button: Learn more. Countries: IN. Min age: 25, Max age: 55.
  12. Save the draft. Click the New campaign button under the form (it stays greyed out until the link starts with https:// and the primary text is filled). The form clears and a row appears in the table, reading: Review — traffic · Meta Ads · Draft · Not published · — · — · —, with a Send for approval button on the right. Saved in Socialyfy only. Nothing has been sent to Meta.
  13. Prove it is not on Meta yet. Switch to tab 2 (Ads Manager) and reload. The Campaigns list has no Review — traffic. Hold for two seconds. Not in Ads Manager yet.
  14. Send it for review. Back in tab 1, click Send for approval. The toast “Sent for review.” appears, the approval column changes to Awaiting review, and the button disappears.
  15. Approve it as Socialyfy's reviewer. Switch to the Profile B window. In the admin sidebar click Advertising. The heading is Advertising, with the subtitle “Campaigns waiting for review. Approving one is what sends it to Google or Meta — nothing reaches an ad platform any other way.” The filter chip Awaiting review is selected, and the Queue lists Review — traffic with workspace · Meta Ads · budget under it. Click it. The Campaign panel fills in: Platform Meta Ads, Ad account (name and ID), Objective OUTCOME_TRAFFIC, Budget, Approval submitted, Publishing unpublished, and under Campaign structure three lines: ad_set · Review — traffic — ad set, creative · Review — traffic — creative, ad · Review — traffic — ad. A person reviews the spend. Approving is the only way anything reaches Meta.
  16. Click Approve & publish. The toast “Approved — publishing now.” appears. Wait about 30 seconds. Then click the Approved filter chip and click Review — traffic again. Publishing now reads published, and each Campaign structure line ends with the ID Meta returned. Hold for three seconds.
  17. Show it on Meta. Switch to Profile A tab 2 and reload Ads Manager. Review — traffic is in the Campaigns list with its toggle On and the daily budget you typed. Click its name. On the Ad sets level, Review — traffic — ad set has the audience you typed (India, 25–55). Click through to the Ads level: Review — traffic — ad is listed. Its delivery may read “In review”: that is Meta's own ad review and is expected. Hold for four seconds. Campaign, ad set and ad were all created by Socialyfy through the Marketing API. Nothing was typed into Ads Manager.
  18. Pause it from Socialyfy. Back in tab 1, reload Ad campaigns. The row now reads Approved · Published with a Pause button. Click Pause. The toast “Campaign paused.” appears. Switch to Ads Manager and reload: the campaign's toggle is Off. Paused from Socialyfy.
  19. Resume it. Back in Socialyfy click Resume. The toast “Campaign resumed.” appears. Reload Ads Manager: the toggle is On again.
  20. Stop recording. Leave the campaign running at its small budget. Video 4 (ads_read) needs a day of delivery to read.
Keep out of this video: the ad preview and the Page name in Ads Manager (that is pages_manage_ads's proof), the Spend / Impressions / Clicks / Reach figures (ads_read's), and Business settings (business_management's). The account picker appears because connecting requires it. Do not caption it.
ads_readNew — submit now
Socialyfy is a social media management tool for small businesses. This permission is used for one feature: showing the business how its own ad campaigns are performing, next to its organic results.

How we use the permission: once an hour a background job calls GET /act_{ad-account-id}/insights for the one ad account the person connected, with level=campaign, time_increment=1 and the fields impressions, reach, frequency, clicks, spend, ctr, cpc, cpm, actions, action_values and cost_per_action_type. Each pass re-reads the last seven days, because Meta restates recent figures. We store one row per campaign per day and show it on the Ad campaigns screen - the Spend, Impressions, Clicks and Reach totals, and each campaign's spend, clicks and reach. The screen reads only our stored rows; opening a page never calls Meta. A metric Meta does not report is shown as a dash, never as zero.

How it adds value: the person sees what each campaign spent and what it returned without opening Ads Manager, and sees it beside their organic posts, so they can decide whether to keep paying for a campaign or put that money into content instead.

Why it is necessary: reading ad insights requires ads_read. Without it the hourly read fails and every figure on the screen stays blank, so the person cannot judge the campaigns they are paying for. We read insights only for the ad account the person connected, and we never share or sell the data.

Note for the reviewer on the screencast: Socialyfy makes these API calls server-side, on an hourly schedule, using the access token stored when the person connected their ad account, so no Meta dialog is on screen at the moment of the read. The recording shows the person granting this permission, then the figures on the Ad campaigns screen being compared with Ads Manager, and then those figures changing after the next hourly read with nobody touching Socialyfy.

Screencast — record this fresh, on its own (video 4 of 4)

Before you press record
  • At least 24 hours have passed since video 2, and in Ads Manager Review — traffic shows impressions and amount spent. If it shows nothing, Meta's ad review has not finished. Wait.
  • In Ads Manager (Profile A tab 2), set the date range (top right) to Last 30 days. Open Columns → Customize columns and keep Amount spent, Impressions, Clicks (all) and Reach visible. Socialyfy's CLICKS is Meta's Clicks (all), not Link clicks.
  • Start recording at about 25 minutes past the hour. Socialyfy reads Meta at 35 past.
The take
  1. Start on the signed-out login page (https://socialyfy.com/login) and sign in as in the other videos. The sidebar appears.
  2. Advertising → Ad accounts. On the Meta Ads card click Disconnect, confirm Disconnect in the dialog (toast “Ad account disconnected.”), then click Connect Meta Ads.
  3. Hold on the grant. Step through Meta's dialog as before. On the screen listing what Socialyfy will be able to do, hold for at least four seconds with the line about your ads' performance / insights readable. ads_read — Socialyfy may read the performance of your ads.
  4. Pick the same account. The popup closes and Choose an ad account appears. Click Use this account on the test ad account. The toast “Ad account connected.” appears.
  5. The “before” numbers. Click Ad campaigns in the sidebar. Hold on the four tiles across the top: SPEND, IMPRESSIONS, CLICKS, REACH. These cover the last 30 days, as of the last hourly read. If an amber line reads “Analytics synchronisation delayed — these numbers may be behind.”, leave it on screen: the new connection has not been read yet, and the product says so instead of passing old numbers off as current. Read from Meta at the last hourly sync.
  6. The same account in Ads Manager. Switch to tab 2 and reload. Point at the totals row for Amount spent, Impressions and Clicks (all). They match Socialyfy's tiles, or run slightly ahead because the campaign kept delivering after the last read. Do not compare Reach: Socialyfy adds up each day's reach, and Ads Manager de-duplicates people across the range, so Socialyfy's figure reads higher. Same ad account, same figures — Socialyfy reads them from Meta's Insights API.
  7. Wait for the read. Pause the recording. Resume at about 40 past the hour, after the 35-past read. Do not touch Socialyfy in between.
  8. The “after” numbers. Reload Ads Manager and note the new Amount spent and Impressions. Switch to tab 1 and reload Ad campaigns. The SPEND and IMPRESSIONS tiles have gone up to match, and the amber “delayed” line (if it was there) is gone. Hold for four seconds on the tiles. Socialyfy re-read the ad account at 35 past the hour. Nothing was typed into it.
  9. Show the honesty rule. Scroll to the line under the table: “A dash means the platform doesn't report that metric — Google Search has no reach, for example. It is not zero.” Hold for two seconds.
  10. Stop recording. Then pause Review — traffic (and Review — Page ad) in Ads Manager so neither keeps spending.
Keep out of this video: creating, approving, pausing or resuming any campaign (all ads_management), the ad preview (pages_manage_ads) and Business settings (business_management). This video only shows numbers being read.
business_managementNew — submit now
Socialyfy is a social media management tool for small businesses. In our ads feature this permission covers one step: reaching the ad accounts a person can advertise from when those accounts belong to a Meta Business Portfolio, so the person can choose one.

How we use the permission: the person connects Meta Ads through Facebook Login for Business, where they pick the Business Portfolio and the ad account inside it that Socialyfy may use. We then call GET /me/adaccounts with the fields account_id, name, currency, timezone_name, account_status and business, and list the active accounts so the person can pick the one that pays for their campaigns. The business field tells us which portfolio the chosen account belongs to, and we store that id with the connection. Every later call - creating the campaigns the person writes, reading their results - goes to that one ad account.

What we deliberately do not do: we never use the Business Manager API to create, change, assign or delete business assets, people or partners. We do not read the portfolio's people, payment methods, catalogues or anything outside the ad account the person picked. There is no Embedded Signup and no client onboarding in this product: a Socialyfy workspace connects only accounts its own person can already reach.

How it adds value: nearly every real business keeps its ad account inside a Business Portfolio rather than on a personal profile. This permission is what lets those customers connect the ad account their company actually uses, in one step.

Why it is necessary: business-owned ad accounts are made available to our app through this permission, and Meta lists business_management as required for the "Create and manage ads with Marketing API" use case. Without it the connect screen would show nothing for most businesses and the ads feature could not be used at all.

Note for the reviewer on the screencast: the read happens while the person connects, so the recording shows the person granting this permission, choosing their Business Portfolio and its ad account in Meta's dialog, the same portfolio-owned ad account (same ID) being listed and selected in Socialyfy, and Business settings confirming that the account belongs to the portfolio.

Screencast — record this fresh, on its own (video 1 of 4)

Before you press record
  • Profile A tab 2: open https://business.facebook.com/settings on the portfolio that owns the test ad account, then Accounts → Ad accounts, with the test ad account selected so its name and ID are on screen.
  • Write the ad account ID on paper. You will point at it in both windows.
The take
  1. Start on the signed-out login page (https://socialyfy.com/login) and sign in with the test account. The sidebar appears.
  2. Advertising → Ad accounts. The heading is Ad accounts, with four platform cards. If the Meta Ads card shows an account, click Disconnect and confirm Disconnect (toast “Ad account disconnected.”).
  3. Click Connect Meta Ads. The Meta popup opens. Keep it fully in frame.
  4. Hold on the business choice. This is the heart of the video. Continue as yourself. When Meta asks which business Socialyfy may use, the portfolio's name is on screen: hold for four seconds. The ad account belongs to this Business Portfolio, not to a person.
  5. Hold on the ad-account choice. On the next screen tick the test ad account (its name and ID are shown) and hold for three seconds. Tick the Mediflow Page when asked.
  6. Hold on the permission screen. On the screen listing what Socialyfy will be able to do, hold for at least four seconds with the line about business assets / your business readable. business_management — access to the ad account held in the Business Portfolio.
  7. Finish. Click Save / Done. The popup closes. A panel headed Choose an ad account appears with the hint “This sign-in can reach more than one ad account. Pick the one that should pay for these campaigns.” Each row shows the account name and ID · currency · time zone. Listed by Socialyfy from Meta (GET /me/adaccounts).
  8. Match it against Business settings. Switch to tab 2 (Business settings → Ad accounts) and point at the same account name and ID under the portfolio. Hold for three seconds. Same ID, owned by the Business Portfolio.
  9. Choose it. Back in tab 1, click Use this account on that row. The toast “Ad account connected.” appears and the Meta Ads card shows the account name and ID · currency.
  10. Show where it will be used. Click Ad campaigns in the sidebar. In the New campaign box, open the Platform dropdown. The portfolio's ad account is listed by name. Select it: the section The ad appears below. Campaigns will run on the portfolio's ad account.
  11. Stop recording. Do not create the campaign.
Keep out of this video: clicking New campaign, the admin dashboard and Ads Manager (all ads_management), any figures (ads_read) and the ad preview (pages_manage_ads). Business settings is shown read-only. Change nothing in it.
pages_manage_adsNew — submit now
Socialyfy is a social media management tool for small businesses. This permission is used for one thing: letting the business's ad run as its own Facebook Page.

How we use the permission: every Meta ad needs a Page identity - the ad account pays, and the Page is the name and picture the ad appears under. When the person connects Meta Ads they choose their Page in Meta's dialog, and we read it with GET /me/accounts. When a campaign they wrote in Socialyfy is published (only after our reviewer approves it), we call POST /act_{ad-account-id}/adcreatives with an object_story_spec whose page_id is that Page and whose link_data holds their link, primary text, headline and button. That creative is what the ad shows. We use only the Page the person picked and administers.

How it adds value: the ad appears under the business's own name and logo, so people who see it recognise the business and can visit its Page, instead of seeing an unfamiliar sponsor.

Why it is necessary: creating an ad creative that names a Page in object_story_spec requires pages_manage_ads; without it Meta refuses the creative and the campaign can never deliver. We use it only to create ads for the connected Page - never to publish organic posts, read messages or change the Page's settings.

Note for the reviewer on the screencast: Socialyfy makes these API calls server-side, in a background worker, after our reviewer approves the campaign, so no Meta dialog is on screen at that moment. The recording shows the person granting this permission and choosing their Page, then writing the ad in Socialyfy, and then the ad's preview in Ads Manager showing it running under the business's own Page.

Screencast — record this fresh, on its own (video 3 of 4)

Before you press record
  • Profile B (admin) is signed in. Profile A tab 2 is Ads Manager on the Campaigns tab, with no Review — Page ad in it.
  • Know which Page the ad should show: Mediflow, with its profile picture.
The take
  1. Start on the signed-out login page (https://socialyfy.com/login) and sign in with the test account.
  2. Advertising → Ad accounts → on Meta Ads click Disconnect, confirm Disconnect, then click Connect Meta Ads.
  3. Hold on the Page choice. In Meta's dialog, continue as yourself and choose the portfolio and ad account. When Meta asks which Pages Socialyfy may use, tick Mediflow and hold for three seconds. The ads will run as this Page.
  4. Hold on the permission screen. Hold for at least four seconds with the line about ads for your Pages readable. pages_manage_ads — create ads that run as your Page.
  5. Finish and pick the account. Save / Done → the popup closes → Choose an ad account → Use this account. The toast “Ad account connected.” appears.
  6. Write the ad. Click Ad campaigns. In New campaign set Platform to the test ad account, Campaign name Review — Page ad, Objective traffic, Budget 500. In The ad, point at its note “Meta runs the ad as the Facebook Page picked when this account was connected…” and hold for two seconds. The ad runs as the business's own Page. Then type: Link https://mediflow.in, Primary text Booking is open for this weekend., Headline (optional) Mediflow, Button Contact us, Countries IN. Leave the ages at 18 and 65.
  7. Save and send. Click New campaign. The row appears as Draft. Click Send for approval. The toast “Sent for review.” appears.
  8. Approve, briefly. Switch to Profile B → Advertising → click Review — Page ad in the Queue → Approve & publish. The toast “Approved — publishing now.” appears. Do not dwell here: this step belongs to the ads_management video.
  9. Open the ad in Ads Manager. Wait about 30 seconds, then switch to Profile A tab 2 and reload. Click Review — Page ad, then the Ads level, then the ad's name Review — Page ad — ad. The ad opens with its preview on the right.
  10. Hold on the preview. This is the proof. The preview shows the Mediflow name and profile picture with Sponsored, the primary text you typed, and the link card with the headline and a Contact us button. In the editor's Identity section the Facebook Page reads Mediflow. Hold for five seconds. Creative created by Socialyfy (object_story_spec with page_id). The ad runs as the Mediflow Page.
  11. Close without saving. Close the ad editor with the ✕ (choose Discard / Close if asked). Never click Publish in Ads Manager.
  12. Stop recording. Then switch Review — Page ad off in Ads Manager so it does not spend.
Keep out of this video: Pause / Resume in Socialyfy (ads_management), any figures (ads_read) and Business settings (business_management). Do not open the Mediflow Page's own timeline either. This permission is about the ad's identity, not organic posting.
Marketing API Access Tier — Full accessFeature, not a permission
Socialyfy is a social media management tool for small businesses. We request Full access to the Marketing API so the businesses that use Socialyfy can run and measure campaigns on their own ad accounts, not only on ad accounts held by people with a role on our app.

How we use it: each business connects its own ad account through Facebook Login for Business. Socialyfy creates campaigns only after the business has written them and a Socialyfy reviewer has approved them, using ads_management, and reads their performance once an hour with ads_read. We do not manage ad accounts on anyone's behalf without their own login, and we do not use the Business Manager API to administer businesses.

How we keep our calls healthy: the dashboard reads stored figures and never calls Meta when a page opens; every publish step records the id Meta returns, so a retry resumes rather than creating duplicates; an expired grant stops further calls for that connection until the business reconnects; and a refused or rate-limited call is logged and retried on the next schedule instead of in a loop.

No screencast — what Meta checks instead

  1. The requirements are on the request page: 500+ Marketing API calls in the past 15 days and an error rate below 15 % across the last 500 calls. Since 4 May 2026 the screen recording is no longer required. The feature was called “Ads Management Standard Access” until then, with Limited = the old Standard and Full = the old Advanced.
  2. It sits on top of the permissions. Meta needs at least ads_read or ads_management for it, so submit it together with them or right after they are approved.
  3. Without it, everything works only for people with a role on the app, or in a portfolio that has claimed it, which is exactly the development-mode limit. Real customers would see Meta's error during connect.
  4. To get there: see “Make the test calls, then qualify for Full access” in the setup above.
Round 2 archive — approvedeight permissions · kept for renewals and the Data Use Checkup

Everything below was submitted in round 2 and approved. The text is exactly what Meta accepted. If Meta ever asks for a renewal or a fresh recording, re-use it as it stands. The organic business_management draft that used to sit here was never submitted. The ads card above replaces it.

Rejected on 17 August, resubmitted — approved

pages_read_user_contentApproved
Socialyfy is a social media management tool. This permission is used for two features, both limited to the connected Page's own posts.

How we use the permission: first, analytics. For each post the person published through Socialyfy we read the engagement counts with GET /{post-id}?fields=reactions.summary(total_count),comments.summary(total_count),shares and show them on the Analytics, Social screen and in the daily performance summary we send the person. Second, comment response. The Page feed webhook delivers the text of comments left on those posts, and this permission is what authorizes us to read that user content so the person's own keyword rules can be matched against it.

How it adds value: the person sees reactions, comments and shares for every post in one place, alongside Instagram, Threads, LinkedIn and X, instead of opening Facebook and checking each post by hand. It is also what lets them answer a customer's comment within seconds rather than hours.

Why it is necessary: reactions and comments are user-generated content, so pages_read_engagement does not authorize this read - Meta answers with error (#10) without this permission, and every engagement column in Socialyfy's analytics renders blank, which makes the analytics feature unusable for Facebook. We read only the connected Page's own posts, never content from Pages the person does not manage, and we do not sell or share the data.

What the screencast proves: the comment and reaction counts in Socialyfy change on camera, from zero to one to two, as comments are added to the post from another Facebook account - so the numbers are visibly read from the Page rather than displayed from memory.

Note for the reviewer on the screencast: Socialyfy makes these API calls server-side. Publishing, analytics collection and the comment automations run in background workers using the access token stored when the user connected their account, so no Meta login dialog is on screen at the moment the API call is made. The recording therefore shows the user granting this permission first, and then the feature that permission enables.

Screencast — record this fresh, on its own

  1. Start the recording on the signed-out login page. Go to https://socialyfy.com/login. You will see the Socialyfy logo, an Email field showing the placeholder you@example.com, a Password field showing dots, and a dark Sign in button beneath them. Begin recording before you type anything.
  2. Sign in. Type akshats@fealtytechnologies.com into Email and the password into Password, then click Sign in. The page redirects to /dashboard/ and the left sidebar appears with Today, Approvals, Chat Studio, Inbox, Statement and Analytics at the top.
  3. Open the platform settings. In the left sidebar click Settings (the gear, near the bottom) to expand it, then click Platforms. The page shows a card headed Connections with the subtitle “The social accounts your approved posts go out to.” and one row per network: LinkedIn, Threads, Twitter / X, Instagram and Facebook.
  4. Disconnect first, so the grant is recorded from scratch. On the Facebook row click Disconnect (right-hand side, next to the green “Connected”). A confirmation dialog appears — confirm it. The row now shows a CONNECT button instead.
  5. Start the Meta login flow. Click CONNECT on the Facebook row. A Meta popup window opens on top of Socialyfy. Do not resize or minimise it — the whole dialog must stay in frame.
  6. Step through Meta's dialog without skipping a screen. Continue as yourself, choose the Mediflow Page when Meta asks which Pages to use, and when the permissions screen appears stop and hold for at least four seconds so that pages_read_user_content is readable on camera. Add a caption naming it. This is requirement 2 on your rejection notice — “a user granting app access to the permission”.
  7. Finish and return. Click through Save and then Done. The popup closes by itself and the Facebook row in Socialyfy flips back to green Connected with the Page name Mediflow beside it.
  8. Open the composer. In the sidebar click Content to expand the group, then New Post. The page is headed New post with the subtitle “Socialyfy writes it in your brand voice…”.
  9. Pick the platform. Under Platforms click the Facebook chip so it is the only one highlighted. The hint below reads “Pick one or more. Each gets its own draft…”, and a per-platform character counter appears on the right.
  10. Write the post yourself. Scroll to Or write it yourself and click into the Your post box (placeholder “Write your post…”). Type New season list is out - ask us anything below.. The character counter updates as you type.
  11. Publish immediately. Leave Schedule for (optional) empty — the hint underneath says “Leave empty to publish immediately.” — and the button at the bottom reads Publish now rather than “Schedule post”. Click it. A green toast confirms, and the credit figure in the top-right corner drops.
  12. Record the "before" state. In the sidebar click Analytics. On the Social tab click Refresh metrics and wait for it to finish. Scroll to Top posts (by engagement), find the row for the post you just published, and hold on it showing LIKES 0 and CMTS 0. Caption: “no comments yet”.
  13. Add the first comment — from a different account. Without stopping the recording, switch to a second browser tab where you are signed in to Facebook as someone other than the Page and other than the admin who connected it. Open the Mediflow post and comment Do you deliver on weekends? Then click Like on the post.
  14. Show the count move. Switch back to the Socialyfy tab and click Refresh metrics again. The same row now reads CMTS 1 and LIKES 1. Hold on it and caption: “the app just read that comment from the Page.”
  15. Do it once more, so it cannot be a coincidence. Go back to Facebook, add a second comment from another account — What are your prices? — return to Socialyfy, click Refresh metrics, and hold on the row now reading CMTS 2.
  16. Stop recording.
The change is the proof, never the number. Round one showed a table that already had figures sitting in it, which demonstrates nothing a reviewer can attribute to this permission. A count moving 0 → 1 → 2 on camera, driven by comments the reviewer watched you post, can only happen if the app is reading user content from the Page.
pages_manage_engagementApproved
Socialyfy is a social media management tool. This permission is used for exactly one feature: a public reply to a comment left on the business's own Page post.

How we use the permission: in Socialyfy the person opens the Auto Replies screen and creates a rule in their own words. They choose a trigger word and they type the reply text themselves at that moment; nothing is generated, rewritten or added afterwards. When the Page feed webhook tells us a comment containing that trigger word was added, we post the reply text they wrote, verbatim, as a threaded public reply with POST /{comment-id}/comments. We reply at most once per comment, we skip comments made by the Page itself, and we act only on posts that were published through Socialyfy.

How it adds value: small businesses lose customers to unanswered comments. The person writes their answer to a common question once and every future asker gets it in seconds, publicly, where other interested people can see it too.

Why it is necessary: creating a comment as the Page requires this permission - pages_manage_posts covers only the Page's own posts and does not authorize writing into comments, and pages_read_user_content only reads them. Without pages_manage_engagement the reply cannot be sent, and our task records a "missing permission" state and asks the person to reconnect rather than failing silently.

Note for the reviewer on the screencast: Socialyfy makes these API calls server-side. Publishing, analytics collection and the comment automations run in background workers using the access token stored when the user connected their account, so no Meta login dialog is on screen at the moment the API call is made. The recording therefore shows the user granting this permission first, and then the feature that permission enables.

Screencast — record this fresh, on its own

  1. Start the recording on the signed-out login page. Go to https://socialyfy.com/login. You will see the Socialyfy logo, an Email field showing the placeholder you@example.com, a Password field showing dots, and a dark Sign in button beneath them. Begin recording before you type anything.
  2. Sign in. Type akshats@fealtytechnologies.com into Email and the password into Password, then click Sign in. The page redirects to /dashboard/ and the left sidebar appears with Today, Approvals, Chat Studio, Inbox, Statement and Analytics at the top.
  3. Open the platform settings. In the left sidebar click Settings (the gear, near the bottom) to expand it, then click Platforms. The page shows a card headed Connections with the subtitle “The social accounts your approved posts go out to.” and one row per network: LinkedIn, Threads, Twitter / X, Instagram and Facebook.
  4. Disconnect first, so the grant is recorded from scratch. On the Facebook row click Disconnect (right-hand side, next to the green “Connected”). A confirmation dialog appears — confirm it. The row now shows a CONNECT button instead.
  5. Start the Meta login flow. Click CONNECT on the Facebook row. A Meta popup window opens on top of Socialyfy. Do not resize or minimise it — the whole dialog must stay in frame.
  6. Step through Meta's dialog without skipping a screen. Continue as yourself, choose the Mediflow Page when Meta asks which Pages to use, and when the permissions screen appears stop and hold for at least four seconds so that pages_manage_engagement is readable on camera. Add a caption naming it. This is requirement 2 on your rejection notice — “a user granting app access to the permission”.
  7. Finish and return. Click through Save and then Done. The popup closes by itself and the Facebook row in Socialyfy flips back to green Connected with the Page name Mediflow beside it.
  8. Open the composer. In the sidebar click Content to expand the group, then New Post. The page is headed New post with the subtitle “Socialyfy writes it in your brand voice…”.
  9. Pick the platform. Under Platforms click the Facebook chip so it is the only one highlighted. The hint below reads “Pick one or more. Each gets its own draft…”, and a per-platform character counter appears on the right.
  10. Write the post yourself. Scroll to Or write it yourself and click into the Your post box (placeholder “Write your post…”). Type New season list is out. Comment below for prices.. The character counter updates as you type.
  11. Publish immediately. Leave Schedule for (optional) empty — the hint underneath says “Leave empty to publish immediately.” — and the button at the bottom reads Publish now rather than “Schedule post”. Click it. A green toast confirms, and the credit figure in the top-right corner drops.
  12. Open the rules screen. In the sidebar click Engagement, then Auto-Replies. At the top you see two counters, Active rules and Total triggers, and below them a form headed Create a new rule.
  13. Fill the rule in on camera — do not paste it. The reviewer needs to see a human writing this text. Name: Price questions. Platform: choose Facebook from the dropdown (it defaults to “All platforms”). Scope: leave it on All posts (global). Keywords (comma-separated): price, pricing, how much, cost. Reply text: Thanks for asking! Our full price list is on our website.. Leave the Enabled toggle on.
  14. Save it. Click Create rule. A toast appears reading “Rule is live — 50 credits charged for the next 30 days.” and the rule now appears under Your rules with a green Active chip, its keywords listed, and Triggers: 0 / Never fired.
  15. Comment from a different account. Open the Mediflow post in a second tab, signed in to Facebook as an account that is neither the Page nor the admin who connected it, and leave a top-level comment: How much is this? (A reply to someone else's comment will be skipped by design and the video will show nothing happening.)
  16. Stay on the Facebook post and do not cut. Within about thirty seconds the Page's own reply appears indented beneath your comment, word for word the text you typed into the rule. Caption it: “public reply, posted by the Page, using the text the business wrote.”
  17. Close the loop inside the app. Return to Socialyfy, still recording, and show the rule under Your rules now reading Triggers: 1 with a Last fired timestamp, and the entry under Recent events marked Sent.
  18. Stop recording.
Do not open the Auto-DMs screen anywhere in this recording, and never show a Messenger inbox. That is exactly what caused the rejection: the reviewer saw a private message and credited it to pages_messaging. This video must contain the public reply and nothing else.
instagram_business_content_publishApproved
Socialyfy is a social media management tool. This permission powers the core feature of the product for accounts connected with Instagram Login: publishing the business's own content to its own Instagram professional account.

How we use the permission: the person drafts or generates a post inside Socialyfy, reviews the caption and image, and explicitly approves it on the Approvals screen - nothing reaches Instagram without that approval click. On approval, or at the scheduled time they chose, we run the standard two-step flow, POST /{ig-user-id}/media to create the container followed by POST /{ig-user-id}/media_publish, for images, videos and carousels. We store the returned media id so we can report on the post afterwards and so our comment-response rules can recognise it later.

How it adds value: the business plans a week or a month of content in one calendar, across Instagram and its other networks, and each item goes out at the time they chose without anyone having to open the app at 9am.

Why it is necessary: this is the only permission that authorizes organic publishing on the Instagram Login token family - it is the direct-connect equivalent of instagram_content_publish. Without it the connection is read-only and the main reason people connect Instagram disappears. We publish only content the person approved, only to the account they connected themselves.

Note for the reviewer on the screencast: Socialyfy makes these API calls server-side. Publishing, analytics collection and the comment automations run in background workers using the access token stored when the user connected their account, so no Meta login dialog is on screen at the moment the API call is made. The recording therefore shows the user granting this permission first, and then the feature that permission enables.

Screencast — record this fresh, on its own

  1. Start the recording on the signed-out login page. Go to https://socialyfy.com/login. You will see the Socialyfy logo, an Email field showing the placeholder you@example.com, a Password field showing dots, and a dark Sign in button beneath them. Begin recording before you type anything.
  2. Sign in. Type akshats@fealtytechnologies.com into Email and the password into Password, then click Sign in. The page redirects to /dashboard/ and the left sidebar appears with Today, Approvals, Chat Studio, Inbox, Statement and Analytics at the top.
  3. Open the platform settings. In the left sidebar click Settings, then Platforms. Find the Instagram row inside the Connections card — it shows an “Awaiting Meta review” badge and the connected handle myselfakshatsharma.
  4. Disconnect first. Click Disconnect on the Instagram row and confirm. The row changes to a CONNECT button.
  5. Choose the Instagram Login flow — this matters. Click CONNECT. A chooser dialog appears offering two ways to connect. Pick “Log in with Instagram”, not the Facebook option. Caption this step: these permissions exist only on the Instagram Login flow. Picking the wrong one produces a connection that cannot use this permission at all.
  6. Step through the Instagram dialog. A popup opens on instagram.com asking you to log in and then to allow Socialyfy. When the permissions list appears, hold for at least four seconds so instagram_business_content_publish is legible, and caption it. Then click Allow.
  7. Return to Socialyfy. The popup closes and the Instagram row shows green Connected with the account handle beside it.
  8. Open the composer. In the sidebar click Content to expand the group, then New Post. The page is headed New post with the subtitle “Socialyfy writes it in your brand voice…”.
  9. Pick the platform. Under Platforms click the Instagram chip so it is the only one highlighted. The hint below reads “Pick one or more. Each gets its own draft…”, and a per-platform character counter appears on the right.
  10. Write the post yourself. Scroll to Or write it yourself and click into the Your post box (placeholder “Write your post…”). Type New arrivals just landed this week.. The character counter updates as you type.
  11. Attach the image Instagram requires. Under the Image (required for Instagram) heading you will see three buttons — Generate with AI, Upload image and Choose from library — and a red line reading “Instagram requires an image to publish.” Click Generate with AI. The button label changes to Generating… and a progress panel appears; after roughly a minute the generated image renders in place and the red line disappears.
  12. Publish immediately. Leave Schedule for (optional) empty — the hint underneath says “Leave empty to publish immediately.” — and the button at the bottom reads Publish now rather than “Schedule post”. Click it. A green toast confirms, and the credit figure in the top-right corner drops.
  13. Show it live on Instagram. Open Instagram in a second tab and go to the connected account's profile. The new post is at the top of the grid. Open it and hold so the reviewer can compare the caption and the image against what they just watched you create in Socialyfy.
  14. Stop recording.
This recording must contain publishing and nothing else — no rules, no comments, no DMs, no analytics. Those belong to the other three instagram_business_* permissions, and sharing one file between them is what sank round one.
instagram_business_manage_commentsApproved
Socialyfy is a social media management tool. This permission is used for exactly one feature: a public reply to a comment left on the business's own Instagram post.

How we use the permission: in Socialyfy the person opens the Auto Replies screen and creates a rule in their own words. They choose a trigger word and they type the reply text themselves at that moment; nothing is generated or altered at send time. We subscribe the account to the comments webhook, and when a comment containing that trigger word arrives we read it and post the reply they wrote, verbatim, with POST /{comment-id}/replies. We reply at most once per comment, we skip comments made by the account itself and replies to other comments, and we act only on posts published through Socialyfy.

How it adds value: a small business misses comments because nobody is watching the app all day. The person writes the answer to a common question once, and every future asker gets it publicly within seconds, where other interested people can read it too.

Why it is necessary: reading the comment text and posting the reply both require this permission. Without it the rule cannot fire, and our task records a "missing permission" state and asks the person to reconnect rather than failing opaquely.

Reviewer testing: sign in to Socialyfy at https://socialyfy.com/login with the email akshats@fealtytechnologies.com and the password Akshat@123, then open "Auto Replies" in the left navigation. The rule listed there shows the trigger word the business chose, the exact reply text they typed, and the Instagram post it applies to. Open that post from any Instagram account other than the connected one and comment the trigger word; the public reply appears underneath within about 30 seconds, and the Auto Replies screen records it with a timestamp.

Note for the reviewer on the screencast: Socialyfy makes these API calls server-side. Publishing, analytics collection and the comment automations run in background workers using the access token stored when the user connected their account, so no Meta login dialog is on screen at the moment the API call is made. The recording therefore shows the user granting this permission first, and then the feature that permission enables.

Screencast — record this fresh, on its own

  1. Start the recording on the signed-out login page. Go to https://socialyfy.com/login. You will see the Socialyfy logo, an Email field showing the placeholder you@example.com, a Password field showing dots, and a dark Sign in button beneath them. Begin recording before you type anything.
  2. Sign in. Type akshats@fealtytechnologies.com into Email and the password into Password, then click Sign in. The page redirects to /dashboard/ and the left sidebar appears with Today, Approvals, Chat Studio, Inbox, Statement and Analytics at the top.
  3. Open the platform settings. In the left sidebar click Settings, then Platforms. Find the Instagram row inside the Connections card — it shows an “Awaiting Meta review” badge and the connected handle myselfakshatsharma.
  4. Disconnect first. Click Disconnect on the Instagram row and confirm. The row changes to a CONNECT button.
  5. Choose the Instagram Login flow — this matters. Click CONNECT. A chooser dialog appears offering two ways to connect. Pick “Log in with Instagram”, not the Facebook option. Caption this step: these permissions exist only on the Instagram Login flow. Picking the wrong one produces a connection that cannot use this permission at all.
  6. Step through the Instagram dialog. A popup opens on instagram.com asking you to log in and then to allow Socialyfy. When the permissions list appears, hold for at least four seconds so instagram_business_manage_comments is legible, and caption it. Then click Allow.
  7. Return to Socialyfy. The popup closes and the Instagram row shows green Connected with the account handle beside it.
  8. Open the composer. In the sidebar click Content to expand the group, then New Post. The page is headed New post with the subtitle “Socialyfy writes it in your brand voice…”.
  9. Pick the platform. Under Platforms click the Instagram chip so it is the only one highlighted. The hint below reads “Pick one or more. Each gets its own draft…”, and a per-platform character counter appears on the right.
  10. Write the post yourself. Scroll to Or write it yourself and click into the Your post box (placeholder “Write your post…”). Type New arrivals just landed. Ask us anything below.. The character counter updates as you type.
  11. Attach the image Instagram requires. Under the Image (required for Instagram) heading you will see three buttons — Generate with AI, Upload image and Choose from library — and a red line reading “Instagram requires an image to publish.” Click Generate with AI. The button label changes to Generating… and a progress panel appears; after roughly a minute the generated image renders in place and the red line disappears.
  12. Publish immediately. Leave Schedule for (optional) empty — the hint underneath says “Leave empty to publish immediately.” — and the button at the bottom reads Publish now rather than “Schedule post”. Click it. A green toast confirms, and the credit figure in the top-right corner drops.
  13. Open the rules screen. In the sidebar click Engagement, then Auto-Replies. At the top you see two counters, Active rules and Total triggers, and below them a form headed Create a new rule.
  14. Fill the rule in on camera — do not paste it. The reviewer needs to see a human writing this text. Name: Price questions. Platform: choose Instagram from the dropdown (it defaults to “All platforms”). Scope: leave it on All posts (global). Keywords (comma-separated): price, pricing, how much, cost. Reply text: Thanks for asking! Full prices are on our website.. Leave the Enabled toggle on.
  15. Save it. Click Create rule. A toast appears reading “Rule is live — 50 credits charged for the next 30 days.” and the rule now appears under Your rules with a green Active chip, its keywords listed, and Triggers: 0 / Never fired.
  16. Comment from a different Instagram account. Open the new post in a second tab while signed in as an Instagram account that is not the connected business account, and leave a top-level comment: How much is this?
  17. Stay on the post in one unbroken shot. Within about thirty seconds the business account's reply appears underneath your comment. Caption it: “public reply, posted under the comment.” Meta asks specifically to see this happen within thirty seconds, so do not cut away and back.
  18. Show the log. Return to Socialyfy and hold on the rule showing Triggers: 1 and the Recent events row marked Sent.
  19. Stop recording.
Never open the Auto-DMs screen or an Instagram inbox in this video. Round one showed the private message instead of the public reply, so Meta credited it to instagram_business_manage_messages and rejected this permission.
instagram_business_manage_insightsApproved
Socialyfy is a social media management tool that reports back to a business on how its own content performed.

How we use the permission: a scheduled job reads insights for the connected Instagram professional account - GET /{media-id}/insights for each post the person published through Socialyfy, plus the account-level follower count. We store those numbers and display them on the Analytics, Social and Analytics, Audience screens, in the per-post detail view, and in the daily performance summary the person receives. We request insights only for the account the person connected and only for its own media.

How it adds value: the person sees reach, impressions, likes, comments and saves for each Instagram post next to the same metrics from their other connected networks, with follower growth charted over time. That side-by-side view is what tells them which formats and posting times actually work, which is not something Instagram's own app shows across networks.

Why it is necessary: post and account insights are available only with this permission. Without it Socialyfy marks the account as unable to report metrics and renders every Instagram figure as a dash - we never substitute zeros, because a fabricated zero would mislead the person into thinking a post failed. Analytics is one of the two reasons people connect Instagram, so the connection loses half its value without it.

Note for the reviewer on the screencast: Socialyfy makes these API calls server-side. Publishing, analytics collection and the comment automations run in background workers using the access token stored when the user connected their account, so no Meta login dialog is on screen at the moment the API call is made. The recording therefore shows the user granting this permission first, and then the feature that permission enables.

Screencast — record this fresh, on its own

  1. Start the recording on the signed-out login page. Go to https://socialyfy.com/login. You will see the Socialyfy logo, an Email field showing the placeholder you@example.com, a Password field showing dots, and a dark Sign in button beneath them. Begin recording before you type anything.
  2. Sign in. Type akshats@fealtytechnologies.com into Email and the password into Password, then click Sign in. The page redirects to /dashboard/ and the left sidebar appears with Today, Approvals, Chat Studio, Inbox, Statement and Analytics at the top.
  3. Open the platform settings. In the left sidebar click Settings, then Platforms. Find the Instagram row inside the Connections card — it shows an “Awaiting Meta review” badge and the connected handle myselfakshatsharma.
  4. Disconnect first. Click Disconnect on the Instagram row and confirm. The row changes to a CONNECT button.
  5. Choose the Instagram Login flow — this matters. Click CONNECT. A chooser dialog appears offering two ways to connect. Pick “Log in with Instagram”, not the Facebook option. Caption this step: these permissions exist only on the Instagram Login flow. Picking the wrong one produces a connection that cannot use this permission at all.
  6. Step through the Instagram dialog. A popup opens on instagram.com asking you to log in and then to allow Socialyfy. When the permissions list appears, hold for at least four seconds so instagram_business_manage_insights is legible, and caption it. Then click Allow.
  7. Return to Socialyfy. The popup closes and the Instagram row shows green Connected with the account handle beside it.
  8. Open the composer. In the sidebar click Content to expand the group, then New Post. The page is headed New post with the subtitle “Socialyfy writes it in your brand voice…”.
  9. Pick the platform. Under Platforms click the Instagram chip so it is the only one highlighted. The hint below reads “Pick one or more. Each gets its own draft…”, and a per-platform character counter appears on the right.
  10. Write the post yourself. Scroll to Or write it yourself and click into the Your post box (placeholder “Write your post…”). Type A look inside the studio this week.. The character counter updates as you type.
  11. Attach the image Instagram requires. Under the Image (required for Instagram) heading you will see three buttons — Generate with AI, Upload image and Choose from library — and a red line reading “Instagram requires an image to publish.” Click Generate with AI. The button label changes to Generating… and a progress panel appears; after roughly a minute the generated image renders in place and the red line disappears.
  12. Publish immediately. Leave Schedule for (optional) empty — the hint underneath says “Leave empty to publish immediately.” — and the button at the bottom reads Publish now rather than “Schedule post”. Click it. A green toast confirms, and the credit figure in the top-right corner drops.
  13. Give the post something to measure. Open Instagram in a second tab, view the new post from two other accounts and like it from one of them.
  14. Wait before you film the numbers. Meta computes post insights in batches, so a post published seconds ago reports nothing and Socialyfy honestly shows a dash rather than inventing a zero. Pause the recording, wait about fifteen minutes, then resume.
  15. Open Analytics. Click Analytics in the sidebar. It opens on the Social tab with the Range dropdown on Last 30 days.
  16. Pull the numbers. Click Refresh metrics on the Per-platform card. The label changes to Refreshing…; when it settles, the Instagram row shows a post count and an impressions figure.
  17. Hold on the per-post detail. Scroll to Top posts (by engagement) and hold on the Instagram row with real values under IMPR, LIKES and CMTS. Caption each column as you point at it.
  18. Show the account-level side too. Click the Follower growth tab in the row of tabs above the table. This is the same permission read at account level rather than per post.
  19. Stop recording.
If a column still shows a dash, the numbers are not in yet — wait longer and click Refresh metrics again before filming. A dash on camera reads as a broken feature. And this recording must contain no comment automation at all.
threads_read_repliesApproved
Socialyfy is a social media management tool. This permission is used for one feature: letting a business answer replies to its own threads with text the business wrote itself.

How we use the permission: it is the read half of that feature. We subscribe to the replies webhook under the moderate topic, and this permission is what those events are delivered under. When someone replies to a thread the business published through Socialyfy, we read the reply text and the identity of the thread it belongs to, then check it against the keyword rules the person created on the Auto Replies screen. If it matches, we post the answer they wrote; if it does not, we do nothing and the reply is not stored.

How it adds value: replies on Threads are easy to miss, and a question left unanswered is a lost customer. Reading them is what lets Socialyfy answer common questions in seconds, in the person's own words, without them watching the app all day.

Why it is necessary: without threads_read_replies we do not receive the replies webhook and cannot read the reply, so the auto-reply feature cannot fire at all - there is nothing to match a rule against. We read replies only on threads that were published through Socialyfy by the connected profile, never on other people's threads.

What the screencast proves: a reply containing the trigger word is answered within seconds with nobody touching Socialyfy, and a reply without the trigger word is not answered at all. The app could only tell those two apart by receiving and reading the text of each reply, which is what this permission authorizes.

Note for the reviewer on the screencast: Socialyfy makes these API calls server-side. Publishing, analytics collection and the comment automations run in background workers using the access token stored when the user connected their account, so no Meta login dialog is on screen at the moment the API call is made. The recording therefore shows the user granting this permission first, and then the feature that permission enables.

Screencast — record this fresh, on its own

  1. Start the recording on the signed-out login page. Go to https://socialyfy.com/login. You will see the Socialyfy logo, an Email field showing the placeholder you@example.com, a Password field showing dots, and a dark Sign in button beneath them. Begin recording before you type anything.
  2. Sign in. Type akshats@fealtytechnologies.com into Email and the password into Password, then click Sign in. The page redirects to /dashboard/ and the left sidebar appears with Today, Approvals, Chat Studio, Inbox, Statement and Analytics at the top.
  3. Open the platform settings. Click Settings then Platforms in the sidebar, and find the Threads row in the Connections card.
  4. Disconnect, then connect. Click Disconnect and confirm; the row becomes a CONNECT button. Click it — a Threads authorization popup opens.
  5. Hold on the permission screen. When Threads lists what Socialyfy is asking for, stop for at least four seconds so threads_read_replies is readable, and caption it. Then authorize. The popup closes and the row shows green Connected with the profile's @username.
  6. Open the composer. In the sidebar click Content to expand the group, then New Post. The page is headed New post with the subtitle “Socialyfy writes it in your brand voice…”.
  7. Pick the platform. Under Platforms click the Threads chip so it is the only one highlighted. The hint below reads “Pick one or more. Each gets its own draft…”, and a per-platform character counter appears on the right.
  8. Write the post yourself. Scroll to Or write it yourself and click into the Your post box (placeholder “Write your post…”). Type Ask us anything about pricing in the replies.. The character counter updates as you type.
  9. Publish immediately. Leave Schedule for (optional) empty — the hint underneath says “Leave empty to publish immediately.” — and the button at the bottom reads Publish now rather than “Schedule post”. Click it. A green toast confirms, and the credit figure in the top-right corner drops.
  10. Open the rules screen. In the sidebar click Engagement, then Auto-Replies. At the top you see two counters, Active rules and Total triggers, and below them a form headed Create a new rule.
  11. Fill the rule in on camera — do not paste it. The reviewer needs to see a human writing this text. Name: Price questions. Platform: choose Threads from the dropdown (it defaults to “All platforms”). Scope: leave it on All posts (global). Keywords (comma-separated): price, pricing, how much, cost. Reply text: Thanks for asking! Our full price list is on our website.. Leave the Enabled toggle on.
  12. Save it. Click Create rule. A toast appears reading “Rule is live — 50 credits charged for the next 30 days.” and the rule now appears under Your rules with a green Active chip, its keywords listed, and Triggers: 0 / Never fired.
  13. Negative control first — this is the important half. Open the new thread in a second tab as a different Threads account and reply Nice photo! Stay on the thread for a full minute and show that nothing happens. Caption: “no trigger word — the app received this reply, read it, and chose not to answer.”
  14. Now the positive case, in the same unbroken shot. From the same account reply How much is this? Within about thirty seconds the connected profile's answer appears underneath it.
  15. Caption the contrast explicitly. Say on screen: “Socialyfy was not touched between these two replies. It could only tell them apart by reading the text of each one.” This sentence is what demonstrates a read permission that has no visible artifact of its own.
  16. Stop recording.
The negative control is the whole point of this take. Round one proved this permission with the rule's internal “Triggers” counter — an app-side number a reviewer cannot verify. Showing the app discriminating between two replies is impossible unless it read both.

First submitted in round 2 — approved

whatsapp_business_messagingApproved
Socialyfy is a social media management tool. WhatsApp is one of four optional notification channels a user can connect - alongside Telegram, Slack and Discord - so the app can reach them where they already are.

How we use the permission: messages are sent with POST /{phone-number-id}/messages, from our own WhatsApp Business number to a user who has connected their own number to their Socialyfy workspace. We send four things, all of them about that user's own account: a draft awaiting their approval (with Approve and Skip buttons they tap in the chat), their daily performance summary, an alert when a scheduled post fails to publish, and an alert when their credit balance runs low. We also receive their replies, so they can approve a draft or ask the assistant a question without opening the web app. A reply can be typed or sent as a WhatsApp voice note. When a voice note arrives we read it with GET /{media-id} and download the audio from the short-lived URL that call returns, transcribe it, and then handle the transcript exactly as we would the identical typed message - same assistant, same workspace, same actions, and anything that would be published still waits for that user's explicit approval. The audio is used for that transcription and nothing else.

How it adds value: someone running a small business is not sitting in a dashboard all day. A draft that needs approving reaches them in an app they already have open, and one tap publishes it. Without this channel, scheduled content waits unseen and posts go out late or not at all. Accepting voice notes matters for the same reason: many of these users are on a phone, often in Hindi or Arabic, and holding the mic button is the difference between answering the assistant and leaving it unanswered.

Why it is necessary: this is the only permission that authorizes sending or receiving WhatsApp messages, so the channel cannot exist without it. We message only numbers whose owner connected them to their own workspace and proved ownership - either with a one-time code we send to that number, or by messaging our business number first from the number itself. Disconnecting the channel in Settings stops every message immediately. We never message numbers that have not opted in, and we send no marketing or bulk messages. We do not share this data with third parties for their own purposes; the speech-to-text service that transcribes voice notes processes the audio solely on our instruction, to return the transcript, and for no purpose of its own.

Reviewer testing: sign in to Socialyfy at https://socialyfy.com/login with the email akshats@fealtytechnologies.com and the password Akshat@123, then open Settings, then Platforms, and scroll to "Messaging channels". The WhatsApp card shows the connected number. To see the opt-in yourself, click "Change number", enter your own WhatsApp number and complete the verification.

Note for the reviewer on the screencast: Socialyfy makes these API calls server-side. Publishing, analytics collection and the comment automations run in background workers using the access token stored when the user connected their account, so no Meta login dialog is on screen at the moment the API call is made. The recording therefore shows the user granting this permission first, and then the feature that permission enables.

Screencast — record this fresh, on its own

  1. Start the recording on the signed-out login page. Go to https://socialyfy.com/login. You will see the Socialyfy logo, an Email field showing the placeholder you@example.com, a Password field showing dots, and a dark Sign in button beneath them. Begin recording before you type anything.
  2. Sign in. Type akshats@fealtytechnologies.com into Email and the password into Password, then click Sign in. The page redirects to /dashboard/ and the left sidebar appears with Today, Approvals, Chat Studio, Inbox, Statement and Analytics at the top.
  3. Open the messaging channels. Click Settings then Platforms in the sidebar, and scroll past the Connections card to Messaging channels, subtitled “Where Socialyfy messages you — daily summaries, approval requests and post updates.” You will see four cards: WhatsApp, Telegram, Slack and Discord.
  4. Start the opt-in. On the WhatsApp card click Change number. A field appears labelled “Enter your WhatsApp number to connect” with the placeholder +14155550123.
  5. Enter your own number and connect. Type your WhatsApp number and click Connect. Caption this step: “the user is choosing to receive these messages.” Consent is what Meta is assessing here, more than delivery.
  6. Verify, using whichever path appears. Either a six-box code field appears with “Code sent. Check WhatsApp.” — enter the code from your phone and it submits itself — or use Or connect by messaging us: scan the QR code with your phone, or tap Open in WhatsApp, and send the pre-written message that appears.
  7. Show it connected. The card changes to Connected — +… with your number displayed.
  8. Open the composer. In the sidebar click Content to expand the group, then New Post. The page is headed New post with the subtitle “Socialyfy writes it in your brand voice…”.
  9. Pick the platform. Under Platforms click the Facebook chip so it is the only one highlighted. The hint below reads “Pick one or more. Each gets its own draft…”, and a per-platform character counter appears on the right.
  10. Write the post yourself. Scroll to Or write it yourself and click into the Your post box (placeholder “Write your post…”). Type Testing our approval notifications.. The character counter updates as you type.
  11. Publish immediately. Leave Schedule for (optional) empty — the hint underneath says “Leave empty to publish immediately.” — and the button at the bottom reads Publish now rather than “Schedule post”. Click it. A green toast confirms, and the credit figure in the top-right corner drops.
  12. Show the message arriving on your phone. Point the camera at your phone, or share the phone screen. A WhatsApp message arrives from the business number containing the draft and two buttons, Approve and Skip.
  13. Tap Approve in WhatsApp. The chat confirms the action.
  14. Show the effect back in the app. Return to Socialyfy and open Approvals in the sidebar — the draft has moved out of the pending queue. The tap in WhatsApp drove it.
  15. Show the user can stop it. Go back to Settings → Platforms → Messaging channels and click Disconnect on the WhatsApp card. Caption: “the user can end these messages at any time.”
  16. Stop recording.
Record the opt-in and the disconnect in the same take. Meta's messaging reviews turn on consent: they want to see a person choosing to receive these messages and able to stop them — not merely that a message was delivered.
whatsapp_business_managementApproved
Socialyfy is a social media management tool that offers WhatsApp as one of four optional notification channels.

How we use the permission: it covers the account-management side of that channel rather than the sending. We read our own WhatsApp Business Account and its phone number (GET /{phone-number-id}) to resolve and display the business number a user is about to message - the connect screen shows it to them before they opt in - and it is the permission under which the `messages` webhook subscription is registered, so a user's replies reach the app at all. Our own diagnostics tooling also inspects the token's granular scopes when an administrator is troubleshooting a delivery failure.

How it adds value: it is what makes the connect step honest. The user sees the exact business number they will be messaging before they send anything, instead of being asked to trust an unnamed sender. It is also what keeps inbound replies working, so approving a draft from the chat actually reaches their account.

Why it is necessary: without it we cannot read our own phone-number configuration or maintain the webhook subscription - the connect screen cannot name the sender, and no reply a user sends is ever delivered. We use it only against our own WhatsApp Business Account. Socialyfy operates a single business number and never accesses, manages, or messages on behalf of any other business's WhatsApp Business Account; there is no Embedded Signup flow and no per-customer WABA in this product.

Note for the reviewer on the screencast: Socialyfy makes these API calls server-side. Publishing, analytics collection and the comment automations run in background workers using the access token stored when the user connected their account, so no Meta login dialog is on screen at the moment the API call is made. The recording therefore shows the user granting this permission first, and then the feature that permission enables.

Screencast — record this fresh, on its own

  1. Start the recording on the signed-out login page. Go to https://socialyfy.com/login. You will see the Socialyfy logo, an Email field showing the placeholder you@example.com, a Password field showing dots, and a dark Sign in button beneath them. Begin recording before you type anything.
  2. Sign in. Type akshats@fealtytechnologies.com into Email and the password into Password, then click Sign in. The page redirects to /dashboard/ and the left sidebar appears with Today, Approvals, Chat Studio, Inbox, Statement and Analytics at the top.
  3. Open the messaging channels. Click Settings then Platforms, and scroll to the Messaging channels section. Find the WhatsApp card.
  4. Open the connect panel. Click Change number. The panel expands to show the number field and, below it, a section headed Or connect by messaging us with a QR code.
  5. Hold on the business number — this is the permission. Underneath the QR code is a line reading “You'll be messaging +…”. Hold on it for several seconds and caption: “this number is read from our own WhatsApp Business Account configuration through whatsapp_business_management. The user sees exactly who they are about to message before they opt in.”
  6. Send the inbound message. Scan the QR code with your phone, or tap Open in WhatsApp. WhatsApp opens with a short message already composed. Send it.
  7. Do not touch the Socialyfy screen — let it change by itself. Keep the browser in frame. Within a few seconds the WhatsApp card flips to Connected on its own, with no code typed and no button clicked.
  8. Caption what that proved. Say on screen: “nothing was entered in the browser. The card connected because our inbound message was delivered to the app through the messages webhook subscription, which is the other half of this permission.”
  9. Stop recording.
This take is deliberately not about sending — that is whatsapp_business_messaging, and mixing the two is the mistake that lost six permissions in round one. The two things to capture here are the business number appearing before opt-in, and the card connecting itself off an inbound message.

Meta Ads — Marketing API

The organic sections above cover posting to Pages, Instagram and Threads, reading their insights and answering comments. This section is a separate product surface: creating and running paid campaigns on a customer's own Meta ad account through the Marketing API. It has its own use case, permissions, login configuration and API version, and it needs an ad account, which is not the same thing as a Facebook Page. Code: socialyfy/backend/services/ads_provider/meta_ads.py, reached through /api/ad-connections and /api/ad-campaigns. Publishing is admin-gated (socialyfy/CLAUDE.md #16). The Social Gateway has no ads code.

Permissions the ads flow requests

PermissionWhat consumes itReview status
ads_management Every write: POST /act_{id}/campaigns, /adsets, /adcreatives, /ads, and POST /{campaign-id} for ACTIVE / PAUSED / DELETED. Required: a grant without it is refused at connect. Round 3, Advanced access
ads_read GET /act_{id}/insights with level=campaign and time_increment=1, run only by the hourly tasks/sync_ad_insights.py sweep (35 past the hour), never on a page load. Required: refused at connect without it. Round 3, Advanced access
business_management Ad accounts held in a Business Portfolio, listed by GET /me/adaccounts (the business field is stored as the connection's business_id). Meta lists it as required for every Marketing API use case. Round 3, Advanced access (never submitted before)
pages_manage_ads The creative: object_story_spec.page_id names the Page the ad runs as. Without it Meta answers (#200) and _domain_error says the Page is the problem. Round 3, Advanced access
pages_show_list GET /me/accounts: the Page offered as the ad identity. The first Page wins, and there is no picker yet. Approved (organic)
pages_read_engagement The Page's fields on that read, including instagram_business_account (the Instagram identity). Approved (organic)

The ads permissions and the organic ones live in separate login configurations (META_ADS_LOGIN_CONFIG_ID vs FACEBOOK_LOGIN_CONFIG_ID), so the publishing connect never asks for ad accounts and the ads connect never asks to publish. The Marketing API Access Tier feature (Full access) sits on top of ads_management / ads_read. Without it the whole flow works only for people with a role on the app.

An ad account is not a Facebook Page. Meta requires both to serve an ad: the ad account pays, and the Page is the identity the ad appears as. An Instagram placement additionally needs the Instagram account, sent as instagram_user_id. The ad_platform_connections row stores all three: the column is still called instagram_actor_id, it holds the same value, and nothing was migrated. The connect flow offers the first Page the person administers. Treating the Page id as the ad account id is the most common way this integration gets wired up wrong.

Configuring the app

  1. Add the use case Create & manage ads with Marketing API to the app (App dashboard → Use cases → Add use case), then add pages_manage_ads under its Customize page. There is no longer a separate “Marketing API product” to add. Facebook Login for Business and Webhooks come with the use case.
  2. Create a Facebook Login for Business configuration for ads: token type User access token, assets Ad accounts + Pages, and the six permissions above. Put its id in META_ADS_LOGIN_CONFIG_ID. With it set, MetaAdsProvider.authorize_url sends config_id= and no scope=, exactly as social_account_service._meta_authorize_url does for the organic connect. Blank means the classic scope= dialog built from META_ADS_OAUTH_SCOPES.
  3. Register the redirect URI exactly: <OAUTH_CALLBACK_BASE_URL>/api/ad-connections/callback/meta_ads. It is derived in config/settings.py (META_ADS_REDIRECT_URI). There is no separate env var to keep in sync, and a mismatch here is the most common cause of a callback that returns to an error page with no detail.
  4. Either reuse the main app (leave META_ADS_APP_ID blank and Socialyfy falls back to META_APP_ID), or point the ads flow at a second app by setting META_ADS_APP_ID and META_ADS_APP_SECRET. The secret is keyed off whichever app id won, so setting only one of the pair fails authentication in a way that reads as a permissions problem.

Requested is not granted — ads too

exchange_code trades the code for a short-lived token, then for the ~60-day one, then reads GET /me/permissions and stores only the granted rows in ad_platform_connections.scopes. It falls back to the requested list only when Meta does not answer, which is the organic flows' contract. A grant without ads_management or ads_read raises ad_permission_missing before any connection is stored (the popup shows the localized message), because a connection that can neither create nor read would only fail later. refresh() carries the recorded scopes over and never re-stamps the settings string.

What can be tested before App Review

Every permission works in development mode (Limited access) for people who hold a role on the app, such as an admin, developer or tester, against ad accounts and Pages those people can already reach. That is enough to run the whole flow end to end: connect, choose the account, write a campaign with its ad on Ad campaigns, approve it in the admin dashboard, publish it, and watch the insights sweep fill in. It is also how each permission gets the test call Meta requires before it can be requested. Development mode does not allow any account outside that list, which is what Advanced access plus the Access Tier's Full access are for. In development mode Meta's error 270 means the token's user is not an admin of both the app and the ad account.

Environment variables

VariableRequired?Notes
META_ADS_APP_IDOptionalFalls back to META_APP_ID.
META_ADS_APP_SECRETWith the aboveFalls back to META_APP_SECRET.
META_ADS_LOGIN_CONFIG_IDYes, on a Business appThe ads Login for Business configuration. Keep it separate from FACEBOOK_LOGIN_CONFIG_ID.
META_ADS_OAUTH_SCOPESHas a defaultads_management,ads_read,business_management,pages_show_list,pages_read_engagement,pages_manage_ads. Ignored when the config id is set.
META_ADS_GRAPH_VERSIONHas a defaultv25.0, available until 23 Feb 2027. Its own knob: see “API version” below.
AD_INSIGHTS_RECONCILE_DAYSHas a defaultHow far back each sync re-reads (7).

All of them are optional. They are deliberately absent from the boot guard in services/security_service.check_runtime_secrets(): a deployment whose customers never advertise must still start. With the app id and secret blank, services/ads_provider.get() returns a stub that raises ProviderNotConfigured, the routes answer 503 provider_not_configured, and the Meta Ads card on /ads/connections says “Not available on this server” instead of offering Connect.

API version

The ads provider calls https://graph.facebook.com/<META_ADS_GRAPH_VERSION> (ads_graph_base()), not META_GRAPH_VERSION. It used to share the organic knob, and Marketing API versions retire far sooner than Graph ones: v23 retired on 9 Jun 2026 and v24 on 10 Nov 2026 while the organic side stayed on v23, so every ads call ran on a dead version. A call on a retired version fails with an error that names something else. Before bumping, read the Marketing API changelog for the calls listed in the permission table. v24 to v25 changed none of them.

The ad a campaign carries

Ad campaigns → New campaign asks for the account, name, objective and daily budget. For a Meta account it also shows The ad: link (https only), primary text, optional headline, button (LEARN_MORE, SHOP_NOW, SIGN_UP, CONTACT_US, GET_QUOTE, SUBSCRIBE), countries and an 18–65 age range. It posts the tree as nodes: an ad_set (objective + targeting), then a creative and an ad under it, in that order, so the creative exists before the ad points at it. The same targeting and creative are kept on the campaign row, so editing either after approval sends the campaign back to review. No countries typed means the workspace's own country. Before that form existed, a published Meta campaign had no ad set, creative or ad, and so nothing to deliver.

Token lifetime

Meta has no refresh-token grant. The connect flow immediately trades the short-lived code for a ~60-day long-lived token, and MetaAdsProvider.refresh() re-exchanges a still-valid token for a fresh one. Once a token has genuinely expired the customer must reconnect: the connection row is marked revoked, and the UI asks for exactly that rather than retrying forever. Disconnect deletes the connection and leaves its campaigns with no connection (they keep running on Meta). Reconnecting the same account creates a new row, so those campaigns can no longer be paused from Socialyfy.

Troubleshooting

SymptomCause
Connect popup ends with “This connection can't manage ads on that account…”ad_permission_missing at connect: /me/permissions shows no ads_management or ads_read. The person declined it, or the app is in development mode and they hold no role, or the login configuration does not list it.
Graph error 190 / 102 / 463The grant is gone. Socialyfy marks the connection revoked and shows "reconnect". It does not surface the code.
Graph error 200 or 10The token lacks a permission for that object. If the message mentions the Page, it is pages_manage_ads, or the person cannot advertise for that Page. Otherwise it is ads_management on the ad account.
Graph error 270Development mode: the token's user must be an admin of both the app and the ad account.
Every ads call fails with an error that makes no senseMETA_ADS_GRAPH_VERSION points at a retired Marketing API version. Check the changelog's “available until” dates.
Ad set refused: “enable or disable the Advantage+ audience feature”Since v23 a narrowed audience must state targeting_automation.advantage_audience. _targeting_spec always sends 0, so this means a hand-rolled call left it out.
Creative refused for instagram_actor_idDeprecated for every version. The field is instagram_user_id, which is what the provider sends.
Campaign create returns 400 with no obvious fieldspecial_ad_categories is required, not optional. Socialyfy always sends []; a hand-rolled call that omits it fails here.
Ad set rejected for the optimization goalThe goal must agree with the campaign objective. The pairing is a platform rule, mapped explicitly in _OPTIMIZATION_BY_OBJECTIVE.
A leads or sales campaign fails at the ad setKnown gap: OUTCOME_LEADS needs a lead form and a promoted_object, and OUTCOME_SALES needs a pixel. Neither is collected yet. Use traffic, awareness or engagement.
Ad create fails with no creativeMeta's ad references its creative by id, and the creative is a sibling created just before it. The publisher hands the id forward; a manual replay must do the same.
Legacy objective rejectedCONVERSIONS, BRAND_AWARENESS and the rest of the pre-2022 set are not accepted on new campaigns. Use the ODAX OUTCOME_* values.
Insights come back empty for a campaign that is spendingMeta reports on its own clock, and its ad review can hold delivery for hours. AD_INSIGHTS_RECONCILE_DAYS exists because recent days are restated.

Official references: Marketing API · Authorization and access levels · Marketing API changelog · object_story_spec · Insights API · Facebook Login for Business · App Review. The Google half of this integration is documented separately in socialyfy/docs/platforms/GOOGLE_ADS_SETUP.html.

Engineering reference

Everything above is written for Meta's reviewers. This section is written for whoever maintains the integration, and carries the material that previously lived in the markdown version of this document.

Where the scope strings live

The constants are declared in socialyfy/backend/config/settings.py and mirrored as documentation in socialyfy/backend/.env.example. There are no hard-coded scope lists in services/ or routes/. Change a scope there and update this page in the same commit.

ConstantProducts it covers
FACEBOOK_OAUTH_SCOPESFacebook Pages
INSTAGRAM_OAUTH_SCOPESInstagram via Facebook Login
INSTAGRAM_DIRECT_OAUTH_SCOPESInstagram API with Instagram Login
THREADS_OAUTH_SCOPESThreads (space-separated, unlike the others)
INSTAGRAM_DELETE_SCOPEInstagram post deletion — instagram_manage_contents, appended to the Instagram request (empty = not granted to the app)
THREADS_DELETE_SCOPEThreads post deletion — threads_delete, appended to the Threads request. Empty until Meta approves it
none — static tokenWhatsApp Cloud API
META_ADS_OAUTH_SCOPESMeta Ads (Marketing API). Documentation only once META_ADS_LOGIN_CONFIG_ID is set. Granted scopes land on ad_platform_connections.scopes, not social_accounts. See “Meta Ads — Marketing API” above.

Requested is not granted

The constants are what we ask for. social_accounts.scopes is what Meta granted, and that column — never the constant — is what every capability gate reads. All four flows ask the provider and fall back to the requested list only when Meta does not answer.

FlowWhere scopes is written from
FacebookGET /me/permissions, granted entries only
Instagram — Facebook Loginthe same helper, on the long-lived user token
Instagram — Instagram Loginthe permissions field on the token exchange
Threadsthe permissions field on the token exchange

The row is written only at connect and reconnect, so adding a scope to settings never widens a live token. The two Instagram normalisers are deliberately separate: Facebook Login grants the instagram_* names and Instagram Login the instagram_business_* ones, so a shared helper would silently mis-report one of them. Storing the settings string on a row is the bug this pattern exists to prevent — it matters doubly under Facebook Login for Business, where a configuration id makes the dialog ignore scope= entirely and can grant permissions the settings string never mentions.

Webhooks — three consumed, and where to configure them

Meta's dashboard offers around nine webhook objects; this app consumes three. Subscribing to one with no handler is harmless but pointless, and leaving one of these three blank means that feature silently never runs — with nothing logged anywhere, because the delivery never happens. Dashboard path: App → Use cases → Customize → Webhooks.

ObjectCallbackFieldVerify tokenDrives
Page/webhooks/meta/facebookfeedMETA_WEBHOOK_VERIFY_TOKENFacebook auto-reply + auto-DM
Instagram/webhooks/meta/instagramcommentsMETA_WEBHOOK_VERIFY_TOKENInstagram auto-reply + auto-DM
WhatsApp Business Account/webhooks/whatsappmessagesWHATSAPP_VERIFY_TOKENWhatsApp bot channel

The WhatsApp handshake uses a different verify token from the Meta-family receivers. Pasting the Meta one there fails the handshake with a 403 and the subscription cannot be saved — worth knowing before assuming the URL is wrong. Threads has its own receiver (/webhooks/meta/threads, field replies under the moderate topic) configured in its separate Meta app.

Two more settings live under Facebook Login for Business → Settings rather than the Webhooks list, and Meta requires both for review: the Deauthorize callback (/webhooks/meta/deauthorize) and the Data Deletion Request URL (/webhooks/meta/data-deletion).

A dashboard subscription is only half of it. Each Page and Instagram account must also be opted in via POST /{id}/subscribed_apps, which the connect flow fires. A Page fully opted in to an app that has no webhook configured reads as healthy on every per-account check and receives nothing.

Runbook: a rule that never fires

This is the one failure mode the automations cannot explain themselves. Everything downstream of the webhook logs why it skipped — but when Meta never delivers there is no request, no event row, no skip reason and no trigger count, so an armed, paid, matching rule looks exactly like a broken one. Work in order; each step gates the next.

  1. Look in the right container. Every auto-reply and auto-DM log line comes from celery-worker, not api. Watching the api logs alone can never show a skip reason. docker compose logs -f celery-worker | grep -E "auto_dm|auto_reply|comment_context"
  2. Ask Meta whether it will deliver at all. It reads subscribed_apps, /me and debug_token live and prints a problems array — an empty one means delivery is fine and the fault is downstream. docker compose exec api python scripts/diagnose_facebook_webhook.py --workspace-id <uuid>
  3. Repair an unsubscribed account — the usual culprit — with --fix, or the resubscribe endpoint. Idempotent, and unlike disconnect + reconnect it does not rotate the token.
  4. Confirm the callback is reachable, which no code can do. The receivers are mounted on both /webhooks/meta/{platform} and /api/webhooks/meta/{platform}; which one your deployment serves depends on the proxy. A single host forwarding only /api/* answers 404 on the bare path, so deliveries hit the CDN and never arrive. Curl the GET handshake on both and configure whichever echoes the challenge.
  5. Test the downstream half without waiting on Meta, using scripts/replay_facebook_webhook.py. It signs a synthetic delivery with the app secret, and sends a real DM when a rule matches — so it requires --confirm.
  6. Comment from a third-party account. A comment posted as the Page, or as the user who connected it, is dropped by the self-comment guard — an easy way to conclude the feature is broken while testing it.

Facebook analytics: two different failures

Tell them apart before touching anything.

SymptomMissing permissionRecorded status
Reach is a dash, likes and comments are real numbersread_insightspartial
Every column is a dashpages_read_user_contentno_scope

A partial row is not automatically a permission problem, and assuming it is has wasted a lot of time. Meta answers a retired metric name with error 100 before checking permissions, so a dead name looks identical to a missing scope. Read insights_error_class off the snapshot's raw column:

ClassMeaningWho fixes it
permissionthe token lacks read_insightsthe account owner, by reconnecting
unsupported_metricMeta retired the metric name we ask forus, by shipping a new name — reconnecting does nothing
othernetwork, throttlingusually nobody; it retries

This bit us in August 2026: every candidate metric name was dead, the UI told owners to reconnect, and the Page had read_insights the whole time. diagnose_facebook_webhook.py --probe-metrics now asks Meta about each candidate name in its own request and prints which are accepted, so the next rename is a reorder of the candidate list rather than another guess.

Post insights also lag publication. For the first minutes after publishing, Meta answers the insights call with an empty result and the UI shows a dash rather than inventing a zero — correct behaviour that looks identical to a missing permission. Clicking Refresh metrics once Meta has the number is what fills it in.

Deleting a published post (Approvals → Delete)

An editor can take down a post Socialyfy published, from Approvals → Workflow history, after a confirm dialog. One post per request; no AI, automation or bot can trigger it; the card is kept and marked deleted. Code: services/post_deletion_service.py (the claim, the confirm, the one retry) plus a delete_post() in each publisher in the Social Gateway (social_gateway/gateway/platform_services/, root CLAUDE.md #32), classified once by the gateway's meta_graph.delete_outcome.

PlatformCallPermissionSwitch
FacebookDELETE /{page-post-id}, Page tokenpages_manage_posts (already held)always on
Instagram — Facebook LoginDELETE /{ig-media-id} on graph.facebook.cominstagram_manage_contentsINSTAGRAM_DELETE_SCOPE
Instagram — Instagram Loginnone — Meta offers no media delete on graph.instagram.com—card says “delete it in the Instagram app”
ThreadsDELETE /{threads-media-id} on graph.threads.net; 100 per account per daythreads_deleteTHREADS_DELETE_SCOPE — empty until approved

Turning Threads on once Meta approves threads_delete: set THREADS_DELETE_SCOPE=threads_delete and restart. The Threads connect request then asks for it, and owners reconnect Threads so their row records the grant; until they do, the card asks them to. While the key is empty, Threads cards read “Delete permissions are not yet granted for this platform” and nothing extra is requested — an unapproved permission in the request can fail the whole connect dialog.

INSTAGRAM_LOGIN_CONFIG_ID is set in production, so the scope string is not what Meta reads. Under a Facebook Login for Business configuration the dialog ignores scope=; tick instagram_manage_contents in that configuration in the Meta dashboard as well, or no Instagram row will ever be granted it. Accounts connected before the permission was added show “Reconnect this account…” on their cards and a banner on the History tab.

A carousel deletes whole. We store the id media_publish / threads_publish returned — the parent album — never a child, and Meta cannot delete a single slide anyway (a test pins this). Ads posts cannot be deleted through this edge.

Deliberately not requested

Searched across the codebase, zero hits. Do not list these on a review submission:

catalog_management commerce_* leads_retrieval pages_manage_metadata instagram_manage_comments instagram_manage_messages email manage_app_solution whatsapp_business_manage_events

ads_management, ads_read, business_management and pages_manage_ads used to be on this list, with a note that the ads subsystem never called the Marketing API. That stopped being true when the Meta Ads provider shipped: they are this round's submission (see “Meta Ads — Marketing API” above). leads_retrieval stays off until lead ads are built. threads_delete left the list when THREADS_DELETE_SCOPE started appending it (see “Deleting a published post” above). Re-check this list against the live scope constants before using it on a submission. It has now gone stale three times, and a Facebook Login for Business configuration can grant permissions the settings string never mentions.

Graph API versions in use

One setting per product family, plus a few deliberate pins. Worth knowing before quoting a version on a submission. The Marketing API retires versions much faster than Graph, which is why ads has its own setting.

VersionWhere
META_GRAPH_VERSION (v23.0)Every graph.facebook.com / graph.instagram.com call through services/meta_graph.py, in the backend and in the gateway's own copy: connect flows, publishing, webhook diagnostics
FACEBOOK_INSIGHTS_API_VERSION (v23.0)Facebook post insights, pinned separately in facebook_service (both modules)
v21.0 (pinned)The Instagram private-reply path and the Facebook Messenger Send API in the gateway, pinned separately from their publishers so the two can move independently
WHATSAPP_GRAPH_VERSION (v25.0)WhatsApp Cloud API
META_ADS_GRAPH_VERSION (v25.0)Every Meta Ads (Marketing API) call, dialog included. v25 is available until 23 Feb 2027.
v1.0Threads (graph.threads.net)

App Review status

The organic surfaces (Facebook, Instagram, Threads, WhatsApp) cleared review in round 2. The “Awaiting Meta review” chip that used to sit on them in Settings → Platforms and onboarding has been removed product-wide; do not reintroduce a per-platform availability badge without its onboarding twin (see the note in app/(app)/settings/platforms/page.tsx). Meta Ads is the one surface still gated: until round 3 and the Access Tier's Full access clear, only people with a role on the app (or in a portfolio that claimed it) can connect an ad account, and anyone else gets an opaque error from Meta in the connect popup.

Round 3 (Meta Ads) is the four permission cards and the Access Tier card at the top. Record the four videos fresh, in the order the setup gives, one file per permission, and check them with the md5 command before uploading. The round-2 text in the archive is exactly what Meta approved; leave it unchanged unless Meta asks for something new. The screencast scripts quote the English UI strings. If a label on screen differs, the app changed, so update the script before recording.