Tool reference

Show the current ZuckerBot authentication mode (demo vs authenticated), the Free/Pro/Scale and Lifetime billing tiers, setup instructions if not yet configured, and the recommended tool flow from audit → campaign → launch → performance. Returns status, recommended_flow steps, pricing info, and setup guide for unauthenticated users. Call this first in any new session to orient the agent.

Check your current ZuckerBot billing tier, API call usage this month, remaining quota, and overage costs. Use this when a user asks about their plan or usage limits.

Run a full audit of the connected Meta ad account: spend flagged for review against each campaign's own objective, creative fatigue, opportunity score (0-100), projected CPL improvement, and prioritised action items. Read-only and available on every tier — the recommended FIRST call for any new account or when a user asks 'how are my ads doing?'.

Analyse the historical ad performance for a business. For accounts WITH history: returns aggregated metrics by audience type, top performing creatives, and comparable CPL ranges. For NEW accounts with NO history: returns is_cold_start=true with industry benchmarks. Use this as the FIRST step in campaign planning — feed the result into zuckerbot_recommend_campaign_structure.

Fetch real-time performance metrics for a ZuckerBot campaign. Legacy campaigns return a flat metrics summary (impressions, clicks, leads, spend, CPL, CTR). Intelligence campaigns additionally return tier-by-tier and ad-by-ad Meta insights, daily breakdowns, CAPI attribution totals, and AI-recommended next actions. Use this to monitor an active campaign or to diagnose underperformance.

Fetch historical Meta ad account performance for a connected business over a date range. Auto-paginates the full range and reports the covered dates plus a truncated flag, so long daily series are complete rather than silently cut short. Returns spend, clicks, impressions, CTR, CPM, CPC, and frequency aggregated daily or monthly.

