BrightshoalDocsOpen console
MenuChat analytics

API reference

Chat analytics

Web chat health, quality, the visitor funnel, trends and incidents, with notification subscriptions.

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_idstring

    Only this project. An org-wide key covers every project by default.

  • assistant_idarray of string

    Only these assistants. Repeat the parameter or comma-separate the values; a row matching any of them is kept.

  • fromstringISO 8601 timestamp

    Default: 24 hours before to.

  • tostringISO 8601 timestamp

    Default: now. Ranges over 90 days are rejected.

  • tzstring

    IANA 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
  • dataChatEngagementrequired

    7 attributes
    • fromstringISO 8601 timestamp

    • tostringISO 8601 timestamp

    • deptharray of objectrequired

      Chats by visitor messages: buckets 1, 2, 3, 4-6, 7+.

      3 attributes
      • bucketstringrequired

      • conversationsintegerrequired

      • leadsintegerrequired

    • open_to_first_messageobjectrequired

      4 attributes
      • samplesinteger

      • p50_sinteger | null

      • p90_sinteger | null

      • by_reasonobject

        2 attributes
        • samplesinteger

        • p50_sinteger | null

    • time_to_leadobjectrequired

      4 attributes
      • samplesinteger

      • p50_sinteger | null

      • p90_sinteger | null

      • p50_messagesinteger | null

    • heatmapobjectrequired

      2 attributes
      • tzstring

      • cellsarray of object

        4 attributes
        • weekdayintegerrequired

          1 (Monday) to 7.

        • hourintegerrequired

        • conversationsintegerrequired

        • leadsintegerrequired

    • out_of_hoursobjectrequired

      measured: chats whose assistant sets working hours; conversations: of those, started while closed. The same for chats with a lead.

      4 attributes
      • measuredinteger

      • conversationsinteger

      • measured_leadsinteger

      • leadsinteger

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
GET /api/chat-analytics/engagement
curl "https://api.brightshoal.com/api/chat-analytics/engagement" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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_idstring

    Only this project. An org-wide key covers every project by default.

  • assistant_idarray of string

    Only these assistants. Repeat the parameter or comma-separate the values; a row matching any of them is kept.

  • fromstringISO 8601 timestamp

    Default: 24 hours before to.

  • tostringISO 8601 timestamp

    Default: now. Ranges over 90 days are rejected.

  • cursorstring

    next_cursor from the previous page.

  • limitinteger1 to 100

    Page size.

    Default 50

Returns

200 OK

Response attributes
  • dataarray of ChatFailurerequired

    14 attributes
    • idstringrequired

    • occurred_atstringrequiredISO 8601 timestamp

    • routestringrequired

      One of config events create message

    • outcomestringrequired

    • status_codeintegerrequired

    • sitestring | null

    • sampledboolean

    • request_idstring | null

    • conversation_idstring | null

    • client_message_idstring | null

    • devicestring | null

    • browserstring | null

    • widget_versionstring | null

    • assistant_idstring | null

  • next_cursorstring | nullrequired

  • has_morebooleanrequired

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
GET /api/chat-analytics/failures
curl "https://api.brightshoal.com/api/chat-analytics/failures" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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_idstring

    Only this project. An org-wide key covers every project by default.

  • assistant_idarray of string

    Only these assistants. Repeat the parameter or comma-separate the values; a row matching any of them is kept.

  • fromstringISO 8601 timestamp

    Default: 24 hours before to.

  • tostringISO 8601 timestamp

    Default: now. Ranges over 90 days are rejected.

  • group_bystring

    Split the funnel into one group per value of this dimension. hour keys each UTC hour of the window; hour_of_day keys the hour of the day (00 to 23) in tz, adding up every day in the window. campaign and medium key the visit's utm_campaign and utm_medium, and ad_platform the ad click id its landing carried (google, meta, microsoft, openai); none when there was none and unknown without analytics consent. url_rule keys the url_rules pattern whose card showed on the page view (card_shown): none for the assistant-wide opener, no_card when no card showed.

    One of none site page device browser source hour hour_of_day open_reason visitor_type assistant campaign medium ad_platform url_rule

    Default "none"

  • tzstring

    IANA time zone hour_of_day counts its hours in, e.g. Europe/London.

    Default "UTC"

  • comparestring

    previous adds each group's counts for the window of the same length just before. average_7 adds 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 previous average_7

