# Agent labels

> Let your agent sort its leads with your own labels, on top of their stage: what labels change, how to set them, notifications, follow-ups and the API.

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

Labels are your own categories for your leads: the project, the budget, the
reason for a no. The agent can put them by itself, from one sentence per
label. They come on top of the lead's stage and change nothing in the
conversation.

## What labels are, and what they are not

Every lead has a stage, such as **In conversation** or **Qualified**. The
agent sets it from its prompt, and the stage decides what the agent does
next. See [Stage or label?](/dashboard/leads/#stage-or-label).

Labels are something else:

- they sort your leads: the filters and the **Labels** column of **Leads**, and the export;
- they can send you a notification, limit some follow-ups, and reach your tools through the API;
- they change nothing in the conversation: the agent does not stop, does not qualify the lead and does not offer slots because of a label.

To change when a lead is qualified, edit the agent's prompt, not its labels.
See [Deciding when a lead is qualified](/dashboard/prompt/#deciding-when-a-lead-is-qualified).

## Set up the agent's labels

1. Open **Agents**, click your agent, open the **Settings** tab, then **Labels**.
2. Click **Add a label**, or next to **Start from a template**, pick **Lead profile**, **Reasons for a no** or **Project timeline**.
3. For each label, write its **Name**, then one sentence for the AI under **When to pose it**.
4. Under **How many per lead**, choose **One main label** or **Several, 3 at most**.
5. Turn on **Pose the labels**.
6. Click **Save**.

An agent holds up to 12 labels. A name holds up to 40 characters, and a
sentence up to 300.

A few minutes after each message from the lead, the agent updates its labels.
When you switch them on, it reads once the conversations where the lead
already wrote. **How labels work**, at the top of the section, shows the
difference with the stage in three steps.

## Tell the AI when to put a label

Under **Posed when**, keep **The AI reads it in the conversation**. Then write,
under **When to pose it**, one sentence about what the lead says or shows:

| Name | When to pose it |
|---|---|
| Budget confirmed | The lead gives a budget that fits the offer. |
| Company | The lead buys for their company or team. |
| Not the right time | The lead puts their project off until later. |

One label, one sentence, about the lead. The AI only picks among your labels:
it never invents one.

When you change a label or its sentence, the agent reads its leads again,
within its budget for the day.

## Labels set by a fact, to keep your CRM's names

Under **Posed when**, three choices are not read by the AI:

| Choice | The label is put when |
|---|---|
| **The first message went out** | The agent's first message has left. |
| **A meeting is booked** | A meeting is booked with the lead. |
| **The lead stopped answering** | The lead has not written for the number of days set under **Days without a message from the lead**, from 1 to 60. |

The lead's stage already says these things. These choices are only useful to
find the stages of your CRM under their own names, for example the
"Contacted" or "No response" your CRM expects. They are updated every hour,
and each fact puts one label only.

When a fact holds, its label wins over the AI's choice. With
**One main label**, **The lead stopped answering** only replaces the label of
the first message, or no label, and only when the lead said nothing more than
a thanks, an "ok", an emoji or an automatic reply.

## One main label, or several

Under **How many per lead**:

| Choice | What each lead carries |
|---|---|
| **One main label** | A single main label, with markers beside it. Each label has a role, under **The label's role**: **Main**, or **Marker, beside the main one**. |
| **Several, 3 at most** | Every label that applies to the lead, up to 3. |

With **One main label**, a new main label takes the place of the previous
one: this fits steps that follow each other, like the stages of a CRM.
Markers add a detail beside it, up to 3.

## Where you find the labels

- On the lead's card, under **Labels**. A small sparkle marks a label the agent put.
- In **Leads**: the **Labels** column, and **Labels** in **Filter**.
- In the export, in the **Labels** column.
- In the API, in the `tags` field of each lead.

The labels the agent puts and the labels a person puts are in the same list.

## Be told when the agent puts a label

1. Open **Agents**, click your agent, open the **Settings** tab, then **Hand-off & alerts**.
2. Under **And when the agent puts the label**, click the labels you want to hear about.
3. Turn on at least one channel: **Via email**, **On WhatsApp** or **Via webhook (advanced)**.

The message leaves on the channels that are on, and only for a lead active in
the last 24 hours. While the agent's labels are off, nothing leaves. See
[Notifications & alerts](/dashboard/notifications/).

## Follow up only some labels

1. Open **Agents**, click your agent, open the **Prompt** tab, then **Follow-ups**.
2. Click a situation: **Never replied** or **Stopped replying**.
3. Under **Who to follow up**, click one or more labels, up to 6. **All these leads** goes back to every lead.

That situation then follows up only the leads that carry one of these labels,
put by the agent or by hand. See [Automatic follow-ups](/dashboard/follow-ups/).

## Labels in the API and the webhook

- [`GET /leads`](/api-reference/operations/listleads/) returns the labels in `tags`, and [`PATCH /leads/{id}`](/api-reference/operations/updatelead/) writes them. Taking off or adding one of the agent's labels this way counts as a change by hand.
- The webhook `contact.label_added` tells your tools when the agent puts a label chosen in **Hand-off & alerts**. It goes to the webhook URLs of that section.

See [API: leads](/developers/guides/leads/) and
[Signed webhooks](/developers/webhooks/).

## You have the last word: hand the labels back

When a person takes off one of the agent's labels on a lead, or adds one of
its labels by hand, the agent no longer touches that lead's labels. A label of
your own, such as **VIP**, changes nothing for the agent.

To give them back:

- one lead: open its card in **Leads**, click **Hand back to the agent**, read what will change, then click **Hand back**;
- several leads: tick them in **Leads**, click **More actions**, then **Hand back to the agent**.

To find these leads, click **Filter** in **Leads**, then
**Labels taken over**.

## Rename or delete a label

- When you rename a label, the leads that carry the old name get the new one within the hour. The leads whose labels a person took over keep the old name.
- When a name is already on leads, put by hand, the section counts them before you save: the agent carries those labels as its own.
- When you delete a label that a follow-up is limited to, that follow-up pauses until you pick another label, or **All these leads**.

## A label named like a stage

A label called "Qualified", "Not interested" or "Contacted" is still only a
label. It does not set the stage: the agent goes on qualifying the lead, and
the lead stays out of the **Qualified** view of **Leads**.

When a label looks like a stage, the section warns you. Keep such a name only
to find a stage of your CRM. To qualify a lead, change its stage.

## If you do not see Labels in the settings

Every WhatsApp agent has a **Labels** section. A group agent and an Instagram
agent have none.

Changing the labels needs the **Edit agents and their prompts** permission.

## Related

- [Leads & CRM](/dashboard/leads/)
- [Notifications & alerts](/dashboard/notifications/)
- [Automatic follow-ups](/dashboard/follow-ups/)
- [Signed webhooks](/developers/webhooks/)
