# Clanker Support — Full Documentation

> An AI-powered support agent for your site — install it with one script tag or one React Server Component (@clankersupport/widget-rsc on npm). It answers from your docs and sources, then escalates to your team. Open source (MIT) and self-hostable (bring your own keys).

Site: https://clankersupport.com · Docs: https://docs.clankersupport.com · Dashboard: https://app.clankersupport.com

This file concatenates the full text of every documentation page below.

# Getting started
URL: https://docs.clankersupport.com/getting-started
Clanker Support puts an AI-powered support agent on your website: it answers visitor questions from your knowledge base, hands off to your team when needed, and every conversation lands in your dashboard inbox. Setup takes a few minutes — create an account, build your agent, and drop one script tag on your site.

## 1. Create an account

Sign up at [app.clankersupport.com/sign-up](https://app.clankersupport.com/sign-up) with an email and password, or continue with Google or GitHub.

<ThemedImage alt="Sign up" basePath="/learn/sign-up" />

## 2. Build your agent

After signing up, onboarding walks you through two screens:

**Pick a plan.** Choose Starter, Growth, or Scale, billed monthly or annually (annual gives you two months free) — see the [pricing page](https://clankersupport.com/pricing) for details. A card is required; subscribing unlocks the build screen.

**Build the agent.** Fill in a few fields while the live preview on the right updates as you type:

| Field                     | What it does                                                                 |
| ------------------------- | ---------------------------------------------------------------------------- |
| **Agent name**            | How the agent introduces itself in the chat header                           |
| **Welcome message**       | The first message visitors see when they open the chat                       |
| **Brand color**           | Colors the launcher bubble and chat accents to match your site               |
| **Website to learn from** | Optional — a URL the agent reads and adds to its knowledge as a first source |

Click **Create my agent** to finish. You land on the new project's settings page.

<ThemedImage alt="Onboarding" basePath="/learn/onboarding" />

## 3. Install the widget

Open your project's settings and switch to the **Widget** tab. The **Install** section holds a ready-made snippet with your project key filled in — copy it and paste it before the closing `</body>` tag on your site:

<ThemedImage alt="Install the widget" basePath="/learn/embed-snippet" />

```html
<script
	src="https://api.clankersupport.com/widget.js"
	data-project="pk_your_project_key"
	async
></script>
```

The same section offers an **Inline embed** (an iframe you can place anywhere on a page) if you don't want a floating bubble. Building with React or Next.js? The `@clankersupport/widget-rsc` SDK installs the same agent as a single component — see [Widget](https://docs.clankersupport.com/learn/widget).

## 4. Say hello

Open your site. The launcher bubble sits in the bottom-right corner — click it, enter a name (email is optional), and ask a question. The agent streams an answer built from your knowledge sources.

<ThemedImage alt="Widget" basePath="/learn/widget" />

Back in the dashboard, open **Conversations** — your test chat is already in the inbox with an AI summary. Reply from the composer and your message appears in the widget on your site. From here, add more knowledge under **Sources**, tune the agent's instructions and escalation settings under **Settings → Behavior**, and invite your site's visitors to talk to it.


# Introduction
URL: https://docs.clankersupport.com/
Clanker Support is an AI-powered support agent for your site. You install it with a single script tag (or the React SDK), point it at your knowledge base — website pages, text snippets, Q\&A pairs — and it answers visitor questions in a chat widget on your site. When a visitor needs a person, the agent hands the conversation off to your team, and every conversation lands in a shared inbox at [app.clankersupport.com](https://app.clankersupport.com).

Clanker Support is open source ([theopenco/llmchat](https://github.com/theopenco/llmchat), MIT). You can self-host the whole stack for free with your own LLM Gateway key, or use the hosted service — see [Pricing](https://docs.clankersupport.com/pricing) for plans.

## What you get

* **A support agent on your site** — streamed answers grounded in the knowledge sources you add, with a welcome message and brand color you control.
* **Escalation to humans** — the widget offers a handoff after a configurable number of messages — or immediately when the visitor asks; your team is notified by email (and Slack, if you add a webhook) and the agent stands down.
* **A shared inbox** — search, filters, tags, and a reply composer; replies reach the visitor in the widget, and by email when they shared an address.
* **Quality signals** — per-message thumbs up/down on answers, plus a separate 1–5 rating the visitor can leave for the conversation.
* **Your choice of install path** — a one-line script tag, a React/Next.js SDK, and connectors for Shopify and WordPress.

## How it fits together

A **workspace** is your team and billing account. Inside it you create **projects** — each project is one embedded widget with its own knowledge base, instructions, and AI model, so separate sites or products get separate agents. Every conversation a project's widget handles lands in the workspace's shared **inbox**, and when a visitor asks for a person, **escalation** notifies your team and hands the conversation to a human — the agent sends a brief holding note and goes silent once a teammate replies.

## Install in one line

Once you've created a project, the whole install is one script tag with your project's public key:

```html
<script
	src="https://api.clankersupport.com/widget.js"
	data-project="pk_…"
	async
></script>
```

Using React or Next.js? The `@clankersupport/widget-rsc` package gives you a `<ClankerSupport apiKey="pk_…" />` Server Component instead, restylable with CSS variables — see the [React SDK](https://docs.clankersupport.com/integrations/react-sdk).

## Four ways to install

* **[Script tag](https://docs.clankersupport.com/integrations/widget)** — one line, works on any site, no build step.
* **[React SDK](https://docs.clankersupport.com/integrations/react-sdk)** — `@clankersupport/widget-rsc` on npm; a Server Component for the drop-in path, plus headless primitives when you want full control.
* **[Shopify](https://docs.clankersupport.com/integrations/shopify)** — a theme app extension, coming soon to the Shopify App Store. Until then, Shopify merchants can paste the script tag into their theme.
* **[WordPress](https://docs.clankersupport.com/integrations/wordpress)** — a plugin with a settings page and a `[clanker_support]` shortcode. The wordpress.org listing is on its way; today it installs as a manual plugin upload.

## How these docs are organized

* **[Getting started](https://docs.clankersupport.com/getting-started)** — create your account and workspace, build your first agent, and install the widget on your site.
* **[Pricing](https://docs.clankersupport.com/pricing)** — plans, included AI responses, overage, and what self-hosting costs (nothing).
* **[Features](https://docs.clankersupport.com/features)** — what the product does: AI responses, knowledge sources, escalation, email threading, the team inbox, ratings, and self-hosting.
* **[Integrations](https://docs.clankersupport.com/integrations)** — the four install paths in detail: script tag, React SDK, Shopify, and WordPress.
* **[Dashboard](https://docs.clankersupport.com/learn)** — working in the dashboard: the inbox, escalation, tags and search, projects and widget settings, workspaces, and billing.

If you get stuck, use the **Help** button in the dashboard's top bar.


# Pricing
URL: https://docs.clankersupport.com/pricing
Hosted Clanker Support is usage-based and **paid-only** — there is no free hosted tier. You pay for what the agent actually does: every **AI response** it sends counts toward your plan's monthly quota. Replies your teammates send from the inbox are human replies — they are never metered — and there are no per-seat fees. Prefer to run it yourself? [Self-hosting](https://docs.clankersupport.com/features/self-hosting) is free.

## What counts as a response

* One AI-generated answer in the widget = **one response**, recorded the moment it's produced.
* Human replies from the [team inbox](https://docs.clankersupport.com/features/team-inbox) are unlimited and never counted.
* The counter resets at the start of each calendar month (UTC).

## Plans

All hosted plans are currently 50% off — every figure below shows the promotional price with the regular price alongside.

| Plan        | Monthly                   | Annual                   | AI responses/mo | Projects | Seats     | Models      | Branding                |
| ----------- | ------------------------- | ------------------------ | --------------- | -------- | --------- | ----------- | ----------------------- |
| **Starter** | $19 (normally $38) | $190 (normally $380)/yr | 2,000           | 2        | 3         | Basic class | "Powered by" badge      |
| **Growth**  | $89 (normally $178)  | $890 (normally $1,780)/yr  | 12,000          | 5        | 10        | All models  | No badge                |
| **Scale**   | $299 (normally $598)   | $2,990 (normally $5,980)/yr   | 50,000          | 20       | Unlimited | All models  | Custom branding allowed |

Annual billing is 10× the monthly price — **two months free**.

**Model access:** every project picks from a curated set of web-search-capable models. Starter is limited to the lighter "basic" class (mini/nano/haiku/flash/lite/small-class models); Growth and Scale unlock the full catalog. See [AI responses](https://docs.clankersupport.com/features/ai-responses).

## What happens past the quota

* **Starter** hard-stops: once the 2,000 included responses are used, the agent stops answering until the next month or an upgrade. Human replies keep working.
* **Growth and Scale** meter overage: responses beyond the included quota are billed per additional response through Stripe, so the agent never goes dark mid-month. Your usage — including how far over you are — is visible on the billing page.

## Enterprise

Enterprise is sold, not self-served — [contact us](https://clankersupport.com/pricing) if you need:

* Everything in Scale
* Custom response volume & pricing
* Unlimited projects & seats
* Enterprise controls on request — a DPA arranged with your agreement; SSO/SAML and audit logs on the Enterprise roadmap
* SLA + dedicated support channel
* White-glove onboarding & migration
* Self-host support contract

## Self-hosting is free

The entire stack is open source (MIT, [theopenco/llmchat](https://github.com/theopenco/llmchat)). Self-host it with your own LLM Gateway key — you pay your model provider directly, and nothing is metered by us. See [Self-hosting](https://docs.clankersupport.com/features/self-hosting).

## Managing your plan

You choose a plan during onboarding and manage it from the dashboard — usage meter, plan changes, invoices, and the Stripe billing portal all live at **Settings → Billing**. See [Billing & usage](https://docs.clankersupport.com/learn/billing) for the walkthrough, and the full pricing page at [clankersupport.com/pricing](https://clankersupport.com/pricing).


# AI responses
URL: https://docs.clankersupport.com/features/ai-responses
When a visitor asks a question, the support agent answers directly in the widget — the reply streams in word by word, so the visitor starts reading immediately instead of watching a spinner. Every answer is grounded in what you've taught that project: its active knowledge sources plus your instructions.

## Grounded in your knowledge

Each response is built from the project's active [knowledge sources](https://docs.clankersupport.com/features/knowledge-sources) — website pages, text snippets, and Q\&A pairs — together with the project's instructions. Sources you deactivate stop informing answers right away, and new sources apply to the next response as soon as they're ready.

The models the agent runs are all web-search-capable, so it can also search the web when a question calls for it — but your own sources are what anchor its answers about your product.

## Choosing a model

Every project picks its own AI model from a curated set of web-search-capable models. The default is `gpt-5.4-mini`, and you can change it per project — so a high-traffic marketing site can run a lighter model while your flagship product runs a stronger one.

Model access follows your plan:

* **Starter** — the lighter "basic" model class (mini, nano, haiku, flash, lite, and small-class models).
* **Growth and Scale** — the full catalog.

See [Pricing](https://docs.clankersupport.com/pricing) for the full plan comparison. If a plan change ever leaves a project saved on a model its plan no longer includes, the agent quietly falls back to the default model instead of going offline — your widget keeps answering.

## Instructions

Instructions are the project's system prompt: the agent's tone, focus, and boundaries. The agent answers from your sources first; instructions shape *how* it answers.

<ThemedImage alt="Project settings — Behavior tab with model and instructions" basePath="/learn/project-behavior" />

## Making it yours

Two widget settings shape the first impression of every conversation:

* **Welcome message** — the greeting the visitor sees when they open the widget.
* **Brand color** — applied to the widget so it matches your site.

Both are set per project, alongside the install snippet and a live preview.

## When the agent can't help

The agent doesn't answer forever. After a configurable number of visitor messages — or immediately, when the visitor asks for a person — the widget offers **Talk to a human**. From there the conversation hands off to your team and the agent stands down. See [Escalation](https://docs.clankersupport.com/features/escalation) for how the handoff works.

## Where to configure it

Model, instructions, welcome message, and brand color all live in the project's settings tabs in the dashboard — see [Project settings](https://docs.clankersupport.com/learn/project-settings) for a walkthrough.


# Email threading
URL: https://docs.clankersupport.com/features/email-threading
Visitors don't always stay on your site waiting for an answer. When a visitor shares their email address, Clanker Support keeps the conversation alive over email: your replies go out to their inbox, and their replies come back into the same thread — chat and email stay one conversation, with no separate ticket to reconcile.

## Replies reach the visitor both ways

Reply from the inbox composer and your message always appears in the visitor's widget — it polls for new messages, so the reply shows up even mid-session. If the visitor shared an email address, the same reply also goes out by email, so they see your answer whether they're still on your site or long gone. The composer's placeholder tells you when a reply will also be emailed.

<ThemedImage alt="Conversation thread with the reply composer" basePath="/learn/conversation-thread" />

## Visitor replies thread back automatically

When the visitor answers your email instead of returning to the widget, their reply lands back in the same conversation in your inbox — appended as a new visitor message, right where the thread left off.

Two mechanisms make the match:

* **Reply address.** Every project has its own reply address, and every outgoing email sets it as the Reply-To. When the visitor hits reply, their email routes straight back to the right project.
* **Message-ID matching.** Each outgoing reply carries a unique email Message-ID tied to the message it came from. When the visitor's reply references it (standard email threading, which mail clients do automatically), it's matched to the exact conversation. If that reference is missing, the sender's address is used as a fallback: the reply is threaded into their most recent conversation on that project.

The result: the visitor just replies to an email like they would to any other, and your team sees it in the inbox thread — no forwarding, no copy-pasting.

## Escalation email keeps the thread alive

[Escalation](https://docs.clankersupport.com/features/escalation) emails both sides, with different jobs:

* **Your team's notification** — sent to the project's notify address so a human knows to step in. Answer from the dashboard inbox (see [Conversations](https://docs.clankersupport.com/learn/conversations)) — your reply reaches the visitor in the widget and by email, with proper threading.
* **The visitor's acknowledgement** — a visitor who has shared an email address gets a confirmation that a human will follow up, and it seeds the email thread. Their reply to it threads back into the conversation automatically.

So a visitor who escalates and closes the tab loses nothing: your team's answer reaches them by email, and the back-and-forth continues in one thread.

## Zero setup on hosted

On the hosted service there is nothing to configure — every project gets its reply address automatically, and outgoing email works out of the box. The only thing that gates email delivery is the visitor: replies go out by email only when they've shared an address (the widget asks for a name and an optional email before the conversation starts).

If you [self-host](https://docs.clankersupport.com/features/self-hosting), email threading needs a Resend account with an inbound domain configured — that powers both escalation notifications and reply threading.

## Where to go next

* [Conversations](https://docs.clankersupport.com/learn/conversations) — reading a thread, replying, and how emailed replies appear in the dashboard.
* [Escalation & human handoff](https://docs.clankersupport.com/features/escalation) — when and how a conversation reaches your team in the first place.


# Escalation & human handoff
URL: https://docs.clankersupport.com/features/escalation
The support agent handles the questions your knowledge base can answer. For everything else, the visitor hands the conversation to your team — and the agent gets out of the way. No ticket form, no starting over: your team picks up the same thread, with everything the visitor already said.

## When the widget offers a human

Each project sets its own threshold: after a number of visitor messages (default **3**), the widget shows a **Talk to a human** option. Set it low to route visitors to your team quickly; set it higher to let the agent try more answers first.

A visitor who explicitly asks for a person doesn't wait for the threshold. When a message reads as a request for a human — "talk to a real person", "get me an agent", "escalate this" — the widget surfaces **Talk to a human** immediately, however early in the conversation it happens. Nobody has to argue with the agent to reach your team.

Either way, escalating stays the visitor's choice: the option appears, and the visitor clicks it.

## What the visitor sees

When the visitor chooses **Talk to a human**, a short recap appears in the chat — a sentence or two summarizing what they asked about and what's been covered, so they know the handoff carries their context and they won't have to repeat themselves. The **Talk to a human** option then disappears; a conversation escalates once.

## How your team finds out

An escalation notifies your team through every channel the project has configured, plus the dashboard itself:

* **Email** — sent to the project's notify address, when one is set.
* **Slack** — posted via an incoming webhook to a channel of your choice, when one is set.
* **Notification bell** — the escalation always appears in the dashboard's notification feed, and the conversation is flagged **Escalated** in the [team inbox](https://docs.clankersupport.com/features/team-inbox) so it stands out while triaging.

## The agent stands down

Escalation isn't just a notification — it changes who's answering:

1. **While your team is on the way**, if the visitor sends another message, the agent replies only with a brief holding note saying a human will follow up. It doesn't attempt an answer.
2. **Once a human replies**, the agent goes fully silent. Every later visitor message reaches only your team.

The handoff is one-way by design: a conversation a human has taken over stays with humans. A visitor who asked for a person is never bounced back to the agent mid-conversation.

From there it's a normal team conversation — replies from the inbox reach the visitor in the widget, and by email when they shared an address. See [Email threading](https://docs.clankersupport.com/features/email-threading) for how those replies stay in one thread.

## Configuration

The threshold, notify email, and Slack webhook all live on the project's **Behavior** tab. [Escalation in the dashboard](https://docs.clankersupport.com/learn/escalation) walks through each setting and how escalated conversations look in the inbox.


# Features
URL: https://docs.clankersupport.com/features
Clanker Support puts an AI-powered support agent on your site: it answers visitor questions from a knowledge base you control, hands off to your team when a person is needed, and keeps every conversation — chat and email — in one shared inbox. This page is the map; each feature page below covers one capability in depth, and the matching [Learn](https://docs.clankersupport.com/learn) pages show where everything lives in the dashboard.

## The features

### [AI responses](https://docs.clankersupport.com/features/ai-responses)

Streamed answers grounded in your knowledge sources and per-project instructions. Every project picks its model from a curated set of web-search-capable models, so the agent can search the web when answering.

### [Knowledge sources](https://docs.clankersupport.com/features/knowledge-sources)

Teach the agent with three kinds of source per project: website URLs (fetched as snapshots you refresh with **Recrawl**), text snippets, and Q\&A pairs. Operators can also promote a good inbox reply into a Q\&A source.

### [Escalation](https://docs.clankersupport.com/features/escalation)

The widget offers **Talk to a human** after a configurable number of messages — or immediately when the visitor asks for one. Your team is notified by email — plus Slack, if configured — and the dashboard bell; the agent posts a holding note and stands down for good once a human replies.

### [Email threading](https://docs.clankersupport.com/features/email-threading)

Inbox replies appear in the visitor's widget, and go out by email when the visitor shared an address. When they answer that email instead of returning to the chat, their reply threads back into the same conversation — no separate ticket to reconcile.

### [Team inbox](https://docs.clankersupport.com/features/team-inbox)

A shared inbox per workspace: filters, full-text search with a ⌘K command palette, colored tags, per-user unread state, AI-generated triage summaries in the list, and resolve and reopen. Roles (owner, admin, agent) are enforced server-side.

### [Ratings & CSAT](https://docs.clankersupport.com/features/ratings-csat)

Two distinct quality signals, never merged: per-message thumbs up/down on individual agent answers, and a separate 1–5 rating the visitor can leave for the whole conversation when they close it.

### [Self-hosting](https://docs.clankersupport.com/features/self-hosting)

The entire stack is open source ([theopenco/llmchat](https://github.com/theopenco/llmchat), MIT). Run it yourself for free with your own LLM Gateway key — you pay your model provider directly.

## Where to go next

* **[Getting started](https://docs.clankersupport.com/getting-started)** — from sign-up to a live widget on your site.
* **[Integrations](https://docs.clankersupport.com/integrations)** — install paths beyond the script tag: the React SDK, Shopify, WordPress, and the iframe embed.
* **[Pricing](https://docs.clankersupport.com/pricing)** — plans, included response quotas, and what's metered.
* **[Learn](https://docs.clankersupport.com/learn)** — the dashboard, page by page: inbox, projects, sources, workspaces, and billing.


# Knowledge sources
URL: https://docs.clankersupport.com/features/knowledge-sources
The agent answers from a knowledge base you build per project. Add the pages, policies, and answers that matter, and every reply the agent gives is grounded in that material — not just what the model happens to know.

## Three kinds of sources

| Kind             | You provide               | Good for                                              |
| ---------------- | ------------------------- | ----------------------------------------------------- |
| **Website URL**  | A page URL                | Docs, FAQs, pricing or shipping pages you already run |
| **Text snippet** | Free-form text, any title | Policies or facts that don't live on a public page    |
| **Q\&A pair**     | A question and its answer | Precise answers to questions visitors ask often       |

A fourth kind, file upload, is coming soon.

Each project has its own knowledge base, so separate sites or products get separately trained agents.

## How grounding works

Every **active** source in the project feeds every answer, alongside the project's instructions (its system prompt). There's no separate indexing or training step — add a source and the very next conversation can draw on it; deactivate or delete one and the agent stops using it immediately.

The agent's answers, model choice, and instructions are covered in [AI responses](https://docs.clankersupport.com/features/ai-responses).

## Website sources are snapshots

A website source is fetched **once, when you add it**. It does not track your live site — publishing changes to a page does not change what the agent knows.

To update the agent after you edit a page, press **Recrawl** on that source in the dashboard. Recrawl re-fetches the URL and replaces the stored snapshot with the current page. It's also the fix for a failed fetch: correct whatever blocked it, then recrawl.

## Status at a glance

Every source carries a status chip in the dashboard:

* **Ready** — a website source fetched successfully; the snapshot is in use.
* **Pending** — a website source that hasn't completed its first fetch.
* **Failed** — the last fetch errored; fix the page or URL and recrawl.
* **Saved** — a text snippet or Q\&A pair, stored exactly as you wrote it.
* **Off** — a deactivated source; it stops informing answers until you switch it back on.

Only website sources have a fetch lifecycle.

## Turn good replies into knowledge

When a teammate answers a visitor in the [team inbox](https://docs.clankersupport.com/features/team-inbox), that reply is often worth teaching the agent. Every teammate reply has an **Add to knowledge** action: it pre-fills a Q\&A pair — the visitor's question and your answer, both editable — and saves it as a source in the project.

Promoting the same reply twice never creates a duplicate, and sources created this way are labeled in the list so you can tell curated answers apart from hand-written ones. Any workspace member can promote a reply; adding and editing other sources is for admins and owners.

## Manage sources in the dashboard

The full walkthrough — adding each source type, the source list, Recrawl, and deletion — is in [Knowledge sources in the dashboard](https://docs.clankersupport.com/learn/sources), and the promote flow is part of the [inbox](https://docs.clankersupport.com/learn/inbox) workflow.

<ThemedImage alt="Knowledge sources in the dashboard" basePath="/learn/sources" />


# Ratings & CSAT
URL: https://docs.clankersupport.com/features/ratings-csat
Clanker Support gives visitors two ways to tell you how it's going, and deliberately keeps them apart: a **thumbs up/down on each individual answer** the agent gives, and a **separate 1–5 CSAT rating for the whole conversation**. One measures answer quality, the other measures the overall experience — and neither is ever folded into the other.

## Per-message thumbs: answer quality

Every answer the agent streams into the widget carries small thumbs up/down controls. Visitors rate individual answers as they read them — no form, no interruption. They can change their mind: tapping the other thumb switches the rating, and tapping the same one again clears it.

A few properties of this signal:

* **It's per answer, not per conversation.** A visitor can mark one reply helpful and the next one not — which is exactly the granularity you want when deciding which answers to fix.
* **Only the agent's answers are rateable.** Visitor messages and teammate replies don't take thumbs.
* **It's actionable at the knowledge level.** A downvoted answer usually points at a gap or a stale entry in your [knowledge sources](https://docs.clankersupport.com/features/knowledge-sources); an upvoted one is worth capturing as a Q\&A pair in your sources.

In the dashboard, thumbs show up inside the conversation thread: each agent reply displays **Helpful**, **Not helpful**, or "Not rated" beneath its bubble. The rating is read-only for your team — it's the visitor's verdict, not something operators edit.

<ThemedImage alt="Conversation thread" basePath="/learn/conversation-thread" />

## Conversation CSAT: experience quality

When a visitor closes the chat, the widget asks them to rate the conversation from **1 to 5**. This is a single score for the whole exchange — did they get what they came for? — and it's stored on the conversation, not on any message.

A visitor can only rate their own conversation, and the widget only asks once — a rated conversation is never re-prompted. CSAT applies to the conversation regardless of who handled it: a thread the agent resolved alone and a thread your team took over after [escalation](https://docs.clankersupport.com/features/escalation) are both eligible.

## Where each shows up in the dashboard

| Signal          | Where you see it                                                                                      |
| --------------- | ----------------------------------------------------------------------------------------------------- |
| Thumbs          | In the thread view, under each agent answer — **Helpful**, **Not helpful**, or "Not rated"            |
| CSAT            | In the conversation's details panel, as 1–5 stars (or "Not rated")                                    |
| CSAT, aggregate | The inbox stats cards show **Avg rating** — the average CSAT across rated conversations, project-wide |

The inbox average counts only conversation-level CSAT scores. Thumbs are never averaged into it.

## Why they're kept separate

Merging the two would destroy both signals. A visitor can rate three answers "not helpful" and still leave a 5-star CSAT because a teammate stepped in and fixed everything — that tells you the *handoff* works but the *knowledge base* has a gap. The reverse happens too: every answer was technically correct, but the visitor left a low CSAT because the experience was slow or frustrating.

So use them for what they each measure:

* **Thumbs** → tune the agent. Chase down the downvoted answers, fix or add sources, refine your instructions.
* **CSAT** → track the outcome. Watch the inbox average as the health metric for the whole support experience.

## Learn more

* [Conversations](https://docs.clankersupport.com/learn/conversations) — reading thumbs in a thread and the CSAT stars in the details panel.
* [Inbox](https://docs.clankersupport.com/learn/inbox) — the stats cards, including the project-wide average rating.


# Self-hosting
URL: https://docs.clankersupport.com/features/self-hosting
Clanker Support is open source under the MIT license, and the entire product lives in one repository: [theopenco/llmchat](https://github.com/theopenco/llmchat). Self-hosting is free forever — you run the infrastructure, bring your own API keys, and pay your model provider directly. There is no feature-gated "community edition"; the code you deploy is the same code behind the hosted service.

## What's in the box

The monorepo contains everything the hosted service runs:

* **API** — a Hono worker that serves the public chat endpoints, the dashboard API, webhooks, and the widget bundle itself at `/widget.js`.
* **Dashboard** — the Next.js operator console: the shared inbox, project settings, knowledge sources, and billing.
* **Marketing site** — the Next.js site behind [clankersupport.com](https://clankersupport.com), if you want it.
* **Widget** — the embeddable script-tag bundle, built once and served by the API, so a self-hosted install still works with a one-line `<script>` tag pointed at your own API origin.
* **Database** — a SQLite-compatible database (D1-style) with SQL migrations included; the deploy platform applies them automatically.

One honest note on the runtime: the API is built to run on **workerd** via the [Ploy platform](https://docs.meetploy.com), not on a plain Node.js server. That's the deployment target the repo is set up for out of the box.

## What you bring

Three external services, only one of which is required:

| Service         | Needed for                                           | Required?                        |
| --------------- | ---------------------------------------------------- | -------------------------------- |
| **LLM Gateway** | Inference — the API key the agent answers with       | Yes                              |
| **Resend**      | Email — escalation notifications and reply threading | Only if you want email           |
| **Stripe**      | Billing — metering and subscriptions                 | Only if you want to charge users |

Inference goes through [LLM Gateway](https://llmgateway.io), so a single key gives your projects access to the model catalog, and usage is billed to your own account — Clanker Support takes no cut on a self-hosted install. Without Resend, chat and the inbox work fine; you just lose [escalation emails](https://docs.clankersupport.com/features/escalation) and [email threading](https://docs.clankersupport.com/features/email-threading). Stripe is entirely optional and only matters if you're running the stack as a service for others.

## Unlocking plan limits

One setup step that isn't obvious: the hosted paywall ships with the code, so on a fresh install every workspace resolves to the `none` plan — zero projects, zero responses — until you tell the API whose workspaces are yours. Set `INTERNAL_ACCOUNT_EMAILS` (comma-separated) in the API's environment to the email address you sign up with, and every workspace that account owns runs fully unlocked, with no plan limits and no billing. The alternative is wiring Stripe and selling plans like the hosted service does. Without one of the two, sign-in works but project creation hits the paywall.

## Self-host or hosted?

Both run the same code; the difference is who operates it.

* **Self-host** — free, MIT. You deploy and operate the stack, apply updates, and pay your model provider directly through your LLM Gateway key. Best when you want full control over data and infrastructure.
* **Hosted** — we run everything at [app.clankersupport.com](https://app.clankersupport.com); you create a project and paste one script tag. Metered by AI responses, with unlimited human replies and no per-seat fees — see [Pricing](https://docs.clankersupport.com/pricing).

Enterprise plans include a self-host support contract if you want the control of self-hosting with someone to call.

## Setting it up

The [GitHub README](https://github.com/theopenco/llmchat) is the canonical setup guide and stays current with the code — follow it rather than any copy of the steps here. In short, it walks you through installing dependencies, copying the example env file and filling in your keys, and starting the full stack with a single dev command; migrations apply automatically.

Once your stack is up, everything in these docs applies unchanged — point the widget's `data-api` attribute (or the SDK's `apiUrl` prop) at your own API origin and continue with [Getting started](https://docs.clankersupport.com/getting-started) and the [dashboard guide](https://docs.clankersupport.com/learn).


# Team inbox
URL: https://docs.clankersupport.com/features/team-inbox
Every conversation your support agents handle — across every project in your workspace — lands in one shared inbox at [app.clankersupport.com](https://app.clankersupport.com). Your team triages, replies, and closes conversations from a single place; nothing lives in a visitor's browser tab or a teammate's private queue.

<ThemedImage alt="The team inbox" basePath="/learn/inbox" />

## Triage without opening threads

The conversation list is built for scanning. Each row carries an **AI-generated triage summary** — a short recap of what the conversation is about, generated automatically (until one exists, the row shows the visitor's first message) — plus status badges (**Escalated**, **Resolved**), tag chips, and a message count. Open a thread and the same summary sits in the header, alongside a details panel with the visitor's contact info, CSAT rating, and tags.

The full triage workflow is covered in [Inbox](https://docs.clankersupport.com/learn/inbox) and [Conversations](https://docs.clankersupport.com/learn/conversations).

## Find anything

Three ways to get to the right conversation:

* **Filters** — narrow the list by status (Open, Resolved, Escalated) and by workspace tags; active filters show as a badge so a narrowed list is never a surprise.
* **Full-text search** — the inbox search box matches visitor names, emails, and message text across the whole project, live as you type.
* **⌘K command palette*&#x2A; — press **⌘K** (or **Ctrl+K**) anywhere in the dashboard to search every project in the workspace at once, and jump straight to a conversation or a project's settings.

See [Search & command palette](https://docs.clankersupport.com/learn/search) for the details.

## Organize with tags

Tags are colored, workspace-level labels — "billing", "bug report", "VIP" — shared by every member. Any member can create and apply them; admins and owners can rename, recolor, or delete them for the whole workspace. Tags show as chips on inbox rows and double as a filter.

See [Tags](https://docs.clankersupport.com/learn/tags).

## Stay on top of new activity

* **Per-user unread state** — each teammate has their own unread indicators: an unread conversation shows a dot and bold preview until *you* open it, independent of whether a colleague already read it.
* **Notification bell** — a workspace-wide feed of new conversations, escalations, and visitor replies, refreshed automatically while the dashboard is open. Click an entry to jump straight to the thread, whatever project it happened in.

See [Notifications](https://docs.clankersupport.com/learn/notifications).

## Close the loop

From the thread header you can **Resolve** a conversation once it's handled and **Reopen** it if the visitor comes back — visitors can also mark their own conversation resolved from the widget, and the inbox tells you which side closed it. Conversations can also be deleted entirely (with confirmation) — deleting requires the admin or owner role.

## Roles

Every member has one role per workspace — **owner** > **admin** > **agent** — and the API enforces it server-side, deny by default. Agents work the inbox (read, reply, resolve, tag); admins additionally manage projects, knowledge, and tags; owners additionally control billing and the workspace itself. Permissions can't be bypassed by the UI.

See [Workspaces & members](https://docs.clankersupport.com/learn/workspaces) for the full role table.

## Learn more

* [Inbox](https://docs.clankersupport.com/learn/inbox) — the list, filters, search, and stats cards
* [Conversations](https://docs.clankersupport.com/learn/conversations) — the thread, replying, and promoting replies into knowledge
* [Tags](https://docs.clankersupport.com/learn/tags) · [Search & command palette](https://docs.clankersupport.com/learn/search) · [Notifications](https://docs.clankersupport.com/learn/notifications)
* [Escalation](https://docs.clankersupport.com/features/escalation) — how a conversation reaches the inbox as a human handoff


# Integrations
URL: https://docs.clankersupport.com/integrations
Every integration is a different way to install the same support agent. Whatever the path, the widget talks to the same project — the same knowledge base, instructions, and AI model — and every conversation lands in the same shared [inbox](https://docs.clankersupport.com/learn/inbox). Pick the path that matches your stack; you can switch later without losing anything, because the project key is all any of them need.

## The four paths

| Integration                                   | Best for                                                                                | Status                                         |
| --------------------------------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------- |
| [Widget & iframe embed](https://docs.clankersupport.com/integrations/widget) | Any website — one script tag, no build step; iframe for site builders                   | Live                                           |
| [React SDK](https://docs.clankersupport.com/integrations/react-sdk)          | React 19 / Next.js App Router apps that want a typed component and CSS-variable styling | Live on npm                                    |
| [Shopify](https://docs.clankersupport.com/integrations/shopify)              | Shopify stores — app-embed block toggled on in the theme editor, zero permission scopes | Coming soon to the Shopify App Store           |
| [WordPress](https://docs.clankersupport.com/integrations/wordpress)          | WordPress sites — settings-page install plus a shortcode for an inline chat             | Plugin ready; wordpress.org listing on its way |

## Choosing a path

* **Not sure? Start with the [script tag](https://docs.clankersupport.com/integrations/widget).** It works on any site that lets you add HTML, loads asynchronously, and renders in a shadow DOM so your site's CSS and the widget's never collide.
* **On React or Next.js**, the [`@clankersupport/widget-rsc` SDK](https://docs.clankersupport.com/integrations/react-sdk) gives you a `<ClankerSupport apiKey="pk_…" />` Server Component for the root layout, plus headless primitives when you want to build your own chat UI.
* **Can't add script tags at all?** The [iframe embed](https://docs.clankersupport.com/integrations/widget) serves the full chat as a page you can frame anywhere.
* **On Shopify today**, paste the script tag into your theme — the app-embed install takes over once the App Store listing is live.
* **On WordPress today**, install the plugin as a manual zip upload; the wordpress.org listing will make that one click.

## The same agent, whichever path you pick

The install path only changes how the widget gets onto the page. Everything the agent does is identical across all four:

* **Answers** stream from the project's knowledge base and instructions — see [AI responses](https://docs.clankersupport.com/features/ai-responses) and [Knowledge sources](https://docs.clankersupport.com/features/knowledge-sources).
* **Escalation** offers "Talk to a human" after the project's message threshold (or immediately when the visitor asks), notifies your team, and stands the agent down — see [Escalation](https://docs.clankersupport.com/features/escalation).
* **Replies** from your team reach the visitor in the widget, and by email when they shared an address, with email replies threading back into the same conversation — see [Email threading](https://docs.clankersupport.com/features/email-threading).
* **Quality signals** — per-message thumbs on answers and a separate 1–5 rating on the conversation — flow into the inbox either way; see [Ratings & CSAT](https://docs.clankersupport.com/features/ratings-csat).

Branding follows the project too: brand color and welcome message are project settings. The script tag can override the brand color per page, and the React SDK can override both — the individual integration pages list the options.

## What every path needs

One thing: your project's **public key** (`pk_…`). You get it when you create a project, and it's always available under **Projects → your project → Widget** in the dashboard — see [Widget & embed settings](https://docs.clankersupport.com/learn/widget). The key is safe to expose in page source; it identifies the project, it doesn't grant dashboard access.

Before installing, make sure the agent has something to answer from — add [knowledge sources](https://docs.clankersupport.com/learn/sources) and set the project's instructions. The [Getting started](https://docs.clankersupport.com/getting-started) guide walks through the whole flow from account to first conversation.


# MCP connector (Claude Code & Codex)
URL: https://docs.clankersupport.com/integrations/mcp
The official MCP server, [`@clankersupport/mcp`](https://www.npmjs.com/package/@clankersupport/mcp), connects Clanker Support to any [Model Context Protocol](https://modelcontextprotocol.io) client — Claude Code and Codex being the two it's tested against. Your coding agent gets the operator surface as tools: list and read conversations, reply to customers, leave internal notes, search the workspace, and add knowledge sources.

The loop it unlocks: a customer reports a bug and escalates → your agent reads the conversation from the terminal, you fix the bug together → the agent replies to the customer and adds the fix to the knowledge base so the AI answers it next time. No dashboard tab involved.

## Claude Code

```sh
claude mcp add clanker-support \
  --env CLANKER_EMAIL=you@company.com \
  --env CLANKER_PASSWORD=your-password \
  -- npx -y @clankersupport/mcp
```

Restart Claude Code (or run `/mcp`) and the `clanker-support` tools are available. For a team-shared, project-scoped setup, commit a `.mcp.json` that references environment variables instead of literal credentials:

```json
{
	"mcpServers": {
		"clanker-support": {
			"command": "npx",
			"args": ["-y", "@clankersupport/mcp"],
			"env": {
				"CLANKER_EMAIL": "${CLANKER_EMAIL}",
				"CLANKER_PASSWORD": "${CLANKER_PASSWORD}"
			}
		}
	}
}
```

## Codex

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.clanker-support]
command = "npx"
args = ["-y", "@clankersupport/mcp"]
env = { CLANKER_EMAIL = "you@company.com", CLANKER_PASSWORD = "your-password" }
```

## Configuration

| Variable               | Required | Default                          | What it does                                                                      |
| ---------------------- | -------- | -------------------------------- | --------------------------------------------------------------------------------- |
| `CLANKER_EMAIL`        | yes      | —                                | Operator account email                                                            |
| `CLANKER_PASSWORD`     | yes      | —                                | Operator account password                                                         |
| `CLANKER_API_URL`      | no       | `https://api.clankersupport.com` | Your API origin when [self-hosting](https://docs.clankersupport.com/features/self-hosting)                       |
| `CLANKER_WORKSPACE_ID` | no       | auto                             | Pin a workspace when the account belongs to several (`list_workspaces` lists ids) |

Prefer a dedicated automation account with the least role that covers what you'll do — `agent` is enough for reading, replying, notes, and knowledge sources.

## Tools

| Tool                     | What it does                                                                  |
| ------------------------ | ----------------------------------------------------------------------------- |
| `list_workspaces`        | Workspaces this account belongs to, with role and project count               |
| `list_projects`          | Support projects in the active workspace                                      |
| `list_conversations`     | Conversations in a project — filter by open / escalated / resolved, or search |
| `conversation_stats`     | Open / escalated / resolved counts for a project                              |
| `get_conversation`       | A conversation's full message thread                                          |
| `reply_to_conversation`  | Send an operator reply to the customer (customer-visible)                     |
| `add_internal_note`      | Team-only note on a conversation — never shown to the customer                |
| `list_knowledge_sources` | The project's knowledge base (url / text / qa sources)                        |
| `add_knowledge_source`   | Add a docs URL, text snippet, or Q\&A pair the AI will answer from             |
| `search`                 | Workspace-wide search — the same one the dashboard's ⌘K palette uses          |

`reply_to_conversation` is customer-visible, and its tool description instructs agents to confirm the draft with you before sending.

## Self-hosting

Set `CLANKER_API_URL` to your deployment's API origin — everything else is identical. The API must be a build that trusts its own origin for sign-in (July 2026 or later).


# React SDK
URL: https://docs.clankersupport.com/integrations/react-sdk
`@clankersupport/widget-rsc` is the Clanker Support widget as an npm package for React and Next.js apps. It's MIT-licensed, has zero runtime dependencies (React 19 is the only peer), and ships two entries: a batteries-included Server Component, and a headless entry with primitives and a hook for building your own UI.

```sh
npm install @clankersupport/widget-rsc
```

## One line in your root layout

Add the component once — every page gets the widget. Grab your project's public key from the dashboard (**Project → Embed**):

```tsx
import { ClankerSupport } from "@clankersupport/widget-rsc";

export default function RootLayout({ children }) {
	return (
		<html lang="en">
			<body>
				{children}
				<ClankerSupport apiKey="pk_your_project_key" />
			</body>
		</html>
	);
}
```

`ClankerSupport` is an async Server Component: it prefetches your widget config on the server (cached, revalidated every 5 minutes), so the client saves a round-trip and branding never flashes. The fetch is wrapped in Suspense and fails soft — a slow or unreachable API never blocks or breaks your page. The public key is safe to expose; it's the same key the script tag uses.

Mounting from a Client Component instead? Import `ClankerSupportWidget` from the `/headless` entry — the identical widget, with the config fetched client-side.

## Props

| Prop                  | Type                              | Default                          | What it does                                                         |
| --------------------- | --------------------------------- | -------------------------------- | -------------------------------------------------------------------- |
| `apiKey`              | `string` (required)               | —                                | Your project's public widget key.                                    |
| `apiUrl`              | `string`                          | `https://api.clankersupport.com` | API origin. Point at your own deployment when self-hosting.          |
| `brandColor`          | `string`                          | `#111827`                        | Accent color for the launcher, header, and visitor bubbles.          |
| `position`            | `"bottom-right" \| "bottom-left"` | `"bottom-right"`                 | Which corner the widget docks to.                                    |
| `title`               | `string`                          | `"Support"`                      | Panel header title.                                                  |
| `greeting`            | `string \| null`                  | `"Hi! How can I help?"`          | Greeting bubble copy. Pass `null` to hide it.                        |
| `escalationThreshold` | `number`                          | `3`                              | Visitor messages before **Talk to a human** appears.                 |
| `defaultOpen`         | `boolean`                         | `false`                          | Open the panel on mount.                                             |
| `className`           | `string`                          | —                                | Extra class on the fixed container — handy for CSS-variable theming. |

## Styling

Unlike the script tag, the SDK does **not** use a shadow DOM. Everything is plain, namespaced CSS — `.clanker-*` classes driven by `--clanker-*` custom properties — so your stylesheet wins:

```css
.clanker-root {
	--clanker-brand: #16a34a;
	--clanker-surface: #0b0f14;
	--clanker-text: #e5e7eb;
}
.clanker-panel {
	border-radius: 8px;
}
```

If re-theming isn't enough, go headless.

## Headless: bring your own UI

`@clankersupport/widget-rsc/headless` exports `ClankerSupportProvider` (aliased as `Root`), the `useClankerSupport()` hook, and unstyled primitives: `Trigger`, `Panel`, `Messages`, `Composer`, `Input`, `Submit`, `EscalateButton`, `ResolveButton`, and `Branding`. Primitives render semantic elements with `data-*` state attributes, forward native props, and interactive ones support `asChild` (Radix-style) so you can swap in your own components. The client-rendered `ClankerSupportWidget` lives here too.

```tsx
"use client";

import * as SupportChat from "@clankersupport/widget-rsc/headless";

export function HelpButton() {
	return (
		<SupportChat.Root apiKey="pk_your_project_key">
			<SupportChat.Trigger>Need help?</SupportChat.Trigger>
			<SupportChat.Panel>
				<SupportChat.Messages />
				<SupportChat.Composer>
					<SupportChat.Input placeholder="Ask anything…" />
					<SupportChat.Submit>Send</SupportChat.Submit>
				</SupportChat.Composer>
				<SupportChat.Branding />
			</SupportChat.Panel>
		</SupportChat.Root>
	);
}
```

Prefer no components at all? `useClankerSupport()` exposes the full surface — `messages`, `status`, `send()`, draft state, `escalate()` / `resolve()` with their eligibility flags, `rate()` for per-message thumbs, CSAT submission, visitor `identify()`, and panel open state — so you can drive everything yourself.

## SDK or script tag?

Use the SDK when your site is React or Next.js and you want server-side config prefetch, CSS-level restyling, or a fully custom UI. Use the [script tag](https://docs.clankersupport.com/integrations/widget) everywhere else — it's one line of HTML, needs no build step, and its shadow DOM keeps host-page CSS out. The two share storage keys, so switching from the script tag to the SDK keeps existing visitor conversations and identities.


# Shopify
URL: https://docs.clankersupport.com/integrations/shopify
The Clanker Support Shopify app is **coming soon to the Shopify App Store**. Until the listing is live, you can put the agent on any Shopify store today with the one-line script tag — see [Install today](#install-today-with-the-script-tag) below.

## What the app does

The app is a theme app extension: an **app embed** block that loads the widget on your storefront. Once it's available and installed, setup is two steps — no code, no theme edits.

* **Zero permission scopes.** The app requests no access to your orders, customers, products, or anything else in your store. The only thing it stores is its own settings.
* **Paste your project key.** Open the app in your Shopify admin and paste your project's public key on its settings page. That's the whole connection.
* **Enable the app embed.** In the theme editor, open **App embeds**, switch on **Clanker Support**, and hit **Save**. App embeds are per theme, so enabling it on your live theme is one Save.
* **The bubble appears on your storefront.** The widget script loads after the page has finished loading, so it never competes with your storefront's own resources or slows down what shoppers see first.
* **Optional bubble color.** The embed block includes a bubble-color setting; leave it unset to use your project's default. (There's also an advanced project-key override, filled automatically when you connect the app.)
* **Clean uninstall.** Removing the app removes the embed from your theme and clears the data the app stored.

If you're already using the manual script tag when you switch to the app, the embed detects the existing snippet and won't mount a second bubble — one widget, never two.

## Install today with the script tag

Until the App Store listing is live, add the agent the same way as any other site: paste the script tag into your theme layout.

1. In your Shopify admin, go to **Online Store → Themes*&#x2A;, open the &#x2A;*…** menu on your current theme, and choose **Edit code**.
2. Open `layout/theme.liquid`.
3. Paste the snippet just before the closing `</body>` tag, with your project's public key:

```html
<script
	src="https://api.clankersupport.com/widget.js"
	data-project="pk_…"
	async
></script>
```

4. Save. The bubble appears on every storefront page.

The full attribute list — brand color, inline mode, escalation threshold — is on the [script tag](https://docs.clankersupport.com/integrations/widget) page.

## Next steps

* Don't have a project key yet? [Getting started](https://docs.clankersupport.com/getting-started) walks you through creating your first project.
* Tune the agent's appearance — welcome message, brand color, position — in [widget settings](https://docs.clankersupport.com/learn/widget).
* Teach the agent about your store by adding [knowledge sources](https://docs.clankersupport.com/features/knowledge-sources): your shipping and returns pages, product FAQs, and Q\&A pairs.


# Widget & iframe embed
URL: https://docs.clankersupport.com/integrations/widget
The fastest way to put your support agent on a site: one `<script>` tag. It works on any stack — no build step, no framework, no dependencies. If you can't add script tags at all (some site builders, sandboxed pages), the iframe embed serves the same chat as a full page you can frame anywhere.

## The script tag

Paste this just before the closing `</body>` tag, with your project's public key:

```html
<script
	src="https://api.clankersupport.com/widget.js"
	data-project="pk_your_project_key"
	async
></script>
```

That's the whole install. The public key is safe to expose — it only identifies which project's agent answers. The dashboard generates this snippet with your key and brand color already filled in; see [where to find it](#copy-your-snippet-from-the-dashboard) below.

## Data attributes

The script tag is configured entirely through `data-*` attributes. This is the complete list:

| Attribute                   | Default                               | What it does                                                               |
| --------------------------- | ------------------------------------- | -------------------------------------------------------------------------- |
| `data-project`              | — (required)                          | Your project's public key                                                  |
| `data-api`                  | the origin the script was loaded from | API origin — only set this when self-hosting the API on a different domain |
| `data-brand`                | `#111827`                             | Accent color for the launcher and chat header                              |
| `data-mode`                 | `bubble`                              | `inline` renders the chat in-page instead of as a floating bubble          |
| `data-escalation-threshold` | agent default (3)                     | Visitor messages before the widget offers **Talk to a human**              |

Because `data-api` defaults to wherever `widget.js` was served from, a self-hosted install points at your own API automatically — no extra configuration.

## Bubble vs inline

* **Bubble** (the default) — a launcher in the bottom-right corner of every page the script is on. Visitors click it to open the chat panel. Recommended for site-wide support.
* **Inline** (`data-mode="inline"`) — the chat renders in-page, always open, instead of as a floating bubble. For a chat pinned to a specific spot on a page — a contact page, a help center — use the [iframe embed](#the-iframe-embed).

## Shadow-DOM isolation

The widget mounts inside a shadow DOM, so it is fully isolated from the host page: your site's CSS can't restyle or break the chat, and the widget's styles never leak into your page. It ships as a single self-contained file — no external stylesheets or fonts to load.

## The iframe embed

`GET https://api.clankersupport.com/embed/{projectKey}` serves a full-page chat — the same widget in inline mode — designed to be iframed anywhere (the page explicitly allows framing by any site). Use it where script tags aren't an option:

```html
<iframe
	src="https://api.clankersupport.com/embed/pk_your_project_key"
	width="400"
	height="600"
	title="Support chat"
	style="border: 0; border-radius: 12px;"
	loading="lazy"
></iframe>
```

The embed page reads your project's brand color and escalation threshold from its settings, so it stays in sync with the dashboard without any attributes. This is also what the [WordPress plugin's](https://docs.clankersupport.com/integrations/wordpress) `[clanker_support]` shortcode renders. You can open the URL directly in a browser to try your agent before installing anything.

## Copy your snippet from the dashboard

Open **Projects → your project → Widget** in the dashboard. The **Install** section generates both snippets — floating bubble and inline embed — with your public key and brand color pre-filled, next to the embed URL and a live preview.

<ThemedImage alt="Install snippet on the Widget tab" basePath="/learn/embed-snippet" />

See [Widget & embedding](https://docs.clankersupport.com/learn/widget) for the full tour of the Widget tab, including appearance settings and the welcome message.

## Other install paths

* **React or Next.js?** Use the [React SDK](https://docs.clankersupport.com/integrations/react-sdk) — a Server Component instead of a script tag, restylable with CSS variables.
* **Shopify** — a theme app extension is [coming soon to the App Store](https://docs.clankersupport.com/integrations/shopify); until then, paste the script tag into your theme.
* **WordPress** — the [plugin](https://docs.clankersupport.com/integrations/wordpress) enqueues the widget for you and adds an iframe shortcode.


# WordPress
URL: https://docs.clankersupport.com/integrations/wordpress
The official WordPress plugin puts the support agent on your site without touching theme code. It loads the same `widget.js` embed the [script tag](https://docs.clankersupport.com/integrations/widget) uses — configured from a settings page in wp-admin instead of HTML — and adds a `[clanker_support]` shortcode for embedding the chat inline in any page or post.

The wordpress.org listing is on its way. Today the plugin installs as a manual upload: a zip built from the plugin package in the GitHub repo.

## Install

1. Build the zip from [`packages/wordpress-plugin`](https://github.com/theopenco/llmchat/tree/main/packages/wordpress-plugin) in the repo — `pnpm package` there emits `dist/clanker-support-<version>.zip`.
2. In wp-admin, go to **Plugins → Add New → Upload Plugin**, choose the zip, and activate.
3. Copy your project's public key from the dashboard (**Projects → your project → Embed**).
4. Go to **Settings → Clanker Support**, paste the key, and save.

The launcher bubble now appears on every public page. Nothing loads in the admin area.

## Settings

Everything lives under **Settings → Clanker Support**:

| Setting                  | Default                          | What it does                                                                               |
| ------------------------ | -------------------------------- | ------------------------------------------------------------------------------------------ |
| **Floating bubble**      | on                               | Shows the launcher bubble on every public page                                             |
| **Project key**          | —                                | Your project's public key — the same key the script tag uses, safe to expose               |
| **API URL**              | `https://api.clankersupport.com` | Point it at your own deployment if you [self-host](https://docs.clankersupport.com/features/self-hosting)                 |
| **Brand color**          | `#111827`                        | Accent color for the launcher and chat                                                     |
| **Escalation threshold** | project default                  | Messages before **Talk to a human** is offered — leave blank to use your project's setting |

The settings page includes a **live connection check**: it verifies your project key against the API and shows a status pill, so a wrong key or API URL is flagged right on the page. The result is cached briefly; saving the settings re-checks.

Under the hood, the plugin enqueues `<API URL>/widget.js` asynchronously with the same `data-*` attributes the dashboard's embed snippet generates — so everything on the [script tag](https://docs.clankersupport.com/integrations/widget) page about widget behavior applies here too.

## Inline chat with the shortcode

Add the shortcode to any page or post to render the chat inline:

```
[clanker_support]
```

It embeds the API's full-page chat (`/embed/{projectKey}`) in an iframe. Optional `width` and `height` attributes control the size (default 400×600):

```
[clanker_support width="500" height="700"]
```

The shortcode works independently of the floating-bubble toggle — you can turn the site-wide bubble off and still offer the chat on a single Contact page.

## Requirements

* WordPress 5.8 or newer
* PHP 7.4 or newer

The plugin is licensed GPLv2 or later. It stores only its settings (one option) and a short-lived connection-status cache (one transient) in WordPress — conversations live in your Clanker Support project, not your WordPress database. Uninstalling removes both stored values.

## Next steps

* Tune the agent's instructions, model, and knowledge base in [project settings](https://docs.clankersupport.com/learn/project-settings) and [knowledge sources](https://docs.clankersupport.com/learn/sources).
* See how the handoff to your team works in [escalation](https://docs.clankersupport.com/features/escalation).
* Triage conversations from your site in the [team inbox](https://docs.clankersupport.com/features/team-inbox).


# Account
URL: https://docs.clankersupport.com/learn/account
The Account page holds your personal settings — everything else in the dashboard is scoped to a workspace or project. Open it from the account menu (your avatar in the top-right corner) and choose **Account**, or go directly to `https://app.clankersupport.com/settings/account`.

<ThemedImage alt="Account" basePath="/learn/account" />

## Profile

| Field     | Description                                                             |
| --------- | ----------------------------------------------------------------------- |
| **Name**  | Your display name. Edit it and click **Save**.                          |
| **Email** | The address you sign in with. Read-only — contact support to change it. |

## Billing

The **Billing** card is a shortcut to your workspace's plan and subscription. Click **Go to Billing** to open [Billing](./billing), where you choose a plan, manage the subscription in Stripe, and track usage.

## Appearance and signing out

Two account-level controls live in the account menu itself rather than on this page:

* **Appearance** — switch between **Light**, **Dark**, and **System**. The menu stays open while you flip themes so you can compare; the choice is saved per browser.
* **Sign out** — ends your session and returns you to the sign-in page.

The top of the menu shows the email and workspace role you're signed in with.

## Danger zone

**Delete account** permanently removes your account and every workspace you solely own — all projects, conversations, messages, sources, tags, and usage history. The card spells out exactly what will be removed before you start. This cannot be undone.

To confirm, the dialog asks you to:

1. Type your account email to confirm.
2. Enter your password. If you signed in with Google or GitHub and never set a password, this step is skipped.

Deletion is blocked while either of these is true:

| Blocker                                               | What to do                                 |
| ----------------------------------------------------- | ------------------------------------------ |
| You share ownership of a workspace with another owner | Transfer or remove the other owner first.  |
| A workspace you own still has an active subscription  | Cancel it from [Billing](./billing) first. |

Once the deletion succeeds, you're signed out and returned to the sign-in page.


# Billing & usage
URL: https://docs.clankersupport.com/learn/billing
Billing lives at **Settings → Billing** — open it from **Billing** in the account menu or the usage meter at the bottom of the sidebar. Hosted Clanker Support is usage-based: every AI response your agent sends counts toward your plan's monthly quota, and this page is where you watch that number, choose a plan, and manage the subscription.

<ThemedImage alt="Billing & usage" basePath="/learn/billing" />

## Your current plan

The card at the top reflects your workspace's live state:

| Item                      | What it shows                                                                                                                      |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Plan**                  | Your current tier and its price                                                                                                    |
| **Manage in Stripe**      | Opens the Stripe billing portal — update your payment method, download invoices, or cancel. Owner only                             |
| **Responses this period** | AI responses sent since the start of the current calendar month (UTC)                                                              |
| **Plan limit bar**        | Your progress toward the AI responses included in your plan, so you can see when you're approaching — or past — the included quota |

The usage meter at the bottom of the sidebar mirrors the same plan and response count from anywhere in the dashboard.

## Choosing a plan

Three tiers are available: **Starter**, **Growth** (Most popular), and **Scale**. Use the **Monthly / Annual** toggle to switch the billing cadence — annual works out to roughly two months free, and each card shows the exact yearly total before you commit.

Plans differ in:

* Included AI responses per month
* What happens past the included quota — some tiers meter overage billed per response, others state a hard cap (each plan card says which)
* Number of projects and team seats
* Model access (fast models vs. all models)
* Widget branding (whether the "Powered by" badge shows)

Current limits and prices are listed on each plan card and on the [pricing page](https://clankersupport.com/pricing).

## What happens at checkout

1. Click &#x2A;*Choose \<tier>** — you're redirected to Stripe Checkout.
2. Enter payment details. A card is required to start; there is no free tier.
3. Once Stripe confirms the payment, your workspace is upgraded automatically and your agent can respond.

Billing is **owner-only**: only the workspace owner can start a checkout, change the plan, or open the billing portal. Other members can view the page, but the buttons are disabled with a note.

Until a workspace has an active plan, its agent isn't live — the dashboard shows an amber banner and onboarding starts with the plan picker. See [Getting started](https://docs.clankersupport.com/getting-started).

## Where usage comes from

* Each AI response the agent generates in the widget counts as **one response**, recorded the moment it's produced.
* Replies your teammates send from the inbox are human replies, not AI responses — they are never metered.
* The **Responses this period** counter resets at the start of each calendar month (UTC).
* On tiers with overage, responses beyond the included quota are metered and billed per response through Stripe; the current-plan card calls out how far over you are.


# Conversations
URL: https://docs.clankersupport.com/learn/conversations
Selecting a conversation in the [Inbox](./inbox) opens its full thread, with a details panel alongside it. This page covers working a single conversation: reading the transcript, replying, and promoting a good reply into your knowledge base.

<ThemedImage alt="Conversation thread" basePath="/learn/conversation-thread" />

## Who's who in the transcript

Every message is labeled and positioned by who sent it:

| Label       | Position | Who it is                                                     |
| ----------- | -------- | ------------------------------------------------------------- |
| **Agent**   | Left     | The AI support agent, with a sparkle avatar and a gray bubble |
| **Visitor** | Right    | The person being helped, in a dark bubble                     |
| **You**     | Right    | A teammate's reply from the inbox, shown as a bordered card   |

Handoff notices — for example when a visitor asks for a human — render centered in the thread with a headset icon, so escalations are easy to spot while scrolling. Long threads load the most recent messages first; click **Load older messages** at the top to page back.

## The thread header

The header shows the visitor's name (or "Anonymous"), a status pill (**Open**, **Escalated**, or **Resolved**), and a subtitle with when the conversation started, the visitor's email, and their device.

Below the name sits an **AI summary** — a short, automatically generated recap of what the conversation is about. The same summary is used as the row preview in the inbox list, so you can triage without opening every thread.

From the header you can **Resolve** or **Reopen** the conversation, or **Delete** it (with a confirmation). Assign is marked coming soon in the UI, as are the composer's Internal note, attachments, and Suggest with AI.

## Replying

Type in the composer at the bottom of the thread. **Enter** sends; **Shift+Enter** inserts a newline.

Where your reply goes depends on what the visitor shared:

* It always appears in the **widget** on the visitor's site.
* If the visitor shared an **email address**, it's also sent to them by email — and their email replies thread back into this same conversation.

The composer's placeholder tells you which case you're in: "Reply (also sent via email)" when an address is on file, or "Reply (no email — shows in the widget on next visit)" when it isn't.

Once you've replied to an escalated conversation, the AI agent stays silent in that thread — see [Escalation](./escalation) for the full handoff flow.

## Message ratings

AI replies can carry the visitor's thumbs rating, shown under the bubble as **Helpful**, **Not helpful**, or "Not rated". Visitors rate individual answers from the widget; in the inbox the rating is read-only — it's a quick signal for which answers to double-check or promote.

This per-message rating is separate from the conversation-level CSAT score in the details panel below.

## The details panel

On desktop the details panel sits to the right of the thread; on smaller screens it opens as a sheet. It shows:

| Section     | Contents                                                                               |
| ----------- | -------------------------------------------------------------------------------------- |
| **Contact** | Email (with a copy button), IP, device, when the conversation started, message count   |
| **Status**  | An amber banner with the date if escalated; a green banner if resolved                 |
| **Rating**  | The visitor's CSAT score as 1–5 stars, or "Not rated"                                  |
| **Tags**    | The conversation's tags — add existing workspace tags, create new ones, or remove them |

The resolved banner tells you who closed the conversation: "Resolved by the visitor" (visitors can mark their own conversation resolved from the widget) or "Resolved by your team".

## Add to knowledge

When you write a good reply, don't let it disappear into one thread — teach it to the agent. Every teammate reply in the transcript has an **Add to knowledge** button.

<ThemedImage alt="Add to knowledge" basePath="/learn/conversation-knowledge" />

Clicking it opens a dialog with an editable **Question** and **Answer**:

1. The question is prefilled from the visitor message your reply answered — edit it into the general form other visitors would ask.
2. The answer is prefilled with your reply — trim anything conversation-specific.
3. Click **Add to knowledge**.

This creates a **Q\&A pair** source in the project's knowledge base, and the button flips to an **In knowledge** badge confirming it was saved. The new source appears on the project's Sources page tagged "Promoted from a reply", where you can manage it like any other source — from then on, the agent uses it to answer future visitors.


# Escalation & human handoff
URL: https://docs.clankersupport.com/learn/escalation
When the support agent can't resolve something, the visitor can hand the conversation to your team. The agent recaps the conversation for them, notifies your team, and stands down until a human has it covered. Everything on this page is configured per project.

<ThemedImage alt="Escalated conversation" basePath="/learn/conversation-escalated" />

## When the widget offers a human

Each project controls how quickly the **Talk to a human** option appears in the widget. Open **Projects → your project → Behavior** and find the **Escalation & handoff** card:

| Field                   | What it does                                                                             |
| ----------------------- | ---------------------------------------------------------------------------------------- |
| **Offer a human after** | Number of messages before the widget shows **Talk to a human** (defaults to 3)           |
| **Notify email**        | Address emailed when a conversation escalates — leave blank to skip                      |
| **Slack webhook URL**   | Posts an escalation notice to a Slack channel via incoming webhook — leave blank to skip |

Set a low threshold if you want visitors to reach your team quickly; set it higher to let the agent try more answers first.

## What the visitor sees

When the visitor chooses **Talk to a human**, a short handoff recap appears in the chat: one or two sentences, addressed to the visitor, summarizing what they asked about and what was already covered — so they don't have to repeat themselves once your team arrives. The **Talk to a human** button then disappears; a conversation escalates once.

## Notifying your team

An escalation notifies your team through every channel you've configured, plus the dashboard itself:

* **Email** — sent to the project's **Notify email** address, when one is set.
* **Slack** — posted to the channel behind the **Slack webhook URL**, when one is set.
* **Notification bell** — the escalation always shows up in the dashboard's notification feed; clicking it opens the thread.

## Escalated conversations in the inbox

Escalated conversations are easy to spot while triaging:

* The conversation row shows an amber **Escalated** badge, and the thread header's status pill reads **Escalated**.
* The details panel shows an amber **Escalated** banner with the date it happened.
* The list rail's **Filters** include a **Status: Escalated** option, and the inbox stats view counts escalated conversations.
* The handoff notice renders in the thread as a centered system message with a headset icon.

See the [Inbox](./inbox) page for the full triage workflow.

## The agent stands down

After escalation, the agent stops answering questions:

1. **While your team is on the way** — if the visitor sends another message, the agent replies only with a brief holding note letting them know a human will follow up. It does not attempt to answer.
2. **Once a human has replied** — the agent goes fully silent. Every later message from the visitor reaches only your team.

The handoff is one-way by design: a visitor who asked for a person never gets bounced back to the agent mid-conversation.

## Replying and email threading

Reply from the inbox composer and your message appears in the visitor's widget. If the visitor shared an email address, the same reply also goes out by email — the composer's placeholder tells you when that's the case.

When the visitor answers that email instead of returning to the widget, their reply threads back into the same conversation in your inbox. There is no separate ticket to reconcile — chat and email stay one thread.


# Inbox
URL: https://docs.clankersupport.com/learn/inbox
The Inbox at [app.clankersupport.com/inbox](https://app.clankersupport.com/inbox) is where every conversation lands. It's split into three panes: the conversation list on the left, the message thread in the middle, and a details panel on the right. This page covers the list — finding, filtering, and scanning conversations.

<ThemedImage alt="Inbox" basePath="/learn/inbox" />

## Choosing a project

The **Project** dropdown at the top of the list shows one project's conversations at a time. It's independent of the project switcher in the top bar, so you can look through a different agent's inbox without changing what the rest of the dashboard points at.

## Conversation rows

Each row is designed so you can triage without opening the thread:

| Element           | Meaning                                                                                                                       |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Name & time**   | The visitor's name (or **Anonymous**) with an initials avatar, plus the time of the last activity                             |
| **Unread dot**    | An indigo dot on the avatar; the name and preview stay bold until you open the conversation                                   |
| **Preview**       | An AI-generated summary of the conversation once one is available, otherwise the visitor's first message                      |
| **Status badge**  | **Resolved** (green) or **Escalated** (amber) — a resolved conversation shows Resolved even if it was escalated along the way |
| **Tag chips**     | Any workspace tags on the conversation, with their colors                                                                     |
| **Message count** | The total number of messages in the conversation                                                                              |

Conversations with no badge are open. Escalated ones are waiting on your team — see [Escalation](./escalation).

The list loads a page at a time. Scrolling to the bottom fetches the next page automatically, and the **Load more** button does the same explicitly.

## Stats cards

Until you select a conversation, the center pane shows four cards summarizing the whole project:

| Card              | What it counts                                                                                         |
| ----------------- | ------------------------------------------------------------------------------------------------------ |
| **Conversations** | Every conversation in the project                                                                      |
| **Escalated**     | Conversations handed off to your team                                                                  |
| **Resolved**      | Conversations marked resolved — by your team or by the visitor                                         |
| **Avg rating*&#x2A;    | The average CSAT score (1–5) across rated conversations; shows &#x2A;*—** until a visitor has left a rating |

These are true project-wide totals, not counts of the rows loaded so far. The average rating comes from the per-conversation CSAT score visitors leave when closing the chat — it's separate from the per-message thumbs you see inside a thread.

## Search

The search box filters the list live as you type, matching visitor names, email addresses, and message text — across the whole project, not just the loaded rows. Matching rows swap their preview for the match itself: a **Name** or **Email** label when the term matched contact details, or a highlighted excerpt when it matched a message.

## Filters

The sliders button above the search box opens the filter panel. A badge on the button shows how many filters are active, so a narrowed list is never a surprise.

<ThemedImage alt="Inbox filters" basePath="/learn/inbox-filters" />

* **Status** — **Open** (the default view), **Resolved**, **Escalated**, or **All**. Two more pills, Unassigned and AI-handled, appear dimmed — they're marked coming soon in the UI.
* **Filter by tag** — select one or more workspace tags; a conversation matches if it carries any of them. **All** clears the tag selection.
* **Manage** — admins and owners can open the Manage tags dialog from here to rename, recolor, or delete workspace tags.

## Refresh

The refresh button next to the Filters toggle refetches both the conversation list and the stats cards on demand.


# Dashboard overview
URL: https://docs.clankersupport.com/learn
Everything you do in Clanker Support — triaging conversations, tuning your support agent, growing its knowledge base — happens in the dashboard at [app.clankersupport.com](https://app.clankersupport.com). Every page shares the same chrome: a top bar for switching context, a sidebar for navigation, and an account menu. This page walks through that chrome so the rest of this section reads without surprises. If you haven't created an agent yet, start with [Getting started](https://docs.clankersupport.com/getting-started).

<ThemedImage alt="Dashboard inbox" basePath="/learn/inbox" />

## Top bar

| Control                | What it does                                                                                                                                         |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Workspace switcher** | Switches between the workspaces you belong to. Each workspace has its own projects, members, and billing — see [Workspaces & members](./workspaces). |
| **Project switcher**   | Selects the project you're working on and jumps to its pages. Hidden until the workspace has at least one project.                                   |
| **Search*&#x2A;             | Opens the command palette — also on **⌘K** / **Ctrl+K**. See [Search & command palette](./search).                                                   |
| **Notification bell**  | A workspace-wide feed of new conversations, escalations, and visitor replies. See [Notifications](./notifications).                                  |
| **Help**               | Opens the documentation in a new tab.                                                                                                                |
| **Account menu**       | Your initials avatar — profile, billing, appearance, and sign out (see below).                                                                       |

## Sidebar

The sidebar has two groups:

* **Workspace** — **Conversations** opens the [Inbox](./inbox); **Projects** opens the [projects list](./projects).
* **Project** — **Sources** and **Settings** for the selected project: its [knowledge sources](./sources) and [project settings](./project-settings). This group appears once a project is selected.

At the bottom, the **usage meter** shows the workspace's plan and how many AI responses it has used this billing period — the same numbers as the [Billing](./billing) page.

Until the workspace is on a plan, an amber banner reminds you that your agent isn't live yet; **Choose a plan** takes you to the [Billing](./billing) page to pick one.

## Account menu

Click your avatar in the top-right corner. The menu shows the email you're signed in with and your workspace role, and contains:

* **Account** — your profile and account settings. See [Account](./account).
* **Billing** — the workspace's plan and usage. See [Billing](./billing).
* **Appearance** — switch the dashboard between **Light**, **Dark**, and **System** (follows your OS setting).
* **Sign out** — end your session.

## Pages in this section

* [Inbox](./inbox) — triage every conversation: filters, live search, and headline stats.
* [Conversations](./conversations) — read a thread, reply to visitors, and promote answers into knowledge.
* [Escalation & human handoff](./escalation) — how the agent hands a conversation to your team and stands down.
* [Resolving conversations](./resolving) — resolve, reopen, or delete finished conversations.
* [Tags](./tags) — label conversations with workspace tags and filter the inbox by them.
* [Notifications](./notifications) — the bell's feed of new conversations, escalations, and replies.
* [Search & command palette](./search) — find any conversation or project with ⌘K.
* [Projects](./projects) — create and manage the support agents you embed.
* [Project settings](./project-settings) — name, branding, model, instructions, and escalation rules.
* [Widget & embedding](./widget) — style the widget and install it with a script tag, iframe, or the React SDK.
* [Knowledge sources](./sources) — teach the agent from website pages, text snippets, and Q\&A pairs.
* [Workspaces & members](./workspaces) — how workspaces group your team, projects, and billing.
* [Billing & usage](./billing) — plans, metered usage, and your Stripe subscription.
* [Account](./account) — your profile, email, and account deletion.


# Notifications
URL: https://docs.clankersupport.com/learn/notifications
The bell in the top bar collects recent activity from every project in your workspace — so you notice new conversations and visitor replies without keeping the [Inbox](./inbox) open.

<ThemedImage alt="Notifications" basePath="/learn/notifications" />

## What lands in the feed

| Event                | When it appears                                                            |
| -------------------- | -------------------------------------------------------------------------- |
| **New conversation** | A visitor starts a conversation with one of your agents                    |
| **Escalated**        | A conversation is handed off to your team (see [Escalation](./escalation)) |
| **New message**      | A visitor sends a follow-up message in an existing conversation            |

A visitor's opening message counts once, as the new conversation — it doesn't also show up as a new message.

Each entry shows the visitor's name (or "Anonymous"), a one-line preview (the message text for follow-ups), the event type, and how long ago it happened. The feed covers the last two weeks of activity; when nothing is new, it reads "You're all caught up".

## The unread badge

Events you haven't seen yet add to the indigo badge on the bell (it caps at &#x2A;*9+**). Inside the panel, unseen entries are marked with a dot next to the visitor's name.

The feed refreshes automatically about every 20 seconds while the dashboard is open, so the badge updates on its own — no reload needed.

## Jumping to a conversation

Click any entry to open that conversation's thread in the Inbox. The right project is selected for you, so this works even if the event happened in a project other than the one you're currently viewing.

## How read state works

Opening the panel marks everything in it as seen and clears the badge. A few things to know:

* **Read state is per-browser.** It's stored locally, not on the server — each teammate has their own unread count, and it doesn't sync across your devices or browsers.
* **It's per-workspace.** Switching workspaces switches to that workspace's own feed and unread count.
* **Nothing slips through.** Events that arrive while the panel is open still count as unread on the next refresh.

Notifications are a heads-up layer only — the per-conversation unread indicators in the [Inbox](./inbox) are tracked separately, so clearing the bell doesn't mark conversations as read.


# Project settings
URL: https://docs.clankersupport.com/learn/project-settings
Each project has its own settings page — open it with **Configure** on a project card, or select the project and click **Settings** in the sidebar (`app.clankersupport.com/settings/projects/<id>`). Settings are split into four tabs: **General**, **Widget**, **Behavior**, and **Members**.

<ThemedImage alt="Project settings — General" basePath="/learn/project-general" />

## Saving changes

All four tabs share one save bar. As soon as you edit any field, an **Unsaved changes** bar appears at the bottom of the page:

* **Save changes** — writes only the fields you actually changed.
* **Cancel** — reverts every unsaved edit back to the stored values.

You can edit fields across several tabs and save them together in one go.

## General

| Setting                        | What it does                                                             |
| ------------------------------ | ------------------------------------------------------------------------ |
| **Agent name*&#x2A;                 | The internal name for this support agent, shown in your dashboard        |
| **"Powered by Clanker" badge** | Read-only state — whether the widget shows the badge is set by your plan |
| **Danger zone**                | Permanently delete the project and all its conversations                 |

The badge row shows **Shown** or **Hidden** depending on your plan: Starter includes the badge, while Growth and Scale remove it. There is no per-project toggle — to change it, change your plan on the Billing page.

**Delete project** asks for confirmation before doing anything. Deletion is permanent: all conversations and data for the project are removed, and any widget embedded with its public key stops working.

## Widget

The **Widget** tab holds the visitor-facing appearance — brand color, welcome message, privacy policy URL, a live chat preview, and the install snippet. It's covered in full on the [Widget & embedding](https://docs.clankersupport.com/learn/widget) page.

## Behavior

The **Behavior** tab controls how the agent thinks and when it hands off to your team.

<ThemedImage alt="Project settings — Behavior" basePath="/learn/project-behavior" />

### Model

Each project picks its own AI model. Click the model button to open the **Choose a model** dialog — a searchable list of web-search-capable models, loaded live from LLM Gateway. Pick one and save; the change applies to new responses immediately.

### Instructions

Instructions are the agent's system prompt: how it should behave, what tone to use, what to focus on. The agent always answers from your Sources first — instructions shape the behavior, while the knowledge itself lives under **Sources** in the sidebar.

Two starter templates get you going:

* **Support template** — a general customer-support persona.
* **Ecommerce template** — tuned for order, shipping, and product questions.

Clicking a template replaces the textarea content, so apply one first and then edit. **Clear** empties the field.

### Escalation & handoff

This card decides when and how a conversation reaches your team:

| Field                   | What it does                                                   |
| ----------------------- | -------------------------------------------------------------- |
| **Offer a human after** | How many messages before the widget offers **Talk to a human** |
| **Notify email**        | Emailed when a conversation escalates — leave blank to skip    |
| **Slack webhook URL**   | Posts escalations to a Slack channel — leave blank to skip     |

When a visitor escalates, your team is notified by email (and Slack, if a webhook is set), the visitor sees a recap of the handoff in-chat, and the agent stands down — it sends a brief holding acknowledgement while your team is on the way, and goes fully silent once a human has replied. Replies from the inbox reach the visitor in the widget (and by email, when they shared an address); the visitor's email replies thread back into the same conversation.

## Members

The **Members** tab lists who has access — today that's the owner on file, shown with an email and a role badge. Workspace roles are **owner**, **admin**, and **agent**, enforced server-side.

The **Invite** button is disabled and marked coming soon in the UI — there is no invite flow yet.


# Projects
URL: https://docs.clankersupport.com/learn/projects
A project is one embedded support agent: it has its own public key, knowledge base, instructions, AI model, and branding. Embed the same project on multiple pages to share one agent, or create separate projects for different sites, products, or audiences. Manage them at **Projects** in the sidebar (`app.clankersupport.com/settings/projects`).

<ThemedImage alt="Projects" basePath="/learn/projects" />

## Creating a project

Your first project is created during onboarding — the build screen ("Let's build your support agent") ends with a fully configured project. See [Getting started](https://docs.clankersupport.com/getting-started).

To add another agent, click **New Project**. The dialog asks for one thing — a project name — and everything else starts with sensible defaults you can change later. Only workspace **owners** and **admins** can create projects — agents don't see the button.

## Project cards

Each project renders as a card:

| Element              | What it shows                                                                                              |
| -------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Name**             | Project name with a brand-colored initial                                                                  |
| **Key**              | The public key with a copy button — this is the `data-project` value in your embed snippet, safe to expose |
| **Responses · 30d**  | AI responses this project generated in the last 30 days                                                    |
| **Model badge**      | The AI model the project currently uses                                                                    |
| **Star / Pin**       | Favorite the project, or pin it into a **Pinned** section at the top of the grid                           |
| **Configure** (gear) | Opens the project's settings — General, Widget, Behavior, and Members tabs                                 |
| **Delete** (trash)   | Deletes the project after confirmation                                                                     |

## Finding projects

With more than a few projects, use the toolbar above the grid:

* **Search** — matches project name, model, and public key.
* **Favorites** — toggle to show only starred projects.
* **Sort** — **Newest** or &#x2A;*Name (A–Z)**.

Pinned projects always sit in their own section on top, with everything else under **All projects**.

## Configuring a project

Click **Configure** on a card (or select the project and open **Settings** in the sidebar) to reach its settings tabs:

* **General** — agent name and the danger zone.
* **Widget** — brand color, welcome message, live preview, and the install snippet.
* **Behavior** — model picker, instructions, and escalation settings.
* **Members** — workspace members and roles.

The knowledge base lives under **Sources** in the sidebar once a project is selected.

## Deleting a project

Click the trash icon on a card and confirm. Deletion is permanent: all conversations and data for the project are removed, and the widget embedded with its key stops working. The dialog shows &#x2A;*Deleting…** until the server confirms, so a failed delete never silently passes.


# Resolving conversations
URL: https://docs.clankersupport.com/learn/resolving
When a conversation is done, mark it resolved to clear it out of your open queue. Resolved is the inbox's closed state: resolved conversations drop out of the default Open view, show a green **Resolved** badge, and stay fully searchable — nothing is lost until you explicitly delete.

<ThemedImage alt="Resolved conversation" basePath="/learn/conversation-resolved" />

## Resolve and reopen

Open a conversation in the [Inbox](./inbox) and use the buttons in the thread header:

* **Resolve** closes the conversation. The status pill flips to **Resolved** and the row gets a green badge in the list.
* **Reopen** appears in the same spot on a resolved conversation and puts it back to **Open**.

You can resolve and reopen as many times as you like — it's a toggle, not a one-way door.

## Finding resolved conversations

The list rail's **Filters** include a Status filter: **Open** (the default), **Resolved**, **Escalated**, and **All**. Switch to **Resolved** to review closed conversations, or **All** to see everything together.

On rows, the green **Resolved** badge takes precedence over the amber **Escalated** badge — a conversation that was escalated and later closed reads as resolved. The stats view (shown when no conversation is selected) also counts resolved conversations alongside totals and escalations.

## Who resolved it

Visitors can close their own conversation from the widget when their question is answered, so resolutions come from two directions. The details panel's resolved banner tells them apart:

| Banner                      | Meaning                                                      |
| --------------------------- | ------------------------------------------------------------ |
| **Resolved by the visitor** | The visitor marked the conversation resolved from the widget |
| **Resolved by your team**   | A teammate clicked **Resolve** in the dashboard              |

One exception: once a conversation has been [escalated](./escalation), the visitor can no longer resolve it — a human is handling it, so only your team can close it from the dashboard.

## Deleting a conversation

**Delete** in the thread header permanently removes the conversation and all of its messages. A confirmation dialog asks first, because this can't be undone — unlike resolving, there is no way to bring a deleted conversation back.

Deleting requires the admin or owner role. If you just want a conversation out of the way, resolve it instead; it stays available for search, stats, and future reference.


# Search & command palette
URL: https://docs.clankersupport.com/learn/search
The command palette gives you workspace-wide search. Press **⌘K** (macOS) or **Ctrl+K** (Windows/Linux) anywhere in the dashboard — or click the search box in the top bar — and start typing.

<ThemedImage alt="Command palette" basePath="/learn/command-palette" />

## What it searches

The palette searches the active workspace, across all of its projects:

| Result group      | Matched on                                    |
| ----------------- | --------------------------------------------- |
| **Conversations** | Visitor name, visitor email, and message text |
| **Projects**      | Project name                                  |

Type at least **2 characters** — shorter terms aren't searched. Results update as you type, and "No matches" only appears once your current term has actually been searched.

## Reading the results

Each conversation result shows the visitor's name (or their email, or "Anonymous visitor" if they shared neither), the project the conversation belongs to, and a snippet explaining the match — an excerpt of the matching message, or the name or email that hit. Conversations are ordered by most recent activity; projects are listed alphabetically.

## Jumping to a result

Move through results with the arrow keys and press **Enter** to open the highlighted one, or click it:

* A **conversation** opens its thread directly in the [Inbox](./inbox), with the right project selected.
* A **project** opens its settings page.

**Esc** closes the palette.

## Palette vs. inbox search

The inbox list rail has its own search box. Both match visitor name, email, and message text, but they cover different ground:

* The **command palette** searches every project in the workspace at once, and also finds projects by name.
* The **inbox search** filters the conversation list for the currently selected project only, alongside the status and tag filters.

Use the palette when you know who or what you're looking for but not which project it lives in.


# Knowledge sources
URL: https://docs.clankersupport.com/learn/sources
Sources are what your agent answers from. Everything you add on this page becomes knowledge the agent can draw on in its replies. Select a project, then open **Sources** in the sidebar (or go to `app.clankersupport.com/settings/projects/<id>/sources`).

<ThemedImage alt="Knowledge sources" basePath="/learn/sources" />

## Adding a source

Pick a type in the **Add a source** card, fill in the form, and add it:

| Type             | You provide                            | Good for                                                  |
| ---------------- | -------------------------------------- | --------------------------------------------------------- |
| **Website**      | A page URL                             | Docs, FAQ, shipping or pricing pages you already maintain |
| **Q\&A pair**     | A question and its answer              | Precise answers to questions visitors ask often           |
| **Text snippet** | Free-form text, with an optional title | Policies or facts that don't live on a public page        |

A fourth type, file upload, is marked coming soon in the UI.

## Website sources are snapshots

A website source is fetched **once, when you add it** — and again only when you press **Recrawl** (the refresh icon on the row). It never updates on its own.

That means publishing new content on your site does **not** change what the agent knows. After you update a page the agent learns from, come back here and press **Recrawl** on that source to replace the stored snapshot with the current page.

Recrawl is also the fix for a **Failed** source: correct whatever blocked the fetch, then recrawl.

## Status chips

Each row carries a status chip:

| Status      | Meaning                                                       |
| ----------- | ------------------------------------------------------------- |
| **Ready**   | The website was fetched successfully; its snapshot is in use  |
| **Pending** | A website source that hasn't completed its first fetch yet    |
| **Failed**  | The last fetch errored — recrawl after fixing the page or URL |
| **Off**     | The source is disabled and not used in answers                |
| **Saved**   | A Q\&A pair or text snippet — stored as-is, nothing to crawl   |

Only websites have a fetch lifecycle. Q\&A pairs and text snippets are used exactly as you wrote them, so they always show **Saved**.

## The source list

Once you have at least one source, rollup cards at the top count your **Websites**, **Q\&A**, and **Text** sources by type.

Below them, each row shows the source's URL or title, a type badge, an items count (each source holds one item today — one page, one pair, or one snippet), its status chip, and when it was added. Website rows also get the **Recrawl** button.

## Promoting a reply from the inbox

When you answer a visitor yourself, that answer is often worth teaching the agent. In the [inbox](./inbox), every teammate reply has an **Add to knowledge** button. It opens a dialog with the question (prefilled from the visitor's message) and the answer (prefilled from your reply), both editable. Saving creates a Q\&A source in the project, and the button flips to **In knowledge**.

Sources created this way are tagged **Promoted from a reply** in the list, so you can tell curated answers apart from hand-written ones.

## Deleting a source

Click the trash icon on a row to remove the source. Deletion takes effect immediately — there's no confirmation step — and the agent stops using that content for future answers. You can always add the same URL, pair, or snippet again.


# Tags
URL: https://docs.clankersupport.com/learn/tags
Tags are colored labels you attach to conversations — "billing", "bug report", "VIP", whatever fits your workflow. They are **workspace-level**: every member sees the same tag list, and a tag created on one conversation is immediately available on all the others.

<ThemedImage alt="Inbox filters with workspace tags" basePath="/learn/inbox-filters" />

## Tagging a conversation

Open a conversation in the [Inbox](./inbox) and find the **Tags** section in the details panel (the right-hand panel on desktop, a sheet on smaller screens).

* Click **Tag** to open the tag picker. Type to search the workspace's existing tags and click one to toggle it on or off.
* If nothing matches what you typed, the picker offers &#x2A;*Create "…"** — this creates the tag and attaches it to the open conversation in one step. New tags get a color automatically; you can change it later in [Manage tags](#managing-tags).
* To remove a tag, click the &#x2A;*×** on its chip in the details panel.

Tag names are case-insensitive and unique per workspace (up to 40 characters) — creating "Billing" when "billing" already exists reuses the existing tag instead of adding a duplicate.

Any workspace member can create and apply tags.

## Tag chips in the list

Each conversation's tags show as small colored chips on its row in the inbox list, so you can scan for a category without opening anything. Chips also appear in the details panel of the open conversation.

## Filtering by tag

In the inbox list rail, click **Filters** to expand the filter panel. Under **Filter by tag**:

* **All** (the default) shows every conversation regardless of tags.
* Click a tag chip to show only conversations carrying that tag. Select several tags to match conversations that have **any** of them.
* The tag filter combines with the status filter and the search box, and the **Filters** toggle shows a badge with the number of active filters.

## Managing tags

Admins and owners see a **Manage** link next to "Filter by tag" in the filter panel. It opens the **Manage tags** dialog, which lists every workspace tag with the number of conversations using it.

| Action      | How                                                                                                                       |
| ----------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Rename**  | Click the pencil icon, edit the name, then press Enter (Escape cancels). The new name applies everywhere the tag is used. |
| **Recolor** | Click the tag's color dot and pick a new color from the palette.                                                          |
| **Delete**  | Click the trash icon. A confirmation states how many conversations the tag will be removed from — this can't be undone.   |

Renaming or recoloring updates the tag on every conversation at once; deleting removes it from all of them.

## Who can do what

| Action                              | Agent | Admin | Owner |
| ----------------------------------- | ----- | ----- | ----- |
| Create a tag                        | Yes   | Yes   | Yes   |
| Add / remove tags on a conversation | Yes   | Yes   | Yes   |
| Filter the inbox by tag             | Yes   | Yes   | Yes   |
| Rename, recolor, delete tags        | No    | Yes   | Yes   |

These limits are enforced server-side, not just hidden in the UI.


# Widget & embedding
URL: https://docs.clankersupport.com/learn/widget
The widget is the chat bubble visitors use to talk to your support agent. Each project has its own widget: style it on the **Widget** tab of your project's settings, then install it with one of the options below.

<ThemedImage alt="Project Widget tab" basePath="/learn/project-widget" />

## Appearance

| Field                  | What it does                                                                                                                                                                                                                                                    |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Brand color**        | The widget's accent color — pick from the swatch or enter a hex value                                                                                                                                                                                           |
| **Agent photo**        | A photo or logo shown on the launcher bubble and the chat header, so the widget carries your team's face. Upload one (it's downscaled and stored with your project) or paste an image URL; an uploaded photo takes precedence. Remove both for the default icon |
| **Welcome message**    | The first message visitors see when they open the chat — also shown as floating **teaser bubbles** above the closed launcher (each line becomes its own bubble, up to two)                                                                                      |
| **Privacy policy URL** | Linked from the privacy notice shown to visitors; leave blank to use the Clanker Support default                                                                                                                                                                |

The live preview beside the form updates as you type; use the save bar to apply your changes. The launcher sits in the bottom-right corner — position options are marked coming soon in the UI.

## Install options

The **Install** section on the same tab generates copy-paste code with your project's public key already filled in. Toggle between **Floating bubble** (recommended) and **Inline embed**.

### Floating bubble (script tag)

One script tag adds the launcher to every page it's on. Paste it just before the closing `</body>` tag:

```html
<script
	src="https://api.clankersupport.com/widget.js"
	data-project="pk_your_project_key"
	data-api="https://api.clankersupport.com"
	data-brand="#6366f1"
	async
></script>
```

| Attribute      | Required | What it does                                                                                                                                 |
| -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-project` | Yes      | Your project's public key — safe to expose, it only identifies the widget                                                                    |
| `data-api`     | No       | API origin; defaults to the origin the script was loaded from                                                                                |
| `data-brand`   | No       | Accent color; the dashboard snippet fills in your project's brand color                                                                      |
| `data-avatar`  | No       | URL of an agent photo or logo shown on the launcher bubble and chat header; the dashboard's **Agent photo** setting overrides it once loaded |
| `data-teaser`  | No       | Set to `off` to disable the proactive teaser bubbles that appear above the closed launcher                                                   |

### Inline embed (iframe)

To fix the chat in a specific spot instead — a contact page, a help center — use the iframe embed:

```html
<iframe
	src="https://api.clankersupport.com/embed/pk_your_project_key"
	width="400"
	height="600"
	title="Support chat"
	style="border: 0; border-radius: 12px;"
	allow="clipboard-write"
	loading="lazy"
></iframe>
```

The `src` is the **Embed URL** shown next to the snippet: a full-page chat you can also open directly (**Open preview**) to try your agent before installing anything.

### React / Next.js SDK

For React apps, install the official SDK — it requires React 19 (Next.js 15+ App Router, or any RSC framework):

```sh
npm install @clankersupport/widget-rsc
```

Add one Server Component to your root layout:

```tsx
import { ClankerSupport } from "@clankersupport/widget-rsc";

export default function RootLayout({ children }) {
	return (
		<html lang="en">
			<body>
				{children}
				<ClankerSupport apiKey="pk_your_project_key" />
			</body>
		</html>
	);
}
```

The component prefetches your widget config on the server and streams in without blocking the page. It renders plain, namespaced markup — no shadow DOM — so you can restyle it from your own stylesheet via the `.clanker-*` classes and `--clanker-*` CSS variables:

```css
.clanker-root {
	--clanker-brand: #16a34a;
	--clanker-surface: #0b0f14;
}
```

For a fully custom UI, `@clankersupport/widget-rsc/headless` exports unstyled primitives (`Root`, `Trigger`, `Panel`, `Messages`, `Composer`, `EscalateButton`, …) and a `useClankerSupport()` hook that exposes the whole conversation — messages, streaming status, `send()`, escalation, ratings. The same entry also ships a client-rendered `ClankerSupportWidget`, the identical styled widget for Client Components and non-RSC React apps.

## What visitors experience

<ThemedImage alt="The chat widget as visitors see it" basePath="/learn/widget" />

* A few seconds after the page loads, the closed launcher shows your welcome message as small **teaser bubbles** inviting the visitor in. Clicking one opens the chat; dismissing them (or opening the chat any other way) hides them for the rest of the browser session, and returning visitors with an open conversation never see them.
* Visitors give a name before chatting; sharing an email is optional, but with one your team's replies also reach them by email.
* Answers stream in from your knowledge base, with markdown formatting and a thumbs up/down on each AI answer.
* When a visitor asks for a human, the widget shows a recap of the handoff and the agent stands down — it sends a brief holding note, then goes quiet once a human replies. See [Escalation](./escalation).
* Replies your team sends from the inbox appear in the widget automatically.
* Visitors can mark their own conversation resolved, and can leave a 1–5 rating when closing the chat.

## Voice calls

On the Scale plan, the widget can also offer **live voice calls**: visitors tap the call button and talk to the same support agent, grounded in the same instructions and knowledge base as the written chat.

A few things worth knowing as an operator:

* **Audio streams in real time and never touches our servers.** The call runs directly between the visitor's browser and the realtime model provider; Clanker Support only issues a short-lived call credential and never receives or stores the audio. When a call starts, a system note appears in the conversation thread so your team knows it happened.
* **Calls are transcribed into the conversation.** When a call ends, a text transcript of what was said (visitor and agent turns, in order) is saved into the same conversation thread — so escalations, email follow-ups, and inbox triage have the full context of the call. The transcript text comes from the realtime provider's speech-to-text; the audio itself is still never stored.
* **Voice-enabled knowledge is visitor-visible.** Starting a call delivers your project's assembled prompt, knowledge, and sources to the caller's browser to configure the realtime session — treat any knowledge on a voice-enabled project as visible to visitors, and keep anything you wouldn't show a visitor out of it.
* **Voice condenses your knowledge.** Realtime voice models accept a much smaller instruction budget than written chat: the upstream limit is 16,384 tokens for the entire prompt, so calls keep an estimated ceiling of about 12,000 tokens under it. For voice, knowledge text is capped at 8,000 characters and reference sources share a 16,000-character budget; if the combined prompt is still over the ceiling, it is trimmed from the end when the call starts. Written chat always uses the full budgets — if voice matters to you, keep the prompt and knowledge for that project concise, and put the essentials first.
* **Calls are budgeted.** Voice sessions are limited per visitor network (4 calls/hour per IP address), per project (20/day), and per workspace (100/day), and each session is capped in duration and spend. If a visitor hits a limit, the widget falls back to the written chat.


# Workspaces & members
URL: https://docs.clankersupport.com/learn/workspaces
A workspace is your team and billing boundary. It holds your members, your plan and usage, and every project (support agent) you create — projects live inside a workspace, and each workspace is billed separately. Manage them at **Settings → Workspaces**.

<ThemedImage alt="Workspaces settings" basePath="/learn/workspaces" />

## How workspaces fit together

* **Workspace** — the team and the subscription. Plan, usage, and members are all per-workspace. See [Billing](./billing).
* **Projects** — the individual support agents inside a workspace, each with its own widget, model, instructions, and knowledge. See [Projects](./projects).
* **Conversations, tags, sources** — always scoped to a project, and therefore to its workspace.

Everything you see in the dashboard — the inbox, projects, settings — is scoped to the workspace you're currently in.

## Roles

Every member has one role in a workspace: **owner** > **admin** > **agent**. Each role includes everything the roles below it can do. Roles are enforced server-side, deny by default — the API rejects any request that exceeds your role, so permissions can't be bypassed by the UI.

| Role      | What they can do                                                                                                                                      |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Owner** | Everything, plus billing: choose or change the plan, open the Stripe portal, and delete the workspace                                                 |
| **Admin** | Manage projects (create, configure, delete), knowledge sources, instruction templates, and workspace tags; delete conversations                       |
| **Agent** | Work the inbox: read and reply to conversations, resolve, reopen, and tag them, and promote a good reply into Q\&A knowledge with **Add to knowledge** |

Your current role is shown next to each workspace on the Workspaces page, and in the account menu in the top bar.

## Members

Each project's **Members** tab (Settings → Projects → your project → **Members**) shows you with your role badge. Inviting teammates isn't available yet — the **Invite** button is marked coming soon in the UI.

## Creating another workspace

Click **Create workspace** on the Workspaces page (or from the workspace switcher in the top bar) and give it a name. The dashboard switches into the new workspace immediately and starts onboarding for it: the new workspace has no plan yet, so you pick one first, then build its first agent.

Use separate workspaces when you need separate billing or separate teams — for example, an agency running support for two different clients.

## Switching workspaces

Use the workspace switcher in the top bar, or click **Switch** next to any workspace on the Workspaces page. The inbox, project list, and usage meter all update to the selected workspace.

## Deleting a workspace

Only an **owner** of a workspace can delete it. Click **Delete** next to the workspace and confirm. Deletion is permanent and removes everything inside it — projects, conversations, knowledge sources, and tags.

Deletion is blocked while either of these is true:

* **It's your last workspace.** You always keep at least one — create another workspace first, or delete your whole account from **Settings → Account** instead.
* **It has an active subscription.** Cancel the plan first via **Manage in Stripe** on the [Billing](./billing) page, then delete the workspace.


# SDKs
URL: https://docs.clankersupport.com/sdks
The plain [script tag](https://docs.clankersupport.com/integrations/widget) works on any site, but if you'd rather emit the embed from your own code, Clanker Support publishes official SDKs for the four most common backends. Each one produces the exact same widget as the dashboard's Embed snippet — a single self-contained script that mounts an AI-powered support agent — so you get streaming answers, escalation, live operator replies, ratings, and CSAT with no extra wiring.

There are two flavors:

* **`@clankersupport/widget-rsc`** renders the widget as a **React component** in the browser (React 19 / RSC). It's the only SDK that draws UI itself.
* **`clankersupport` (Python), `clankersupport` (Ruby), and `clankersupport/clankersupport-php`** are **server-side helpers**: they emit the `<script>` tag with the right `data-*` attributes and HTML-escape every value, so a template renders the embed without a copy-pasted snippet. The widget itself is still the client-side JavaScript served from the API.

Every SDK is MIT-licensed and open source. All of them take your project's **public key** (`pk_…`), which is safe to expose in page source or a client bundle — it only identifies which project's agent answers, and it grants no dashboard access. Find it under **Projects → your project → Widget** in the dashboard.

## Official SDKs

| Package                             | Registry                                                                      | Use it from                                                 |
| ----------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `@clankersupport/widget-rsc`        | [npm](https://www.npmjs.com/package/@clankersupport/widget-rsc)               | React 19 / Next.js — styled component + headless primitives |
| `clankersupport`                    | [PyPI](https://pypi.org/project/clankersupport/)                              | Any Python app; Jinja2-safe out of the box                  |
| `clankersupport`                    | [RubyGems](https://rubygems.org/gems/clankersupport)                          | Any Ruby app; Rails view helper via Railtie                 |
| `clankersupport/clankersupport-php` | [Packagist](https://packagist.org/packages/clankersupport/clankersupport-php) | Any PHP app; Laravel auto-discovery + Blade directive       |

## React / Next.js — `@clankersupport/widget-rsc`

The React SDK is the widget as an npm package for React 19 and Next.js App Router apps: zero runtime dependencies, a batteries-included Server Component, and a headless entry with primitives and a hook for building your own chat UI.

```sh
npm install @clankersupport/widget-rsc
```

Add the component once in your root layout and every page gets the widget:

```tsx
import { ClankerSupport } from "@clankersupport/widget-rsc";

export default function RootLayout({ children }) {
	return (
		<html lang="en">
			<body>
				{children}
				<ClankerSupport apiKey="pk_your_project_key" />
			</body>
		</html>
	);
}
```

`ClankerSupport` is an async Server Component that prefetches your widget config on the server, so branding never flashes and the client saves a round-trip. Mounting from a Client Component instead? Import `ClankerSupportWidget` from the `@clankersupport/widget-rsc/headless` entry — the identical widget, with config fetched client-side. The headless entry also exports unstyled primitives and a `useClankerSupport()` hook when you want to build the chat UI yourself.

See the [React SDK integration page](https://docs.clankersupport.com/integrations/react-sdk) for the full prop list, CSS-variable theming, and the headless API.

## Python — `clankersupport`

A server-side helper for Python web apps (FastAPI, Flask, Django). It builds the widget `<script>` tag with HTML-attribute escaping and returns a `str` subclass that implements the `__html__` protocol — so Jinja2 and other MarkupSafe-aware templates render it as markup without a `| safe` filter.

```sh
pip install clankersupport
```

```python
from clankersupport import script_tag

tag = script_tag("pk_your_project_key")
```

Pass the result to your template and render it directly:

```python
from fastapi import FastAPI, Request
from fastapi.templating import Jinja2Templates
from clankersupport import script_tag

app = FastAPI()
templates = Jinja2Templates(directory="templates")


@app.get("/")
def home(request: Request):
	return templates.TemplateResponse(
		"index.html",
		{"request": request, "clanker": script_tag("pk_your_project_key")},
	)
```

```html
<!-- templates/index.html, just before </body> -->
{{ clanker }}
```

Because `script_tag` returns a `ScriptTag` (a `str` with `__html__`), Jinja2 autoescaping emits it as HTML — no `| safe` needed. Keyword arguments let you override the defaults: `api_url` (for self-hosting), `brand_color`, `mode` (`"bubble"` or `"inline"`), `theme` (`"light"`, `"dark"`, or `"auto"`), and `escalation_threshold`.

## Ruby / Rails — `clankersupport`

A server-side helper for Ruby web apps, with a Rails view helper wired in through a Railtie.

```sh
gem install clankersupport
```

The core method works in any Ruby app and returns a plain `String`:

```ruby
require "clankersupport"

tag = ClankerSupport.script_tag("pk_your_project_key")
```

In Rails, the gem's Railtie mixes a `clanker_support_tag` helper into ActionView. It returns an `html_safe` string, so ERB autoescaping renders it as markup. Drop it into your layout just before `</body>`:

```erb
<%= clanker_support_tag %>
```

Called with no argument, `clanker_support_tag` reads the key from `ENV["CLANKER_PROJECT_KEY"]`. Pass one explicitly to override it, along with any options:

```erb
<%= clanker_support_tag "pk_your_project_key", theme: "auto" %>
```

Options mirror the other SDKs: `api_url`, `brand_color`, `mode`, `theme`, and `escalation_threshold`.

## PHP / Laravel — `clankersupport/clankersupport-php`

A server-side helper for PHP apps, with a first-class Laravel bridge: an auto-discovered service provider, publishable config, and a Blade directive.

```sh
composer require clankersupport/clankersupport-php
```

The static method works in any PHP app:

```php
<?php

use ClankerSupport\ClankerSupport;

// In your layout, just before </body>:
echo ClankerSupport::scriptTag('pk_your_project_key');
```

In **Laravel**, the service provider is auto-discovered — no manual registration. Set `CLANKER_PROJECT_KEY` in your `.env`, then drop the `@clankerSupport` Blade directive into your layout:

```blade
	@clankerSupport
</body>
```

The directive reads its configuration from env vars (`CLANKER_PROJECT_KEY`, and optional `CLANKER_API_URL`, `CLANKER_BRAND_COLOR`, `CLANKER_MODE`, `CLANKER_THEME`, `CLANKER_ESCALATION_THRESHOLD`). When `CLANKER_PROJECT_KEY` is unset it renders an HTML comment instead of throwing, so a fresh install never breaks page rendering. Named arguments on `scriptTag()` — `apiUrl`, `brandColor`, `mode`, `theme`, `escalationThreshold` — cover the same options everywhere else.

## Which one do I use?

* **React or Next.js?** Reach for [`@clankersupport/widget-rsc`](https://docs.clankersupport.com/integrations/react-sdk) — it renders the widget as a component, prefetches config on the server, and can be restyled with CSS variables or replaced entirely with the headless primitives.
* **A server-rendered app in Python, Ruby, or PHP?** The matching helper emits the embed from your templates, HTML-escaped and framework-safe, so you never hand-copy a snippet.
* **Anything else?** The [script tag](https://docs.clankersupport.com/integrations/widget) is one line of HTML and works on every stack.

Want a running starting point instead of wiring it up yourself? The [starter templates](https://docs.clankersupport.com/sdks/templates) ship a deployable app for each of these SDKs.


# Starter templates
URL: https://docs.clankersupport.com/sdks/templates
If you'd rather start from a working app than wire up an [SDK](https://docs.clankersupport.com/sdks) yourself, Clanker Support publishes five open-source starter templates — one per popular stack, each with the AI-powered support agent already mounted and a real page around it. Every template lives in the [`theopenco/clankersupport-templates`](https://github.com/theopenco/clankersupport-templates) monorepo, deploys in one click, and needs only your project's public key (`pk_…`) to go live. The key is safe to expose — it identifies the project, nothing more.

## The five templates

| Template                                                                                                     | Stack                               | SDK                                                 | Deploy  |
| ------------------------------------------------------------------------------------------------------------ | ----------------------------------- | --------------------------------------------------- | ------- |
| [`nextjs-shadcn`](https://github.com/theopenco/clankersupport-templates/tree/main/templates/nextjs-shadcn)   | Next.js 15 · App Router · shadcn/ui | `@clankersupport/widget-rsc` (RSC Server Component) | Vercel  |
| [`tanstack-start`](https://github.com/theopenco/clankersupport-templates/tree/main/templates/tanstack-start) | TanStack Start · Vite               | `@clankersupport/widget-rsc/headless`               | Vercel  |
| [`react-router`](https://github.com/theopenco/clankersupport-templates/tree/main/templates/react-router)     | React Router 7 · Vite · SSR         | `@clankersupport/widget-rsc/headless`               | Vercel  |
| [`laravel`](https://github.com/theopenco/clankersupport-templates/tree/main/templates/laravel)               | Laravel 12 · Blade                  | `clankersupport/clankersupport-php`                 | Railway |
| [`fastapi`](https://github.com/theopenco/clankersupport-templates/tree/main/templates/fastapi)               | FastAPI · Jinja2                    | `clankersupport` (pip)                              | Vercel  |

## What each one gives you

### [`nextjs-shadcn`](https://github.com/theopenco/clankersupport-templates/tree/main/templates/nextjs-shadcn)

A Next.js 15 App Router help-center page with hand-vendored shadcn/ui-style components and Tailwind CSS v4. The support agent is mounted site-wide by the `<ClankerSupport />` Server Component from `@clankersupport/widget-rsc`, so its config is prefetched on the server and streamed in via Suspense — zero client round-trips before first paint. Deploys to **Vercel**; set `NEXT_PUBLIC_CLANKER_KEY`.

### [`tanstack-start`](https://github.com/theopenco/clankersupport-templates/tree/main/templates/tanstack-start)

A TanStack Start (Vite) landing/help page with the agent in the corner and no styling framework — proof the SDK drops into plain-CSS apps. It uses `ClankerSupportWidget` from the headless entry, which renders cleanly through TanStack Start's SSR with config fetched client-side. Deploys to **Vercel**; set `VITE_CLANKER_KEY`.

### [`react-router`](https://github.com/theopenco/clankersupport-templates/tree/main/templates/react-router)

A React Router v7 starter in framework mode with SSR enabled — a small product landing page whose real star is the support-agent bubble. It uses the headless `ClankerSupportWidget` entry of the React SDK. Vercel auto-detects React Router, so there are no build settings to configure; just set `VITE_CLANKER_KEY`. Deploys to **Vercel**.

### [`laravel`](https://github.com/theopenco/clankersupport-templates/tree/main/templates/laravel)

The official `laravel/laravel` 12.x skeleton with the agent rendered by the `@clankerSupport` Blade directive from `clankersupport/clankersupport-php` — no JavaScript build step. Deploys to **Railway** via a registered template button (or any Laravel host — Forge, Laravel Cloud, Fly.io, your own server); set `CLANKER_PROJECT_KEY`.

### [`fastapi`](https://github.com/theopenco/clankersupport-templates/tree/main/templates/fastapi)

A FastAPI + Jinja2 landing/help page that renders the agent server-side with the `clankersupport` pip package — no `| safe` filter, no copy-pasted snippet, thanks to the package's `__html__` protocol. Without a key the page still renders and shows a setup callout instead of breaking. Deploys to **Vercel**; set `CLANKER_PROJECT_KEY`.

## Deploy in one click

Every template's README carries a deploy button. The four JavaScript and Python templates deploy to **Vercel** (each pre-fills the one environment variable it needs — `NEXT_PUBLIC_CLANKER_KEY`, `VITE_CLANKER_KEY`, or `CLANKER_PROJECT_KEY`), and the Laravel template deploys to **Railway**. Click the button, paste your project's public key when prompted, and the app ships with a live support agent.

## Scaffold from the command line

Prefer to start locally? Scaffold any of the templates with the CLI:

```sh
npm create clanker-support@latest
```

It prompts for a template, a project directory, and (optionally) your project key — supply the key and it writes a ready-to-run `.env`; skip it and set the template's env var yourself. From there it's a normal app — install dependencies and run the dev server as you would for that stack.

## After you deploy

Whichever template you pick, the widget behaves exactly like every other install path — it talks to the same project, the same knowledge base, and the same shared [inbox](https://docs.clankersupport.com/learn/inbox). Add [knowledge sources](https://docs.clankersupport.com/learn/sources) so the agent has something to answer from, tune its instructions and [escalation](https://docs.clankersupport.com/features/escalation) settings, and you're live. To customize how the widget mounts or looks, see the [SDK reference](https://docs.clankersupport.com/sdks) and the [React SDK](https://docs.clankersupport.com/integrations/react-sdk) page.