> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dmly.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Build a lead qualification bot

> Install a ready-made lead qualification template, tune it, and publish a bot that captures interest, tags hot leads and hands them to a human.

A lead qualification bot answers the first message, finds out what someone wants, saves the
answers onto the contact, and passes the strong ones to a human. DMLY ships two ready-made
templates for this, and installing one is faster than building it node by node.

Pick the one that matches what you have:

<Columns cols={2}>
  <Card title="AI Lead Qualification bot" icon="sparkles">
    "An AI agent greets visitors, qualifies inbound leads, captures their details, tags hot
    leads, and hands strong prospects to a human." Works on every channel. Needs a connected
    AI provider and the AI Agent on your plan.
  </Card>

  <Card title="Lead Qualification Flow" icon="diagram-project">
    "Ask interest, budget and timeline, then route hot leads to sales and nurture the rest."
    Fixed questions, no AI, nothing to connect. Predictable, and free of the plan gate.
  </Card>
</Columns>

<Warning>
  The AI template is not self-sufficient. If no AI provider is connected, the **AI Reply**
  step does not error — it is **skipped**. The flow carries on to the end and writes a system
  note into the conversation ("AI step skipped — no AI provider is connected."). The contact
  gets nothing back. Connect a provider before you publish.

  The AI Agent plan gate is skipped the same way, with its own note ("AI step skipped — your
  plan does not include the AI Agent."). You won't hit this on the way in — a plan without
  the AI Agent blocks the install outright. It only bites after a downgrade, so check the bot
  again after any plan change.
</Warning>

## Route A — the AI lead qualification bot

<Steps>
  <Step title="Connect an AI provider">
    Go to **Integrations** and connect one of the four providers the AI step supports:
    **OpenAI**, **Claude (Anthropic)**, **Google Gemini** or **DeepSeek**. That is the whole
    list — nothing else can drive an AI Reply step.

    If the tile shows a **Plan locked** pill and an **Upgrade** button instead of
    **Connect**, the AI Agent isn't on your plan. See [Plans](/billing/plans) and
    [Connect OpenAI](/integrations/openai).
  </Step>

  <Step title="Install the template">
    Create a new automation on the channel you want the bot to run on. The templates picker
    opens, already filtered to that channel's platform — only templates that channel supports
    are shown. The AI bot carries a **Popular** badge and sits in the default **Recommended**
    section — look there, or search for it by name. Open the card and select **Use this
    template**.

    Installing creates a Draft automation seeded with the template's flow and drops you
    straight onto the builder canvas. Nothing is live yet.

    An amber **Setup required** badge on the card means no AI provider is connected yet — and
    the button reads **Install & set up** instead. The template still installs; the step just
    won't reply until you connect one. (The **Requires AI** chip is not a warning — it lists
    what the template needs, and stays on the card whether or not a provider is connected.)
  </Step>

  <Step title="Read the flow">
    The AI template is deliberately small: a trigger, one **AI Reply** node, and an End node.
    On the canvas the trigger reads **User sends a message** — installing rewrites the
    template's generic trigger to the real one for your channel. It fires on *every* inbound
    message from a contact, not just their first; to change that, use the **Only respond once
    per contact** toggle on the trigger. All the behaviour lives inside the one node — there
    is no branching to wire up.
  </Step>

  <Step title="Write the prompt">
    Open the **AI Reply** node and go to the **Prompt** tab. **System prompt / instructions**
    is where you tell the AI what qualifying means for your business: what to ask, what counts
    as a hot lead, when to hand over.

    The prompt supports tokens — `{{business_name}}` resolves to your workspace name, and
    `{{first_name}}` to the contact's first name. Be specific about your own qualifiers
    ("ask which treatment they want, roughly when, and whether they've visited before")
    rather than leaving it generic.

    Also on this tab: **Fallback message (on error / empty reply)**, which is what the contact
    receives if the AI fails or returns nothing, and **Typing delay before reply (seconds)**.
  </Step>

  <Step title="Check the model settings">
    On **Configuration**, pick your **Provider** (only connected providers are listed) and a
    **Model**. The model field is free text with suggestions — you can type any model id your
    provider supports.

    **Max tokens** caps the length of a reply. **Conversation history (messages)** controls
    how much of the thread the AI sees each turn; qualification is a conversation, so don't
    cut this down to a couple of messages.
  </Step>

  <Step title="Confirm the tools">
    **Built-in Tools** is what makes this a qualification bot rather than a chat toy. The
    template arrives with eight already ticked under **CRM contact tools**:

    | Tool                           | What it lets the AI do                         |
    | ------------------------------ | ---------------------------------------------- |
    | **Get contact info**           | See who it's talking to before asking          |
    | **Update phone number**        | Save a number the contact types in chat        |
    | **Set custom fields**          | Store the answers — budget, timeline, interest |
    | **Add tags** / **Remove tags** | Mark a lead hot, clear a stale tag             |
    | **Move CRM stage**             | Advance the contact down the pipeline          |
    | **Add a note**                 | Leave the human a summary                      |
    | **Hand over to a human**       | Stop the bot and pass the thread over          |

    Create the tags, stages and fields you name in the prompt *first*, so the AI has somewhere
    to put the answers — see [Tags and segments](/contacts/tags-and-segments),
    [Pipeline stages](/contacts/pipeline-stages) and
    [Custom fields](/contacts/custom-fields). The full tool surface, including booking tools,
    is on [AI agent tools](/automation/ai-agent-tools).
  </Step>

  <Step title="Test it in the Playground">
    The **Playground** tab runs your configuration without sending a real message. Type a
    **Test message**, select **Run**, and you get back the **Reply** plus a **Tool calls**
    trace showing which tools the AI decided to use. Tool calls there run against demo data —
    no contact is touched and nothing lands in the Inbox.

    This is the fastest way to find a prompt that never bothers to hand over, or one that tags
    everyone as hot.
  </Step>

  <Step title="Publish">
    Publish from the builder. See [Publishing bots](/automation/publishing-bots).
  </Step>
