Sylius Setup Guide

Architecture

Emporiqa uses your store catalog as its knowledge base: the plugin pushes products, variants, 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 is a Symfony bundle that hooks into Sylius via resource events (sylius.product.post_update, sylius.product_variant.post_update, etc.), Doctrine lifecycle events for page entities, and the Sylius checkout workflow (Symfony Workflow on 2.x, Winzou state machine on 1.x) for conversion tracking.

Webhook events use deferred delivery: event subscribers queue payloads in an in-memory WebhookEventQueue with deduplication, and the queue flushes to Emporiqa on kernel.terminate after the HTTP response is sent. Saving a product or completing checkout completes synchronously while the outbound HTTP call runs asynchronously. From version 1.11.1 a product or page batch Emporiqa did not accept (unreachable, or a wrong secret after a change) is kept in cache.app and sent first with the next request's changes; a newer change to the same product or page replaces the kept one. At most 500 events are kept, for at most 7 days, and a completed full sync clears them. A batch refused for its content (HTTP 400 or 413) is not kept.

All translations and channels for a single product or page consolidate into one webhook event. Variant changes cascade to the parent: editing a variant triggers a parent re-sync so search always sees the full catalog state. Every service that formats, resolves, looks up, or transports data ships behind an interface so you can decorate any part of the pipeline without patching plugin code.

Requirements

Checked with plugin 1.11.0 on Sylius 2.3 (Symfony 8.1, PHP 8.4), Sylius 2.2 (Symfony 7.4, PHP 8.3) and Sylius 1.12 (Symfony 6.4, PHP 8.1). Sylius 1.12 and 1.13 no longer get security fixes, and a current Composer refuses to install them unless their advisories are ignored.

Configuration Reference

Configuration lives in config/packages/emporiqa.yaml. Only store_id, webhook_url, and webhook_secret are required. Everything else has sensible defaults.

Settings

Full configuration example

# config/packages/emporiqa.yaml
emporiqa:
    store_id: '%env(EMPORIQA_STORE_ID)%'
    webhook_url: '%env(EMPORIQA_WEBHOOK_URL)%'
    webhook_secret: '%env(EMPORIQA_WEBHOOK_SECRET)%'
    base_url: 'https://myshop.com'
    media_base_path: '/media/image/'
    brand_attribute_code: 'brand'
    min_order_quantity_attribute: 'min_order_qty'
    enabled_languages: ['en_US', 'de_DE']
    sync:
        products: true
        pages: true
    page_entity_classes:
        - App\Entity\StaticPage
        - App\Entity\BlogPost
    cart:
        enabled: true

Channels

The plugin uses the Sylius channel code directly as the Emporiqa channel identifier, no mapping configuration needed. Each channel's pricing, availability, and translations are consolidated into the same webhook event.

Features

Webhook Payload

Webhook requests are POSTed to the configured webhook_url with an X-Webhook-Signature header containing the HMAC-SHA256 signature of the raw body. Each request carries a batch of events.

Batch envelope

{
  "events": [
    {"type": "product.updated", "data": {...}},
    {"type": "product.updated", "data": {...}}
  ]
}

Event types

Product event

{
  "type": "product.updated",
  "data": {
    "identification_number": "product-123",
    "sku": "PROD-123",
    "channels": ["", "b2b"],
    "names":        {"": {"en_US": "Product Name", "de_DE": "Produktname"}, "b2b": {"en_US": "Product Name"}},
    "descriptions": {"": {"en_US": "Description...", "de_DE": "Beschreibung..."}},
    "links":        {"": {"en_US": "https://store.com/en_US/products/product-name", "de_DE": "https://store.com/de_DE/products/produktname"}},
    "categories":   {"": {"en_US": ["Electronics"], "de_DE": ["Elektronik"]}, "b2b": {"en_US": ["Electronics"]}},
    "attributes":   {"": {"en_US": {"Color": "Blue"}, "de_DE": {"Farbe": "Blau"}}},
    "brands":       {"": "Brand Name", "b2b": "Brand Name"},
    "prices":       {"": [{"currency": "EUR", "current_price": 79.99, "regular_price": 99.99}], "b2b": [{"currency": "USD", "current_price": 69.99, "regular_price": 89.99}]},
    "images":       {"": ["https://store.com/media/image/product.jpg"]},
    "availability_statuses": {"": "available", "b2b": "available"},
    "stock_quantities":      {"": 25, "b2b": 25},
    "min_order_quantities":  {"": 1, "b2b": 1},
    "max_order_quantities":  {"": null, "b2b": null},
    "available_for_order": true,
    "condition": null,
    "is_virtual": false,
    "parent_sku": null,
    "is_parent": false,
    "variation_attributes": {}
  }
}

Field structure

For variable products, the parent ships with is_parent: true and variation_attributes containing translated option names. Each variant ships separately with parent_sku set and variation_attributes: {}. Delete events contain only identification_number.

Customization

Every behavior customization goes through standard Symfony mechanisms: service decoration for replacing pipeline components, and event listeners for reacting to the sync lifecycle. No plugin code gets patched.

Service interfaces you can decorate

Symfony events you can listen to

Example: add a carrier tracking link to Order status

namespace App\EventListener;

use Emporiqa\SyliusPlugin\Event\OrderStatusEvent;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;

#[AsEventListener(event: OrderStatusEvent::NAME)]
class TrackingLinkListener
{
    public function __invoke(OrderStatusEvent $event): void
    {
        $data = $event->getData();

        foreach ($data['tracking'] as &$parcel) {
            $parcel['url'] = 'https://track.example.com/?n=' . rawurlencode($parcel['number']);
        }

        $event->setData($data);
    }
}

