Gengage Documentation

Welcome to the Gengage integration documentation. Learn how to integrate our AI-powered shopping assistant into your e-commerce platform.

📘 What is Gengage?

Gengage is an AI shopping assistant that helps your customers discover products through natural conversation. It integrates seamlessly with your existing product catalog and shopping cart.

Integration Options

Gengage offers two integration paths:

Data Integration API: Expose your product catalog to our AI agents using a standardized REST API
Frontend Integration: Embed the Gengage assistant UI into your website using an iframe

Architecture Overview

The Gengage platform architecture consists of two integrated layers that work together:

Data Integration & Intelligence Layer: You implement the Data Integration API to expose your product catalog and customize the assistant behavior. This makes the assistant iframe servable with your merchant-specific intelligence. Gengage hosts the AI assistant and uses your merchant data capabilities as tools for agentic product discovery.
Bidirectional Communication Layer: Once the iframe is embedded, it provides built-in analytics tracking and enables seamless interaction between your site and the assistant:
- Host → Iframe: Your site triggers the assistant based on user actions (button clicks, page navigation, product views)
- Iframe → Host: The assistant triggers actions on your site (add-to-basket, product navigation) based on chat interactions

Both integrations work together to provide a complete shopping assistant experience.

Data Integration API

The Data Integration API is a standardized REST API that merchants implement to expose their product catalogs to AI-powered commerce platforms.

Key Features

Schema.org Native: Uses JSON-LD format that LLMs understand natively
Google Shopping Compatible: Attributes map directly to existing Merchant Center feeds
Structured Filtering: SQL-like queries mixed with fuzzy keyword search
Real-Time Verification: Stock availability and pricing checked before agent commits

Authentication

Merchants must implement simple header-based authentication for server-to-server communication.

API Key Authentication

Include your API key in the request header:

X-API-Key: your-api-key-here

🔐 Security Note

Handshake between GengageAI and the merchant on API key issuance is required prior to integration. Contact support to obtain your API key.

Product Search

Search products using fuzzy keywords with progressive facet and category discovery. This endpoint mirrors typical Algolia/Elasticsearch e-commerce search behavior.

Agentic Search Flow

Discovery: Send keywords → receive matching categories, available facets, and preliminary results
Evaluate: Review discovered categories/facets with hit counts to understand selectivity
Refine & Loop: Apply category/facet filters, adjust keywords, repeat until satisfied

Endpoint

POST /v1/products/search

Request Example

{
  "keywords": "running shoes black",
  "include": ["variants"],
  "limit": 20,
  "offset": 0,
  "categoryFilter": {
    "include": ["shoes-042", "running-shoes-007"],
    "exclude": ["sandals-015"]
  },
  "facetFilter": [
    {"name": "color", "values": ["Black"]},
    {"name": "brand", "values": ["Nike", "Adidas"]}
  ],
  "priceRange": {
    "min": 500,
    "max": 2000
  },
  "inStockOnly": true,
  "returnFacets": true,
  "returnCategories": true,
  "sort": {
    "field": "relevance",
    "order": "desc"
  }
}

Request Parameters

Parameter	Type	Required	Description
`keywords`	string	Yes*	Fuzzy search keywords. *Required unless categoryFilter is provided
`include`	string[]	No	Optional data to include: variants, reviews, qna
`limit`	integer	No	Results per page (default: 20, max: 100)
`categoryFilter`	object	No	Category inclusion/exclusion filters
`facetFilter`	array	No	Facet value selections for filtering
`priceRange`	object	No	Price range filter (min/max)
`inStockOnly`	boolean	No	Filter to in-stock items only (default: false)

Response Example

