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

# Lead Qualification Funnel

> Score conversations, email the right people once, tag chats, and split leads across inboxes

The **Lead Qualification Funnel** is Convocore’s built-in SDR layer. While a visitor talks to your agent (web chat, WhatsApp, voice, and other channels), the system:

1. Scores the conversation against **qualification steps** you define (always totaling **100 points**).
2. Extracts facts mentioned in the chat (budget, timeline, name, phone, and so on).
3. Sends **one branded email** when a **conditional email alert** matches — not a workspace-wide blast.
4. Writes **chat tags** so you can filter the conversation in the dashboard.
5. Optionally **splits** those tagged chats across teammates by percent (50/50, 70/30) with no extra AI.

It is **not** an outbound email drip / marketing sequence. It does not send follow-ups to the lead. It emails **your team** when a conversation becomes a qualified lead.

<Info>
  Plan: included on **Pro**, or add **Lead funnel** (\$15/mo) on other plans. See [Pricing](/Pricing/overview). If the builder shows a lock, the workspace does not have the `lead_funnel` capability yet.
</Info>

## Who this is for

<CardGroup cols={3}>
  <Card title="Sales teams" icon="chart-line">
    Get pinged the moment a hot prospect shares budget, timeline, or a phone number — without reading every transcript.
  </Card>

  <Card title="Agencies" icon="building">
    Route client leads to the right inbox, split volume fairly between closers, and send emails in the agency brand.
  </Card>

  <Card title="Multi-location businesses" icon="location-dot">
    Tag chats by market (for example `egypt_rest`) then 50/50 split Omar vs Abdelrahman without a second AI pass.
  </Card>
</CardGroup>

## End-to-end picture

```mermaid theme={null}
flowchart TD
  A[Visitor talks to the agent] --> B{Funnel enabled?}
  B -->|No| Z[Skip]
  B -->|Yes| C[Evaluate after each AI reply<br/>or once at end of a voice call]
  C --> D[Match qualification steps<br/>Score out of 100 + extract facts]
  D --> E{Any enabled email rule matches?}
  E -->|No| F[Save score on the conversation<br/>Wait for the next turn]
  E -->|Yes| G{Need contact info?}
  G -->|Yes and none yet| H[Wait: phone OR email OR WhatsApp]
  G -->|No or already have it| I[First matching rule wins]
  I --> J{Tag routing for this rule tag?}
  J -->|Yes| K[Pick percent share<br/>Send to that share's emails]
  J -->|No| L[Send to the rule's recipients]
  K --> M[Tag the chat + lock<br/>One funnel email per conversation]
  L --> M
```

## Where to find it

<Steps>
  <Step title="Open the agent builder">
    Dashboard → Agents → your agent → **Prompt / Nodes** view (the canvas + right-hand tools rail).
  </Step>

  <Step title="Open Funnel & Lead Scoring">
    On the right rail, find **Funnel & Lead Scoring**. Toggle **Enable scoring**.
  </Step>

  <Step title="Save the agent">
    Funnel config is stored on the agent as `funnelConfig`. Save like any other prompt/tools change.
  </Step>
</Steps>

