BrightshoalDocsOpen console
MenuHow it fits together

Get started

How it fits together

The handful of objects behind every call and chat, which credential reaches which of them, and what comes back when a conversation ends.

The objects

Your organization holds everything. Inside it, projects separate brands, clients or environments: each assistant, phone number, publishable key and webhook belongs to exactly one project.

ObjectWhat it isID
ProjectA container inside your organizationproj_...
AssistantOne agent: its instructions, models, voice, tools and channelsasst_...
Phone numberA number the assistant answers, or calls frompn_...
CallOne phone or browser call, with its transcript, recordings and analysiscall_...
ConversationOne web chat or WhatsApp thread, with its messagesconv_...
LeadThe details an assistant captured from a conversationlead_...
Knowledge basePages and documents an assistant answers from (organization-wide)kb_...
WebhookAn HTTPS endpoint of yours that hears about eventswhsub_...

Treat every ID as an opaque string: the prefix tells you what it is, nothing else is promised. Timestamps are ISO 8601 in UTC, like 2026-10-28T09:30:00.000Z.

An assistant

An assistant's config has four parts you will meet in these guides:

  • agent: what it is for. instructions is required; context, first_message and first_message_instructions are optional. All four can hold {{ variables }}.
  • session: the voice pipeline used on calls: llm, stt (speech to text) and tts (text to speech), each a provider and model. GET /api/registry lists what you can choose.
  • channels.web_chat: whether it answers chat, the model chat uses (llm, openai/gpt-6.1-sol with medium reasoning unless you set one), the allowed origins, greeting and the rest of the widget's behaviour.
  • variables: up to 50 named values (key, optional label, description and default) that a call can fill in, so one assistant can greet each person by name.

Every change to the live config creates a new version, whether it comes from a PATCH or from publishing a draft. Calls record the version they ran on. A chat always uses the assistant's current config, so a long conversation picks up a change at its next message.

Sandbox and test

Every chat, lead and event belongs to one of three kinds of traffic, shown as the traffic field on conversations and leads:

  • Real is what customers do: live chats and calls that no rule has caught.
  • Sandbox is everything made through a non-live key, so you can try a change without your customers seeing it. It is sandbox from the start.
  • Test is a live chat that one of our rules caught as not being a customer: a placeholder email, your own email domain, a staging site, or a test marker. The chat ran live, so its webhooks still reach live subscriptions.

If both apply, sandbox wins over test, and test wins over real. Sandbox and test traffic stay out of real numbers such as analytics and alerts.

Sandbox

Sandbox runs the assistant's saved draft instead, or its live config when there is no draft. Live is what customers reach: a site publishable key (pk_live_), your phone numbers, and the assistant's live config.

Sandbox chats come from:

  • a sandbox publishable key (pk_test_, which loads only on its own staging origins, and still needs web chat on),
  • the console's sandbox chat,
  • a preview link (pk_preview_, from POST/api/preview-links), made for sharing: a hosted page that runs the live config with no webhooks and no analytics.

Sandbox calls are placed with mode: "test", or reach a number switched to sandbox mode with PATCH/api/phone-numbers/{id}. Of your own tools, only those marked read-only run in the sandbox (on calls, only those the platform runs for you); calls make no transfers. Lead capture works as usual.

The stored values keep the old word: mode is live, test or preview, sandbox keys start with pk_test_, and a sandbox webhook subscription has mode: "test". In the console and these docs, that mode is called Sandbox.

Sandbox traffic reaches only webhook subscriptions created with mode: "test", and its events carry livemode: false.

Edit the draft with PUT/api/assistants/{id}/draft and make it live with POST/api/assistants/{id}/publish. A PATCH still changes the live config at once. POST/api/test-data/clear deletes a project's sandbox chats with everything they produced (messages, files, leads), and its finished sandbox calls.

Test

A live chat becomes test traffic when a rule applies: a test marker on the conversation, a page on a preview or staging host, or a lead that is test (a placeholder or business email, a staging site, or marked as test by a member). Test chats keep their live webhooks, flagged with traffic: "test". See Leads.

Where an assistant answers

ChannelHow it startsGuide
Phone, inboundSomeone calls a number you attached to the assistantAnswer calls on your number
Phone, outboundYour server asks it to call someonePlace an outbound call
Browser callYour web app joins a voice room with a short-lived tokenCalls in the browser
Web chatA visitor writes in the widget or in your own chat UIAdd chat to your website
WhatsAppA customer messages a WhatsApp number assigned to the assistantWhatsApp reference

Three ways in, one way out

What comes back

When a call ends you get its transcript, usage, recordings and, once analysis runs, a summary. When a chat captures a name and a way to reach someone, a lead appears. Read either with the API whenever you like, or subscribe to webhooks and hear about each the moment it happens. When your team follows up, report what became of the lead (booked, lost or open) so the numbers in the console show real outcomes: Leads and outcomes.

Stuck on how it fits together?