BrightshoalDocsOpen console
MenuPublic chat API

API reference

Public chat API

The versioned API for your own chat interface, in a page or an app: start a conversation with a publishable key, then send messages with the conversation token it returns. It runs the same conversations as the chat widget.

Get the widget configuration

GET/public/v1/config

What a chat interface needs before the first message: display name, greeting, quick replies, appearance, proactive rules, text overrides and (when on) attachment limits. Safe to call from a browser and cached for 60 seconds. When the assistant lists allowed_origins, a request whose Origin is not on the list is refused with 403.

Publishable key (pk_live_... or pk_test_...), from an origin it allows. How it works

Query parameters

  • keystringrequired

    Publishable key, pk_live_....

  • assistantstring

    Required with a project-scoped publishable key; ignored-if-matching for assistant-pinned keys.

Returns

200 OK

Response attributes
  • dataPublicWidgetConfigrequired

    The assistant's public web chat settings, as GET /public/v1/config (the widget's GET /public/chat/widget-config) and conversation start return them. Never includes instructions, model settings or secrets.

    21 attributes
    • namestringrequired

      Display name: appearance.display_name, or the assistant's name.

    • greetingstring

    • quick_repliesarray of string

    • hero_topicsarray of string

      Topic buttons shown before the first message.

    • appearanceobject

      Colours, position, display name and avatar.

    • proactiveobject

      When and where to open a teaser on its own.

    • stringsobject

      Interface text overrides.

    • callobject | null

      A phone number to offer in the header, when set.

    • whatsappobject

      Present when the assistant offers "Continue on WhatsApp". Get the link to open from POST /public/chat/conversations/{id}/whatsapp-ref; before there is a conversation, open https://wa.me/<digits>?text=<prefill>.

      3 attributes
      • numberstringrequired

        The business's WhatsApp number, E.164.

      • labelstringup to 40 characters

      • prefillstringup to 200 characters

        The message WhatsApp opens with.

    • contact_consentobject

      Present only when the assistant offers consent to be contacted. Once the conversation reports phone_captured, show one unticked box per option with its text exactly, and send the ticked ones to POST /public/chat/conversations/{id}/contact-consent with their version.

      1 attribute
      • optionsarray of objectrequired

        4 attributes
        • channelstringrequired

          One of whatsapp sms voice_human

        • purposestringrequired

          One of service marketing

        • versionintegerrequired

          The wording version, sent back with a tick.

        • textstringrequired

          The wording to show beside the box, unchanged.

    • handoff_messagestring | null

      What to show when the visitor asks for a person.

    • powered_byany

    • feedbackobject

      Whether to ask for reply feedback and a conversation rating.

    • attachmentsobject

      Present only when the assistant takes files and this deployment can store them.

      4 attributes
      • enabledboolean

        One of true

      • max_bytesinteger

      • max_filesinteger

        Per message.

      • acceptarray of string

        Accepted content types.

    • analyticsobject

      Off for sandbox and preview chats, so they never reach your analytics.

      4 attributes
      • data_layerboolean

      • gtagboolean

      • event_prefixstring

      • require_consentboolean

    • identity_scopestringrequired

      An opaque id for the project, the same for every key in it. Use it to name where you keep a visitor id, so a rotated or second key keeps the same visitors.

    • modestring

      Present only for a sandbox key or a preview link; a live key's config has no mode.

      One of test preview

    • uiobject

      Present only when the assistant uses the quiet chat style.

      1 attribute
      • stylestring

        One of quiet

    • dynamic_uiobject

      Present only when the assistant shows contact details as links.

      1 attribute
      • contact_linksboolean

        One of true

    • lead_capturePublicLeadSchema

      The lead details the chat asks for, so your page can show what it has captured. Present only when lead capture and dynamic_ui.lead_panel are both on.

      2 attributes
      • require_completebooleanrequired

        No lead is saved until every required field and an email or phone are in.

      • fieldsarray of objectrequired

        4 attributes
        • keystringrequired

        • labelstringrequired

          The field's short name for people to read.

        • typestringrequired

          One of string email phone number

        • requiredbooleanrequired

    • voiceobject

      Present only when the assistant takes voice in the browser and voice calls can be placed: offer a microphone button (POST /public/v1/conversations/{id}/voice).

      2 attributes
      • enabledbooleanrequired

        One of true

      • max_secondsintegerrequired

        Each voice session's length cap.

  • 403 origin_not_allowed: the request's Origin is not in the assistant's allowed_origins
  • 404 not_found: unknown or revoked key, no such assistant for it, or web chat is off for the assistant
  • 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 /public/v1/config
curl "https://api.brightshoal.com/public/v1/config?key=pk_live_..."
Response 200
{
  "data": {
    "name": "Front desk",
    "greeting": "Hi! Planning a trip? I can help.",
    "quick_replies": [
      "Lisbon in May",
      "Group bookings"
    ],
    "hero_topics": [],
    "appearance": {
      "position": "bottom-right",
      "header_style": "accent"
    },
    "proactive": {
      "enabled": false,
      "url_rules": []
    },
    "handoff_message": null,
    "powered_by": {
      "enabled": true,
      "label": "Powered by Brightshoal",
      "url": "https://brightshoal.com"
    },
    "feedback": {
      "replies": false,
      "rating": false
    },
    "analytics": {
      "data_layer": false,
      "gtag": false,
      "event_prefix": "chat_",
      "require_consent": false
    }
  }
}

Start a conversation

POST/public/v1/conversations

Starts a conversation with the assistant behind a publishable key and returns its id and token. Send the token as Authorization: Bearer ct_... on every later call for this conversation; it is returned only here. The widget starts a conversation when the visitor sends a first message, not when the panel opens. A browser page calling from its own site is checked by its Origin header against the assistant's allowed_origins (an empty list allows every site).

Publishable key (pk_live_... or pk_test_...), from an origin it allows. How it works

