Overview
A voice agent holds spoken conversations, handles objections, answers questions from a knowledge base, and books meetings. People can talk to it through a WebRTC browser call without a phone number, or through a phone call when a number is configured. Agents have their own endpoints: List or get agents, Create agent, Update agent and Delete agent. Everything an agent uses (its channels, inbound settings, knowledge bases, tools and publish state) is read and changed on the agent itself. Each agent has:- A first message, the greeting it opens with
- A system prompt, which defines the agent’s goal, talking points, and guardrails
- Assigned knowledge bases, documents the agent can search in real time
- Assigned tools, actions the agent can take (book a meeting, end the call, transfer to human, etc.)
- Channel assignments and inbound settings
- An optional connected phone number for phone calls
Creating a voice agent
draft: true to save the agent without publishing it. Assign knowledge bases and tools before using it in a campaign.
Reading agents
One endpoint lists agents and returns a single agent.configuration: the editable settings (prompt, voice, model, limits)inbound: inbound call settingschannels: channel assignments, keyed byemail,linkedin,whatsappandphoneknowledge_bases: the assigned knowledge basestools: the assigned tools
include=voices to also get the voice choices that agent can use.
Updating an agent
PATCH /api/v1/public/agents/{agent_id} changes settings, inbound behavior, channels, knowledge bases, tools and the publish state in one call. Send only what you want to change.
The steps run in this order: settings, inbound, channels, knowledge bases, tools, publish. If a step fails, the steps before it stay applied and the error lists them under
applied. The response is the updated agent.
Changes take effect immediately for the next call. Any in-progress call uses the prompt from when it was initiated.
Agent setup flow
Equipping an agent end-to-end
The typical setup flow for a new agent:Knowledge base assignment
See the Knowledge Bases guide for building knowledge bases. Assign them withknowledge_base_ids on Update agent. The list you send is the whole set, so send the ids of every knowledge base the agent should keep.
Tool assignment
See the Tools guide for the full tool catalog and configuration. Assign tools withtool_ids on Update agent, which is also the full set. Tools that exist only on one agent (direct booking, email, text, transfer and call control) are created with agent_id on Create tool.
Deleting an agent
Webhook events from voice agents
Subscribe to these via Webhooks to build downstream workflows (CRM updates, Slack notifications, follow-up sequences, etc.).