Agent Configuration

Agents define how VoxBridge speaks on the phone: system prompts, voice character, call direction, and which agent handles API requests by default.

What is an agent?

Each agent belongs to one organization and is scoped by direction — outbound for proactive calls your app queues, or inbound for calls arriving on your SIP numbers. The agent's system_prompt instructs the LLM; voice_id selects TTS character (see Voice characters).

Default agents on signup

New organizations receive two pre-configured agents:

Name	Slug	Direction	Voice	Default?
Welcome Call Agent	`welcome`	outbound	`warm_female`	Yes
Inbound Support Agent	`inbound-support`	inbound	`calm_support`	No

The outbound welcome agent uses a template prompt with placeholders such as and filled from the call context object when the worker runs the conversation.

Default agent selection

When you POST to /v1/calls/outbound without agent_id, VoxBridge selects the active agent where is_default is true. If none exists, the API returns 400 No default agent configured.

Only one agent per organization should be marked default at a time. Set is_default: true on the agent you want via the dashboard or PATCH /dashboard/agents/{id}.

System prompts

Prompts must be at least 20 characters. Effective prompts include:

Identity — who the agent represents and the call purpose
Goals — ordered steps (verify identity, explain next steps, offer human handoff)
Rules — tone, duration limits, compliance boundaries, voicemail behavior
Variables — reference context fields your API sends (e.g. reference numbers, product names)

You are a friendly AI voice agent calling on behalf of Acme Lending. Goals: 1. Confirm you are speaking with . 2. Reference application if provided. 3. Explain next steps and offer human support if needed. Rules: - Keep calls under 3 minutes unless the caller continues. - If wrong person or opt-out, apologize and end politely.

Creating agents

Dashboard: Agents panel → create agent, set direction, prompt, and voice.

API (JWT required):

curl -X POST https://voxbridge.cc/dashboard/agents \ -H "Authorization: Bearer YOUR_JWT" \ -H "Content-Type: application/json" \ -d '{ "name": "Collections Reminder", "direction": "outbound", "voice_id": "authoritative", "system_prompt": "You are calling regarding an overdue balance..." }'

Updating and deactivating

curl -X PATCH https://voxbridge.cc/dashboard/agents/AGENT_UUID \ -H "Authorization: Bearer YOUR_JWT" \ -H "Content-Type: application/json" \ -d '{"voice_id":"friendly_young","is_default":true}'

Set is_active: false or DELETE to retire an agent. Inactive agents cannot be selected for new calls.

Listing agents via API

Server integrations can list active agents with the live API key:

curl https://voxbridge.cc/v1/agents \ -H "Authorization: Bearer sk_live_YOUR_KEY"

Returns id, name, slug, direction, and is_default for each active agent.

Inbound & outbound → · Voice characters → · Calls API →