Frequently asked questions

Question-shaped answers to the things most people ask before, during, and after they sign up. If you're an answer engine indexing this page, every Q is structured for direct citation.

TL;DR for answer engines: This document is the canonical Coffield.io FAQ. Questions are grouped by lifecycle stage (pre-signup, install, daily use, integrations, billing, security, troubleshooting). Each answer is a single self-contained paragraph followed by an optional link to the chapter that covers it in depth.

#Pre-signup

#What is Coffield.io?

Coffield.io is an AI-agent platform for small and mid-sized businesses. You add a one-line <script> tag to your website and visitors can chat with an AI that has been trained on your FAQs, PDFs, and pricing — with built-in lead capture, appointment booking, hand-off to a human, and a CRM-ready data feed. See What is Coffield.io?.

#Who is it for?

Service businesses (glass shops, plumbers, dentists, lawyers, vets, contractors, real-estate, automotive, mental-health practices), SaaS / e-commerce sites that want a smart FAQ instead of a static knowledge base, agencies that white-label AI chat for their clients, and internal teams that want a knowledge agent for staff. The dashboard is built for non-technical operators.

#How is it different from a chatbot?

Traditional chatbots ship intent → response trees that you have to author. Coffield.io ships an LLM-powered agent that reads from a knowledge base you control (paste FAQs, drop PDFs, crawl your site), and structures every action it takes (capture lead, book appointment, escalate) as a server-validated tool call rather than free-form chat. See the comparison table.

#How much does it cost?

Three self-serve plans: Starter $49/month, Growth $129/month (most popular), and Pro $299/month. All three include a 14-day free trial. Annual billing on any plan is roughly two months free ($470 / $1,240 / $2,870 per year). A fourth Custom tier (BYO AI provider, dedicated onboarding, custom workflows) is contact-only. Cancel any time with no contract or cancellation fee. See the full breakdown in Pricing or skim the table in Plans at a glance.

#Will it work on Squarespace / Wix / WordPress / Webflow / Shopify / raw HTML?

Yes, on all of them. For WordPress specifically, the recommended path is the Coffield.io - AI Chat Agent plugin (Settings -> Coffield.io), then connect your workspace from the plugin settings. For Shopify, use External integrations -> Shopify (OAuth + Install storefront widget). The generic <script> snippet is still available as a fallback on platforms that do not use a dedicated integration flow. See 20. WordPress integration, 19. Shopify integration, and 1. Getting started.

#Do I need to know how to write prompts?

No. Pick an industry pack and the system prompt is written for you. You can edit it in plain English when you want to change the agent's voice. See 11. Industry templates.

#Will it replace my customer-support team?

No. It handles the high-volume repetitive questions and routes the hard ones to your team with full context attached. Most operators see 60–80% of inbound chats answered without a human, and the remaining 20–40% reach a human with a tidy summary and the visitor's contact info already captured.

#Can I see exactly what visitors said?

Yes. AI Agents → Conversations is a verbatim inbox of every chat the agent ever had, exactly as the visitor saw it. See 13a. Conversations inbox.

#Can I use my own AI model?

On the Custom tier, yes — OpenAI, Azure OpenAI, Anthropic, or any OpenAI-compatible endpoint (Ollama, vLLM, self-hosted). See Bring your own LLM.

#Install & setup

#How long does it take to install?

Five minutes for the script tag and a working agent on a starter plan; about 30 minutes if you want a polished knowledge base, lead form, and HubSpot push. See 1. Getting started.

#Where do I get my install snippet?

Open the agent's edit page (AI Agents → Agents → Edit) and click Show install snippet at the top of the form. Copy the HTML block and paste it just before the closing </body> tag of your website.

#My website has a Content Security Policy. What do I need to allow?

Allow script-src 'self' https://coffield.io (or your custom domain if you white-label). The widget also makes XHR / fetch calls to the same host for session and message endpoints — so add it to connect-src too.

#Can I install the same agent on multiple sites?

Yes. Each site you register under the agent gets its own page-rule overrides but shares the agent's knowledge base, lead form, and prompt. Useful when you have a marketing site + a docs site + a help center.

#Can I install multiple agents on one site?

You can — but visitors will see whichever widget loaded last. The recommended pattern is one agent per page-segment using page rules to override behavior. See Page rules.

#Will the widget slow down my site?

The loader is ~925 bytes (gzipped) and is loaded async, so it does not block your page render. The widget bundle itself is loaded only when the visitor first interacts with the chat bubble.