Request body

  • widget_keystringrequirednot empty

    Publishable key, pk_live_....

  • assistantstringnot empty

    Assistant id; required with a project-scoped publishable key.

  • parent_originstring

    The site the chat runs on, for requests that carry no Origin header of their own (your server, for example) and for the widget's own frame. A browser calling from another site is checked by its real Origin header instead, and this field is ignored, so a page cannot borrow an allowed site's name.

  • visitor_idstring

    Your stable id for the visitor, so their conversations can be grouped. Stored only when analytics consent is granted or not required.

  • visit_idstringup to 256 characters

    The visit this conversation started in. Kept in metadata.visit_id only when analytics consent is granted or not required, and only when it is 1 to 128 letters, digits, _ or -; any other string up to 256 characters is ignored, and a longer one answers 400.

  • timezonestringup to 64 characters

    The visitor's IANA time zone (for example America/New_York), so dates and callback times are theirs. A recognised zone is stored as metadata.visitor_timezone; an unknown one is ignored.

  • attributionChatAttribution

    Where the visitor came from. Sanitized, never a reason to refuse the chat. Only chat_page is kept without analytics consent.

    4 attributes
    • chat_pagestring

      The path the visitor started chatting on.

    • visitChatAttributionTouch

      This visit's landing.

      20 attributes
      • landing_pagestring

        A path starting with /, without query or fragment.

      • referrer_hoststring

      • utm_sourcestring

      • utm_mediumstring

      • utm_campaignstring

      • utm_termstring

      • utm_contentstring

      • gclidstring

      • gbraidstring

      • wbraidstring

      • fbclidstring

      • msclkidstring

      • opprefstring

      • ctwa_clidstring

        WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

      • ad_idstring

        WhatsApp only: the ad or post id (source_id) from Meta's referral.

      • ad_source_typestring

        WhatsApp only: ad or post.

      • ad_source_urlstring

        WhatsApp only: the ad's URL, up to 512 characters.

      • ad_headlinestring

        WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

      • whatsapp_link_idstring

        WhatsApp only: the campaign link (wal_...) the chat started from.

      • whatsapp_link_namestring

        WhatsApp only: that campaign link's name.

    • firstobject

      The visitor's first-ever landing.

      21 attributes
      • landing_pagestring

        A path starting with /, without query or fragment.

      • referrer_hoststring

      • utm_sourcestring

      • utm_mediumstring

      • utm_campaignstring

      • utm_termstring

      • utm_contentstring

      • gclidstring

      • gbraidstring

      • wbraidstring

      • fbclidstring

      • msclkidstring

      • opprefstring

      • ctwa_clidstring

        WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

      • ad_idstring

        WhatsApp only: the ad or post id (source_id) from Meta's referral.

      • ad_source_typestring

        WhatsApp only: ad or post.

      • ad_source_urlstring

        WhatsApp only: the ad's URL, up to 512 characters.

      • ad_headlinestring

        WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

      • whatsapp_link_idstring

        WhatsApp only: the campaign link (wal_...) the chat started from.

      • whatsapp_link_namestring

        WhatsApp only: that campaign link's name.

      • atstringISO 8601 timestamp

        When the visitor first landed.

    • latest_paidobject

      The visitor's latest ad click within 90 days: a landing with a click id, or with utm_medium cpc, ppc or paid*. Recorded even when the click came inside a visit that began elsewhere, and kept through later direct visits, so it can differ from visit and first.

      21 attributes
      • landing_pagestring

        A path starting with /, without query or fragment.

      • referrer_hoststring

      • utm_sourcestring

      • utm_mediumstring

      • utm_campaignstring

      • utm_termstring

      • utm_contentstring

      • gclidstring

      • gbraidstring

      • wbraidstring

      • fbclidstring

      • msclkidstring

      • opprefstring

      • ctwa_clidstring

        WhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.

      • ad_idstring

        WhatsApp only: the ad or post id (source_id) from Meta's referral.

      • ad_source_typestring

        WhatsApp only: ad or post.

      • ad_source_urlstring

        WhatsApp only: the ad's URL, up to 512 characters.

      • ad_headlinestring

        WhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).

      • whatsapp_link_idstring

        WhatsApp only: the campaign link (wal_...) the chat started from.

      • whatsapp_link_namestring

        WhatsApp only: that campaign link's name.

      • atstringISO 8601 timestamp

        When the visitor landed from this ad click.

  • metadataobject

    Free-form context stored on the conversation and sent in its webhooks (for example a region or campaign). The preview and attribution keys are reserved and dropped; send attribution in attribution.

  • client_message_idstringup to 128 characters

    The id of the first message you are about to send, so this request is linked to it in chat analytics.

  • page_view_idstringup to 128 characters

    The page view the chat started on, as reported to POST /public/v1/telemetry.

  • consentstring

    The visitor's analytics consent, which decides whether analytics ids are stored.

    One of granted denied not_required

  • preamblearray of objectup to 5 items

    Assistant lines your interface already showed (a greeting or proactive teaser), stored first so the transcript reads as the visitor saw it.

    1 attribute
    • contentstringrequiredup to 2000 characters

Returns

201 Conversation created

Response attributes
  • dataobjectrequired

    5 attributes
    • conversation_idstringrequired

    • tokenstringrequired

      Conversation token, ct_...: send it as Authorization: Bearer ct_... on this conversation's routes. Returned once; valid for at most 30 days (less when a sandbox key behind it is revoked, or a preview link turned off or expired).

    • statusstringrequired

      One of open

    • messagesarray of PublicMessagerequired

      Any preamble lines you sent, stored as the assistant's first messages.

      6 attributes
      • idstringrequired

        msg_...

      • rolestringrequired

        One of user assistant agent

      • contentstringrequired

      • richRichContent | nullrequired

        4 attributes
        • quick_repliesarray of object

          2 attributes
          • labelstringrequired

          • valuestringrequired

        • buttonsarray of object

          3 attributes
          • typestringrequired

            One of link upload

          • labelstringrequired

          • urlstringuri

            Link buttons only. An upload button opens the file picker.

        • metadataobject

          4 attributes
          • billingobject

            AI billing refusal on sandbox assistant messages only (test or preview mode), including the message.completed event. Absent for live visitors.

            2 attributes
            • codestringrequired

              One of ai_balance_exhausted model_price_unavailable free_request_too_large plan_limit_reached feature_not_in_plan

            • messagestringrequired

          • pageobject

            Visitor messages from the web widget: the page they sent the message from.

            2 attributes
            • pathstringrequired

            • titlestringrequired

          • channelstring

            A turn spoken in a voice session of this conversation rather than typed.

            One of voice

          • voice_session_idstring

            The voice session the turn was spoken in.

        • attachmentsarray of ConversationAttachment

          Files sent with the message. Each url is a signed link that works without credentials.

          5 attributes
          • idstringrequired

          • namestringrequired

          • content_typestringrequired

            One of image/jpeg image/png image/webp image/gif application/pdf application/vnd.openxmlformats-officedocument.wordprocessingml.document

          • sizeintegerrequired

            Bytes.

          • urlstringrequireduri

            Signed download link (GET /public/chat/attachments/{id}), valid for 24 hours (7 days in webhooks).

      • seqintegerrequired

        Position in the conversation; pass the highest you have as after_seq when polling.

      • created_atstringrequiredISO 8601 timestamp

    • configPublicWidgetConfigrequired

      The assistant's public web chat settings, as GET /public/v1/config (the widget's GET /public/chat/widget-config) and conversation start return them. Never includes instructions, model settings or secrets.

      21 attributes
      • namestringrequired

        Display name: appearance.display_name, or the assistant's name.

      • greetingstring

      • quick_repliesarray of string

      • hero_topicsarray of string

        Topic buttons shown before the first message.

      • appearanceobject

        Colours, position, display name and avatar.

      • proactiveobject

        When and where to open a teaser on its own.

      • stringsobject

        Interface text overrides.

      • callobject | null

        A phone number to offer in the header, when set.

      • whatsappobject

        Present when the assistant offers "Continue on WhatsApp". Get the link to open from POST /public/chat/conversations/{id}/whatsapp-ref; before there is a conversation, open https://wa.me/<digits>?text=<prefill>.

        3 attributes
        • numberstringrequired

          The business's WhatsApp number, E.164.

        • labelstringup to 40 characters

        • prefillstringup to 200 characters

          The message WhatsApp opens with.

      • contact_consentobject

        Present only when the assistant offers consent to be contacted. Once the conversation reports phone_captured, show one unticked box per option with its text exactly, and send the ticked ones to POST /public/chat/conversations/{id}/contact-consent with their version.

        1 attribute
        • optionsarray of objectrequired

          4 attributes
          • channelstringrequired

            One of whatsapp sms voice_human

          • purposestringrequired

            One of service marketing

          • versionintegerrequired

            The wording version, sent back with a tick.

          • textstringrequired

            The wording to show beside the box, unchanged.

      • handoff_messagestring | null

        What to show when the visitor asks for a person.

      • powered_byany

      • feedbackobject

        Whether to ask for reply feedback and a conversation rating.

      • attachmentsobject

        Present only when the assistant takes files and this deployment can store them.

        4 attributes
        • enabledboolean

          One of true

        • max_bytesinteger

        • max_filesinteger

          Per message.

        • acceptarray of string

          Accepted content types.

      • analyticsobject

        Off for sandbox and preview chats, so they never reach your analytics.

        4 attributes
        • data_layerboolean

        • gtagboolean

        • event_prefixstring

        • require_consentboolean

      • identity_scopestringrequired

        An opaque id for the project, the same for every key in it. Use it to name where you keep a visitor id, so a rotated or second key keeps the same visitors.

      • modestring

        Present only for a sandbox key or a preview link; a live key's config has no mode.

        One of test preview

      • uiobject

        Present only when the assistant uses the quiet chat style.

        1 attribute
        • stylestring

          One of quiet

      • dynamic_uiobject

        Present only when the assistant shows contact details as links.

        1 attribute
        • contact_linksboolean

          One of true

      • lead_capturePublicLeadSchema

        The lead details the chat asks for, so your page can show what it has captured. Present only when lead capture and dynamic_ui.lead_panel are both on.

        2 attributes
        • require_completebooleanrequired

          No lead is saved until every required field and an email or phone are in.

        • fieldsarray of objectrequired

          4 attributes
          • keystringrequired

          • labelstringrequired

            The field's short name for people to read.

          • typestringrequired

            One of string email phone number

          • requiredbooleanrequired

      • voiceobject

        Present only when the assistant takes voice in the browser and voice calls can be placed: offer a microphone button (POST /public/v1/conversations/{id}/voice).

        2 attributes
        • enabledbooleanrequired

          One of true

        • max_secondsintegerrequired

          Each voice session's length cap.

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 403 origin_not_allowed: the calling site is not in the assistant's allowed_origins (see parent_origin for which site that is)
  • 404 not_found: unknown or revoked key, no such assistant for it, or web chat is off for the assistant
  • 429 key_quota_exceeded: the publishable key has used a budget shared by every visitor of your site: 300 new conversations an hour, 30 an hour from one IP address, or 5,000 assistant replies a day. rate_limited is the ordinary per-address limit. Both carry Retry-After, in seconds.
