Capture leads

A visitor asks a good question at 11 p.m., gets an answer, and leaves. Without a contact detail that conversation is over the moment the tab closes. With one, it is a contact your team can reach — and an agent that can follow up on WhatsApp instead of hoping they come back.

The lead form is a short panel inside the widget that asks for some combination of name, email and phone. It is off by default.

Who can set it up: owners and admins, on every plan. Open the agent, click Deploy → Web widget (or Edit settings on its live web deployment), go to the Appearance step and switch on Ask for contact details. The form is saved when you click Save changes (or Set live) on the Install step — not when you leave Appearance.

When it appears #

Two timings, and the choice matters more than it looks.

before_chat maximises capture rate per conversation and reduces the number of conversations. after_first_reply does the opposite: fewer forms shown, higher completion, and every lead has already seen the agent do something useful.

For support widgets, after_first_reply is almost always right — asking for an email before answering "where is my order" reads as a toll gate. For a sales enquiry form where every visitor is a potential deal, before_chat earns its friction.

With Before the chat, the form is the first thing in the panel. With After the first reply, it appears under the agent's first answer. Either way, when any field is Required, the composer is locked and reads "Fill in the details above to start…" until the form is submitted. When every field is optional, the composer stays open and the form has a Skip button.

Skipping #

The form has a Skip button only when no field is marked Required. Mark any field required and the form can only be filled in, not dismissed: the visitor has to submit it to keep chatting.

What you can ask for #

Three fields. Each one can be shown or hidden, and each shown field can be optional or required.

In the console, tick a field under What to collect to show it, and tick Required beside it to make it mandatory. In the widget, optional fields are labelled (optional), and the phone field shows an example number from your workspace's country. The submit button reads Start chat with Before the chat, and Save details with After the first reply.

At least one field must be enabled. Untick all three and the console warns "Pick at least one detail to collect, or turn the form off."

A field you disable is not collected, even if something submits it anyway — it is dropped server-side, not just hidden.

Three pieces of copy frame the ask:

The consent line is optional and renders with a checkbox the visitor must tick. Use it when your privacy notice requires an explicit act of agreement — "I agree to be contacted about my enquiry." — rather than an inferred one. If you leave it empty, no checkbox is shown and no consent is recorded.

What happens to a submission #

Three things, in this order:

A contact is matched or created. The email and phone are looked up in your Contacts. If either matches an existing contact, the lead is linked to that contact as it is: nothing on the existing contact is added or changed. If neither matches, a new contact is created with the name, email and phone.

The conversation is stamped with the customer. The chat that was anonymous ten seconds ago now carries a name, email and phone. Anyone opening it in the inbox sees who they are reading, and the agent has the same information for the rest of the conversation.

A lead.created event fires. If you have a webhook endpoint subscribed, your systems are told immediately — with the contact id, name, email and phone. That is the hook for pushing the lead into your own CRM, starting a nurture sequence, or paging a salesperson while the visitor is still on the page. See Event reference.

Validation #

The form validates on submit, and the messages a visitor sees are these exactly.

Submitting the form counts against the widget's rate limit of 12 requests per 60 seconds per visitor, like sending a message does.

Email #

The check is a format check, not a delivery check: some text, an @, a domain with a dot, and a plausible ending. asha@example.com passes. asha@example fails. asha at example.com fails.

Nothing verifies that the mailbox exists. nobody@example.com is a perfectly valid-looking address and will be accepted. If your process depends on the address being real, send something to it and see.

Phone numbers #

Phone input from real people is a mess — spaces, dashes, brackets, a leading zero out of habit, sometimes a country code and sometimes not. All of it is normalised into a single international form before it is stored.

The rule, in two parts:

1. A number that carries its own country code is taken at its word. A leading + or 00 is the visitor stating which country they are in, and it is never overridden.
2. A number without one is read as a local number in your workspace's country — the country you chose when you created the workspace, under Settings → Organization.

Part 2 is why the same ten digits can be two different people. 4155552671 is a San Francisco line for a workspace based in the United States and a number in India for a workspace based in India, and nothing in the digits themselves distinguishes the two. Your workspace country is what decides.

The number is then checked against that country's own numbering plan — how long its numbers are, which prefixes it issues — and stored as + followed by the full international form. Anything that is not a real number in that country is rejected rather than completed, because a completed guess is a number that belongs to a stranger.

Worked examples, for a workspace based in India:

The same table for a workspace based in the United States:

That last row is the one worth understanding. 9876543210 is an ordinary mobile number in India, and read against a US workspace it would become +19876543210 — an area code North America has never assigned, so a number that cannot ring. It is refused rather than stored, because a stored number that silently cannot be reached is worse than a visitor being asked to check what they typed.

The same is true in reverse, and in every direction: the check is always "is this a real number in that country", not "is this ten digits".

Duplicate submissions #

The same person, twice, is one contact — but the second submission doesn't update it.

• A submission whose email or phone matches an existing contact is linked to that contact. No second contact is created.
• The existing contact keeps the details it already had. Someone who gave meera.k@gmail.com in March and meera@krishnan.in in August with the same phone number stays one contact with the March email. The August email is on the lead and in the lead.created event, not on the contact.
• If the email belongs to one contact and the phone to another, the lead is kept with no contact linked.

Update a contact's details yourself in Contacts when a lead tells you something new.

For your own systems: treat contact_id from the lead.created event as the identity, not the email address. Two events can carry different emails and the same contact.

Why the phone number is the valuable field #

A captured phone number is what lets an agent continue the conversation on WhatsApp.

The chain is short: the lead becomes the conversation's customer, the customer carries a phone number, and an agent that has a phone number can send a WhatsApp message to it. A visitor who asks about delivery to Pune at midnight and leaves can get an answer on WhatsApp when the warehouse confirms in the morning — on a channel they will actually see, rather than an email they will not.

Two things to keep in mind before you build on it:

• The 24-hour window still applies. Capturing a number does not open a WhatsApp session. Outside an open window you need an approved template, not free text.
• A number in your CRM is not consent to message it. The visitor gave you a way to reach them about their enquiry. Use the consent line if you need a recorded basis for anything broader, and honour opt-outs — they are enforced across every number in your workspace.

Troubleshooting #

Next #