KnowDesk: AI Customer Support Platform with 300+ Agents

KnowDesk is more than a knowledge base chatbot - it is an AI customer support platform with 300+ purpose-built agents. Connect your docs (Google Docs, PDFs, Notion, Confluence, plain text) and deploy a branded AI widget in minutes. Support Agents handle WISMO queries, returns, and carrier claims. Brand Agents review ad copy, listings, and content for brand consistency. Retention Agents run abandoned cart flows, winback campaigns, and VIP segmentation. Mission Control aggregates GA4, Stripe, and Gorgias into one view with anomaly alerts. When a conversation needs a human, agents reply from the Live Inbox. When a customer asks about an order, the AI looks it up live.

This guide covers every feature - from your first widget deploy to configuring agents, Mission Control, QA Reviews, Vertical AI, and the Partner Integration API. Follow sections in order for your first setup, or jump using the left navigation.

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

Connecting ClickUp#

KnowDesk can read your ClickUp Spaces, Docs, and Chat channels as knowledge sources. Connect via OAuth - no API key needed.

Syncing sources#

Connected sources that read a live copy - Google Docs, websites, sitemaps, help centres, GitHub and Airtable - re-sync on their own every few hours. Manual text, PDFs, videos, Notion, Confluence and ClickUp don't, so click the ⟳ Sync button after editing one of those, or to pull any change in right away. 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 AI. 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.

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.

Voice AI - Phone Support#

Voice AI gives your business a dedicated phone number answered by a real-time AI agent - not a menu tree, an actual conversation. It automatically inherits the same knowledge base, brand tone, and Vertical AI tools you already configured in Widget Config, so there's nothing to rebuild - just a number to turn on.

1. Get a phone number#

Open Dashboard → Voice AI. The Numbers panel lets you provision a number two ways:

Once a number is active, assign it to the widget whose knowledge base and Vertical AI setup should answer those calls. If you run multiple widgets, use the Widget selector at the top of the settings panel to switch between them.

2. Configure the caller experience#

Settings reference#

Minutes, wallet, and overage#

The top of the Voice AI page shows three live numbers: minutes used this billing cycle, minutes included on your plan, and your prepaid wallet balance. When included minutes run out mid-cycle, calls continue drawing from the wallet rather than cutting off - top it up any time from the Buy Minutes panel.

Call log#

Every call is logged with its transcript, duration, and outcome - resolved by AI, transferred to a human, or escalated. Missed calls that couldn't be answered live appear in the callback queue so your team can follow up.

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://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://knowdesk.io/widget.js" 
      data-key="kd_live_your_api_key_here">
    </script>
  </body>
</html>

Works on any platform#

Mobile apps: the Android and iOS SDK#

Put your support chat inside your own Android and iOS apps. It's the same chat as your website widget - AI answers from your knowledge base, hand-over to live agents, tickets, ratings, attachments, transcripts and browser calls - shown full-screen, plus push notifications when an agent replies. New widget features reach your app without an app update.

Before you start#

Android#

dependencies {
    implementation("io.knowdesk:knowdesk-android:1.0.0")
}

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        KnowDesk.init(this, "kd_live_your_api_key")
    }
}

// e.g. in your Help screen
helpButton.setOnClickListener { KnowDesk.open(this) }

Push notifications on Android use your app's own Firebase project. Pass the token to KnowDesk and forward messages that arrive while the app is open:

FirebaseMessaging.getInstance().token.addOnSuccessListener { KnowDesk.setPushToken(it) }

class MyMessagingService : FirebaseMessagingService() {
    override fun onNewToken(token: String) = KnowDesk.setPushToken(token)
    override fun onMessageReceived(m: RemoteMessage) {
        if (KnowDesk.handlePush(this, m.data, m.notification?.title, m.notification?.body)) return
        // ...your own messages
    }
}

// Your launcher activity: a tapped reply notification opens the chat
override fun onCreate(savedInstanceState: Bundle?) { /* ... */ KnowDesk.handleIntent(this, intent) }
override fun onNewIntent(intent: Intent) { super.onNewIntent(intent); KnowDesk.handleIntent(this, intent) }