POST /public/v1/conversations
curl -X POST "https://api.brightshoal.com/public/v1/conversations" \
  -H "Origin: https://www.example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "widget_key": "pk_live_4b1f0c9e2a7d4e6b8c3f5a1d9e0b7c62"
}'
Response 201
{
  "data": {
    "conversation_id": "conv_0c8e5f2a9b7d4c1e86f3a0d2b4c6e8f1",
    "token": "ct_...",
    "status": "open",
    "messages": [],
    "config": {
      "name": "Front desk"
    }
  }
}

Send a message and stream the reply

POST/public/v1/conversations/{id}/messages

Sends the visitor's message and streams the reply as server-sent events (see ChatSseEvents): usually message.accepted, then message.delta chunks and any tool.status, always ending with exactly one message.completed or error. A 200 status does not mean the turn succeeded: read to the terminal event. While a person has taken over, the stream is a single message.completed with message: null, and their reply arrives through the updates route. One turn runs at a time per conversation. Send a client_message_id so a retry after a dropped connection replays the stored result as one terminal event instead of answering twice. A retry of a turn whose reply was cut off (none stored, or a truncated one) is answered again when no person has taken over and nothing but read-only work (such as knowledge searches) ran; otherwise it ends with error turn_interrupted.

Conversation token (ct_...) returned when the conversation started. How it works

Path parameters

  • idstringrequired

    Conversation id, conv_.... An id the token does not belong to answers 401.

Request body

  • client_message_idstringup to 128 characters

    Your id for this message, unique within the conversation. Resending the same id with the same content replays the stored turn; with different content or files it is 409 message_id_conflict.

  • contentstringup to 4000 characters

    May be empty when attachment_ids is given. A message needs non-empty content, attachment_ids, or both (otherwise 422 invalid_content).

    Default ""

  • consentstring

    The visitor's analytics consent as your interface knows it now.

    One of granted denied not_required

  • attachment_idsarray of stringup to 5 items

    Ids returned by POST /public/v1/conversations/{id}/attachments for this conversation, at most 5. Each file can be sent once.

  • pageobject

    The host page the visitor sent this from. A new message stores its path (no origin, query or hash) and title as rich.metadata.page, and a web chat model reads them beside that message. A retry keeps the page stored first. A malformed or non-http(s) page is ignored, never refused.

    2 attributes
    • urlstringrequiredup to 2048 characters

    • titlestringrequiredup to 200 characters

  • page_view_idstringup to 128 characters

    The page view the visitor sent this from, as reported to POST /public/v1/telemetry. Ignored when malformed.

  • testboolean

    Marks the conversation as a test from now on, for a chat that began before the page was marked as one. Cannot be undone.

    One of true

Returns

200 SSE assistant turn

  • 401 Missing, wrong or expired conversation token, or a conversation id the token does not belong to (unauthorized; an unknown id is a 401, never a 404)
  • 403 attachments_disabled: the assistant's web chat attachments.enabled is false
  • 409 turn_in_progress (another turn is still running), conversation_ended, message_id_conflict (a replayed client_message_id with different content or attachments), attachment_already_sent or llm_not_configured
  • 422 invalid_content (no text and no files, or text over 4,000 characters), attachment_not_found or too_many_attachments
  • 429 key_quota_exceeded: the publishable key has used a budget shared by every visitor of your site: 300 new conversations an hour, 30 an hour from one IP address, or 5,000 assistant replies a day. rate_limited is the ordinary per-address limit. Both carry Retry-After, in seconds.
  • 503 chat_temporarily_unavailable: retry after Retry-After seconds (1)
POST /public/v1/conversations/{id}/messages
curl -N -X POST "https://api.brightshoal.com/public/v1/conversations/CONVERSATION_ID/messages" \
  -H "Authorization: Bearer $CONVERSATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "content": "Do you have trips to Lisbon in May?",
  "client_message_id": "9b2f6c1e-3d4a-4f5b-8c7d-0e1f2a3b4c5d",
  "page": {
    "url": "https://www.acmetravel.com/lisbon",
    "title": "Lisbon breaks"
  }
}'
Response 200
event: message.accepted
data: {}

event: message.delta
data: {"text":"We do. "}

event: message.delta
data: {"text":"Which dates suit you?"}

event: message.completed
data: {"message":{"id":"msg_...","role":"assistant","content":"We do. Which dates suit you?","seq":2},"conversation":{"status":"open","taken_over":false,"lead_id":null}}

Poll for new messages

GET/public/v1/conversations/{id}/updates

Messages after a sequence number, plus the conversation's state. Poll this while a person has taken over (their replies arrive here, not on the send stream) or after a dropped stream. Keep the highest seq you have seen and pass it as after_seq. Polling has its own rate limit: 60 a minute per conversation and IP address.

Conversation token (ct_...) returned when the conversation started. How it works

Path parameters

  • idstringrequired

    Conversation id, conv_.... An id the token does not belong to answers 401.

Query parameters

  • after_seqinteger

    Return messages with a seq greater than this. A missing or invalid value reads as 0 (everything).

    Default 0

Returns

200 Conversation state and visible messages after the cursor