Returns

200 OK

Response attributes
  • dataChatFunnelrequired

    15 attributes
    • fromstringrequiredISO 8601 timestamp

    • tostringrequiredISO 8601 timestamp

    • group_bystringrequired

    • comparestring | null

      The comparison in previous, or null.

      One of previous average_7

    • tzstring

      The time zone hour_of_day was counted in.

    • signalsobject | null

      With 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 from page_exit events: 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 objectrequired

        2 attributes
        • countrystringrequired

        • page_viewsintegerrequired

      • located_page_viewsintegerrequired

      • languagesarray of objectrequired

        2 attributes
        • languagestringrequired

        • page_viewsintegerrequired

      • automated_page_viewsintegerrequired

      • exitsobjectrequired

        6 attributes
        • page_viewsintegerrequired

        • median_visible_sinteger | nullrequired

        • scrollobjectrequired

          Keys 0, 25, 50, 75, 100.

        • openedintegerrequired

          Page views where the panel opened; a card alone does not count.

        • closedintegerrequired

          Of those, the visitor closed the panel. A card put away is not a close.

        • median_closed_after_sinteger | nullrequired

      • auto_openobjectrequired

        Page views by page_exit auto_open outcome, consent_held included.

      • banner_page_viewsintegerrequired

        Page views where a cookie or consent banner was up (page_exit banner).

    • visits_sincestring | nullISO 8601 timestamp

      When this scope's first page view tied to a visit arrived; visit counts start here. Null before any did.

    • page_views_sincestring | nullISO 8601 timestamp

      When this scope's first page view the widget reported arrived; page-view stages start here. Null before any did.

    • groupsarray of objectrequired

      22 attributes
      • page_viewsobjectrequired

        Distinct page views per stage. Events without a page_view_id are excluded.

        6 attributes
        • loadedintegerrequired

        • shownintegerrequired

        • cardintegerrequired

          A card (nudge, continue, link follow-up or teaser) showed: card_shown.

        • openedintegerrequired

        • typedintegerrequired

        • sentintegerrequired

      • visitsobjectrequired

        Distinct 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
        • loadedintegerrequired

        • shownintegerrequired

        • cardintegerrequired

          A card (nudge, continue, link follow-up or teaser) showed: card_shown.

        • openedintegerrequired

        • typedintegerrequired

        • sentintegerrequired

      • opensobject

        Distinct 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.opened mixes them.

        3 attributes
        • visitorintegerrequired

        • proactiveintegerrequired

        • apiintegerrequired

      • cardsobject

        Distinct page views where each card showed (card_shown), counted separately.

        4 attributes
        • nudgeintegerrequired

        • continueintegerrequired

        • follow_upintegerrequired

        • teaserintegerrequired

      • opens_fromobject

        Distinct page views opened, by what opened them (widget_opened from): 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 predate from count in none of these.

        6 attributes
        • launcherintegerrequired

        • nudgeintegerrequired

        • continueintegerrequired

        • follow_upintegerrequired

        • apiintegerrequired

        • autointegerrequired

      • first_sendsobject

        Of conversations: by how the first message was sent (message_send source): typed, a reply chip, a starter, a nudge answer, a continue-card draft, or the contact card. Chats from widgets that predate source count in none.

        6 attributes
        • typedintegerrequired

        • replyintegerrequired

        • starterintegerrequired

        • nudgeintegerrequired

        • continueintegerrequired

        • contactintegerrequired

      • crawlersobject | null

        Page 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
        • loadedintegerrequired

        • openedintegerrequired

      • visitorsintegerrequired

        Distinct visitor ids among widget_loaded events.

      • returning_visitsintegerrequired

        Distinct visits among widget_loaded events whose visit_number is above 1.

      • identified_page_viewsintegerrequired

        Distinct page views among widget_loaded events that carry a visit_id. Divide by tracked_page_views for coverage.

      • tracked_page_viewsinteger

        Distinct 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 | nullrequired

        5 attributes
        • pressedinteger

        • acceptedinteger

        • answeredinteger

        • failedinteger

        • refusedinteger

      • conversationsinteger | nullrequired

        Chats 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 untracked when 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_conversationsinteger

        Of conversations: chats with three or more visitor messages.

      • single_message_conversationsinteger

        Of conversations: chats where the visitor sent one message and stopped.

      • leadsinteger | nullrequired

        Leads saved in the window, grouped as their chat is.

      • valid_leadsinteger

        Leads with at least one email or phone that is not a placeholder or the business's own number.

      • handoffsinteger | nullrequired

        Handoffs requested in the window, grouped as their chat is.

      • bookedinteger | nullrequired

      • convertedobject

        The 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
        • conversationsintegerrequired

        • leadsintegerrequired

        • valid_leadsintegerrequired

      • keystring | nullrequired

      • previousobject

        The 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_viewsobjectrequired

          Distinct page views per stage. Events without a page_view_id are excluded.

          6 attributes
          • loadedintegerrequired

          • shownintegerrequired

          • cardintegerrequired

            A card (nudge, continue, link follow-up or teaser) showed: card_shown.

          • openedintegerrequired

          • typedintegerrequired

          • sentintegerrequired

        • visitsobjectrequired

          Distinct 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
          • loadedintegerrequired

          • shownintegerrequired

          • cardintegerrequired

            A card (nudge, continue, link follow-up or teaser) showed: card_shown.

          • openedintegerrequired

          • typedintegerrequired

          • sentintegerrequired

        • opensobject

          Distinct 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.opened mixes them.

          3 attributes
          • visitorintegerrequired

          • proactiveintegerrequired

          • apiintegerrequired

        • cardsobject

          Distinct page views where each card showed (card_shown), counted separately.

          4 attributes
          • nudgeintegerrequired

          • continueintegerrequired

          • follow_upintegerrequired

          • teaserintegerrequired

        • opens_fromobject

          Distinct page views opened, by what opened them (widget_opened from): 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 predate from count in none of these.

          6 attributes
          • launcherintegerrequired

          • nudgeintegerrequired

          • continueintegerrequired

          • follow_upintegerrequired

          • apiintegerrequired

          • autointegerrequired

        • first_sendsobject

          Of conversations: by how the first message was sent (message_send source): typed, a reply chip, a starter, a nudge answer, a continue-card draft, or the contact card. Chats from widgets that predate source count in none.

          6 attributes
          • typedintegerrequired

          • replyintegerrequired

          • starterintegerrequired

          • nudgeintegerrequired

          • continueintegerrequired

          • contactintegerrequired

        • crawlersobject | null

          Page 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
          • loadedintegerrequired

          • openedintegerrequired

        • visitorsintegerrequired

          Distinct visitor ids among widget_loaded events.

        • returning_visitsintegerrequired

          Distinct visits among widget_loaded events whose visit_number is above 1.

        • identified_page_viewsintegerrequired

          Distinct page views among widget_loaded events that carry a visit_id. Divide by tracked_page_views for coverage.

        • tracked_page_viewsinteger

          Distinct 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 | nullrequired

          5 attributes
          • pressedinteger

          • acceptedinteger

          • answeredinteger

          • failedinteger

          • refusedinteger

        • conversationsinteger | nullrequired

          Chats 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 untracked when 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_conversationsinteger

          Of conversations: chats with three or more visitor messages.

        • single_message_conversationsinteger

          Of conversations: chats where the visitor sent one message and stopped.

        • leadsinteger | nullrequired

          Leads saved in the window, grouped as their chat is.

        • valid_leadsinteger

          Leads with at least one email or phone that is not a placeholder or the business's own number.

        • handoffsinteger | nullrequired

          Handoffs requested in the window, grouped as their chat is.

        • bookedinteger | nullrequired

        • convertedobject

          The 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
          • conversationsintegerrequired

          • leadsintegerrequired

          • valid_leadsintegerrequired

    • groups_totalintegerrequired

      Groups found; only the first 50 are returned (hours are never cut).

    • truncatedbooleanrequired

    • coverageobjectrequired

      Counted chats in the window, and those tied to a page view the widget reported.

      2 attributes
      • conversationsintegerrequired

      • trackedintegerrequired

    • excludedobjectrequired

      Chats 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
      • testintegerrequired

      • previewintegerrequired

      • internalintegerrequired

    • excluded_trafficobjectrequired

      The same left-out chats by traffic, each counted once: sandbox chats come from a non-live key (a sandbox key, the console's sandbox chat or a preview link); test chats are live chats our rules caught (a test marker, a staging or preview host, or a placeholder or own-domain lead email).

      2 attributes
      • sandboxintegerrequired

      • testintegerrequired

    • partialbooleanrequired

      True 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 in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
GET /api/chat-analytics/funnel
curl "https://api.brightshoal.com/api/chat-analytics/funnel" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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_idstring

    Only this project. An org-wide key covers every project by default.

  • assistant_idarray of string

    Only these assistants. Repeat the parameter or comma-separate the values; a row matching any of them is kept.

  • fromstringISO 8601 timestamp

    Default: 24 hours before to.

  • tostringISO 8601 timestamp

    Default: now. Ranges over 90 days are rejected.

Returns

200 OK

Response attributes
  • dataChatHealthrequired

    3 attributes
    • checkerobjectrequired

      2 attributes
      • swept_atstring | nullrequiredISO 8601 timestamp

      • stalebooleanrequired

    • partialbooleanrequired

      True when not every send in the window could be read, so the counts are a lower bound. Retry, or narrow the range.

    • sitesarray of objectrequired

      14 attributes
      • sitestring | nullrequired

      • statusstringrequired

        One of ok warning critical idle

      • page_viewsintegerrequired

      • showninteger

      • openedinteger

      • sendsintegerrequired

      • acceptedinteger

      • failedinteger

      • refusedinteger

      • failure_ratenumber | null

      • reply_ms_p50integer | null

      • reply_ms_p90integer | null

      • last_success_atstring | nullISO 8601 timestamp

      • open_incidentsintegerrequired

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
GET /api/chat-analytics/health
curl "https://api.brightshoal.com/api/chat-analytics/health" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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_idstring

    Only this project. An org-wide key covers every project by default.

  • assistant_idarray of string

    Only these assistants' incidents. Repeat the parameter or comma-separate the values; a row matching any of them is kept.

  • statusstring

    Which incidents to list.

    One of open resolved all

    Default "open"

  • cursorstring

    next_cursor from the previous page.

  • limitinteger1 to 100

    Page size.

    Default 50

Returns

200 OK

Response attributes
  • dataarray of ChatIncidentrequired

    23 attributes
    • idstringrequired

    • org_idstring

    • project_idstringrequired

    • assistant_idstring | null

    • widget_key_idstring | null

    • sitestring | null

    • rulestringrequired

    • severitystringrequired

      One of info warning critical

    • statusstringrequired

      One of open resolved

    • dedupe_keystring

    • first_seen_atstringISO 8601 timestamp

    • last_seen_atstringISO 8601 timestamp

    • occurrencesinteger

    • example_request_idstring | null

    • example_conversation_idstring | null

    • detailobject | null

    • muted_untilstring | nullISO 8601 timestamp

    • muted_bystring | null

    • resolved_atstring | nullISO 8601 timestamp

    • resolutionstring | null

      One of recovered quiet manual

    • resolved_bystring | null

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

  • next_cursorstring | nullrequired

  • has_morebooleanrequired

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
GET /api/chat-analytics/incidents
curl "https://api.brightshoal.com/api/chat-analytics/incidents" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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

  • idstringrequired

    Incident id.

Request body

  • minutesintegerrequired15 to 10080

Returns

200 OK

Response attributes
  • dataChatIncidentrequired

    23 attributes
    • idstringrequired

    • org_idstring

    • project_idstringrequired

    • assistant_idstring | null

    • widget_key_idstring | null

    • sitestring | null

    • rulestringrequired

    • severitystringrequired

      One of info warning critical

    • statusstringrequired

      One of open resolved

    • dedupe_keystring

    • first_seen_atstringISO 8601 timestamp

    • last_seen_atstringISO 8601 timestamp

    • occurrencesinteger

    • example_request_idstring | null

    • example_conversation_idstring | null

    • detailobject | null

    • muted_untilstring | nullISO 8601 timestamp

    • muted_bystring | null

    • resolved_atstring | nullISO 8601 timestamp

    • resolutionstring | null

      One of recovered quiet manual

    • resolved_bystring | null

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

  • 400 Validation error: usually invalid_request, with the failing fields in issues when 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). Wait Retry-After seconds. 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).
