Widget Embedding Guide

Overview

The Emporiqa chat widget is a lightweight chat assistant that you can embed on your e-commerce store. It provides:

• 24/7 customer support
• Product search and recommendations
• Image search: shoppers upload a photo and get matching products
• In-chat cart: add, update, and check out inside the conversation (opt-in)
• Optional order tracking (if configured in store settings)
• Proactive messages based on visitor behavior
• Post-chat satisfaction rating (CSAT)
• Conversion tracking: chat to cart to purchase attribution
• Multi-language support
• Responsive design (works on desktop and mobile)
• Customizable appearance to match your brand
• Optional human handoff for complex queries

Getting Your Store ID

Each store has a unique Store ID that identifies it. To find your Store ID and embed code:

1. Log in to your Emporiqa dashboard
2. Navigate to Store Settings → Integration tab
3. Find your Store ID in the header and the ready-to-use Embed Code in the Chat Widget Integration section
4. Click the copy button to copy either the Store ID or the complete embed code

Basic Embedding

Add this single line of code to your website, just before the closing </body> tag:

<script async crossorigin="anonymous" src="https://emporiqa.com/chat/embed/?store_id=YOUR_STORE_ID&language=en"></script>

Replace YOUR_STORE_ID with your actual Store ID, and en with your store's language code (e.g., en, de, fr, pt-br, zh-cn). Both 2-letter codes and full regional codes are accepted. Codes are case-insensitive: EN, en-US, and en-us all work.

Optional Parameters

You can add optional parameters to control currency display and sales channel filtering:

<script async crossorigin="anonymous" src="https://emporiqa.com/chat/embed/?store_id=YOUR_STORE_ID&language=en&currency=EUR&channel=b2b"></script>

Example

<!DOCTYPE html>
<html>
<head>
    <title>My Store</title>
</head>
<body>
    <!-- Your store content -->

    <!-- Emporiqa Widget - place before </body> -->
    <script async crossorigin="anonymous" src="https://emporiqa.com/chat/embed/?store_id=ABC123xyz...&language=en"></script>
</body>
</html>

User Identification

You can optionally pass a user_id parameter to track conversations across sessions and devices. This is useful for logged-in customers. If you use order tracking, the user ID is forwarded to your order tracking API so you can restrict results to that customer's orders.

The user_id parameter must be a signed token generated server-side using your connection secret. This prevents customers from forging another user's identity.

Token Format

The token is composed of two parts separated by a dot: a Base64url-encoded JSON payload and an HMAC-SHA256 signature.

base64url({"uid":"CUSTOMER_ID","ts":UNIX_TIMESTAMP}).hmac_sha256_hex(payload, webhook_secret)

• uid - Any string that uniquely identifies the customer (customer ID, email, account number)
• ts - Required. The time the token was created, as an integer Unix timestamp in seconds (not milliseconds), at most 5 minutes in the future. Tokens expire after 7 days, so generate a fresh one on each page render rather than caching it.

Generating the Token (Server-Side)

The token must be generated on your server - never expose the connection secret to the browser.

PHP

function emporiqa_generate_user_token(string $userId, string $webhookSecret): string
{
    $payload = json_encode(['uid' => $userId, 'ts' => time()], JSON_UNESCAPED_SLASHES);
    $encodedPayload = rtrim(strtr(base64_encode($payload), '+/', '-_'), '=');
    $signature = hash_hmac('sha256', $encodedPayload, $webhookSecret);

    return $encodedPayload . '.' . $signature;
}

Python

import base64, hashlib, hmac, json, time

def emporiqa_generate_user_token(user_id: str, webhook_secret: str) -> str:
    payload = json.dumps({"uid": user_id, "ts": int(time.time())}, separators=(",", ":")).encode()
    encoded_payload = base64.urlsafe_b64encode(payload).decode().rstrip("=")
    signature = hmac.new(webhook_secret.encode(), encoded_payload.encode(), hashlib.sha256).hexdigest()
    return f"{encoded_payload}.{signature}"

