Meta AI Ads

Create and manage Meta (Facebook & Instagram) ad campaigns, lead forms, audiences, pixels, and product catalogs via the Plai API. Also connects Facebook/Inst...

Security Scan

The skill is a coherent CLI for Plai's Meta ad APIs and mostly matches its description, but two mismatches — an undeclared PLAI_BASE_URL override that can redirect requests, and a postinstall that runs npm install in the scripts directory — raise caution before installing.

Purpose & Capability

Name, description, required env vars (PLAI_API_KEY, PLAI_USER_ID), required binary (node), and the code all match a Plai Meta Ads CLI that creates/manages campaigns, forms, audiences, etc.

Instruction Scope

SKILL.md instructs running the provided CLI and describes expected operations; however the runtime script reads an optional PLAI_BASE_URL environment variable (defaults to https://public.plai.io). PLAI_BASE_URL is not declared in requires.env or documented in SKILL.md, which means API calls can be redirected to an arbitrary endpoint if that env var is set — a potential data-exfiltration vector if misused.

Install Mechanism

Install uses Homebrew to ensure node exists (reasonable). package.json contains a postinstall script that runs `cd scripts && npm install` — this will reach out to the npm registry and create node_modules under scripts if dependencies are present. This networked install step is not large but is an extra action that will modify disk and can fetch code from npm; review the scripts folder before running postinstall.

Credentials

The two required env vars (PLAI_API_KEY, PLAI_USER_ID) are appropriate and proportional for a Plai integration. However, the script also honors PLAI_BASE_URL (undeclared) which can redirect API traffic; the presence of this undocumented env var is worth noting and documenting before use.

Persistence & Privilege

Skill does not request always:true and does not modify other skills or system-wide settings. It runs as a CLI and has no persistent background agent components.

What to consider before installing

This skill appears to implement the advertised Plai Meta Ads CLI and asks only for a Plai API key and user id, which is expected. Before installing or running it: (1) Inspect scripts/plai-meta.js yourself — note it will POST your PLAI_API_KEY and PLAI_USER_ID to the configured BASE_URL; by default that's https://public.plai.io but an undocumented PLAI_BASE_URL env var can redirect calls to any host, so only set PLAI_BASE_URL to a trusted endpoint. (2) Be aware package.json has a postinstall script that runs `cd scripts && npm install` — this will download from npm and write node_modules; run in a controlled environment or offline if you prefer. (3) Review OAuth connection links the tool generates before opening them. If you trust Plai and will only use the official endpoint, the skill is generally coherent. If you cannot verify the endpoint or want to avoid automatic npm installs, treat this as higher risk.

Meta Ads via Plai

Manage Meta (Facebook & Instagram) advertising through the Plai API.

Setup

Requires two environment variables:

• PLAI_API_KEY — your Plai API key (from your Plai account dashboard)
• PLAI_USER_ID — your Plai user ID

How to Run

All operations are run via:

node scripts/plai-meta.js <command> [options]

Options are passed as --key value pairs. JSON array/object values must be passed as quoted JSON strings, e.g. --locations '[{"id":"2537","type":"city","countryCode":"AE"}]'.

---

Account Connection

This must be done before any ad operation. If an ad tool returns "User has no connected Facebook account" or similar, generate a connection link and share it with the user so they can complete the OAuth flow.

Generate an account connection link

# Connect Facebook / Instagram Ads account
node scripts/plai-meta.js create-connection-link --platform FACEBOOK

# Connect Google Ads account
node scripts/plai-meta.js create-connection-link --platform GOOGLE

# With a custom redirect after connection
node scripts/plai-meta.js create-connection-link \
  --platform FACEBOOK \
  --redirectUri "https://yourapp.com/connected"

Required: --platform (FACEBOOK | GOOGLE) Optional: --redirectUri — URL the user lands on after completing OAuth

Returns a link the user must open in their browser to connect their account. Share this link directly; do not attempt to open it automatically.

---

Campaign Management

List all campaigns

node scripts/plai-meta.js list-campaigns

Create a campaign

node scripts/plai-meta.js create-campaign \
  --campaignName "My Campaign" \
  --campaignType LEAD_GENERATION \
  --budget 50 \
  --url "https://example.com" \
  --locations '[{"id":"2537","type":"city","countryCode":"AE"}]' \
  --primaryText '[{"text":"Join us today!"}]' \
  --images '["https://example.com/image.jpg"]' \
  --leadsFormId "1234567890"

Required params: campaignName, campaignType, budget, locations

Required by type:

• LEAD_GENERATION → also requires --leadsFormId
• CONVERSIONS / OUTCOME_SALES → also requires --pixelId and --conversionGoal

Optional params: --url, --primaryText, --headlines, --images, --videos, --interests, --gender ("1" male / "2" female), --minAge, --maxAge, --targetLocales, --audienceId

Notes:

• --images takes a JSON array of URL strings — they are automatically transformed to {url} objects.
• --minAge and --maxAge must both be provided together.
• callToAction is always LEARN_MORE (set automatically).

campaignType values: LEAD_GENERATION | LINK_CLICKS | CONVERSIONS | OUTCOME_SALES

---

Create a message engagement campaign

Drives conversations via messaging apps (Messenger, Instagram DM, WhatsApp).

node scripts/plai-meta.js create-message-engagement \
  --campaignName "Chat with Us" \
  --budget 50 \
  --url "https://example.com" \
  --locations '[{"id":"2537","type":"city","countryCode":"AE"}]' \
  --messagingApps '["MESSENGER","WHATSAPP"]' \
  --multipleCreatives '[{
    "url": "https://example.com",
    "primaryText": "Chat with us today!",
    "greetingText": "Hi {{user_first_name}}! How can we help you?",
    "conversations": [{"title": "Learn more about our products"},{"title": "Get a quote"}],
    "image": "https://example.com/image.jpg"
  }]'