{
  "success": true,
  "data": {
    "products": [
      {
        "@context": "https://schema.org",
        "@type": "Product",
        "sku": "NK-PEGASUS-39-BLK",
        "groupId": "NK-PEGASUS-39",
        "name": "Nike Air Zoom Pegasus 39",
        "description": "Lightweight running shoe with responsive cushioning",
        "brand": {
          "@type": "Brand",
          "name": "Nike"
        },
        "image": [
          "https://cdn.merchant.com/products/pegasus39-main.jpg"
        ],
        "url": "https://merchant.com/product/pegasus-39",
        "category": ["Sports", "Shoes", "Running Shoes"],
        "categoryId": ["sports-001", "shoes-042", "running-shoes-007"],
        "offers": {
          "@type": "Offer",
          "cartId": "cart-pegasus-39-blk",
          "price": "1899.99",
          "originalPrice": "2499.99",
          "priceCurrency": "TRY",
          "availability": "https://schema.org/InStock"
        },
        "aggregateRating": {
          "@type": "AggregateRating",
          "ratingValue": "4.5",
          "reviewCount": "128"
        }
      }
    ],
    "totalCount": 156,
    "categories": {
      "canFilter": true,
      "items": [
        {
          "id": "running-shoes-007",
          "name": "Running Shoes",
          "count": 89
        }
      ]
    },
    "facets": [
      {
        "name": "brand",
        "displayName": "Brand",
        "filterable": true,
        "values": [
          {"value": "Nike", "count": 45},
          {"value": "Adidas", "count": 38}
        ]
      }
    ]
  },
  "pagination": {
    "offset": 0,
    "limit": 20,
    "totalCount": 156,
    "hasMore": true
  }
}

Product Detail

Retrieve complete product information by SKU.

Endpoint

GET /v1/products/{sku}

Query Parameters

Parameter	Type	Description
`include`	string	Comma-separated: reviews, qna, variants

Request Example

curl -X GET "https://api.merchant.com/v1/products/NK-PEGASUS-39-BLK?include=reviews,qna,variants" \
  -H "X-API-Key: your-api-key"

Response

Returns a complete Product object with all requested includes (variants, reviews, Q&A).

Batch Product Retrieval

Retrieve multiple products by SKU list in a single request.

Endpoint

POST /v1/products/batch

Request Example

{
  "skus": ["NK-PEGASUS-39-BLK", "AD-ULTRABOOST-22", "PM-VELOCITY-3"],
  "include": ["variants"]
}

⚠️ Limit

Maximum 50 SKUs per request

Response

{
  "success": true,
  "data": {
    "products": [
      { "@type": "Product", "sku": "NK-PEGASUS-39-BLK", "..." },
      { "@type": "Product", "sku": "AD-ULTRABOOST-22", "..." }
    ],
    "notFound": ["PM-VELOCITY-3"]
  }
}

Real-Time Availability

Verify current stock status before agent commits to a recommendation.

Endpoint

POST /v1/products/availability

Request Example

{
  "skus": ["NK-PEGASUS-39-BLK-42", "NK-PEGASUS-39-BLK-43"],
  "zipCode": "34000"
}

Response Example

{
  "success": true,
  "data": {
    "NK-PEGASUS-39-BLK-42": {
      "availability": "InStock",
      "cartId": "cart-pegasus-39-blk-42",
      "quantity": 4,
      "price": "1899.99",
      "originalPrice": "2499.99",
      "canDeliverBy": "2025-02-20"
    },
    "NK-PEGASUS-39-BLK-43": {
      "availability": "OutOfStock",
      "cartId": "cart-pegasus-39-blk-43",
      "nextRestockDate": "2025-03-01"
    }
  }
}

💡 Usage Note

Call this endpoint immediately before presenting purchase options. Maximum 20 SKUs per request.

Agent Instructions (Optional)

Retrieve merchant-specific guidance for AI shopping agents. This endpoint provides markdown-formatted instructions that help agents understand store policies and conversation style.

Endpoint

GET /v1/agent/instructions

Available Sections

policies: Store policies, FAQs, shipping/return rules
tone: Conversation style and tone instructions
expert: Expert question-answering guidance
search: Search behavior guidance, site limits

Request Example

curl -X GET "https://api.merchant.com/v1/agent/instructions?sections=policies,tone&language=en" \
  -H "X-API-Key: your-api-key"

Data Schema: Product

All product data follows Schema.org vocabulary with Google Shopping attribute extensions.

Product Object