POST /api/chat-analytics/incidents/{id}/mute
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
}'
Response 200
{
  "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

  • idstringrequired

    Incident id.

Returns

200 OK

Response attributes
  • dataChatIncidentrequired

    23 attributes
    • idstringrequired

    • org_idstring

    • project_idstringrequired

    • assistant_idstring | null

    • widget_key_idstring | null

    • sitestring | null

    • rulestringrequired

    • severitystringrequired

      One of info warning critical

    • statusstringrequired

      One of open resolved

    • dedupe_keystring

    • first_seen_atstringISO 8601 timestamp

    • last_seen_atstringISO 8601 timestamp

    • occurrencesinteger

    • example_request_idstring | null

    • example_conversation_idstring | null

    • detailobject | null

    • muted_untilstring | nullISO 8601 timestamp

    • muted_bystring | null

    • resolved_atstring | nullISO 8601 timestamp

    • resolutionstring | null

      One of recovered quiet manual

    • resolved_bystring | null

    • created_atstringISO 8601 timestamp

    • updated_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). Wait Retry-After seconds. 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).
POST /api/chat-analytics/incidents/{id}/resolve
curl -X POST "https://api.brightshoal.com/api/chat-analytics/incidents/INCIDENT_ID/resolve" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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

  • idstringrequired

    Incident id.

