openclaw-adspirer 2026.3.13 → 2026.3.16

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 2026.3.16 (2026-03-16)
+
+### Added
+- **Placement-specific image creatives** for Meta campaigns — use different images for Feed (1080x1080), Stories/Reels (1080x1920), and Right Column (1200x628) via `asset_feed_spec`
+- Auto-detection of Page-Backed Instagram Account (PBIA) for `asset_feed_spec` creatives
+- `story_image_url` and `right_column_image_url` parameters for `create_meta_image_campaign` and `add_meta_ad`
+- **City-level targeting** for Meta campaigns — target specific cities with optional radius
+- **Emoji/rich text support** in Meta `primary_text` — emojis, line breaks, bullet points for higher engagement
+- Graceful fallback to standard `object_story_spec` when placement image uploads fail
+
+### Fixed
+- Meta `asset_feed_spec` requires explicit `instagram_user_id` (unlike `object_story_spec` which auto-assigns)
+- Meta `asset_customization_rules` requires at least 2 rules — single-image fallback prevents API errors
+
+## 2026.3.15 (2026-03-15)
+
+### Added
+- **Input format requirements** section in embedded skill prompt — guides AI clients on IDs-as-strings, text length limits, enum casing, budget types, and keywords format
+- Server-side input resilience: auto-coerces int IDs to strings, normalizes enum casing, strips whitespace, ignores unknown fields, parses JSON string arrays
+
+### Fixed
+- Reduced ~160 preventable validation errors (22% of all tool call failures) through server-side coercion and client-side guidance
+
 ## 2026.3.7 (2026-03-07)
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-adspirer",
-  "version": "2026.3.13",
+  "version": "2026.3.16",
   "type": "module",
   "description": "OpenClaw plugin for Adspirer — manage Google, Meta, TikTok & LinkedIn ads via natural language",
   "keywords": [

package/src/commands/cli.ts

@@ -16,7 +16,7 @@ import { readFileSync, writeFileSync, rmSync, existsSync } from "node:fs";
 import { join } from "node:path";
 
 const PLUGIN_ID = "openclaw-adspirer";
-const PLUGIN_VERSION = "2026.3.13";
+const PLUGIN_VERSION = "2026.3.16";
 
 function getConfigPath(): string {
   return join(process.env.HOME || process.env.USERPROFILE || ".", ".openclaw", "openclaw.json");

package/src/errors.ts

@@ -7,7 +7,7 @@ export function mapHTTPError(status: number, body?: any): string {
     case 401:
       return "Session expired. Run 'openclaw adspirer login' to reconnect.";
     case 402:
-      return "This feature requires Adspirer Plus/Pro. Upgrade at https://adspirer.ai/settings?tab=billing";
+      return "This feature requires Adspirer Plus/Pro. Upgrade at https://adspirer.ai/";
     case 403:
       return "Access denied. Check account permissions or subscription tier.";
     case 404:

package/src/skill-prompt.ts

@@ -203,6 +203,65 @@ These tools operate on REAL ad accounts that spend REAL money. Follow strictly:
 
 ---
 
+## Critical: Input Format Requirements
+
+Follow these rules EXACTLY when calling Adspirer tools to avoid validation errors:
+
+### IDs Must Be Strings
+All IDs (campaign_id, ad_account_id, video_id, image_hash, ad_group_id, keyword_id, organization_id, creative_id) MUST be passed as quoted strings, never as bare integers.
+
+- ✅ \`"existing_video_id": "1333064875515942"\`
+- ❌ \`"existing_video_id": 1333064875515942\`
+
+### Never Modify IDs
+Copy IDs exactly as returned by list/discover tools. Do not round, truncate, or change any digits. If \`list_campaigns\` returns \`campaign_id: "120240129373510507"\`, use that exact value.
+
+### Always Call List/Discover Before Create/Update
+Many tools require IDs from prior tool calls:
+- \`list_campaigns\` → get \`campaign_id\` before update/pause/structure
+- \`get_campaign_structure\` → get \`ad_group_id\` before keyword operations
+- \`discover_existing_assets\` → get \`image_hash\`, \`video_id\` before campaign creation
+- \`get_linkedin_organizations\` → get \`organization_id\` and \`account_id\`
+
+### Text Length Limits
+Respect character limits — the server will reject text that's too long:
+- Google Ads headline: max 30 characters
+- Google Ads description: max 90 characters
+- Google Ads sitelink text: max 25 characters
+- Google Ads callout: max 25 characters
+- Meta primary_text: max 125 characters (supports emojis, line breaks, bullet points)
+- Meta headline: max 40 characters
+
+### Meta Ad Copy Formatting
+Meta primary_text supports rich formatting for higher engagement:
+- Use emojis strategically: \`\`🔥 ✅ 🎯 💰 ⚡ 🚀 👉 ⭐\`\`
+- Use line breaks (\\n) and bullet points (•, ✅, ▸) for readability
+- Example: \`\`"🔥 Limited Time Offer!\\n\\n✅ Free Shipping\\n✅ 30-Day Returns\\n\\n👉 Shop now!"\`\`
+- Bold/italic/HTML are NOT supported — plain text with emojis only
+
+### Enum Values Are Case-Insensitive
+The server auto-normalizes casing, but these are the expected values:
+- **status:** ENABLED, PAUSED, ACTIVE, ARCHIVED
+- **objective:** OUTCOME_TRAFFIC, OUTCOME_SALES, OUTCOME_LEADS, etc.
+- **match_type:** EXACT, PHRASE, BROAD
+- **call_to_action:** LEARN_MORE, SHOP_NOW, SIGN_UP, etc.
+- **date_range:** last_7_days, last_30_days, last_90_days, etc.
+- **campaign_type:** search, pmax, image, video, carousel, etc.
+
+### Budgets Are Numbers
+Pass budget fields (\`budget_daily\`, \`budget_amount\`, \`target_cpa\`) as numbers, not strings:
+- ✅ \`"budget_daily": 50\`
+- ❌ \`"budget_daily": "50"\`
+
+Budget is in the account's local currency (not cents). Meta minimum varies by currency.
+
+### Keywords Format
+For \`add_negative_keywords\`, each keyword must be an object:
+- ✅ \`"keywords": [{"text": "free", "match_type": "BROAD"}]\`
+- ❌ \`"keywords": ["free", "cheap"]\`
+
+---
+
 ## Platform Quick Reference
 
 ### When to Use Each Platform
@@ -277,7 +336,7 @@ Adspirer is billed by tool calls \u2014 each API action (reading performance, cr
 
 All plans include access to all ad platforms (Google Ads, Meta Ads, LinkedIn Ads, TikTok Ads). Tool call quotas reset monthly.
 
-Sign up and connect ad accounts at https://adspirer.ai/settings?tab=billing
+Sign up and connect ad accounts at https://adspirer.ai/
 
 ---
 
@@ -314,5 +373,5 @@ Sign up and connect ad accounts at https://adspirer.ai/settings?tab=billing
 | Session expired | Token auto-refreshes; if persistent, run login again |
 | No platform data | Connect ad platforms at https://adspirer.ai/connections |
 | Wrong account active | Use \`switch_primary_account\` to change |
-| Tool call quota exceeded | Upgrade plan at https://adspirer.ai/settings?tab=billing (Free: 15/mo, Plus: 150/mo, Pro: 600/mo, Max: 3,000/mo) |
+| Tool call quota exceeded | Upgrade plan at https://adspirer.ai/ (Free: 15/mo, Plus: 150/mo, Pro: 600/mo, Max: 3,000/mo) |
 `;