{
  "@context": "https://schema.org",
  "@type": "Product",

  "sku": "string (required, unique per variant)",
  "groupId": "string (required, shared by all variants of same product)",
  "name": "string (required)",
  "description": "string",

  "brand": {
    "@type": "Brand",
    "name": "string (required)"
  },

  "gtin": "string (recommended for cross-merchant matching)",
  "mpn": "string",

  "image": ["string (url)", "..."],
  "video": ["string (url)", "..."],
  "url": "string (url, required)",

  "category": ["string", "..."],
  "categoryId": ["string", "..."],

  "additionalProperty": [
    {
      "@type": "PropertyValue",
      "name": "string",
      "value": "string"
    }
  ],

  "offers": { "@type": "Offer", "..." },
  "aggregateRating": { "@type": "AggregateRating", "..." },

  "variants": ["..."],
  "review": ["..."],
  "qna": ["..."]
}

Data Schema: Offer

Offer Object

{
  "@type": "Offer",

  "cartId": "string (required, identifier for add-to-cart operations)",
  "price": "string (numeric, required)",
  "originalPrice": "string (numeric, original price before discount)",
  "discountDescription": "string (reason for discount)",
  "priceCurrency": "string (ISO 4217, required)",
  "priceValidUntil": "string (ISO 8601 date)",

  "availability": "string (Schema.org URL, required)",
  "itemCondition": "string (Schema.org URL)",

  "shippingDetails": {
    "@type": "OfferShippingDetails",
    "deliveryTime": {
      "@type": "ShippingDeliveryTime",
      "businessDays": {
        "minValue": "integer",
        "maxValue": "integer"
      }
    },
    "shippingRate": {
      "@type": "MonetaryAmount",
      "value": "string",
      "currency": "string"
    }
  }
}

Availability Values

https://schema.org/InStock
https://schema.org/OutOfStock
https://schema.org/PreOrder
https://schema.org/LimitedAvailability

Data Schema: Review

{
  "@type": "Review",

  "reviewRating": {
    "@type": "Rating",
    "ratingValue": "string (1-5)"
  },

  "author": {
    "@type": "Person",
    "name": "string"
  },

  "datePublished": "string (ISO 8601)",
  "reviewBody": "string",
  "isVerifiedPurchase": "boolean"
}

Data Schema: Q&A

{
  "@type": "Question",

  "text": "string",
  "dateCreated": "string (ISO 8601)",
  "author": {
    "@type": "Person",
    "name": "string"
  },

  "acceptedAnswer": {
    "@type": "Answer",
    "text": "string",
    "dateCreated": "string (ISO 8601)",
    "author": {
      "@type": "Person | Organization",
      "name": "string"
    }
  }
}

Data Schema: Variant

{
  "sku": "string (required)",

  "additionalProperty": [
    {"@type": "PropertyValue", "name": "size", "value": "42"},
    {"@type": "PropertyValue", "name": "color", "value": "Black"}
  ],

  "offers": {
    "cartId": "string (required)",
    "price": "string",
    "availability": "string (Schema.org URL)"
  },

  "image": "string (url)"
}

Implementation Guide

Google Merchant Center Feed Mapping

If you already have a Google Shopping feed, use this mapping to implement the API:

API Field	Google Feed Attribute	Notes
`sku`	`g:id`	Unique product identifier
`groupId`	`g:item_group_id`	Required - All color/size variants share this ID
`name`	`g:title`	Product title
`gtin`	`g:gtin`	Recommended for cross-merchant matching
`offers.cartId`	(merchant-specific)	Required for add-to-cart operations
`offers.price`	`g:sale_price`	Current selling price
`offers.originalPrice`	`g:price`	Original price before discount

Error Handling

Error Response Format

{
  "success": false,
  "error": {
    "code": "PRODUCT_NOT_FOUND",
    "message": "The requested product does not exist",
    "details": {
      "sku": "ABC123"
    },
    "requestId": "req-uuid-12345"
  }
}

Standard Error Codes

HTTP Status	Error Code	Description
400	`INVALID_REQUEST`	Malformed request body
401	`UNAUTHORIZED`	Missing or invalid authentication
404	`PRODUCT_NOT_FOUND`	SKU doesn't exist
429	`RATE_LIMITED`	Too many requests
500	`INTERNAL_ERROR`	Server error

Rate Limiting

Recommended Limits

Endpoint	Requests/Second	Requests/Minute
Search	50	1000
Product Detail	100	2000
Batch	20	500
Availability	100	2000

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1705320000
Retry-After: 45