// Android 13+: ask at a moment that makes sense, e.g. after the first chat
KnowDesk.requestNotificationPermission(activity)

iOS#

In Xcode choose File → Add Package Dependencies… and enter https://github.com/knowdesk/knowdesk-ios, or add pod 'KnowDesk' to your Podfile.

import KnowDesk

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    KnowDesk.configure(apiKey: "kd_live_your_api_key")
    return true
}

// e.g. in your Help screen
KnowDesk.present(from: self)

Add these to Info.plist so customers can attach photos and make browser calls from the chat:

// after the user allows notifications
UIApplication.shared.registerForRemoteNotifications()

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken token: Data) {
    KnowDesk.setPushToken(token)          // or KnowDesk.setFirebaseToken(fcmToken) if you use Firebase on iOS
}

// UNUserNotificationCenterDelegate
func userNotificationCenter(_ c: UNUserNotificationCenter, willPresent n: UNNotification,
                            withCompletionHandler done: @escaping (UNNotificationPresentationOptions) -> Void) {
    done(KnowDesk.shouldPresentInForeground(n.request.content.userInfo) ? [.banner, .sound] : [])
}
func userNotificationCenter(_ c: UNUserNotificationCenter, didReceive r: UNNotificationResponse,
                            withCompletionHandler done: @escaping () -> Void) {
    KnowDesk.handleNotificationTap(r.notification.request.content.userInfo)   // opens the chat
    done()
}

Signed-in users#

When your app knows who the customer is, tell KnowDesk. Their chat history then follows them to every phone, they're never asked for their name and email, and agents see who they are. To stop anyone pretending to be another user, your server signs the user id with the widget's identity secret (HMAC-SHA256, hex) and the app passes that signature on. Never put the secret in the app.

// Android
KnowDesk.identify(user.id, userHashFromYourServer, user.name, user.email)
// iOS
KnowDesk.identify(userId: user.id, userHash: userHashFromYourServer, name: user.name, email: user.email)

// on sign-out (forgets the chat on this device, stops its notifications)
KnowDesk.logout()

// Node.js
const userHash = crypto.createHmac("sha256", process.env.KNOWDESK_IDENTITY_SECRET).update(String(user.id)).digest("hex");

// PHP
$userHash = hash_hmac("sha256", (string) $user->id, getenv("KNOWDESK_IDENTITY_SECRET"));

# Python
user_hash = hmac.new(os.environ["KNOWDESK_IDENTITY_SECRET"].encode(), str(user.id).encode(), hashlib.sha256).hexdigest()

Push notifications#

When an agent replies in the Live Inbox, KnowDesk sends the notification with your app's own push keys, so it carries your app's name and icon. Add them in Widget Config → Mobile apps:

Open the chat once in your app with notifications allowed, then use Send a test notification. For iOS development builds, tick Development builds (sandbox); untick it for TestFlight and the App Store.

Unread badge and events#

// Android
KnowDesk.listener = object : KnowDeskListener() {
    override fun onUnreadCountChanged(count: Int) { helpBadge.isVisible = count > 0 }
    override fun onError(message: String) { Log.w("KnowDesk", message) }
}

// iOS - class MyHelp: KnowDeskDelegate { func knowDesk(unreadCountChanged count: Int) { ... } }
KnowDesk.delegate = self

White-label partners#

If your clients use your own domain, load the chat from it so your brand is used throughout: KnowDeskOptions(baseUrl = "https://help.yourdomain.com") on Android, KnowDeskOptions(baseURL: URL(string: "https://help.yourdomain.com")!) on iOS.

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 Growth plans and up, 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, Intercom, and Zoho Desk 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":  "[email protected]",
  "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.

To ask a teammate for help on a conversation, coach an agent with whispered replies, or call the customer - free in the browser or on their phone - see Huddle.

Huddle: Team Chat & Calls#

Huddle puts team chat, voice calls and customer calling inside the Live Inbox, so an agent never leaves a conversation to get help, talk a problem through with a colleague, or speak to the customer. Open it with the Huddle button at the top of the Live Inbox.

