Meta Ad Accounts

Connect and manage Meta ad accounts on the Ad accounts page (/accounts). How many accounts a team can connect is a plan limit (see the comparison on /pricing); past the limit the connect flow stops with a “plan limit reached” message and offers an upgrade. Select the relevant account for account-scoped actions; team members may have different account access.

Connect with Facebook

Ad accounts are connected only through the official Continue with Facebook button — Facebook Login for Business through the AdWitch app. AdWitch never asks you to paste an access token and has no file import.

Before you start, make sure you have:

1. a Business portfolio with the ad accounts assigned to you (Business settings → Ad accounts → People);
2. a Facebook Page you administer (needed for creatives and Instagram placements);
3. a Pixel / dataset (recommended for conversion campaigns; it can be added later).

Then:

1. Open Ad accounts (/accounts), choose Add account, and press Continue with Facebook. Meta shows a login dialog for the AdWitch app; sign in with the Facebook profile that has access to the ad accounts.
2. After you return, AdWitch lists every ad account visible to that Facebook user: name, act_ id, currency, status and Business. Long lists are read page by page — press Show more to continue. Tick the accounts you want and press Connect N account(s). Nothing is imported silently.
3. Accounts that are already connected in your team through another Facebook user are shown locked. Accounts connected through the same user (or with an expired token) are offered as Reconnect.

Each account card shows through which Facebook user it is connected, the token type Meta issued (user or System User) and its expiry as reported by Meta. When no date is reported it says expiry unknown — never “permanent”.

Several Facebook profiles or Meta Business portfolios

Repeat Add account with another Facebook profile. Each authorisation adds its ad accounts to the team without touching the accounts connected through other profiles. When a token expires or is revoked, the card offers Reconnect via Facebook.

What the connection can and cannot do

• Meta decides the permissions: they come from the login configuration of the AdWitch app and from your role on the ad account, Page and Business. Connecting never launches ads or changes anything in Meta.
• The minimal configuration contains exactly ads_read, ads_management, business_management, pages_show_list, pages_read_engagement. The full configuration includes those plus, in order: pages_manage_ads, pages_manage_posts, leads_retrieval, catalog_management, instagram_basic, threads_business_basic, pages_read_user_content, pages_manage_engagement, instagram_manage_comments, page_events, whatsapp_business_management, whatsapp_business_manage_events, instagram_manage_events. If a connection lacks a feature permission, the account card offers Reconnect via Facebook; that feature remains unavailable. An unknown grant list is not treated as a missing grant. ads_read reads insights; ads_management manages campaigns, creatives, audiences, pixels, Conversions API and offline dataset events, custom conversions, split tests, budget schedules, ad labels and ad copies. business_management resolves the owning Business and Business-owned assets. pages_show_list and pages_read_engagement list Facebook Pages and their posts.
• pages_manage_ads supports creating lead forms, downloading leads together with leads_retrieval, promoting existing Page posts, click-to-message ads (Messenger, Instagram Direct, WhatsApp), collection Instant Experiences and reading Page lead forms as custom-audience sources. pages_manage_posts uploads unpublished, temporary Page photos and creates a hidden Page canvas for a collection ad’s Instant Experience — it never publishes feed posts. Meta’s Instant Experiences guide lists only pages_manage_ads, while its Page Photos and Page Canvases references require the union pages_manage_posts, pages_manage_ads, pages_read_engagement, pages_read_user_content, pages_show_list; the latter also reads the canvas alongside its comment-moderation role. Collection publishing refuses before calling Graph when stored scopes prove either pages_manage_posts or pages_manage_ads missing.
• catalog_management enables catalogs; instagram_basic resolves Instagram media and identity; threads_business_basic resolves the linked or advertiser-backed Threads account for Threads ads (which also need instagram_basic and pages_read_engagement). pages_read_user_content and pages_manage_engagement moderate Facebook ad comments using the owner Page’s token; instagram_manage_comments moderates Instagram ad-media comments. Sales closed in chats (the assistant reports them through Meta’s Conversions API for Business Messaging, into the dataset of the Page, WhatsApp Business account or Instagram account rather than the pixel) need page_events for Messenger, whatsapp_business_management and whatsapp_business_manage_events for WhatsApp, and instagram_manage_events for Instagram (measurement only: Meta optimises chat purchases for click-to-Messenger and click-to-WhatsApp ads). These four reach the platform’s Login configuration only after Meta’s App Review approves them; the assistant lists each one as granted, missing or unknown before the first send and sends nothing while one is known to be missing. No additional Login permission is needed for pixel Conversions API/offline dataset events (covered by ads_management), for publishing click-to-WhatsApp ads (no WhatsApp Business permission), or for Threads ads beyond the permissions above. Ad Library needs identity confirmation, not another permission.
• An ad account, a Page, an Instagram identity and a Pixel are separate grants. Seeing an ad account in the list does not mean the connection can post from a Page or read a Pixel.
• The token issued by Meta is stored encrypted, is used only from AdWitch’s server and is never shown — not in URLs, logs or analytics. The authorisation result waits for your selection for 15 minutes; after that you simply start again.

App setup and Page access

Operators select Ad accounts, Pages, Instagram accounts, Catalogs, Pixels / Datasets, and Businesses if offered in Login for Business. Pixels / Datasets support Conversions API, offline datasets and default-pixel binding, especially for System User connections. Facebook Login for Business asks users to grant every permission in its configuration at once: a new permission such as pages_manage_posts must be approved in App Review before adding it to production, or tested in a separate configuration with a second config_id. Adding an unapproved permission to production can break everyone’s connections.