Response attributes
  • dataobjectrequired

    2 attributes
    • conversationobjectrequired

      8 attributes
      • statusstringrequired

        One of open ended

      • resumableboolean

        Ended only because the visitor went quiet: the next message reopens it.

      • handoff_requested_atstring | nullrequiredISO 8601 timestamp

      • taken_overbooleanrequired

      • lead_idstring | null

        The lead this conversation created, once the visitor's details are in.

      • callback_requested_atstring | nullISO 8601 timestamp

        When the visitor's callback request was stored; null without one.

      • leadPublicChatLead | null

        Present only when the assistant's web chat dynamic_ui.lead_panel or dynamic_ui.guided is on: what this visitor has given so far (before the lead is saved too), or null before they have given anything.

        One of 2 shapes

        PublicChatLead

        • fieldsobjectrequired

        • completebooleanrequired

          An email or phone and every required field are in.

        Option 2

      • phone_capturedboolean

        Present only when the assistant's web chat consent_capture is on: the chat has the visitor's phone, so the consent boxes can be offered.

    • messagesarray of PublicMessagerequired

      6 attributes
      • idstringrequired

        msg_...

      • rolestringrequired

        One of user assistant agent

      • contentstringrequired

      • richRichContent | nullrequired

        4 attributes
        • quick_repliesarray of object

          2 attributes
          • labelstringrequired

          • valuestringrequired

        • buttonsarray of object

          3 attributes
          • typestringrequired

            One of link upload

          • labelstringrequired

          • urlstringuri

            Link buttons only. An upload button opens the file picker.

        • metadataobject

          4 attributes
          • billingobject

            AI billing refusal on sandbox assistant messages only (test or preview mode), including the message.completed event. Absent for live visitors.

            2 attributes
            • codestringrequired

              One of ai_balance_exhausted model_price_unavailable free_request_too_large plan_limit_reached feature_not_in_plan

            • messagestringrequired

          • pageobject

            Visitor messages from the web widget: the page they sent the message from.

            2 attributes
            • pathstringrequired

            • titlestringrequired

          • channelstring

            A turn spoken in a voice session of this conversation rather than typed.

            One of voice

          • voice_session_idstring

            The voice session the turn was spoken in.

        • attachmentsarray of ConversationAttachment

          Files sent with the message. Each url is a signed link that works without credentials.

          5 attributes
          • idstringrequired

          • namestringrequired

          • content_typestringrequired

            One of image/jpeg image/png image/webp image/gif application/pdf application/vnd.openxmlformats-officedocument.wordprocessingml.document

          • sizeintegerrequired

            Bytes.

          • urlstringrequireduri

            Signed download link (GET /public/chat/attachments/{id}), valid for 24 hours (7 days in webhooks).

      • seqintegerrequired

        Position in the conversation; pass the highest you have as after_seq when polling.

      • created_atstringrequiredISO 8601 timestamp

  • 401 Missing, wrong or expired conversation token, or a conversation id the token does not belong to (unauthorized; an unknown id is a 401, never a 404)
  • 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 /public/v1/conversations/{id}/updates
curl "https://api.brightshoal.com/public/v1/conversations/CONVERSATION_ID/updates" \
  -H "Authorization: Bearer $CONVERSATION_TOKEN"
Response 200
{
  "data": {
    "conversation": {
      "status": "open",
      "resumable": true,
      "handoff_requested_at": "2026-10-28T09:30:00.000Z",
      "taken_over": true,
      "lead_id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "callback_requested_at": "2026-10-28T09:30:00.000Z",
      "lead": {
        "fields": {
          "key": {}
        },
        "complete": true
      },
      "phone_captured": true
    },
    "messages": [
      {
        "id": "msg_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "role": "user",
        "content": "Hi, can I book a trip to Lisbon in May?",
        "rich": {
          "quick_replies": [
            {}
          ],
          "buttons": [
            {}
          ],
          "metadata": {
            "billing": {},
            "page": {},
            "channel": "voice",
            "voice_session_id": {}
          },
          "attachments": [
            {}
          ]
        },
        "seq": 1,
        "created_at": "2026-10-28T09:30:00.000Z"
      }
    ]
  }
}

Get a conversation's visible history

GET/public/v1/conversations/{id}

Everything the visitor can see, for rebuilding the chat after a reload: status, whether a quiet conversation can be reopened, handoff state and the visible messages. lead_name is the first name of the captured lead, when there is one.

Conversation token (ct_...) returned when the conversation started. How it works

Path parameters

  • idstringrequired

    Conversation id, conv_.... An id the token does not belong to answers 401.

Returns

200 OK

Response attributes
  • dataPublicConversationrequired

    10 attributes
    • conversation_idstringrequired

    • statusstringrequired

      One of open ended

    • ended_reasonstring | nullrequired

      Why it ended. Null while it is open.

      One of visitor_ended idle_timeout max_messages error

    • resumablebooleanrequired

      Ended only because the visitor went quiet and still inside the resume window: the next message reopens it.

    • resume_allowedbooleanrequired

      False once the chat is past the assistant's resume_days window (counted from its last message), or can no longer be carried on. A chat still open but past the window is expired too. Sends and uploads to it answer 409 conversation_ended; the widget starts a fresh chat.

    • handoff_requested_atstring | nullrequiredISO 8601 timestamp

    • taken_overbooleanrequired

      A person holds the conversation now.

    • lead_namestring

      First name of the captured lead. Present only when there is one.

    • leadPublicChatLead | null

      Present only when the assistant's web chat dynamic_ui.lead_panel or dynamic_ui.guided is on: what this visitor has given so far (before the lead is saved too), or null before they have given anything.

      One of 2 shapes

      PublicChatLead

      • fieldsobjectrequired

      • completebooleanrequired

        An email or phone and every required field are in.

      Option 2

    • messagesarray of PublicMessagerequired

      6 attributes
      • idstringrequired

        msg_...

      • rolestringrequired

        One of user assistant agent

      • contentstringrequired

      • richRichContent | nullrequired

        4 attributes
        • quick_repliesarray of object

          2 attributes
          • labelstringrequired

          • valuestringrequired

        • buttonsarray of object

          3 attributes
          • typestringrequired

            One of link upload

          • labelstringrequired

          • urlstringuri

            Link buttons only. An upload button opens the file picker.

        • metadataobject

          4 attributes
          • billingobject

            AI billing refusal on sandbox assistant messages only (test or preview mode), including the message.completed event. Absent for live visitors.

            2 attributes
            • codestringrequired

              One of ai_balance_exhausted model_price_unavailable free_request_too_large plan_limit_reached feature_not_in_plan

            • messagestringrequired

          • pageobject

            Visitor messages from the web widget: the page they sent the message from.

            2 attributes
            • pathstringrequired

            • titlestringrequired

          • channelstring

            A turn spoken in a voice session of this conversation rather than typed.

            One of voice

          • voice_session_idstring

            The voice session the turn was spoken in.

        • attachmentsarray of ConversationAttachment

          Files sent with the message. Each url is a signed link that works without credentials.

          5 attributes
          • idstringrequired

          • namestringrequired

          • content_typestringrequired

            One of image/jpeg image/png image/webp image/gif application/pdf application/vnd.openxmlformats-officedocument.wordprocessingml.document

          • sizeintegerrequired

            Bytes.

          • urlstringrequireduri

            Signed download link (GET /public/chat/attachments/{id}), valid for 24 hours (7 days in webhooks).

      • seqintegerrequired

        Position in the conversation; pass the highest you have as after_seq when polling.

      • created_atstringrequiredISO 8601 timestamp

  • 401 Missing, wrong or expired conversation token, or a conversation id the token does not belong to (unauthorized; an unknown id is a 401, never a 404)
  • 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 /public/v1/conversations/{id}