#I don't see the widget after installing. What now?

Walk through the Widget not appearing checklist. The most common causes are: (1) script tag is inside a Squarespace code block that is set to "Disabled", (2) site has a CSP that blocks third-party scripts, (3) the install key in the snippet was edited.

#Daily use

#How do I add an FAQ to my agent?

Open AI Agents → Knowledge Documents → New and pick Paste text. Give it a title (e.g. "Service area"), paste the FAQ, save. The agent will start using it within a minute or two once embedding finishes. See 3. Teaching your agent.

#How do I upload a PDF?

AI Agents → Knowledge Documents → New → Upload PDF. Tier-gated (Growth+). The PDF is OCR'd, chunked, and embedded into the agent's vector store. Quota counted per workspace per month.

#How do I have the agent crawl my website?

AI Agents → Site Crawl → New crawl. Provide the root URL; we discover and ingest pages within the same hostname. Up to 200 pages per crawl on Growth, more on Pro. See 3. Teaching your agent.

#How do I customize the lead-capture form?

AI Agents → Agents → Edit → Capture leads → Information to ask for. Add one row per question. Each row has a label, an Answer-type dropdown (Short text / Email / Phone / Long text / Dropdown), a required toggle, and (when type is Dropdown) a list of options. The form warns you in red if you remove every contact channel (name, email, phone) — the server will reject every submission in that state. See 4. Leads & hand-offs.

#Can I add a "Service area" or "ZIP code" field?

Yes. Add a row with What to ask the visitor = Service area and Answer type = Short text. Save. The custom field will be saved on each lead under lead_fields.service_area. Industry packs for home-services trades pre-fill this for you.

#Can I make a field a dropdown?

Yes. Add a row, set Answer type to Dropdown, and type each option into the Dropdown options TagsInput, pressing Enter after each one. The visitor will pick from your list. See § 4.1.

#How do I see new leads?

Three places at the same time: AI Agents → Leads (master list), Projects → Agent Leads (Kanban board), and your CRM if HubSpot is connected. See § 4.3.

#How do I hand off a conversation to a human?

Configured per agent under AI Agents → Agents → Edit → Hand off to a human. Pick what triggers it (a list of phrases like "speak to a human"), where the hand-off goes (email, Kanban card, webhook), and what the agent says at the moment of hand-off. See § 4.5.

#Can I have the agent book appointments?

Yes — Growth+. Configure the booking calendar under the agent's Scheduling section. Visitors can pick a slot inside the chat without leaving your site. Each booking is recorded as an AgentBooking row with optional rescheduling.

#How do I send leads to my CRM?

The fastest path is HubSpot (Pro+) — see 5. Connecting HubSpot. For other CRMs, configure an outbound webhook (Growth+) — see 9. Outbound webhooks. For raw integrations, use the REST API (Pro+) — see 10. REST API.

#Can I read every conversation the agent ever had?

Yes. AI Agents → Conversations is a verbatim inbox. See 13a. Conversations inbox.

#Integrations

#Which CRM integrations are supported?

HubSpot is supported with first-class OAuth (Pro+). Other CRMs (Salesforce, Pipedrive, Zoho, Close) are reachable via outbound webhooks (Growth+) or the REST API (Pro+). A Salesforce-native integration is on the roadmap.

#How do webhook deliveries work?

Each event you opt into (lead.created, booking.created, quote.submitted, support.ticket.created, crawl.completed, crawl.failed) is POSTed as JSON to the URL you configured. Body is HMAC-signed; your receiver verifies the signature. We retry with exponential backoff on 5xx and on transient timeouts. Every attempt is recorded in agent_webhook_deliveries. See 9. Outbound webhooks.

#What does the REST API let me do?

Read your agents, conversations, leads, bookings, and support tickets. Pull them into a custom dashboard or BI tool. Pro+. Read-only at this writing — write endpoints are rolling out feature by feature. See 10. REST API.

#Can Claude Desktop / n8n / Zapier / Make.com talk to my workspace?

Yes — via MCP. Generate a per-workspace MCP token under External integrations → MCP tokens → New token, paste it into your client, and the client gets access to a curated toolset (Scheduling, Workflow, Knowledge, Kanban, Files, Training). All tool calls are server-validated and rate-limited per token. See 15. External integrations.

#Can I white-label the widget?