Returns

200 OK

Response attributes
  • dataChatIncidentrequired

    23 attributes
    • idstringrequired

    • org_idstring

    • project_idstringrequired

    • assistant_idstring | null

    • widget_key_idstring | null

    • sitestring | null

    • rulestringrequired

    • severitystringrequired

      One of info warning critical

    • statusstringrequired

      One of open resolved

    • dedupe_keystring

    • first_seen_atstringISO 8601 timestamp

    • last_seen_atstringISO 8601 timestamp

    • occurrencesinteger

    • example_request_idstring | null

    • example_conversation_idstring | null

    • detailobject | null

    • muted_untilstring | nullISO 8601 timestamp

    • muted_bystring | null

    • resolved_atstring | nullISO 8601 timestamp

    • resolutionstring | null

      One of recovered quiet manual

    • resolved_bystring | null

    • created_atstringISO 8601 timestamp

    • updated_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). Wait Retry-After seconds. 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).
POST /api/chat-analytics/incidents/{id}/unmute
curl -X POST "https://api.brightshoal.com/api/chat-analytics/incidents/INCIDENT_ID/unmute" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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_idstring

    Only this project. An org-wide key covers every project by default.

  • assistant_idarray of string

    Only these assistants. Repeat the parameter or comma-separate the values; a row matching any of them is kept.

  • fromstringISO 8601 timestamp

    Default: 24 hours before to.

  • tostringISO 8601 timestamp

    Default: now. Ranges over 90 days are rejected.

