# HYROS Installation: Facebook Ads - Interactive Setup Guide

I'll guide you through setting up Facebook Ads tracking with HYROS step by step.

Before we begin, please note:
- If you're using Wicked Reports, Triple Whale, or Northbeam, you can use your existing tracking UTMs
- Updating ads may reset the learning phase, but the ROI gained from tracking outweighs this
- This guide does NOT work for Messenger Ads (contact HYROS support for those)

Let me start by asking a few questions to understand your setup:

1. Do you have admin access to Facebook Ads Manager?
2. Do you have admin access to the Facebook Business Manager?
3. Are you already using Wicked Reports, Triple Whale, or similar tracking?

[Wait for their responses. Based on their answers:]

**If they said YES to question 3 (using existing tracking):**
Great! You can use your existing tracking UTMs. Let's skip ahead to Step 2: Integrating Facebook with HYROS.

**If they said NO to question 3 (not using existing tracking):**
Perfect, let's start with Step 1: Installing Facebook Parameters.

---

## Step 1: Install Facebook Parameters

Here's the HYROS Facebook Tracking Parameter you'll need:
```
fbc_id={{adset.id}}&h_ad_id={{ad.id}}
```

How would you like to proceed? I can guide you through this manually step-by-step, or give you quick automated instructions.

Type 'manual' for detailed guidance, or 'automatic' for quick steps.

[Wait for their response]

### If they chose "automatic":

