> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automate.ax/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Automate.ax automations are TypeScript programs.
> Use Bun for installation and command examples.
> Use Automate.ax for the product name and automate.ax for the package, CLI, and domain.
> Treat documented public APIs as current; do not invent transitional or deprecated names.

# Connect Meta Ads and extend its API

> Configure Meta OAuth, production permissions, token lifecycle, Webhooks, versioning, quotas, and custom Graph calls.

Automate.ax connects Meta Ads through Meta OAuth. It exchanges Meta's short-lived authorization result for a long-lived user token and records its expiration. Meta does not issue a standard refresh token for this flow, so reconnect the account after expiration or invalidation.

Packaged actions request the least permissions they need. Reads use `ads_read` or `ads_management`; writes and managed ad-account webhooks use `ads_management`; Business portfolio inventory also uses `business_management`. Lead reads use `ads_management`, `leads_retrieval`, `pages_manage_ads`, `pages_show_list`, and `pages_read_engagement`; managed lead webhooks also use `pages_manage_metadata`.

Meta grants Limited Access to development apps. Production use and access to assets owned by another business generally require Business Verification, App Review, and Advanced Access for each permission. Verify access with disposable business, ad-account, Page, pixel, and lead-form resources before relying on a workflow.

The integration pins Graph and Marketing API `v26.0`. Version upgrades are explicit Automate.ax releases. API failures throw `MetaAdsApiError` with the HTTP status, Meta code and subcode, transient marker, trace ID, retry delay, and raw app, ad-account, and business-use-case usage headers. Back off when Meta reports quota pressure.

Managed triggers configure the app-level `ad_account` or `page` Webhooks subscription, attach the selected ad account or Page to the app, validate Meta's GET challenge, and verify `X-Hub-Signature-256` against the exact request body. Status-change events announce a change; read the object to obtain its current status. Filtered `subscriptions` events require a provider subscription created through the subscription actions.

Use `getMetaAdsApi(account)` inside a custom account-backed action for an uncovered Graph edge. Paths remain under `https://graph.facebook.com/v26.0/`, query and body keys use public camel case, nested bodies are converted to Meta wire keys, and every response requires a Zod schema. This is an authenticated helper, not a generic packaged action.

See Meta's [Marketing API authorization](https://developers.facebook.com/documentation/business-api/marketing-api/authorization), [Graph API versioning](https://developers.facebook.com/docs/graph-api/guides/versioning), [Ads Webhooks](https://developers.facebook.com/documentation/ads-commerce/marketing-api/webhooks/overview), [Lead Ads retrieval](https://developers.facebook.com/docs/marketing-api/guides/lead-ads/retrieving), and [Conversions API](https://developers.facebook.com/docs/marketing-api/conversions-api/using-the-api).