Etherlabz Intercom Sync

The complete Intercom integration for WooCommerce. Customers, orders, cart funnel, abandoned carts, subscriptions, purchase tags — and a HMAC-secured Messenger embed. All in one plugin, all open source.

Why this plugin

Most Intercom integrations stop at "sync the customer record." That's table stakes. Where Intercom actually drives revenue is in the front-end funnel — browse abandonment, cart recovery, post-purchase nurture — and in Fin AI answering "where is my order?" without a human in the loop.

This plugin closes the entire loop, end-to-end:

• Server-side sync so contact records are always fresh
• Front-end events so Intercom Series can react to behaviour
• Cart-abandonment cron so recovery campaigns fire automatically
• Purchase-based tagging so segments build themselves
• Fin REST endpoints so the AI can answer order questions in real time
• HMAC-secured Messenger embed so identity verification is solved out of the box

No Composer dependencies at runtime. No npm. No build step. Drop it in wp-content/plugins/ and activate.

Features at a glance

Requirements

No Composer, no npm, no build step at runtime. Composer is only used for the dev toolchain (PHPCS + PHPUnit).

Installation

From a release ZIP

1. Download the latest ZIP from the Releases page.
2. WP Admin → Plugins → Add New → Upload Plugin → pick the ZIP.
3. Activate Etherlabz Intercom Sync.
4. Open Intercom Sync in the admin sidebar.
5. Paste your Intercom Access Token and click Test Connection.

From source

cd wp-content/plugins
git clone https://github.com/EtherLabZ/intercom-sync-plugin-wordpress.git etherlabz-intercom-sync
cd etherlabz-intercom-sync
composer install   # only needed for tests / lint

Then activate as above.

Setup checklist

After activation, walk through this once:

1. Settings tab → paste Access Token, hit Test Connection (must show ✓).
2. (Optional) Paste your Identity Verification Secret — required for HMAC on the Messenger.
3. (Optional) Paste your Intercom App ID + flip Embed Intercom Messenger on if you want the chat widget on the public site.
4. Pick which capabilities to enable (all default off except guest-checkout sync):
   • Track Cart & Funnel Events — fires product-viewed, cart-added, coupon-applied, checkout-started
   • Abandoned Cart Detection — hourly cron + minutes threshold
   • WooCommerce Subscriptions Events — needs WC Subscriptions
   • Auto-Tag Customers by Purchase — purchased-{slug} and purchased-category-{slug}
5. Fin / Data tab → Register Attributes in Intercom (one click, idempotent).
6. (For Fin) Generate API Key and configure your Intercom Custom Action with the URLs shown.

Where to get the credentials

Architecture

A small, modern, no-magic codebase:

• Namespaced PHP (Etherlabz\Intercom_Woo_Sync) with declare(strict_types=1) everywhere.
• PSR-4 autoloading via a custom 30-line loader — zero Composer runtime deps.
• Singleton bootstrap (Main) wires every module exactly once.
• Registrable interface — every module has one register_hooks() entry point.
• WP_Error returns from every API call so callers can distinguish 401, 422, 500 cleanly.
• HPOS-ready via FeaturesUtil::declare_compatibility('custom_order_tables').

