Skip to main content

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

Send 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.
A single voice agent comes back with everything attached to it:
  • configuration: the editable settings (prompt, voice, model, limits)
  • inbound: inbound call settings
  • channels: channel assignments, keyed by email, linkedin, whatsapp and phone
  • knowledge_bases: the assigned knowledge bases
  • tools: the assigned tools
Add 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 with knowledge_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 with tool_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

Deletes the agent configuration. Does not affect historical call logs or campaign data. If the agent is assigned to an active campaign, the campaign must be stopped first.

Webhook events from voice agents

Subscribe to these via Webhooks to build downstream workflows (CRM updates, Slack notifications, follow-up sequences, etc.).