Returns

200 OK

Response attributes
  • dataChatLeadSourcesrequired

    5 attributes
    • fromstringISO 8601 timestamp

    • tostringISO 8601 timestamp

    • leadsintegerrequired

    • first_toucharray of ChatLeadSourcerequired

      3 attributes
      • keystringrequired

      • leadsintegerrequired

      • valid_leadsintegerrequired

    • latest_paidarray of ChatLeadSourcerequired

      3 attributes
      • keystringrequired

      • leadsintegerrequired

      • valid_leadsintegerrequired

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
GET /api/chat-analytics/lead-sources
curl "https://api.brightshoal.com/api/chat-analytics/lead-sources" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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_idstring

    Only this project. An org-wide key covers every project by default.

  • assistant_idarray of string

    Only these assistants. Repeat the parameter or comma-separate the values; a row matching any of them is kept.

  • fromstringISO 8601 timestamp

    Default: 24 hours before to.

  • tostringISO 8601 timestamp

    Default: now. Ranges over 90 days are rejected.

Returns

200 OK

Response attributes
  • dataChatOutcomesBackfillrequired

    3 attributes
    • queuedintegerrequired

    • candidatesintegerrequired

    • remainingbooleanrequired

      More chats in the window still need a label: call again.

  • 400 Validation error: usually invalid_request, with the failing fields in issues when 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). Wait Retry-After seconds. 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).
