KnowDesk: The All-in-One AI Customer Support Platform

KnowDesk is more than a knowledge base chatbot - it is a complete AI customer support platform. Connect your docs (Google Docs, PDFs, Notion, Confluence, plain text) and deploy a branded AI widget on any website in minutes. When a conversation needs a human, agents reply from the Live Inbox. When a customer asks about an order, the AI looks it up in Stripe, Shopify, or Paystack. When someone emails support, it becomes a ticket automatically. No engineers. No chatbot training. No rebuilding documentation.

This guide walks you through every feature - from creating your account and connecting your knowledge base, to setting up live agent replies, order lookup, and email inbound. Follow the sections in order for your first setup, or jump to any section using the navigation on the left.

Getting Started

Follow these four steps to go from signup to a live widget on your website.

Knowledge Base

The knowledge base is the foundation of your AI support bot. KnowDesk is a knowledge base chatbot - it only answers from what you connect here, never from general internet knowledge. The more structured your content, the more accurate the answers.

Supported source types

Adding a Google Drive source

To connect a Google Doc:

1. Go to Knowledge Base in your dashboard
2. Click + Add Source
3. Select Google Drive
4. Give the source a descriptive name (e.g. "Operations SOP")
5. Open your Google Doc and copy the file ID from the URL: docs.google.com/document/d/FILE_ID/edit
6. Paste the file ID into the field and click Add Source
7. Click Sync - the source status changes to SYNCED within a few seconds

Syncing sources

Sources don't auto-sync continuously. Click the ⟳ Sync button after editing a document to update what the AI knows. Syncing typically takes 2–10 seconds depending on document size.

Plan limits

Video Knowledge Base

Upload your tutorial videos, product walkthroughs, onboarding recordings, or any audio content and KnowDesk automatically transcribes the content using AssemblyAI. The transcript is indexed with timestamps, so the AI can reference the exact moment where relevant content appears - and users see clickable time links in the widget to jump directly to that point.

How it works

Timestamp links in the widget

When the AI answers a question from a video source, it includes the timestamp of the relevant moment - for example: "As shown at [2:14], you connect your account by clicking Settings → Integrations."

Users see a clickable chip below the answer that reads ▶ 2:14. Clicking it opens the video at that exact moment in a new tab. No extra setup needed - this works automatically for any synced video source.

Setup requirement

Supported file formats

Widget Configuration

The Widget Config page controls everything your users see - brand name, colour, welcome message, tone, and suggested prompts. Changes save immediately and take effect on your live widget without any redeployment.

Brand settings

AI behaviour

Tone - Controls how the AI writes responses:

• Casual - Clear, direct, and conversational. Sounds like a knowledgeable teammate.
• Formal - Complete sentences, professional language, structured responses.
• Technical - Assumes domain knowledge, uses precise terminology.

Suggested Prompts - Up to 4 quick-start buttons shown in the widget before the user types. Enter one per line. Example: "How do I escalate a client issue?" or "What is our refund policy?"

Dark / Light mode

Toggle whether the widget renders in dark or light mode. This affects only the widget appearance - not your dashboard. Choose whichever matches your website's background.

Embed the AI Chat Widget on Your Website

Your embed code is a single script tag. It's the easiest way to embed an AI chat widget on any website - Webflow, WordPress, Shopify, Next.js, or plain HTML. Copy it from Widget Config → Embed Code and paste it before </body>.

<script 
  src="https://cdn.knowdesk.io/widget.js" 
  data-key="kd_live_your_api_key_here">
</script>

Where to paste it

Paste the script tag just before the closing </body> tag on every page you want the widget to appear.

<!DOCTYPE html>
<html>
  <head>
    <title>Your Website</title>
  </head>
  <body>
    <!-- Your website content -->

    <!-- KnowDesk Widget - paste here -->
    <script 
      src="https://cdn.knowdesk.io/widget.js" 
      data-key="kd_live_your_api_key_here">
    </script>
  </body>
</html>

Works on any platform

Analytics

The Analytics page gives you a unified view of all support activity across every channel - AI widget conversations, escalated tickets, live agent replies, and inbound email threads - in one dashboard.

Key metrics

Channel breakdown