Embedding with the Token

<script async crossorigin="anonymous" src="https://emporiqa.com/chat/embed/?store_id=YOUR_STORE_ID&language=en&user_id=TOKEN_HERE"></script>

Drupal Commerce (PHP)

$params = ['store_id' => $store_id, 'language' => $language];
if ($user->isAuthenticated()) {
    $params['user_id'] = emporiqa_generate_user_token((string) $user->id(), $webhook_secret);
}
$url = 'https://emporiqa.com/chat/embed/?' . http_build_query($params);

Customization

Customize the widget appearance through your Emporiqa dashboard. No code changes required!

Available Options

Custom CSS

Use the Custom CSS field to fully customize the chat widget's appearance. Your CSS is injected into the widget iframe and can override any styles.

CSS Variables

The widget uses CSS variables for colors. Override them in the :root selector:

:root {
  --primary-color: #1A73E8;    /* Send button and accent color */
  --secondary-color: #1669D4;  /* Hover states */
}

Example: Custom Brand Colors

:root {
  --primary-color: #E91E63;    /* Pink brand color */
  --secondary-color: #C2185B;  /* Darker pink for hover */
}

/* Additional customizations */
.btn-primary {
  border-radius: 4px;  /* Square corners */
}

Position Options

Multi-Language Settings

You can configure different titles and messages for each language in your dashboard. The widget automatically detects the customer's language.

Store Settings & Display Options

These options live under Platform > Store Settings and control what the assistant shows to shoppers. They change the display only; your synced product data is never modified.

Show part of a description, keep the rest for search

Add a <!--more--> marker anywhere in a product description to split it. Everything before the marker is shown to shoppers; everything after it is used only to help the assistant answer questions, which is handy for FAQ, care, or sizing detail you do not want on the card. The full description is always indexed for search either way. Drupal's <!--break--> works the same way. This needs an editor that keeps HTML comments; some rich-text editors strip them on save.

Satisfaction rating (CSAT)

After a conversation, shoppers can rate it with a thumbs up or down. The score and the top reasons for negative ratings appear in your dashboard. This is always on.

Responsive Behavior

Security

Allowed Domains

Restrict where your widget can be embedded by configuring allowed domains in your dashboard. This prevents unauthorized sites from using your widget.

Chat by Country

If you only sell to certain countries, you can limit where the chat appears. Under Settings › Security, choose either Only these countries or All except these countries and list the ones you want.

Visitors outside the countries you serve never see the chat button at all, and they cannot start a conversation, so they never appear on your bill. Everyone else is unaffected.

Changes take up to 10 minutes to reach every page, because the widget script is cached.

Token Authentication

The widget uses time-limited, HMAC-signed tokens for API authentication. This prevents abuse and ensures requests come from legitimate widget instances.

Rate Limiting

Built-in rate limiting protects against abuse:

• 10 messages per minute per IP address
• 100 messages per hour per conversation

Load on Click

Some data protection officers will not have a visitor's browser contact a third party before the visitor asks for it, because the request itself carries their IP address. For them, load the chat only when the visitor clicks (the "two-click solution"): your page draws the chat button itself, and nothing is loaded from Emporiqa until the click.

Copy the snippet from Settings › Integration › Embed code and webhook › Load the chat only when the visitor clicks and paste it instead of the script tag, just before </body>. Your colours, corner and store name are already filled in. It is self-contained: a style, a button with the icon drawn inline, and a short script. Its shape:

<style>#emporiqa-load{ ... your colours and corner ... }</style>
<button type="button" id="emporiqa-load" aria-label="Your store"
  data-store="YOUR_STORE_ID"
  data-src="https://emporiqa.com/chat/embed/?store_id=YOUR_STORE_ID"><svg>...</svg></button>
<script> ... </script>

What happens

