Magento Setup Guide

Architecture

The module observes Magento events (catalog_product_save_after, catalog_product_delete_before, cms_page_save_after, cms_page_delete_before, checkout_submit_all_after, and inventory events) and pushes webhook events to Emporiqa via Magento's DB message queue. Saving a product never blocks on the network — the observer publishes a message; emporiqa.webhook.consumer processes it asynchronously.

All translations and channels for a single product or page consolidate into one webhook event. Configurable products cascade up: editing a child variation triggers a parent re-sync so search always sees the full catalog state. Stock changes (orders, cancellations, credit memos, shipments) flow through a separate emporiqa.stock.sync.consumer queue.

Channels are derived automatically from the Magento website code, and salable quantity uses Multi-Source Inventory when available with automatic fallback to legacy stock.

Requirements

Configuration Reference

All settings live at Stores → Configuration → Emporiqa → Chat Assistant. The Sync Dashboard at Emporiqa → Sync Dashboard is for triggering full syncs and testing connection.

General Settings

Advanced

Most stores don't need to change these.

Always-on capabilities

• Order tracking — always active with HMAC signature verification and billing-email matching. Paste the Order Tracking URL into the Emporiqa dashboard to enable lookups from chat.
• Cart operations — customers can add, update, and remove items from inside the chat via the /rest/V1/emporiqa/cart/* REST endpoints. When the customer is ready to check out, the widget redirects them to your Magento checkout page.
• Conversion tracking — sales_order_save_after observer links chat sessions to completed orders for revenue attribution.
• Multi-channel — channel auto-derived from Magento website code.

Features

Webhook Payload

Each product or CMS 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-123",
    "sku": "PROD-123",
    "channels": ["base"],
    "names":        {"base": {"en-us": "Summer Jacket", "de-de": "Sommerjacke"}},
    "descriptions": {"base": {"en-us": "Lightweight jacket...", "de-de": "Leichte Jacke..."}},
    "links":        {"base": {"en-us": "https://store.com/summer-jacket", "de-de": "https://store.com/de/sommerjacke"}},
    "attributes":   {"base": {"en-us": {"Material": "Cotton"}, "de-de": {"Material": "Baumwolle"}}},
    "categories":   {"base": {"en-us": ["Jackets", "Summer"], "de-de": ["Jacken", "Sommer"]}},
    "brands":       {"base": "TrailPeak"},
    "prices":       {"base": [{"currency": "EUR", "current_price": 79.99, "regular_price": 99.99}]},
    "availability_statuses": {"base": "available"},
    "stock_quantities":      {"base": 42},
    "images":       {"base": ["https://store.com/media/catalog/product/jacket.jpg"]},
    "is_parent": false,
    "parent_sku": null,
    "variation_attributes": {}
  }
}

For configurable products, the parent is synced with is_parent: true and variation_attributes: {"base": {"en-us": ["Color", "Size"], "de-de": ["Farbe", "Größe"]}}. Each child variation is synced with parent_sku referencing the parent's SKU.

CMS Page Event

{
  "type": "page.updated",
  "data": {
    "identification_number": "page-45",
    "channels": ["base"],
    "titles":   {"base": {"en-us": "Shipping Policy"}},
    "contents": {"base": {"en-us": "Free shipping on orders over..."}},
    "links":    {"base": {"en-us": "https://store.com/shipping-policy"}}
  }
}

Magento CMS pages don't have per-store-view attributes — translations are handled by creating separate page entities assigned to different store views. Each page is exported only for the store views it belongs to.

Field Structure

Customization

The module follows standard Magento 2 extensibility patterns. To customize sync behavior, the formatted payload, or the order tracking response, use plugins, preferences, or observers in your own module.

Example: skip a product from sync

// app/code/Vendor/Module/etc/di.xml
<type name="Emporiqa\ChatAssistant\Model\ProductFormatter">
    <plugin name="vendor_skip_internal_products"
            type="Vendor\Module\Plugin\SkipInternalProductsPlugin"
            sortOrder="10"/>
</type>

// app/code/Vendor/Module/Plugin/SkipInternalProductsPlugin.php
public function aroundFormat(
    \Emporiqa\ChatAssistant\Model\ProductFormatter $subject,
    callable $proceed,
    \Magento\Catalog\Api\Data\ProductInterface $product
) {
    if ($product->getData('is_internal')) {
        return null; // skip
    }
    return $proceed($product);
}

Example: enrich the product payload

public function afterFormat(
    \Emporiqa\ChatAssistant\Model\ProductFormatter $subject,
    ?array $result,
    \Magento\Catalog\Api\Data\ProductInterface $product
): ?array {
    if ($result === null) {
        return $result;
    }
    $result['data']['custom_field'] = $product->getData('my_custom_attribute');
    return $result;
}

CLI Commands

All commands run from the Magento root directory.

# Sync all products
bin/magento emporiqa:sync:products

# Sync all CMS pages
bin/magento emporiqa:sync:pages

# Sync products and pages in one command
bin/magento emporiqa:sync:all

# Test webhook connection
bin/magento emporiqa:test-connection

# Adjust batch size
bin/magento emporiqa:sync:products --batch-size=25

# Dry run (no webhooks sent)
bin/magento emporiqa:sync:products --dry-run

# Start the webhook consumer manually
bin/magento queue:consumers:start emporiqa.webhook.consumer

Sync Sessions

Each sync operation creates a session that tracks what was sent:

1. sync.start — opens a session (with session_id and entity).
2. Batched events — product/page data tagged with sync_session_id.
3. sync.complete — closes the session. Items not seen during the session are marked deleted on the backend.

Sessions expire after 24 hours. For very large catalogs, lower --batch-size to fit completion within the window.

Order Tracking

Emporiqa can look up order status on behalf of customers during chat conversations. The module exposes a signed REST endpoint that Emporiqa calls when a customer asks about their order.

Flow

1. Customer asks “Where is my order #12345?” in the chat.
2. Emporiqa sends an HMAC-SHA256 signed POST to your store.
3. The module looks up the order, verifies the customer's email matches the billing email, and returns the status.
4. The salesperson presents the order information to the customer.

Endpoint

Setup

The endpoint is always active once the module is installed. Email verification is always required — the customer's email must match the order's billing email before any data is returned. To enable order lookup from chat, set the Order Tracking API URL in your Emporiqa dashboard (Store Settings → Integration) to:

Troubleshooting