> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sendora.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Voice Agents

> Create and configure AI voice agents that call leads on your behalf.

## 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](/guides/webrtc-browser-calls) without a phone number, or through a phone call when a number is configured.

Each agent has:

* A **persona**, name, greeting, and personality instructions
* A **system prompt**, 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.)
* An optional connected **phone number** for phone calls

## Creating a voice agent

```bash theme={"dark"}
curl -X POST https://api.sendora.ai/api/v1/public/voice-agents \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alex - Outbound SDR",
    "persona_name": "Alex",
    "greeting": "Hi, this is Alex calling from Sendora. Is now a good time for a quick 2-minute chat?",
    "system_prompt": "You are Alex, an outbound sales development rep for Sendora. Your goal is to qualify the lead and book a 15-minute demo call with an account executive. Be friendly, concise, and handle objections confidently. Never be pushy."
  }'
```

The agent is created in `inactive` state. Assign knowledge bases and tools before deploying it in a campaign.

## Updating an agent

```bash theme={"dark"}
curl -X PATCH "https://api.sendora.ai/api/v1/public/voice-agents/{agent_id}" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "system_prompt": "You are Alex, an outbound SDR for Sendora... [updated prompt]"
  }'
```

Changes take effect immediately for the next call. Any in-progress call uses the prompt from when it was initiated.

## Listing agents

```bash theme={"dark"}
GET /api/v1/public/voice-agents
```

Returns all agents in your workspace with their status, assigned KBs, and assigned tools.

## Getting a single agent

```bash theme={"dark"}
GET /api/v1/public/voice-agents/{agent_id}
```

Returns full agent detail including:

* `knowledge_bases`, list of assigned KBs with source counts and status
* `tools`, list of assigned tools with configuration
* `connected_phone_number`, the number this agent dials from
* `call_count`, total calls placed
* `avg_duration_seconds`, average call length

## Agent setup flow

```mermaid theme={"dark"}
flowchart TD
    A[POST /voice-agents\nCreate agent] --> B[POST /knowledge-bases\nCreate KB]
    B --> C[POST /knowledge-bases/id/sources/text\nor /sources/url]
    C --> D[POST /voice-agents/id/knowledge-bases\nAssign KB]
    A --> E[GET /tools/catalog\nPick tools]
    E --> F[POST /tools\nCreate tool instance]
    F --> G[POST /tools/id/assignments\nAssign to agent]
    D --> H[Add agent to campaign\nand launch]
    G --> H
```

## Equipping an agent end-to-end

The typical setup flow for a new agent:

```bash theme={"dark"}
# 1. Create the agent
AGENT_ID=$(curl -sX POST .../voice-agents \
  -d '{"name":"Alex","persona_name":"Alex","greeting":"Hi, is now a good time?","system_prompt":"..."}' \
  | jq -r .id)

# 2. Create a product FAQ knowledge base
KB_ID=$(curl -sX POST .../knowledge-bases \
  -d '{"name":"Product FAQ"}' | jq -r .id)

# 3. Add a text source to the KB
curl -X POST ".../knowledge-bases/$KB_ID/sources/text" \
  -d '{"title":"Pricing FAQ","content":"Q: How much does it cost?..."}'

# 4. Assign the KB to the agent
curl -X POST ".../voice-agents/$AGENT_ID/knowledge-bases" \
  -d "{\"kb_id\":\"$KB_ID\"}"

# 5. Create a meeting booking tool
TOOL_ID=$(curl -sX POST .../tools \
  -d '{"slug":"book_meeting","name":"Book Demo","config":{"calendar_connection_id":"conn_gcal","meeting_duration_minutes":30}}' \
  | jq -r .id)

# 6. Assign the tool to the agent
curl -X POST ".../tools/$TOOL_ID/assignments" \
  -d "{\"agent_id\":\"$AGENT_ID\"}"

# 7. Verify the agent is fully configured
curl ".../voice-agents/$AGENT_ID" | jq '{knowledge_bases: .knowledge_bases|length, tools: .tools|length}'
```

## Knowledge base assignment

See [Knowledge Bases guide](/guides/knowledge-bases) for full details on building and assigning KBs.

```bash theme={"dark"}
# Assign a KB to an agent
POST /api/v1/public/voice-agents/{agent_id}/knowledge-bases
Body: { "kb_id": "kb_abc" }

# List all KBs assigned to an agent
GET /api/v1/public/voice-agents/{agent_id}/knowledge-bases

# Unassign a KB
DELETE /api/v1/public/voice-agents/{agent_id}/knowledge-bases/{kb_id}
```

## Tool assignment

See [Tools guide](/guides/tools) for the full tool catalog and configuration options.

```bash theme={"dark"}
# Assign a tool
POST /api/v1/public/tools/{tool_id}/assignments
Body: { "agent_id": "agent_abc" }

# Unassign a tool
DELETE /api/v1/public/tools/{tool_id}/assignments/{agent_id}
```

## Deleting an agent

```bash theme={"dark"}
DELETE /api/v1/public/voice-agents/{agent_id}
```

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

| Event | When it fires |
| - | - |
| `call.completed` | After every call ends, includes transcript URL, duration, outcome |
| `meeting.booked` | When the agent books a meeting during a call |

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.