Leads & hand-offs

A lead is what happens when a visitor on your website shares their contact info with your agent — usually because they want a quote, want to book, or just want to hear back from a real person. This chapter explains how to switch lead capture on, what gets collected, where leads land, and how to hand off the conversation to a human when the AI hits the limits of what it should answer.

Plain English summary: You decide what the agent should ask for (name, email, phone, etc.) and when it should ask. Every time a visitor answers, we save them as a lead in your dashboard, drop a card on a project board so you can work them like a sales pipeline, and — if you've connected one — push them straight into your CRM.

#Turning lead capture on

1. Open the agent's edit page (AI Agents → Agents → Edit).
2. Scroll to the Capture leads section.
3. Toggle Collect leads from this agent to on.
4. Under Information to ask for, click Add another field for each piece of info you want to collect. For each row:
   • What to ask the visitor — the label the visitor sees (e.g. "Your name", "Best email", "Phone number", "What do you need?").
   • Answer type — pick one:
     • Short text — free-form one-line answer (default).
     • Email address — validates the input is shaped like an email in the visitor's browser.
     • Phone number — mobile-keyboard friendly numeric input.
     • Long text — multi-line textarea, ideal for "Tell us about your project".
     • Dropdown — visitor picks from a list you supply.
   • Required — if on, the visitor must answer to finish the form.
   • Dropdown options — only appears when Answer type is Dropdown. Type each option and press Enter (e.g. Shower door / Mirror / Window). Drag to reorder.
5. Watch the green banner under the form. If you remove every contact channel (name / email / phone), the banner turns red and warns: "Heads up: none of the fields above are recognised as name, email, or phone. The lead form will reject every submission until at least one of those is added." That's the server-side validation rule — follow the warning.
6. (Optional) Add a short phrase to Words that start lead capture, e.g. "get a quote", "schedule a call", "talk to sales". If you leave this blank, the AI decides on its own based on how the conversation is going.
7. Click Save.

Tip — the canonical key is auto-detected. If you label a field "Your name" the system recognises it as a contact name and stores it in the typed contact_name column (so it shows up in the Leads list, the CRM push, and the analytics). The same is true for email, phone, and project-detail style fields. Anything else (e.g. "ZIP code", "Service area", "Vehicle make") is saved as a custom field on the lead under lead_fields_json.

What if I don't set a trigger phrase? The agent watches for natural buying-intent language ("how much would it cost", "do you do X", "can someone call me") and asks for the contact details at the right moment. The trigger phrase is just a hard cue you can add when there's specific wording your visitors use.

#What the visitor sees

When the agent decides it's time to collect a lead, it asks one question at a time — not a long form. For example:

"I'd love to put you in touch with someone who can give you an accurate quote. What's the best name to put on that?"

"Thanks, Sam — and what email should they use to follow up?"

"Got it. Last one — what's the best phone number, in case email goes to spam?"

The visitor can answer in any order, skip fields ("no email please — just call"), or change their mind. The agent is permissive on purpose so it doesn't feel like an interrogation. As long as at least one contact field is filled in, the lead gets saved.

#Where leads land

Every captured lead lands in three places at the same time:

#The Leads list

Each row shows the visitor's name (or Anonymous visitor if they didn't share one), email, phone, which agent captured them, status badge, the Kanban card number, and when they came in. Click the row to see the full conversation context — including the visitor's project notes and the conversation ID.

#The Agent Leads project board

We create the "Agent Leads" project automatically the first time a lead comes in, with five columns ready to go:

1. New Leads — fresh, untouched.
2. Contacted — you've reached out.
3. Qualified — it's a real opportunity.
4. Converted — they became a customer.
5. Lost — moved on.

Each card's title is the lead's name + contact summary, and the description includes the project notes the visitor shared. Drag cards across columns to move them through your pipeline. The board respects everyone you've invited to your workspace, so your team can work leads together.

Why both a list and a board? The list is for finding a specific lead and updating its status. The board is for working through leads visually, in order, the way most teams already think about a pipeline.