The channel breakdown shows how support volume is split between the widget, email inbound, and agent-handled conversations. Use this to understand which channels your customers prefer and where to focus knowledge base improvements.

Conversation history

Every conversation is logged and viewable in full - widget chats, agent replies, and email threads all in one place. Click any row to expand it and read the full exchange. Filter by status (open / resolved / escalated) or by source (widget / email).

Escalation & Ticketing

When the AI can't fully resolve a conversation, KnowDesk automatically escalates it - creating a ticket in your helpdesk provider, populating it with the full conversation, and syncing its status back to your dashboard in real time. No copy-paste, no manual triage.

How escalation works

Tickets dashboard

All escalated conversations appear in your Tickets dashboard. You can filter by status (open, pending, resolved, closed), date range, and provider. Click any row to read the full conversation transcript and see the AI-generated subject and priority.

AI-powered ticket enrichment

Per-widget configuration

On Enterprise plans, each widget can have its own escalation destination. For example, your Sales widget can escalate to Freshdesk while your Support widget escalates to Zendesk. Configure this in Widget Config → Escalation.

Two-way status sync

KnowDesk automatically polls Freshdesk, Zendesk, and Intercom for ticket status changes and mirrors them in your Tickets dashboard. Click ⟳ Sync Status at any time for an immediate refresh.

Custom webhook

The webhook destination sends a POST request to any URL you configure whenever a ticket is created or updated.

{
  "event":       "ticket.created",
  "ticket_id":   "kd_tk_abc123",
  "subject":     "Can't access my account after password reset",
  "priority":    "high",
  "status":      "open",
  "user_name":   "Jane Smith",
  "user_email":  "jane@acmecorp.com",
  "description": "User: I've been locked out...

AI: Let me help...",
  "created_at":  "2026-06-06T12:34:56Z",
  "widget_id":   "wdg_abc123",
  "company_id":  "cmp_xyz456"
}

Live Agent Inbox

The Live Agent Inbox lets your team reply to widget conversations in real time, directly from the KnowDesk dashboard. When a conversation is escalated - either because the customer asked to speak to a human, or because the AI could not find an answer - it lands in the Live Inbox and your agents can take over instantly.

Replies appear in the customer's chat widget immediately. No separate live chat tool, no new tab, no copy-pasting between systems.

How it works

Refresh rate

The conversation list refreshes automatically every 15 seconds. When you have a conversation open, the message thread refreshes every 6 seconds to pick up new customer messages without you having to do anything.

Sources

The Live Inbox shows conversations from two sources - widget (escalated chat conversations) and email (inbound email tickets). Each conversation shows a source label so your agents can tell at a glance which channel they are handling.

Order Lookup - Stripe, Shopify & Paystack

Connect your payment processor or e-commerce store and the AI widget will be able to look up order and payment details directly in the chat. When a customer asks "where is my order?" or "was my payment processed?", the AI queries your connected platform in real time and shares the details - no human needed.

Connecting a platform

1. Go to Commerce Integrations in your dashboard navigation
2. Click Connect next to the platform you want to add
3. Enter your API credentials:
   • Stripe - Secret Key (starts with sk_live_)
   • Shopify - Store domain (e.g. mystore.myshopify.com) + Admin API token
   • Paystack - Secret Key (starts with sk_live_)
4. Click Save. KnowDesk stores credentials encrypted and uses them for order lookups only.

How order lookup works in the chat

Once connected, the AI automatically detects when a customer is asking about an order or payment. It then:

Security

Your API credentials are stored encrypted in KnowDesk's secure storage. They are never exposed to the customer, logged in conversation history, or returned in any widget response. The lookup happens server-side on your Cloudflare Worker.

Email Inbound - Support Emails as Tickets

Email Inbound automatically converts every email your customers send to your support address into a ticket in the KnowDesk dashboard. The sender gets an instant acknowledgement. Your team handles everything from the Live Inbox. Nothing gets lost.

Your inbound address

Each widget has a unique inbound address in this format:

inbound+{your_widget_api_key}@knowdeskio-workers.com

Find your full inbound address in Settings → Email Inbound in your dashboard.

Setting up forwarding

What happens when an email arrives

Team Management

Add your colleagues so they can access the dashboard. Each team member gets a role that controls what they can see and do.

