Skip to main content

​
Connect your business

An organization admin connects Meta Ads from Control Hub > Integrations. Sign in to Meta, choose your business portfolio, and select the ad accounts and any Pages, Instagram accounts, catalogs, or pixels that agents should access. At least one ad account is required; the other asset types are optional. The connection is shared within your Aster organization. Meta permissions and asset assignments determine what it can access. Use Aster’s Tools & permissions settings and agent tool selection to control which agents can read or manage those assets. The business login uses a system-user token. It can remain authorized without a scheduled expiry, but Meta or the business can still revoke access. If a token or data-access grant expires, reconnect from Control Hub. Aster keeps the token server-side and does not return it to an agent or the browser.

​
Three tools

These tools accept native Meta fields and parameters, so features do not each require a separate tool. Meta validates which fields, permissions, and parameter combinations an endpoint supports. The existing search_meta_ads tool remains available for public Ad Library research. Ad Library eligibility and verification are separate from business advertising access; connecting a business does not automatically grant Ad Library access.

​
Account and campaign discovery

Then query /act_<account_id>/campaigns, /adsets, /ads, or another edge. Read an individual object with /<object_id>. Account paths use the act_ prefix. Request useful fields explicitly; Meta’s default selection can be minimal. Use /me/businesses and a business’s /owned_ad_accounts or /client_ad_accounts edges when exploring business relationships. Available results depend on the assets and permissions granted during connection.

​
Performance reporting

Dates are inclusive and interpreted in the ad account’s timezone. Without a date selection, reports use last_30d. Use params for breakdowns, filtering, attribution windows, action report time, or unified attribution settings. Compare like-for-like definitions: different attribution settings, conversion action types, currencies, or timezones can change the meaning of totals. For large reports:
  1. Call start_report with the report definition and keep report_run_id from content.result.
  2. Call report_status with that ID. Wait for async_status to be Job Completed; failed jobs are not empty reports.
  3. Call report_results with the same ID and page through the rows.

​
Creating and managing ads

POST to an object’s ID to update its status, budget, targeting, or other supported fields. POST to a supported /copies edge to duplicate an object. DELETE removes an object or edge item. New campaigns, ad sets, and ads default to PAUSED when status is omitted; an explicit ACTIVE status can start delivery and spending. Check the account’s currency and the endpoint’s budget-unit rules before writing. Insights spend and budget parameters are not interchangeable. API errors are returned to the agent, and writes are never automatically retried. If a request times out, query the resource before retrying because the write may already have succeeded. Nested parameters such as targeting, object_story_spec, asset_feed_spec, and audience payloads are serialized for Meta. Image upload supports an API-compatible bytes payload; video creation can use file_url. A local file path or Aster attachment reference is not itself a Meta upload: obtain the supported media payload or URL first. Endpoint-specific multipart and resumable upload workflows are not automatically performed by these tools.

​
Pagination and large results

Read tools retrieve one page at a time, with a default page size of 100 and maximum of 500. Meta may return fewer rows. When has_more is true, repeat the same request with next_cursor as after_cursor. All three tools use Aster’s shared _spill handling. Large fetched results become files with bounded inline previews. A file contains only the fetched page, not subsequent pages. Pagination metadata remains inline. If storage is unavailable, the response explicitly states that the complete result is unavailable. Direct API calls retain their direct-response size limit.

​
Troubleshooting

​
Pilot testing while Meta review is pending

The unpublished app is not yet a public customer connection. Before a pilot tester connects, an Aster app administrator must add their real Facebook account under App roles > Roles > Add People > Tester, and the tester must accept the invitation. Meta requires a Facebook Developer Account for this role. The Tester role allows testing permissions without granting app-settings administration. Meta may still restrict particular assets or features until the required reviews are complete. For the tester:
  1. Sign in to Aster on www.asteragents.com as an admin of the organization that should own the connection.
  2. Open Control Hub > Integrations > Meta Ads, continue to Meta, and sign in with the Facebook account invited as an app tester. To test the business integration system-user flow, that account must have full control of the client business, which must be separate from Aster’s app-owning portfolio, and access to the assets being selected.
  3. Choose the business portfolio and intended ad account. Select any Pages, Instagram accounts, catalogs, and pixels needed for the test, then finish the authorization and return to Aster.
  4. Enable Query Meta Ads and Meta Ads Insights on a test agent. Ask it to list accessible accounts, then report campaign spend, impressions, and clicks for a short, explicit date range on the chosen account. Compare with Ads Manager using the same timezone, attribution settings, and date range.
  5. For an explicitly authorized write test, also enable Manage Meta Ads and request a clearly named, paused test campaign. Keep it paused and confirm the returned ID and status in Ads Manager. Activation and spending are separate actions.
