Download the PHP package xavicabot/filament-activecampaign without Composer

Filament ActiveCampaign

Advanced ActiveCampaign integration for Laravel and FilamentPHP 3, focused on developer productivity.

This package allows you to:

• Sync Lists, Tags and Custom Fields from ActiveCampaign
• Create Automations based on custom events (user.registered, wallet.first_deposit, etc.)
• Subscribe contacts to Lists
• Add Tags
• Update Custom Fields
• Update System Fields (firstName, lastName, phone, etc.)
• Use dynamic templating ({user.*}, {ctx.*}, {now}, etc.)
• Log every automation execution (success, payload, warnings, errors)
• Preview the execution plan before running an automation
• Manage everything visually from FilamentPHP

🔧 Installation

Install via Composer:

Publish config and migrations:

⚙️ Configuration

Add your ActiveCampaign credentials to .env:

Published config file:

🔄 Syncing Metadata (Lists, Tags, Fields)

This package stores ActiveCampaign metadata locally:

• activecampaign_lists
• activecampaign_tags
• activecampaign_fields

Sync everything

Or individually:

From Filament

The Automations resource includes a "Sync metadata" button to refresh lists/tags/fields without CLI access.

🏷️ Creating Tags

You can create new tags either from the Filament UI or programmatically from your code.

From Filament UI

1. Navigate to ActiveCampaign Tags in Filament
2. Click the "Create Tag" button in the header
3. Fill in the form:
   • Tag Name (required) - The name as it will appear in ActiveCampaign
   • Description (optional) - Internal reference note (only used when creating new tags)
4. Submit

Smart behavior: If the tag name already exists (locally or in ActiveCampaign), it will be retrieved instead of creating a duplicate. No errors, just works!

From Code

Use the ActiveCampaign facade to create or retrieve tags programmatically:

Recommended: getOrCreateTag() (Safe, no duplicates)

What happens with getOrCreateTag():

1. Searches local database first (case-insensitive)
2. If not found locally, searches ActiveCampaign API
3. If found in AC but not locally, syncs it to local database
4. If not found anywhere, creates it in ActiveCampaign and stores locally
5. Cache automatically updated for instant use

Benefits:

• ✅ No duplicate errors
• ✅ Idempotent (safe to call multiple times)
• ✅ Handles sync automatically

Alternative: createTag() (Always creates new)

Warning: This method will fail if the tag already exists in ActiveCampaign.

Note: All tags are created with type contact (the standard type for 99% of use cases).

🧷 Managing Contact Tags & Lookup

Use the ActiveCampaign facade to manage tags on a contact and to look up existing contacts.

Tag names are resolved to ActiveCampaign IDs using the same cached lookup as addTagToContact — make sure the tag has been synced (php artisan activecampaign:sync-metadata --tags) or created beforehand.

⚡ Single-Call Field Sync

When an automation has multiple fields and/or system_fields, the package now sends them in a single POST /contact/sync request (plus the initial contact resolution call) instead of one HTTP call per field. No code change is required on the consumer side — existing automations benefit automatically.

Behavioural note: a custom field whose template references {user.*} or {ctx.*} and resolves to an empty value is now omitted from the payload (it used to be sent as an empty string). This mirrors how system_fields already behaved and prevents accidental overwrites with blank values.

📦 Filament Resources Included

⚡ Creating Automations

An Automation links:

• a custom event name
• to a set of ActiveCampaign actions

Actions available:

• Subscribe to a list
• Add tags
• Update custom fields
• Update system fields

Example automation:

🧠 Triggering Automations from Your Laravel App

Use the facade:

With context:

With another model:

Trigger without a registered user (by email)

You can also trigger automations for contacts that are not users in your system by providing an email and optional contact data. The contact will be created/synced in ActiveCampaign if it does not exist.

Basic usage:

With optional contact data and context:

Notes:

• email is required; other contact fields are optional.
• System fields defined in the automation will be synced using the provided email.
• Template placeholders {ctx.} work as usual; {user.} placeholders will be left as-is if no user is provided.

🔀 Async (Queue) Support

By default, automations run synchronously. You can enable async execution to dispatch triggers to a Laravel queue.

Configuration

In your published config/activecampaign.php:

Or use environment variables:

Usage

Option 1: Global async via config

Set async => true in config. All trigger() and triggerWithEmail() calls will automatically dispatch to the queue:

Option 2: Explicit async methods

Use triggerAsync() or triggerWithEmailAsync() to always dispatch to the queue, regardless of the async config value:

How it works

• The job serializes only primitive data (event name, user ID, email, contact data, context) — no Eloquent models are serialized.
• When a userId is provided, the job resolves the user from the database at execution time. If the user no longer exists, the job exits gracefully without errors.
• Retries and backoff are configurable via async_tries and async_backoff.

Retrocompatibility

With async => false (default), the package behaves exactly as before — all triggers execute synchronously. No changes needed in existing code.

🧩 Template Engine

Templates support:

Global

• {now} — current datetime
• {now_date} — current date

User data (supports relations)

Context data

If a value is missing → placeholder is preserved.
Objects/arrays → JSON encoded.

🔍 Preview Mode (For Testing Automations)

From Filament, you can preview an automation:

• Select a User
• Provide JSON context
• Preview the execution plan without hitting ActiveCampaign
• See:
  • list subscription
  • tags
  • field updates
  • system fields
  • rendered templates
  • warnings
  • payload

Perfect for debugging before going live.

📝 Execution Logs

Every execution is stored in:

Includes:

• automation_id
• event
• user_id
• success
• error_message
• context (JSON)
• payload (JSON)
• warnings (missing tags/fields/etc.)

Filament UI offers:

• warning icons
• JSON pretty blocks
• full detail view

🚀 Examples — Automation on User Registration

1. Create automation in Filament:

• Event: user.registered
• List: “Main List”
• Tags: “New User”
• Custom fields:
  • LANGUAGE = {user.profile.language}
• System fields:
  • firstName = {user.name}

2. Trigger from your application:

❤️ Contributing

PRs are welcome, especially for:

• new actions
• templates
• automation presets
• improvements to the runner or logging

📄 License

MIT License.