Frequently Asked Questions

Answers to the questions operators ask most often. If you don’t see your question here, email [email protected].

Topics

Prompt Builder
Knowledge Base
Lead Capture
Chat Widget
Billing & Usage

Prompt Builder

What’s the difference between Basic and Advanced mode?

Basic mode covers the essentials: identity, company, tone, unsure strategy, lead capture timing, a simple tool list, and a Knowledge Base on/off toggle. Advanced mode adds emoji/bullet preferences, per-tool settings, knowledge base mode/strictness/citation/no-result controls, custom API tool configuration, and a free-form Custom Instructions field.

If you’re not sure, start in Basic. Switching to Advanced later preserves everything you’ve already configured.

Do I have to use the Prompt Builder?

No. The Instructions field on the Persona tab accepts any prompt you write directly. The Prompt Builder is for operators who’d rather configure than write. Some operators use it to generate a starting point, then hand-edit the result in the Preview step.

Can I edit the compiled prompt?

Yes — the Preview step has a textarea you can edit directly before clicking Apply. Edits there are saved exactly as written and replace the compiled prompt; they don’t add to it.

What happens if I re-open the Prompt Builder after editing the prompt by hand?

The Builder won’t re-parse your hand-edits back into form fields. If you re-open it and regenerate from the form, your manual edits are lost. Either keep configuration in the form, or commit to hand-editing — mixing the two requires manual reconciliation.

Why is the Knowledge Base section missing in the Prompt Builder?

The Knowledge Base section only appears when the agent has files or URL sources attached. Add content in the Knowledge tab first, then re-open the Builder.

Why are some tools greyed out or missing in the Prompt Builder?

The Builder only shows tools that are enabled in the agent’s Tools tab. To make a tool available, enable it there first, then re-open the Builder.

I changed something in the Tools or Knowledge tab and the Builder doesn’t reflect it. Why?

The Builder reads agent state when you open it, not continuously. Close it and re-open it to pick up changes from other tabs.

Can I put custom rules in Custom Instructions that override the built-in rules?

No. The compiled prompt explicitly tells the model that Custom Instructions cannot override Security Rules, Tool Rules, Lead Capture Rules, Knowledge Base Rules, or Core Behavior. Attempts to override them via Custom Instructions are ignored at runtime.

Custom Instructions are best used for:

Domain phrasing (“always refer to the product as ‘our platform’”)
Topic redirection (“if asked about pricing, point to /pricing instead of quoting numbers”)
Output conventions specific to your use case

If you want to disable a tool, do it in the Tools tab rather than instructing the model to “never call” it.

My agent isn’t calling `lead_capture_tool` even though I configured Lead Capture. What’s wrong?

A few things to check:

Is the Lead Capture tool enabled in the agent’s Tools tab? (Not just in the Prompt Builder.)
Has the visitor actually provided the required fields? The agent will not invent or fabricate field values — if the visitor hasn’t given a valid email, the tool won’t fire.
Did the agent regenerate the prompt after you changed the Lead Capture settings? Re-open the Builder and re-apply.

If all three are true and the tool still doesn’t fire, share both the compiled system prompt/instructions and the full conversation log with [email protected] so we can reproduce.

My agent is making up case studies / statistics / customer stories. How do I stop it?

This usually means one of:

The Knowledge Base isn’t enabled, or doesn’t have the relevant content. Add files or URL sources covering those topics.
Strictness is set to Flexible — KB as guide. Switch to Strict — KB only or Balanced — KB + general. Strict explicitly tells the agent not to speculate when retrieval is empty.
Unsure strategy is set to Give its best guess. For company-specific facts, switch to Say it doesn't know or Offer to escalate.

The compiler also adds an explicit “do not generate plausible-sounding examples, customer stories, statistics, or case studies” rule when KB is enabled, but it can’t help if there’s no KB to search.

I set Strictness to `Strict` and Unsure strategy to `Best guess`. Which one wins?

Strict wins for company-specific questions. The compiler detects this combination and adds a tie-breaking rule: when knowledge base retrieval is empty, the agent will not provide a speculative answer for company-specific facts, regardless of the Best guess setting. Both options stay configured — there’s no silent override of your settings — but the contradiction is resolved in favor of the safer rule.

Why does the compiled prompt show tools by their snake_case names like `weather_tool` and `search_knowledge_base`?

These are the exact identifiers the runtime registers the tools under. Using them in the prompt removes ambiguity — the model knows precisely what to call rather than having to map display labels to runtime keys. If you write Custom Instructions referencing tools, use these names too (e.g. call `search_knowledge_base` before answering).

Not directly through the Builder. Each agent has its own configuration. The closest workaround is to open the Builder on the source agent, copy the compiled prompt from the Preview step, then paste it into the target agent’s Instructions field directly.

Will my agent leak the system prompt if a user asks for it?