Frontend Integration

Integrate the Gengage Assistant UI into your website using an iframe. The integration relies on bidirectional communication via the window.postMessage API.

Core Principle

Host → Assistant: Send messages to trigger the assistant, open specific contexts, or manage visibility
Assistant → Host: Receive commands based on user interactions (add to cart, navigation, etc.)

Accessing the Assistant (Standalone Mode)

The Assistant can be accessed directly via a standalone URL for testing or specific use cases.

URL Structure

https://chatdev.gengage.ai/{accountId}?{parameters}

Account ID

Your account ID is derived from your website hostname by removing www. and all dots:

Website	Account ID
www.example.com.tr	examplecomtr
www.koctas.com.tr	koctascomtr

URL Parameters

Parameter	Required	Description	Example
`sku`	No	Product SKU for product-specific context	12345678
`init_state`	No	Initial state: single-product or explore	single-product
`uid`	No	Unique user identifier	user_abc123
`mobile`	No	Whether user is on mobile	true/false

Example URL

https://chatdev.gengage.ai/koctascomtr?sku=5000463606&init_state=single-product&uid=docsuser

Embedding the Assistant (Iframe Integration)

To integrate the Assistant into your website, embed the Gengage iframe. The visual presentation (Overlay vs. Drawer) is controlled by your CSS.

HTML Embed Example

<iframe
  id="gengage-assistant-iframe"
  src="https://chatdev.gengage.ai/{YOUR_ACCOUNT_ID}"
  allow="clipboard-read; clipboard-write; microphone;"
  style="
    position: fixed;
    right: 0;
    top: 0;
    width: 420px;
    height: 100%;
    border: none;
    z-index: 9999;
    display: none;
  "
></iframe>

Display Modes

Drawer Mode (Default)

The assistant slides in from the right side of the screen as a drawer panel.

.gengage-assistant-iframe {
  position: fixed;
  right: 0;
  top: 0;
  width: 420px;
  height: 100%;
  border: none;
  z-index: 9999;
  transform: translateX(100%);
  transition: transform 0.3s ease-in-out;
}

.gengage-assistant-iframe.open {
  transform: translateX(0);
}

Overlay Mode

The assistant appears as a floating overlay with a semi-transparent background.

.gengage-overlay-bg {
  position: fixed;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  background-color: rgba(0, 0, 0, 0.3);
  z-index: 9998;
}

.gengage-assistant-iframe.overlay {
  position: fixed;
  right: 20px;
  bottom: 20px;
  width: 400px;
  height: 600px;
  border-radius: 16px;
  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.15);
}

Mobile Responsive

For mobile devices, the assistant should take full screen:

@media screen and (max-width: 768px) {
  .gengage-assistant-iframe {
    width: 100%;
    height: 100%;
    right: 0;
    bottom: 0;
  }
}

Avatar Trigger

The standard "launcher" icon (Avatar) is hosted on your site. When clicked, it makes the iframe visible and sends an "Open" command to the Assistant.

HTML Structure

<button id="gengage-launcher" class="gengage-launcher">
  <img src="https://storage.googleapis.com/gengage-resources-fr/launcher-image/default-launcher.svg" alt="Chat">
</button>

JavaScript Handler

const launcher = document.getElementById('gengage-launcher');
const iframe = document.getElementById('gengage-assistant-iframe');

// Toggle open/close
launcher.addEventListener('click', function() {
  const isVisible = iframe.style.display !== 'none';

  if (isVisible) {
    // Request iframe to close (for analytics)
    iframe.contentWindow.postMessage({ type: 'requestClose' }, '*');

    // Hide iframe
    iframe.style.display = 'none';
    launcher.classList.remove('hidden');
  } else {
    // Open
    iframe.style.display = 'block';
    iframe.classList.add('open');
    launcher.classList.add('hidden');

    // Send show message
    iframe.contentWindow.postMessage({ type: 'show' }, '*');

    // For mobile
    if (window.innerWidth <= 768) {
      iframe.contentWindow.postMessage({ message: 'glovMobileChatbotOpen' }, '*');
    }
  }
});