curl "https://api.brightshoal.com/public/v1/conversations/CONVERSATION_ID" \
  -H "Authorization: Bearer $CONVERSATION_TOKEN"
Response 200
{
  "data": {
    "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "status": "open",
    "ended_reason": "visitor_ended",
    "resumable": true,
    "resume_allowed": true,
    "handoff_requested_at": "2026-10-28T09:30:00.000Z",
    "taken_over": true,
    "lead_name": "string",
    "lead": {
      "fields": {
        "key": "string"
      },
      "complete": true
    },
    "messages": [
      {
        "id": "msg_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "role": "user",
        "content": "Hi, can I book a trip to Lisbon in May?",
        "rich": {
          "quick_replies": [
            {}
          ],
          "buttons": [
            {}
          ],
          "metadata": {
            "billing": {},
            "page": {},
            "channel": "voice",
            "voice_session_id": {}
          },
          "attachments": [
            {}
          ]
        },
        "seq": 1,
        "created_at": "2026-10-28T09:30:00.000Z"
      }
    ]
  }
}

Upload a file for a message

POST/public/v1/conversations/{id}/attachments

The request body is the raw file bytes (any content type), not a multipart form. Send the file name URI-encoded in X-MLF-Filename. The type is detected from the bytes, not the header or extension: JPEG, PNG, WebP, GIF, PDF and DOCX are accepted. Limits: 10 MB per file, 5 per message, 20 per conversation. Refused unless the assistant's web chat attachments.enabled is true. The file joins a message when POST /public/v1/conversations/{id}/messages names its id in attachment_ids.

Conversation token (ct_...) returned when the conversation started. How it works

Path parameters

  • idstringrequired

    Conversation id, conv_.... An id the token does not belong to answers 401.

Headers

  • X-MLF-Filenamestring

    URI-encoded file name. Defaults to file.

Request body

The file's raw bytes as the body, with the file's own Content-Type. Not multipart form data.

Returns

201 File stored

Response attributes
  • dataConversationAttachmentrequired

    5 attributes
    • idstringrequired

    • namestringrequired

    • content_typestringrequired

      One of image/jpeg image/png image/webp image/gif application/pdf application/vnd.openxmlformats-officedocument.wordprocessingml.document

    • sizeintegerrequired

      Bytes.

    • urlstringrequireduri

      Signed download link (GET /public/chat/attachments/{id}), valid for 24 hours (7 days in webhooks).

  • 401 Missing, wrong or expired conversation token, or a conversation id the token does not belong to (unauthorized; an unknown id is a 401, never a 404)
  • 403 attachments_disabled
  • 409 conversation_ended or attachment_limit_reached (20 files per conversation)
  • 413 attachment_too_large (over 10 MB)
  • 415 attachment_type_not_supported
  • 422 attachment_empty
  • 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).
  • 503 attachments_unavailable: this deployment cannot store files
POST /public/v1/conversations/{id}/attachments
curl -X POST "https://api.brightshoal.com/public/v1/conversations/CONVERSATION_ID/attachments" \
  -H "Authorization: Bearer $CONVERSATION_TOKEN" \
  -H "Content-Type: image/png" \
  --data-binary @photo.png
Response 201
{
  "data": {
    "id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "name": "Front desk",
    "content_type": "image/jpeg",
    "size": 1,
    "url": "https://example.com/hook"
  }
}

Download an attachment

GET/public/chat/attachments/{id}

Public: the signed link is the only credential. Links come from API responses (url on an upload or on a message's rich.attachments) and from webhook payloads. Links from the widget and console API last 24 hours; links in webhooks last 7 days. Both stop working sooner when the chat came from a sandbox key that is revoked or a preview link that is turned off or expires.

The signed URL is the credential; no key needed. How it works

Path parameters

  • idstringrequired

    Attachment id, att_....

Query parameters

  • expiresintegerrequired

    Link expiry, Unix seconds.

  • signaturestringrequired

    The link's signature. Use the URL as given; do not build it yourself.

Returns

200 The file bytes, with the file's own Content-Type. Content-Disposition is inline for images and attachment for documents.

  • 404 Invalid or expired link, or the file no longer exists
  • 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 /public/chat/attachments/{id}
curl "https://api.brightshoal.com/public/chat/attachments/ATTACHMENT_ID?expires=1&signature=string" \
  -o attachment

End a conversation

POST/public/v1/conversations/{id}/end

Ends the conversation for good when the visitor closes it, and triggers its conversation.ended webhook and analysis. A conversation that ended only because the visitor went quiet reopens on their next message; one ended here does not.

Conversation token (ct_...) returned when the conversation started. How it works

Path parameters

  • idstringrequired

    Conversation id, conv_.... An id the token does not belong to answers 401.

Returns

200 Conversation ended

Response attributes
  • dataobjectrequired

    1 attribute
    • statusstringrequired

      One of ended

  • 401 Missing, wrong or expired conversation token, or a conversation id the token does not belong to (unauthorized; an unknown id is a 401, never a 404)
  • 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 /public/v1/conversations/{id}/end
curl -X POST "https://api.brightshoal.com/public/v1/conversations/CONVERSATION_ID/end" \
  -H "Authorization: Bearer $CONVERSATION_TOKEN"
Response 200
{
  "data": {
    "status": "ended"
  }
}

Rate an assistant reply

POST/public/v1/conversations/{id}/messages/{messageId}/feedback

Thumbs up or down on one of the assistant's replies, with an optional reason for a thumbs down. Sending again replaces the verdict; none takes it back. Feeds the quality view in chat analytics.

Conversation token (ct_...) returned when the conversation started. How it works

Path parameters

  • idstringrequired

    Conversation id, conv_.... An id the token does not belong to answers 401.

  • messageIdstringrequired

    An assistant reply in this conversation, msg_....

Request body

  • ratingstringrequired

    One of up down none

  • reasonstring

    One of wrong unhelpful incomplete other

Returns

200 OK

Response attributes
  • dataobjectrequired

    1 attribute
    • ratingstringrequired

      One of up down none

  • 401 Missing, wrong or expired conversation token, or a conversation id the token does not belong to (unauthorized; an unknown id is a 401, never a 404)
  • 404 not_found: the message is not one of this conversation's assistant replies
  • 422 invalid_feedback
  • 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 /public/v1/conversations/{id}/messages/{messageId}/feedback
curl -X POST "https://api.brightshoal.com/public/v1/conversations/CONVERSATION_ID/messages/MESSAGE_ID/feedback" \
  -H "Authorization: Bearer $CONVERSATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "rating": "up"
}'
Response 200
{
  "data": {
    "rating": "up"
  }
}

Rate the conversation

POST/public/v1/conversations/{id}/rating

The visitor's 1 to 5 rating of the whole chat, with an optional comment. Sending again replaces it.

Conversation token (ct_...) returned when the conversation started. How it works

Path parameters

  • idstringrequired

    Conversation id, conv_.... An id the token does not belong to answers 401.

Request body

  • ratingintegerrequired1 to 5

  • commentstringup to 500 characters

Returns

200 OK

