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

# Connect Meta Ads (Facebook & Instagram)

> Track and manage Meta ad campaigns in Hiveku

Bring your Facebook and Instagram ad campaigns into Hiveku to track performance, pull insights, and unify paid media reporting across channels.

<Info>
  Meta Ads uses a manual token-paste flow — not OAuth. You generate a long-lived system user access token in Meta's Business Manager, then paste it into Hiveku along with your ad account ID.
</Info>

## Before You Start

* A Facebook Business account at [business.facebook.com](https://business.facebook.com)
* Access to the Ad Account you want to connect (with `ads_read` or `ads_management` permissions)
* A Meta Developer account at [developers.facebook.com](https://developers.facebook.com)

## Create the Meta App

<Steps>
  <Step title="Create a Business-type app">
    Go to [developers.facebook.com](https://developers.facebook.com) > **My Apps** > **Create App**. Choose **Business** as the type. Name it something recognizable like `Acme Hiveku`.
  </Step>

  <Step title="Add the Marketing API product">
    In your new app, go to **Add Product** and find **Marketing API**. Click **Set Up**.
  </Step>

  <Step title="Link the app to your Business Manager">
    Meta will ask you to associate the app with a Business — pick the Business Manager that owns the ad accounts you want to connect.
  </Step>
</Steps>

## Generate a System User Access Token

System user tokens are long-lived (don't expire as long as the system user exists), which makes them the right choice for server-to-server integrations like Hiveku.

<Steps>
  <Step title="Open Business Settings">
    Go to [business.facebook.com](https://business.facebook.com) > **Business Settings** (gear icon).
  </Step>

  <Step title="Create a system user">
    **Users > System Users > Add**. Give it a name like `Hiveku Integration` and set the role to **Admin** or **Employee** depending on how you want to scope it.
  </Step>

  <Step title="Assign ad account access">
    Click **Add Assets > Ad Accounts**, pick your ad account, and assign **Manage ad account** permissions to the system user.
  </Step>

  <Step title="Generate the token">
    On the system user's row, click **Generate New Token**. Select:

    * **App:** your Business app from the previous section
    * **Token expiration:** Never (system user tokens don't expire)
    * **Scopes:** at minimum `ads_read`; add `ads_management` if you want Hiveku to also write (pause/resume, update budgets)

    Click **Generate Token**. Copy the token immediately.

    <Warning>
      Treat this token like a password. Anyone with it can read (or manage) your ad account. Store it securely and rotate if leaked.
    </Warning>
  </Step>
</Steps>

## Find Your Ad Account ID

In [Meta Ads Manager](https://www.facebook.com/adsmanager), the ad account picker in the top-left shows the ID. It's a numeric ID with an `act_` prefix:

```
act_123456789
```

**Include the `act_` prefix** when pasting into Hiveku — it's part of the ID.

## Connect in Hiveku

<Steps>
  <Step title="Open the integration">
    Go to **Marketing > PPC > Add Connection > Meta Ads**.
  </Step>

  <Step title="Paste the token and ad account ID">
    * **Access token:** the system user token from Business Manager
    * **Ad account ID:** `act_123456789` format (include the `act_` prefix)
  </Step>

  <Step title="Save">
    Hiveku validates the token against the Meta API and, if valid, saves the connection.
  </Step>
</Steps>

## What You Get

* **Campaign, ad set, and ad** metrics — spend, impressions, clicks, CPC, CPM, conversions
* **Creative performance**
* **Audience insights** (where enabled)
* **Attribution windows** configurable via the Hiveku dashboard

Data refreshes on an ongoing schedule and is backfilled where available.

## Rotating the Token

System user tokens don't expire, but you should rotate periodically (e.g., every 12 months) for hygiene.

<Steps>
  <Step title="Generate a new token in Business Manager">
    Same flow as above — pick the same system user, generate a new token.
  </Step>

  <Step title="Update in Hiveku">
    **Marketing > PPC > \[Meta Ads connection] > Edit > paste new token > Save**.
  </Step>

  <Step title="Revoke the old token">
    In Business Manager, revoke the previous token so it stops working.
  </Step>
</Steps>

## Connect Multiple Ad Accounts

Repeat the flow for each ad account. You can reuse the same system user token if it has access to all the accounts — just paste different ad account IDs.

## Verify the Connection

* Connection status shows **Active**
* Campaigns list populates within a few minutes
* Spend and performance match what's in Meta Ads Manager (small delays are normal)

## Troubleshooting

<AccordionGroup>
  <Accordion title="'Invalid access token' or 'Session has expired'">
    The token is expired, revoked, or malformed. Generate a fresh system user token in Business Manager and update the connection. Make sure you copied the full token string.
  </Accordion>

  <Accordion title="'Unsupported get request' or 'Cannot find ad account'">
    Usually means the ad account ID is missing the `act_` prefix. The correct format is `act_123456789`, not `123456789`.
  </Accordion>

  <Accordion title="'Permission denied' on the ad account">
    The system user token doesn't have `ads_read` (or `ads_management` if writing) on that specific ad account. In Business Manager, open the system user, confirm the ad account is assigned, and regenerate the token with the right scopes.
  </Accordion>

  <Accordion title="Rate limit errors">
    Meta's Marketing API has per-app, per-user, and per-ad-account rate limits. If you're hitting them, consider batching requests or applying for a higher tier in Meta's App Review. Shared apps in development mode hit limits fast — promote your app to Live status.
  </Accordion>

  <Accordion title="No data for recent campaigns">
    Meta's insights API has inherent delays (typically up to an hour for recent metrics, longer for attribution-based conversions). Cross-check in Ads Manager — if data's missing there too, it's a Meta-side delay.
  </Accordion>
</AccordionGroup>

## What's Next?

<CardGroup cols={2}>
  <Card title="Connect Google Ads" icon="google" href="/how-tos/connect-google-ads">
    Add PPC from Google alongside Meta
  </Card>

  <Card title="Connect TikTok Ads" icon="tiktok" href="/how-tos/connect-tiktok-ads">
    Add TikTok paid media
  </Card>
</CardGroup>