Required params: campaignName, budget, url, locations, messagingApps, multipleCreatives

messagingApps — JSON array of: MESSENGER | INSTAGRAM | WHATSAPP — always ask the user; never default.

multipleCreatives — JSON array of 1–10 creative objects. Each creative:

• Required: url, primaryText, greetingText, conversations (array of {title} objects)
• Optional: headlines, phoneNumber, image (URL), video ({video_id, thumbnail_url})

Optional campaign params: --interests, --gender, --minAge, --maxAge, --targetLocales, --audienceId

Get campaign insights

node scripts/plai-meta.js get-insights \
  --campaignId "123456789" \
  --startDate "2024-01-01" \
  --endDate "2024-01-31"

Update campaign status

node scripts/plai-meta.js update-status --campaignId "123456789" --status ACTIVE
node scripts/plai-meta.js update-status --campaignId "123456789" --status PAUSED
node scripts/plai-meta.js update-status --campaignId "123456789" --status DELETE

status values: ACTIVE | PAUSED | DELETE

Update campaign budget

node scripts/plai-meta.js update-budget --campaignId "123456789" --amount 100

---

Lead Forms

Check Lead Ads Terms of Service

Always run this before creating a lead form. If TOS is not accepted, the user must accept at https://www.facebook.com/ads/leadgen/tos first.

node scripts/plai-meta.js check-leadform-tos

List existing lead forms

node scripts/plai-meta.js list-leadforms

Create a lead form

Requires user to provide all values — never assume or fabricate them.

node scripts/plai-meta.js create-leadform \
  --leadsFormName "My Lead Form" \
  --privacyPolicyUrl "https://example.com/privacy" \
  --privacyPolicyName "Privacy Policy" \
  --website_url "https://example.com/thank-you" \
  --questionPageCustomHeadline "Tell us about yourself"

---

Targeting

Search targeting locations (always use before creating a campaign)

node scripts/plai-meta.js search-locations --query "Dubai"
node scripts/plai-meta.js search-locations --query "United States"

Returns {id, type, countryCode} objects. Pass these directly to create-campaign --locations.

Search targeting interests

node scripts/plai-meta.js search-interests --query "fitness"
node scripts/plai-meta.js search-interests --query "real estate" \
  --specialAdCategories '["HOUSING"]' \
  --specialAdCountries '["US","GB"]'

specialAdCategories values: HOUSING | FINANCIAL_PRODUCTS_SERVICES | EMPLOYMENT

Returns {id, name, type} objects. Pass to create-campaign --interests.

Get targeting locales (language targeting)

node scripts/plai-meta.js get-locales

Returns numeric locale IDs. Pass as --targetLocales '[65,24]' to create-campaign.

---

Audiences

List custom audiences