Want the full board tour? See Chapter 7 — Projects (Kanban) for everything boards can do: card chat, attachments, deep-link URLs, member access, and the activity log.

#Updating a lead's status

1. Go to AI Agents → Leads.
2. Click the row for the lead.
3. Click Update status (top-right).
4. Pick one of: New, Contacted, Qualified, Converted, Lost.
5. Click Save.

You'll get a green confirmation toast. The Leads list and the Kanban card stay in sync — moving the card on the board updates the lead's status, and updating the status here moves the card.

Who can update statuses? Anyone with the Manage agents permission. Other workspace users can view leads but not edit them — handy if you want to give finance or fulfillment read-only access.

#Hand-offs: when the agent should give up the mic

The agent will happily answer most questions, but some conversations need a human — angry customers, complex billing disputes, urgent on-site problems, or the word lawyer. That's a hand-off.

Hand-offs are configured on the agent's edit page, in the Hand off to a human section (collapsed by default — click to expand).

1. Words that trigger a hand-off — type each phrase and press Enter. Examples: "speak to a human", "this is urgent", "file a complaint", "talk to a manager", "lawyer". When the visitor uses any of these phrases, the agent stops trying to solve the problem itself and routes the conversation.
2. Where to send it — pick one:

3. What to say while handing off — the line the agent says to the visitor at the moment of hand-off. Default works fine; customize it to match your tone.
4. Click Save.

The agent always confirms. When a hand-off fires, the agent finishes the visitor's current question politely, says the "What to say while handing off" line, and stops trying to solve. It does not silently end the conversation — the visitor always knows a human is on the way.

#Safety-driven hand-offs (regulated templates only)

If you installed a regulated industry template (mental health counseling, dental, veterinary, automotive, etc. — see chapter 11), the agent already has safety-critical hand-off rules baked in that you don't have to configure:

• Mental health — any mention of self-harm or crisis triggers the 988 Suicide & Crisis Lifeline + 911 script verbatim, every time. The agent will not attempt counseling.
• Veterinary — emergencies route to ASPCA Animal Poison Control: (888) 426-4435 and your office phone.
• Dental / medical — emergency-page visits skip qualification questions and go straight to "call our office now" with the office phone number.
• Automotive — safety issues (brakes, accidents, leaks) skip quote intake and route to your shop phone.

These rules ship in the Per-page behavior tab as page rules attached to the agent. They start as Needs site — open each rule, pick which website it applies to, and save. See chapter 11 for the full workflow.

You can add to the safety rules but you should not remove them. They're how we keep visitors (and your business) safe.

#Sending leads to your CRM

The fastest path is HubSpot on the Pro plan — see chapter 5 for the one-screen setup.

If you're not on HubSpot, use a webhook instead. Every captured lead can fire an outbound webhook with the lead's full payload — Zapier, Make, n8n, Pipedrive's webhooks, Salesforce Process Builder, and most other tools will happily receive it. See chapter 9 for setup.

No CRM at all? That's fine. The Leads list + Agent Leads project board are a complete pipeline on their own. Plenty of small businesses run their whole intake-to-close flow here.

#Privacy & deletion

• Leads are tenant-scoped. Only people inside your workspace see your leads.
• Conversations are saved. Each lead links back to the conversation that captured it so you have the full context when you follow up. Don't lose the conversation ID — it's how support can help you reconstruct anything.
• Deleting a lead — leads are append-only by design (so you can audit your pipeline). If you need a specific lead permanently erased (GDPR / CCPA request), email support@coffield.io with the lead ID; we'll process it within 30 days.
• CRM pushes can be retried but not "unsent." If you don't want a contact in HubSpot, delete it from HubSpot directly — we don't have permission to remove what we created.

#Troubleshooting

#Next steps

• Connect HubSpot so leads flow into your CRM → 5. Connecting HubSpot.
• Send leads to any tool with an outbound webhook → 9. Outbound webhooks.
• See how leads are converting compared to plain conversations → AI Agents → Conversation analytics.
• Install an industry template that ships with sensible defaults already filled in → 11. Industry templates.