Team chat#

Team channel and direct messages

One channel for the whole workspace plus one-to-one messages, with unread counts, @mentions and presence: online, busy, away or on a call.

Get help

On any conversation, Get help opens a team thread linked to it, with a 3-line AI summary of the chat (who the customer is, the issue, what was tried). Whoever joins becomes a collaborator and is shown in the conversation header. The customer sees nothing.

Whisper replies

Owners, admins and QA leads watching a live chat can draft a reply only the agent sees. The agent inserts it with one click, edits it if needed, and sends it as their own.

@KnowDesk

Ask @KnowDesk a question in any thread - for example “what is our refund policy for sale items?” - and it answers from the workspace's knowledge base.

Translation

Team messages can be shown in each reader's dashboard language.

Notifications

In-app, desktop and sound alerts for mentions, help requests and calls. Do not disturb silences all of them.

When a conversation is resolved or closed, its help threads are marked solved. QA reviewers see the help threads and who joined, whispered or called on the conversation's review page (hidden in blind reviews).

Calls between teammates#

Start a free voice call from a direct message, a help thread or the Team channel. Calls run in the browser - there are no call charges - with mute, screen share, microphone and speaker choice, a call-quality indicator and a speaking ring on each person. A call keeps going while you move between dashboard pages. Ringing reaches teammates on any dashboard page; unanswered calls show a missed-call notice, and the thread gets a call log line with who joined and for how long.

Choosing the call engine#

In Widget Config → Calls (Huddle), owners and admins choose the engine for each widget's calls:

Use Test connection to check the choice. Saving LiveKit details while Cloudflare is selected keeps them as a fallback: if a call can't connect, it offers to move everyone to the other engine. Tick Use for team calls on the widget whose engine staff-to-staff calls should use.

Calling customers#

Open a conversation in the Live Inbox and choose 📞 Call in its header.

Voice AI hand-over to an agent's browser#

Agents who switch on Take phone calls in this browser in the Huddle panel receive Voice AI hand-overs: when the AI decides a caller needs a person, it rings an online agent's browser with the AI's briefing on screen, before trying your forwarding number. The tab needs to stay open to receive calls.

AI on calls, recording and consent#

Nothing is recorded or transcribed until the customer agrees. On a browser call they answer a question on the call page; on a phone call a spoken notice plays when they answer and the agent confirms the reply. If the customer says no, the call goes ahead without recording or transcript, and the conversation shows “Not recorded”.

Omnichannel - WhatsApp, Messenger, Instagram, Slack & Telegram#

Omnichannel lets customers reach you on the messaging apps they already use - WhatsApp Business, Facebook Messenger, Instagram, Slack, and Telegram - while your team answers everything from the single Live Agent Inbox. Inbound messages land in the same place as widget chats and email tickets, and every reply your team sends routes back automatically to the exact channel the customer wrote from - just like email. There is also a hosted WebChat page you can share as a plain link, with nothing to embed.

How it works#

Supported channels#

Email is also a channel in the same inbox - see Email Inbound for its setup.

Connecting a channel#

Every channel is configured per widget. Open Dashboard → Widgets → your widget → Omnichannel, then connect the channels you want. Connect once and the channel works everywhere that widget is embedded.

Telegram

1. In Telegram, open @BotFather and send /newbot. Give the bot a name and username.
2. BotFather replies with an HTTP API token (looks like 123456:ABC-DEF...). Copy it.
3. In the KnowDesk Omnichannel card, click Connect next to Telegram.
4. Paste the token and click Connect. KnowDesk registers the webhook and shows the bot username as the connection label.

WhatsApp, Messenger & Instagram (via Facebook)

1. In the Omnichannel card, click Connect via Facebook.
2. Sign in with the Facebook account that manages your Page / WhatsApp Business account and grant the requested permissions.
3. Back in KnowDesk, choose which assets to attach to this widget: a Facebook Page for Messenger, an Instagram account, and/or a WhatsApp number.
4. Click Confirm. KnowDesk subscribes each channel's webhook and the rows show as connected.

