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

# Collect leads with your AI agent

> Capture a visitor's contact details as a lead, either through a form in the chat or conversationally

The Chatbase Collect Leads Action captures a visitor's name, email, phone number and other details as a lead during a conversation with your AI agent. It's for teams that want to turn website and messaging visitors into contactable leads and send them to a CRM, a webhook or an inbox. The AI agent can show a lead form in the chat or ask for the details conversationally, and the Action works on every channel.

Each AI agent can have one Collect Leads Action. Its name is fixed, so there's no **Action Name** field to fill in. For several different collections on one AI agent, use [Collect Data](https://chatbase.co/docs/user-guides/chatbot/actions/collect-data.md), which allows more than one Action.

> [card] Best for:
>
> Turning an interested visitor into a contactable lead before they leave, and routing that lead straight to your CRM or inbox.

**Common Use Cases:**

* Capturing details when a visitor asks about pricing or a demo
* Following up with someone whose question needs a human answer
* Qualifying interest with custom fields like company name or budget
* Seeing which ad or email campaign each lead came from, with [UTM hidden fields](#utm-hidden-fields)

## How to create the Action

**1. Navigate to Actions**

Go to your [Chatbase dashboard](https://www.chatbase.co/dashboard/) and select your AI agent. Click **Build > Actions** in the left sidebar.

**2. Create the Action**

Click **Create Action**, then select **Collect Leads**.

**3. Configure General Settings**

**When to use:** Specify when the form should show during the conversation. You can also add other instructions related to the Action, such as *Show only the leads form without listing the form's fields*. Previewing the Action will help you spot the edits you may want to make.

To restrict the Action to [Procedure](https://chatbase.co/docs/user-guides/chatbot/procedures/procedures-overview.md) steps only, turn on [**Only use in Procedures**](https://chatbase.co/docs/user-guides/chatbot/actions/actions-overview.md#only-use-in-procedures). When it's on, the **When to use** field is hidden, because the AI agent no longer decides when to call the Action.

![The When to use field for the Collect Leads Action](https://mintcdn.com/chatbase/EhvCUQ4ZmSlhciUK/user-guides/chatbot/images/actions/actions-26.1.png?fit=max\&auto=format\&n=EhvCUQ4ZmSlhciUK\&q=85\&s=40e9ffd2f83d66e37b36c57f24976f72)

**4. Define your fields**

In the **Fields** section, choose how the AI agent collects details and which fields it asks for. See [Fields](#fields) below.

**5. Set your destinations**

In **Destinations**, choose where collected leads should be sent. See [Destinations](#destinations) below. This step is optional.

**6. Choose Channels**

This Action is compatible with every channel. Toggle it on or off for each configured channel. See [Channels](https://chatbase.co/docs/user-guides/chatbot/actions/actions-overview.md#channels) for what configured, unconfigured, and incompatible mean.

**7. Enable and Test**

Preview your settings in the AI agent on the Action page, then click **Enable**.

## Fields

In the **Fields** section, you first choose how the AI agent collects the lead's details:

| Mode | What it does |
| - | - |
| **Form** | The AI agent displays a form in the chat on the Chat Bubble, Help Page and Center Stage. On channels that can't show a form, it asks for the same fields in chat. Up to three fields, no custom fields. |
| **Conversational** | The AI agent asks for the details naturally in chat, one message at a time, and saves the lead once it has everything required. Supports custom fields. |

> [!NOTE]
>
> Whichever mode you pick, either **E-mail** or **Phone Number** must be enabled and set as required. This guarantees every saved lead has a way to be contacted, and the Action cannot be saved without it.

### Form mode

You can enable or disable any of the three available fields in the form (**Name**, **E-mail**, and **Phone Number**) and set any or all of them as required.

> [!NOTE]
>
> A lead form holds a maximum of three fields, and custom fields are not available in this mode.

**On channels without a form.** WhatsApp, email, Messenger, Instagram, Slack, phone, the API and the SDKs can't display a form. On those channels, the AI agent asks for the enabled form fields in chat, respecting which ones are required. Once it has them, it saves the lead and adds your **Success Message** to its reply.

### Conversational mode

In conversational mode, the AI agent gathers the lead's details in chat on every channel. The fields table has two parts:

* **Identity fields**: Name, E-mail, and Phone Number. Each can be toggled on or off and marked as required. Their types are fixed, and you can add a description to guide the AI agent on how to ask for them.
* **Custom fields**: any extra details you want collected, such as company name or budget. Each custom field has a name, a type (text, number, email, date, or boolean), a description that tells the AI agent what to ask for, and a **Required** checkbox. You can add up to 20 custom fields. There's no choice-list (dropdown) type: to offer fixed options, list them in the field's description.

The AI agent asks for all required fields before saving the lead; optional fields are saved when the customer provides them but never block the save.

![Conversational fields editor with identity and custom fields](https://mintcdn.com/chatbase/EhvCUQ4ZmSlhciUK/user-guides/chatbot/images/actions/collect-leads-conversational-fields.png?fit=max\&auto=format\&n=EhvCUQ4ZmSlhciUK\&q=85\&s=82b81513f67e42d77b753b46d986d8e1)

The AI agent never invents values: it only saves what the customer has explicitly provided, and if the customer shares more details later in the conversation, the lead is updated without losing what was already collected.

Collected leads appear under **Activity > Leads**, where each custom field gets its own column. Custom fields are also included in CSV and PDF exports and in the [`leads.submit` webhook](https://chatbase.co/docs/developer-guides/webhooks).

#### Example: a conversational lead

Example configuration: **Name** and **E-mail** on, with **E-mail** required, plus a custom text field `company` described as "The company the visitor works for".

> **Visitor:** Can I get a demo for my team?
>
> **AI agent:** Happy to set that up. What's the best email to reach you?
>
> **Visitor:** [jane@example.com](mailto:jane@example.com). I'm Jane Doe from Acme.
>
> **AI agent:** Thanks, Jane. I've passed your details to our team, and someone will email you to schedule the demo.

The lead is saved with name Jane Doe, email [jane@example.com](mailto:jane@example.com) and company Acme, and appears under **Activity > Leads**.

### UTM hidden fields

Turn on **UTM hidden fields** at the bottom of the **Fields** section to save which campaign brought each lead in. It works in both form and conversational mode, and visitors never see an extra field.

![The UTM hidden fields switch in the Fields section](https://mintcdn.com/chatbase/ImI0KQFIvwCjIoQX/user-guides/chatbot/images/actions/collect-leads-utm-hidden-fields.png?fit=max\&auto=format\&n=ImI0KQFIvwCjIoQX\&q=85\&s=5f6d0dc7ee2ac9053cf8566eb282274b)

When a lead is submitted, Chatbase saves the visitor's `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, and `utm_content` with it. To provide them, pass the UTM parameters as `user_metadata` when you identify the visitor. Steps 1 and 2 of [UTM tracking](https://chatbase.co/docs/developer-guides/website-integration/utm-tracking.md#step-1-save-the-utms) show how.

* A UTM the visitor doesn't have is left out. If a visitor has none, the lead is saved without them.
* Only these five UTM parameters are saved. Other values in `user_metadata` are ignored.
* Each UTM appears as a column under **Activity > Leads**, and is included in CSV and PDF exports and in the [`leads.submit` webhook](https://chatbase.co/docs/developer-guides/webhooks) as `customFields`.

![The Leads page with utm\_medium, utm\_source, and utm\_campaign columns](https://mintcdn.com/chatbase/ImI0KQFIvwCjIoQX/user-guides/chatbot/images/actions/collect-leads-utm-columns.png?fit=max\&auto=format\&n=ImI0KQFIvwCjIoQX\&q=85\&s=f04200001eed9f8ac215ef4965207bf2)

### Messages

The **Messages** section appears only in Form mode.

**Success Message:** The message displayed once the customer submits the form. On channels that can't show a form, it's added to the AI agent's reply once the details are collected.

**Dismiss Message:** The message shown once the customer dismisses the form by clicking the **X** button. This only applies to form mode, since conversational mode has no form to dismiss.

![The Success and Dismiss message fields](https://mintcdn.com/chatbase/EhvCUQ4ZmSlhciUK/user-guides/chatbot/images/actions/actions-29.1.png?fit=max\&auto=format\&n=EhvCUQ4ZmSlhciUK\&q=85\&s=9d99ec8fe5d84d17bcaf268f1874c43c)

## Destinations

Use **Destinations** to specify where collected lead information should be sent. You can skip this step if you don't want to send leads anywhere external.

### Webhooks

Add one or more webhook endpoints to receive each collected lead as a `POST` request.

**1. Expand Destinations**

Open the **Destinations** section of the Action.

**2. Enter the endpoint URL**

Add the URL that should receive the lead.

**3. Create the webhook**

Click **Create webhook**.

### Email notifications

Enable **Email notification** to receive an email every time a lead is collected through this Action. You can add one or more email addresses, and each successful lead submission triggers an email containing the collected lead information.

> [!NOTE]
>
> This is different from the **Daily leads** email notification available under **Settings → Notifications**. Email notifications configured here are sent **immediately for each collected lead**, whereas the daily leads notification sends a summary of leads collected throughout the day.

> [!WARNING]
>
> Neither email is available on HIPAA accounts. The Action's **Email notification** switch is locked off with "Lead email notifications are not available for HIPAA accounts.", and the daily email is locked off with "Daily conversations and leads are not available for HIPAA accounts." Use a webhook instead.

## Where leads are saved

Every lead is saved to **Activity > Leads** and attached to its conversation, then sent to your webhooks and email notifications. A lead doesn't create or update a [Contact](https://chatbase.co/docs/user-guides/chatbot/contacts/contacts-overview.md).

Repeat submissions are partly merged:

* If a lead for the same AI agent has exactly the same name, email and phone number, it's updated instead of duplicated. Any difference, including a missing value, creates a new lead.
* On non-HIPAA accounts, a lead from the same WhatsApp user, or else with the same phone number, is updated in place and its date refreshed.

> [!TIP]
>
> Test the Action by having a conversation that should trigger it, and confirm the lead appears under **Activity > Leads** with every field populated.

## Channels

The Collect Leads Action is compatible with every channel. Use **Channels** in the Action's configuration to enable or disable it per channel. See [Channels](https://chatbase.co/docs/user-guides/chatbot/actions/actions-overview.md#channels) for what configured, unconfigured, and incompatible mean.

## Best Practices

> [card] Pick the Right Mode
>
> Use **Form** for a quick, familiar capture in the Chat Bubble, and **Conversational** when you need custom fields or a less abrupt ask.

> [card] Ask at the Right Moment
>
> Trigger the form once the visitor has shown intent, not at the start of every conversation.

> [card] Use Natural Language
>
> Keep **When to use** instructions short and simple, include examples, start with action verbs, and say what you want the AI agent to do rather than what to avoid.

> [card] Keep Required Fields Few
>
> Every required field is another reason a visitor abandons the form. Require the contact method and little else.

## Frequently asked questions

> [accordion] Can I have more than one Collect Leads Action on an AI agent?
>
> No. Each AI agent has at most one Collect Leads Action, and its name is fixed. To collect different sets of details, add [Collect Data](https://chatbase.co/docs/user-guides/chatbot/actions/collect-data.md) Actions, which you can create as many times as your plan's Action limit allows.

> [accordion] Does the lead form work on WhatsApp and email?
>
> The form itself shows only on the Chat Bubble, Help Page and Center Stage. On WhatsApp, email and other messaging channels, the AI agent asks for the same fields in chat and then adds your **Success Message** to its reply. If you need custom fields everywhere, use **Conversational** mode.

> [accordion] Will the AI agent show the form again after a visitor dismisses it?
>
> It can. Dismissing the form shows your **Dismiss Message**, and the AI agent knows the visitor declined. Whether it offers the form again depends on your **When to use** text, so say explicitly if it shouldn't ask again in the same conversation.

> [accordion] Can the AI agent qualify leads before saving them?
>
> There's no built-in qualification filter. In **Conversational** mode, a lead is saved only when the AI agent completes the collection, so you can tell it in **When to use** not to collect details from visitors who don't fit, for example "Only collect leads from companies with more than 10 employees." In **Form** mode, **When to use** only decides whether the form is shown: whatever the visitor submits is saved.

> [accordion] Can a custom field be a dropdown or multiple choice?
>
> No. Custom fields can be text, number, email, date or boolean. To steer answers toward fixed options, list them in the field's description, for example "One of: Starter, Growth, Enterprise."

> [accordion] Are leads added to my Contacts?
>
> No. Leads are stored separately under **Activity > Leads** and sent to your webhooks and email notifications. They don't create or update Contacts.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.