</Steps>

### How the AI bot behaves in a real conversation

<Accordion title="It keeps chatting until it's done">
  Because the node's output leads to an End node, the AI Reply step is **conversational**: it
  replies, then waits for the contact's next message and replies again. That's what lets it
  ask a follow-up question. A conversation caps at 40 turns, after which the step moves on.

  Put a node *after* the AI step and it stops being conversational — it replies once and
  continues down the flow.
</Accordion>

<Accordion title="Handover really stops it">
  When the AI hands over to a human, the bot is paused for that contact and the AI step ends
  rather than parking for another turn. It can't talk over your team.
</Accordion>

<Accordion title="Failures don't stall the flow">
  If the AI errors or returns an empty reply, the contact receives your **Fallback message
  (on error / empty reply)** instead. The AI template ships with "Thanks `{{first_name}}`! A
  member of our team will follow up with you shortly." unless you change it. The flow always
  continues.

  If the node's chosen provider isn't connected but another one is, it quietly uses the other
  one rather than failing.
</Accordion>

<Tip>
  Want the bot to answer product or pricing questions while it qualifies? Turn on **Document
  search (File Search)** on the **Built-in Tools** tab and select a vector store — but note it
  is offered on OpenAI and Google Gemini only. On Claude and DeepSeek the tab reads "Document
  search is not available for this provider." The tool is also silently dropped if you switch
  it on without selecting a store. See [Knowledge base](/integrations/knowledge-base).
</Tip>

## Route B — the fixed-question flow

**Lead Qualification Flow** asks the same three questions every time and branches on the
answer. No AI provider, no plan gate, no surprises.

The installed flow is eight nodes:

1. Three question steps, asking **interest**, **budget** and **timeline** and saving each
   answer into a custom field of that name.
2. A condition that checks the timeline answer against a keyword list: `asap`, `urgent`,
   `this week`, `this month`, `now`.
3. A **HOT** branch with an **Assign Conversation** step, and a **NURTURE** branch that sends
   a follow-up message.

<Note>
  That keyword list is the whole of the bot's judgement — edit it to match how your customers
  actually write. "Today", "right away" and "before Friday" all fall into NURTURE until you
  add them.
</Note>

<Warning>
  As installed, the **Assign Conversation** step on the HOT branch assigns to nobody. The
  canvas summary reads "Assign to Sales", but no team member is actually selected — and
  nothing warns you, on the canvas or at publish. Open the node and pick someone under
  **Assign to**, or hot leads route to the branch and sit there unassigned.
</Warning>

Both branches must stay connected. An unconnected condition branch is advisory on the canvas
but blocks publish — see [Common mistakes](/automation/common-mistakes).

## Other qualification templates

Worth a look before you build anything by hand:

<Columns cols={2}>
  <Card title="Welcome & qualify new chats" icon="whatsapp">
    A WhatsApp quick automation — a welcome that qualifies in the same breath. No canvas.
  </Card>

  <Card title="Welcome & Qualify New Chats" icon="hand">
    The flow-builder one, near-identical in name. Uses interactive buttons, so it installs on
    WhatsApp, Facebook and Instagram only.
  </Card>

  <Card title="Lead qualification flow" icon="instagram">
    Instagram. "Ask a question, branch on the answer, and tag the lead."
  </Card>

  <Card title="Ask for phone number when missing" icon="phone">
    WhatsApp. Bolt onto the end of a qualification bot when the contact reached you without a
    number — see [Request phone](/automation/request-phone).
  </Card>
</Columns>

## Before it goes live

<Accordion title="Only one bot can answer every message on a channel">
  Publishing is blocked if another active automation on the same channel already replies to
  every message — both would answer. Give one a specific keyword, or pause the other. This is
  the most common thing that stops a lead qualification bot from publishing, because
  qualification bots are exactly the kind that answer everything.
</Accordion>

<Accordion title="Publish is blocked on a plan without the AI Agent">
  You'll see: "This automation uses an AI step, which your plan does not include. Upgrade your
  plan to use it, or remove the AI step." Route B has no AI step and publishes fine.
</Accordion>

<Accordion title="It published but never fires">
  A bot that is paused for that contact, a flow with no published version, or "only respond
  once per contact" having already fired will all silently do nothing. Start at
  [Automation not triggering](/troubleshooting/automation-not-triggering).
</Accordion>

<Columns cols={2}>
  <Card title="Flow builder" icon="diagram-project" href="/automation/flow-builder">
    The canvas, nodes and ports in full.
  </Card>

  <Card title="AI agent tools" icon="sparkles" href="/automation/ai-agent-tools">
    Every tool the AI step can act with.
  </Card>

  <Card title="Templates" icon="copy" href="/automation/templates">
    The whole template library and how the picker filters it.
  </Card>

  <Card title="Common mistakes" icon="triangle-exclamation" href="/automation/common-mistakes">
    Unconnected branches, fan-out, orphan nodes.
  </Card>
</Columns>