Slack

1. Click Connect next to Slack in the Omnichannel card.
2. Authorize the KnowDesk app in your Slack workspace and pick the channel to link.
3. Messages posted in that channel become conversations in the Live Inbox; agent replies post back into the same Slack thread.

Hosted WebChat

1. Click Enable next to WebChat.
2. KnowDesk generates a public page at knowdesk.io/chat/your-slug.
3. Share that link anywhere - an email signature, a QR code, a social bio, a support article. No website or embed code required.

How replies route back#

KnowDesk records the origin channel on every conversation. When the AI or an agent sends a message, it is delivered back through that same channel using the stored credentials - Messenger replies go to Messenger, Telegram replies go to Telegram, and so on. If a provider rejects a delivery (for example, WhatsApp's 24-hour customer-service window has closed), the failure is surfaced in the Live Inbox rather than failing silently.

Benefits#

• One inbox for everything - agents handle every channel in one screen, with no app-switching and no lost context.
• The same AI on every channel - knowledge-base answers, order lookup, escalation, and QA reviews all work identically no matter where the customer wrote from.
• No friction for customers - people stay in the app they already use and get replies there natively.
• Per-widget control - connect a channel to one widget or brand without affecting any other widget.
• Full history and analytics - every channel conversation is logged, searchable, and included in analytics with a per-channel breakdown.

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 Integrations → Email Inbound in your dashboard.

Setting up forwarding#

What happens when an email arrives#

Workflow Automation#

Workflows let you automate support processes without code. Each workflow starts from a trigger - a chat intent, a live-call event, a QA outcome, a resolved conversation, or a manual run - then walks through paths of steps on a visual canvas, branching on any field the trigger or an earlier step produced. Steps call ready-made blocks: order lookups, returns, tickets, win-back emails, SLA checks, warm call transfers, custom webhooks and more.

You’ll find everything under Dashboard → Workflows, which has three tabs: Rules, Block Library and My Workflows.

Core concepts#

Trigger

What starts a run: a chat intent rule, a live-call event, a QA outcome, a resolved conversation, or a manual/test run.

Path

A box on the canvas holding an ordered list of steps. Every workflow has one entry path where the run begins.

Step

Either an action (calls a block) or a delay (waits up to 10 minutes). Steps in a path run top to bottom.

Branch

A connection from one path to the next. It can carry a condition, or be the “else” branch used when no condition matches.

Block

A reusable action from the Block Library - 42 blocks across 11 categories, each available on specific plans.

Run

One execution of a workflow. Every run is recorded with the status and output of each step.

The three tabs#

Triggers#

Build your first workflow#

Branches and conditions#

When a path finishes its steps, its branches are checked in order. The first branch whose condition matches wins; if none match, the else branch is used; if there’s no else branch, the run ends. A path can have any number of branches (switch/case style), and several branches can lead back into the same path.

Conditions can read nested fields with dot paths, for example order.status or summary.total_conversations. The field picker suggests every output a block really returns, and where a field has known values (such as true / false), those are suggested too.

Templating with {{field}}#

Any text setting can include placeholders. When the step runs, each {{field}} is replaced with that value from the trigger or an earlier step - dot paths work here too. If a value doesn’t exist, the placeholder is left as-is so you can spot it in Run history.

Hi {{customer_name}}, your order {{order.id}} is {{order.status}}.
We've opened ticket {{ticket_id}} and will update you within 24 hours.

Built-in fields reference#

Every run carries a context: the fields its trigger supplies, plus everything each block returns as it finishes. Branch conditions and {{field}} placeholders read from it. These are the fields you can rely on.

From the trigger

Chat intent - widget, WhatsApp, social and inbound email:

Live call event (Voice AI):

QA outcome:

Conversation resolved:

Manual:

A manual run supplies no fields - only what you enter in the test console’s Test data.

Channel values

From blocks (available after the step runs)

When a step finishes, its result merges into the context - a later step or branch can use these. Where a field only ever takes certain values, they’re listed (and the branch editor suggests them).

When is a field available?#

A field exists from the moment it’s created: trigger fields from the start, block fields only after that block’s step finishes. A placeholder for a field that doesn’t exist yet stays as written - for example {{ticket_id}} inside the very step that creates the ticket. The Connection check flags these: “only a later step creates it” or “this step is what creates it”.

A step’s own settings always win over context fields with the same name - so an escalation step’s message setting is what gets sent, even though a chat trigger also carries the customer’s message.

Route by channel#

Steps in a path always run top to bottom, so to do something different per channel, branch on channel. Example: hand website chats to the Live Inbox, but turn emails into a help-desk ticket - and alert Slack only for urgent cases.

Delays#

Add a delay step to wait before the next action - for example, a short pause before a follow-up. Delays are capped at 10 minutes per step. On live-call workflows, delay steps are skipped so callers never hear dead air.

Ready-made templates#

Custom webhooks (Slack, Teams or your own API)#

The Call a custom webhook block connects a workflow to anything that isn’t pre-built. It sends an HTTPSPOST with a JSON body containing the step’s own settings plus everything the trigger and earlier steps supplied.

{
  "text": "🔔 Refund request from {{customer_email}} - order {{order.id}} is {{order.status}}",
  "customer_email": "[email protected]",
  "order": { "id": "4821", "status": "delivered" }
}

Escalate & create ticket: Live Inbox or help-desk ticket#

Want both? Add the step twice in the same path - live_chat first, then ticket - or route by channel (above).

Your message becomes an internal note

The step’s message setting is added to the conversation as an internal note from “Workflow” - never shown as something the customer said.

Closed conversations go back to the Queue

Escalating a closed or resolved conversation clears the previous agent and puts it back in the Queue.

Ticket integrations are per widget

A ticket uses the help desk connected to the widget the chat came in on. Connect it for every widget that should create tickets - the Connection check lists which widgets are covered.

AI subject & priority

On plans with AI priority, the ticket’s subject and priority are set by AI from the conversation.

Workflows on live calls#

Call-event workflows run inside the live call, so they can act on it directly with three Voice AI blocks: warm transfer to a human with a briefing, end the call, and send a follow-up SMS.

Test & verify#

Every workflow has a Test & verify console with three modes. Your canvas is saved automatically before each run, and the execution log replays each step - click any line to inspect it in Step output.

Test data

The form matches your trigger. For chat rules it shows whether your message fires the rule, using your real phrases. Other fields:

Channel

Pretend the chat came from widget, email, whatsapp… to test channel branches.

Conversation ID (optional)

Paste a real conversation ID from the Live Inbox to test with its full chat. Left empty, your test message is used as the conversation.

Extra fields

Any other values as JSON, e.g. {"priority": "urgent"} to send a Simulate run down your urgent branch. In a Live run, block results replace these.

Every simulation and live run is also listed in Run history with a Test or Live badge, its status and each step’s output.

Limits and safety#

Troubleshooting#

QA Reviews - Agent Quality Scorecard#

KnowDesk's built-in QA module lets you score any support conversation across 9 weighted attributes, run calibration sessions to align your QA team, and give every agent a private coaching portal - all without a separate tool. It is designed to replace ad-hoc spreadsheet reviews with a structured, auditable, data-driven process.

The 9 QA Attributes#

Every review scores the following attributes on a 1–5 scale. Each can be independently weighted, have auto-fail enabled, or be disabled entirely from the Settings tab.

Score scale#

How to start a QA review#

Smart Queue - AI-prioritised sampling#

Enable Smart Queue from the toggle in the Queue tab. KnowDesk scores each conversation across four risk signals and surfaces the most important ones first:

Calibration Sessions#

Calibration ensures your QA reviewers are scoring consistently. In a calibration session, a second reviewer scores the same conversation independently - KnowDesk then computes a per-attribute and overall inter-reviewer agreement rate. A QA Lead (or admin/owner) resolves any differences and sets the final agreed scores.

Agreement rate calculation

The overall agreement rate is the average across all non-N/A attribute pairs. ≥80% is considered strong, 60–79% moderate, below 60% divergent and requires discussion before resolution.

Starting a calibration review

1. Go to QA Reviews → Queue
2. Find a conversation that already has a submitted review
3. Click Calibrate next to that conversation
4. A second draft review is created with the is_calibration flag
5. A second QA reviewer opens the conversation and scores it independently - without seeing the first reviewer's scores
6. After submission, a QA Lead navigates to QA Reviews → Calibration and clicks Compare & Resolve

Resolving a calibration session

On the calibration comparison page, the QA Lead sees Reviewer A scores and Reviewer B scores side by side for every attribute. For attributes where scores differ, quick-pick buttons let you Use A, Use B, or Average with one click. A resolution note documents the rationale. On submission, the original review's final scores are updated and the calibration review is marked resolved.

Agent Coaching Portal#

Every team member with the Member role gets a personal QA Scores page at /dashboard/qa/my-scores. This private portal shows all their submitted QA reviews, per-attribute score averages, coaching notes from reviewers, and an "Areas to Focus On" panel highlighting their three lowest-scoring attributes.

Agents are notified on their dashboard home when new unviewed QA reviews are waiting. The notification clears automatically once they visit their coaching portal. No email setup required - the notification is in-product.

QA Settings - Weights, Auto-Fail & Attribute Configuration#

Admin, owner, and QA Lead roles can configure the scorecard from QA Reviews → Settings. Three controls are available per attribute:

QA Analytics & Weekly Reports#

The Analytics tab inside QA Reviews shows aggregate metrics across all submitted reviews: total reviews, average QA score, open disputes, auto-fail count, agent leaderboard sorted by score, attribute performance heatmap (average score per attribute), and a weekly score trend chart.

Admin, owner, and QA Lead roles can click Send Weekly Report to generate a styled HTML email report covering the last 7 days - agent leaderboard, attribute averages, score trends - and preview it before sending. The report is logged in the qa_report_logs table for audit purposes.

Roles and QA access#

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": "[email protected]",
  "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:      '[email protected]',
});

