Meta App Review · round 3 — Meta Ads
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.
pages_read_user_content pages_manage_engagement instagram_business_content_publish instagram_business_manage_comments instagram_business_manage_insights threads_read_replies whatsapp_business_messaging whatsapp_business_management
Their review text and scripts are kept, collapsed, in the archive further down — reuse them for Meta's annual Data Use Checkup.pages_show_list pages_read_engagement public_profileads_management ads_read business_management pages_manage_ads Marketing API Access Tier — Full access
business_management was drafted for round 2 but never submitted; Meta lists it as required
for every Marketing API use case, so it goes in now, with an answer written for ads.
pages_manage_ads is marked optional by the use case, but creating an ad that runs as a Page needs it.md5sum *.mp4 | sort | uniq -c -w32 in the recordings folder — every line must read 1. In round 1 one shared recording sank six permissions.ads_read video lingers on a campaign being created, ads_management gets the credit and ads_read is rejected.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.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.<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.socialyfy/backend/.env, then restart api and the Celery workers)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.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.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”.ADMIN_USERNAME / ADMIN_PASSWORD), because a campaign only reaches Meta after an admin approves it.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./admin.business_management: creates no campaign.ads_management: creates Review — traffic and leaves it running at a small daily budget, so ads_read has something to read.pages_manage_ads: creates its own campaign, Review — Page ad. Pause it in Ads Manager as soon as you stop recording.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.ads_read script reads the four account totals rather than one campaign's row.
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.
ads_read video.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.ads_read) needs a day of delivery to read.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.
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.
ads_management), the ad preview (pages_manage_ads) and Business settings
(business_management). This video only shows numbers being read.
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.
ads_management), any figures (ads_read) and the ad preview
(pages_manage_ads). Business settings is shown read-only. Change nothing in it.
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.
ads_management video.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.
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.
ads_read or ads_management for it, so submit it together with them or right after they are approved.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.
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.
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”.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.
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”.pages_messaging. This video must contain the public reply and nothing else.
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.
instagram_business_content_publish is legible, and caption it. Then click Allow.instagram_business_*
permissions, and sharing one file between them is what sank round one.
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.
instagram_business_manage_comments is legible, and caption it. Then click Allow.instagram_business_manage_messages and rejected this permission.
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.
instagram_business_manage_insights is legible, and caption it. Then click Allow.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.
threads_read_replies is readable, and
caption it. Then authorize. The popup closes and the row shows green Connected with the
profile's @username.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.
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.
whatsapp_business_management. The user sees exactly who they are about to message before
they opt in.”messages webhook
subscription, which is the other half of this permission.”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.
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.
| Permission | What consumes it | Review 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.
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.
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.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.<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.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.
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.
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.
| Variable | Required? | Notes |
|---|---|---|
META_ADS_APP_ID | Optional | Falls back to META_APP_ID. |
META_ADS_APP_SECRET | With the above | Falls back to META_APP_SECRET. |
META_ADS_LOGIN_CONFIG_ID | Yes, on a Business app | The ads Login for Business configuration. Keep it separate from FACEBOOK_LOGIN_CONFIG_ID. |
META_ADS_OAUTH_SCOPES | Has a default | ads_management,ads_read,business_management,pages_show_list,pages_read_engagement,pages_manage_ads. Ignored when the config id is set. |
META_ADS_GRAPH_VERSION | Has a default | v25.0, available until 23 Feb 2027. Its own knob: see “API version” below. |
AD_INSIGHTS_RECONCILE_DAYS | Has a default | How 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.
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.
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.
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.
| Symptom | Cause |
|---|---|
| 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 / 463 | The grant is gone. Socialyfy marks the connection revoked and shows "reconnect". It does not surface the code. |
Graph error 200 or 10 | The 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 270 | Development 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 sense | META_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_id | Deprecated for every version. The field is instagram_user_id, which is what the provider sends. |
| Campaign create returns 400 with no obvious field | special_ad_categories is required, not optional. Socialyfy always sends []; a hand-rolled call that omits it fails here. |
| Ad set rejected for the optimization goal | The 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 set | Known 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 creative | Meta'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 rejected | CONVERSIONS, 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 spending | Meta 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.
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.
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.
| Constant | Products it covers |
|---|---|
FACEBOOK_OAUTH_SCOPES | Facebook Pages |
INSTAGRAM_OAUTH_SCOPES | Instagram via Facebook Login |
INSTAGRAM_DIRECT_OAUTH_SCOPES | Instagram API with Instagram Login |
THREADS_OAUTH_SCOPES | Threads (space-separated, unlike the others) |
INSTAGRAM_DELETE_SCOPE | Instagram post deletion — instagram_manage_contents, appended to the Instagram request (empty = not granted to the app) |
THREADS_DELETE_SCOPE | Threads post deletion — threads_delete, appended to the Threads request. Empty until Meta approves it |
| none — static token | WhatsApp Cloud API |
META_ADS_OAUTH_SCOPES | Meta 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. |
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.
| Flow | Where scopes is written from |
|---|---|
GET /me/permissions, granted entries only | |
| Instagram — Facebook Login | the same helper, on the long-lived user token |
| Instagram — Instagram Login | the permissions field on the token exchange |
| Threads | the 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.
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.
| Object | Callback | Field | Verify token | Drives |
|---|---|---|---|---|
| Page | /webhooks/meta/facebook | feed | META_WEBHOOK_VERIFY_TOKEN | Facebook auto-reply + auto-DM |
/webhooks/meta/instagram | comments | META_WEBHOOK_VERIFY_TOKEN | Instagram auto-reply + auto-DM | |
| WhatsApp Business Account | /webhooks/whatsapp | messages | WHATSAPP_VERIFY_TOKEN | WhatsApp 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.
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.
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"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>--fix, or the resubscribe endpoint. Idempotent, and unlike disconnect + reconnect it does not rotate the token./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.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.Tell them apart before touching anything.
| Symptom | Missing permission | Recorded status |
|---|---|---|
| Reach is a dash, likes and comments are real numbers | read_insights | partial |
| Every column is a dash | pages_read_user_content | no_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:
| Class | Meaning | Who fixes it |
|---|---|---|
permission | the token lacks read_insights | the account owner, by reconnecting |
unsupported_metric | Meta retired the metric name we ask for | us, by shipping a new name — reconnecting does nothing |
other | network, throttling | usually 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.
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.
| Platform | Call | Permission | Switch |
|---|---|---|---|
DELETE /{page-post-id}, Page token | pages_manage_posts (already held) | always on | |
| Instagram — Facebook Login | DELETE /{ig-media-id} on graph.facebook.com | instagram_manage_contents | INSTAGRAM_DELETE_SCOPE |
| Instagram — Instagram Login | none — Meta offers no media delete on graph.instagram.com | — | card says “delete it in the Instagram app” |
| Threads | DELETE /{threads-media-id} on graph.threads.net; 100 per account per day | threads_delete | THREADS_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.
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.
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.
| Version | Where |
|---|---|
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.0 | Threads (graph.threads.net) |
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.