Roles

Inviting a team member

1. Go to Team in your dashboard
2. Click + Invite Member
3. Enter their email address and choose their role
4. Click Send Invite
5. They receive a magic link by email - clicking it creates their account and gives them access

Billing & Plans

All plans include a 7-day free trial. Toggle between monthly and annual pricing below - annual saves 20%.

Managing your subscription

Billing is handled by Stripe. To upgrade, downgrade, or cancel - go to Billing → Manage Billing. This opens the Stripe customer portal where you can update your plan, payment method, or download invoices.

Shopify billing

Merchants who install KnowDesk via the Shopify App Store are billed through Shopify's native billing system - not Stripe. Plan selection happens in the Shopify app on first install. To upgrade or cancel, manage app subscriptions directly from your Shopify admin.

Settings

Company info

Update your company name, website, and support email. These are used internally and on invoices.

Google Drive integration

To allow KnowDesk to read your Google Docs, share them with the service account email shown in Settings → Google Drive Integration. Set the permission to Viewer. You only need to do this once per document.

Widget API key

Your API key is the unique identifier in your embed code. It's safe to have in your website's HTML - it only authorises the widget to load content, not to modify data.

Password

Change your password from the Settings page. Enter your new password twice to confirm. You'll remain logged in on your current device.

WordPress & Shopify Plugins

KnowDesk is available as a free installable plugin for WordPress and Shopify. Both plugins embed your widget using your API key - no code changes needed on your site.

WordPress Plugin

The KnowDesk WordPress plugin is available free on the official WordPress Plugin Directory. It works on any WordPress site running version 5.8 or higher, including WooCommerce stores and multisite networks.

Installation

Display settings reference

Shopify App

The KnowDesk Shopify app embeds your widget on your storefront using a Theme App Extension - the modern Shopify standard that does not use the deprecated script_tags API. It is fully compliant with Shopify App Store review requirements.

Installation

Partner Integration API

The KnowDesk Partner Integration API allows platforms - such as Freshdesk, Zendesk, Intercom, help desk tools, and app marketplaces - to track customer installs and payments and automatically earn revenue share commission. This API is for Integration Partners who list KnowDesk in their marketplace or plugin directory.

How it works

The integration flow has three stages:

Authentication

All API requests must include your API key in the X-Api-Key header. Your API key is available in the KnowDesk admin panel under Partners → Integration Apps.

POST /api/integrations/freshdesk/track HTTP/1.1
Host: knowdesk.io
X-Api-Key: kd_int_live_a1b2c3d4e5f6g7h8i9j0
X-Webhook-Signature: sha256=3a5b8c...
Content-Type: application/json

Signing requests (recommended)

For added security, sign each request body with your webhook_secret using HMAC-SHA256 and include the result in the X-Webhook-Signature header. KnowDesk verifies this signature before processing.

const crypto = require('crypto');

function signPayload(body, secret) {
  return 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(body))
    .digest('hex');
}

const payload   = { event: 'install', external_account_id: 'fd_acct_123' };
const signature = signPayload(payload, process.env.KD_WEBHOOK_SECRET);

// Include in request:
// X-Webhook-Signature: sha256=3a5b8c9d...

Base URL

https://knowdesk.io/api/integrations/{your-app-slug}/track

Replace {your-app-slug} with the slug assigned to your integration (e.g. freshdesk, zendesk, intercom). Your slug is shown in the KnowDesk admin panel.

Event: install

Send this event when a user in your platform installs or activates KnowDesk. This creates the attribution record that ties future payments to your integration.

{
  "event": "install",
  "external_account_id": "fd_acct_abc123",
  "external_email": "owner@acmecorp.com",
  "company_id": null
}

{
  "ok": true,
  "event": "install_recorded"
}

// 401 - Invalid or missing API key
{
  "error": "Invalid API key or app not found"
}

// 401 - Signature mismatch
{
  "error": "Invalid webhook signature"
}

// 500 - Database error
{
  "error": "Internal error - please retry"
}

Event: payment

Send this event whenever the attributed customer makes a successful payment to KnowDesk. KnowDesk calculates your commission automatically based on the amount_cents and the commission percentage configured for your integration in the admin panel.