Response attributes
  • dataobjectrequired

    1 attribute
    • ratingintegerrequired1 to 5

  • 401 Missing, wrong or expired conversation token, or a conversation id the token does not belong to (unauthorized; an unknown id is a 401, never a 404)
  • 422 invalid_rating
  • 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 /public/v1/conversations/{id}/rating
curl -X POST "https://api.brightshoal.com/public/v1/conversations/CONVERSATION_ID/rating" \
  -H "Authorization: Bearer $CONVERSATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "rating": 1
}'
Response 200
{
  "data": {
    "rating": 1
  }
}

Report the visitor is still here

POST/public/v1/conversations/{id}/presence

A heartbeat while the chat is open, so a person who has taken over can see the visitor is still on the page. Presence lapses 150 seconds after the last call; send one every minute or so. No request body.

Conversation token (ct_...) returned when the conversation started. How it works

Path parameters

  • idstringrequired

    Conversation id, conv_.... An id the token does not belong to answers 401.

Returns

200 OK

Response attributes
  • dataobjectrequired

    1 attribute
    • okbooleanrequired

      One of true

  • 401 Missing, wrong or expired conversation token, or a conversation id the token does not belong to (unauthorized; an unknown id is a 401, never a 404)
  • 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 /public/v1/conversations/{id}/presence
curl -X POST "https://api.brightshoal.com/public/v1/conversations/CONVERSATION_ID/presence" \
  -H "Authorization: Bearer $CONVERSATION_TOKEN"
Response 200
{
  "data": {
    "ok": true
  }
}

Update the visitor's analytics consent

POST/public/v1/conversations/{id}/consent

Call when the visitor answers your cookie banner while a chat is open, so later analytics follow their choice.

Conversation token (ct_...) returned when the conversation started. How it works

Path parameters

  • idstringrequired

    Conversation id, conv_.... An id the token does not belong to answers 401.

Request body

  • consentstringrequired

    One of granted denied not_required

Returns

200 OK

Response attributes
  • dataobjectrequired

    1 attribute
    • consentstringrequired

      One of granted denied not_required

  • 401 Missing, wrong or expired conversation token, or a conversation id the token does not belong to (unauthorized; an unknown id is a 401, never a 404)
  • 422 invalid_consent
  • 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 /public/v1/conversations/{id}/consent
curl -X POST "https://api.brightshoal.com/public/v1/conversations/CONVERSATION_ID/consent" \
  -H "Authorization: Bearer $CONVERSATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "consent": "granted"
}'
Response 200
{
  "data": {
    "consent": "granted"
  }
}

Report chat analytics events

POST/public/v1/telemetry

The funnel events a chat interface reports (loaded, shown, opened, typed, sent, result, and how the page view ended), up to 50 per batch, which chat analytics is built from. Optional for a custom interface. Rate limited to 120 a minute per IP address (429). Past the limiter it always answers 204 with no body, even for a body it cannot read or a key it does not know, so analytics never breaks a page; such batches are dropped.

Publishable key (pk_live_... or pk_test_...), from an origin it allows. How it works

Request body

  • widget_keystringrequiredup to 256 characters

    Publishable key, pk_live_....

  • assistantstringup to 128 characters

    Assistant id; needed with a project-scoped publishable key.

  • parent_originstringup to 2048 characters

    Read as on conversation start: ignored from a browser on another site.

  • visitor_idstringup to 128 characters

  • pagestringup to 2048 characters

    The page URL the events happened on.

  • page_view_idstring

  • visit_idstring

    The visit this page view belongs to. Stored only with analytics consent.

  • visit_numberinteger1 to 1000000

    Which visit this is for the visitor: 1 for the first.

  • consentstring

    One of granted denied not_required

  • widget_versionstringup to 40 characters

  • referrerstringup to 2048 characters

  • landingstringup to 2048 characters

    The landing URL's query, read for campaign tags and never stored. With analytics consent, a widget_loaded event whose landing carries an ad click id stores which one in its properties.click_id_type (gclid, gbraid, wbraid, fbclid, msclkid or oppref, the first present in that order), never the id's value, so click-id coverage can be counted per page view and visit.

  • testboolean

  • ga_client_idstringup to 128 characters

  • ga_session_idstringup to 64 characters

  • languagestringup to 35 characters

    The browser's language (navigator.language, e.g. en-US). Stored only with analytics consent; the visitor's country and region come from the request itself, under the same rule.

  • automatedboolean

    navigator.webdriver was set: an automated browser, likely a bot.

  • eventsarray of objectrequiredup to 50 items

    Each event is checked on its own: one with a name this API does not know, or a malformed one, is dropped and the rest of the batch is stored.

    29 attributes
    • event_idstringrequired

      Unique per event, so a resent batch counts once.

    • namestringrequired

      One of widget_loaded widget_shown widget_opened composer_typed message_send message_result page_exit link_clicked card_shown card_dismissed

    • occurred_atinteger

      Milliseconds since the epoch, browser clock.

    • reasonstring

      widget_opened: why the panel opened.

      One of proactive visitor api

    • pagestringup to 2048 characters

    • conversation_idstring

    • client_message_idstring

    • statusstring

      message_result only.

      One of ok rescued failed

    • error_codestring

    • duration_msinteger0 to 3600000

    • first_token_msinteger0 to 3600000

    • attemptsinteger0 to 20

    • quick_replyboolean

    • reply_shownboolean

    • visible_sinteger0 to 86400

      page_exit: seconds the page was visible.

    • scrollinteger

      page_exit: the deepest scroll reached, as a percentage of the page.

      One of 0 25 50 75 100

    • closedboolean

      page_exit: the panel opened and the visitor closed it. A card put away is card_dismissed, not a close.

    • bannerboolean

      page_exit: a cookie or consent banner was up during the page view.

    • viewportstring

      widget_loaded: the window width: s under 480px, m under 1024px, l wider.

      One of s m l

    • cardstring

      card_shown and card_dismissed: which card.

      One of nudge continue follow_up teaser

    • rulestringup to 128 characters

      card_shown: the matched url_rules pattern; absent for the assistant-wide opener.

    • answersinteger0 to 20

      card_shown: how many answers the card offered.

    • fromstring

      widget_opened with reason visitor: what the visitor opened the chat with.

      One of launcher nudge continue continue_fresh follow_up teaser

    • sourcestring

      message_send: how the message was written or picked. quick_reply is still sent for older consumers.

      One of typed reply starter nudge continue contact

    • channelstring

      message_send from the contact card: the channel given.

      One of email phone

    • switchedboolean

      message_send from the contact card: the visitor changed channel.

    • invalidinteger0 to 20

      message_send from the contact card: submits refused as invalid before this one.

    • closed_after_sinteger0 to 86400

      page_exit: seconds between the panel opening and the visitor closing it.

    • auto_openstring

      page_exit: whether the proactive opener fired, and if not, why: off (no opener), url_rule (no rule matched the page), already_used (used or closed earlier in the visit), left_early (the page ended before the delay), chat_open, hidden (the site hid the chat), crawler, claim_refused (the once-per-visit claim was refused for another reason, such as a tab not in view), frame_not_ready (the chat frame never said ready while the page was in view), already_chatting (the visitor had already written in the chat), visitor_typing (a draft was in the composer), seen_before (shown or dismissed within repeat_after_days), consent_held (a card was ready but waited while a cookie banner was up; a card shown later still reports opened), or not_fired (unknown; older widgets send it for all of these). Send one page_exit per page view under one event_id; a later report with more visible time replaces it.

      One of opened off url_rule already_used left_early chat_open hidden crawler claim_refused frame_not_ready already_chatting visitor_typing seen_before consent_held not_fired