POST /api/chat-analytics/outcomes/backfill
curl -X POST "https://api.brightshoal.com/api/chat-analytics/outcomes/backfill" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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_idstring

    Only this project. An org-wide key covers every project by default.

  • assistant_idarray of string

    Only these assistants. Repeat the parameter or comma-separate the values; a row matching any of them is kept.

  • fromstringISO 8601 timestamp

    Default: 24 hours before to.

  • tostringISO 8601 timestamp

    Default: now. Ranges over 90 days are rejected.

Returns

200 OK

Response attributes
  • dataChatQualityrequired

    15 attributes
    • reply_msobject

      7 attributes
      • bucketsarray of object

        2 attributes
        • le_msinteger | nullrequired

        • countintegerrequired

      • p50integer | null

      • p90integer | null

      • p95integer | null

      • p99integer | null

      • samplesinteger

        Replies measured.

      • slowinteger

        Replies slower than 15 seconds.

    • first_token_msobject

      2 attributes
      • p50integer | null

      • p90integer | null

    • repliesobject

      3 attributes
      • answeredinteger

      • missinginteger

      • rescuedinteger

    • sendsobject

      3 attributes
      • totalinteger

      • failedinteger

      • quick_reply_sharenumber | null

    • handoffobject

      4 attributes
      • requestedinteger

      • answeredinteger

        Taken over by an advisor.

      • repliedinteger

        An advisor wrote after the request.

      • median_answer_secondsinteger | null

    • leadsobject

      10 attributes
      • totalinteger

      • with_emailinteger

      • with_phoneinteger

      • with_nameinteger

      • validinteger

        With one email or phone that is not a placeholder or the business's own number.

      • flagsobject

        3 attributes
        • placeholder_emailinteger

        • placeholder_phoneinteger

        • business_phoneinteger

      • required_completeinteger | null

        Leads holding every required field; null when no assistant marks any.

      • bookedinteger

      • lostinteger

      • revenuearray of object

        2 attributes
        • currencystringrequired

        • amountnumberrequired

    • costobject

      3 attributes
      • totalarray of object

        2 attributes
        • currencystringrequired

        • amountnumberrequired

      • per_leadarray of object

        2 attributes
        • currencystringrequired

        • amountnumberrequired

      • per_valid_leadarray of object

        Chat cost over leads with a usable email or phone.

        2 attributes
        • currencystringrequired

        • amountnumberrequired

    • ended_reasonsobject

      Ended chats by how they ended (visitor_ended, idle_timeout, max_messages, error, unknown).

    • chipsarray of object

      Suggested replies visitors tapped in chats started in the window, most sent first (at most 10), masked.

      4 attributes
      • textstringrequired

      • sendsintegerrequired

      • conversationsintegerrequired

      • leadsintegerrequired

        Of conversations: chats that saved a lead.

    • stop_pointsarray of object

      Where ended chats stopped while the assistant waited on the visitor, by what it had asked (from the analysis labels).

      3 attributes
      • keystringrequired

      • textstringrequired

      • conversationsintegerrequired

    • outcomesobject

      How ended chats ended, from the analysis labels. Counts by label; labelled of ended were labelled.

      7 attributes
      • endedinteger

      • labelledinteger

      • intentsobject

      • goalobject

      • waiting_onobject

      • contact_declinedinteger

      • frictionobject

    • toolsarray of object

      Tool calls in the window's chats. expected failures are the tool asking for what is missing; the rest are the platform failing.

      5 attributes
      • namestring

      • callsinteger

      • failedinteger

      • expectedinteger

      • errorsobject

    • knowledgeobject

      Knowledge searches by result: unavailable is the search failing, empty is missing content.

      5 attributes
      • searchesinteger

      • okinteger

      • emptyinteger

      • unavailableinteger

      • otherinteger

    • improvementChatImprovementrequired

      What 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
      • repliesobjectrequired

        Thumbs up and down on assistant replies.

        4 attributes
        • ratedintegerrequired

        • upintegerrequired

        • downintegerrequired

        • reasonsobjectrequired

          Thumbs-down count per reason.

      • chats_ratedobjectrequired

        3 attributes
        • countintegerrequired

        • averagenumber | nullrequired

        • distributionarray of integerrequired

          Count of 1 to 5 star ratings, in order.

      • containmentobjectrequired

        5 attributes
        • chatsintegerrequired

        • without_personintegerrequired

          Never asked for a person.

        • with_leadintegerrequired

        • asked_for_personintegerrequired

        • one_messageintegerrequired

          Conversations, open or ended, with exactly one visitor message and no lead.

      • knowledge_gapsobjectrequired

        Replies whose knowledge searches all came back empty.

        3 attributes
        • totalintegerrequired

        • recentarray of objectrequired

          3 attributes
          • questionstringrequired

          • conversation_idstringrequired

          • atstringrequiredISO 8601 timestamp

        • toparray of objectrequired

          The same gaps grouped by question, most asked first (at most 10), with the latest wording and its chat.

          4 attributes
          • questionstringrequired

          • countintegerrequired

          • conversation_idstringrequired

          • atstringrequiredISO 8601 timestamp

      • unhelpfularray of objectrequired

        Recent replies rated down.

        4 attributes
        • answerstringrequired

        • reasonstring | nullrequired

        • conversation_idstringrequired

        • atstringrequiredISO 8601 timestamp

      • commentsarray of objectrequired

        Recent conversation ratings that came with a comment.

        4 attributes
        • ratingintegerrequired

        • commentstringrequired

        • conversation_idstringrequired

        • atstringrequiredISO 8601 timestamp

      • top_fixesarray of objectrequired

        Changes the conversation analysis suggested, by kind, most common first, with up to 3 of the latest as examples.

        3 attributes
        • kindstringrequired

          One of knowledge prompt flow settings handoff

        • countintegerrequired

          Chats with at least one fix of this kind.

        • examplesarray of objectrequired

          3 attributes
          • suggestionstringrequired

          • conversation_idstringrequired

          • seqinteger | nullrequired

            The message that shows it.

      • stop_pointsarray of objectrequired

        Assistant 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>), or read_back for a message that read the visitor's details back. Up to 10, most stops first.

        7 attributes
        • keystringrequired

        • stepstring | nullrequired

        • textstringrequired

          An example message, masked; empty when none may be shown, such as a read-back.

        • labelstring | nullrequired

          What a step asked for ("Asked for <field label>"), or a read-back's description; null for a text group.

        • reachedintegerrequired

          Analysed chats with this message.

        • stoppedintegerrequired

          Of those, chats where the visitor never replied to it.

        • conversation_idstringrequired

          The latest chat that stopped here.

      • assistant_flagsobjectrequired

        Problems the conversation analysis found in the assistant's own messages.

        3 attributes
        • totalintegerrequired

        • kindsobjectrequired

          Count per kind: wrong, invented, off_policy, unhelpful, tone.

        • recentarray of objectrequired

          5 attributes
          • kindstringrequired

            One of wrong invented off_policy unhelpful tone

          • notestringrequired

          • seqintegerrequired

          • conversation_idstringrequired

          • atstringrequiredISO 8601 timestamp

            When the chat started.

    • partialbooleanrequired

      True 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 in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
