API-Triggered Campaigns (Backend → Clix)

Use this skill to set up API-triggered campaigns in the Clix console and trigger them from your backend with dynamic data (

trigger.*

• Transactional notifications (orders, password reset, receipts)
• Workflow messages (assignments, approvals)
• System alerts (moderation, support tickets)
• Programmatic sends where marketers/ops should control content + targeting

What the official docs guarantee (high-signal)

• API-triggered campaigns are configured in the console, then triggered via:

  POST /api/v1/campaigns/{campaign_id}:trigger

• Authentication uses secret headers:

  • X-Clix-Project-ID

  • X-Clix-API-Key

• Request

  properties

  become

  trigger.*

  for:
  • Dynamic audience filtering (console audience rules)
  • Personalization in templates (title/body/deep links)

• audience.broadcast=true

  sends to all users eligible under the campaign’s segment definition;

  audience.targets

  narrows to specific users/devices (still filtered by the segment definition).
• Dynamic audience filters are intentionally constrained for performance: max 3 attributes in the audience definition.

MCP-first (source of truth)

If Clix MCP tools are available, treat them as the source of truth:

• Use

  clix-mcp-server:search_docs

  to confirm the latest API contract + limits:
  • query examples:

    • "API-triggered campaign trigger endpoint"

    • "campaigns/{campaign_id}:trigger audience targets broadcast"

    • "trigger.* dynamic audience filters limitations"

If MCP tools are not available, use the bundled references:

• API contract →

  references/api-contract.md

• Console setup + dynamic filters →

  references/console-setup.md

• Backend patterns (auth, retries, timeouts) →

  references/backend-patterns.md

• Security/key handling →

  references/security-and-keys.md

• Personalization + dynamic filters →

  references/personalization-and-dynamic-filters.md

• Debugging checklist →

  references/debugging.md

Workflow (copy + check off)

API-triggered campaign progress:
- [ ] 1) Confirm goals + trigger source (what backend event sends the message?)
- [ ] 2) Define campaign contract (properties keys/types; PII policy)
- [ ] 3) Configure campaign in console (API-triggered + audience rules + templates)
- [ ] 4) Implement backend trigger wrapper (auth, timeout, retries, logging)
- [ ] 5) Validate trigger plan JSON (schema + naming + safety)
- [ ] 6) Verify in Clix (test payloads, Message Logs, segment matching)

1) Confirm the minimum inputs

Ask only what’s needed:

• Campaign: where is it in the console? do you already have

  campaign_id

  ?
• Channel: push / in-app / email / etc. (affects message template fields)
• Audience mode: broadcast vs explicit targets
• Dynamic filter keys: which

  trigger.*

  keys are used in audience rules
• Properties: list of keys + types + example values (avoid PII by default)
• Backend: runtime and HTTP client (Node/Fetch, Axios, Python, Go, etc.)

2) Create a “Trigger Plan” (before touching backend code)

Create

api-trigger-plan.json

.clix/

Recommended location:

.clix/api-trigger-plan.json

Plan schema (high-level):

• campaign_id

  (string)

• audience.mode

  :

  "broadcast" | "targets" | "default"

• audience.targets

  (if mode is

  "targets"

  )

• dynamic_filter_keys

  (array of up to 3 snake_case keys)

• properties

  (map of snake_case keys →

  { type, required?, example?, pii? }

  )

Example:

{
  "campaign_id": "019aa002-1d0e-7407-a0c5-5bfa8dd2be30",
  "audience": {
    "mode": "broadcast"
  },
  "dynamic_filter_keys": ["store_location"],
  "properties": {
    "store_location": {
      "type": "string",
      "required": true,
      "example": "San Francisco"
    },
    "order_id": { "type": "string", "required": true, "example": "ORD-12345" },
    "item_count": { "type": "number", "required": true, "example": 3 },
    "pickup_time": { "type": "string", "required": false, "example": "2:30 PM" }
  }
}

3) Configure campaign in the console (API-triggered)

• Set the campaign type to API-Triggered.
• Build audience rules using

  {{ trigger.* }}

  for dynamic filters.
• Use

  {{ trigger.* }}

  in message templates + deep links.

See:

references/console-setup.md

4) Implement backend trigger wrapper (best practices)

Backend wrapper responsibilities:

• Auth: load

  X-Clix-Project-ID

  and

  X-Clix-API-Key

  from environment/secret store (never commit).
• Timeout: set a short timeout (e.g., 3–10s) and fail fast.
• Retries: retry only on transient failures (network/5xx), with backoff; do not retry blindly on 4xx.
• Dedupe: prevent double-sends in your system (e.g., unique key per order event) since the API call is “send-like”.
• Logging: log

  campaign_id

  , your correlation id (order id), and the Clix response (e.g.,

  trigger_id

  ).

Copy/paste examples:

• Node:

  examples/trigger-campaign-node.js

• Python:

  examples/trigger-campaign-python.py

5) Validate the plan (fast feedback loop)

Run:

bash <skill-dir>/scripts/validate-api-trigger-plan.sh .clix/api-trigger-plan.json

This validator checks:

• valid JSON

• campaign_id

  present

• dynamic_filter_keys

  is ≤ 3 and snake_case

• properties

  keys are snake_case and have valid types
• example values match declared types

• targets

  entries specify exactly one of

  project_user_id

  or

  device_id

6) Verify (Clix + end-to-end)

Minimum verification:

• Campaign is API-Triggered and

  campaign_id

  matches.
• If using dynamic audience filters, the

  trigger.*

  keys exist in the API call and match audience rules exactly.
• Trigger once with a known-good payload; confirm delivery + inspect Message Logs for rendering errors.

See

references/debugging.md

Progressive Disclosure

• Level 1: This

  SKILL.md

  (always loaded)
• Level 2:

  references/

  (load when implementing details)
• Level 3:

  examples/

  (load when copy/pasting backend code)
• Level 4:

  scripts/

  (execute directly; do not load into context)

References

• references/api-contract.md

• references/console-setup.md

• references/backend-patterns.md

• references/security-and-keys.md

• references/personalization-and-dynamic-filters.md

• references/debugging.md