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. 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.

Live and test

Each chat and call runs in one of two modes, so you can try a change without your customers seeing it:

Live is what customers reach: a site publishable key (pk_live_), your phone numbers, and the assistant's live config.
Test runs the assistant's saved draft instead, or its live config when there is no draft. Test chats come from a test publishable key (pk_test_, which loads only on its own staging origins, and still needs web chat on) or the console's test chat. Test calls are placed with mode: "test", or reach a number switched to test mode with PATCH/api/phone-numbers/{id}. Of your own tools, only those marked read-only run in a test (on calls, only those the platform runs for you); calls make no transfers. Lead capture works as usual.

Test traffic reaches only webhook subscriptions created with mode: "test", and its events carry livemode: false. It stays out of analytics and alerts.

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 test and preview chats with everything they produced (messages, files, leads), and its finished test calls.

A preview link (pk_preview_, from POST/api/preview-links) is a third kind, made for sharing: a hosted page that runs the live config with no webhooks and no analytics.

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
WhatsApp	A customer messages a WhatsApp number assigned to the assistant	WhatsApp reference

Three ways in, one way out

The developer API, /api From your server, with a secret key (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.