{
  "event": "payment",
  "external_account_id": "fd_acct_abc123",
  "amount_cents": 14900,
  "invoice_id": "in_1Abc2DefGhi3Jkl",
  "plan": "growth"
}

{
  "ok": true,
  "event": "payment_recorded"
}

Behind the scenes, KnowDesk:

1. Finds the integration_installs row for this external_account_id
2. Calculates your commission: amount_cents × (commission_pct / 100)
3. Creates a partner_earnings record with status: "pending"
4. Updates the integration app's revenue_shared_cents total
5. After 7 days the earning is confirmed and included in your next monthly payout

Event: uninstall

Send this event when a customer removes or deactivates KnowDesk from your platform. Commission generation stops from this point. The customer's existing confirmed earnings are not affected.

{
  "event": "uninstall",
  "external_account_id": "fd_acct_abc123"
}

{
  "ok": true,
  "event": "uninstall_recorded"
}

Commission calculation

Your commission percentage is configured by the KnowDesk admin team when your integration is approved. The default for Integration Partners is 20%. This can be adjusted by the KnowDesk team at any time from the admin panel.

Viewing your earnings

All commission records are visible in your integration's revenue dashboard in the KnowDesk admin panel under Partners → Integration Apps → [Your App] → Revenue. You can also query earnings programmatically:

GET /api/integrations/freshdesk/earnings?from=2025-01-01&to=2025-12-31
X-Api-Key: kd_int_live_a1b2c3d4e5f6g7h8i9j0

{
  "app": "freshdesk",
  "period": {
    "from": "2025-01-01",
    "to":   "2025-12-31"
  },
  "install_count":        42,
  "total_revenue_cents":  328500,
  "total_commission_cents": 65700,
  "commission_pct":       20,
  "status_breakdown": {
    "pending":   12300,
    "confirmed": 18400,
    "paid":      35000
  },
  "recent_earnings": [
    {
      "id":             "pe_abc123",
      "amount_cents":   2980,
      "commission_pct": 20,
      "mrr_cents":      14900,
      "status":         "confirmed",
      "period_start":   "2025-05-01",
      "created_at":     "2025-05-03T14:22:11Z"
    }
  ]
}

Payout schedule

Earnings follow this lifecycle:

Error reference

Full integration example

Below is a complete Node.js example showing the full install → payment → uninstall flow using the KnowDesk Partner Integration API.

const crypto  = require('crypto');
const fetch   = require('node-fetch'); // or native fetch in Node 18+

const API_KEY    = process.env.KD_API_KEY;           // kd_int_live_...
const WH_SECRET  = process.env.KD_WEBHOOK_SECRET;
const BASE_URL   = 'https://knowdesk.io/api/integrations/your-slug/track';

function sign(body) {
  return 'sha256=' + crypto
    .createHmac('sha256', WH_SECRET)
    .update(JSON.stringify(body))
    .digest('hex');
}

async function track(payload) {
  const res = await fetch(BASE_URL, {
    method:  'POST',
    headers: {
      'Content-Type':       'application/json',
      'X-Api-Key':          API_KEY,
      'X-Webhook-Signature': sign(payload),
    },
    body: JSON.stringify(payload),
  });
  const data = await res.json();
  if (!res.ok) throw new Error(data.error || 'KnowDesk API error');
  return data;
}

// 1. Customer installs KnowDesk from your marketplace
await track({
  event:               'install',
  external_account_id: 'acct_abc123',
  external_email:      'owner@customer.com',
});

// 2. Customer's subscription payment succeeds (hook into Stripe webhook)
await track({
  event:               'payment',
  external_account_id: 'acct_abc123',
  amount_cents:        14900,        // $149.00
  invoice_id:          'in_stripe_invoice_id',
  plan:                'growth',
});

// 3. Customer uninstalls
await track({
  event:               'uninstall',
  external_account_id: 'acct_abc123',
});

Testing your integration

Use the test API key (prefixed kd_int_test_) during development. Test events are processed identically to production but do not create real commission records. Your test API key is available alongside your live key in the KnowDesk admin panel.

https://knowdesk.io/api/integrations/your-slug/track
X-Api-Key: kd_int_test_a1b2c3d4e5f6g7h8i9j0

Frequently Asked Questions