// 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

Vertical AI#

Vertical AI transforms your KnowDesk widget into an industry-specific AI assistant. Instead of a generic Q&A bot, visitors get a structured booking, intake, or product-lookup experience - all powered by your own data. Available on Growth, Scale and Enterprise plans.

Activating Vertical AI#

Real Estate#

The Real Estate vertical lets visitors search your property listings, ask about availability, and submit booking or viewing requests - all inside the widget. Your data is synced from a spreadsheet, database, or REST API.

Required data columns

Healthcare#

The Healthcare vertical allows patients to check provider availability, ask about appointment types, and submit booking requests. Your appointment and provider data is pulled from a spreadsheet or API.

Required data columns

Legal#

The Legal vertical allows prospective clients to check attorney availability, understand practice areas, and schedule consultations - directly inside the widget.

Required data columns

Data Source Setup (Real Estate, Healthcare & Legal)#

All three verticals use the same five data source types. Choose the one that matches where your data lives.

Google Sheets

Airtable

REST API

CSV Upload

Notion

Ecommerce#

The Ecommerce vertical connects your store platform directly to the widget, enabling customers to look up orders, understand return policies, submit post-purchase issues, and complete intake forms - all without leaving the chat.

Platform connections

Setting up Shopify

Setting up WooCommerce