// Listen for close messages FROM iframe
window.addEventListener('message', function(event) {
  if (event.source !== iframe.contentWindow) return;

  if (event.data.type === 'close' || event.data.message === 'glovMobileChatbotClose') {
    iframe.style.display = 'none';
    iframe.classList.remove('open');
    launcher.classList.remove('hidden');
  }
});

Find Similar Button

You can place a "Find Similar" button on your product listings. Clicking this opens the Assistant with recommendations similar to the selected product.

HTML Structure

<button id="find-similar-btn" class="gengage-find-similar-btn" data-sku="PRODUCT_SKU">
  Find Similar Products
</button>

JavaScript Handler

findSimilarBtn.addEventListener('click', function() {
  const sku = this.dataset.sku;

  // Show the iframe
  iframe.style.display = 'block';
  iframe.classList.add('open');
  iframe.contentWindow.postMessage({ type: 'show' }, '*');

  // Send mobile open message first
  iframe.contentWindow.postMessage({ message: 'glovMobileChatbotOpen' }, '*');

  // Send find similar request
  iframe.contentWindow.postMessage({
    type: 'startNewChatWithLauncherAction',
    payload: {
      type: 'findSimilar',
      payload: { sku: sku }
    }
  }, '*');
});

Q&A Box

On a Product Detail Page (PDP), the Assistant should start with context about the specific product being viewed. The Q&A box displays suggested questions.

Fetching Suggested Questions

async function fetchSuggestedQuestions(sku, accountId) {
  const response = await fetch('https://gengage-ai-abilities-894145150101.europe-west3.run.app/chat/launcher_action', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': localStorage.getItem('gengage_user_id') || ''
    },
    body: JSON.stringify({
      sku: sku,
      account_id: accountId
    })
  });

  if (response.ok) {
    return await response.json();
  }
  return null;
}

Opening Chat with Context

function openChatWithQuestion(text, isSuggested = false) {
  iframe.style.display = 'block';
  iframe.classList.add('open');
  iframe.contentWindow.postMessage({ type: 'show' }, '*');

  // For mobile, use half-screen mode
  if (window.innerWidth <= 768) {
    iframe.contentWindow.postMessage({ message: 'glovMobileChatbotHalf' }, '*');
  }

  // Send question with context
  iframe.contentWindow.postMessage({
    type: 'startNewChatWithDetailContext',
    payload: {
      action: {
        type: 'inputText',
        payload: {
          text: text,
          is_launcher: 1,
          is_suggested_text: isSuggested ? 1 : 0
        }
      },
      sku: getCurrentProductSku()
    }
  }, '*');
}

Closing the Assistant

The Assistant will send a close message when the user clicks the close button inside the iframe. Listen for this to hide the iframe:

window.addEventListener('message', function(event) {
  if (event.source !== iframe.contentWindow) return;

  if (event.data.type === 'close' || event.data.message === 'glovMobileChatbotClose') {
    // Animate iframe closing
    iframe.classList.remove('open');

    // Hide after animation
    setTimeout(() => {
      iframe.style.display = 'none';
    }, 300);

    // Show launcher again
    launcher.classList.remove('hidden');
  }
});

Cart Integration

When a user decides to buy a product inside the chat, the Assistant sends a message to the Host site. You must listen for this event and trigger your add-to-cart logic.

Message Format

{
  message: 'glovAddToBasket',
  sku: '12345678',
  quantity: 1,
  cart_code: 'CART_CODE'
}

Listening for Cart Messages

window.addEventListener('message', function(event) {
  if (event.source !== iframe.contentWindow) return;

  if (event.data.message === 'glovAddToBasket') {
    handleAddToCart({
      sku: event.data.sku,
      quantity: event.data.quantity,
      cartCode: event.data.cart_code
    });
  }
});

Add-to-Cart Handler with Response

async function handleAddToCart({ sku, quantity, cartCode }) {
  try {
    const response = await fetch('/api/cart/add', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        productCode: cartCode || sku,
        quantity: quantity
      })
    });

    if (response.ok) {
      // Notify iframe of success
      iframe.contentWindow.postMessage({
        type: 'addToCardHandler',
        payload: {
          error_message: null,
          sku: sku,
          cart_code: cartCode
        }
      }, '*');
    } else {
      // Notify iframe of error
      const error = await response.json();
      iframe.contentWindow.postMessage({
        type: 'addToCardHandler',
        payload: {
          error_message: error.message || 'Failed to add to cart',
          sku: sku,
          cart_code: cartCode
        }
      }, '*');
    }
  } catch (error) {
    console.error('Add to cart failed:', error);
  }
}

