Guide d'installation Magento

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. 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 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.

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

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.

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 module is on the versions below. Guests see your public prices, as before.

• Their own prices, version 1.4.0 or newer: customer-group prices, tier prices, special prices and catalog price rules, as Magento calculates them in the customer's website. They come from Magento's own price calculation for that customer, so extensions that plug into that calculation apply too. Adobe Commerce B2B shared catalogs and company accounts are not supported yet. 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.4.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 module 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.4.2 the module answers a signed customer_info request about a shopper who is signed in to your store: the name and email of their customer account (never an order's) and up to 10 of the account's own orders in the enabled store views, newest first (order number, date, status, total and currency). Guest orders placed with the same email, carts, addresses, phone numbers and customer groups are never included. 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 store every 10 minutes. To remove a key or add your own under extra, observe the emporiqa_customer_info_data event (with customer, orders and transport), which runs after the answer is built:

public function execute(\Magento\Framework\Event\Observer $observer): void
{
    $transport = $observer->getData('transport');
    $data = $transport->getData('data');
    unset($data['customer']['email']);
    $data['extra']['loyalty_tier'] = 'Gold';
    $transport->setData('data', $data);
}

Updating and uninstalling

After updating the module (for version 1.4.2 this is required, not optional), run:

bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Then, once after updating to 1.4.2, run a full product sync and a full page sync (Sync Products and Sync Pages on the Emporiqa → Sync Dashboard). The product sync corrects bundle and grouped products that were sent as out of stock; the page sync removes the 404 and "Enable Cookies" pages, and pages without text, that earlier versions sent.

To remove the module and everything it stored (settings, its emporiqa_* tables and order columns), run bin/magento module:uninstall --remove-data Emporiqa_ChatAssistant. Before version 1.4.2 Magento skipped this cleanup.

Troubleshooting