# Leads & CRM

> Follow every contact your agents talk to: stages, labels, owners, notes, next actions, an Excel or CSV export and a trash kept for 30 days.

Source: https://docs.whatsetter.com/dashboard/leads/

**Leads** lists every person your agents talk to, with where they stand, who
handles them and what comes next. The agent moves leads through the stages.
You correct, assign, annotate, export and clean.

## What the Leads page shows

Open **Leads** in the **Run** group of the menu. Each row is one person with
one agent: someone who talks to two of your agents has two rows. For each lead
the table shows the name and the number, the **Stage**, the **Last message**
and, depending on your team, the **Owner**, the **Agent** and the
**Next action**.

- Click a row to open the lead in a panel on the right.
- Hover a row to reach its shortcuts: the conversation, and a menu with
  **Open record**, **Reply in Conversations**, **Copy phone** and
  **Delete…**.
- At the bottom, the page says how many leads are shown, and a button loads
  the next ones.

People who wrote in private to a number that follows your WhatsApp groups are
not listed here: they are in [Conversations](/dashboard/conversations/). A
member limited to their own leads sees their leads and the ones nobody owns.

## Stage or label?

In **Leads**, a lead carries two different things: one stage, and labels.
Only the stage changes what the agent does.

| | The stage | The labels |
|---|---|---|
| Who sets it | The agent, on its own, from what its prompt says. A person can change it by hand. | A person, on the lead's card or on several leads at once. Or the agent, from the rules you write in its settings, under **Labels**. |
| What it changes | What the agent does next. **Qualified**: it stops qualifying and goes for the meeting. **Not interested**: it no longer writes. **Cold**: it stops insisting. **Stopped**: it no longer writes. | Nothing in the conversation. Labels sort your leads: filters, the **Labels** column, the export, notifications, follow-ups and the API. |
| Where you change it | On the lead's card, with **Change the stage**. To change when the agent qualifies, edit its prompt. | On the lead's card, under **Labels**, or with **Label** on a selection. |

A label named like a stage, for example "Qualified", is still only a label. It
does not make the lead qualified: the agent goes on qualifying it, and the
lead stays out of the **Qualified** view. To qualify a lead, change its stage.
The agent's **Labels** settings warn you when a label looks like a stage.

