SevenKnots
Sign Up

Documentation

Everything you need to integrate the SevenKnots widget into your website, app, or backend.

Quick Start

Get the widget live on your site in three steps.

  1. 1

    Sign up for a free trial

    Create an account — no credit card required. You'll get a unique tenant ID.

  2. 2

    Connect your data

    From the Data Connections page, link your POS, e-commerce store, or upload a CSV. The AI uses this catalog to answer customer questions.

  3. 3

    Embed the widget script

    Copy this script tag and paste it into the <body> of every page where you want the widget to appear.

    <script
  src="https://widget.sevenknots.co/widget/sevenknots-widget.js"
  data-tenant="YOUR_TENANT_ID"
  async
></script>

Website Integration

HTML

The simplest integration. Drop this anywhere in your HTML and the widget appears.

<script
  src="https://widget.sevenknots.co/widget/sevenknots-widget.js"
  data-tenant="YOUR_TENANT_ID"
  async
></script>

React

Component that loads the script on mount and removes it on unmount.

// components/SevenKnotsWidget.tsx
'use client';
import { useEffect } from 'react';

export default function SevenKnotsWidget({ tenantId }: { tenantId: string }) {
  useEffect(() => {
    const s = document.createElement('script');
    s.src = 'https://widget.sevenknots.co/widget/sevenknots-widget.js';
    s.setAttribute('data-tenant', tenantId);
    s.async = true;
    document.body.appendChild(s);
    return () => { document.body.removeChild(s); };
  }, [tenantId]);
  return null;
}

Next.js

Use the built-in next/script for optimal loading.

// app/layout.tsx
import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Script
          src="https://widget.sevenknots.co/widget/sevenknots-widget.js"
          data-tenant="YOUR_TENANT_ID"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

Vue

<!-- App.vue -->
<script setup>
import { onMounted, onUnmounted } from 'vue';

let scriptEl;
onMounted(() => {
  scriptEl = document.createElement('script');
  scriptEl.src = 'https://widget.sevenknots.co/widget/sevenknots-widget.js';
  scriptEl.setAttribute('data-tenant', 'YOUR_TENANT_ID');
  scriptEl.async = true;
  document.body.appendChild(scriptEl);
});
onUnmounted(() => scriptEl?.remove());
</script>

Mobile Integration

For native apps, embed the widget in a WebView.

Flutter

// pubspec.yaml
dependencies:
  webview_flutter: ^4.0.0

// In your widget tree:
import 'package:webview_flutter/webview_flutter.dart';

WebView(
  initialUrl: 'https://widget.sevenknots.co/embed/YOUR_TENANT_ID',
  javascriptMode: JavascriptMode.unrestricted,
)

React Native

import { WebView } from 'react-native-webview';

<WebView
  source={{ uri: 'https://widget.sevenknots.co/embed/YOUR_TENANT_ID' }}
  style={{ flex: 1 }}
/>

API Reference

Call the AI directly from your backend. Generate an API key from the Push API panel.

POST /v1/chat

Send a customer message and receive an AI response with optional product references.

POST https://admin.sevenknots.co/api/v1/chat
Content-Type: application/json
x-api-key: sk_live_xxxxxxxxxxxxxxxxxxxx

{
  "tenant_id": "YOUR_TENANT_ID",
  "message": "Do you have decaf coffee?",
  "conversation_id": "optional-uuid-for-multi-turn"
}

Response

{
  "conversation_id": "5f8e9...",
  "text": "Yes, we have 3 decaf options:",
  "products": [
    {
      "id": "prod_xxx",
      "name": "Swiss Water Decaf",
      "price": 14.99,
      "stock": 12,
      "action": "add_to_cart"
    }
  ],
  "usage": { "input_tokens": 142, "output_tokens": 87 }
}

Webhooks

Receive real-time notifications when customers place orders through the widget. Configure your endpoint URL from the Embed page.

order.created event

Fired when a customer completes checkout via the widget.

{
  "event": "order.created",
  "tenant_id": "YOUR_TENANT_ID",
  "order": {
    "id": "ord_xxxxxxxx",
    "total": 24.50,
    "currency": "USD",
    "items": [
      { "product_id": "prod_xxx", "name": "Latte", "qty": 2, "price": 6.50 },
      { "product_id": "prod_yyy", "name": "Croissant", "qty": 1, "price": 3.50 }
    ],
    "customer": {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "phone": "+1234567890"
    },
    "created_at": "2026-04-11T10:30:00Z"
  }
}

Retry policy

If your endpoint returns a non-2xx response, we retry with exponential backoff: 30s, 2m, 5m, 15m, 1h, 3h. After 6 failed attempts the event is dropped and logged. Make sure your endpoint responds in under 10 seconds.

Widget Configuration

The widget reads its configuration from your saved settings, but you can override individual values by adding data-* attributes to the script tag.

AttributeDescriptionExample
data-tenantRequired. Your unique tenant ID from the dashboard.11111111-1111-1111-1111-111111111111
data-positionOverride the saved widget position.bottom-right or bottom-left
data-themeOverride the saved theme.light, dark, or auto
data-greetingOverride the saved greeting message.Hi! Welcome to my store
data-languageForce a specific language regardless of browser locale.en, ar, or fr
data-modeBubble or inline panel mode.bubble or inline