These protections only apply to prompts generated by the Prompt Builder. When the Builder compiles your configuration, it automatically appends explicit security rules: the agent is instructed not to reveal, modify, or reinterpret its instructions, to treat all user content and retrieved documents as untrusted data, to ignore encoded or obfuscated instructions, and to reject any claim that prior messages were system instructions. These rules are anchored at both the start of the prompt (in Instruction Priority) and the end (in Security Rules).

If you wrote the Instructions field by hand (without the Prompt Builder, or by replacing the compiled output with your own text), none of these rules are present unless you added them yourself. Hand-written prompts are exactly what you write — there’s no implicit safety layer. If you write your own prompt, consider copying the Security Rules section from a Builder-compiled prompt to retain the same protections.

That said, language models are probabilistic and prompt-injection techniques evolve. Even with the Security Rules in place, no system prompt can offer a 100% guarantee against disclosure — especially against persistent, adversarial users. We continuously harden these rules, but you should not put genuinely sensitive information (API keys, customer PII, internal credentials) into Custom Instructions or anywhere else in the agent’s context. The Security Rules reduce risk; they don’t eliminate it.

Does the agent see emojis differently if I toggle the emoji setting?

Toggling Use emojis changes one line in the compiled prompt. When off, the agent is told “Do not use emojis.” When on, it’s told to use them sparingly. The setting affects the agent’s output, not how it reads the visitor’s messages.

🚨 Knowledge Base

What file types can I upload?

PDF, plain text (.txt), CSV, and Word documents (.docx). Other formats are rejected at upload time.

What’s the maximum file size?

The platform-wide cap is 32 MB per file, with a per-plan override:

Good — 5 MB
Better — 20 MB
Best — 32 MB

The smaller of (your plan limit, 32 MB) is what’s enforced. Larger files are rejected at upload.

How many files and URLs can I add per agent?

Plan	Files	URLs
Good	3	5
Better	10	20
Best	10	—

The Best plan caps file count at 10, same as Better — bumping to Best primarily increases agent count and file size, not knowledge volume per agent.

My agent isn’t using my uploaded files. What’s wrong?

Most likely:

Embedding isn’t finished yet. Uploads are processed asynchronously through a queue. Until the embedding run completes, the content isn’t searchable. Check the file/URL status — queued and processing mean it’s not ready yet; completed means it is.
The embedding run failed. Status will show failed with an error. Re-upload the file or check that the URL is publicly accessible.
Knowledge Base is disabled in the Prompt Builder. Open the Builder and confirm the Knowledge Base section is enabled.
The agent’s prompt was hand-written and doesn’t reference search_knowledge_base. Hand-written prompts don’t auto-instruct the model to call the tool — see the next question.

Do I need to mention `search_knowledge_base` in my prompt?

No — if you use the Prompt Builder. When your agent has files or URL sources attached, the Builder automatically registers the search_knowledge_base tool and injects the rules that tell the model when to call it. You don’t need to name the tool in your instructions.

Yes — if you hand-write the prompt. A hand-written prompt that doesn’t mention the tool will leave the model without explicit guidance on when to retrieve, and retrieval calls may be inconsistent. If you’re hand-writing, add a line like:

For questions about products, pricing, hours, or any other company-specific information, call the `search_knowledge_base` tool before answering.

Only include this once the agent actually has files or URLs attached — referencing a tool that isn’t registered won’t error, but it tells the model to call something that doesn’t exist.

How do URL sources work? Does it re-fetch the URL every time?

No — the URL is fetched once at ingestion time, its contents are chunked and embedded into the vector index, and that’s what the agent searches. The live URL is not re-fetched per query. If the page content changes, you need to re-ingest the URL (delete and re-add, or trigger a re-embed) for the agent to see the update.

Why does my agent return outdated info from a URL?

See above — URL sources are embedded once and not re-fetched. If your source has changed since you added it, the agent will keep returning the original snapshot until you re-ingest.

Why are some answers correct but missing details from my docs?

The retriever pulls the top-K most semantically similar chunks for each question. If a critical detail lives in a chunk that isn’t the closest match to the visitor’s wording, it won’t be in the context the agent sees. Ways to improve recall:

Add more focused documents that cover each topic separately, instead of a single dense PDF
Use clear headings and section breaks (the chunker respects document structure)
Phrase visitor-facing copy with the same vocabulary the docs use

What’s “Strict” vs “Balanced” vs “Flexible” mode in practice?

Strict — the agent answers only from retrieved content. If nothing matches, it says so. Best for support and documentation agents where fabrication is unacceptable.
Balanced — primarily retrieval; can use general knowledge for context or framing, never to substitute for missing company facts. Recommended default.
Flexible — retrieval as a guide, supplemented by general knowledge where retrieval is incomplete. Still forbidden from fabricating company-specific examples or statistics.