To change when the agent qualifies a lead, see
[Deciding when a lead is qualified](/dashboard/prompt/#deciding-when-a-lead-is-qualified).
The labels the agent can set are on [Agent labels](/dashboard/labels/).

## The four views: All, To handle, Qualified, Meetings booked

Above the table in **Leads**, four views each show a count:

| View | What it contains |
|---|---|
| **All** | Every lead. |
| **To handle** | The leads whose last message got no answer, neither from the AI nor from a person, for more than 30 minutes, over the last 48 hours, or whose planned next action is overdue. It is the same rule as the **To do** view in **Conversations**. |
| **Qualified** | The leads in the stage **Qualified**: qualified, no meeting yet. |
| **Meetings booked** | The leads whose meeting is booked and not yet marked as held, cancelled or missed. |

The counts follow your filters and your search. They do not move when you
click a view: each number is the number of rows that view opens on. Counts
are exact up to 5,000. Beyond that, the view shows 5,000 with a plus sign.

## The stages of a lead

In **Leads**, the **Stage** column says where each lead stands. A lead is
always in exactly one stage.

| Stage | What it means |
|---|---|
| **Contacted** | The exchange has not started: no reply is counted yet. A person who wrote to you first is here until your agent has answered. |
| **In conversation** | The lead has replied. The agent, or you, is talking with them. |
| **Not contacted yet** | The lead's first message was held back and never left. It is not a task: the lead is not listed in **To handle**. |
| **Qualified** | The agent, or someone on your team, marked the lead as qualified. No meeting yet. |
| **Meeting booked** | A meeting is on the calendar, or has taken place. |
| **Not interested** | The agent, or someone on your team, marked the lead as not interested. |
| **Cold** | The agent wrote first and the lead has not answered. |
| **Stopped** | The conversation was stopped. The AI no longer writes. |

A hand icon next to the stage means someone took the conversation over.

## What moves a lead from one stage to the next

On the **Leads** page, stages change by themselves as the conversation goes:

- a lead your agent writes to first starts in **Cold**. At the lead's first
  reply, it moves to **In conversation**;
- a person who writes to you first starts in **Contacted**, and moves to
  **In conversation** once the agent has answered and the exchange goes on;
- when the agent judges the lead qualified, from what its prompt says, it
  moves to **Qualified** and the date is kept as **Qualified on**. When the agent judges the lead is not
  interested, it moves to **Not interested**;
- when a meeting is booked, the lead shows **Meeting booked**, whatever its
  stage before;
- when the lead asks not to be contacted any more, in any language, it moves
  to **Stopped**, even if it also asks who you are or where you got its
  number. Asking to be reached another way, by phone, by email or on another
  number, is not a stop: the conversation goes on;
- when a closed conversation starts again, the lead goes back to
  **In conversation** and the conversation shows the note "The conversation
  resumes". A lead in **Stopped** never goes back by itself.

You can also change the stage yourself at any time.

## Change the stage by hand

Open a lead in **Leads** and click the stage under **Where it stands**. In
**Conversations**, the same line is in **Details**, under
**Where they stand**. The menu **Change the stage** has five choices and says
what the AI does next:

| Stage | What the AI does |
|---|---|
| **In conversation** | The AI resumes the conversation. |
| **Qualified** | The lead is qualified: the AI stops qualifying. |
| **Not interested** | The AI stops writing to this lead. |
| **Cold** | Marked unanswered: the AI stops insisting. |
| **Stopped** | Conversation stopped: the AI no longer writes. |

To qualify a lead yourself, choose **Qualified**. **Contacted**,
**Not contacted yet** and **Meeting booked** cannot be chosen.

A stage you set by hand holds. A lead you put in **Not interested** or
**Stopped** never goes back to **In conversation** by itself, even if it
writes again. A lead you put in
**Qualified** only leaves it if the person asks to stop or to have their data
erased. Choosing **In conversation**, **Qualified** or **Cold** puts the lead
back in the hands of the AI.

If the AI still handles the lead, a window asks: **Change the stage** (the AI
is told and carries on) or **Change and take over** (the AI stops writing and
the lead is yours). This needs the **Edit leads** permission. A stage cannot
be changed on several leads at once.

Changing the stage by hand acts on one lead. To change when the agent itself
qualifies its leads, edit its prompt: see
[Deciding when a lead is qualified](/dashboard/prompt/#deciding-when-a-lead-is-qualified).

## Search and filter the leads

In **Leads**, type in **Search leads**: a first name, a number or an email.
Click **Filter**, or press F, to narrow the table:

| Group | Questions |
|---|---|
| **Ownership** | **Agent**, with **Agents in service** to keep the live ones, and **Owner**: **Mine**, **Nobody** or a teammate. |
| **Follow-up** | **Stage**, **Next action** (**Overdue**, **Today**, **Upcoming**, **None**), **Meeting**, **Outcome** (**Open**, **Won**, **Lost**), **AI** (**AI answers**, **Taken over**) and **Labels**. |
| **Origin and period** | **Origin**, **Country** and **Period**: a **Date** (**Last activity**, **First contact**, **Qualified on**, **First meeting booked**) and a period, from **Today** to **Last 12 months**. |

Each choice becomes a chip under the toolbar. **Clear all** removes the
filters and the search, and keeps the view. The filters are in the address of
the page: bookmark a filtered view, or send it to a teammate.

## Sort the table

In **Leads**, click the arrows button next to **Filter**:

| Sort | Order |
|---|---|
| **Recent activity first** | By last message, most recent first. This is the default. |
| **Oldest activity first** | By last message, oldest first. |
| **Next action** | By the date of the next action. Only leads that have one. |
| **First contact** | Newest arrivals first. |
| **Recently qualified** | By qualification date. Only qualified leads. |

You can also click a column header to sort: **Next action**,
**Last message**, **First contact** or **Qualified on**. Click again to
reverse the order.

## Choose the columns

On a computer, click **Display** in **Leads**. Under **Columns**, tick what
you want to see: **Stage**, **Next action**, **Owner**, **Agent**,
**Last message**, **Meeting**, **Outcome**, **Labels**, **Origin**, **Country**,
**First contact**, **Qualified on**, **Messages**, **Follow-ups**, **Email**
and **Number**. The lead's name always stays.

Under **Leads per load**, choose 25, 50 or 100. **Reset display** goes back
to the default.

Without a choice of yours, the table shows the stage and the last message,
the owner when your team has several members, the agent when you have several
agents, and the next action once your team uses it. Your columns are kept on
this browser, for each team.

## Open a lead: the panel

Click a row in **Leads**. The lead opens in a panel on the right and the
address of the page now carries it, so you can send it to a teammate. From
top to bottom:

- **Where it stands**: next action, stage, meeting, owner, outcome and the
  **AI** line;
- **Latest messages**: the last 6 messages, a button to show them all, and
  **Open in Conversations**;
- **Notes** and **Labels**;
- **About**: the title, first name and last name when the lead comes from
  an imported list, then the agent, **Comes from**, the first contact, the
  last activity, the qualification date, the number of messages and the
  email;
- **History**: every change made by a person, with who and when, and the
  milestones (first contact, qualified by the AI, first meeting booked).

When the lead comes from an imported list, the top of the panel shows the
full name, for example "Herr Max Mustermann", even when the agent only uses
the last name. This comes from the list's columns and changes nothing in what
the agent writes. **Details** in **Conversations** shows it too.

The up and down arrows move to the previous and the next lead. Esc closes the
panel. The panel does not send messages: click **Reply in Conversations**.

## Plan a next action

In a lead's panel in **Leads**, or in **Details** in **Conversations**, click
**Plan** on the **Next action** line. Choose the date and the time under
**When**, write what to do under **What to do (optional)**, up to 160
characters, then click **Save**. To remove it, open it again and click
**Clear**.

A next action is the date your team sets to get back to a lead. Once the date
has passed, it reads **Overdue**, and the lead enters **To handle** in
**Leads** and **To do** in **Conversations**. The **Next action** filter and
sort list them. This needs the **Edit leads** permission.

## Mark the meeting and the outcome

In a lead's panel in **Leads**, under **Where it stands**:

- **Meeting** shows the state of the meeting: **Offered**, **Booked**,
  **Held**, **Cancelled**, **No-show** or **Expired**. When a meeting is
  booked, click its date and choose under **This meeting**: **Held**,
  **No-show** or **Cancelled**. The booking itself is made in the
  conversation. See [Meetings](/dashboard/bookings/);
- **Outcome** is set by hand: **Open**, **Won**, or one of the reasons under
  **Why lost?** (**Price**, **Bad timing**, **Unqualified**, **Competitor**,
  **Unreachable**, **Other**), which marks the lead **Lost**.

Both need the **Edit leads** permission. Each change is written in the
**History** of the lead.

## Add notes to a lead

In a lead's panel in **Leads**, or in **Details** in **Conversations**, write
under **Notes** and click **Add the note**. On a computer, Cmd+Enter or
Ctrl+Enter saves too. A note holds up to 2,000 characters.

- Each note keeps its author and its time.
- The panel shows the four most recent notes.
- A note is for your team: the lead never sees it.

Writing a note needs the **Edit leads** permission. Your own tools can add
notes through the API. See [API: leads](/developers/guides/leads/).

## Add labels to a lead

In a lead's panel in **Leads**, or in **Details** in **Conversations**, click
**Add a label** under **Labels**. Pick a suggestion (**VIP**,
**Existing client**, **Referral**, **Partner**) or type your own and press
Enter. Click the cross on a label to remove it.

- A label holds up to 40 characters, and a lead up to 20 labels.
- Labels become a filter (**Labels** in **Filter**) and a column of the table.
- To label several leads at once, tick them and click **Label**.

A label changes nothing in the conversation: the agent does not stop, does
not qualify the lead and does not offer a meeting because of a label. Use
labels for what the stage does not say: the project, the budget, the reason
for a no, or the names of your CRM.

Editing labels needs the **Edit leads** permission.

## Labels set by the agent, and handing them back

When the agent's labels are on, the agent sets some labels itself. On the
lead's card, a small sparkle next to a label means the agent set it. See
[Agent labels](/dashboard/labels/).

You have the last word. When you take off one of the agent's labels, or add
one of its labels yourself, the agent stops changing this lead's labels, and
the card says so. A label of your own, such as **VIP**, changes nothing for
the agent.

To give the labels back, click **Hand back to the agent** on the card. The
card first says what will change: click **Hand back** to confirm. For several
leads, tick them, click **More actions**, then **Hand back to the agent**. To
list these leads, click **Filter**, then **Labels taken over**.

**Hand back to the agent** is about labels only. To let the AI answer a lead
again, use **Hand back to the AI** on the **AI** line.

## Assign a lead to someone

In **Leads**, click the **Owner** cell of a row, or the **Owner** line of the
lead's panel. The menu offers **Take it**, your teammates and
**Remove owner**.

- With the **Reply by hand** permission you can take a lead nobody owns, let
  go of one of yours, and hand one of yours to a colleague.
- With the **Assign a lead to someone** permission you can move any lead:
  take a colleague's lead, remove its owner, or give a free lead to someone
  else.
- If two people take the same lead at once, the second one gets a message
  saying that someone took this lead first.

A lead can only go to a member of your team. Taking a lead does not stop the
agent: see [Take over a conversation](/dashboard/human-takeover/).

## Who answers the lead: the AI line

In a lead's panel in **Leads**, the **AI** line under **Where it stands**
says who answers the lead right now:

| What you read | Meaning | Button |
|---|---|---|
| **The AI answers** | The agent is in charge. | **Take over** |
| **Taken over** | Someone answers by hand. The AI does not answer. | **Hand back to the AI** |
| **AI paused** | The agent is off on this lead and nobody took it over. | **Take over** |

In the table, a hand icon next to the stage marks the leads taken over. To
list them, click **Filter**, then **AI**, then **Taken over**. Everything a
takeover changes is on [Take over a conversation](/dashboard/human-takeover/).

## The Follow-ups column

In **Leads**, add the **Follow-ups** column with **Display**. It says where
the automatic follow-ups stand for each lead:

| What you read | Meaning |
|---|---|
| **Scheduled** | A follow-up is planned for later. |
| **Due now** | The planned time of the follow-up has passed. |
| **Sent** | Follow-ups were sent and none is planned. |
| **Done** | The follow-ups are over for this lead. |
| **Active** | Follow-ups were sent, with no date known for the next one. |

The number after the label is the number of follow-ups already sent. A dash
means no follow-up for this lead. See
[Automatic follow-ups](/dashboard/follow-ups/).

## Where a lead came from

In **Leads**, the origin of a lead shows in three places: the **Origin**
column (add it with **Display**), the **Origin** question of **Filter**, and
**Comes from** in the lead's panel. It reads:

- **List**: imported in a [list](/dashboard/lists/);
- **Via API** or **Webhook**: sent by your own tools;
- **Wrote in**: the person wrote to you on their own;
- **Added by hand**;
- the place a [tracked link](/dashboard/tracked-links/) was clicked:
  **Website**, **Email**, **QR code**, **Ads**, **Google search**, **SMS**,
  **Direct link**, **Other link** or the name of a social network.

The word "probable" means the most likely origin, when several places were
clicked in the same window. A dash means the lead was created before origins
were tracked. In the panel, click the origin of a lead that came through a
tracked link to open that link.

## Act on several leads at once

In **Leads**, tick rows, or tick the header box to take the rows on screen. A
bar appears:

- **Select all** and the number of results takes every lead of the view, up
  to 5,000;
- **Assign** gives the leads to a teammate, or removes their owner;
- **Label** adds one label to all of them;
- **Export** opens the export on your selection;
- **More actions**, then **Hand back to the agent**, gives their labels back to the agent, when its labels are on;
- **More actions**, then **Delete…**, sends them to the trash.

The work runs 100 leads at a time, with a progress bar and a **Stop** button.
What is done stays done. At the end, a message counts the leads updated,
skipped and failed. Leads outside what you are allowed to see are skipped.
With every result selected, **Assign** and **Label** ask you to confirm with
**Apply**.

## Export leads to Excel or CSV

In **Leads**, click **Export**. The window **Export leads** asks three
things:

1. **Which leads?** Choose **Your selection** (the ticked rows) or **By criteria**: the same views and the same **Filter** as the page. Changing them here leaves your list as it is.
2. **Columns**: **Like the table**, **All** (everything known about each lead, without the columns that are empty for all of them) or **Choose**.
3. **Format**: **Excel (.xlsx)**, where dates stay dates and every column has its filter, or **CSV (.csv)**, in UTF-8, separated by a comma when the dashboard is in English and by a semicolon in French and Spanish.

The button shows how many leads will be exported. The file is prepared in
your browser, 1,000 leads at a time, with a progress percentage, and **Stop**
cancels it. There is no maximum number of leads. Your columns and your format
are kept on this browser.

## What the export contains

In the window **Export leads** of the **Leads** page, **Choose** lists the
columns by group:

| Group | Columns |
|---|---|
| **Identity** | **Name**, **Number**, **Channel**, **Country**, **Email**. |
| **Follow-up** | **Stage**, **Owner**, **AI**, **Next action**, **Planned action**, **Meeting**, **Meeting date**, **Outcome**, **Lost reason**, **Labels**. |
| **Origin** | **Agent**, **Campaign**, **Origin**, **Tracked link**, **A/B variant**. |
| **Activity** | **First contact**, **Last message**, **Qualified on**, **Meeting booked on**, **Messages**, **AI messages**, **Replied**, **Follow-ups sent**, **Whatsetter ID**. |

**Owner** is offered when your team has several members. The file name
carries your team, the view and the date. The export holds only the leads
you are allowed to see. To export one conversation instead, see
[Conversations](/dashboard/conversations/).

## Delete a lead

In **Leads**, open the menu at the end of a row, or **More actions** in the
lead's panel, and click **Delete…**. The window says what happens:

- the record, the conversation, the notes and the history go to the trash,
  and you can restore everything for 30 days;
- the chat stays on WhatsApp, and a meeting stays in your calendar;
- if the person writes again, they start over as a new contact;
- a box, **Stop the AI answering this number**, also silences the agent for
  that number.

Click **Delete lead**. A message confirms it, with **Undo** for 8 seconds.

To delete several leads, tick them, click **More actions** in the bar, then
**Delete…**. From 10 leads, you type their number to confirm. This needs the
**Delete leads** permission, which owners and admins have by default.

## The trash: restore a deleted lead

In **Leads**, click **More options** (the three dots next to **Export**),
then **Trash**. Each deleted lead shows who deleted it, when, and how many
days it has left.

- A deleted lead stays 30 days in the trash, then it is deleted for good.
- **Restore** puts the lead back with its conversation, its notes and its
  history. If the person wrote again in the meantime, the old history joins
  their current record.
- In the menu of a lead, **Delete permanently** erases it now. **Empty trash**
  erases them all. This cannot be undone.

The trash shows only with the **Delete leads** permission. A member limited
to their own leads sees what they deleted themselves.

## A lead could not be deleted

In **Leads**, a deletion can end with a message instead of the trash:

- "This lead couldn't be deleted: it has far more messages than a normal
  conversation. Contact support." The lead is left untouched on purpose.
  Write to support with the name of the lead;
- a message counting the leads that could not be deleted, after a deletion
  of several leads. The others are in the trash. Try again on the ones left;
- a message saying you are not allowed to delete leads. Ask the owner of the
  team for the **Delete leads** permission. See
  [Team & roles](/dashboard/team/).

## Who can do what on Leads

Opening **Leads**, searching, filtering and exporting need no special
permission. The actions do:

| Action | Permission |
|---|---|
| Change the stage, the outcome, the meeting, the labels, the notes or the next action | **Edit leads** |
| Take a free lead, let go of yours, hand yours to a colleague, take over | **Reply by hand** |
| Move any lead from one person to another | **Assign a lead to someone** |
| Delete leads, open the trash, restore | **Delete leads** |

A member whose leads are set to **Their own and the unclaimed** sees, edits
and exports only those leads. See [Team & roles](/dashboard/team/).

## From your CRM

The API reads and writes the same fields as the **Leads** page: the stage
(`status`), the labels (`tags`), the owner, the next action, the outcome and
the notes. It can also stop the agent on a lead and start it again. Only
`status` changes what the agent does: `tags` never does. Events such as a
qualified lead, or a label the agent puts, can reach your tools through
webhooks.

- [API: leads](/developers/guides/leads/)
- [Webhooks](/developers/webhooks/)

Leads created through the API appear in **Leads** with the origin
**Via API**.

## Related

- [Conversations](/dashboard/conversations/)
- [Take over a conversation](/dashboard/human-takeover/)
- [Agent labels](/dashboard/labels/)
- [Team & roles](/dashboard/team/)
