Magento Einrichtungsanleitung

Architecture

Emporiqa uses your store catalog as its knowledge base: the module pushes products, variations, prices, stock and CMS 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.

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 sends changes to Emporiqa through Magento's DB message queue. A product or page save queues only its ID on emporiqa.sync.live; the consumer loads, formats and sends it, so the save doesn't wait for formatting or delivery, and a retried message always sends current data. Deletions, stock-only updates and order events go through emporiqa.webhook.consumer. A full sync queues the catalog's IDs in chunks on emporiqa.sync.full (see Sync Sessions).

Nothing is dropped when Emporiqa is briefly unavailable. On HTTP 429 (or 503 with Retry-After) the consumer waits as long as it is asked, server and network errors are retried with growing back-off, and only permanent failures (bad credentials, an unknown store, an event rejected as invalid) are given up on and shown on the Sync Dashboard.

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 status: the signed endpoint behind the ready-made Order status rule. Add the rule in Emporiqa under Settings → Rules (or click Open in Emporiqa under Ready-made rules); see Order status. The older order tracking endpoint was removed in version 1.4.1.
• 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: checkout_submit_all_after and sales_order_place_after observers link chat sessions to placed 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},
    "min_order_quantities":  {"base": 1},
    "max_order_quantities":  {"base": null},
    "available_for_order": true,
    "condition": null,
    "is_virtual": false,
    "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 status answer, use plugins, preferences, or observers in your own module.

Declare the plugin in your module's global etc/di.xml, not in etc/frontend/di.xml or etc/adminhtml/di.xml: the sync runs from the queue consumers (cron) and the CLI, so an area-specific plugin would not apply. Keep plugins idempotent. Saving a configurable variation re-formats its parent, so the same events can pass through your plugin twice.

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

Example: skip a product from sync

Return an empty list, never null: format() is declared to return an array, and a null makes Magento throw. A skipped product is left out of full syncs, so Emporiqa removes it when the next full sync completes.

public function aroundFormat(
    \Emporiqa\ChatAssistant\Model\ProductFormatter $subject,
    callable $proceed,
    \Magento\Catalog\Model\Product $product,
    bool $isNew = false
): array {
    if ($product->getData('is_internal')) {
        return [];
    }
    return $proceed($product, $isNew);
}

Example: enrich the product payload

public function afterFormat(
    \Emporiqa\ChatAssistant\Model\ProductFormatter $subject,
    array $events,
    \Magento\Catalog\Model\Product $product
): array {
    foreach ($events as &$event) {
        if (($event['data']['identification_number'] ?? '') === 'product-' . $product->getId()) {
            $event['data']['custom_field'] = $product->getData('my_custom_attribute');
        }
    }
    unset($event);
    return $events;
}

Example: hide prices shown only after login

The sync sends the guest price the store has for each product. If your store hides prices from guests (a “hide price” or “call for price” extension, Adobe Commerce category permissions), remove them from the payload so the chat does not show them. Replace isPriceHidden() with the rule your store uses.

public function afterFormat(
    \Emporiqa\ChatAssistant\Model\ProductFormatter $subject,
    array $events
): array {
    foreach ($events as &$event) {
        if ($this->isPriceHidden($event['data']['identification_number'] ?? '')) {
            foreach (array_keys($event['data']['prices'] ?? []) as $channel) {
                $event['data']['prices'][$channel] = [];
            }
        }
    }
    unset($event);
    return $events;
}

CLI Commands

All commands run from the Magento root directory.

# Queue a full product sync, then send chunks from this process until it ends
# (running queue consumers help in parallel; Ctrl+C only stops watching)
bin/magento emporiqa:sync:products

# Queue only and exit; the queue consumers send it in the background
bin/magento emporiqa:sync:products --async

# Progress of the current or last sync, or cancel a running one
bin/magento emporiqa:sync:products --status
bin/magento emporiqa:sync:products --cancel

# Format everything without sending anything
bin/magento emporiqa:sync:products --dry-run

# The same for CMS pages, or products then pages in one command
bin/magento emporiqa:sync:pages
bin/magento emporiqa:sync:all

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

# Start the consumers manually (production cron does this for you)
bin/magento queue:consumers:start emporiqa.sync.full.consumer
bin/magento queue:consumers:start emporiqa.sync.live.consumer
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. The module queues the IDs in chunks of 50 products (25 pages) and the consumers send them.
3. sync.complete: closes the session. Items not seen during the session are marked deleted on the backend. The module sends it only after every chunk was delivered; if any chunk failed, the session stays open and nothing is deleted.

Sessions expire after 24 hours, so a run must finish within 23. For catalogs of hundreds of thousands of products, run several full-sync consumers in parallel with 'cron_consumers_runner' => ['multiple_processes' => ['emporiqa.sync.full.consumer' => 4]] in app/etc/env.php. A new sync is accepted once a cancelled or failed one has been idle for an hour.

Order status

The ready-made Order status rule answers "Where is my order?" in the chat. Emporiqa asks your store through the module's signed order_status endpoint and tells the shopper the status, the order date and, when there is one, the tracking link. Only orders of the enabled store views are found. It needs module version 1.4.0 or newer.

Set it up

1. In the admin, open Stores → Configuration → Emporiqa → Chat Assistant. Once connected, it shows a Ready-made rules group with the Order status address and a Copy button. If the group is not there yet, run Test Connection on Emporiqa → Sync Dashboard.
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 module shows, which looks like this:

From version 1.4.1 the address is on Magento's REST API. Version 1.4.0 used /emporiqa/action/, which keeps working; click Connect again to move to the REST address. If a firewall or proxy filters /rest/, allow /rest/V1/emporiqa/action/.

What the shopper gives

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

Endpoint

When Magento does not render your storefront

If shoppers browse a separate frontend and Magento's own storefront is switched off, version 1.4.1 of the module covers this much:

• Set Storefront base URL (Stores → Configuration → Emporiqa → Chat Assistant → Storefront address, per store view) so product and CMS page links point to your frontend. The path stays Magento's (URL key and suffix), so your frontend must open products at those paths. Images stay on Magento.
• Add the chat to your frontend with the embed code; Magento's layout cannot add it there.
• Order status works over Magento's REST API for guests (order number and email). The chat cannot recognise signed-in shoppers there, so customer prices and lookups by order number alone are not available, and in-chat cart changes need Magento's own pages.
• Test Connection warns when product links or the Order status address answer 404.

Troubleshooting