GET /api/chat-analytics/quality
curl "https://api.brightshoal.com/api/chat-analytics/quality" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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_idstring

    Only this project. An org-wide key covers every project by default.

Returns

200 OK

Response attributes
  • dataarray of ChatSubscriptionrequired

    9 attributes
    • idstringrequired

    • org_idstring

    • project_idstringrequired

    • kindstringrequired

      One of health digest

    • channelobjectrequired

      One of 2 shapes

      Option 1

      • typestringrequired

        One of webhook

      • urlstringrequireduri

      Option 2

      • typestringrequired

        One of email

      • tostringrequiredemail

        The address the alerts or digest are emailed to.

    • enabledbooleanrequired

    • timezonestringrequired

    • created_atstringISO 8601 timestamp

    • updated_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). Wait Retry-After seconds. 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).
GET /api/chat-analytics/subscriptions
curl "https://api.brightshoal.com/api/chat-analytics/subscriptions" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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_idstring

  • kindstringrequired

    One of health digest

  • channelobjectrequired

    One of 2 shapes

    Option 1

    • typestringrequired

      One of webhook

    • urlstringrequireduri

    Option 2

    • typestringrequired

      One of email

    • tostringrequiredemail

      The address the alerts or digest are emailed to.

  • timezonestring

    IANA zone; default UTC.