Order lookup rules

Configure how customers identify their order. You can enable lookup by email address, order number, or both. You can also require the customer to provide both to match - useful for stores with high volume where order numbers may collide.

Return policy

Paste your return policy text in the Return Policy field. The AI reads this verbatim when customers ask about returns or refunds. Keep it plain text - no HTML or markdown needed.

Post-resolution actions

Choose what happens after the AI answers a post-purchase question. Options: escalate to live agent, create a support ticket (if escalation is configured), or show a custom message. You can set a different action per question type (refund request vs. delivery inquiry vs. general complaint).

Custom Question Flow Builder#

All four verticals include a question flow builder. This lets you define the structured questions the AI asks before fulfilling a visitor request - for example, asking for name, phone, and preferred viewing time before recording a property enquiry.

Adding a question

1. In the Vertical AI panel, scroll to Intake Questions
2. Click + Add Question
3. Enter the question text (e.g. "What is your preferred viewing date?")
4. Choose the response type: Text, Date, Phone, or Email
5. Mark as Required if the visitor must answer before proceeding
6. Click Save

Questions are shown to visitors in the order they appear in the list. Drag to reorder. The AI does not proceed to the booking confirmation step until all required questions are answered.

Confirmation emails

Enable Send confirmation email in the Vertical AI panel to automatically email the visitor a summary of their submission. The email includes their answers, the time of submission, and a reference number. No SMTP setup required - KnowDesk sends it from your configured support email.