Here are the steps:
1. Navigate to Ads Manager (https://adsmanager.facebook.com)
2. Find Campaigns tab, select a campaign
3. Go to Ad Sets tab
4. Check the ad set to edit
5. Click Edit (pencil icon)
6. Scroll to find "Tracking" section near the bottom
7. Look for "URL Parameters" field
8. Paste the HYROS parameter: `fbc_id={{adset.id}}&h_ad_id={{ad.id}}`

Have you added the parameters?

[Wait for response - if YES, continue to validation. If NO, ask what issue they encountered]

### If they chose "manual":

Let me walk you through this step by step.

**Step 1:** Open your Facebook Ads Manager at https://adsmanager.facebook.com

**Step 2:** Select Ads - Check the boxes for EVERY active ad in your account

**Step 3:** Find Tracking - In the edit side-pane, scroll down to the Tracking section

**Step 4:** Install the Parameter:
- If the field is empty: Paste the parameter string exactly: `fbc_id={{adset.id}}&h_ad_id={{ad.id}}`
- If UTMs already exist: Add an `&` to the end of your existing text, then paste our parameter
- Example: `utm_source=fb&fbc_id={{adset.id}}&h_ad_id={{ad.id}}`

**Step 5:** Click the green Publish button

Did you add parameters to all ad sets?

[Wait for response - if YES, continue to validation. If NO, ask what issue they encountered]

---

## Validation: Confirm Parameter Installation

Did you add parameters to all active ad sets?

[Wait for response]

**If YES:**
Great! Let's move on to Step 2.

**If NO:**
What issue did you encounter?

[Wait for their response, then provide relevant troubleshooting:]
- Check if you have edit permissions for the ads
- Verify you're in the correct ad account
- Make sure you clicked "Publish" after adding parameters

After troubleshooting, have you added the parameters?

[Wait - if YES, proceed to Step 2. If NO, continue troubleshooting]

---

## Step 2: Integrate Facebook with HYROS

Now let's connect your Facebook account to HYROS.

Direct URL: https://app.hyros.com/integrations/facebook

How would you like to proceed? I can guide you manually or give you automated instructions.

Type 'manual' or 'automatic'.

[Wait for their response]

### If they chose "automatic":

Here are the steps:
1. Navigate to the HYROS Facebook Integration page (https://app.hyros.com/integrations/facebook)
2. Click "Add Account"
3. Enter a name for the integration
4. Click "Connect" - this opens Facebook OAuth
5. Complete the authorization
6. Select Business Manager and Ad Accounts

Have you completed the integration?

[Wait for response - if YES, continue to validation. If NO, ask what issue they encountered]

### If they chose "manual":

Let me walk you through this:

**Step 1:** Go to Integrations > Meta in your Hyros Dashboard (https://app.hyros.com/integrations/facebook)

**Step 2:** Click Add Account and enter a nickname

**Step 3:** Permissions Check - A Facebook pop-up will appear. You must select 'Allow All Permissions'. Skipping one will cause a 'Permission Denied' error in 24 hours

**Step 4:** Whitelisting - Toggle the switch to ON for the specific Ad Accounts you want to track

**Step 5:** Click Save

Have you completed the integration?

[Wait for response - if YES, continue to validation. If NO, ask what issue they encountered]

---

## Validation: Verify Facebook Integration

Does Facebook show as 'Connected' in HYROS integrations?

[Wait for response]

**If YES:**
Great! Do you use Facebook Lead Ads?

[Wait for response]
- If YES to Lead Ads: Let's set up Lead Ads tracking (continue to Lead Ads section)
- If NO to Lead Ads: Let's do a final validation check

**If NO (not connected):**
Let's troubleshoot:
- Check if you selected "Allow All Permissions" during OAuth
- Verify you have admin access to the Business Manager
- Try disconnecting and reconnecting the integration
- Ensure you toggled the whitelist ON for your ad accounts

After troubleshooting, is Facebook connected?

[Wait - if YES, ask about Lead Ads. If NO, continue troubleshooting]

---

## Step 3: Facebook Lead Ads (Optional)

### Phase 1: Enable Tracking

**Step 1:** Navigate to Settings → Integrations → Facebook in Hyros

**Step 2:** Select Lead Ads in the sidebar

**Step 3:** Toggle ON - Enable only the specific pages you are currently running ads on

Have you enabled Lead Ads tracking?

[Wait for response - if YES, continue to Phase 2. If NO, ask what issue]

### Phase 2: Permission Recovery

**Step 1:** Click 'Re-integrate with Facebook' in Hyros to refresh your token

**Step 2:** Meta Business Fix:
- Go to Meta Business Suite → Settings → Integrations → Leads Access
- Click Restore Default Access

Have you restored permissions?

[Wait for response]

Do you want to test your Lead Ads integration?

[Wait for response]

**If YES (wants to test):**
Follow Meta's testing process: https://www.facebook.com/business/help/417969522258325?id=735435806665862

Once test is successful, the lead and its source tag will appear in Hyros.

Did the test lead appear in Hyros?

[Wait - if YES, proceed to final validation. If NO, troubleshoot]

**If NO (doesn't want to test):**
No problem, let's do a final validation check.

---

## Final Validation

Are you experiencing any of these issues?
- missing_campaigns - Campaigns not showing up in HYROS
- no_attribution - Leads appear but show "No Attribution"
- messy_parameters - Parameters look broken/messy
- none - Everything looks good

Which one, or type 'none'?

[Wait for response]

### If "missing_campaigns":

Hyros usually imports data automatically upon the first click. If a campaign is missing, it's likely because no click has been tracked yet or it's an "Awareness" campaign.

Are you running Awareness ads without a 'Call to Action' button?

[Wait for response]

**If YES:**

NOTE: You can manually import ads for cost tracking, but this will NOT track view-through conversions.

- **Step 1:** Navigate to Settings > Integrations > Facebook
- **Step 2:** Locate the button: Import Ads and Ad Sets
- **Step 3:** Select the missing campaigns and click Confirm

Have you imported the missing campaigns?

[Wait for response]

**Whitelist Check:**

By default, Hyros shows all accounts your FB profile can access but only tracks those with active scripts.
- **To Track:** Ensure the account is Whitelisted (Toggle ON)
- **To Hide:** Use Blacklist to exclude accounts for privacy or NDA reasons

Have you verified your ad accounts are Whitelisted (toggled ON)?

[Wait for response]

Are campaigns appearing now?

[Wait - if YES, ask if any other issues. If NO, advise waiting 24-48 hours for first click]

### If "no_attribution":

If leads are appearing in Hyros but show "No Attribution," the URL parameters are likely broken.

When you check the Final URL in your ads, are the parameters visible?

Type 'yes', 'no', or 'not_sure'.

[Wait for response]

**If NO (parameters missing):**
You're likely using a redirect (e.g., bit.ly or linktree). Remove the shortener and use the direct URL in Facebook Ads Manager.

Are you using a URL shortener or redirect service?

[Wait - if YES, instruct to replace with direct URL and verify. If NO, continue troubleshooting]

**If YES (parameters visible):**
Do the parameters look normal or messy/broken?

Type 'normal' or 'messy'.

[Wait - if MESSY, go to messy parameters troubleshooting. If NORMAL, check syntax]

**If NOT_SURE:**
Let me help you check:
- Go to Facebook Ads Manager
- Select an ad
- Look at the "Final URL" or "Website URL" field
- Check if you see: `fbc_id={{adset.id}}&h_ad_id={{ad.id}}`

Do you see the parameters in the Final URL?

[Wait and loop back with their answer]

### If "messy_parameters":

Parameters looking messy (e.g., `%%fbc_id%=214...`) is a syntax error.

This usually happens when you placed a `?` before the parameter when one already existed.

**Fix:**
- If UTMs already exist: Use `&` (e.g., `?utm_source=fb&fbc_id={{ad.id}}...`)
- If it's a clean URL: Use `?` (e.g., `site.com/?fbc_id={{ad.id}}...`)

Does your destination URL already contain a question mark (?) with other parameters?

Type 'yes', 'no', or 'not_sure'.

[Wait for response and provide appropriate fix based on their URL structure]

### If "none":

Perfect! Facebook Ads integration setup is complete. Your ads are now tracked in HYROS.

---

## Source
Synced from: docsContent.ts (facebookAdsIntegration)
Last synced: 2026-01-14