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.
| Object | What it is | ID |
|---|---|---|
| Project | A container inside your organization | proj_... |
| Assistant | One agent: its instructions, models, voice, tools and channels | asst_... |
| Phone number | A number the assistant answers, or calls from | pn_... |
| Call | One phone or browser call, with its transcript, recordings and analysis | call_... |
| Conversation | One web chat or WhatsApp thread, with its messages | conv_... |
| Lead | The details an assistant captured from a conversation | lead_... |
| Knowledge base | Pages and documents an assistant answers from (organization-wide) | kb_... |
| Webhook | An HTTPS endpoint of yours that hears about events | whsub_... |
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.instructionsis required;context,first_messageandfirst_message_instructionsare optional. All four can hold{{ variables }}.session: the voice pipeline used on calls:llm,stt(speech to text) andtts(text to speech), each aproviderandmodel.GET /api/registrylists what you can choose.channels.web_chat: whether it answers chat, the model chat uses (llm,openai/gpt-6.1-solwith 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, optionallabel,descriptionanddefault) 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
| Channel | How it starts | Guide |
|---|---|---|
| Phone, inbound | Someone calls a number you attached to the assistant | Answer calls on your number |
| Phone, outbound | Your server asks it to call someone | Place an outbound call |
| Browser call | Your web app joins a voice room with a short-lived token | Calls in the browser |
| Web chat | A visitor writes in the widget or in your own chat UI | Add chat to your website |
| A customer messages a WhatsApp number assigned to the assistant | WhatsApp reference |
Three ways in, one way out
vak_...). Everything: assistants, calls, conversations, leads, webhooks.The public chat API, /public/v1 From a browser, with a publishable key (pk_live_...) and then a conversation token. Chat, and voice in the same conversation.The console Where people create keys, review conversations and change settings. It uses the same API.Webhooks, out to you We POST signed events to your endpoint: calls ending, messages, leads, handoffs.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.