Query campaign, ad set, or ad-level performance for any campaign in the connected Meta ad account — including campaigns not created by ZuckerBot. Tags each row with is_zuckerbot so you can benchmark ZuckerBot campaigns against manually managed ones. Supports date range filtering, campaign name search, status filters, time-series breakdowns, and multi-column sorting. For deduped truth use meta_result / cost_per_meta_result (Meta's Ads Manager \"Results\" for any objective) or conversion_leads / meta_leads — not the inflated, deprecated leads / cpl (the response labels every lead field). Ad set and ad rows report their own status, with the sync time stated per response. meta_result and conversion_leads are most reliable on campaign-level, non-time-incremented queries.

Check whether the user's Facebook/Meta account is connected to ZuckerBot. Returns connection status, connected ad accounts, and a connect URL if not yet linked. Always call this before attempting to launch a campaign to confirm Meta credentials are available.

Fetch the current Conversions API configuration for a business: whether CAPI delivery is enabled, CRM source, currency, stage-to-event mappings, action source, and webhook URL. Use this before configuring CAPI to see what is already set, or to audit the current event mapping. The webhook secret is write-only: reads return a masked value, never the full secret.

Get 7-day and 30-day CAPI delivery statistics for the business: total events sent, events by type (Lead/Contact/Purchase), match quality and identifier-coverage breakdowns, Meta's own acknowledged count, and attribution counts with their basis. Attribution counts campaign links (ZuckerBot records or Meta lead resolution) — delivery health is meta_events_received.

Send a synthetic CAPI test event through the business configuration to verify the full pipeline: stage mapping, hashing, and Meta Graph API delivery. Logs as a test event (does not affect real attribution). Use after setting up or updating CAPI config to confirm events are flowing.

Fetch live Meta performance and downstream CAPI attribution for a launched audience portfolio. Returns enriched tier rows with ad breakdowns, daily metrics, CPA vs. target comparisons, and autonomous evaluation outputs. Use this to monitor a running portfolio and decide whether to rebalance.

Generate a campaign structure recommendation: audience tiers, budget allocation, creative mix. For accounts WITH history: uses Claude to generate data-driven recommendations. For NEW accounts (cold start): generates conservative defaults from industry benchmarks + safe 2-tier structure (broad 60% / interest 40%). Always returns comparable_historical_cpl with source (account_history or industry_benchmarks) and a disclaimer — NEVER a CPL projection. Lead campaigns default to Meta Instant Form; for leads driving to a website landing page rather than Meta Instant Form, set lead_destination='website'. Present the recommendation to the customer for approval before proceeding.

Generate a detailed creative brief from an approved campaign structure. SAFE — pure function, no Meta API calls, no money spent. Automatically pulls brand context and historical creative patterns (or uses brand context alone for cold-start accounts). Returns per-slot creative directions: for static ads, specific ad template + headline/body/CTA + hero image prompt; for video ads, hook concept + voiceover direction + visual style. After brief is generated, present it to the customer, then call zuckerbot_generate_static_ad / zuckerbot_generate_video_ad for each slot.

Build a complete PAUSED Meta campaign from an approved Campaign Architect session. dry_run defaults to TRUE and must be presented for approval first. Live mode creates PAUSED Meta objects for review only; Architect auto-activation is temporarily disabled. Use a reviewed legacy draft for the supported live launch path.

Generate a zero-cost campaign preview from any business URL. Scrapes the site and writes AI-generated headlines and body copy, using the site's own imagery for the mockup — all without a Meta account or live budget. Use this as the first step to show a user what their ads could look like before committing to a full campaign.

Create a campaign draft. It defaults to legacy mode, which is the only launch-ready path. Explicit intelligence mode remains available for planning and review only and cannot currently activate. Draft creation itself does not spend money or create anything on Meta.

Build a complete Meta campaign verbatim from a declarative JSON spec — no strategy generation, no copy authoring. Supports website conversions and Meta instant forms, and can clone an existing ad's image or video asset into the new build. Everything is created paused, always; launch stays a separate deliberate call. Send dry_run first to review the fully resolved payloads before anything is created; validation failures come back as clear per-field errors.

Duplicate ONE supported ad into an existing ad set in the SAME ad account. Dry-run by default: it returns the exact object plan (1 new creative + 1 new ad) without creating anything; pass execute: true plus an idempotency_key to perform it. The duplicated ad is ALWAYS created PAUSED — activating it is a separate deliberate action. Supported source shapes: static single-image creatives with an accessible image hash, and single pre-uploaded video creatives. Carousel, dynamic/catalogue, existing-post and multi-asset creatives are rejected with the unsupported feature named. A new creative is always built — creative IDs are never reused.

Fetch the full details of a ZuckerBot campaign by ID: intelligence workflow state, approved strategy, stored creatives, audience tier executions, and performance status. Use this to inspect a campaign at any stage of the lifecycle.

Approve the AI-generated intelligence strategy for a campaign, optionally narrowing to specific audience tiers and creative angles. This locks in the plan before creative production starts. Required before calling zuckerbot_request_creative or zuckerbot_upload_creative.

Not currently available. Intelligence campaigns are planning-only; create and review a legacy-mode draft, then use zuckerbot_launch_campaign for the supported live path.

Launch a draft campaign on Meta (Facebook/Instagram). THIS IS THE MONEY ENDPOINT — it creates real ads on the user's Meta ad account and immediately begins spending their budget. Stored Meta credentials are auto-resolved when available. Set launch_all_variants=true to launch every creative variant as separate ads for A/B testing (Meta auto-optimizes for the winner). Always confirm the user has budget available and Meta is connected (zuckerbot_meta_status) before calling.

Pause delivery at any level — a whole campaign, one ad set, or one ad — so you can stop an underperformer without touching the winners beside it. Campaign resume is not currently available through ZuckerBot — paused objects are resumed from Meta Ads Manager.

Generate creative production briefs based on the business's tagged ad-performance patterns. Each brief specifies hook type, visual style, copy tone, CTA, and script guidance weighted toward the top-performing creative attributes. Use after running zuckerbot_creative_analysis to know which patterns to bias toward.

Build a Meta custom audience from hashed CAPI user data stored for a business, filtered by CRM lifecycle stage (e.g., 'lead', 'customer'). Use this as the first step to create retargeting or reactivation audiences from your own first-party CRM data.

Create a Meta lookalike audience from a stored seed audience. Expands a first-party seed (e.g., 'customer' stage) into a 1%, 3%, or 5% prospecting audience that Meta will target based on similarity. Typically used for the prospecting tier of an intelligence campaign.

List all stored Meta audiences for a business: seed audiences, lookalike audiences, sizes, delivery statuses, and CAPI source details. Use this to see what audiences are available before launching a campaign, or to find audience IDs for refresh and delete operations.

Rebuild a stored audience from fresh data. For seed audiences: re-hashes the latest CAPI events for the source CRM stage. For lookalike audiences: syncs the current size and delivery status from Meta after the seed refreshes. Use this when CAPI has received new events since the audience was last built.

Fetch the current Meta delivery status, size, and readiness for a stored audience. Updates the local audience registry row. Use this to check if an audience is large enough to use in a campaign before launch.

Permanently delete a stored audience from both Meta and ZuckerBot's local registry. This cannot be undone. Use when an audience is stale, was created in error, or you need to free up Meta audience slots.

Create a planning and monitoring-only multi-tier audience portfolio. New portfolio launch is temporarily disabled; use a reviewed legacy draft for live launch.

Fetch portfolio configuration and any existing performance data for planning, monitoring, or rebalancing an already-active portfolio.

Update the name, total daily budget, active status, or tier configuration of an existing audience portfolio. Changes to budget and tiers take effect on the next autonomous evaluation cycle. Use this to adjust a portfolio without relaunching all tiers.

Dry-run or execute a budget rebalance across portfolio tiers based on each tier's actual vs. target CPA. With dry_run=true (default) returns recommendations without making changes — useful for review before committing. With dry_run=false updates Meta ad set budgets and local records in one operation.

Not currently available. Portfolio planning and monitoring remain available, but new multi-tier launches cannot create Meta objects.

Generate a brand-aware 1080×1080 static ad image. Automatically injects brand context (logo, colors, brand name, value props, social proof) from the business profile when business_id is provided — no need to pass brand data manually. Templates: stat_hook (statistic + supporting copy), pain_headline (bold headline + benefit bullets), testimonial (customer quote + portrait), feature_showcase (product + benefits). Returns a public image URL and QA scores. Present the image to the customer for approval; to generate more variants, call again with different parameters.

Generate a video ad through ZuckerBot's video generation pipeline (AI scripting → AI video → captioned overlay → hosted upload). ASYNC operation: returns a job_id immediately. Poll with zuckerbot_get_video_ad_status every 30 seconds for completion. Brand context is loaded server-side. Typical generation time: 5-15 minutes. Note: AI-generated video ads may face Meta ad review scrutiny — rejection tracking is built in.

Check the status of an async video ad generation job. Returns current status and, when complete, the final video URL. Also surfaces Meta ad review status and rejection reasons if the ad has been submitted to Meta. Poll every 30 seconds until status is 'completed' or 'failed'.

Dispatch a creative production request for an approved intelligence campaign. If a creative-production webhook is configured on the business, ZuckerBot generates full video scripts and fires the production payload. Use this when you want ZuckerBot to handle creative production end-to-end rather than uploading your own assets.

Generate standalone ad creative variants (images or video) using AI image and video models. Works independently of campaign creation — useful for quick mockups, creative testing, or building assets before attaching them to a campaign. If the description mentions video, reels, UGC, or TikTok, the tool auto-routes to the video model.

Upload finished creative assets (images or videos) to an approved intelligence campaign. ZuckerBot queues the Meta upload and ad-creation jobs asynchronously, then polls until they complete or the polling window expires. Use this when you have your own creative assets ready.

Check the asynchronous upload queue for an intelligence campaign. all_complete=true means every queued job has finished for review; intelligence activation is temporarily disabled.

Analyse creative performance patterns for a business by grouping ads by hook type, visual style, product focus, setting, CTA type, copy tone, or opening element. Returns average CPL/CTR/CPC/frequency per group, per-group trend direction, a structured insight object with recommendations, and can optionally include the top and bottom individual ads for the selected metric. Use this before generating new briefs to inform the creative strategy.

Cross two creative dimensions to find winning combinations. Example: hook_type × visual_style can reveal that curiosity + ugc outperforms pain_point + stock. Returns a performance matrix, best and worst combinations, and an actionable insight string.

Score proposed creative variants against the business's historical top-performing patterns. Accepts raw creative specs (copy, headline, CTA, asset URLs, frame URLs for video) and returns a pattern-match score for each. Use this before producing expensive creative assets to pre-validate concepts against what has historically worked.

Tag Meta ads with creative attributes (hook type, visual style, product focus, CTA type, copy tone, setting) by providing ad metadata and optional asset URLs. ZuckerBot uses Claude vision to analyze the creative and store structured tags. These tags feed the zuckerbot_creative_analysis pipeline. Run this after launching new ads to keep the creative intelligence database current.

Read the stored creative attribute tags for up to 50 Meta ads in the canonical creative_attributes.v1 shape: the 17 extracted attributes, the extraction lifecycle (tag status, error class, attempt metadata, legacy-row flag), taxonomy/prompt/model versions, asset and input fingerprints, and the campaign objective family. A pure read of already-stored rows — it never triggers extraction.

Send downstream conversion quality feedback to Meta via CAPI. When a ZuckerBot-sourced lead converts (sale, appointment, qualified call) or bounces (uncontactable, bad fit), reporting it here teaches Meta's algorithm to find more (or fewer) people like them — improving lead quality over time. Call this from your CRM when a lead status changes.

List Meta Pixels available on the currently selected ad account and show which is currently selected for conversion tracking. Optionally select a pixel by providing select_id. The selected pixel is used for all future conversion tracking and CAPI attribution.

List Meta lead forms (Instant Forms) available on the selected Facebook Page and show which is currently selected. Optionally select a form by providing select_id to persist it for future lead generation campaign launches. Use this before launching a leads-objective campaign so ZuckerBot reuses the business's CRM-connected form rather than creating a new one.

Read one Meta lead form (Instant Form) in full — questions, privacy policy URL and legal content, locale, context card, thank-you page, follow-up action URL, status, created time and lead counts. A pure read: it never changes or persists the selected form.

Export lead submissions from a Meta instant form for a date range: each lead's id, created_time and submitted field values, with bare numeric lead ids (no CSV 'l:' prefix). Requires the leads_retrieval permission on the connected Meta token; large ranges are capped and flagged truncated so you can narrow and re-call.

Update the Conversions API configuration for a business. Set stage-to-event mappings (e.g., 'lead' → Meta Lead event), enable/disable delivery, change the CRM source, currency, optimisation target, or action source. Custom Meta event names are supported alongside the standard ones, and any normalised stage keys are reported back. Changes take effect immediately for new CAPI events. Use zuckerbot_capi_test to verify the updated config works.

Rotate the Conversions API webhook secret for a business. The new secret is returned exactly once, in the rotate response only — all other reads show a masked value. The old secret stops authenticating immediately, so update the system that signs your inbound webhooks in the same sitting.

List the custom conversions on the connected ad account — id, name, rule, source event and pixel — so a campaign spec can reference the right conversion by id.

Read one custom conversion in full — rule, source event, category, default conversion value, availability and creation time, plus the fields Meta actually permits updating. Optional bounded stats (30-day default window) on request. A pure read that never binds an ad account.

Create a custom conversion on the connected ad account from a pixel, a name and an optional URL rule. Requires sufficient permissions on the connected Meta token.

Manually send a Conversions API event for a business contact/lead. Useful for debugging CAPI pipelines, testing stage mappings with real user data, or sending events from custom integrations not covered by the webhook. Authenticates with the business API key OR with an x-zuckerbot-webhook-secret header if using the webhook path.

Crawl a business website and extract structured intelligence used by campaign planning: company description, services, pricing signals, testimonials, location data, and brand tone. Run this before creating a campaign when the business has not been enriched yet, or use force_refresh after a website update to refresh stale context.

Return only the creative angles and audience tiers for a campaign draft — a lightweight alternative to zuckerbot_get_campaign when you need just the strategy summary without the full campaign payload, stored creatives, or tier execution details.

Fetch review intelligence for a business by name. Searches Google and Yelp to surface star rating, review count, recurring sentiment themes, and standout customer quotes that can be used directly in ad copy. Use before creating a campaign to identify proof points and objection-handling angles.

Scrape Meta Ad Library and search the web to analyse competitor ads in a given industry and location. Returns competitor positioning, common creative hooks, and exploitable gaps. Use before creating a campaign to benchmark against the competitive landscape and find differentiation opportunities.

Get market size, addressable audience estimates, and Meta ad benchmarks (CPL, CTR, CPM) for an industry and location. Use before creating a campaign to set realistic budget expectations and understand how large the targetable audience is. Also useful for proposals and client presentations.

Redeem a ZuckerBot lifetime licence code (format ZB-XXXXX-XXXXX-XXXXX) purchased on Dealify or AppSumo. Codes stack on one account: 1 code = Lifetime Tier 1 (1 ad account, 2,500 calls/mo), 2 codes = Tier 2 (3 accounts, 10K calls/mo), 3 codes = Tier 3 (10 accounts, 30K calls/mo). Redeeming upgrades ALL of the account's API keys to the new tier immediately.

Upload a text document (ad performance data, brand guidelines, customer data, sales data, or competitor analysis) so ZuckerBot can extract structured planning insights from it. Accepts raw text content — not binary files. Use this when the business has existing performance data or brand docs that should inform campaign strategy.

List all uploaded business-context files for a business along with their extracted summaries. Use this to confirm what planning documents are loaded before creating a campaign, or to check whether a previous upload was processed successfully.

List Meta ad accounts available to the connected user and show which is currently selected for launches and reporting. Optionally select an ad account by providing select_id — this clears the stored page selection so you can pick a matching page. Call this during setup or when switching between multiple ad accounts.

List Facebook Pages available to the connected Meta account and show which is currently selected for ad delivery. Optionally select a page by providing select_id. The selected page is used as the ad identity for all future launches.

Resolve and validate all stored Meta launch credentials for the authenticated user: access token, ad account, page, and pixel. Reports whether autonomous launch (no credential params needed at launch time) is possible. Call this after completing the setup sequence to confirm everything is ready before launching a campaign.