If login or a tool fails, share the exact error, step, and time with Aster. Do not send access tokens or app secrets. A successful invitation or connection alone does not establish that every permission or asset is accessible.
  • Missing asset: Confirm that the connecting business has access and selected the asset during login. Reconnect to grant additional assets.
  • Permission error: Confirm the permission’s access level in the Aster Meta app and the connected business’s role on the asset. Page advertising, lead retrieval, catalogs, and partnership ads use additional permissions.
  • Expired or revoked connection: Reconnect Meta Ads in Control Hub. Tokens without scheduled expiry can still be revoked.
  • Report too large or slow: Use the asynchronous report actions, a shorter date range, or fewer breakdowns.
  • Invalid reporting combination: Reduce the selected metrics and breakdowns; not all combinations are valid in Meta.

​
Disconnect and data deletion

Disconnecting in Control Hub removes this organization’s stored Meta connection. To revoke the Meta-side grant, use Meta’s business integration controls. Disconnecting does not erase previously generated conversation messages or report attachments; use Aster’s deletion controls or contact Aster for assistance with retained data.

​
Operator setup

This integration requires Aster’s own Meta app, Facebook Login for Business configuration, and server environment variables:
  • META_APP_ID — 1936571317326333 for the Aster app.
  • META_APP_SECRET — server secret; never put it in a frontend variable or tool arguments.
  • META_LOGIN_CONFIG_ID — 1111521144590653 for the Aster Meta Ads business login configuration.
  • OAUTH_STATE_SECRET — shared OAuth-state signing secret already used by other integrations.
Register https://www.asteragents.com/api/integrations/meta/callback as a valid OAuth redirect URI. Keep HTTPS and strict redirect matching enabled. Development or preview hosts require their own exact registered callbacks; a production connection starts on www.asteragents.com so the browser-bound state cookie reaches the callback. The callback validates the initiating organization admin, signed state and browser cookie, token app ID, system-user token type, expiry, and advertising permissions before saving a connection. Existing manually supplied tokens remain usable by the tools until replaced or disconnected. For external customers, complete Business Verification, App Review for Advanced Access to the requested permissions, and the Marketing API Access Tier upgrade to Full Access before publishing. Meta retired separate Access Verification on October 9, 2026; the Tech Provider classification still applies to this customer integration. A successful local build or saved login configuration does not establish external-customer access. The configuration requests ads_read, ads_management, business_management, catalog_management, instagram_basic, instagram_branded_content_ads_brand, leads_retrieval, pages_manage_ads, pages_read_engagement, and pages_show_list. Asset selection and permission approval are separate: selecting an asset in business login does not grant an unapproved permission. Meta also requires Advanced Access to public_profile for Facebook Login for Business to serve external users. This app-level login requirement does not mean adding public_profile to the system-user token configuration. The review form requires pages_read_engagement alongside ads_management, pages_show_list alongside Page permissions, and instagram_basic alongside instagram_branded_content_ads_brand. Marketing API Full Access requires at least 500 successful Marketing API calls in the preceding 15 days and an error rate below 15% over the last 500 calls. Monitor these ongoing requirements. Permission tests are valid for 30 days and their counters can take 24 hours to update. The tier upgrade no longer requires a recording, but most of the individual permissions still require demonstrations. Before rollout:
  1. Complete Business Verification for the legal entity behind Aster’s business portfolio. Add the Website platform with https://www.asteragents.com/, supply the app icon, and review published privacy and deletion disclosures for the Meta features being enabled. Complete the data-handling questionnaire using verified legal-entity, processor, and government-request information.
  2. Configure the server variables above, deploy the integration, and run a real connection using an app-role account and its authorized test assets.
  3. Verify account discovery, a bounded performance report, asynchronous report retrieval, creation of a paused test campaign, and disconnect/reconnect. Publishing ads or changing budgets requires the account owner’s requested activation and spending intent.
  4. Prepare permission-specific explanations and recordings showing Aster sign-in, Meta authorization, asset selection, and actual use of each requested capability. Supply a dedicated Aster reviewer account and reproducible instructions. Complete test-call requirements and submit App Review, including the Full Access tier request.
  5. Confirm customer access with an account outside the app’s roles after Meta approves the permissions and the app is published.
The local test suites are scripts/test_meta_ads.mts and scripts/test_meta_oauth.mts. They mock Meta requests and do not establish live permission access.