Guide d'installation WooCommerce

Architecture

Emporiqa uses your store catalog as its knowledge base: the plugin pushes products, variations, prices, stock and store pages over webhooks as you save them, so there is no separate knowledge base you have to write or keep up to date. For anything your shop pages never covered, you can write a page yourself on the Pages screen in the Emporiqa dashboard: a title and the text in your own words, in up to 10 languages on the same page. You write each language yourself, and any of them can carry a link to the same page on your site. The chat answers from it like it answers from any page your shop sent, and a sync never overwrites it. Up to 25 pages per store. On the Products screen you can set up to 50 products to Promoted or Top: the chat shows them first when they match what the shopper asked, Top before Promoted, and never shows them for unrelated questions. A sync never clears it.

The plugin listens to WooCommerce and WordPress hooks (woocommerce_update_product, save_post, woocommerce_order_status_completed, etc.) and sends webhook events to Emporiqa using deferred delivery: product and page events are queued during the request and flushed on shutdown, while order conversion events are scheduled via Action Scheduler. Saving a product completes locally; the webhook delivery runs asynchronously after the response.

All translations and channels for a single product or page consolidate into one webhook event. Variable products sync the parent plus each variation, and changes cascade: saving a variation triggers a parent re-sync so search always sees the full catalog state. The plugin declares WooCommerce High-Performance Order Storage (HPOS) compatibility.

Requirements

Configuration reference

All settings live at Settings → Emporiqa. Connection Settings is the main section and is expanded by default. Sync toggles and advanced settings (languages, webhook URL, batch size) are collapsed under Advanced.

Connection settings

Advanced settings

Most stores don't need to change these.

Always-on capabilities

• Cart operations: add, update, remove from inside the chat via AJAX endpoints that talk directly to WooCommerce's cart.
• Conversion tracking: chat sessions linked to completed orders for revenue attribution.
• Multi-currency: detects the active currency from WOOCS, WPML Multi-Currency, WooCommerce Payments, and Aelia Currency Switcher; override with the emporiqa_active_currency filter.

Features

Webhook payload

Each product or page is sent as a single webhook event containing all languages and channels. Translatable fields are nested by channel and language code.

Product event

{
  "type": "product.updated",
  "data": {
    "identification_number": "product-42",
    "sku": "SKU-001",
    "channels": ["default"],
    "names":        {"default": {"en": "Hiking Boots", "de": "Wanderschuhe"}},
    "descriptions": {"default": {"en": "Waterproof leather boots...", "de": "Wasserdichte Lederstiefel..."}},
    "links":        {"default": {"en": "https://store.com/hiking-boots", "de": "https://store.com/de/wanderschuhe"}},
    "categories":   {"default": {"en": ["Footwear > Hiking"], "de": ["Schuhe > Wandern"]}},
    "attributes":   {"default": {"en": {"Material": "Leather"}, "de": {"Material": "Leder"}}},
    "brands":       {"default": "TrailPeak"},
    "prices":       {"default": [{"currency": "EUR", "current_price": 129.99, "regular_price": 149.99}]},
    "images":       {"default": ["https://store.com/wp-content/uploads/boots-front.jpg"]},
    "availability_statuses": {"default": "available"},
    "stock_quantities":      {"default": 42},
    "min_order_quantities":  {"default": 1},
    "max_order_quantities":  {"default": null},
    "available_for_order": true,
    "condition": null,
    "is_virtual": false,
    "is_parent": false,
    "parent_sku": null,
    "variation_attributes": {}
  }
}

Field structure

Customization filters

The plugin exposes WordPress filters you can hook from a custom plugin or your theme's functions.php to control sync behavior and modify data before it's sent.

Example: skip draft products

add_filter('emporiqa_should_sync_product', function ($should_sync, $product) {
    if (str_contains($product->get_name(), '[DRAFT]')) {
        return false;
    }
    return $should_sync;
}, 10, 2);

Example: add a custom attribute to the product payload

// Attributes are nested: {channel: {lang: {key: value}}}.
add_filter('emporiqa_product_data', function ($data, $product) {
    foreach ($data['attributes'] as $channel => &$languages) {
        foreach ($languages as $lang => &$attrs) {
            $attrs['material'] = get_field('material', $product->get_id());
        }
    }
    return $data;
}, 10, 2);

