API reference
Conversations
Web chat conversations with their messages, costs and lead. Your team can take one over, reply as a person and hand it back to the assistant.
- GET
/api/conversationsList conversations - GET
/api/conversations/{id}Get a conversation - PUT
/api/conversations/{id}/callbackMark a callback made, or reopen it - GET
/api/conversations/{id}/journeyThe visits this conversation's visitor made to the site - POST
/api/conversations/{id}/messagesSend a message as a person - POST
/api/conversations/{id}/releaseHand a conversation back to the assistant - POST
/api/conversations/{id}/reply-suggestionsDraft unsent replies for a conversation - POST
/api/conversations/{id}/takeoverTake over a conversation - POST
/api/conversations/{id}/takeover/heartbeatKeep a takeover alive - GET
/api/conversations/handoff-summarySummarize human handoffs - GET
/api/test-dataCount a project's sandbox data - POST
/api/test-data/clearClear a project's sandbox and preview chats and leads
List conversations
GET/api/conversations
Web chat and WhatsApp conversations, newest first by default, one cursor page at a time. Each row is the conversation without its messages; fetch one by id for the transcript. Sandbox conversations are left out unless include_test=true.
Secret API key. How it works
Query parameters
project_idstringOnly this project's conversations (an org-wide key sees every project by default).
assistant_idarray of stringOnly these assistants' conversations. Repeat the parameter or comma-separate the values; a row matching any of them is kept.
statusstringOnly open or only ended conversations.
One of
openendedqstringCase-insensitive literal substring across conversation id, lead name/email/phone, analysis summary and visitor messages.
fromstringISO 8601 timestampCreated at or after this time (ISO 8601 with an offset).
tostringISO 8601 timestampCreated at or before this time (ISO 8601 with an offset).
engagementstringengaged: the visitor replied at least once.no_reply: they never did.One of
engagedno_replyallDefault
"all"handoffstringrequested: a handoff was asked for. pending: asked for, nobody has taken over, chat open. answered: a human took over at or after the request. missed: the chat ended before anyone took over (never an abandoned chat). missed_in_hours: missed, asked while advisors were said to be available. out_of_hours: asked while advisors were said to be unavailable (outside working hours). active: someone holds the seat now. taken_over: a human took over at least once, asked for or not. abandoned: a human took over and then left the visitor waiting (human_outcome abandoned).
One of
requestedpendingansweredmissedmissed_in_hoursout_of_hoursactivetaken_overabandonedcallbackstringrequested: the visitor left a callback request. open: requested and not yet marked called. done: marked called (PUT /conversations/{id}/callback).
One of
requestedopendoneinclude_testbooleanSandbox chats (metadata.test, e.g. the console's sandbox chat) are left out unless this is true. Ignored when
modeis given.Default
falsemodestringWhich chats to include, by the mode the server gave each. Absent: sandbox and preview chats are left out, and so are live chats a page marked as a test, as before. live: every live-mode chat, including those a page marked as a test. test: sandbox chats (stored mode
test). preview: preview chats. all: every chat.One of
livetestpreviewalltrafficstringComma-separated subset of real, sandbox and test: only chats of those kinds. When given it replaces the default view (and
include_test); an explicitmodestill narrows. Absent: the default view, unchanged.needs_reviewbooleanWhen true, only conversations whose analysis flagged the human advisor's replies with severity 2 or more (see ConversationAnalysis.human_review).
intentstringOnly chats whose outcome label has this intent (ConversationAnalysis outcome).
One of
new_enquiryinformationexisting_customerhuman_requestjob_or_vendorspam_or_testotherunknownexclude_intentstringExclude chats with this latest analysis intent; keep chats without analysis or intent.
One of
new_enquiryinformationexisting_customerhuman_requestjob_or_vendorspam_or_testotherunknowngoalstringOnly chats whose outcome label says whether the visitor got what they came for.
One of
metpartly_metnot_metunknownfrictionstringOnly chats whose outcome label lists this friction sign.
One of
contact_pushedprice_not_givenquestion_unansweredrepeated_questionwrong_or_unclear_answerforced_choicebot_errorratinginteger1 to 5Only chats the visitor rated with this many stars.
leadstringyes: only chats that saved a lead.no: only chats without one.missed: only missed leads (seemissed_leadon Conversation).One of
yesnomissedended_reasonstringOnly chats that ended this way and that the visitor wrote in.
One of
visitor_endedidle_timeoutmax_messageserrorsourcestringOnly chats with this source on the
touchattribution: the UTM source, else the referrer host without www, elsedirect; onlatest_paid, the ad platform (google,meta,microsoft,openai), else the UTM source, elsepaid.not_recordedmatches chats with no such touch.touchstringWhich attribution touch
sourcereads.One of
firstvisitlatest_paidDefault
"visit"channelstringOnly chats on this channel.
One of
web_chatwhatsapplead_fromstringISO 8601 timestampOnly chats whose lead was saved at or after this time (ISO 8601 with offset).
lead_tostringISO 8601 timestampOnly chats whose lead was saved before this time (ISO 8601 with offset).
taken_over_bystringOnly conversations this operator id (the takeover
agent.id) holds or held.sortstringSort by creation time or by number of messages.
One of
created_atmessage_countDefault
"created_at"dirstringSort direction.
One of
ascdescDefault
"desc"cursorstringnext_cursorfrom the previous page. Keep the same filters and sort while paging.limitinteger1 to 200Page size.
Default
50include_totalbooleanWhen true, the response carries
total: the number of conversations matching every filter, ignoring the cursor.Default
false
Returns
200 OK
Response attributes
dataarray of Conversationrequired46 attributes
idstringconversation_idstringAlias used by the public resume surface.
org_idstringproject_idstringassistant_idstringwidget_key_idstring | nullchannelstringOne of
web_chatwhatsappmodestringSet by the server from the key the chat came in on: sandbox chats run the draft, preview chats send nothing out.
One of
livetestpreviewtrafficstringOperator list and detail only. Which traffic this belongs to:
sandbox(made through a non-live key: a sandbox key, the console's sandbox chat, a sandbox phone or WhatsApp number, or a preview link),test(a live chat or lead one of our rules caught: a test marker, a staging or preview page, a placeholder or own-domain email, or marked as test by hand) orreal. Sandbox wins over test. Sandbox and test are both left out of real numbers.One of
realsandboxteststatusstringrequiredOne of
openendedended_reasonstring | nullOne of
visitor_endedidle_timeoutmax_messageserrorresumablebooleanPublic resume surface: ended only because the visitor went quiet, so the next message reopens it.
handoff_requested_atstring | nullISO 8601 timestamptaken_over_atstring | nullISO 8601 timestamptaken_over_heartbeat_atstring | nullISO 8601 timestamptaken_over_bystring | nulltaken_over_by_namestring | nulltaken_overbooleanfirst_taken_over_atstring | nullISO 8601 timestampFirst time a human took over; unlike taken_over_at, never cleared.
handoff_answered_atstring | nullISO 8601 timestampFirst takeover at or after handoff_requested_at.
handoff_in_hoursboolean | nullWhether the bot told the visitor advisors were available when they first asked for a person, by the assistant's working hours (none configured counts as available). Null when unknown, as on requests from before 7 October 2026 without a stored answer.
handoff_statusstringmissed: the chat ended before anyone took over. abandoned: a human took over and then left the visitor waiting; it takes precedence over the others.
One of
nonependingansweredmissedabandonedhandoff_answer_secondsinteger | nullhuman_outcomestring | nullNull when no human took part. handled: every visitor message to the human got a human reply. abandoned: at least one did not, before the bot replied, the chat ended, or (chat still open) 5 minutes passed. Recomputed when a seat is released, when the chat ends, and on each analysis run.
One of
handledabandonedhuman_metricsHumanMetrics | nullOne of 2 shapes
HumanMetrics
first_response_secondsinteger | nullrequiredFrom the first takeover to the first human message.
longest_wait_secondsinteger | nullrequiredThe longest a visitor waited on the human, answered or not.
unanswered_countintegerrequiredVisitor messages to the human that no human answered.
agent_message_countintegerrequired
Option 2
needs_reviewbooleanOperator list only: the analysis flagged the human advisor's replies with severity 2 or more.
missed_leadbooleanOperator list and detail only. A live web chat that ended without a lead: the visitor gave no email or phone, but gave a name or company and at least one other detail. Chats the analysis labelled job_or_vendor, spam_or_test or existing_customer are left out.
visitor_idstring | nullparent_originstring | nulllast_message_atstring | nullISO 8601 timestampmessage_countintegerlead_idstring | nullmetadataobject | nullcallbackobject | nullOne of 2 shapes
Option 1
phonestringrequiredslot_startstringISO 8601 timestampnotestringrequested_atstringrequiredISO 8601 timestampdone_atstringISO 8601 timestampWhen staff marked the callback made; absent while it is open. A new request from the visitor replaces the callback, open again.
done_bystringWho marked it: a user id, or the
agent.idan API key named.done_by_namestring
Option 2
ended_atstring | nullISO 8601 timestampcreated_atstringISO 8601 timestampupdated_atstringISO 8601 timestampmessagesarray of ConversationMessage12 attributes
idstringrequiredconversation_idstringorg_idstringproject_idstringrolestringrequiredOne of
userassistantagenttoolsystemcontentstringrequiredrichRichContent | null4 attributes
quick_repliesarray of object2 attributes
labelstringrequiredvaluestringrequired
buttonsarray of object3 attributes
typestringrequiredOne of
linkuploadlabelstringrequiredurlstringuriLink buttons only. An upload button opens the file picker.
metadataobject4 attributes
billingobjectAI billing refusal on sandbox assistant messages only (test or preview mode), including the message.completed event. Absent for live visitors.
2 attributes
codestringrequiredOne of
ai_balance_exhaustedmodel_price_unavailablefree_request_too_largeplan_limit_reachedfeature_not_in_planmessagestringrequired
pageobjectVisitor messages from the web widget: the page they sent the message from.
2 attributes
pathstringrequiredtitlestringrequired
channelstringA turn spoken in a voice session of this conversation rather than typed.
One of
voicevoice_session_idstringThe voice session the turn was spoken in.
attachmentsarray of ConversationAttachmentFiles sent with the message. Each
urlis a signed link that works without credentials.5 attributes
idstringrequirednamestringrequiredcontent_typestringrequiredOne of
image/jpegimage/pngimage/webpimage/gifapplication/pdfapplication/vnd.openxmlformats-officedocument.wordprocessingml.documentsizeintegerrequiredBytes.
urlstringrequireduriSigned download link (GET /public/chat/attachments/{id}), valid for 24 hours (7 days in webhooks).
tool_callsarray of object | nulltool_call_idstring | nullseqintegercreated_atstringrequiredISO 8601 timestampupdated_atstringISO 8601 timestamp
costsarray of objectleadLead | nullOne of 2 shapes
Lead
idstringrequiredorg_idstringrequiredproject_idstringrequiredassistant_idstring | nullThe assistant that captured the lead; null when no assistant did (a form lead, or one added by hand).
conversation_idstring | nullnamestring | nullemailstring | nullemailphonestring | nullfact_provenanceobjectProvenance per field key, including name, email and phone. Legacy values use lead creation time with captured_at_estimated true; edits retain captured_at and set edited_at and edited_by.
9 attributes
sourcestringrequiredOne of
conversationchannelformmanualchannelstringrequiredOne of
web_chatweb_callphone_callsmswhatsappformad_formschedulingotherconversation_idstring | nullrequiredcall_idstring | nullrequiredform_submission_idstring | nullrequiredcaptured_atstringrequiredISO 8601 timestampcaptured_at_estimatedbooleanrequirededited_atstring | nullrequiredISO 8601 timestampedited_bystring | nullrequired
fieldsobject | nullsourcestringrequiredWhere the lead came from:
web_chat,web_call(a call from a browser),phone_call,sms,whatsapp,form,ad_form(an ad platform's own lead form, such as a Google lead form),scheduling(a booking) orother(such as a lead added by hand).One of
web_chatweb_callphone_callsmswhatsappformad_formschedulingothermodestringCapture provenance: the chat mode, independent of email classification.
One of
livetestpreviewtestbooleanEffective left-out status, sandbox or test together: non-live capture mode, or the member override when set, otherwise the automatic classification. See
trafficto tell them apart.trafficstringWhich traffic this belongs to:
sandbox(made through a non-live key: a sandbox key, the console's sandbox chat, a sandbox phone or WhatsApp number, or a preview link),test(a live chat or lead one of our rules caught: a test marker, a staging or preview page, a placeholder or own-domain email, or marked as test by hand) orreal. Sandbox wins over test. Sandbox and test are both left out of real numbers.One of
realsandboxtesttest_reasonstring | nullAutomatic classification, recomputed when saved:
reserved_domain(placeholder email),business_domain(your own email domain) orstaging_site(a live chat on a staging or preview page). An email reason wins over staging_site.One of
reserved_domainbusiness_domainstaging_sitetest_overrideboolean | nullMember override. Null follows automatic classification; leads from sandbox (non-live) chats always remain sandbox.
outcomestring | nullWhat became of the lead, as your CRM reports it (PUT /leads/{id}/outcome).
One of
openbookedlostoutcome_valuestring | nullBooking value as a decimal string.
outcome_currencystring | nulloutcome_atstring | nullISO 8601 timestampoutcome_refstring | nullThe CRM's own id for the booking.
customer_idstring | nullThe customer's own id for this person, set with PUT /v1/leads/{id}/outcome.
statusstringThe front desk's progress on the lead (PUT /v1/leads/{id}/status). Every lead starts
new.new,contactedandqualifiedare open;wonandlostclose it. Separate fromoutcome, which your CRM reports.One of
newcontactedqualifiedwonloststatus_changed_atstring | nullISO 8601 timestampstatus_changed_bystring | nullA user id, or the
agent.idan API key named.status_changed_by_namestring | nullattributionChatAttribution | nullWhere the lead's chat came from. Returned by the list and detail reads; null when none was recorded.
One of 2 shapes
ChatAttribution
chat_pagestringThe path the visitor started chatting on.
visitChatAttributionTouchThis visit's landing.
20 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
firstobjectThe visitor's first-ever landing.
21 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
atstringISO 8601 timestampWhen the visitor first landed.
latest_paidobjectThe visitor's latest ad click within 90 days: a landing with a click id, or with
utm_mediumcpc, 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 fromvisitandfirst.21 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
atstringISO 8601 timestampWhen the visitor landed from this ad click.
Option 2
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestampcapture_methodstringHow the lead was first saved:
tool(the assistant saved it during the conversation),analysis(read from the conversation afterwards),form(a form submission)manual(added by hand) orscheduling(a direct booking). Later updates never change it.One of
toolanalysisformmanualschedulingcall_idstring | nullThe call the lead came from, when it came from one.
form_submission_idstring | nullThe form submission the lead came from, when it came from one.
phone_e164string | nullphonein E.164 form when it could be read as a number;phonestays as given.phone_sourcestring | nullcaller_idwhen a call lead'sphoneis the number the call came from, because the caller never said one. Null means the person gave it.One of
givencaller_idfirst_contacted_atstring | nullISO 8601 timestampThe first contact: the earliest logged contact, or the first status change out of
newby a person or key. Null until contacted.last_contacted_atstring | nullISO 8601 timestampThe latest contact.
next_follow_up_atstring | nullISO 8601 timestampWhen to contact the lead again. Cleared when the lead is won or lost.
time_to_first_contact_secondsinteger | nullWall clock from
created_attofirst_contacted_at, in seconds. Null until contacted.uncontacted_nudged_atstring | nullISO 8601 timestampWhen
lead.uncontactedwas recorded for the lead; null when it never was.merged_into_idstring | nullThe kept lead's id when this lead was merged. Merged leads remain readable by id.
Option 2
handoff_summaryobject | nullOperator list only. The structured handoff from the latest analysis.
One of 2 shapes
Option 1
wantsstringrequiredup to 1200 charactersdone_by_assistantarray of stringrequiredup to 5 itemsneeds_youarray of stringrequiredup to 5 items
Option 2
summarystring | nullOperator list only: the latest background summary, when analysis is on.
intentstring | nullOperator list only: the latest analysis intent, or null when none is recorded.
One of
new_enquiryinformationexisting_customerhuman_requestjob_or_vendorspam_or_testotherunknownlast_visitor_messagestring | nullup to 200 charactersOperator list only: the newest user message by sequence, trimmed and limited to 200 characters. Null when none exists.
analysisConversationAnalysis | nullOperator detail only: the latest background summary and extracted facts.
One of 2 shapes
ConversationAnalysis
handoff_summaryobject | nullWants, completed assistant actions, and unresolved human tasks. Null for older or unvalidated analyses. Shares through_seq with the analysis.
One of 2 shapes
Option 1
wantsstringrequiredup to 1200 charactersdone_by_assistantarray of stringrequiredup to 5 itemsneeds_youarray of stringrequiredup to 5 items
Option 2
summarystring | nullrequiredstructuredobjectrequiredThe configured
channels.web_chat.analysis.fieldsthe chat stated, keyed by field key.through_seqintegerrequiredThe last message seq the run read.
human_reviewHumanReview | nullNull when no human took part.
One of 2 shapes
HumanReview
flagsarray of objectrequired3 attributes
codestringrequiredOne of
unanswered_questionspelling_grammarunprofessional_tonebroken_promisewrong_factotherleft_mid_chatslow_replyseverityintegerrequired1 to 3evidencestringrequiredup to 200 charactersA paraphrase; never contact details.
reviewed_through_seqintegerrequiredThe last message seq the model review read.
Option 2
needs_reviewbooleanhuman_review has a flag of severity 2 or more.
updated_atstringrequiredISO 8601 timestamp
Option 2
live_handoffbooleanOperator detail only: whether the org takes web chats over live. When false, takeover is refused with 409 live_handoff_disabled.
next_cursorstring | nullrequiredOpaque pagination cursor.
has_morebooleanrequiredtotalintegermin 0Conversations matching the filters across all pages. Present only when include_total=true.
live_handoffbooleanrequiredWhether the org takes web chats over live. When false, takeover is refused and handoff requests are callback requests.
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/conversations" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": [
{
"id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"widget_key_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"channel": "web_chat",
"mode": "live",
"traffic": "real",
"status": "open",
"ended_reason": "visitor_ended",
"resumable": true,
"handoff_requested_at": "2026-10-28T09:30:00.000Z",
"taken_over_at": "2026-10-28T09:30:00.000Z",
"taken_over_heartbeat_at": "2026-10-28T09:30:00.000Z",
"taken_over_by": "string",
"taken_over_by_name": "string",
"taken_over": true,
"first_taken_over_at": "2026-10-28T09:30:00.000Z",
"handoff_answered_at": "2026-10-28T09:30:00.000Z",
"handoff_in_hours": true,
"handoff_status": "none",
"handoff_answer_seconds": 1,
"human_outcome": "handled",
"human_metrics": {
"first_response_seconds": 1,
"longest_wait_seconds": 1,
"unanswered_count": 1,
"agent_message_count": 1
},
"needs_review": true,
"missed_lead": true,
"visitor_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"parent_origin": "https://www.example.com",
"last_message_at": "2026-10-28T09:30:00.000Z",
"message_count": 1,
"lead_id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"metadata": {},
"callback": {
"phone": "+14155550123",
"slot_start": "2026-10-28T09:30:00.000Z",
"note": "string",
"requested_at": "2026-10-28T09:30:00.000Z",
"done_at": "2026-10-28T09:30:00.000Z",
"done_by": "string",
"done_by_name": "string"
},
"ended_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z",
"messages": [
{
"id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"role": "user",
"content": "Hi, can I book a trip to Lisbon in May?",
"rich": {
"quick_replies": {},
"buttons": {},
"metadata": {},
"attachments": {}
},
"tool_calls": [
{}
],
"tool_call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"seq": 1,
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z"
}
],
"costs": [
{}
],
"lead": {
"id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"email": "ana@example.com",
"phone": "+14155550123",
"fact_provenance": {
"key": {}
},
"fields": {
"key": {}
},
"source": "web_chat",
"mode": "live",
"test": true,
"traffic": "real",
"test_reason": "reserved_domain",
"test_override": true,
"outcome": "open",
"outcome_value": "string",
"outcome_currency": "string",
"outcome_at": "2026-10-28T09:30:00.000Z",
"outcome_ref": "string",
"customer_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"status": "new",
"status_changed_at": "2026-10-28T09:30:00.000Z",
"status_changed_by": "string",
"status_changed_by_name": "string",
"attribution": {},
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z",
"capture_method": "tool",
"call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"form_submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"phone_e164": "+14155550123",
"phone_source": "given",
"first_contacted_at": "2026-10-28T09:30:00.000Z",
"last_contacted_at": "2026-10-28T09:30:00.000Z",
"next_follow_up_at": "2026-10-28T09:30:00.000Z",
"time_to_first_contact_seconds": 1,
"uncontacted_nudged_at": "2026-10-28T09:30:00.000Z",
"merged_into_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
},
"handoff_summary": {
"wants": "string",
"done_by_assistant": [
{}
],
"needs_you": [
{}
]
},
"summary": "string",
"intent": "new_enquiry",
"last_visitor_message": "Hi, can I book a trip to Lisbon in May?",
"analysis": {
"handoff_summary": {},
"summary": "string",
"structured": {},
"through_seq": 1,
"human_review": {},
"needs_review": true,
"updated_at": "2026-10-28T09:30:00.000Z"
},
"live_handoff": true
}
],
"next_cursor": "eyJ0IjoiMjAyNi0xMC0yOCJ9",
"has_more": true,
"total": 1,
"live_handoff": true
}Get a conversation
GET/api/conversations/{id}
The conversation with its messages, usage lines, lead and latest analysis. Tool and system rows, and assistant tool-call steps, are returned only to instance staff, org admins and owners, and API keys. Members and viewers get the transcript the visitor saw.
Secret API key. How it works
Path parameters
idstringrequiredConversation id,
conv_....
Returns
200 OK
Response attributes
dataConversationrequired46 attributes
idstringconversation_idstringAlias used by the public resume surface.
org_idstringproject_idstringassistant_idstringwidget_key_idstring | nullchannelstringOne of
web_chatwhatsappmodestringSet by the server from the key the chat came in on: sandbox chats run the draft, preview chats send nothing out.
One of
livetestpreviewtrafficstringOperator list and detail only. Which traffic this belongs to:
sandbox(made through a non-live key: a sandbox key, the console's sandbox chat, a sandbox phone or WhatsApp number, or a preview link),test(a live chat or lead one of our rules caught: a test marker, a staging or preview page, a placeholder or own-domain email, or marked as test by hand) orreal. Sandbox wins over test. Sandbox and test are both left out of real numbers.One of
realsandboxteststatusstringrequiredOne of
openendedended_reasonstring | nullOne of
visitor_endedidle_timeoutmax_messageserrorresumablebooleanPublic resume surface: ended only because the visitor went quiet, so the next message reopens it.
handoff_requested_atstring | nullISO 8601 timestamptaken_over_atstring | nullISO 8601 timestamptaken_over_heartbeat_atstring | nullISO 8601 timestamptaken_over_bystring | nulltaken_over_by_namestring | nulltaken_overbooleanfirst_taken_over_atstring | nullISO 8601 timestampFirst time a human took over; unlike taken_over_at, never cleared.
handoff_answered_atstring | nullISO 8601 timestampFirst takeover at or after handoff_requested_at.
handoff_in_hoursboolean | nullWhether the bot told the visitor advisors were available when they first asked for a person, by the assistant's working hours (none configured counts as available). Null when unknown, as on requests from before 7 October 2026 without a stored answer.
handoff_statusstringmissed: the chat ended before anyone took over. abandoned: a human took over and then left the visitor waiting; it takes precedence over the others.
One of
nonependingansweredmissedabandonedhandoff_answer_secondsinteger | nullhuman_outcomestring | nullNull when no human took part. handled: every visitor message to the human got a human reply. abandoned: at least one did not, before the bot replied, the chat ended, or (chat still open) 5 minutes passed. Recomputed when a seat is released, when the chat ends, and on each analysis run.
One of
handledabandonedhuman_metricsHumanMetrics | nullOne of 2 shapes
HumanMetrics
first_response_secondsinteger | nullrequiredFrom the first takeover to the first human message.
longest_wait_secondsinteger | nullrequiredThe longest a visitor waited on the human, answered or not.
unanswered_countintegerrequiredVisitor messages to the human that no human answered.
agent_message_countintegerrequired
Option 2
needs_reviewbooleanOperator list only: the analysis flagged the human advisor's replies with severity 2 or more.
missed_leadbooleanOperator list and detail only. A live web chat that ended without a lead: the visitor gave no email or phone, but gave a name or company and at least one other detail. Chats the analysis labelled job_or_vendor, spam_or_test or existing_customer are left out.
visitor_idstring | nullparent_originstring | nulllast_message_atstring | nullISO 8601 timestampmessage_countintegerlead_idstring | nullmetadataobject | nullcallbackobject | nullOne of 2 shapes
Option 1
phonestringrequiredslot_startstringISO 8601 timestampnotestringrequested_atstringrequiredISO 8601 timestampdone_atstringISO 8601 timestampWhen staff marked the callback made; absent while it is open. A new request from the visitor replaces the callback, open again.
done_bystringWho marked it: a user id, or the
agent.idan API key named.done_by_namestring
Option 2
ended_atstring | nullISO 8601 timestampcreated_atstringISO 8601 timestampupdated_atstringISO 8601 timestampmessagesarray of ConversationMessage12 attributes
idstringrequiredconversation_idstringorg_idstringproject_idstringrolestringrequiredOne of
userassistantagenttoolsystemcontentstringrequiredrichRichContent | null4 attributes
quick_repliesarray of object2 attributes
labelstringrequiredvaluestringrequired
buttonsarray of object3 attributes
typestringrequiredOne of
linkuploadlabelstringrequiredurlstringuriLink buttons only. An upload button opens the file picker.
metadataobject4 attributes
billingobjectAI billing refusal on sandbox assistant messages only (test or preview mode), including the message.completed event. Absent for live visitors.
2 attributes
codestringrequiredOne of
ai_balance_exhaustedmodel_price_unavailablefree_request_too_largeplan_limit_reachedfeature_not_in_planmessagestringrequired
pageobjectVisitor messages from the web widget: the page they sent the message from.
2 attributes
pathstringrequiredtitlestringrequired
channelstringA turn spoken in a voice session of this conversation rather than typed.
One of
voicevoice_session_idstringThe voice session the turn was spoken in.
attachmentsarray of ConversationAttachmentFiles sent with the message. Each
urlis a signed link that works without credentials.5 attributes
idstringrequirednamestringrequiredcontent_typestringrequiredOne of
image/jpegimage/pngimage/webpimage/gifapplication/pdfapplication/vnd.openxmlformats-officedocument.wordprocessingml.documentsizeintegerrequiredBytes.
urlstringrequireduriSigned download link (GET /public/chat/attachments/{id}), valid for 24 hours (7 days in webhooks).
tool_callsarray of object | nulltool_call_idstring | nullseqintegercreated_atstringrequiredISO 8601 timestampupdated_atstringISO 8601 timestamp
costsarray of objectleadLead | nullOne of 2 shapes
Lead
idstringrequiredorg_idstringrequiredproject_idstringrequiredassistant_idstring | nullThe assistant that captured the lead; null when no assistant did (a form lead, or one added by hand).
conversation_idstring | nullnamestring | nullemailstring | nullemailphonestring | nullfact_provenanceobjectProvenance per field key, including name, email and phone. Legacy values use lead creation time with captured_at_estimated true; edits retain captured_at and set edited_at and edited_by.
9 attributes
sourcestringrequiredOne of
conversationchannelformmanualchannelstringrequiredOne of
web_chatweb_callphone_callsmswhatsappformad_formschedulingotherconversation_idstring | nullrequiredcall_idstring | nullrequiredform_submission_idstring | nullrequiredcaptured_atstringrequiredISO 8601 timestampcaptured_at_estimatedbooleanrequirededited_atstring | nullrequiredISO 8601 timestampedited_bystring | nullrequired
fieldsobject | nullsourcestringrequiredWhere the lead came from:
web_chat,web_call(a call from a browser),phone_call,sms,whatsapp,form,ad_form(an ad platform's own lead form, such as a Google lead form),scheduling(a booking) orother(such as a lead added by hand).One of
web_chatweb_callphone_callsmswhatsappformad_formschedulingothermodestringCapture provenance: the chat mode, independent of email classification.
One of
livetestpreviewtestbooleanEffective left-out status, sandbox or test together: non-live capture mode, or the member override when set, otherwise the automatic classification. See
trafficto tell them apart.trafficstringWhich traffic this belongs to:
sandbox(made through a non-live key: a sandbox key, the console's sandbox chat, a sandbox phone or WhatsApp number, or a preview link),test(a live chat or lead one of our rules caught: a test marker, a staging or preview page, a placeholder or own-domain email, or marked as test by hand) orreal. Sandbox wins over test. Sandbox and test are both left out of real numbers.One of
realsandboxtesttest_reasonstring | nullAutomatic classification, recomputed when saved:
reserved_domain(placeholder email),business_domain(your own email domain) orstaging_site(a live chat on a staging or preview page). An email reason wins over staging_site.One of
reserved_domainbusiness_domainstaging_sitetest_overrideboolean | nullMember override. Null follows automatic classification; leads from sandbox (non-live) chats always remain sandbox.
outcomestring | nullWhat became of the lead, as your CRM reports it (PUT /leads/{id}/outcome).
One of
openbookedlostoutcome_valuestring | nullBooking value as a decimal string.
outcome_currencystring | nulloutcome_atstring | nullISO 8601 timestampoutcome_refstring | nullThe CRM's own id for the booking.
customer_idstring | nullThe customer's own id for this person, set with PUT /v1/leads/{id}/outcome.
statusstringThe front desk's progress on the lead (PUT /v1/leads/{id}/status). Every lead starts
new.new,contactedandqualifiedare open;wonandlostclose it. Separate fromoutcome, which your CRM reports.One of
newcontactedqualifiedwonloststatus_changed_atstring | nullISO 8601 timestampstatus_changed_bystring | nullA user id, or the
agent.idan API key named.status_changed_by_namestring | nullattributionChatAttribution | nullWhere the lead's chat came from. Returned by the list and detail reads; null when none was recorded.
One of 2 shapes
ChatAttribution
chat_pagestringThe path the visitor started chatting on.
visitChatAttributionTouchThis visit's landing.
20 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
firstobjectThe visitor's first-ever landing.
21 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
atstringISO 8601 timestampWhen the visitor first landed.
latest_paidobjectThe visitor's latest ad click within 90 days: a landing with a click id, or with
utm_mediumcpc, 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 fromvisitandfirst.21 attributes
landing_pagestringA path starting with /, without query or fragment.
referrer_hoststringutm_sourcestringutm_mediumstringutm_campaignstringutm_termstringutm_contentstringgclidstringgbraidstringwbraidstringfbclidstringmsclkidstringopprefstringctwa_clidstringWhatsApp only: the Click-to-WhatsApp ad's click id, from Meta's referral.
ad_idstringWhatsApp only: the ad or post id (
source_id) from Meta's referral.ad_source_typestringWhatsApp only:
adorpost.ad_source_urlstringWhatsApp only: the ad's URL, up to 512 characters.
ad_headlinestringWhatsApp only: the ad's headline as Meta sent it (advertiser text, not verified).
whatsapp_link_idstringWhatsApp only: the campaign link (
wal_...) the chat started from.whatsapp_link_namestringWhatsApp only: that campaign link's name.
atstringISO 8601 timestampWhen the visitor landed from this ad click.
Option 2
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestampcapture_methodstringHow the lead was first saved:
tool(the assistant saved it during the conversation),analysis(read from the conversation afterwards),form(a form submission)manual(added by hand) orscheduling(a direct booking). Later updates never change it.One of
toolanalysisformmanualschedulingcall_idstring | nullThe call the lead came from, when it came from one.
form_submission_idstring | nullThe form submission the lead came from, when it came from one.
phone_e164string | nullphonein E.164 form when it could be read as a number;phonestays as given.phone_sourcestring | nullcaller_idwhen a call lead'sphoneis the number the call came from, because the caller never said one. Null means the person gave it.One of
givencaller_idfirst_contacted_atstring | nullISO 8601 timestampThe first contact: the earliest logged contact, or the first status change out of
newby a person or key. Null until contacted.last_contacted_atstring | nullISO 8601 timestampThe latest contact.
next_follow_up_atstring | nullISO 8601 timestampWhen to contact the lead again. Cleared when the lead is won or lost.
time_to_first_contact_secondsinteger | nullWall clock from
created_attofirst_contacted_at, in seconds. Null until contacted.uncontacted_nudged_atstring | nullISO 8601 timestampWhen
lead.uncontactedwas recorded for the lead; null when it never was.merged_into_idstring | nullThe kept lead's id when this lead was merged. Merged leads remain readable by id.
Option 2
handoff_summaryobject | nullOperator list only. The structured handoff from the latest analysis.
One of 2 shapes
Option 1
wantsstringrequiredup to 1200 charactersdone_by_assistantarray of stringrequiredup to 5 itemsneeds_youarray of stringrequiredup to 5 items
Option 2
summarystring | nullOperator list only: the latest background summary, when analysis is on.
intentstring | nullOperator list only: the latest analysis intent, or null when none is recorded.
One of
new_enquiryinformationexisting_customerhuman_requestjob_or_vendorspam_or_testotherunknownlast_visitor_messagestring | nullup to 200 charactersOperator list only: the newest user message by sequence, trimmed and limited to 200 characters. Null when none exists.
analysisConversationAnalysis | nullOperator detail only: the latest background summary and extracted facts.
One of 2 shapes
ConversationAnalysis
handoff_summaryobject | nullWants, completed assistant actions, and unresolved human tasks. Null for older or unvalidated analyses. Shares through_seq with the analysis.
One of 2 shapes
Option 1
wantsstringrequiredup to 1200 charactersdone_by_assistantarray of stringrequiredup to 5 itemsneeds_youarray of stringrequiredup to 5 items
Option 2
summarystring | nullrequiredstructuredobjectrequiredThe configured
channels.web_chat.analysis.fieldsthe chat stated, keyed by field key.through_seqintegerrequiredThe last message seq the run read.
human_reviewHumanReview | nullNull when no human took part.
One of 2 shapes
HumanReview
flagsarray of objectrequired3 attributes
codestringrequiredOne of
unanswered_questionspelling_grammarunprofessional_tonebroken_promisewrong_factotherleft_mid_chatslow_replyseverityintegerrequired1 to 3evidencestringrequiredup to 200 charactersA paraphrase; never contact details.
reviewed_through_seqintegerrequiredThe last message seq the model review read.
Option 2
needs_reviewbooleanhuman_review has a flag of severity 2 or more.
updated_atstringrequiredISO 8601 timestamp
Option 2
live_handoffbooleanOperator detail only: whether the org takes web chats over live. When false, takeover is refused with 409 live_handoff_disabled.
- 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 404 Not found, or outside what the key can see
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/conversations/CONVERSATION_ID" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"widget_key_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"channel": "web_chat",
"mode": "live",
"traffic": "real",
"status": "open",
"ended_reason": "visitor_ended",
"resumable": true,
"handoff_requested_at": "2026-10-28T09:30:00.000Z",
"taken_over_at": "2026-10-28T09:30:00.000Z",
"taken_over_heartbeat_at": "2026-10-28T09:30:00.000Z",
"taken_over_by": "string",
"taken_over_by_name": "string",
"taken_over": true,
"first_taken_over_at": "2026-10-28T09:30:00.000Z",
"handoff_answered_at": "2026-10-28T09:30:00.000Z",
"handoff_in_hours": true,
"handoff_status": "none",
"handoff_answer_seconds": 1,
"human_outcome": "handled",
"human_metrics": {
"first_response_seconds": 1,
"longest_wait_seconds": 1,
"unanswered_count": 1,
"agent_message_count": 1
},
"needs_review": true,
"missed_lead": true,
"visitor_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"parent_origin": "https://www.example.com",
"last_message_at": "2026-10-28T09:30:00.000Z",
"message_count": 1,
"lead_id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"metadata": {},
"callback": {
"phone": "+14155550123",
"slot_start": "2026-10-28T09:30:00.000Z",
"note": "string",
"requested_at": "2026-10-28T09:30:00.000Z",
"done_at": "2026-10-28T09:30:00.000Z",
"done_by": "string",
"done_by_name": "string"
},
"ended_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z",
"messages": [
{
"id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_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": [
{}
]
},
"tool_calls": [
{}
],
"tool_call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"seq": 1,
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z"
}
],
"costs": [
{}
],
"lead": {
"id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"email": "ana@example.com",
"phone": "+14155550123",
"fact_provenance": {
"key": {
"source": "conversation",
"channel": "web_chat",
"conversation_id": {},
"call_id": {},
"form_submission_id": {},
"captured_at": {},
"captured_at_estimated": {},
"edited_at": {},
"edited_by": {}
}
},
"fields": {
"key": "string"
},
"source": "web_chat",
"mode": "live",
"test": true,
"traffic": "real",
"test_reason": "reserved_domain",
"test_override": true,
"outcome": "open",
"outcome_value": "string",
"outcome_currency": "string",
"outcome_at": "2026-10-28T09:30:00.000Z",
"outcome_ref": "string",
"customer_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"status": "new",
"status_changed_at": "2026-10-28T09:30:00.000Z",
"status_changed_by": "string",
"status_changed_by_name": "string",
"attribution": {
"chat_page": {},
"visit": {},
"first": {},
"latest_paid": {}
},
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z",
"capture_method": "tool",
"call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"form_submission_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"phone_e164": "+14155550123",
"phone_source": "given",
"first_contacted_at": "2026-10-28T09:30:00.000Z",
"last_contacted_at": "2026-10-28T09:30:00.000Z",
"next_follow_up_at": "2026-10-28T09:30:00.000Z",
"time_to_first_contact_seconds": 1,
"uncontacted_nudged_at": "2026-10-28T09:30:00.000Z",
"merged_into_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
},
"handoff_summary": {
"wants": "string",
"done_by_assistant": [
"string"
],
"needs_you": [
"string"
]
},
"summary": "string",
"intent": "new_enquiry",
"last_visitor_message": "Hi, can I book a trip to Lisbon in May?",
"analysis": {
"handoff_summary": {
"wants": {},
"done_by_assistant": {},
"needs_you": {}
},
"summary": "string",
"structured": {},
"through_seq": 1,
"human_review": {
"flags": {},
"reviewed_through_seq": {}
},
"needs_review": true,
"updated_at": "2026-10-28T09:30:00.000Z"
},
"live_handoff": true
}
}Mark a callback made, or reopen it
PUT/api/conversations/{id}/callback
done: true stamps done_at, done_by and done_by_name on the conversation's callback; repeating it keeps the first stamp. done: false clears them. Works on ended chats and when the org has live handoff off. 409 no_callback when the visitor left no callback request. With an API key, name the person in agent.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredConversation id,
conv_....
Request body
donebooleanrequiredTrue marks the callback made; false reopens it.
agentAgentIdentityInput3 attributes
idstringemailstringemailnamestring
Returns
200 OK
Response attributes
dataConversationCallbackStaterequired2 attributes
idstringrequiredcallbackobjectrequired7 attributes
phonestringrequiredslot_startstringISO 8601 timestampnotestringrequested_atstringrequiredISO 8601 timestampdone_atstringISO 8601 timestampdone_bystringdone_by_namestring
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Not found, or outside what the key can see
- 409 Conflict
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X PUT "https://api.brightshoal.com/api/conversations/CONVERSATION_ID/callback" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"done": true
}'{
"data": {
"id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"callback": {
"phone": "+14155550123",
"slot_start": "2026-10-28T09:30:00.000Z",
"note": "string",
"requested_at": "2026-10-28T09:30:00.000Z",
"done_at": "2026-10-28T09:30:00.000Z",
"done_by": "string",
"done_by_name": "string"
}
}
}The visits this conversation's visitor made to the site
GET/api/conversations/{id}/journey
Up to 20 recent visits, newest first, across the organization's projects, by the conversation's visitor id and by the visitor ids of other conversations in the same organization whose lead shares its email, phone number (digits only, at least 7) or customer id (at most 10 visitors, listed in visitors); test traffic excluded. A conversation without a visitor id (no analytics consent, or an older widget) and without linked chats returns visitors and visits empty.
Secret API key. How it works
Path parameters
idstringrequired
Returns
200 OK
Response attributes
dataVisitorJourneyrequired4 attributes
visitor_idstring | nullrequiredvisitorsarray of objectrequiredThe visitor ids whose visits are listed: this conversation's own, plus those of conversations in the same organization whose lead shares an email, phone number or customer id. At most 10.
3 attributes
visitor_idstringrequiredlinked_bystringrequiredOne of
this_chatemailphonecustomer_idconversation_idsarray of stringrequired
visitsarray of objectrequired14 attributes
visit_idstringrequiredvisitor_idstringrequiredsitestring | nullrequiredThe site of the visit's earliest event.
visit_numberinteger | nullrequiredstarted_atstringrequiredISO 8601 timestamplast_atstringrequiredISO 8601 timestamplanding_pagestring | nullrequiredsourcestringrequiredutm_source, else the referrer host, else direct.
page_viewsintegerrequiredpagesarray of stringrequiredThe first 10 distinct pages, in the order visited.
opened_reasonstring | nullrequiredOne of
proactivevisitorapisentbooleanrequiredconversation_idsarray of stringrequiredis_this_conversationbooleanrequired
truncatedbooleanrequiredTrue when the visitor has more than 20 visits.
- 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 404 Not found, or outside what the key can see
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/conversations/CONVERSATION_ID/journey" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"visitor_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"visitors": [
{
"visitor_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"linked_by": "this_chat",
"conversation_ids": [
"conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
]
}
],
"visits": [
{
"visit_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"visitor_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"site": "string",
"visit_number": 1,
"started_at": "2026-10-28T09:30:00.000Z",
"last_at": "2026-10-28T09:30:00.000Z",
"landing_page": "string",
"source": "string",
"page_views": 1,
"pages": [
"string"
],
"opened_reason": "proactive",
"sent": true,
"conversation_ids": [
"conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
],
"is_this_conversation": true
}
],
"truncated": true
}
}Send a message as a person
POST/api/conversations/{id}/messages
Only the operator holding the seat may send (403 otherwise). With client_message_id, a retry by the same operator returns the original message instead of sending it again; reusing the id for different content is 409 client_message_id_reused.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredConversation id,
conv_....
Request body
contentstringrequiredup to 4000 charactersagentAgentIdentityInput3 attributes
idstringemailstringemailnamestring
client_message_idstringup to 200 charactersUnique per message from this operator; makes a retried send safe.
Returns
201 OK
Response attributes
dataConversationMessagerequired12 attributes
idstringrequiredconversation_idstringorg_idstringproject_idstringrolestringrequiredOne of
userassistantagenttoolsystemcontentstringrequiredrichRichContent | null4 attributes
quick_repliesarray of object2 attributes
labelstringrequiredvaluestringrequired
buttonsarray of object3 attributes
typestringrequiredOne of
linkuploadlabelstringrequiredurlstringuriLink buttons only. An upload button opens the file picker.
metadataobject4 attributes
billingobjectAI billing refusal on sandbox assistant messages only (test or preview mode), including the message.completed event. Absent for live visitors.
2 attributes
codestringrequiredOne of
ai_balance_exhaustedmodel_price_unavailablefree_request_too_largeplan_limit_reachedfeature_not_in_planmessagestringrequired
pageobjectVisitor messages from the web widget: the page they sent the message from.
2 attributes
pathstringrequiredtitlestringrequired
channelstringA turn spoken in a voice session of this conversation rather than typed.
One of
voicevoice_session_idstringThe voice session the turn was spoken in.
attachmentsarray of ConversationAttachmentFiles sent with the message. Each
urlis a signed link that works without credentials.5 attributes
idstringrequirednamestringrequiredcontent_typestringrequiredOne of
image/jpegimage/pngimage/webpimage/gifapplication/pdfapplication/vnd.openxmlformats-officedocument.wordprocessingml.documentsizeintegerrequiredBytes.
urlstringrequireduriSigned download link (GET /public/chat/attachments/{id}), valid for 24 hours (7 days in webhooks).
tool_callsarray of object | nulltool_call_idstring | nullseqintegercreated_atstringrequiredISO 8601 timestampupdated_atstringISO 8601 timestamp
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Not found, or outside what the key can see
- 409 Conflict
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X POST "https://api.brightshoal.com/api/conversations/CONVERSATION_ID/messages" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "Hi Ana, this is Alex from Acme Travel. Happy to help with Lisbon.",
"agent": {
"id": "operator_1"
}
}'{
"data": {
"id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"role": "user",
"content": "Hi, can I book a trip to Lisbon in May?",
"rich": {
"quick_replies": [
{
"label": "string",
"value": "string"
}
],
"buttons": [
{
"type": "link",
"label": "string",
"url": "https://example.com/hook"
}
],
"metadata": {
"billing": {
"code": "ai_balance_exhausted",
"message": "Hi, can I book a trip to Lisbon in May?"
},
"page": {
"path": "string",
"title": "Front desk"
},
"channel": "voice",
"voice_session_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
},
"attachments": [
{
"id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"content_type": "image/jpeg",
"size": 1,
"url": "https://example.com/hook"
}
]
},
"tool_calls": [
{}
],
"tool_call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"seq": 1,
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z"
}
}Hand a conversation back to the assistant
POST/api/conversations/{id}/release
The holder releases their own seat; org admins and API keys may release anyone's, which is recorded as a forced release naming the previous holder. Send the same agent you took over with, so the release is recorded as yours rather than forced. Release still works when the org has turned live handoff off.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredConversation id,
conv_....
Request body
agentAgentIdentityInput3 attributes
idstringemailstringemailnamestring
Returns
200 OK
Response attributes
dataConversationTakeoverrequired5 attributes
idstringrequiredstatusstringrequiredOne of
openendedtaken_over_atstring | nullrequiredISO 8601 timestamptaken_over_heartbeat_atstring | nullrequiredISO 8601 timestamptaken_over_bystring | nullrequired
- 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Not found, or outside what the key can see
- 409 Conflict
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X POST "https://api.brightshoal.com/api/conversations/CONVERSATION_ID/release" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"email": "ana@example.com"
}
}'{
"data": {
"id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"status": "open",
"taken_over_at": "2026-10-28T09:30:00.000Z",
"taken_over_heartbeat_at": "2026-10-28T09:30:00.000Z",
"taken_over_by": "string"
}
}Draft unsent replies for a conversation
POST/api/conversations/{id}/reply-suggestions
Member role. Generates two or three text drafts from the current transcript and stored analysis, using this project's configured analysis model (or chat model). Requires the project's provider credentials. Sends nothing, executes no tools and stores no messages. through_seq identifies the transcript read; analysis_through_seq can lag or be null.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequired
Returns
200 Unsent text drafts
Response attributes
dataobject3 attributes
repliesarray of stringrequiredup to 3 itemsthrough_seqintegerrequiredanalysis_through_seqinteger | nullrequired
- 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 model_connection_required
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address). - 502 reply_draft_failed
curl -X POST "https://api.brightshoal.com/api/conversations/CONVERSATION_ID/reply-suggestions" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"replies": [
"string"
],
"through_seq": 1,
"analysis_through_seq": 1
}
}Take over a conversation
POST/api/conversations/{id}/takeover
Only one operator holds a seat: when another already does, 409 already_taken_over names them in taken_over_by. Taking over a seat you hold refreshes it. 409 live_handoff_disabled when the org does not take web chats over live. Heartbeat and operator messages refuse the same way. With an API key, name the person in agent (otherwise the holder is api_key) and send the same agent on every message, heartbeat and release. A seat with no heartbeat for three minutes is released.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredConversation id,
conv_....
Request body
agentAgentIdentityInput3 attributes
idstringemailstringemailnamestring
Returns
200 OK
Response attributes
dataConversationTakeoverrequired5 attributes
idstringrequiredstatusstringrequiredOne of
openendedtaken_over_atstring | nullrequiredISO 8601 timestamptaken_over_heartbeat_atstring | nullrequiredISO 8601 timestamptaken_over_bystring | nullrequired
- 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Not found, or outside what the key can see
- 409 Conflict
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X POST "https://api.brightshoal.com/api/conversations/CONVERSATION_ID/takeover" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent": {
"id": "operator_1",
"name": "Alex"
}
}'{
"data": {
"id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"status": "open",
"taken_over_at": "2026-10-28T09:30:00.000Z",
"taken_over_heartbeat_at": "2026-10-28T09:30:00.000Z",
"taken_over_by": "string"
}
}Keep a takeover alive
POST/api/conversations/{id}/takeover/heartbeat
Call at least once a minute while a person is working the chat. A seat with no heartbeat for three minutes is released and the assistant answers again. Send the same agent you took over with.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredConversation id,
conv_....
Request body
agentAgentIdentityInput3 attributes
idstringemailstringemailnamestring
Returns
200 OK
Response attributes
dataConversationTakeoverHeartbeatrequired1 attribute
taken_over_heartbeat_atstringrequiredISO 8601 timestamp
- 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Not found, or outside what the key can see
- 409 Conflict
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X POST "https://api.brightshoal.com/api/conversations/CONVERSATION_ID/takeover/heartbeat" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"email": "ana@example.com"
}
}'{
"data": {
"taken_over_heartbeat_at": "2026-10-28T09:30:00.000Z"
}
}Summarize human handoffs
GET/api/conversations/handoff-summary
Conversations created in the range (inclusive), sandbox conversations excluded unless mode says otherwise. answer_seconds runs from the handoff request to the first takeover. first_response_seconds and longest_wait_seconds are taken over the conversations with human_metrics.
Secret API key. How it works
Query parameters
project_idstringOnly this project's conversations.
assistant_idarray of stringOnly these assistants' conversations. Repeat the parameter or comma-separate the values; a row matching any of them is kept.
fromstringISO 8601 timestampCreated at or after this time.
tostringISO 8601 timestampCreated at or before this time.
modestringWhich chats to include, by the mode the server gave each. Absent: sandbox and preview chats are left out, and so are live chats a page marked as a test, as before. live: every live-mode chat, including those a page marked as a test. test: sandbox chats (stored mode
test). preview: preview chats. all: every chat.One of
livetestpreviewalltrafficstringComma-separated subset of real, sandbox and test: only chats of those kinds. When given it replaces the default view (and
include_test); an explicitmodestill narrows. Absent: the default view, unchanged.group_bystringassistantreturns onlyby_assistant(ConversationHandoffsByAssistant): the plain counts for each assistant with conversations in the range, under the same filters, without the whole-range figures.One of
noneassistantDefault
"none"
Returns
200 OK
Response attributes
dataConversationHandoffSummary | ConversationHandoffsByAssistantrequiredOne of 2 shapes
ConversationHandoffSummary
conversationsintegerrequiredrequestedintegerrequiredpendingintegerrequiredansweredintegerrequiredmissedintegerrequiredrequested_in_hoursintegerrequiredRequests made while advisors were said to be available.
requested_out_of_hoursintegerrequiredRequests made outside working hours, when the bot offers a callback instead.
missed_in_hoursintegerrequiredmissed_out_of_hoursintegerrequiredtaken_overintegerrequiredConversations a human took over, requested or not.
abandonedintegerrequiredConversations a human took over and then left the visitor waiting.
handledintegerrequiredConversations a human took part in where every visitor message to them got a human reply.
unanswered_messagesintegerrequiredVisitor messages to a human that no human answered, summed.
callbacksintegerrequiredConversations where the visitor left a callback request.
live_handoffbooleanrequiredWhether the org takes web chats over live. When false, requests for a person are callback requests only.
answer_secondsSecondsPercentilesrequired2 attributes
medianinteger | nullrequiredp90integer | nullrequired
first_response_secondsSecondsPercentilesrequiredFrom the first takeover to the first human message.
2 attributes
medianinteger | nullrequiredp90integer | nullrequired
longest_wait_secondsSecondsPercentilesrequiredEach conversation's longest wait for the human, answered or not.
2 attributes
medianinteger | nullrequiredp90integer | nullrequired
ConversationHandoffsByAssistant
by_assistantarray of ConversationHandoffCountsrequired11 attributes
assistant_idstringrequiredconversationsintegerrequiredrequestedintegerrequiredpendingintegerrequiredansweredintegerrequiredmissedintegerrequiredrequested_in_hoursintegerrequiredrequested_out_of_hoursintegerrequiredmissed_in_hoursintegerrequiredmissed_out_of_hoursintegerrequiredcallbacksintegerrequired
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/conversations/handoff-summary" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"conversations": 1,
"requested": 1,
"pending": 1,
"answered": 1,
"missed": 1,
"requested_in_hours": 1,
"requested_out_of_hours": 1,
"missed_in_hours": 1,
"missed_out_of_hours": 1,
"taken_over": 1,
"abandoned": 1,
"handled": 1,
"unanswered_messages": 1,
"callbacks": 1,
"live_handoff": true,
"answer_seconds": {
"median": 1,
"p90": 1
},
"first_response_seconds": {
"median": 1,
"p90": 1
},
"longest_wait_seconds": {
"median": 1,
"p90": 1
}
}
}Count a project's sandbox data
GET/api/test-data
What POST /v1/test-data/clear would delete now: sandbox and preview chats, their files, the leads they captured, and sandbox telemetry. An estimate, as sandbox chats may start meanwhile.
Secret API key. How it works
Query parameters
project_idstringrequired
Returns
200 OK
Response attributes
dataobjectrequired6 attributes
project_idstringrequiredconversationsintegerrequiredSandbox and preview chats there are now.
leadsintegerrequiredSandbox and preview leads.
eventsintegerrequiredChat events and request outcomes.
attachmentsintegerrequiredUploaded files.
callsintegerFinished sandbox calls (with their costs, analysis and recording rows).
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Not found, or outside what the key can see
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/test-data?project_id=proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"conversations": 1,
"leads": 1,
"events": 1,
"attachments": 1,
"calls": 1
}
}Clear a project's sandbox and preview chats and leads
POST/api/test-data/clear
Deletes the project's sandbox and preview chats started before the request (with their messages, files, analysis, telemetry and webhook events) and the leads they captured. Live chats are never touched, nor are live chats whose page only claimed to be a test. Sends no webhooks. Returns what it deleted.
Secret API key, not a viewer key. How it works
Request body
project_idstringrequired
Returns
200 OK
Response attributes
dataobjectrequired7 attributes
project_idstringrequiredconversationsintegerrequiredSandbox and preview chats deleted.
leadsintegerrequiredSandbox and preview leads.
eventsintegerrequiredChat events and request outcomes.
attachmentsintegerrequiredUploaded files.
callsintegerFinished sandbox calls (with their costs, analysis and recording rows).
attachment_failuresintegerFiles whose delete failed (logged).
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Not found, or outside what the key can see
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X POST "https://api.brightshoal.com/api/test-data/clear" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
}'{
"data": {
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"conversations": 1,
"leads": 1,
"events": 1,
"attachments": 1,
"calls": 1,
"attachment_failures": 1
}
}