Returns

204 Accepted (or ignored). No body.

  • 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 /public/v1/telemetry
curl -X POST "https://api.brightshoal.com/public/v1/telemetry" \
  -H "Origin: https://www.example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "widget_key": "string",
  "events": [
    {
      "event_id": "evt_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "name": "widget_loaded"
    }
  ]
}'

Record the visitor's consent to be contacted

POST/public/v1/conversations/{id}/contact-consent

The boxes the visitor ticked, from the widget config's contact_consent, once the chat has their phone. Each becomes a grant in the consent ledger for the chat's phone with the wording shown, the page, the visitor's address and user agent, the seller and the lead and conversation. Every tick must be an option the assistant offers, in the project's current wording version, or nothing is recorded. An empty list records nothing.

Conversation token (ct_...) returned when the conversation started. How it works

Path parameters

  • idstringrequired

    Conversation id, conv_.... An id the token does not belong to answers 401.

Request body

  • consentsarray of objectrequiredup to 6 items

    3 attributes
    • channelstringrequired

      One of whatsapp sms voice_human

    • purposestringrequired

      One of service marketing

    • wording_versionintegerrequiredmin 1

Returns

200 OK

Response attributes
  • dataobjectrequired

    1 attribute
    • recordedarray of objectrequired

      4 attributes
      • channelstring

      • purposestring

      • wording_versioninteger

      • event_idstring

  • 401 Missing, wrong or expired conversation token, or a conversation id the token does not belong to (unauthorized; an unknown id is a 401, never a 404)
  • 409 phone_required: the chat has no phone yet; wording_outdated: the wording changed, reload the settings
  • 422 invalid_consent, or consent_not_offered: the assistant does not offer that channel and purpose
  • 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 /public/v1/conversations/{id}/contact-consent
curl -X POST "https://api.brightshoal.com/public/v1/conversations/CONVERSATION_ID/contact-consent" \
  -H "Authorization: Bearer $CONVERSATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "consents": [
    {
      "channel": "whatsapp",
      "purpose": "service",
      "wording_version": 1
    }
  ]
}'
Response 200
{
  "data": {
    "recorded": [
      {
        "channel": "string",
        "purpose": "string",
        "wording_version": 1,
        "event_id": "evt_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
      }
    ]
  }
}

Ask for a follow-up on a linked page

POST/public/v1/conversations/{id}/link-follow-up

The visitor opened a page the latest assistant reply linked and has stayed on it without replying: the assistant writes one short message about that page, stored with rich.metadata.follow_up (of: the reply that linked it, page). One model call with no tools, on the chat's own model and prompt. Allowed once per reply, only while the chat can be resumed, nobody has taken it over or been asked for, message_id is the latest message and an assistant reply under 30 minutes old, and one of its links (markdown or link button) has the page's path. Any other case is a 409 and nothing is written.

Conversation token (ct_...) returned when the conversation started. How it works

Path parameters

  • idstringrequired

    Conversation id, conv_.... An id the token does not belong to answers 401.

Request body

  • message_idstringrequired

    The assistant reply whose link the visitor opened.

  • pageobjectrequired

    2 attributes
    • urlstringrequiredup to 2048 characters

    • titlestringrequiredup to 200 characters

  • page_view_idstring

Returns

200 OK

Response attributes
  • dataobjectrequired

    1 attribute
    • messagePublicMessagerequired

      A message as the visitor sees it. agent is a person who took over the chat.

      6 attributes
      • idstringrequired

        msg_...

      • rolestringrequired

        One of user assistant agent

      • contentstringrequired

      • richRichContent | nullrequired

        4 attributes
        • quick_repliesarray of object

          2 attributes
          • labelstringrequired

          • valuestringrequired

        • buttonsarray of object

          3 attributes
          • typestringrequired

            One of link upload

          • labelstringrequired

          • urlstringuri

            Link buttons only. An upload button opens the file picker.

        • metadataobject

          4 attributes
          • billingobject

            AI billing refusal on sandbox assistant messages only (test or preview mode), including the message.completed event. Absent for live visitors.

            2 attributes
            • codestringrequired

              One of ai_balance_exhausted model_price_unavailable free_request_too_large plan_limit_reached feature_not_in_plan

            • messagestringrequired

          • pageobject

            Visitor messages from the web widget: the page they sent the message from.

            2 attributes
            • pathstringrequired

            • titlestringrequired

          • channelstring

            A turn spoken in a voice session of this conversation rather than typed.

            One of voice

          • voice_session_idstring

            The voice session the turn was spoken in.

        • attachmentsarray of ConversationAttachment

          Files sent with the message. Each url is a signed link that works without credentials.

          5 attributes
          • idstringrequired

          • namestringrequired

          • content_typestringrequired

            One of image/jpeg image/png image/webp image/gif application/pdf application/vnd.openxmlformats-officedocument.wordprocessingml.document

          • sizeintegerrequired

            Bytes.

          • urlstringrequireduri

            Signed download link (GET /public/chat/attachments/{id}), valid for 24 hours (7 days in webhooks).

      • seqintegerrequired

        Position in the conversation; pass the highest you have as after_seq when polling.

      • created_atstringrequiredISO 8601 timestamp

  • 401 Missing, wrong or expired conversation token, or a conversation id the token does not belong to (unauthorized; an unknown id is a 401, never a 404)
  • 409 not_web_chat, conversation_ended, taken_over, handoff_in_progress, already_followed_up, not_latest_message, link_not_found, link_too_old, conversation_full, llm_not_configured or turn_in_progress
  • 422 invalid_follow_up
  • 429 key_quota_exceeded: the publishable key has used a budget shared by every visitor of your site: 300 new conversations an hour, 30 an hour from one IP address, or 5,000 assistant replies a day. rate_limited is the ordinary per-address limit. Both carry Retry-After, in seconds.
  • 502 llm_error: the model did not answer; nothing was stored.
POST /public/v1/conversations/{id}/link-follow-up
curl -X POST "https://api.brightshoal.com/public/v1/conversations/CONVERSATION_ID/link-follow-up" \
  -H "Authorization: Bearer $CONVERSATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "message_id": "msg_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
  "page": {
    "url": "https://example.com/hook",
    "title": "Front desk"
  }
}'
Response 200
{
  "data": {
    "message": {
      "id": "msg_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "role": "user",
      "content": "Hi, can I book a trip to Lisbon in May?",
      "rich": {
        "quick_replies": [
          {
            "label": {},
            "value": {}
          }
        ],
        "buttons": [
          {
            "type": "link",
            "label": {},
            "url": {}
          }
        ],
        "metadata": {
          "billing": {
            "code": "ai_balance_exhausted",
            "message": {}
          },
          "page": {
            "path": {},
            "title": {}
          },
          "channel": "voice",
          "voice_session_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
        },
        "attachments": [
          {
            "id": {},
            "name": {},
            "content_type": "image/jpeg",
            "size": {},
            "url": {}
          }
        ]
      },
      "seq": 1,
      "created_at": "2026-10-28T09:30:00.000Z"
    }
  }
}

Start a voice session

POST/public/v1/conversations/{id}/voice