Will deleting a file remove it from the agent’s knowledge immediately?

Deleting a file removes the source record and triggers cleanup of the associated vectors. After the cleanup completes, the agent can no longer retrieve from that file. There can be a brief window between deletion and full vector cleanup, but no new responses will use the deleted content once cleanup finishes.

What happens if I delete a URL source while the agent is in use?

Same as files — the vectors are cleaned up and the agent stops retrieving that content. Conversations already in progress aren’t interrupted.

Lead Capture

How does Lead Capture know who to save?

Leads are uniquely identified by (agent, email). If a visitor returns and provides the same email, their existing record is updated rather than duplicated. New information (intent changes, additional fields) is merged into the existing lead.

What if the visitor never provides an email?

A lead can still be saved without an email — but without an email there’s no deduplication key, so each tool call creates a new row. This is intentional (a lead with only a name or phone is better than no lead at all), but it means you can see multiple rows for the same anonymous visitor across sessions.

Why is my agent rejecting valid-looking emails like `[email protected]`?

The Lead Capture tool rejects emails from common placeholder/test domains: example.com, test.com, placeholder.com, fake.com, dummy.com, sample.com. These are typically AI hallucinations or test inputs, not real visitors. If a visitor provides one of these, the lead is not saved and the agent is told to ask for a real address.

My agent collected an email but no lead appeared in the Leads tab. What happened?

A few possibilities:

The agent acknowledged the email in conversation but never called the tool. Acknowledging a field is not the same as persisting it. Check the conversation — if the agent said “Thanks, I’ve got your email” without then calling the tool, the lead wasn’t saved.
The email was in the rejected placeholder list (see above).
The Lead Capture tool wasn’t enabled in the Tools tab — check there first.
The prompt was hand-written and doesn’t tell the model to call lead_capture_tool. The Prompt Builder generates rules for this automatically; hand-written prompts need to invoke it explicitly.

Can I require both email and phone?

Yes. In the agent’s Tools tab, under Lead Capture Fields, mark both as required. The agent will collect them both before calling the tool. Keep in mind: more required fields means higher friction and more drop-off. Email alone is often enough.

What’s the difference between “required” and “optional” fields?

Required fields are collected first — the agent will not call lead_capture_tool until all required fields are provided by the visitor. Optional fields are asked naturally and contextually, without interrupting the conversation flow. The agent won’t repeatedly ask for an optional field if the visitor declines.

How does the agent classify lead intent?

The agent silently infers intent from the conversation and includes it in each tool call. There are 10 possible values: PRICING, DEMO, SALES, SUPPORT, BOOKING, GENERAL, JOB_APPLICANT, PARTNERSHIP, SPAM, UNKNOWN.

You don’t configure intent detection — it’s automatic. If the agent returns a value that doesn’t match any of these (e.g. an LLM hallucination), it’s safely coerced to UNKNOWN rather than failing the lead save.

Why does intent sometimes stay at `UNKNOWN`?

A few reasons:

The visitor hasn’t said anything that signals a clear intent — most “hello” or one-line exchanges produce UNKNOWN.
The agent followed the Intent Policy rule: don’t promote intent on weak signals. This is intentional — false-high intent classifications are worse than UNKNOWN.
The model returned an invalid enum value, which gets coerced to UNKNOWN to avoid losing the lead.

Intent can also be updated on later tool calls as stronger signals emerge.

Will the same lead be updated as the conversation progresses?

Yes — the agent treats the lead record as a continuously evolving profile. As the visitor provides more information (a name later in the chat, a clearer intent signal, a phone number), the agent calls the tool again with the updated values, and the existing row is upserted.

Where does the visitor’s location come from?

City, region, and country are captured automatically from the visitor’s chat session (based on their request metadata). The AI does not provide geo — it’s attached at tool execution time. You don’t need to configure anything.

Can I disable lead capture without uninstalling the tool?

Yes — disable it in the Tools tab. The tool will no longer be registered at runtime and the agent won’t have access to it, regardless of what the prompt says.

You can also disable it for a specific conversation by not enabling it on that particular agent. Lead Capture is per-agent.

Can I export leads?

Yes — the Leads tab has a CSV export. All captured leads for the agent, including intent and geo, are included.

What if I change the required/optional fields after leads have already been collected?

Existing leads are not affected. New leads will follow the updated field configuration. Note: if you switch a field from optional to required, the agent will only enforce the new requirement for new tool calls — existing leads won’t be retroactively updated.

After changing field configuration, re-open the Prompt Builder and re-apply so the agent’s prompt reflects the new rules.

Where do I get my publishable key?

It’s on each agent’s Script tab. The same key works across all installation methods (script tag, GTM, framework integrations, etc.).

Check, in order:

