Voice Agents
Voice agents are the core of the Hanc.AI platform — AI-powered virtual assistants that handle phone conversations with your customers. This section covers everything you need to know about creating, configuring, and managing voice agents.
What is a Voice Agent?
A voice agent is an AI program that:
- Answers phone calls automatically, 24/7
- Understands speech in natural language
- Responds with voice using natural-sounding speech
- Follows your instructions defined in the prompt
- Uses your information from the knowledge base
- Performs actions like booking appointments or transferring calls
Agent Architecture
Creating an Agent
From the Dashboard
- Navigate to Voice Agents in the sidebar
- Click "Create voice agent"
- Choose a template or start from scratch
- Configure basic settings
- Save and test
Available Templates
| Template | Use Case | Includes |
|---|---|---|
| Customer Service | General support, FAQs | Friendly prompt, escalation rules |
| Appointment Booking | Scheduling | Calendar integration, availability check |
| Sales | Lead qualification | Product info, qualifying questions |
| Reception | Call routing | Department identification, transfers |
| Custom | Any purpose | Empty configuration |
Deploy Workflow
There are two ways to create an agent from a template:
| Option | Description |
|---|---|
| Deploy Agent | Creates the agent instantly with default template settings. You can fill in your business details later. |
| Guided Setup | Opens the Setup Wizard immediately so you can configure the agent step by step before it goes live. |
After deployment, a success banner appears with suggested next steps — such as testing the agent, assigning a phone number, or embedding a widget on your website.
Setup Wizard
When you create an agent from a template, a glowing wand icon appears next to the agent name. Click it to open the Setup Wizard, which walks you through filling in your business details section by section.
- Progress is tracked at the top of the wizard (e.g., "2/7 sections completed").
- Each section covers a specific part of the configuration — business info, hours, services, and so on.
- You can complete sections in any order and return to the wizard at any time.
The Setup Wizard is the fastest way to get a template-based agent fully configured. Complete all sections to ensure your agent has the information it needs to handle calls effectively.
Reset to Template
If you manually edit the prompt or knowledge base files after creating an agent from a template, the Setup Wizard is automatically disabled. A "Reset to Template" button appears in the agent header, allowing you to restore the original template configuration and re-enable the wizard.
Resetting to the template will overwrite any manual changes you have made to the prompt and knowledge base.
Agent Configuration
Basic Information
| Field | Description | Example |
|---|---|---|
| Name | Internal identifier | "Main Reception" |
| Description | Purpose of the agent | "Handles all incoming calls" |
| Status | Active or inactive | Active |
Agent Header Toolbar
The toolbar at the top of the agent page includes an Info button. Clicking it opens a dropdown that shows a quick overview of your agent's current configuration:
- Voice — the selected voice
- Language — the primary language
- Knowledge Bases — connected knowledge base files
- Active Tools — enabled tools (Call Forwarding, Google Calendar, etc.)
- Role — the agent's defined role from the prompt
This is a convenient way to review your agent's setup at a glance without navigating through each tab.
Agent Tabs
Your agent page has six tabs:
| Tab | What's Inside |
|---|---|
| Dashboard | Call logs, analytics, sentiment overview |
| Model | Greeting message and agent prompt editor |
| Knowledge Base | Manage knowledge base files attached to this agent — add, edit, or remove files |
| Settings | Language, voice, call behavior, recording, post-call analysis |
| Actions | Tools (Call Forwarding, Google Calendar, API RAG), post-call actions (Email, SMS, WhatsApp, API), and retrieval variables |
| Widgets | Website widget configuration — theme, embed code, domain restrictions, terms |
Model Tab
The core agent configuration:
First Message
The greeting when the agent answers:
Hello! Thank you for calling ABC Company. How can I assist you today?
- Keep under 10 seconds when spoken
- State your company name
- Invite the caller to speak
- Sound welcoming
Agent Prompt
Instructions defining agent behavior. See Prompt Engineering for detailed guidance.
Knowledge Base Tab
Each agent has its own Knowledge Base tab where you can manage attached knowledge base files — create new ones, upload files, edit content inline, or remove files. For general Knowledge Base management, see the Knowledge Base section.
Template Warning
When an agent was created from a template, the Model and Knowledge Base tabs display a warning message. This warning informs you that editing the prompt or knowledge base files manually will disable the Setup Wizard. If you want to use the wizard to configure the agent, avoid making manual edits in these tabs.
Settings Tab
Configure agent behavior in the Settings tab:
| Setting | Description |
|---|---|
| Language | Initial greeting language (agent adapts to caller's language) |
| Voice | Voice selection (gender, tone, style) |
| End call after silence | Auto-end call if no response |
| End-Call timeout (sec) | Seconds of silence before ending |
| Reminder timeout (sec) | Time before repeating last message |
| Max reminders | How many times to repeat before ending |
| Recording Enabled | Toggle call recording on or off |
| Sentiment analysis | Track caller mood (positive/neutral/negative) |
| Call summary | Generate summary with key phrases after call |
Language
Primary communication language for the greeting. The agent will:
- Start in this language
- Automatically switch to the caller's language
- Understand multiple languages
Voice Selection
Choose from available voices with different:
- Genders (male/female)
- Tones (professional, friendly, calm)
- Styles and accents
Match voice to your brand: professional services benefit from a calm, mature voice; youth brands from an energetic, younger voice; healthcare from a warm, reassuring voice.
Actions & Tools
Tools and actions extend what your agent can do beyond conversation. Access them via the Actions tab in your agent settings — tools, post-call actions, and retrieval variables are all managed in one place.
Available Tools
| Tool | Purpose | Configuration |
|---|---|---|
| Call Forwarding | Transfer to human operator | Name, forwarding number, trigger condition |
| Google Calendar | Check availability & book appointments | Google account, calendar, working hours, slot duration |
| API Tool RAG | Real-time external data | Endpoint URL, headers, body schema, timeout |
Call Forwarding
Transfer calls to a human when specific conditions are met:
| Setting | Description |
|---|---|
| Name | Name of the person/department |
| Forwarding Number | Phone number to transfer to |
| Global Condition | When to trigger (e.g., "customer asks for manager") |
Google Calendar
Connect your Google Calendar so the agent can check availability and book appointments:
| Setting | Description |
|---|---|
| Google Account | Connected Google account |
| Calendar | Which calendar to use |
| Timezone | Timezone for appointments |
| Working Days | Available days (Mon–Sun) |
| Working Hours | Start and end time |
| Slot Duration | Appointment length (minutes) |
API Tool RAG
Connect to external APIs for real-time information:
| Setting | Description |
|---|---|
| Name | Tool name |
| General Condition | When to query the API |
| Execution Message | What agent says while waiting for response |
| API Endpoint URL | External API endpoint |
| Method/Headers/Body | Request configuration |
| Request Timeout | Maximum wait time |
Post-Call Actions
Actions allow your agent to perform tasks after a conversation ends — sending emails, SMS, or calling external APIs. These are also managed in the Actions tab.
Retrieval Variables
Define custom variables that the AI extracts from conversations:
| Variable Type | Example Use |
|---|---|
| Text | Customer name, email, notes |
| Number | Quantity, budget, phone number |
| Boolean | Yes/no responses |
| Selector | Choice from predefined options |
Each variable needs:
- Name: Variable identifier
- Description: Instructions for the AI on when/how to extract this value
Available Actions
| Action | Purpose | Key Settings |
|---|---|---|
| Send Email | Email data after call | Recipients, subject, message template |
| Send SMS | Text message with data | Recipients, message template |
| Send WhatsApp | WhatsApp message with data | Recipients, message template |
| API Call | Send data to external API | Endpoint, method, headers, body |
Send Email Action
| Setting | Description |
|---|---|
| Name | Action identifier |
| Subject | Email subject line |
| Message | Content (can include extracted variables) |
| Condition | When to send (leave empty = always) |
| Recipient Email(s) | One or more email addresses |
Send SMS Action
Same as email, without subject line.
API Call Action
| Setting | Description |
|---|---|
| Name | Action identifier |
| Condition | When to trigger |
| API Endpoint URL | Where to send data |
| Method/Headers/Body | Request configuration |
Website Widgets
Embed your agent on any website. Access via the Widgets tab.
Floating Widget
A button that floats on your page (usually bottom-right corner):
<hanc-ai-floating-call agent-id="YOUR_AGENT_ID"></hanc-ai-floating-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
- Appears as a floating call button
- Exists outside your page layout
- Visitors click to start voice conversation
Inline Widget
Embeds directly into your page content:
<hanc-ai-inline-call agent-id="YOUR_AGENT_ID"></hanc-ai-inline-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
- Integrates into your page layout
- Can be placed anywhere in your content
- Good for dedicated "Talk to Us" sections
Copy your Agent ID from the Overview tab → Quick Actions → Copy AgentID
Managing Your Agent
The agent header toolbar and agent list provide several actions for managing your agents day-to-day.
Rename
Click "Rename" in the agent header toolbar to change the agent name. The new name takes effect immediately across the platform.
Duplicate
From the Voice Agents list, click the three-dot menu on an agent card and select "Duplicate". This clones the agent with all its settings — prompt, knowledge base, tools, actions, and configuration — so you can use it as a starting point for a new agent.
Delete
Click "Delete" in the agent header toolbar to remove an agent. Deletion uses a two-step confirmation: you must type the agent name to confirm. This prevents accidental removal.
Demo Call
Click the "Demo" button in the agent header to open a shareable demo page. Share this link with colleagues or stakeholders to let them test the agent without needing platform access.
Test Call
Click "Talk to Agent" for a browser-based test call using WebRTC (no phone required), or use a connected phone number to call the agent directly.
Phone Management
Assigned phone numbers appear as chips in the agent header. Click "Manage" to assign or remove phone numbers directly from the agent page.
Request Feature
Click "Request Feature" in the toolbar to send a feature request directly to the Hanc.AI team.
Testing Agents
Quick Actions (Overview Tab)
| Action | Description |
|---|---|
| Talk to agent | Test via browser (WebRTC) - no phone needed |
| Call Agent | Get phone numbers to test via real call |
| Copy AgentID | Copy agent identifier |
Browser Test (Talk to agent)
- Click "Talk to agent" in Quick Actions
- Allow microphone access in your browser
- Wait for agent greeting
- Speak naturally and test scenarios
- Click end call when done
Test Scenarios
Run through these scenarios:
| Scenario | What to Say | Expected Result |
|---|---|---|
| Greeting | (Just listen) | Agent greets appropriately |
| Simple question | "What are your hours?" | Correct business hours |
| Service inquiry | "What services do you offer?" | Service list |
| Booking | "I'd like to book an appointment" | Booking flow starts |
| Unknown topic | "What's the weather?" | Polite deflection |
| Frustration | (Sound annoyed) | Empathetic response |
| Transfer request | "I want to speak to a human" | Transfer initiated |
Test every scenario that matters for your business before going live. Pay special attention to edge cases and escalation triggers.
Test Call Logs
After testing, review:
- Full transcript
- Response times
- Any errors or issues
- Sentiment analysis
Managing Multiple Agents
When to Use Multiple Agents
| Scenario | Recommendation |
|---|---|
| Different departments | Separate agents (Sales, Support, Billing) |
| Different languages | Separate agents per language |
| Different brands | Separate agents per brand |
| Simple business | One agent handles everything |
Agent Organization
Use clear naming conventions:
[Department] - [Function] - [Language]
Examples:
- Sales - Inbound - EN
- Support - Tier 1 - DE
- Reception - Main - EN
Agent Analytics
Track agent performance:
Key Metrics
| Metric | Description | Good Target |
|---|---|---|
| Call Volume | Number of calls handled | Depends on business |
| Avg Duration | Average call length | 2-5 minutes typical |
| Resolution Rate | Calls completed without transfer | Above 70% |
| Sentiment | Customer satisfaction | Above 70% positive |
| Escalation Rate | Calls transferred to human | Below 30% |
Viewing Analytics
- Go to Dashboard for overview
- Click specific agent for detailed stats
- Use Call Logs for individual call analysis
Best Practices
- Keep prompts clear and specific
- Test thoroughly before deploying
- Update knowledge base regularly
- Monitor call logs for issues
- Iterate based on real conversations
- Set appropriate escalation triggers
- Make prompts too long or complex
- Deploy without testing
- Ignore negative sentiment patterns
- Let knowledge base become outdated
- Promise capabilities the agent doesn't have
- Skip escalation paths
Guides in This Section
Prompt Engineering
Write effective prompts that define agent behavior
Actions & Tools
Call forwarding, Google Calendar, actions, retrieval variables
Website Widgets
Embed voice agents on your website
Settings
Voice, call behavior, and post-call analysis