URL Navigation

The assistant may request to navigate the user to product pages or search results.

Navigation Message Types

Open URL in Same Window

{
  type: 'openURL',
  payload: {
    url: 'https://example.com/product/123'
  }
}

Open URL in New Tab

{
  type: 'openURLInNewTab',
  payload: {
    url: 'https://example.com/product/123'
  }
}

Handler Implementation

window.addEventListener('message', function(event) {
  if (event.source !== iframe.contentWindow) return;

  // Open URL in same window
  if (event.data.type === 'openURL') {
    window.location.href = event.data.payload.url;
  }

  // Open URL in new tab
  if (event.data.type === 'openURLInNewTab') {
    window.open(event.data.payload.url, '_blank');
  }
});

Cart Quantity Handler (Optional)

When the assistant opens, you can optionally send the current cart state to provide context-aware responses.

Send Cart State on Open

// When opening the chat
launcher.addEventListener('click', function() {
  // ... open logic ...

  // Send cart state to iframe
  const cartItems = getCartItems(); // Your function to get cart
  const totalQuantity = cartItems.reduce((sum, item) => sum + item.quantity, 0);

  iframe.contentWindow.postMessage({
    type: 'cartQuantityHandler',
    payload: {
      quantity: totalQuantity,
      items: cartItems
    }
  }, '*');
});

Customization & Branding

To ensure the Assistant matches your brand identity, provide the following to the Gengage team:

CSS Customization

Provide the URL to your custom CSS file:

:root {
  --gengage-primary: #your-brand-color;
  --gengage-primary-hover: #your-brand-color-dark;
}

.gengage-send-btn {
  background-color: var(--gengage-primary);
}

Logo Customization

Provide the URL to your assistant avatar/logo image (SVG recommended, 60x60px minimum).

Configuration Request

Item	Description	Example
Custom CSS URL	URL to your CSS file	https://cdn.example.com/gengage.css
Logo URL	URL to your avatar image	https://cdn.example.com/avatar.svg
Privacy URL	URL to privacy content	https://example.com/privacy-content

Implementation Checklist

Before going live, verify the following:

✅ Iframe Setup: Iframe loads with correct accountId and allow attributes
✅ Open/Close: Launcher opens iframe and close messages hide it properly
✅ PDP Context: startNewChatWithDetailContext sends correct SKU on product pages
✅ QNA Box: Suggested questions are fetched and displayed correctly
✅ Find Similar: findSimilar message opens assistant with correct product context
✅ Cart Add: glovAddToBasket message triggers add-to-cart function
✅ Cart Response: addToCardHandler response sent back to iframe
✅ URL Navigation: openURL and openURLInNewTab handlers work correctly
✅ Privacy Consent: kvkk-approved message saves to localStorage
✅ Cart State: cartQuantityHandler sends cart info on open (optional)
✅ Mobile Responsiveness: Half-screen and full-screen modes work correctly
✅ Animations: Drawer/overlay animations work smoothly

Live Demo Integration

Experience the Gengage Assistant in action with this live demo using the Koçtaş integration.

Interactive Demo

Adjust the parameters below to see how different configurations affect the assistant. The demo uses the koctascomtr account which has data integration already in place.

SKU

Initial State

User ID

Interactive Examples

Try these interactive examples that demonstrate how to communicate with the embedded assistant:

1. Avatar Launcher Button

Click to open/close the assistant

This button shows/hides the iframe and sends the appropriate postMessage commands.

2. Find Similar Products

Trigger similarity search for a product

Opens the assistant and asks for similar products to the specified SKU.

3. Q&A Box Integration

Send questions directly to the assistant

Opens the assistant with product context and sends your question.

Live Assistant Iframe

The iframe below responds to the interactive examples above. Click the avatar button to open/close it.

💡 Try these interactions

Ask questions about the product
Request similar products or alternatives
Inquire about specifications and features
Test the add-to-cart functionality

Complete Integration Example