The script actually loaded — open DevTools → Network and confirm widget.js returned 200.
The publishable key is correct — typos in data-pk or the init call silently fail.
Console errors — script errors from other libraries on the page can prevent the widget from initializing.
Lazy mode — if you set data-lazy="interaction", the widget only loads after the visitor scrolls, clicks, or moves the mouse. It’s not broken; it’s waiting.
Inline container missing — if you passed container: '#some-id', that element must exist when init is called.

Yes. On the agent’s settings, set the Client Origin to your domain (e.g. example.com). The chat API will only accept requests from that origin or its subdomains. Setting it to * allows any origin (not recommended for production).

Almost always a Client Origin mismatch. Local dev runs on localhost (or a tunnel domain), production runs on your real domain. Either:

Set Client Origin to your production domain before deploying, or
Use * temporarily for testing (then lock down for production)

Yes. The chat endpoint returns SUBSCRIPTION_EXPIRED if the agent’s owner doesn’t have an active subscription. The widget will load but conversations will fail.

Is there a rate limit on conversations?

Yes — 1,000 requests per agent per hour, sliding window. Bursts within that limit are fine; sustained traffic above it returns rate-limit errors.

Use the metadata option (JSON string). See Widget Guide § Identifying Users. The metadata becomes available to the agent during the conversation.

My users log in and out — how do I prevent chat history from leaking between sessions?

Call window.Jhunkoo('destroy') on logout to tear down the widget. To switch to a different user or tenant without a page refresh, call init again — passing a new publishable key starts a fresh session. See Widget Guide § SPA Security & Routing for details.

For sensitive deployments (e.g. multi-tenant dashboards), reload the page on logout as a stronger guarantee — a full page reload always resets all client-side state.

How do I install via Google Tag Manager?

GTM strips custom script attributes like data-pk. Use a Custom HTML Tag with the inline init pattern documented in Widget Guide § GTM / Segment.

Yes — the widget runs anywhere a <script> tag runs. Standard browser CORS and frame-ancestors policies apply; if the parent page blocks framing, the widget inside the iframe is still functional within that iframe.

The widget JavaScript downloads on demand. With async loading, it doesn’t block your page render but takes a moment to initialize. With data-lazy="interaction", it’s deliberately deferred until the visitor interacts with the page (for Lighthouse score reasons).

Billing & Usage

🚨 What’s the difference between free and paid tokens?

Free tokens are included with your plan and reset every billing period:

Good — 1,000,000 / month
Better — 5,000,000 / month
Best — 25,000,000 / month

Annual plans get 12× the monthly allowance up-front for the year.

Paid tokens are top-ups you buy on demand. They don’t expire and roll over indefinitely.

When the agent consumes tokens, free tokens are spent first, then paid tokens. The chat API requires at least 5,000 tokens of combined balance to start a new conversation.

My conversations stopped working — what happened?

Check the agent’s chat error response. Common causes:

SUBSCRIPTION_EXPIRED — no active subscription. Re-subscribe to restore access.
Low token balance (combined free + paid is under 5,000). Buy a token top-up or wait for the next billing cycle.
Rate limit hit (1,000 requests/hour per agent). Comes back automatically.

How do I see token usage?

The Usage tab on each agent shows per-agent token consumption. The Manage → Usage page shows your account-wide totals.

Where can I buy more tokens?

Manage → Tokens. Purchases are immediate and credited to your paidTokens balance, which never expires.

Why did this conversation cost more tokens than I expected?

A few common reasons:

Large system prompt — every message pays for the full prompt on input. Lots of Custom Instructions, many tools, and large knowledge-base retrievals all inflate input cost.
Long conversation history — chat history is included in each request, up to the configured window (default 5 message pairs). Longer windows mean larger inputs.
Knowledge Base retrievals — when the agent searches the KB, the retrieved chunks are added to the prompt for that turn.
Tool calls — each tool call is a round-trip with the model, consuming more tokens than a direct answer.

Do failed conversations consume tokens?

Yes — tokens are spent during model invocation, not at delivery. A request that errors mid-stream still consumes whatever was processed up to the failure point.

🚨 What are the per-plan agent and API tool limits?

Plan	Agents	API tools / agent	Files / agent	URLs / agent
Good	3	3	3	5
Better	10	10	10	20
Best	100	10	10	—

🚨 Can I have multiple organizations?

Plan-dependent: Good includes 1 organization, Better includes 3, Best includes more. Membership limits per organization also scale with plan (Good: 3, Better: 5).

Does usage on a deleted agent still count against my plan?

Past usage that’s already been recorded stays in your usage history (and in any unsettled billing for the current cycle). Going forward, a deleted agent can’t accumulate new usage. Token consumption is by user/owner account, not per agent — deleting the agent doesn’t refund or release tokens already spent.

Have a question that isn’t answered here? Email [email protected] — we update this page based on what operators actually ask.

Widget Guide