What the visitor sees#

AI Agents#

KnowDesk ships 300+ AI agents across four categories - Support, Content & Brand, Email & Retention, and Ops & Reporting. Unlike generic chatbots, each agent is pre-trained for a specific workflow. You activate them from the Agents tab in your dashboard; no prompt engineering or custom training required.

Agent availability depends on your plan. Agents marked Growth+ require a Growth plan or higher. Agents marked Scale+ require a Scale plan. Enterprise agents are available on the Enterprise plan only.

Migrating from Another Helpdesk#

KnowDesk includes a full data migration engine so you can switch from Intercom, Zendesk, Freshdesk, or Zoho Desk without losing your conversation history, customer context, or support intelligence. Your historical data is imported, your customers never notice the switch, and the AI has full context from day one.

What Gets Migrated#

Each imported record is normalised into a common schema and stored in your KnowDesk account:

• Conversations - full message body, platform reference ID
• Contacts - visitor name and email address
• Topics / Tags - conversation labels mapped to KnowDesk topics
• CSAT Scores - satisfaction ratings normalised to a 0–5 scale
• Resolution Time - time-to-resolve in seconds, stored for analytics

How to Run an Import#

Go to Dashboard → Data Migration and follow the 6-step wizard:

1. Select platform - choose your source helpdesk (Intercom, Zendesk, Freshdesk, or Zoho Desk)
2. Upload file - drag and drop your export file (JSON, CSV, or XML, up to 50 MB). Auto-detection reads the file structure and identifies the platform automatically. You can override the detected platform if needed.
3. Review field mapping - KnowDesk auto-maps source fields to its own schema. You can enable or disable any field before proceeding.
4. Confirm - review the record count, contact count, and mapping summary before starting.
5. Import - records are processed in the background in batches of 100. A live progress bar updates every few seconds. You can close the page - the import continues server-side.
6. Done - a summary shows how many conversations and contacts were imported, how many errors occurred, and a link to download the error log if any records failed.

Exporting Data From Your Current Platform#

Before uploading to the import wizard, you need to export your data from your current helpdesk. Steps vary by platform:

AI Memory Layer#

After a successful import, KnowDesk automatically builds an AI Memory Layer - a profile for every unique contact in your imported data. Each profile aggregates:

• Number of past conversations
• Most common issue types (from conversation topics)
• Average CSAT score
• Date of last contact
• A plain-text summary: "Customer name: Alice · Previous interactions: 4 conversations · Past issues: billing, shipping · Average satisfaction: 3.8/5 · Last contact: 12 July 2026"

When a returning visitor opens the widget and their email address is known (either from a pre-chat form or a previous session), KnowDesk injects this context into the AI system prompt automatically. The AI greets them by name and responds with awareness of their history - without you writing any code.

Contacts with an average CSAT score below 3.0 are automatically flagged as coaching needed, surfacing them for your QA team.

Platform Field Mapping Reference#

KnowDesk auto-maps these fields from each supported platform:

Import History#

Past import jobs are listed at the bottom of the Data Migration page with their status (queued, processing, complete, error), record counts, and timestamps. You can download the error log for any failed job in JSON format.

Frequently Asked Questions#

A complete self-service customer support portal - and the tools to keep it excellent