Meta Ads Analytics & Event Finder

A powerful toolkit to monitor your Meta (Facebook/Instagram) advertising performance directly through chat. This bundle includes analytics reporting and an event discovery tool to ensure accurate tracking.

🚀 Capabilities

• Ad Performance Reporting:
• Calculates Spend, Conversions, and CAC (Cost Per Acquisition).
• Breaks down data by Ad Set.
• Supports natural language date ranges (e.g., "yesterday", "last month", "last 7 days").
• Event Discovery Tool:
• Lists all raw event names (e.g., offsite_conversion.custom...) currently active in your ad account.
• Helps you find the exact event name to configure for conversion tracking.

⚙️ Configuration (.env)

To use this skill, you must set the following environment variables in your OpenClaw setup:

| Variable | Description | Required | Default | | :--- | :--- | :--- | :--- | | META_ACCESS_TOKEN | User Access Token from Meta Developers | Yes | - | | META_AD_ACCOUNT_ID | Ad Account ID (must start with act_) | Yes | - | | META_EVENT_NAME | The specific conversion event to track | No | offsite_conversion.fb_pixel_custom |

🔑 How to Get Credentials

1. Get Access Token

• Go to Meta Graph API Explorer.
• Select your App.
• Add Permissions: ads_read, read_insights.
• Click Generate Access Token and copy the string.

2. Get Ad Account ID

• Go to Facebook Ads Manager.
• Check the URL for act=12345678.
• Your ID is act_12345678 (Don't forget the act_ prefix).

💬 Example Commands

check Analytics

"Show me yesterday's ad performance"

"Calculate CAC for the last 7 days"

"How were the ads from 2026-02-01 to 2026-02-10?"

"Report ad spend for this month"

Find Correct Event Name

"List all ad events"

"Show me available meta events"

⚠️ Troubleshooting

Q: My conversion count is 0, but I have sales. A: The default event is offsite_conversion.fb_pixel_custom. Your pixel might be using a different name like purchase, lead, or start_trial.

• Ask the bot: "List all ad events".
• Copy the exact raw name from the list.
• Update your META_EVENT_NAME variable with that name.