After the conversation
Leads and outcomes
Have the assistant save each visitor's details as a lead, get every lead into your CRM the moment it is captured, and report back what became of it.
A lead is what a conversation produced: a name, an email or phone number, and any other details you asked the assistant to collect. Leads come from chat, on your website and on WhatsApp, and there is at most one per conversation; when the visitor adds a detail later, the same lead is updated.
Leads with placeholder email domains, the business's own website domain, or a staging site are automatically marked as test. The website domains come from the capturing assistant's published channels.web_chat.allowed_origins. These leads stay saved and still reach lead.captured webhooks, with lead.test and lead.test_reason. Their chat mode and the webhook envelope's livemode stay unchanged. A live lead is on a staging site (staging_site) when its chat ran on a preview or staging host, unless an email reason applies first. Test leads do not count in analytics, trigger lead conversions, or link returning visitors by contact details.
Every lead has a traffic field: real, sandbox (captured through a sandbox key, the console's sandbox chat or a preview link) or test (a live lead our rules caught, or one a member marked as test). Sandbox is the new name for leads from non-live chats; their mode is still test or preview.
Lists default to real leads. Use traffic to choose: a comma list of real, sandbox and test, for example traffic=real,test. When traffic is set it decides what is returned. Without it, mode=test lists effective test leads, mode=all lists everything, and mode=preview still filters capture mode. A member can call PATCH /v1/leads/{id} with { "test": false } (Not test), { "test": true } (Test), or { "test": null } (Use automatic). Responses include test, test_reason (reserved_domain, business_domain, staging_site, or null), and test_override. Leads from non-live chats are always sandbox, and the Not test control does not apply to them. Clearing sandbox data removes only sandbox chat data, so a test lead from a live chat is retained.
Turn on lead capture
Lead capture is off until you turn it on in the assistant's web chat settings. When it is on, the assistant can save the visitor's name, email and phone, plus the extra fields you list:
{
"enabled": true,
"lead_capture": {
"enabled": true,
"fields": [
{ "key": "destination", "label": "Where they want to travel" },
{ "key": "travel_dates", "label": "When they want to travel", "required": true }
]
}
}| Setting | Meaning |
|---|---|
fields[].key | The name the value is saved under in the lead's fields. |
fields[].label | What the assistant is told the field is. Write it the way you would brief a colleague. |
fields[].type | string (the default), email or phone. |
fields[].required | The assistant asks for it before it finishes. |
require_complete | When true, no lead is saved until every required field and an email or phone number are known. A visitor who leaves earlier leaves a conversation, not a lead. |
By default a lead is saved as soon as there is an email or a phone number, and filled in as the visitor says more.
To change it on an existing assistant, read the assistant, edit config.channels.web_chat, and send the whole config back with PATCH/api/assistants/{id}: a config you send replaces the stored one, it is not merged. Values the API never returns (secrets, tool request specs) are kept for the objects and tools you send back.
Get each lead as it is captured
Subscribe a webhook to lead.captured. It fires when the assistant saves the lead, when a later analysis creates or refreshes it, when the visitor sends files after it exists, and when the chat is read again after a voice session and that creates or changes the lead. Each delivery carries the whole lead as it is now, so update your record in place rather than adding a new one.
{
"event": "lead.captured",
"event_id": "evt_9d1f...",
"conversation_id": "conv_0c8e5f2a9b7d4c1e86f3a0d2b4c6e8f1",
"data": {
"lead": {
"id": "lead_3a9c7e1f5b2d4c8e9f0a1b2c3d4e5f6a",
"name": "Ana Silva",
"email": "ana@example.com",
"phone": null,
"fields": { "destination": "Lisbon", "travel_dates": "May, one week" }
},
"conversation_id": "conv_0c8e5f2a9b7d4c1e86f3a0d2b4c6e8f1",
"source": "tool",
"summary": null
}
}source is tool when the assistant saved it during the chat, analysis when the background analysis did, attachments when files arrived, and voice when the conversation was read after a voice session in it ended. summary is the latest summary of the conversation, or null before the first analysis. All event fields are in webhook events.
Read leads
List leads newest first with GET/api/leads. It pages by cursor and filters by project_id, and by creation time with from and to (ISO 8601 with an offset).
curl "https://api.brightshoal.com/api/leads?from=2026-10-01T00:00:00Z&limit=100" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": [
{
"id": "lead_3a9c7e1f5b2d4c8e9f0a1b2c3d4e5f6a",
"project_id": "proj_...",
"assistant_id": "asst_...",
"conversation_id": "conv_0c8e5f2a9b7d4c1e86f3a0d2b4c6e8f1",
"name": "Ana Silva",
"email": "ana@example.com",
"phone": null,
"fields": { "destination": "Lisbon", "travel_dates": "May, one week" },
"source": "web_chat",
"outcome": null,
"outcome_value": null,
"outcome_currency": null,
"outcome_at": null,
"outcome_ref": null,
"created_at": "2026-10-28T09:31:04.517Z",
"updated_at": "2026-10-28T09:33:40.002Z"
}
],
"next_cursor": null,
"has_more": false
}Here source is the channel the lead came from, web_chat or whatsapp. GET/api/leads/{id} returns one lead with an attachments list: the files the visitor sent in the chat, each with a signed url. The conversation behind it, with the full transcript, is at GET/api/conversations/{id}.
Follow up on leads
Every lead has a status, the front desk's progress on it: new, contacted, qualified, won or lost. Every lead starts new; new, contacted and qualified are open, won and lost close it. Set it with PUT/api/leads/{id}/status. With an API key, name the person who acted in agent.
Log a contact
When someone calls, messages or meets the lead, log it with POST/api/leads/{id}/contacts. The console's Call, WhatsApp and Email buttons do this as they open the link. A new lead moves to contacted, which sends lead.status_changed.
curl -X POST https://api.brightshoal.com/api/leads/lead_3a9c7e1f5b2d4c8e9f0a1b2c3d4e5f6a/contacts \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "channel": "whatsapp", "next_follow_up_at": "2026-11-05T04:30:00Z", "agent": { "name": "Ana" } }'| Field | Meaning |
|---|---|
channel | Required. phone, whatsapp, email, sms, in_person or other. |
contacted_at | When it happened. Defaults to now. Not in the future, not before the lead was created, at most 30 days back. |
next_follow_up_at | When to contact them again, within a year. null clears it; leaving it out keeps the one set. |
agent | With an API key: who made the contact, as PUT /status takes it, or just a name. A contact logged with a key is recorded as via: api. |
The answer is 201 with the contact and the whole lead. A won or lost lead still takes the contact, without a status change, but a follow-up date on it is 409 lead_closed: reopen it first.
A contact logged by mistake can be undone for 24 hours with POST/api/leads/{id}/contacts/{contactId}/void. A contact is never deleted: an undone one is voided and counts for nothing. If that contact moved the lead out of new and it is still contacted, it goes back to new. After 24 hours the answer is 409 void_window_passed.
Set or clear the next follow-up on its own with PUT/api/leads/{id}/follow-up. Winning or losing a lead clears it.
Every lead carries first_contacted_at, last_contacted_at, next_follow_up_at and time_to_first_contact_seconds. A status change out of new by a person or an API key counts as the first contact when none was logged; one made by an outreach step does not. The detail read adds contacts, the live ones, newest first.
Needs attention
GET /leads takes attention to list the leads someone should act on now, oldest first:
attention | Leads |
|---|---|
uncontacted | Status new and never contacted, by when they arrived. |
overdue | Open, with next_follow_up_at before today. |
due_today | Open, with next_follow_up_at today. |
any | All three. |
Days are read in tz (an IANA zone such as Asia/Kolkata), by default the project's timezone when you see one project, else UTC. The other filters still apply, and test leads stay out unless you ask for them. GET/api/leads/attention answers the counts: uncontacted, overdue, due_today and total (a lead in two buckets counted once).
Speed to lead
GET/api/leads/speed reports how long leads waited for a first contact, wall clock, over from and to (default the last 30 days), optionally for one project_id or channel. It counts live leads that are not test and were not added by hand (staff usually type a lead in after talking to them). median_seconds and p90_seconds cover contacted leads only, so read uncontacted beside them: a team cannot look fast by not contacting. within_5m, within_1h and within_24h count contacted leads, and by_channel splits the same numbers by channel.
Nudges
When a new lead is still uncontacted 60 minutes after it arrived, Brightshoal sends lead.uncontacted, once per lead. When a follow-up date comes, it sends lead.follow_up_due. Both go only to webhooks subscribed to them and to Slack rules that list them, never by email. Test leads and leads added by hand are never nudged as uncontacted.
Change the wait per project with PUT/api/leads/settings (an admin): uncontacted_after_minutes from 15 to 1,440, or null to turn the nudge off. GET/api/leads/settings shows it, and counts_contact_hours: when the project has contact hours and a timezone, only those hours count, holidays closed. A lead that arrives on Friday evening with a 60 minute wait is nudged an hour into Monday's hours. A nudge more than 6 hours late (after an outage) is never sent.
Report what became of it
When your team books the trip, wins the deal or loses it, tell the API. Outcomes turn conversations into bookings in chat analytics, where the funnel counts booked leads.
curl -X PUT https://api.brightshoal.com/api/leads/lead_3a9c7e1f5b2d4c8e9f0a1b2c3d4e5f6a/outcome \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "outcome": "booked", "value": 2480, "currency": "EUR", "ref": "OPP-10442" }'| Field | Meaning |
|---|---|
outcome | Required. open, booked or lost. |
value | What it was worth, zero or more. Needs currency. Stored to two decimals and returned as a string, "2480.00". |
currency | Three uppercase letters, such as EUR or USD. |
at | When it happened, ISO 8601 with an offset. Defaults to now. |
ref | Your own id for the booking or opportunity, up to 128 characters. |
The call replaces the whole outcome: a field you leave out is cleared, not kept. Send the full outcome every time, including when you only change the value. customer_id, your CRM's id for the person, is the exception: leaving it out keeps the stored one. The response is the updated lead.