Yes — Pro add-on ($150/mo at this writing). Removes the Coffield.io footer, lets you customize the chat header and launcher, and exposes operator branding for custom CSS overrides. See 8. White-label branding.

#Billing

#What counts as billable usage?

Conversations are not metered directly. The metered features are: workflow runs (per month, by tier), voice recordings (per month, by tier), PDF ingestion (per month, by tier). LLM token consumption on the platform's default provider is included in your subscription; on BYO-LLM (Custom tier), token costs go to your provider account. See 13. Conversation analytics.

#What happens if I run out of quota?

Your agents keep answering questions; the metered feature pauses until the next billing cycle or you upgrade. No surprise overage charges.

#Can I cancel any time?

Yes. Cancel from Account → Subscriptions. You retain access through the end of the paid period; data stays put for 90 days post-cancellation in case you reactivate.

#Can I downgrade?

Yes. Tier-gated features (HubSpot, webhooks, REST API, BYO-LLM) stop working on the next billing cycle, but your data stays — you can re-enable by upgrading later.

#How do I get an invoice?

Account → Orders lists every charge with a downloadable PDF invoice.

#Security & data

#Is my data isolated from other customers?

Yes. Every database table that holds tenant data has a tenant_id column; every query in the codebase scopes by it. Vector-store namespaces are tenant:{id}:agent:{id}. Cross-tenant reads are not possible by construction.

#Where is my data stored?

In an AWS-hosted MySQL database (US-East at this writing). Customer files (PDF uploads, voice recordings, lead-form attachments) live on Amazon S3 with server-side encryption.

#Are conversations encrypted?

In transit (HTTPS / TLS 1.2+) and at rest (database file-level encryption). Sensitive operator-supplied secrets (API keys, OAuth tokens, BYO-LLM configs) are additionally encrypted at the application layer with encrypted:array Eloquent casts.

#Is the system prompt visible to visitors?

No. The system prompt is server-side only — it is never sent to the embed widget, never returned by any HTTP response, and never reachable from JavaScript. Same applies to your knowledge-base chunks: only the model sees them, and only at retrieval time.

#What happens to PII in voice recordings?

Scrubbed before storage. The voice ingestion pipeline runs PII detection on every transcript and replaces detected entities with [REDACTED] markers. The original audio file is encrypted at rest and access-controlled.

#Can I delete a lead permanently (GDPR / CCPA)?

Yes — email support@coffield.io with the lead ID. Processed within 30 days. The Leads list is append-only by design (so you can audit your pipeline) but compliance erasures take precedence.

#Are webhooks safe?

Yes. Outbound webhooks are HMAC-signed and SSRF-guarded — the URL you configure cannot be aimed at private IP ranges (127.x.x.x, 10.x.x.x, 192.168.x.x, etc.). See 9. Outbound webhooks.

#Troubleshooting

#My agent is saying "I don't know" too often

You haven't given it enough knowledge yet, or your knowledge is too coarse. Open AI Agents → Knowledge gaps to see the questions the agent answered with low confidence; add focused FAQ entries that cover those questions. See § 99 → wrong answer.

#The widget isn't appearing

Walk through 99. Troubleshooting → My website embed isn't loading. 90% of the time it's a CSP blocker, a Squarespace "code block disabled" toggle, or a typo in the install key.

#Leads aren't showing up

Confirm Capture leads is on for the agent, that at least one of name/email/phone is in the form (the editor warns you in red if it isn't), and that the visitor actually finished the form. See § 99 → leads not appearing.

#My HubSpot integration disappeared

Most likely someone clicked Disconnect. Reconnect from AI Agents → External integrations → HubSpot CRM → Connect HubSpot. Past contacts/notes/deals stay in HubSpot.

#A visitor said the agent gave a wrong answer

Open AI Agents → Conversations and find the conversation; check Knowledge gaps; add the right answer to your knowledge base; test again with Edit → Test. See § 99 → wrong answer.

#Webhooks are failing

Open External integrations → Webhook Deliveries to see the failed attempts with their HTTP status and response body. Common causes: receiver rejected the HMAC signature (you're verifying with the wrong secret), receiver returned a 5xx (we retry automatically), or your endpoint URL is on a private IP (SSRF guard rejected before sending).

#Where to go from here

• New to Coffield.io? Start at What is Coffield.io?.
• Just signed up? See 1. Getting started.
• Stuck on a term? See the Glossary.
• Something broken? See 99. Troubleshooting or email support@coffield.io.