etherlabz-intercom-sync/
├── intercom-woo-sync.php           Plugin bootstrap + header
├── uninstall.php                    Clean removal of all options + crons
├── inc/
│   ├── Autoloader.php              PSR-4 autoloader (no Composer)
│   ├── Main.php                    Singleton + module registry
│   ├── Contracts/
│   │   ├── Registrable.php         interface { register_hooks(): void }
│   │   └── Singleton.php           shared singleton trait
│   ├── Core/
│   │   ├── Assets.php              Admin CSS/JS enqueue + i18n strings
│   │   └── Encryption.php          AES-256-CBC token storage
│   └── Modules/
│       ├── Intercom_API.php        Intercom v2.10 REST wrapper (WP_Error returns)
│       ├── Customer_Sync.php       Contact upsert on WC customer change
│       ├── Order_Events.php        Order events + line items + guest checkout
│       ├── Cart_Events.php         product-viewed / cart-added / checkout-started
│       ├── Cart_Abandonment.php    Hourly cron for abandoned-cart event
│       ├── Subscription_Events.php WC Subscriptions lifecycle events
│       ├── Tag_Manager.php         purchased-{slug} tagging on completion
│       ├── Messenger.php           Intercom Messenger embed + HMAC user_hash
│       ├── Bulk_Sync.php           WP-Cron batch resync
│       ├── Fin_Connector.php       REST endpoints + bearer-key auth for Fin
│       ├── Ajax_Handler.php        Admin UI AJAX endpoints
│       └── Settings/
│           ├── Admin_Screen.php    Top-level admin menu page
│           └── Settings.php        Settings API: register + sanitize + render
├── templates/admin-screen.php      Tabbed admin UI (Settings / Bulk / Fin / Log)
└── assets/{css,js}/admin.{css,js}  Scoped styles + jQuery-built UI

Filter hooks (extensibility surface)

Every payload that crosses into Intercom is filterable. Use these to add custom attributes, redact PII, route through your own enrichment pipeline, etc.

Example — add a VIP attribute to every contact synced:

add_filter( 'etherlabz_intercom_contact_payload', function ( array $data, WC_Customer $customer ) {
    if ( (float) $customer->get_total_spent() > 1000 ) {
        $data['custom_attributes']['vip'] = true;
    }
    return $data;
}, 10, 2 );

Example — strip PII from order events:

add_filter( 'etherlabz_intercom_order_event_metadata', function ( array $metadata ) {
    unset( $metadata['line_items'] ); // omit per-product breakdown
    return $metadata;
} );

Fin AI: order lookup REST endpoints

Authenticated with a Bearer key (generated on the Fin / Data tab):

GET /wp-json/etherlabz-intercom/v1/orders?email={email}
GET /wp-json/etherlabz-intercom/v1/orders/{id}
GET /wp-json/etherlabz-intercom/v1/customer?email={email}

Authorization: Bearer <your-fin-api-key>

Configure these as a Custom Action in Intercom (Settings → AI Agent → Custom Actions). The setup guide is rendered in-product on the Fin / Data tab once you generate a key.

Development

composer install     # install dev tools (PHPCS, PHPUnit, Brain\Monkey, Mockery)
composer lint        # PHPCS — WordPress + VIP + PHPCompatibility (must exit 0)
composer lint:fix    # PHPCBF auto-fixes
composer test        # PHPUnit — currently 80 tests, 125 assertions, all green
composer build       # bash bin/build.sh — produces dist/etherlabz-intercom-sync-X.Y.Z.zip

The Makefile wraps the same commands plus releases:

make check           # lint + test
make build           # production ZIP
make release         # build + create draft GitHub release
make release-publish # build + publish immediately

Releases are also automated on tag push via .github/workflows/release.yml. See RELEASING.md for the full procedure.

Testing

The unit-test suite mocks WordPress + WooCommerce via Brain\Monkey and Mockery, so it runs in isolation against plain PHP — no full WordPress test environment required.

composer test
# 80 / 80 tests, 125 assertions, ~130 ms

Coverage focuses on the pure-logic surfaces: encryption round-trip, settings sanitization, HMAC generation, line-item extraction, tag computation, abandonment thresholds, and the WP_Error pathways through the API wrapper.

Security model

• Tokens and secrets are encrypted at rest in wp_options with AES-256-CBC keyed off AUTH_KEY / AUTH_SALT.
• All admin AJAX endpoints require manage_options capability and a wp_create_nonce check.
• Front-end Messenger uses HMAC-SHA256 (user_hash) when an Identity Verification Secret is configured, preventing contact impersonation.
• The Fin REST connector is gated by a per-install Bearer key generated client-side and never displayed in plaintext after the first reveal.
• Uninstall removes every etherlabz_intercom_ option and clears every etherlabz_intercom_*_cron schedule.

License

GPL-2.0-or-later. Use it, fork it, ship it.

Built with ♥ by Etherlabz GitHub · Issues · Releases · Discord