• Before the click: no request to Emporiqa (no script, no settings, no font), no cookie, and nothing written to the browser's storage. The button reads one entry, emporiqaChatOpened_<store id>, which exists only if this visitor opened the chat before.
• On the click: the chat loads and opens, and the real chat button takes the place of yours.
• On later pages: for 30 days after the visitor last opened the chat, it loads straight away, without a click, so the conversation carries on as they browse.
• When your store cannot chat (switched off, over its monthly cap, or not offered in the visitor's country): the button still shows, because finding out would mean asking us before the click, and it disappears when clicked.
• Language: the chat follows the page's <html lang>. To fix it, add &language=de to data-src.

What is off in this mode

Proactive messages, the button's attention pulse, the daily counts of how many visitors saw and opened the chat, and the list of recently viewed products. Conversations, the cart, order status and handoff to your team work as usual, and where page awareness is on, the page the visitor is on still goes with their message. Your dashboard's visitor and open counts leave out these visitors; their conversations are counted.

After the click the chat still sets the emporiqa_sid cookie, which links an order to the conversation for your dashboard's revenue from chat. The chat works without it. To store nothing beyond the chat, switch off Link orders to chats in the Shopware plugin (version 1.4.0 or newer), which then sends no orders either, or add &attribution=off to data-src, which stops the cookie. Our other plugins still send each order to Emporiqa from your server for now.

Behind your consent banner

To load the chat once a visitor has given consent, keep the snippet and call window.EmporiqaLoad() from your consent manager. It loads the chat in the same mode without opening it. The page receives emporiqa:ready on window when the chat is there (then window.EmporiqaChat.open() opens it), or emporiqa:unavailable when there is no chat to show; the button removes itself on either. If a visitor withdraws consent, remove emporiqaChatOpened_<store id> from localStorage too, or later pages keep loading the chat for 30 days after their last open.

What is stored after the click

On your store's domain, and nothing else. <id> is your store ID, followed by the customer's ID when the tag carries a signed user_id. None holds a name, email address or IP address.

The chat window itself runs on Emporiqa's domain, and the browser keeps its storage separate for each shop. It holds the conversation and the time of its last message, which signed-in customer a conversation belongs to, how often the satisfaction question was shown, and, where voice is on, whether the visitor confirmed the voice notice and whether spoken replies are muted.

Not written in this mode: emporiqaVisited_, emporiqaVisit_, emporiqaTriggerClaim_, emporiqaReported_, emporiqaRecentlyViewed_ and emporiqaNudged. The full list for both modes is on the cookies page.

Cart Handler

In-chat cart is off by default. Turn it on under Platform > Store Settings (see Store Settings). Once enabled, the widget delegates cart actions (add, remove, update, clear, view, checkout) to a JavaScript function on your page. The plugins for Drupal Commerce, WooCommerce, Sylius, Magento 2, PrestaShop, and Shopware implement this function automatically.

For custom platforms, register EmporiqaCartHandler before the widget loads:

window.EmporiqaCartHandler = async function({ action, items }) {
  const item = items?.[0];

  if (action === 'add') {
    const res = await fetch('/api/cart/add', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        product_id: item.product_id,
        variation_id: item.variation_id,
        quantity: item.quantity
      })
    });
    return await res.json();
  }

  if (action === 'view') {
    const res = await fetch('/api/cart');
    return await res.json();
  }

  if (action === 'checkout') {
    return { success: true, checkoutUrl: '/checkout' };
  }

  // handle remove, update, clear similarly
};

Response Format

Every handler call must resolve with this structure:

{
  "success": true,
  "checkoutUrl": "/checkout/2",
  "cart": {
    "items": [
      {
        "product_id": "257",
        "variation_id": "1097",
        "name": "iPhone 14 - Midnight, 128GB",
        "quantity": 1,
        "unit_price": 699.00,
        "image_url": "https://store.com/images/iphone-14.jpg",
        "product_url": "https://store.com/product/iphone-14"
      }
    ],
    "item_count": 3,
    "total": 1397.00,
    "currency": "USD"
  }
}

Troubleshooting