Example: mutate product data before send

namespace App\EventListener;

use Emporiqa\SyliusPlugin\Event\PostFormatEvent;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;

#[AsEventListener(event: PostFormatEvent::NAME)]
class ExtraProductFieldsListener
{
    public function __invoke(PostFormatEvent $event): void
    {
        $events = $event->getFormattedEvents();

        foreach ($events as &$webhookEvent) {
            $webhookEvent['data']['sustainability_score'] = 'A+';
        }

        $event->setFormattedEvents($events);
    }
}

Page sync setup

Implement Emporiqa\SyliusPlugin\Model\PageInterface on your page entity (the translations must expose getTitle(), getContent(), getSlug(), getLocale()), list its FQCN under page_entity_classes, and decorate PageUrlResolverInterface to emit real URLs. Without the decorator, the default resolver returns an empty string.

Console Commands

All commands use memory-efficient batching and can run in reconciliation sessions. Items not seen during the session can be marked deleted on the Emporiqa side.

Shared flags

# Full reconciliation
bin/console emporiqa:sync:all

# Products only, small batches, no session markers
bin/console emporiqa:sync:products --batch-size=25 --no-session

# Validate payload without sending
bin/console emporiqa:sync:products --dry-run

# End-to-end connection test
bin/console emporiqa:test-connection -v

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 the tracking number of each shipment. It needs plugin version 1.11.0 or newer.

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

Set it up

1. Set framework.router.default_uri to your shop's https address. Emporiqa only calls https addresses.
2. Run bin/console emporiqa:test-connection. Under Ready-made rules it prints your Order status address and whether the rule is On.
3. In your Emporiqa dashboard, open Settings → Rules and add Order status. It asks for this address: paste it there, then click the link Emporiqa emails you to confirm it.
4. Click Try it and ask about one of your recent orders. When it answers correctly, click Go live.

The Order status address 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

Status mapping

Cart and Checkout

The plugin exposes a REST API for in-chat cart operations, so the shopper can add what the chat recommended and walk to checkout without leaving the conversation. The chat widget calls it through window.EmporiqaCartHandler, registered by the bundled emporiqa-cart.js.

Endpoints

Cart response

Every cart endpoint returns the same JSON shape.

{
  "success": true,
  "checkoutUrl": "https://store.com/checkout",
  "cart": {
    "items": [
      {
        "product_id": "product-123",
        "variation_id": "variation-456",
        "name": "Product Name",
        "quantity": 1,
        "unit_price": 29.99,
        "image_url": "https://store.com/media/image/product.jpg",
        "product_url": "https://store.com/products/product-name"
      }
    ],
    "item_count": 1,
    "total": 29.99,
    "currency": "EUR"
  }
}

Add items request

{
  "items": [
    {"variation_id": 456, "quantity": 2}
  ]
}

EmporiqaCartHandler

The emporiqa-cart.js script registers window.EmporiqaCartHandler, which the embed script calls for cart operations. It handles:

• Action routing: add, update, remove, clear, view, checkout.
• ID extraction: strips prefixes from IDs ("variation-456" → 456).
• Response normalization: returns consistent {success, error, checkoutUrl, cart} objects.

Disabling the cart API

emporiqa:
    cart:
        enabled: false

With the cart disabled, the CartController and OrderCompleteSubscriber services are removed from the container.

Order Completion

When a customer completes checkout, the plugin sends an order.completed webhook to Emporiqa so the sale can be attributed to the conversation that produced it.

Flow

1. The Emporiqa embed script sets an emporiqa_sid cookie holding the chat session ID.
2. When checkout completes, the subscriber reads the cookie and queues the webhook.
3. An order.completed webhook is sent with the order data and the session ID.
4. Emporiqa uses the session ID to attribute the conversion to the chat interaction.

State machine engines

The subscriber works with both engines. On Sylius 2.x it listens to workflow.sylius_order_checkout.completed.complete (Symfony Workflow). On Sylius 1.x it listens to Winzou's winzou.state_machine.post_transition and acts on the sylius_order_checkout graph's complete transition (plugin 1.11.0 or newer; earlier versions never received it).

Webhook payload

{
  "type": "order.completed",
  "data": {
    "order_id": "000123",
    "total": 149.98,
    "currency": "EUR",
    "emporiqa_session_id": "abc123",
    "items": [
      {"product_id": "456", "quantity": 2, "price": 74.99}
    ]
  }
}

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.11.0 or newer: the price your channel pricing, and any price resolver you added, gives that customer. 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.11.1 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.11.1 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 up to 10 of their placed orders in the channels the plugin syncs, newest first (order number, date, status, total and currency). Carts, guest orders placed with the same email, addresses, phone numbers and internal ids 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, counted in cache.app. To remove a field or add your own under extra, listen to CustomerInfoEvent, which runs after the answer is built; getCustomer() gives the Sylius customer.

use Emporiqa\SyliusPlugin\Event\CustomerInfoEvent;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;

#[AsEventListener(event: CustomerInfoEvent::NAME)]
final class LoyaltyCustomerInfoListener
{
    public function __invoke(CustomerInfoEvent $event): void
    {
        $data = $event->getData();
        unset($data['customer']['email']);
        $data['extra']['loyalty_tier'] = 'gold';
        $event->setData($data);
    }
}

Troubleshooting