Lets the visitor talk to the assistant through their microphone, in the same conversation. Available when the assistant's web chat voice.enabled is on (the widget config then has voice), never in a preview link's chat. Join the LiveKit room at url with token before expires_at, publish the microphone and play the agent's audio. The agent knows the conversation so far and carries on from it. Live captions arrive as LiveKit text streams on topic lk.transcription: the visitor's words come from identity web_{voice_session_id}, the assistant's from the agent, with attributes lk.segment_id and lk.transcription_final. The session ends after max_seconds, when either side hangs up, or when the browser never joins. The spoken turns then join the conversation as messages with rich.metadata.channel voice (read them through the updates route), and the conversation is checked for a lead. One session per conversation at a time.

Conversation token (ct_...) returned when the conversation started. How it works

Path parameters

  • idstringrequired

    Conversation id, conv_.... An id the token does not belong to answers 401.

Request body

  • consentobjectrequired

    The visitor agreed to use their microphone. Ask before you call this.

    1 attribute
    • microphonebooleanrequired

      One of true

Returns

201 Voice session started

Response attributes
  • dataobjectrequired

    5 attributes
    • voice_session_idstringrequired

      Keep it to read or end the session.

    • urlstringrequired

      The LiveKit server to join, wss://....

    • tokenstringrequired

      A room token for this browser only.

    • expires_atstringrequiredISO 8601 timestamp

      Join before this. The session itself then runs up to max_seconds.

    • max_secondsintegerrequired

      The session's length cap, 60 to 600 seconds.

  • 400 consent_required: the body did not carry consent.microphone: true
  • 401 Missing, wrong or expired conversation token, or a conversation id the token does not belong to (unauthorized; an unknown id is a 401, never a 404)
  • 403 voice_disabled (voice is off for the assistant, or this is a preview chat) or origin_not_allowed
  • 404 Not found, or outside what the key can see
  • 409 voice_session_active (one is already running: end it first; voice_session_id names it when known), conversation_ended, or conversation_taken_over (a person is answering)
  • 429 key_quota_exceeded: the publishable key has started 60 voice sessions this hour, 10 from this IP address, or used its 300 voice minutes for the UTC day. voice_busy: the key already has 5 sessions running. rate_limited: the ordinary per-address limit. All carry Retry-After, in seconds.
  • 503 voice_unavailable: voice calls cannot be placed right now. When the cause is passing it carries Retry-After (5 seconds); without the header, voice is not set up on this deployment.
POST /public/v1/conversations/{id}/voice
curl -X POST "https://api.brightshoal.com/public/v1/conversations/CONVERSATION_ID/voice" \
  -H "Authorization: Bearer $CONVERSATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "consent": {
    "microphone": true
  }
}'
Response 201
{
  "data": {
    "voice_session_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "url": "https://example.com/hook",
    "token": "string",
    "expires_at": "2026-10-28T09:30:00.000Z",
    "max_seconds": 1
  }
}

Get a voice session

GET/public/v1/conversations/{id}/voice/{voiceSessionId}

Whether the session is still connecting, running or over, and why it ended. Only sessions of this conversation are found.

Conversation token (ct_...) returned when the conversation started. How it works

Path parameters

  • idstringrequired

    Conversation id, conv_.... An id the token does not belong to answers 401.

  • voiceSessionIdstringrequired

    The voice_session_id that starting the session returned.

Returns

200 OK

Response attributes
  • dataobjectrequired

    4 attributes
    • voice_session_idstringrequired

      The voice session's id, which is also its call's id.

    • statusstringrequired

      One of connecting active ended

    • ended_reasonstring | nullrequired

      Null until the session ends. Then the call's ended reason (for example customer_hangup, assistant_ended or max_duration), visitor_ended when you ended it through this API, not_joined when the browser never joined, or expired.

    • max_secondsinteger | nullrequired

      The session's length cap, in seconds.

  • 401 Missing, wrong or expired conversation token, or a conversation id the token does not belong to (unauthorized; an unknown id is a 401, never a 404)
  • 404 not_found: no such voice session in this conversation
  • 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 /public/v1/conversations/{id}/voice/{voiceSessionId}
curl "https://api.brightshoal.com/public/v1/conversations/CONVERSATION_ID/voice/VOICE_SESSION_ID" \
  -H "Authorization: Bearer $CONVERSATION_TOKEN"
Response 200
{
  "data": {
    "voice_session_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "status": "connecting",
    "ended_reason": "string",
    "max_seconds": 1
  }
}

End a voice session

POST/public/v1/conversations/{id}/voice/{voiceSessionId}/end

Hangs up for both sides. Safe to repeat: a session that already ended answers with its state. The conversation stays open for typing.

Conversation token (ct_...) returned when the conversation started. How it works

Path parameters

  • idstringrequired

    Conversation id, conv_.... An id the token does not belong to answers 401.

  • voiceSessionIdstringrequired

    The voice_session_id that starting the session returned.

Returns

200 OK

Response attributes
  • dataobjectrequired

    4 attributes
    • voice_session_idstringrequired

      The voice session's id, which is also its call's id.

    • statusstringrequired

      One of connecting active ended

    • ended_reasonstring | nullrequired

      Null until the session ends. Then the call's ended reason (for example customer_hangup, assistant_ended or max_duration), visitor_ended when you ended it through this API, not_joined when the browser never joined, or expired.

    • max_secondsinteger | nullrequired

      The session's length cap, in seconds.

  • 401 Missing, wrong or expired conversation token, or a conversation id the token does not belong to (unauthorized; an unknown id is a 401, never a 404)
  • 404 not_found: no such voice session in this conversation
  • 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).
  • 503 voice_unavailable: the call could not be ended just now and may still be running. Retry after Retry-After seconds.
POST /public/v1/conversations/{id}/voice/{voiceSessionId}/end
curl -X POST "https://api.brightshoal.com/public/v1/conversations/CONVERSATION_ID/voice/VOICE_SESSION_ID/end" \
  -H "Authorization: Bearer $CONVERSATION_TOKEN"
Response 200
{
  "data": {
    "voice_session_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "status": "connecting",
    "ended_reason": "string",
    "max_seconds": 1
  }
}

Get the Continue on WhatsApp link

POST/public/v1/conversations/{id}/whatsapp-ref

The wa.me link for the assistant's WhatsApp number, its text the configured prefill (or "Hi, I was chatting on your website.") followed by "(ref CODE)". The first WhatsApp message carrying the code links the WhatsApp conversation to this one and copies this chat's attribution as far as its analytics consent allows. The code lasts 7 days and is reused until then, so calling again returns the same link. No request body.

Conversation token (ct_...) returned when the conversation started. How it works

Path parameters

  • idstringrequired

    Conversation id, conv_.... An id the token does not belong to answers 401.

Returns

200 OK

Response attributes
  • dataobjectrequired

    2 attributes
    • urlstringrequireduri

    • expires_atstringrequiredISO 8601 timestamp

  • 401 Missing, wrong or expired conversation token, or a conversation id the token does not belong to (unauthorized; an unknown id is a 401, never a 404)
  • 404 whatsapp_not_configured: the assistant offers no WhatsApp number.
  • 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 /public/v1/conversations/{id}/whatsapp-ref
curl -X POST "https://api.brightshoal.com/public/v1/conversations/CONVERSATION_ID/whatsapp-ref" \
  -H "Authorization: Bearer $CONVERSATION_TOKEN"
Response 200
{
  "data": {
    "url": "https://example.com/hook",
    "expires_at": "2026-10-28T09:30:00.000Z"
  }
}