API reference
Chat analytics
Web chat health, quality, the visitor funnel, trends and incidents, with notification subscriptions.
- GET
/api/chat-analytics/engagementGet chat depth, timing and busy hours - GET
/api/chat-analytics/failuresList failed chat requests - GET
/api/chat-analytics/funnelGet the visitor funnel - GET
/api/chat-analytics/healthGet chat health by site - GET
/api/chat-analytics/incidentsList chat health incidents - POST
/api/chat-analytics/incidents/{id}/muteMute an incident - POST
/api/chat-analytics/incidents/{id}/resolveResolve an incident - POST
/api/chat-analytics/incidents/{id}/unmuteUnmute an incident - GET
/api/chat-analytics/lead-sourcesGet leads by first touch and latest paid touch - POST
/api/chat-analytics/outcomes/backfillLabel how already analysed chats ended (staff only) - GET
/api/chat-analytics/qualityGet chat quality - GET
/api/chat-analytics/subscriptionsList notification subscriptions - POST
/api/chat-analytics/subscriptionsCreate a notification subscription - PATCH
/api/chat-analytics/subscriptions/{id}Update a notification subscription - DELETE
/api/chat-analytics/subscriptions/{id}Delete a notification subscription - GET
/api/chat-analytics/trendGet daily or weekly chat totals
Get chat depth, timing and busy hours
GET/api/chat-analytics/engagement
Counted web chats started in the window by visitor messages (with how many saved a lead), seconds from a page view's first open to its first send, seconds and visitor messages from a chat's first message to its lead, chats and leads by weekday and hour in tz, and how many started while the assistant's working hours were closed.
Secret API key. How it works
Query parameters
project_idstringOnly this project. An org-wide key covers every project by default.
assistant_idarray of stringOnly these assistants. Repeat the parameter or comma-separate the values; a row matching any of them is kept.
fromstringISO 8601 timestampDefault: 24 hours before
to.tostringISO 8601 timestampDefault: now. Ranges over 90 days are rejected.
tzstringIANA time zone the weekday and hour heatmap counts in. Default: the first working-hours zone among the assistants asked for, else UTC.
Returns
200 OK
Response attributes
dataChatEngagementrequired7 attributes
fromstringISO 8601 timestamptostringISO 8601 timestampdeptharray of objectrequiredChats by visitor messages: buckets
1,2,3,4-6,7+.3 attributes
bucketstringrequiredconversationsintegerrequiredleadsintegerrequired
open_to_first_messageobjectrequired4 attributes
samplesintegerp50_sinteger | nullp90_sinteger | nullby_reasonobject2 attributes
samplesintegerp50_sinteger | null
time_to_leadobjectrequired4 attributes
samplesintegerp50_sinteger | nullp90_sinteger | nullp50_messagesinteger | null
heatmapobjectrequired2 attributes
tzstringcellsarray of object4 attributes
weekdayintegerrequired1 (Monday) to 7.
hourintegerrequiredconversationsintegerrequiredleadsintegerrequired
out_of_hoursobjectrequiredmeasured: chats whose assistant sets working hours;conversations: of those, started while closed. The same for chats with a lead.4 attributes
measuredintegerconversationsintegermeasured_leadsintegerleadsinteger
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/chat-analytics/engagement" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"from": "2026-10-28T09:30:00.000Z",
"to": "2026-10-28T09:30:00.000Z",
"depth": [
{
"bucket": "string",
"conversations": 1,
"leads": 1
}
],
"open_to_first_message": {
"samples": 1,
"p50_s": 1,
"p90_s": 1,
"by_reason": {
"key": {
"samples": 1,
"p50_s": 1
}
}
},
"time_to_lead": {
"samples": 1,
"p50_s": 1,
"p90_s": 1,
"p50_messages": 1
},
"heatmap": {
"tz": "string",
"cells": [
{
"weekday": 1,
"hour": 1,
"conversations": 1,
"leads": 1
}
]
},
"out_of_hours": {
"measured": 1,
"conversations": 1,
"measured_leads": 1,
"leads": 1
}
}
}List failed chat requests
GET/api/chat-analytics/failures
Each public chat request (config, events, start, send) that failed or was refused, with its status, outcome code, site, browser and request id, for chasing a broken embed. A malformed cursor is a 400.
Secret API key. How it works
Query parameters
project_idstringOnly this project. An org-wide key covers every project by default.
assistant_idarray of stringOnly these assistants. Repeat the parameter or comma-separate the values; a row matching any of them is kept.
fromstringISO 8601 timestampDefault: 24 hours before
to.tostringISO 8601 timestampDefault: now. Ranges over 90 days are rejected.
cursorstringnext_cursorfrom the previous page.limitinteger1 to 100Page size.
Default
50
Returns
200 OK
Response attributes
dataarray of ChatFailurerequired14 attributes
idstringrequiredoccurred_atstringrequiredISO 8601 timestamproutestringrequiredOne of
configeventscreatemessageoutcomestringrequiredstatus_codeintegerrequiredsitestring | nullsampledbooleanrequest_idstring | nullconversation_idstring | nullclient_message_idstring | nulldevicestring | nullbrowserstring | nullwidget_versionstring | nullassistant_idstring | null
next_cursorstring | nullrequiredhas_morebooleanrequired
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/chat-analytics/failures" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": [
{
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"occurred_at": "2026-10-28T09:30:00.000Z",
"route": "config",
"outcome": "string",
"status_code": 1,
"site": "string",
"sampled": true,
"request_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"client_message_id": "msg_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"device": "string",
"browser": "string",
"widget_version": "string",
"assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
}
],
"next_cursor": "eyJ0IjoiMjAyNi0xMC0yOCJ9",
"has_more": true
}Get the visitor funnel
GET/api/chat-analytics/funnel
Page views at each stage (loaded, shown, card, opened, typed, sent), then sends, conversations, leads, handoffs and bookings, optionally split by a dimension and compared with the window before.
Secret API key. How it works
Query parameters
project_idstringOnly this project. An org-wide key covers every project by default.
assistant_idarray of stringOnly these assistants. Repeat the parameter or comma-separate the values; a row matching any of them is kept.
fromstringISO 8601 timestampDefault: 24 hours before
to.tostringISO 8601 timestampDefault: now. Ranges over 90 days are rejected.
group_bystringSplit the funnel into one group per value of this dimension.
hourkeys each UTC hour of the window;hour_of_daykeys the hour of the day (00to23) intz, adding up every day in the window.campaignandmediumkey the visit'sutm_campaignandutm_medium, andad_platformthe ad click id its landing carried (google,meta,microsoft,openai);nonewhen there was none andunknownwithout analytics consent.url_rulekeys theurl_rulespattern whose card showed on the page view (card_shown):nonefor the assistant-wide opener,no_cardwhen no card showed.One of
nonesitepagedevicebrowsersourcehourhour_of_dayopen_reasonvisitor_typeassistantcampaignmediumad_platformurl_ruleDefault
"none"tzstringIANA time zone
hour_of_daycounts its hours in, e.g.Europe/London.Default
"UTC"comparestringpreviousadds each group's counts for the window of the same length just before.average_7adds the mean of the same window on each of the seven days before (or of the seven windows before, for a window of a day or longer), to one decimal; it takes windows of 7 days or less.One of
previousaverage_7
Returns
200 OK
Response attributes
dataChatFunnelrequired15 attributes
fromstringrequiredISO 8601 timestamptostringrequiredISO 8601 timestampgroup_bystringrequiredcomparestring | nullThe comparison in
previous, or null.One of
previousaverage_7tzstringThe time zone
hour_of_daywas counted in.signalsobject | nullWith group_by=none only, else null. Per page view, under the funnel's rules: the top countries and browser languages (stored only with analytics consent, from widgets that send them), page views from automated browsers (
navigator.webdriver, still counted in the funnel), and frompage_exitevents: median visible seconds, deepest scroll by quarter, how often the visitor closed the chat that opened and after how long, and why the opener did not fire (auto_open).7 attributes
countriesarray of objectrequired2 attributes
countrystringrequiredpage_viewsintegerrequired
located_page_viewsintegerrequiredlanguagesarray of objectrequired2 attributes
languagestringrequiredpage_viewsintegerrequired
automated_page_viewsintegerrequiredexitsobjectrequired6 attributes
page_viewsintegerrequiredmedian_visible_sinteger | nullrequiredscrollobjectrequiredKeys
0,25,50,75,100.openedintegerrequiredPage views where the panel opened; a card alone does not count.
closedintegerrequiredOf those, the visitor closed the panel. A card put away is not a close.
median_closed_after_sinteger | nullrequired
auto_openobjectrequiredPage views by
page_exitauto_openoutcome,consent_heldincluded.banner_page_viewsintegerrequiredPage views where a cookie or consent banner was up (
page_exitbanner).
visits_sincestring | nullISO 8601 timestampWhen this scope's first page view tied to a visit arrived; visit counts start here. Null before any did.
page_views_sincestring | nullISO 8601 timestampWhen this scope's first page view the widget reported arrived; page-view stages start here. Null before any did.
groupsarray of objectrequired22 attributes
page_viewsobjectrequiredDistinct page views per stage. Events without a page_view_id are excluded.
6 attributes
loadedintegerrequiredshownintegerrequiredcardintegerrequiredA card (nudge, continue, link follow-up or teaser) showed:
card_shown.openedintegerrequiredtypedintegerrequiredsentintegerrequired
visitsobjectrequiredDistinct visits (a run of page views by one browser) per stage, with the same filters as page_views. Only events that carry a visit_id count: visits exist only with analytics consent and a current widget.
6 attributes
loadedintegerrequiredshownintegerrequiredcardintegerrequiredA card (nudge, continue, link follow-up or teaser) showed:
card_shown.openedintegerrequiredtypedintegerrequiredsentintegerrequired
opensobjectDistinct page views opened for each reason, counted separately: a page view the widget opened by itself (
proactive) and the visitor later reopened (visitor) counts in both.page_views.openedmixes them.3 attributes
visitorintegerrequiredproactiveintegerrequiredapiintegerrequired
cardsobjectDistinct page views where each card showed (
card_shown), counted separately.4 attributes
nudgeintegerrequiredcontinueintegerrequiredfollow_upintegerrequiredteaserintegerrequired
opens_fromobjectDistinct page views opened, by what opened them (
widget_openedfrom): the launcher, the nudge (or the classic teaser), the continue card (or its start-fresh button), the link follow-up card, the host's API, or by itself (auto). Visitor opens from widgets that predatefromcount in none of these.6 attributes
launcherintegerrequirednudgeintegerrequiredcontinueintegerrequiredfollow_upintegerrequiredapiintegerrequiredautointegerrequired
first_sendsobjectOf
conversations: by how the first message was sent (message_sendsource): typed, a reply chip, a starter, a nudge answer, a continue-card draft, or the contact card. Chats from widgets that predatesourcecount in none.6 attributes
typedintegerrequiredreplyintegerrequiredstarterintegerrequirednudgeintegerrequiredcontinueintegerrequiredcontactintegerrequired
crawlersobject | nullPage views from declared crawlers (device
bot), which every other count leaves out, and how many the widget opened by itself. Only for group_by none, site, page, hour, hour_of_day and assistant; null otherwise.2 attributes
loadedintegerrequiredopenedintegerrequired
visitorsintegerrequiredDistinct visitor ids among widget_loaded events.
returning_visitsintegerrequiredDistinct visits among widget_loaded events whose visit_number is above 1.
identified_page_viewsintegerrequiredDistinct page views among widget_loaded events that carry a visit_id. Divide by tracked_page_views for coverage.
tracked_page_viewsintegerDistinct page views since visit tracking started for this scope (the response's visits_since); 0 before it started. The coverage denominator, so earlier, untracked weeks do not count as untracked traffic.
sendsobject | nullrequired5 attributes
pressedintegeracceptedintegeransweredintegerfailedintegerrefusedinteger
conversationsinteger | nullrequiredChats with a visitor message started in the window, in every grouping: a chat takes the page, source and device of the page view its first message was sent from, or the group
untrackedwhen there is none. Sandbox chats and live chats our rules caught (test markers, preview hosts, internal lead emails) are left out (see excluded and excluded_traffic).deep_conversationsintegerOf conversations: chats with three or more visitor messages.
single_message_conversationsintegerOf conversations: chats where the visitor sent one message and stopped.
leadsinteger | nullrequiredLeads saved in the window, grouped as their chat is.
valid_leadsintegerLeads with at least one email or phone that is not a placeholder or the business's own number.
handoffsinteger | nullrequiredHandoffs requested in the window, grouped as their chat is.
bookedinteger | nullrequiredconvertedobjectThe conversion cohort: page views loaded in the window from which a chat started, and those whose chat saved a lead or a valid lead in the window. Divide by page_views.loaded for conversion; unlike the activity counts above, it leaves out chats with no page view or from before page tracking.
3 attributes
conversationsintegerrequiredleadsintegerrequiredvalid_leadsintegerrequired
keystring | nullrequiredpreviousobjectThe same counts for the comparison the request asked for. Under compare=average_7 they are means, to one decimal, so not whole numbers.
20 attributes
page_viewsobjectrequiredDistinct page views per stage. Events without a page_view_id are excluded.
6 attributes
loadedintegerrequiredshownintegerrequiredcardintegerrequiredA card (nudge, continue, link follow-up or teaser) showed:
card_shown.openedintegerrequiredtypedintegerrequiredsentintegerrequired
visitsobjectrequiredDistinct visits (a run of page views by one browser) per stage, with the same filters as page_views. Only events that carry a visit_id count: visits exist only with analytics consent and a current widget.
6 attributes
loadedintegerrequiredshownintegerrequiredcardintegerrequiredA card (nudge, continue, link follow-up or teaser) showed:
card_shown.openedintegerrequiredtypedintegerrequiredsentintegerrequired
opensobjectDistinct page views opened for each reason, counted separately: a page view the widget opened by itself (
proactive) and the visitor later reopened (visitor) counts in both.page_views.openedmixes them.3 attributes
visitorintegerrequiredproactiveintegerrequiredapiintegerrequired
cardsobjectDistinct page views where each card showed (
card_shown), counted separately.4 attributes
nudgeintegerrequiredcontinueintegerrequiredfollow_upintegerrequiredteaserintegerrequired
opens_fromobjectDistinct page views opened, by what opened them (
widget_openedfrom): the launcher, the nudge (or the classic teaser), the continue card (or its start-fresh button), the link follow-up card, the host's API, or by itself (auto). Visitor opens from widgets that predatefromcount in none of these.6 attributes
launcherintegerrequirednudgeintegerrequiredcontinueintegerrequiredfollow_upintegerrequiredapiintegerrequiredautointegerrequired
first_sendsobjectOf
conversations: by how the first message was sent (message_sendsource): typed, a reply chip, a starter, a nudge answer, a continue-card draft, or the contact card. Chats from widgets that predatesourcecount in none.6 attributes
typedintegerrequiredreplyintegerrequiredstarterintegerrequirednudgeintegerrequiredcontinueintegerrequiredcontactintegerrequired
crawlersobject | nullPage views from declared crawlers (device
bot), which every other count leaves out, and how many the widget opened by itself. Only for group_by none, site, page, hour, hour_of_day and assistant; null otherwise.2 attributes
loadedintegerrequiredopenedintegerrequired
visitorsintegerrequiredDistinct visitor ids among widget_loaded events.
returning_visitsintegerrequiredDistinct visits among widget_loaded events whose visit_number is above 1.
identified_page_viewsintegerrequiredDistinct page views among widget_loaded events that carry a visit_id. Divide by tracked_page_views for coverage.
tracked_page_viewsintegerDistinct page views since visit tracking started for this scope (the response's visits_since); 0 before it started. The coverage denominator, so earlier, untracked weeks do not count as untracked traffic.
sendsobject | nullrequired5 attributes
pressedintegeracceptedintegeransweredintegerfailedintegerrefusedinteger
conversationsinteger | nullrequiredChats with a visitor message started in the window, in every grouping: a chat takes the page, source and device of the page view its first message was sent from, or the group
untrackedwhen there is none. Sandbox chats and live chats our rules caught (test markers, preview hosts, internal lead emails) are left out (see excluded and excluded_traffic).deep_conversationsintegerOf conversations: chats with three or more visitor messages.
single_message_conversationsintegerOf conversations: chats where the visitor sent one message and stopped.
leadsinteger | nullrequiredLeads saved in the window, grouped as their chat is.
valid_leadsintegerLeads with at least one email or phone that is not a placeholder or the business's own number.
handoffsinteger | nullrequiredHandoffs requested in the window, grouped as their chat is.
bookedinteger | nullrequiredconvertedobjectThe conversion cohort: page views loaded in the window from which a chat started, and those whose chat saved a lead or a valid lead in the window. Divide by page_views.loaded for conversion; unlike the activity counts above, it leaves out chats with no page view or from before page tracking.
3 attributes
conversationsintegerrequiredleadsintegerrequiredvalid_leadsintegerrequired
groups_totalintegerrequiredGroups found; only the first 50 are returned (hours are never cut).
truncatedbooleanrequiredcoverageobjectrequiredCounted chats in the window, and those tied to a page view the widget reported.
2 attributes
conversationsintegerrequiredtrackedintegerrequired
excludedobjectrequiredChats in the window left out of every number, each under the first reason that applies: a test marker or sandbox key, a preview or staging host, or an internal lead email.
3 attributes
testintegerrequiredpreviewintegerrequiredinternalintegerrequired
excluded_trafficobjectrequiredThe same left-out chats by traffic, each counted once:
sandboxchats come from a non-live key (a sandbox key, the console's sandbox chat or a preview link);testchats are live chats our rules caught (a test marker, a staging or preview host, or a placeholder or own-domain lead email).2 attributes
sandboxintegerrequiredtestintegerrequired
partialbooleanrequiredTrue when not every send in the window could be read, so the counts are a lower bound. Retry, or narrow the range.
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/chat-analytics/funnel" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"from": "2026-10-28T09:30:00.000Z",
"to": "2026-10-28T09:30:00.000Z",
"group_by": "string",
"compare": "previous",
"tz": "string",
"signals": {
"countries": [
{
"country": "string",
"page_views": 1
}
],
"located_page_views": 1,
"languages": [
{
"language": "en",
"page_views": 1
}
],
"automated_page_views": 1,
"exits": {
"page_views": 1,
"median_visible_s": 1,
"scroll": {
"key": 1
},
"opened": 1,
"closed": 1,
"median_closed_after_s": 1
},
"auto_open": {
"key": 1
},
"banner_page_views": 1
},
"visits_since": "2026-10-28T09:30:00.000Z",
"page_views_since": "2026-10-28T09:30:00.000Z",
"groups": [
{
"page_views": {
"loaded": 1,
"shown": 1,
"card": 1,
"opened": 1,
"typed": 1,
"sent": 1
},
"visits": {
"loaded": 1,
"shown": 1,
"card": 1,
"opened": 1,
"typed": 1,
"sent": 1
},
"opens": {
"visitor": 1,
"proactive": 1,
"api": 1
},
"cards": {
"nudge": 1,
"continue": 1,
"follow_up": 1,
"teaser": 1
},
"opens_from": {
"launcher": 1,
"nudge": 1,
"continue": 1,
"follow_up": 1,
"api": 1,
"auto": 1
},
"first_sends": {
"typed": 1,
"reply": 1,
"starter": 1,
"nudge": 1,
"continue": 1,
"contact": 1
},
"crawlers": {
"loaded": 1,
"opened": 1
},
"visitors": 1,
"returning_visits": 1,
"identified_page_views": 1,
"tracked_page_views": 1,
"sends": {
"pressed": 1,
"accepted": 1,
"answered": 1,
"failed": 1,
"refused": 1
},
"conversations": 1,
"deep_conversations": 1,
"single_message_conversations": 1,
"leads": 1,
"valid_leads": 1,
"handoffs": 1,
"booked": 1,
"converted": {
"conversations": 1,
"leads": 1,
"valid_leads": 1
},
"key": "string",
"previous": {
"page_views": {
"loaded": {},
"shown": {},
"card": {},
"opened": {},
"typed": {},
"sent": {}
},
"visits": {
"loaded": {},
"shown": {},
"card": {},
"opened": {},
"typed": {},
"sent": {}
},
"opens": {
"visitor": {},
"proactive": {},
"api": {}
},
"cards": {
"nudge": {},
"continue": {},
"follow_up": {},
"teaser": {}
},
"opens_from": {
"launcher": {},
"nudge": {},
"continue": {},
"follow_up": {},
"api": {},
"auto": {}
},
"first_sends": {
"typed": {},
"reply": {},
"starter": {},
"nudge": {},
"continue": {},
"contact": {}
},
"crawlers": {
"loaded": {},
"opened": {}
},
"visitors": 1,
"returning_visits": 1,
"identified_page_views": 1,
"tracked_page_views": 1,
"sends": {
"pressed": {},
"accepted": {},
"answered": {},
"failed": {},
"refused": {}
},
"conversations": 1,
"deep_conversations": 1,
"single_message_conversations": 1,
"leads": 1,
"valid_leads": 1,
"handoffs": 1,
"booked": 1,
"converted": {
"conversations": {},
"leads": {},
"valid_leads": {}
}
}
}
],
"groups_total": 1,
"truncated": true,
"coverage": {
"conversations": 1,
"tracked": 1
},
"excluded": {
"test": 1,
"preview": 1,
"internal": 1
},
"excluded_traffic": {
"sandbox": 1,
"test": 1
},
"partial": true
}
}Get chat health by site
GET/api/chat-analytics/health
For each site the chat runs on: page views, shown and opened panels, sends, failures and refusals, reply time percentiles, the last successful reply and open incidents, with a status (ok, warning, critical, idle). Defaults to the last 24 hours.
Secret API key. How it works
Query parameters
project_idstringOnly this project. An org-wide key covers every project by default.
assistant_idarray of stringOnly these assistants. Repeat the parameter or comma-separate the values; a row matching any of them is kept.
fromstringISO 8601 timestampDefault: 24 hours before
to.tostringISO 8601 timestampDefault: now. Ranges over 90 days are rejected.
Returns
200 OK
Response attributes
dataChatHealthrequired3 attributes
checkerobjectrequired2 attributes
swept_atstring | nullrequiredISO 8601 timestampstalebooleanrequired
partialbooleanrequiredTrue when not every send in the window could be read, so the counts are a lower bound. Retry, or narrow the range.
sitesarray of objectrequired14 attributes
sitestring | nullrequiredstatusstringrequiredOne of
okwarningcriticalidlepage_viewsintegerrequiredshownintegeropenedintegersendsintegerrequiredacceptedintegerfailedintegerrefusedintegerfailure_ratenumber | nullreply_ms_p50integer | nullreply_ms_p90integer | nulllast_success_atstring | nullISO 8601 timestampopen_incidentsintegerrequired
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/chat-analytics/health" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"checker": {
"swept_at": "2026-10-28T09:30:00.000Z",
"stale": true
},
"partial": true,
"sites": [
{
"site": "string",
"status": "ok",
"page_views": 1,
"shown": 1,
"opened": 1,
"sends": 1,
"accepted": 1,
"failed": 1,
"refused": 1,
"failure_rate": 1,
"reply_ms_p50": 640,
"reply_ms_p90": 640,
"last_success_at": "2026-10-28T09:30:00.000Z",
"open_incidents": 1
}
]
}
}List chat health incidents
GET/api/chat-analytics/incidents
Problems the health checker opened on its own (for example a site whose sends started failing), newest activity first. An incident resolves itself when the site recovers or goes quiet, or by hand.
Secret API key. How it works
Query parameters
project_idstringOnly this project. An org-wide key covers every project by default.
assistant_idarray of stringOnly these assistants' incidents. Repeat the parameter or comma-separate the values; a row matching any of them is kept.
statusstringWhich incidents to list.
One of
openresolvedallDefault
"open"cursorstringnext_cursorfrom the previous page.limitinteger1 to 100Page size.
Default
50
Returns
200 OK
Response attributes
dataarray of ChatIncidentrequired23 attributes
idstringrequiredorg_idstringproject_idstringrequiredassistant_idstring | nullwidget_key_idstring | nullsitestring | nullrulestringrequiredseveritystringrequiredOne of
infowarningcriticalstatusstringrequiredOne of
openresolveddedupe_keystringfirst_seen_atstringISO 8601 timestamplast_seen_atstringISO 8601 timestampoccurrencesintegerexample_request_idstring | nullexample_conversation_idstring | nulldetailobject | nullmuted_untilstring | nullISO 8601 timestampmuted_bystring | nullresolved_atstring | nullISO 8601 timestampresolutionstring | nullOne of
recoveredquietmanualresolved_bystring | nullcreated_atstringISO 8601 timestampupdated_atstringISO 8601 timestamp
next_cursorstring | nullrequiredhas_morebooleanrequired
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/chat-analytics/incidents" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": [
{
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"widget_key_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"site": "string",
"rule": "string",
"severity": "info",
"status": "open",
"dedupe_key": "string",
"first_seen_at": "2026-10-28T09:30:00.000Z",
"last_seen_at": "2026-10-28T09:30:00.000Z",
"occurrences": 1,
"example_request_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"example_conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"detail": {},
"muted_until": "2026-10-28T09:30:00.000Z",
"muted_by": "string",
"resolved_at": "2026-10-28T09:30:00.000Z",
"resolution": "recovered",
"resolved_by": "string",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z"
}
],
"next_cursor": "eyJ0IjoiMjAyNi0xMC0yOCJ9",
"has_more": true
}Mute an incident
POST/api/chat-analytics/incidents/{id}/mute
Stops notifications for this incident for 15 minutes to 7 days. The incident stays open and keeps counting.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredIncident id.
Request body
minutesintegerrequired15 to 10080
Returns
200 OK
Response attributes
dataChatIncidentrequired23 attributes
idstringrequiredorg_idstringproject_idstringrequiredassistant_idstring | nullwidget_key_idstring | nullsitestring | nullrulestringrequiredseveritystringrequiredOne of
infowarningcriticalstatusstringrequiredOne of
openresolveddedupe_keystringfirst_seen_atstringISO 8601 timestamplast_seen_atstringISO 8601 timestampoccurrencesintegerexample_request_idstring | nullexample_conversation_idstring | nulldetailobject | nullmuted_untilstring | nullISO 8601 timestampmuted_bystring | nullresolved_atstring | nullISO 8601 timestampresolutionstring | nullOne of
recoveredquietmanualresolved_bystring | nullcreated_atstringISO 8601 timestampupdated_atstringISO 8601 timestamp
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Not found, or outside what the key can see
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X POST "https://api.brightshoal.com/api/chat-analytics/incidents/INCIDENT_ID/mute" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"minutes": 15
}'{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"widget_key_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"site": "string",
"rule": "string",
"severity": "info",
"status": "open",
"dedupe_key": "string",
"first_seen_at": "2026-10-28T09:30:00.000Z",
"last_seen_at": "2026-10-28T09:30:00.000Z",
"occurrences": 1,
"example_request_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"example_conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"detail": {},
"muted_until": "2026-10-28T09:30:00.000Z",
"muted_by": "string",
"resolved_at": "2026-10-28T09:30:00.000Z",
"resolution": "recovered",
"resolved_by": "string",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z"
}
}Resolve an incident
POST/api/chat-analytics/incidents/{id}/resolve
Closes the incident as manual. No request body. 409 already_resolved if it is closed already; a new failure opens a new incident.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredIncident id.
Returns
200 OK
Response attributes
dataChatIncidentrequired23 attributes
idstringrequiredorg_idstringproject_idstringrequiredassistant_idstring | nullwidget_key_idstring | nullsitestring | nullrulestringrequiredseveritystringrequiredOne of
infowarningcriticalstatusstringrequiredOne of
openresolveddedupe_keystringfirst_seen_atstringISO 8601 timestamplast_seen_atstringISO 8601 timestampoccurrencesintegerexample_request_idstring | nullexample_conversation_idstring | nulldetailobject | nullmuted_untilstring | nullISO 8601 timestampmuted_bystring | nullresolved_atstring | nullISO 8601 timestampresolutionstring | nullOne of
recoveredquietmanualresolved_bystring | nullcreated_atstringISO 8601 timestampupdated_atstringISO 8601 timestamp
- 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Not found, or outside what the key can see
- 409 Conflict
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X POST "https://api.brightshoal.com/api/chat-analytics/incidents/INCIDENT_ID/resolve" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"widget_key_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"site": "string",
"rule": "string",
"severity": "info",
"status": "open",
"dedupe_key": "string",
"first_seen_at": "2026-10-28T09:30:00.000Z",
"last_seen_at": "2026-10-28T09:30:00.000Z",
"occurrences": 1,
"example_request_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"example_conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"detail": {},
"muted_until": "2026-10-28T09:30:00.000Z",
"muted_by": "string",
"resolved_at": "2026-10-28T09:30:00.000Z",
"resolution": "recovered",
"resolved_by": "string",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z"
}
}Unmute an incident
POST/api/chat-analytics/incidents/{id}/unmute
Resumes notifications for a muted incident. No request body.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredIncident id.
Returns
200 OK
Response attributes
dataChatIncidentrequired23 attributes
idstringrequiredorg_idstringproject_idstringrequiredassistant_idstring | nullwidget_key_idstring | nullsitestring | nullrulestringrequiredseveritystringrequiredOne of
infowarningcriticalstatusstringrequiredOne of
openresolveddedupe_keystringfirst_seen_atstringISO 8601 timestamplast_seen_atstringISO 8601 timestampoccurrencesintegerexample_request_idstring | nullexample_conversation_idstring | nulldetailobject | nullmuted_untilstring | nullISO 8601 timestampmuted_bystring | nullresolved_atstring | nullISO 8601 timestampresolutionstring | nullOne of
recoveredquietmanualresolved_bystring | nullcreated_atstringISO 8601 timestampupdated_atstringISO 8601 timestamp
- 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Not found, or outside what the key can see
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X POST "https://api.brightshoal.com/api/chat-analytics/incidents/INCIDENT_ID/unmute" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"widget_key_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"site": "string",
"rule": "string",
"severity": "info",
"status": "open",
"dedupe_key": "string",
"first_seen_at": "2026-10-28T09:30:00.000Z",
"last_seen_at": "2026-10-28T09:30:00.000Z",
"occurrences": 1,
"example_request_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"example_conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"detail": {},
"muted_until": "2026-10-28T09:30:00.000Z",
"muted_by": "string",
"resolved_at": "2026-10-28T09:30:00.000Z",
"resolution": "recovered",
"resolved_by": "string",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z"
}
}Get leads by first touch and latest paid touch
GET/api/chat-analytics/lead-sources
Counted web chat leads saved in the window, grouped by the visitor's first-ever touch (UTM source, else referrer host, else direct; not_recorded without one) and by their latest paid touch within 90 days (the ad platform its click id names, else its UTM source). Sorted by valid leads, at most 20 rows each.
Secret API key. How it works
Query parameters
project_idstringOnly this project. An org-wide key covers every project by default.
assistant_idarray of stringOnly these assistants. Repeat the parameter or comma-separate the values; a row matching any of them is kept.
fromstringISO 8601 timestampDefault: 24 hours before
to.tostringISO 8601 timestampDefault: now. Ranges over 90 days are rejected.
Returns
200 OK
Response attributes
dataChatLeadSourcesrequired5 attributes
fromstringISO 8601 timestamptostringISO 8601 timestampleadsintegerrequiredfirst_toucharray of ChatLeadSourcerequired3 attributes
keystringrequiredleadsintegerrequiredvalid_leadsintegerrequired
latest_paidarray of ChatLeadSourcerequired3 attributes
keystringrequiredleadsintegerrequiredvalid_leadsintegerrequired
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/chat-analytics/lead-sources" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"from": "2026-10-28T09:30:00.000Z",
"to": "2026-10-28T09:30:00.000Z",
"leads": 1,
"first_touch": [
{
"key": "string",
"leads": 1,
"valid_leads": 1
}
],
"latest_paid": [
{
"key": "string",
"leads": 1,
"valid_leads": 1
}
]
}
}Label how already analysed chats ended (staff only)
POST/api/chat-analytics/outcomes/backfill
Queues ended, counted web chats in the window whose analysis has no outcome label for an outcome-only run. It sends nothing to any CRM or webhook. At most 500 per call; call again while remaining is true.
Secret API key, not a viewer key. How it works
Query parameters
project_idstringOnly this project. An org-wide key covers every project by default.
assistant_idarray of stringOnly these assistants. Repeat the parameter or comma-separate the values; a row matching any of them is kept.
fromstringISO 8601 timestampDefault: 24 hours before
to.tostringISO 8601 timestampDefault: now. Ranges over 90 days are rejected.
Returns
200 OK
Response attributes
dataChatOutcomesBackfillrequired3 attributes
queuedintegerrequiredcandidatesintegerrequiredremainingbooleanrequiredMore chats in the window still need a label: call again.
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X POST "https://api.brightshoal.com/api/chat-analytics/outcomes/backfill" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"queued": 1,
"candidates": 1,
"remaining": true
}
}Get chat quality
GET/api/chat-analytics/quality
How well the chat is doing for visitors: reply and first-token time, missing replies, handoffs answered, how complete leads are, cost per lead, the assistant lines visitors most often stop after, and improvement (reply feedback, conversation ratings, containment, unanswered knowledge questions, unhelpful answers and comments, suggested fixes, where chats stop and flags on the assistant's answers, with emails, phone numbers and common name patterns masked).
Secret API key. How it works
Query parameters
project_idstringOnly this project. An org-wide key covers every project by default.
assistant_idarray of stringOnly these assistants. Repeat the parameter or comma-separate the values; a row matching any of them is kept.
fromstringISO 8601 timestampDefault: 24 hours before
to.tostringISO 8601 timestampDefault: now. Ranges over 90 days are rejected.
Returns
200 OK
Response attributes
dataChatQualityrequired15 attributes
reply_msobject7 attributes
bucketsarray of object2 attributes
le_msinteger | nullrequiredcountintegerrequired
p50integer | nullp90integer | nullp95integer | nullp99integer | nullsamplesintegerReplies measured.
slowintegerReplies slower than 15 seconds.
first_token_msobject2 attributes
p50integer | nullp90integer | null
repliesobject3 attributes
answeredintegermissingintegerrescuedinteger
sendsobject3 attributes
totalintegerfailedintegerquick_reply_sharenumber | null
handoffobject4 attributes
requestedintegeransweredintegerTaken over by an advisor.
repliedintegerAn advisor wrote after the request.
median_answer_secondsinteger | null
leadsobject10 attributes
totalintegerwith_emailintegerwith_phoneintegerwith_nameintegervalidintegerWith one email or phone that is not a placeholder or the business's own number.
flagsobject3 attributes
placeholder_emailintegerplaceholder_phoneintegerbusiness_phoneinteger
required_completeinteger | nullLeads holding every required field; null when no assistant marks any.
bookedintegerlostintegerrevenuearray of object2 attributes
currencystringrequiredamountnumberrequired
costobject3 attributes
totalarray of object2 attributes
currencystringrequiredamountnumberrequired
per_leadarray of object2 attributes
currencystringrequiredamountnumberrequired
per_valid_leadarray of objectChat cost over leads with a usable email or phone.
2 attributes
currencystringrequiredamountnumberrequired
ended_reasonsobjectEnded chats by how they ended (
visitor_ended,idle_timeout,max_messages,error,unknown).chipsarray of objectSuggested replies visitors tapped in chats started in the window, most sent first (at most 10), masked.
4 attributes
textstringrequiredsendsintegerrequiredconversationsintegerrequiredleadsintegerrequiredOf
conversations: chats that saved a lead.
stop_pointsarray of objectWhere ended chats stopped while the assistant waited on the visitor, by what it had asked (from the analysis labels).
3 attributes
keystringrequiredtextstringrequiredconversationsintegerrequired
outcomesobjectHow ended chats ended, from the analysis labels. Counts by label;
labelledofendedwere labelled.7 attributes
endedintegerlabelledintegerintentsobjectgoalobjectwaiting_onobjectcontact_declinedintegerfrictionobject
toolsarray of objectTool calls in the window's chats.
expectedfailures are the tool asking for what is missing; the rest are the platform failing.5 attributes
namestringcallsintegerfailedintegerexpectedintegererrorsobject
knowledgeobjectKnowledge searches by result: unavailable is the search failing, empty is missing content.
5 attributes
searchesintegerokintegeremptyintegerunavailableintegerotherinteger
improvementChatImprovementrequiredWhat visitors said about the chat, and where it could do better. Quoted text is one line, at most 200 characters, with emails and phone numbers masked, and names masked where they follow common patterns (an introduction such as "my name is" or a greeting such as "Thanks Jane"). Other personal details can remain.
9 attributes
repliesobjectrequiredThumbs up and down on assistant replies.
4 attributes
ratedintegerrequiredupintegerrequireddownintegerrequiredreasonsobjectrequiredThumbs-down count per reason.
chats_ratedobjectrequired3 attributes
countintegerrequiredaveragenumber | nullrequireddistributionarray of integerrequiredCount of 1 to 5 star ratings, in order.
containmentobjectrequired5 attributes
chatsintegerrequiredwithout_personintegerrequiredNever asked for a person.
with_leadintegerrequiredasked_for_personintegerrequiredone_messageintegerrequiredConversations, open or ended, with exactly one visitor message and no lead.
knowledge_gapsobjectrequiredReplies whose knowledge searches all came back empty.
3 attributes
totalintegerrequiredrecentarray of objectrequired3 attributes
questionstringrequiredconversation_idstringrequiredatstringrequiredISO 8601 timestamp
toparray of objectrequiredThe same gaps grouped by question, most asked first (at most 10), with the latest wording and its chat.
4 attributes
questionstringrequiredcountintegerrequiredconversation_idstringrequiredatstringrequiredISO 8601 timestamp
unhelpfularray of objectrequiredRecent replies rated down.
4 attributes
answerstringrequiredreasonstring | nullrequiredconversation_idstringrequiredatstringrequiredISO 8601 timestamp
commentsarray of objectrequiredRecent conversation ratings that came with a comment.
4 attributes
ratingintegerrequiredcommentstringrequiredconversation_idstringrequiredatstringrequiredISO 8601 timestamp
top_fixesarray of objectrequiredChanges the conversation analysis suggested, by kind, most common first, with up to 3 of the latest as examples.
3 attributes
kindstringrequiredOne of
knowledgepromptflowsettingshandoffcountintegerrequiredChats with at least one fix of this kind.
examplesarray of objectrequired3 attributes
suggestionstringrequiredconversation_idstringrequiredseqinteger | nullrequiredThe message that shows it.
stop_pointsarray of objectrequiredAssistant messages visitors stopped replying after while something was left open (worked out in code, not by the model), grouped by structured-flow step (
step:<lead field>) when the message offered a lead field's options, else by its normalised text (text:<key>), orread_backfor a message that read the visitor's details back. Up to 10, most stops first.7 attributes
keystringrequiredstepstring | nullrequiredtextstringrequiredAn example message, masked; empty when none may be shown, such as a read-back.
labelstring | nullrequiredWhat a step asked for ("Asked for <field label>"), or a read-back's description; null for a text group.
reachedintegerrequiredAnalysed chats with this message.
stoppedintegerrequiredOf those, chats where the visitor never replied to it.
conversation_idstringrequiredThe latest chat that stopped here.
assistant_flagsobjectrequiredProblems the conversation analysis found in the assistant's own messages.
3 attributes
totalintegerrequiredkindsobjectrequiredCount per kind: wrong, invented, off_policy, unhelpful, tone.
recentarray of objectrequired5 attributes
kindstringrequiredOne of
wronginventedoff_policyunhelpfultonenotestringrequiredseqintegerrequiredconversation_idstringrequiredatstringrequiredISO 8601 timestampWhen the chat started.
partialbooleanrequiredTrue when not every send in the window could be read, so the counts are a lower bound. Retry, or narrow the range.
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/chat-analytics/quality" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"reply_ms": {
"buckets": [
{
"le_ms": 640,
"count": 1
}
],
"p50": 1,
"p90": 1,
"p95": 1,
"p99": 1,
"samples": 1,
"slow": 1
},
"first_token_ms": {
"p50": 1,
"p90": 1
},
"replies": {
"answered": 1,
"missing": 1,
"rescued": 1
},
"sends": {
"total": 1,
"failed": 1,
"quick_reply_share": 1
},
"handoff": {
"requested": 1,
"answered": 1,
"replied": 1,
"median_answer_seconds": 1
},
"leads": {
"total": 1,
"with_email": 1,
"with_phone": 1,
"with_name": 1,
"valid": 1,
"flags": {
"placeholder_email": 1,
"placeholder_phone": 1,
"business_phone": 1
},
"required_complete": 1,
"booked": 1,
"lost": 1,
"revenue": [
{
"currency": "string",
"amount": 1
}
]
},
"cost": {
"total": [
{
"currency": "string",
"amount": 1
}
],
"per_lead": [
{
"currency": "string",
"amount": 1
}
],
"per_valid_lead": [
{
"currency": "string",
"amount": 1
}
]
},
"ended_reasons": {
"key": 1
},
"chips": [
{
"text": "Hi, can I book a trip to Lisbon in May?",
"sends": 1,
"conversations": 1,
"leads": 1
}
],
"stop_points": [
{
"key": "string",
"text": "Hi, can I book a trip to Lisbon in May?",
"conversations": 1
}
],
"outcomes": {
"ended": 1,
"labelled": 1,
"intents": {
"key": 1
},
"goal": {
"key": 1
},
"waiting_on": {
"key": 1
},
"contact_declined": 1,
"friction": {
"key": 1
}
},
"tools": [
{
"name": "Front desk",
"calls": 1,
"failed": 1,
"expected": 1,
"errors": {
"key": 1
}
}
],
"knowledge": {
"searches": 1,
"ok": 1,
"empty": 1,
"unavailable": 1,
"other": 1
},
"improvement": {
"replies": {
"rated": 1,
"up": 1,
"down": 1,
"reasons": {
"key": 1
}
},
"chats_rated": {
"count": 1,
"average": 1,
"distribution": [
1
]
},
"containment": {
"chats": 1,
"without_person": 1,
"with_lead": 1,
"asked_for_person": 1,
"one_message": 1
},
"knowledge_gaps": {
"total": 1,
"recent": [
{
"question": {},
"conversation_id": {},
"at": {}
}
],
"top": [
{
"question": {},
"count": {},
"conversation_id": {},
"at": {}
}
]
},
"unhelpful": [
{
"answer": "string",
"reason": "string",
"conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"at": "2026-10-28T09:30:00.000Z"
}
],
"comments": [
{
"rating": 1,
"comment": "string",
"conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"at": "2026-10-28T09:30:00.000Z"
}
],
"top_fixes": [
{
"kind": "knowledge",
"count": 1,
"examples": [
{}
]
}
],
"stop_points": [
{
"key": "string",
"step": "string",
"text": "Hi, can I book a trip to Lisbon in May?",
"label": "string",
"reached": 1,
"stopped": 1,
"conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
}
],
"assistant_flags": {
"total": 1,
"kinds": {
"key": 1
},
"recent": [
{
"kind": "wrong",
"note": {},
"seq": {},
"conversation_id": {},
"at": {}
}
]
}
},
"partial": true
}
}List notification subscriptions
GET/api/chat-analytics/subscriptions
Where health alerts and the digest are sent: your own HTTPS endpoint or an email address. Needs the admin role, which API keys have.
Secret API key. How it works
Query parameters
project_idstringOnly this project. An org-wide key covers every project by default.
Returns
200 OK
Response attributes
dataarray of ChatSubscriptionrequired9 attributes
idstringrequiredorg_idstringproject_idstringrequiredkindstringrequiredOne of
healthdigestchannelobjectrequiredOne of 2 shapes
Option 1
typestringrequiredOne of
webhookurlstringrequireduri
Option 2
typestringrequiredOne of
emailtostringrequiredemailThe address the alerts or digest are emailed to.
enabledbooleanrequiredtimezonestringrequiredcreated_atstringISO 8601 timestampupdated_atstringISO 8601 timestamp
- 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/chat-analytics/subscriptions" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": [
{
"id": "whsub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"kind": "health",
"channel": {
"type": "webhook",
"url": "https://example.com/hook"
},
"enabled": true,
"timezone": "string",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z"
}
]
}Create a notification subscription
POST/api/chat-analytics/subscriptions
Sends health alerts (incidents opening and resolving) or a digest summary to an HTTPS URL or an email address. An org-wide key must name project_id.
Secret API key, not a viewer key. How it works
Request body
project_idstringkindstringrequiredOne of
healthdigestchannelobjectrequiredOne of 2 shapes
Option 1
typestringrequiredOne of
webhookurlstringrequireduri
Option 2
typestringrequiredOne of
emailtostringrequiredemailThe address the alerts or digest are emailed to.
timezonestringIANA zone; default UTC.
Returns
201 OK
Response attributes
dataChatSubscriptionrequired9 attributes
idstringrequiredorg_idstringproject_idstringrequiredkindstringrequiredOne of
healthdigestchannelobjectrequiredOne of 2 shapes
Option 1
typestringrequiredOne of
webhookurlstringrequireduri
Option 2
typestringrequiredOne of
emailtostringrequiredemailThe address the alerts or digest are emailed to.
enabledbooleanrequiredtimezonestringrequiredcreated_atstringISO 8601 timestampupdated_atstringISO 8601 timestamp
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Not found, or outside what the key can see
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X POST "https://api.brightshoal.com/api/chat-analytics/subscriptions" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"kind": "health",
"channel": {
"type": "webhook",
"url": "https://example.com/hook"
}
}'{
"data": {
"id": "whsub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"kind": "health",
"channel": {
"type": "webhook",
"url": "https://example.com/hook"
},
"enabled": true,
"timezone": "string",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z"
}
}Update a notification subscription
PATCH/api/chat-analytics/subscriptions/{id}
Turn a subscription on or off, or change where it sends or its time zone. Send at least one field.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredSubscription id.
Request body
enabledbooleanchannelobjectOne of 2 shapes
Option 1
typestringrequiredOne of
webhookurlstringrequireduri
Option 2
typestringrequiredOne of
emailtostringrequiredemailThe address the alerts or digest are emailed to.
timezonestring
Returns
200 OK
Response attributes
dataChatSubscriptionrequired9 attributes
idstringrequiredorg_idstringproject_idstringrequiredkindstringrequiredOne of
healthdigestchannelobjectrequiredOne of 2 shapes
Option 1
typestringrequiredOne of
webhookurlstringrequireduri
Option 2
typestringrequiredOne of
emailtostringrequiredemailThe address the alerts or digest are emailed to.
enabledbooleanrequiredtimezonestringrequiredcreated_atstringISO 8601 timestampupdated_atstringISO 8601 timestamp
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Not found, or outside what the key can see
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X PATCH "https://api.brightshoal.com/api/chat-analytics/subscriptions/SUBSCRIPTION_ID" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"enabled": true,
"channel": {
"type": "webhook",
"url": "https://example.com/hook"
}
}'{
"data": {
"id": "whsub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"kind": "health",
"channel": {
"type": "webhook",
"url": "https://example.com/hook"
},
"enabled": true,
"timezone": "string",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z"
}
}Delete a notification subscription
DELETE/api/chat-analytics/subscriptions/{id}
Stops the subscription for good. Answers 204 with no body.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredSubscription id.
Returns
204 Deleted
- 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Not found, or outside what the key can see
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X DELETE "https://api.brightshoal.com/api/chat-analytics/subscriptions/SUBSCRIPTION_ID" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"Get daily or weekly chat totals
GET/api/chat-analytics/trend
Funnel totals per day or per ISO week (weeks start on Monday), for charts over a longer range than the live views.
Secret API key. How it works
Query parameters
project_idstringOnly this project. An org-wide key covers every project by default.
assistant_idarray of stringOnly these assistants. Repeat the parameter or comma-separate the values; a row matching any of them is kept.
fromstringISO 8601 timestampDefault: 90 days before
to.tostringISO 8601 timestampDefault: now. Up to 400 days.
intervalstringOne point per day or per week.
One of
dayweekDefault
"day"
Returns
200 OK
Response attributes
dataChatTrendrequired2 attributes
intervalstringrequiredOne of
dayweekpointsarray of objectrequired10 attributes
periodstringrequiredYYYY-MM-DD; a Monday for weekly points.
page_viewsintegershownintegeropenedintegersendsintegeracceptedintegerfailedintegerconversationsintegerleadsintegerhandoffsinteger
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/chat-analytics/trend" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"interval": "day",
"points": [
{
"period": "string",
"page_views": 1,
"shown": 1,
"opened": 1,
"sends": 1,
"accepted": 1,
"failed": 1,
"conversations": 1,
"leads": 1,
"handoffs": 1
}
]
}
}