<Tip>
  The in-product tooltip links here: [docs.convocore.app/features/lead-qualification-funnel](https://docs.convocore.app/features/lead-qualification-funnel).
</Tip>

***

## Qualification steps (the score)

Steps are the checklist the evaluator uses. Each enabled step has:

| Field         | What it does                                                                   |
| ------------- | ------------------------------------------------------------------------------ |
| **Name**      | Short label (e.g. `Budget disclosed`). Shows in emails and debug.              |
| **Condition** | Natural-language rule the model evaluates against the transcript. Be specific. |
| **Points**    | 5–25 typical. **All enabled steps must add up to exactly 100.**                |

<Warning>
  If points are not 100, the builder shows a validation error and the funnel is not considered correctly configured.
</Warning>

### Example: B2B demo booking (100 points)

| Step           | Condition (write this kind of detail)                                     | Points |
| -------------- | ------------------------------------------------------------------------- | ------ |
| Engaged        | Visitor asked a real product question, not just “hi”.                     | 10     |
| Use case       | They described a job-to-be-done (inbound WhatsApp, hotel bookings, etc.). | 15     |
| Company / role | Named a company or decision role (owner, GM, marketing).                  | 15     |
| Budget         | Mentioned a budget range, package, or “we already pay X”.                 | 20     |
| Timeline       | Wants to start within 90 days, or has a date.                             | 15     |
| Contact        | Shared email **or** phone **or** WhatsApp number.                         | 15     |
| Booking intent | Asked to book a demo / meeting / call.                                    | 10     |

**Score 70** on this funnel usually means “talked business + some buying signal.” **Score 90+** usually means “ready to close / book.”

### Writing conditions that actually fire

Bad: `User is interested.`\
Good: `The visitor named a monthly budget in money (USD, EUR, EGP, SAR) or compared Convocore to a competitor they currently pay.`

Bad: `Has contact info.`\
Good: `The visitor typed an email address, a mobile number (7+ digits), or a WhatsApp number in the chat — not the agent offering a form.`

The evaluator looks at roughly the **last 20 messages**. Put the important facts in the conversation; don’t hide them only in a tool result the model never said out loud.

### AI Assist

Click **AI** next to Enable scoring.

* **Empty steps** → generates 5–10 steps from the system prompt (+ optional notes).
* **Existing steps** → **Refine** mode (e.g. “weight budget higher”, “add decision-maker”).

Always review names, conditions, and the 100-point total before you keep the result.

### How scoring is applied

* Chat / WhatsApp / social: after **each AI reply** (user-only messages do not evaluate).
* Voice / phone: **once when the call ends**.
* Matched steps **accumulate**. A later turn can add points; it does not normally “un-match” a step that already scored.
* Extracted fields (name, email, phone, custom keys) are stored on the conversation as funnel data and can appear in the email.

***

## Conditional email alerts (the “email funnel”)

This is the part people mean by **email funnel**: not a drip to the customer, but **rules that email your team**.

Each rule is independent:

* Its own **name**
* Its own **trigger** (score threshold **or** required steps)
* Its own **recipients** (only those people get this email)
* Its own **chat tag**
* Optional **“Phone or email is enough”** (on by default)

Click **Rule** to add more. Rules are **not** a workspace blast. Omar’s rule never emails Abdelrahman unless you put Abdelrahman on that rule (or on a tag-routing share).

<Warning>
  **First matching enabled rule wins.** The runtime walks rules top-to-bottom, sends **one** email, then **locks the conversation**. Later rules do not also fire. Put the most specific / hottest rule first if you use more than one.
</Warning>

```mermaid theme={null}
flowchart LR
  Q[Score + matched steps + contact] --> R1{Rule 1 Hot lead?}
  R1 -->|Match| S[Send once + tag + lock]
  R1 -->|No| R2{Rule 2 Qualified?}
  R2 -->|Match| S
  R2 -->|No| W[Wait for next evaluation]
```

### Trigger types (dashboard)

<AccordionGroup>
  <Accordion title="If score ≥ threshold">
    Fires when `leadScore` is at least the number you set (default seed is **70**).

    **With “Phone or email is enough” on (default):** the rule can also qualify as soon as the lead is **reachable** (phone **or** email **or** WhatsApp), even if the score is still below the threshold. Sending still waits until that contact exists.

    **With the toggle off:** only the numeric threshold counts. Email can go out without a phone/email if you turned the toggle off.
  </Accordion>

  <Accordion title="If steps completed">
    Fires only when **all** selected steps are matched — score can be anything. Use this for “must have budget **and** timeline” regardless of other points.
  </Accordion>
</AccordionGroup>

### Recipients

* Search workspace member emails or type a custom address.
* Empty recipients **and** no tag-routing share with emails → that rule cannot send (builder warns).
* If you add several addresses on one rule, they receive the **same** copy (To / CC split is handled internally).

### Chat tag

When the rule fires, the conversation is tagged.

* Leave blank → tag is a slug of the **rule name** (`Omar Alert` → `omar_alert`).
* Or set an explicit tag: `egypt_rest`, `hot_lead`, `omar_alert`.
* Tags are lowercase `a-z`, `0-9`, underscores.

Use tags in the [Conversations tab](/features/conversations-tab) filter so each closer only sees “their” chats.

### Phone or email is enough

Default **on**. Meaning:

* **Any one** reachable channel qualifies as contact: `userEmail`, `userPhone`, WhatsApp number, or the same fields inside captured/extracted variables.
* Never requires email **and** phone.
* If the score/steps already matched but there is still no way to reach the lead, the email is **held** and retried on later turns.

Turn it **off** only if you want alerts on conversation quality even when the visitor never left a number.

### One email per conversation (hard lock)

Once any funnel email succeeds for a convo:

* `funnelNotificationSent` is set
* The rule id is recorded
* **No second funnel email**, even if the score later jumps from 70 → 100 or another rule would match

Design rules knowing you get **one shot**. If you need both “SDR ping” and “AE ping”, use **tag routing** on that one email, or a different product (campaigns, CRM webhooks) — not a second funnel send.

***

## Tag routing (percent splits)

**Tag routing is not AI.** After a rule has tagged the chat, you can split volume across inboxes.

Example used in production-style setups:

1. AI rule tags the chat `egypt_rest` when it qualifies.
2. Tag routing: tag `egypt_rest` → **50%** Omar (`omar_alert`) / leftover **50%** Abdelrahman (`abdelrahman_alert`).
3. Emails go to the **share’s** recipients, not the original rule list (rule recipients are ignored when a matching split exists).
4. The conversation also gets the **share tag**, so Omar filters `omar_alert` and never sees Abdelrahman’s half.

```mermaid theme={null}
flowchart TD
  A[Rule fires<br/>tag: egypt_rest] --> B[Stable hash of conversation id]
  B --> C{roll 0–99}
  C -->|0–49| D[Omar 50%<br/>email omar@...<br/>extra tag omar_alert]
  C -->|50–99 leftover| E[Abdelrahman rest<br/>email abdelrahman@...<br/>extra tag abdelrahman_alert]
```

The split is **stable per conversation** (hash of convo / user id). Refreshing the page or a second evaluation does not re-roll to the other person. Leftover percent after listed shares always goes to the **last** share (the UI labels it **rest**).

<Steps>
  <Step title="Set the AI rule tag">
    On the email rule, Chat tag = `egypt_rest` (must match the split’s tag).
  </Step>

  <Step title="Add a split">
    Under **Tag routing**, click **Split**. Tag to split = `egypt_rest`.
  </Step>

  <Step title="Configure shares">
    Share 1: `50`, share tag `omar_alert`, Omar’s email.\
    Share 2: leftover / `50`, share tag `abdelrahman_alert`, Abdelrahman’s email.\
    Percents should add to 100; if they don’t, leftover still goes to the last share.
  </Step>
</Steps>

<Tip>
  You can 70/30, 40/40/20, or 100% to one person as a manual override. Click **Share** to add slices.
</Tip>

***

## Worked examples

### Example A — Solo founder, simple ping

**Goal:** Email me when someone is a real lead and I can call them back.

1. Enable scoring. AI Assist → generate from your prompt. Keep 6–8 steps totaling 100.
2. One rule: **If score ≥ 70**, recipients = your email, tag `hot_lead`.
3. Leave **Phone or email is enough** on.
4. Test in the agent tester: mention budget + drop a phone number. You should get one email with score, matched steps, and a conversation link.

### Example B — Two closers, fair split

**Goal:** Restaurant leads in Egypt go 50/50 to Omar and Abdelrahman.

| Piece       | Value                                                                                     |
| ----------- | ----------------------------------------------------------------------------------------- |
| Steps       | Intent, party size / venue, date, budget, contact (100 pts)                               |
| Rule 1      | Score ≥ 60, tag `egypt_rest`, recipients can be empty **if** the split has emails         |
| Tag routing | `egypt_rest` → 50% `omar@…` + tag `omar_alert` / rest `abdel@…` + tag `abdelrahman_alert` |

Omar’s dashboard filter: tag `omar_alert`. He should never receive Abdelrahman’s emails.

### Example C — Two rules, hottest first

**Goal:** Score 90+ goes to the founder; everyone else at 60+ goes to SDR.

1. **Rule 1 (top):** If score ≥ 90, recipients = founder, tag `founder_alert`.
2. **Rule 2:** If score ≥ 60, recipients = sdr@, tag `sdr_queue`.

A 95-point lead matches rule 1, emails the founder, **locks**. SDR does **not** also get mail. A 65-point lead skips rule 1, matches rule 2.

### Example D — Steps, not score

**Goal:** Only email when **Budget** and **Timeline** are both matched, even if total score is 40.

Rule type **If steps completed** → select those two steps. Recipients = sales\@. Contact toggle on so you can follow up.

### Example E — Agency client, white-label mail

1. Assign the agent to a **client org**.
2. Complete agency [theme](/whitelabeling/agency/theme), [custom domain](/whitelabeling/agency/custom-domain), [email domain](/whitelabeling/agency/email).
3. Funnel emails use agency logo, colors, sender, and conversation links on the client domain.

***

## What the notification email contains

<CardGroup cols={2}>
  <Card title="Lead" icon="user">
    Name (if known), score / 100, agent name, how we can reach them.
  </Card>

  <Card title="Why they qualified" icon="list-check">
    Matched steps with points, extracted fields, short AI summary of the chat.
  </Card>

  <Card title="Open the chat" icon="link">
    Deep link into the conversation. Agency custom domain when configured.
  </Card>

  <Card title="Voice" icon="phone">
    Recording link when the conversation was a call and a recording exists.
  </Card>
</CardGroup>

One send per conversation. Opening the link does not send another email.

***

## Where scores and tags show up

After evaluation, the conversation record holds (among other fields):

* `leadScore` — 0–100
* `funnelStepsMatched` — step ids
* `funnelExtractedData` — facts the model pulled
* `funnelSummary` — short summary used in the email
* `funnelNotificationSent` — lock flag
* Conversation **tags** — rule tag + optional share tag

In the dashboard, use the [Conversations tab](/features/conversations-tab) **tag filter** (`omar_alert`, `egypt_rest`, …) to slice the inbox. Export / API (`PATCH` agent `funnelConfig`, leads endpoints) expose the same fields for CRM sync.

***

## Prompt integration

When the funnel is on, qualification step **names and conditions** are injected into the agent instructions so the model knows what to gather **naturally**.

Do this in the system prompt:

* Ask one qualifying question at a time.
* Prefer helping over interrogation.
* Collect contact when the visitor is ready (“What’s the best WhatsApp to send the quote?”).

Do not:

* Dump all seven BANT questions in the first message.
* Instruct the model to invent a budget the user never said — the evaluator will still try to score from the transcript.

***

## Whitelabel branding

Client-assigned agents send funnel mail with **agency** branding automatically. Workspace-only agents use **Convocore** defaults.

<CardGroup cols={2}>
  <Card title="Client agent" icon="building">
    Agency logo, primary color, custom domain on the convo link, agency From address when email domain is verified.
  </Card>

  <Card title="Workspace agent" icon="circle">
    Convocore logo, convocore.ai links, default sender.
  </Card>
</CardGroup>

Missing pieces fall back per component (logo vs domain vs From). Setup: [What is an Agency](/whitelabeling/agency/what-is-an-agency) → [Theme](/whitelabeling/agency/theme) → [Custom domain](/whitelabeling/agency/custom-domain) → [Email](/whitelabeling/agency/email) → assign the agent on the client.

### Testing branded mail

<Steps>
  <Step title="Low threshold">
    Temporarily set score ≥ 20 so a short test chat can fire.
  </Step>

  <Step title="Add yourself">
    Put your inbox on the rule (or on the tag-routing share you expect to win).
  </Step>

  <Step title="Talk like a lead">
    Mention qualifying facts and leave a phone **or** email.
  </Step>

  <Step title="Check header / From / link">
    Logo, brand color, sender domain, conversation URL host.
  </Step>
</Steps>

Raise the threshold again before going live.

***

## Best practices

<AccordionGroup>
  <Accordion title="Steps">
    5–8 steps. Progress from engagement → commercial facts → contact. Make conditions observable in text. Re-run AI Assist after you change the business prompt.
  </Accordion>

  <Accordion title="Thresholds">
    40–60 engaged · 60–75 qualified · 75–90 hot · 90–100 ready. Start higher if your inbox is noisy; lower if sales complains they never get mail.
  </Accordion>

  <Accordion title="Rules vs splits">
    Use **multiple rules** for different *meanings* (hot vs nurture, market A vs B). Use **tag routing** for different *people* on the same meaning. Don’t clone the same threshold five times just to fan out — that’s what splits are for.
  </Accordion>

  <Accordion title="Contact">
    Keep “Phone or email is enough” on for sales follow-up. Capture WhatsApp on WhatsApp channel automatically when the user is messaging from there.
  </Accordion>

  <Accordion title="Agencies">
    Test one client agent end-to-end before rollout. Keep logo + From domain consistent with the client dashboard.
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="No email arrived">
    * Funnel enabled and agent **saved**
    * Workspace has Lead funnel / Pro
    * Enabled rule has recipients **or** a tag split with emails on the chosen share
    * Score/steps actually matched (read funnel debug lines in the tester)
    * Contact toggle on but no phone/email/WhatsApp yet
    * Another rule already fired and **locked** the convo
    * Check spam; agency From must be a verified domain
  </Accordion>

  <Accordion title="Email went to the wrong person">
    First matching **rule** wins. Then tag routing picks a **share**. Confirm rule order, the rule’s chat tag equals the split tag, and percents (leftover → last share).
  </Accordion>

  <Accordion title="I wanted two emails for one chat">
    Not supported. Funnel is one notify per conversation. Split recipients with CC on one rule, or tag routing, or a webhook/CRM.
  </Accordion>

  <Accordion title="Score looks wrong">
    Conditions too vague, or the fact only lived in a tool JSON the user never said. Tighten conditions; ask the agent to confirm facts in chat. Exclusive groups exist at API level for mutually exclusive steps; the dashboard step editor is name / condition / points.
  </Accordion>

  <Accordion title="Branding / link is convocore.ai">
    Agent not on a client org, or custom domain not verified. See [Custom domain](/whitelabeling/agency/custom-domain). Re-assign the agent if it was recently moved.
  </Accordion>

  <Accordion title="Plan lock in the builder">
    Upgrade to Pro or attach the **Lead funnel** add-on in [Billing](/Pricing/billing).
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Is this email marketing to the lead?">
    No. The lead does not get a funnel sequence. Your team gets a qualification alert.
  </Accordion>

  <Accordion title="Does Gmail channel integration use this?">
    No. [Gmail](/integration/google/email) is the agent **reading/replying** to a mailbox. Funnel mail is a separate notify to sales.
  </Accordion>

  <Accordion title="Can I change steps later?">
    Yes. New evaluations use the new steps. Already-sent convos stay locked.
  </Accordion>

  <Accordion title="Voice vs chat?">
    Same steps and rules. Voice evaluates once at hangup; chat evaluates incrementally.
  </Accordion>

  <Accordion title="API / clone?">
    `funnelConfig` is on the agent (`notificationRules`, `tagRouting`, `steps`). [Clone](/api-reference/v3/agents/clone) and template import **do not** copy partner recipients unless you opt in — so you don’t leak another workspace’s funnel emails.
  </Accordion>
</AccordionGroup>