Returns

201 OK

Response attributes
  • dataChatSubscriptionrequired

    9 attributes
    • idstringrequired

    • org_idstring

    • project_idstringrequired

    • kindstringrequired

      One of health digest

    • channelobjectrequired

      One of 2 shapes

      Option 1

      • typestringrequired

        One of webhook

      • urlstringrequireduri

      Option 2

      • typestringrequired

        One of email

      • tostringrequiredemail

        The address the alerts or digest are emailed to.

    • enabledbooleanrequired

    • timezonestringrequired

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

  • 400 Validation error: usually invalid_request, with the failing fields in issues when 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). Wait Retry-After seconds. 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).
POST /api/chat-analytics/subscriptions
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"
  }
}'
Response 201
{
  "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

  • idstringrequired

    Subscription id.

Request body

  • enabledboolean

  • channelobject

    One of 2 shapes

    Option 1

    • typestringrequired

      One of webhook

    • urlstringrequireduri

    Option 2

    • typestringrequired

      One of email

    • tostringrequiredemail

      The address the alerts or digest are emailed to.

  • timezonestring

Returns

200 OK

Response attributes
  • dataChatSubscriptionrequired

    9 attributes
    • idstringrequired

    • org_idstring

    • project_idstringrequired

    • kindstringrequired

      One of health digest

    • channelobjectrequired

      One of 2 shapes

      Option 1

      • typestringrequired

        One of webhook

      • urlstringrequireduri

      Option 2

      • typestringrequired

        One of email

      • tostringrequiredemail

        The address the alerts or digest are emailed to.

    • enabledbooleanrequired

    • timezonestringrequired

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

  • 400 Validation error: usually invalid_request, with the failing fields in issues when 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). Wait Retry-After seconds. 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).
PATCH /api/chat-analytics/subscriptions/{id}
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"
  }
}'
Response 200
{
  "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

  • idstringrequired

    Subscription 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). Wait Retry-After seconds. 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).
DELETE /api/chat-analytics/subscriptions/{id}
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_idstring

    Only this project. An org-wide key covers every project by default.

  • assistant_idarray of string

    Only these assistants. Repeat the parameter or comma-separate the values; a row matching any of them is kept.

  • fromstringISO 8601 timestamp

    Default: 90 days before to.

  • tostringISO 8601 timestamp

    Default: now. Up to 400 days.

  • intervalstring

    One point per day or per week.

    One of day week

    Default "day"

Returns

200 OK

Response attributes
  • dataChatTrendrequired

    2 attributes
    • intervalstringrequired

      One of day week

    • pointsarray of objectrequired

      10 attributes
      • periodstringrequired

        YYYY-MM-DD; a Monday for weekly points.

      • page_viewsinteger

      • showninteger

      • openedinteger

      • sendsinteger

      • acceptedinteger

      • failedinteger

      • conversationsinteger

      • leadsinteger

      • handoffsinteger

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
GET /api/chat-analytics/trend
curl "https://api.brightshoal.com/api/chat-analytics/trend" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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
      }
    ]
  }
}