node scripts/plai-meta.js list-audiences

Create page engagers audience

node scripts/plai-meta.js create-page-audience \
  --name "FB Page Engagers" \
  --type FACEBOOK

node scripts/plai-meta.js create-page-audience \
  --name "IG Engagers" \
  --type INSTAGRAM

Create lead form audience

All fields are required — ask the user for each one explicitly.

node scripts/plai-meta.js create-leadform-audience \
  --name "Lead Form Openers" \
  --description "People who opened our summer campaign form" \
  --leadFormIds '["12345","67890"]' \
  --type open

type values: open | close | submit

Create lookalike audience

node scripts/plai-meta.js create-lookalike \
  --sourceType AUDIENCE \
  --sourceId "120231334546180123" \
  --audienceName "Lookalike - US" \
  --countryCode US

sourceType options: AUDIENCE (requires --sourceId) | PAGE (no sourceId needed)

---

Pixels & Conversions

List pixels

node scripts/plai-meta.js list-pixels

List custom conversions for a pixel

node scripts/plai-meta.js list-conversions \
  --pixelId "123456789" \
  --campaignType CONVERSIONS

campaignType options: CONVERSIONS | OUTCOME_SALES

---

Media

List ad account media

node scripts/plai-meta.js list-media --type IMAGE
node scripts/plai-meta.js list-media --type VIDEO

Returns {video_id, thumbnail_url} for videos. Use these in create-campaign --videos.

List Facebook page media

node scripts/plai-meta.js list-fb-media --type IMAGE

List Instagram page media

node scripts/plai-meta.js list-ig-media

Upload a video

node scripts/plai-meta.js upload-video --videoUrl "https://example.com/video.mp4"

Returns a videoId. Then poll until ready:

node scripts/plai-meta.js get-video-info --videoId "123456789"

Poll until status is READY, then use video_id + thumbnail_url in create-campaign --videos.

---

Product Catalogs

List catalogs

node scripts/plai-meta.js list-catalogs

Create a catalog

node scripts/plai-meta.js create-catalog --name "My Store Catalog"

Create a product feed (imports products from a URL)

node scripts/plai-meta.js create-catalog-feed \
  --catalogId "123456" \
  --name "Daily Feed" \
  --fileUrl "https://example.com/products.csv" \
  --currencyCode USD \
  --timezone "America/New_York" \
  --interval DAILY

Get catalog feed status

node scripts/plai-meta.js get-catalog-feed --catalogFeedId "123456"

List products in a product set

node scripts/plai-meta.js list-catalog-products --productSetId "123456"

Create a product set

node scripts/plai-meta.js create-product-set \
  --catalogId "123456" \
  --name "Summer Collection" \
  --productIds '["prod1","prod2","prod3"]'

---

Workflow Guide

Before creating any campaign

1. Run create-connection-link --platform FACEBOOK if the Meta account is not yet connected — share the returned link with the user.
2. Run search-locations to get valid location IDs — never guess IDs.
3. Optionally run search-interests for interest targeting.
4. For LEAD_GENERATION: run check-leadform-tos, then list-leadforms or create-leadform.
5. For CONVERSIONS/OUTCOME_SALES: run list-pixels then list-conversions.
6. Run list-media if using existing account media for creatives.

Campaign type decision

Goal	Command	campaignType
Collect leads via a form	create-campaign	LEAD_GENERATION
Drive traffic to a website	create-campaign	LINK_CLICKS
Optimize toward a pixel event	create-campaign	CONVERSIONS
Optimize toward purchases	create-campaign	OUTCOME_SALES
Drive messaging conversations	create-message-engagement	OUTCOME_ENGAGEMENT

After creating a campaign

Campaigns are created paused by default. Run:

node scripts/plai-meta.js update-status --campaignId "<id>" --status ACTIVE

when the user confirms they are ready to go live.

---

Error Handling

Error message	Cause	Fix
Unauthorized	Invalid PLAI_API_KEY	Check the key in your Plai dashboard
User has no connected Facebook account	Meta account not linked in Plai	Run create-connection-link --platform FACEBOOK and share the link with the user
User has no connected Google account	Google Ads account not linked	Run create-connection-link --platform GOOGLE and share the link with the user
TOS not accepted	Lead Ads TOS pending	User must accept at facebook.com/ads/leadgen/tos