Here's a complete working example that combines all the integration components:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Product Page with Gengage</title>
  <style>
    .gengage-assistant-iframe {
      position: fixed; right: 0; top: 0;
      width: 420px; height: 100%; border: none; z-index: 9999;
      transform: translateX(100%);
      transition: transform 0.3s ease-in-out;
    }
    .gengage-assistant-iframe.open { transform: translateX(0); }
    .gengage-launcher {
      position: fixed; right: 20px; bottom: 20px;
      width: 60px; height: 60px; border-radius: 50%;
      background: linear-gradient(135deg, #FF6B00, #FF4800);
      cursor: pointer; box-shadow: 0 4px 12px rgba(0, 0, 0, 0.2);
    }
    .gengage-launcher.hidden { opacity: 0; pointer-events: none; }
  </style>
</head>
<body>
  <main>
    <h1>Product Name</h1>
    <p>Product description...</p>
  </main>
  <iframe id="gengage-assistant-iframe" class="gengage-assistant-iframe"
    src="https://chatdev.gengage.ai/youraccountid"
    allow="clipboard-read; clipboard-write; microphone;"></iframe>
  <button id="gengage-launcher" class="gengage-launcher">
    <img src="https://storage.googleapis.com/gengage-resources-fr/launcher-image/default-launcher.svg" alt="Chat">
  </button>
  <script>
    const iframe = document.getElementById('gengage-assistant-iframe');
    const launcher = document.getElementById('gengage-launcher');

    // Toggle open/close
    launcher.addEventListener('click', () => {
      const isOpen = iframe.classList.contains('open');

      if (isOpen) {
        // Request iframe to close (for analytics)
        iframe.contentWindow.postMessage({ type: 'requestClose' }, '*');
        iframe.classList.remove('open');
        launcher.classList.remove('hidden');
      } else {
        // Open
        iframe.classList.add('open');
        launcher.classList.add('hidden');
        iframe.contentWindow.postMessage({ type: 'show' }, '*');
      }
    });

    // Listen for messages from iframe
    window.addEventListener('message', (event) => {
      if (event.source !== iframe.contentWindow) return;

      if (event.data.type === 'close') {
        iframe.classList.remove('open');
        launcher.classList.remove('hidden');
      }

      if (event.data.message === 'glovAddToBasket') {
        handleAddToCart(event.data);
      }
    });

    async function handleAddToCart({ sku, quantity, cart_code }) {
      console.log('Adding to cart:', sku, quantity);
      iframe.contentWindow.postMessage({
        type: 'addToCardHandler',
        payload: { error_message: null, sku: sku, cart_code: cart_code }
      }, '*');
    }
  </script>
</body>
</html>

Full Examples

Example 1: Agentic Search Flow

A complete example of the 3-step agentic search flow for finding "bluetooth headphones under 2000 TL":

# Step 1: Discovery (Initial keyword search)
curl -X POST "https://api.merchant.com/v1/products/search" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "keywords": "bluetooth headphones",
    "limit": 10,
    "returnFacets": true,
    "returnCategories": true
  }'

# Step 2: Refine with Category and Price
curl -X POST "https://api.merchant.com/v1/products/search" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "keywords": "bluetooth headphones",
    "categoryFilter": {
      "include": ["headphones-001"]
    },
    "priceRange": {
      "max": 2000
    },
    "inStockOnly": true
  }'

# Step 3: Final Refinement with Facets
curl -X POST "https://api.merchant.com/v1/products/search" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "keywords": "bluetooth headphones",
    "categoryFilter": {
      "include": ["headphones-001"]
    },
    "facetFilter": [
      {"name": "brand", "values": ["JBL", "Sony"]},
      {"name": "features", "values": ["Noise Cancelling"]}
    ],
    "priceRange": {
      "max": 2000
    },
    "sort": {
      "field": "rating",
      "order": "desc"
    }
  }'

Example 2: Availability Check Before Purchase

curl -X POST "https://api.merchant.com/v1/products/availability" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "skus": ["JBL-TUNE760NC-BLK", "JBL-TUNE760NC-WHT"],
    "zipCode": "34000"
  }'

📚 Need Help?

If you have questions or need assistance with integration, please contact the Gengage support team at [email protected]