WP-CLI commands

The plugin registers a wp emporiqa command for automation and debugging. A reference is also available in the plugin's Sync tab.

# Sync all products
wp emporiqa sync-products

# Sync all pages
wp emporiqa sync-pages

# Full sync (products + pages)
wp emporiqa sync-all

# Test webhook connection (also available as a button in the Sync tab)
wp emporiqa test-connection

# Adjust batch size for large catalogs
wp emporiqa sync-products --batch-size=25

When to run a full sync

Price, stock and status changes reach Emporiqa as you save them, because each save fires a webhook. A few kinds of edit do not fire one, so the catalog in the chat can drift until you run a full sync. Run Sync All from the plugin's Sync tab, or wp emporiqa sync all, after any of these:

• A bulk import or update that writes products through CSV, REST or direct SQL rather than the normal save path.
• Renaming a category or an attribute, which changes many products at once without re-saving each one.
• Changing your store currency, or tax rates that alter displayed prices.
• Adding a language, or enabling a new WPML or Polylang translation set.
• An extended outage on the Emporiqa side, where queued webhooks may not have been delivered.

Running it more often than needed costs nothing beyond the time it takes. A weekly full sync is a reasonable safety net for a busy catalog.

Order status

The ready-made Order status rule answers "Where is my order?" in the chat. Emporiqa asks your shop through the plugin's signed order_status endpoint and tells the shopper the status, the order date and, when there is one, the tracking number (WooCommerce Shipment Tracking and Advanced Shipment Tracking are read when installed). It needs plugin version 1.2.0 or newer.

What the shopper sees, what your team gets and how to write your own rules: Rules guide.

Set it up

1. In WordPress, open Settings → Emporiqa. Once connected, it shows a Ready-made rules section with the Order status address and a Copy button. If the section is not there yet, click Test Connection on the Sync tab.
2. Click Open in Emporiqa next to Order status. Your Emporiqa dashboard opens at Settings → Rules with Order status highlighted. Click Add.
3. Click Try it and ask about one of your recent orders. When it answers correctly, click Go live.

If you connected with Connect to Emporiqa, there is nothing to copy: Emporiqa fills in your shop's address itself and checks it with your shop. If it ever asks for the address, paste the Order status address the plugin shows, which looks like this:

What the shopper gives

• Signed in to your shop: only the order number. The plugin answers only for that customer's own orders.
• Guest: the order number and the email used for the order.

Endpoint

Signed-in customers

When a shopper is signed in to your store, the chat shows them their own prices and uses their account when it hands the conversation to your team. There is nothing to set up: it starts once the plugin is on the versions below. Guests see your public prices, as before.

• Their own prices, version 1.2.0 or newer: the price WooCommerce calculates for that customer, including role and wholesale prices set through WooCommerce's price filters. The chat asks your store through the signed customer_prices action when it shows a product, and shows the answer to that customer only, on the cards, in quotes and in the product details. Coupons and cart rules apply at your checkout, as before, and a search with a price limit ("under 200") is applied to what the customer pays.
• Their name and email, version 1.2.2 or newer (the Customer info action): the chat greets them by first name, and a handoff reaches your team with the name and email on their account, so they are not asked for them.

Both answer only for the customer the plugin signed in for this store, and only on that customer's own messages: a shopper who signs out is a guest from their next message. Per customer, prices are kept for 5 minutes and the account details for 30. Each customer is limited to 30 requests and each store to 600 every 10 minutes.

Customer info action

From version 1.2.2 the plugin answers a signed customer_info request about a shopper who is signed in to your shop: the name and email on their account and their 10 newest orders (number, date, status, total and currency). Only that customer's own placed orders are listed, never a checkout draft, an address, a phone number or anyone else's orders. With it, a signed-in shopper who asks "where is my order?" without a number gets their newest order, as long as the Order status rule is on; there is nothing to set up.

Requests are signed like Order status and limited to 30 per customer and 600 per site every 10 minutes. To remove a field or add your own under extra, use the emporiqa_customer_info_data filter, which runs after the answer is built:

add_filter('emporiqa_customer_info_data', function ($data, $user) {
    unset($data['customer']['email']);
    $data['extra']['loyalty_points'] = (int) get_user_meta($user->ID, 'loyalty_points', true);
    return $data;
}, 10, 2);

Troubleshooting