App features (not Login permissions)

App-level features, separate from Login permissions: Marketing API Access Tier (required, formerly Ads Management Standard Access) calls its tiers Limited and Full. Full lifts Meta’s cap on the number of client ad accounts and gives normal rate limits; Meta requires at least 500 Marketing API calls in the past 15 days and an error rate under 15% over the last 500 calls before requesting it. The API server reads Graph response headers (development_access = Limited, standard_access = Full), and the admin panel’s Meta app permissions check shows the last observed tier. Business Asset User Profile Access is conditional, not yet confirmed: request it with App Review if commenter names (from / username) are empty. Ads MCP server is an optional separate dashboard use case for ads_mcp_management, available only behind a platform flag.

Page-side prerequisites

No Login permission grants the Page-side ADVERTISE task (required for every ad using its identity, lead forms, lead download and click-to-message), the CREATE_CONTENT task (collection ads), or Leads Access (Leads Access Manager in Business settings, for lead downloads).

Managing accounts and pixels

Each connected account keeps its own campaign data. You can activate or deactivate an account for automation and default lookups without disconnecting it. The agent can list accounts, check connection status, and inspect or manage their pixels and Pages. Team settings control which accounts a member can see.

In the account’s defaults, choose a default Page and pixel for new ads. Under pixels, select an existing pixel or Enter pixel ID for a pixel shared from another Business; AdWitch checks the ID with Meta. Create pixel creates one in the account’s Business (or the account if it has no Business) and sets it as the default. After creation, use Copy code to install the base code on your site. If Meta requires its Business Tools Terms, an admin of the Business must accept them before creation; the app shows a card with a link to Business Settings.

Open Signal & optimisation event for the default pixel’s scorecard: match quality, browser/server deduplication, value and currency, funnel coverage and freshness. Refresh from Meta reads a new snapshot. Unknown means a measurement was unavailable, not that the signal is broken; event recommendations depend on available ad-set insights. On a Shopify or WooCommerce store where only browser events arrive or customer matching is weak, the section also shows the free fix: the setup steps for Meta’s own integration (see Conversions API).

Pages, Pixels and Other Lists

• Full lists. Pixels, Pages, custom audiences, custom conversions, lead forms, creatives, images and videos are read from Meta page by page — not just the first 25–100 objects. For very large accounts a safety ceiling applies (500 objects, 200 for media); when it is hit the agent and the UI show a “list truncated” note.
• Instagram-linked Pages. The Page picker shows whether a professional Instagram account is linked. Select a linked Page for Instagram identity. Threads placement is offered when Meta allows it for the objective and requires a linked Instagram account. Link one under Facebook Page settings if it is missing; the connection also needs the relevant Instagram and Threads permissions.
• Valid destination link required. A link ad is never published without an http(s) destination URL; the agent will ask for one instead of substituting a placeholder.

Additional Meta diagnostics (MCP)

An optional, off-by-default toggle on the Ad accounts page (visible only when the platform has the feature enabled) connects Meta’s official Ads MCP Server to the chat as a read-only diagnostics source: account opportunity score, insight anomalies, auction and industry benchmarks, performance trends, dataset/EMQ quality, Help Center answers for error codes, Ad Library search and the account activity log.

• What is shared. While the toggle is on, AdWitch’s server calls mcp.facebook.com with the token of one connected ad account during a chat turn; the token is sent only to Meta, not to the AI provider. Only read-only tools are available, and every call is checked against the tool’s declared resource selectors so it concerns only the team’s connected accounts (foreign or disconnected accounts, undocumented arguments and token-wide account listings are refused; catalog tools stay off until a catalog can be tied to a connected account). Every write tool is excluded, so nothing can be created or changed through this path. Campaign creation and edits stay native (confirmations, Meta-first writes, billing).
• Extra permission. When the optional Ads MCP server use case is enabled, its separate configuration must grant ads_mcp_management; it is not in the always-on Login configuration. Accounts connected without that permission can press Reconnect via Facebook after the operator enables the use case and its permission. Without it the panel shows “Reconnect via Facebook with the additional permission” and the agent explains the same in chat instead of failing silently.
• Tool list. Meta rolls the tools out gradually per ad account. Check tools fetches the live list and shows how many of the allow-listed read-only tools are available for your account.
• Turn it off with the same toggle — no MCP calls are made from the next chat turn on. If Meta rejects the token (permission missing, token revoked), the panel shows Reconnect via Facebook and the diagnostics stay off until the account is reconnected.

Troubleshooting

Issue	Solution
“Facebook returned no ad accounts”	The Facebook profile you signed in with has no ad accounts assigned. In Business settings → Ad accounts → People add yourself, then Try again with Facebook
“You cancelled the Facebook dialog”	The permission request was declined. Start again and accept the requested permissions
“Facebook login is not configured”	The installation has no Meta app configured (FB_APP_ID, FB_APP_SECRET, FB_LOGIN_CONFIG_ID). Contact the administrator
“This authorisation has expired”	More than 15 minutes passed between the Facebook dialog and your selection — press Try again with Facebook
“Connected via another Facebook user”	The account is already in the team through another profile. Ask that person to reconnect, or leave it as is
“Expiry unknown”	Meta did not report a date. Treat it as unknown, not as permanent