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
┌─────────────────────────────────────────────────────────────────┐
│ VOICE AGENT │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ PROMPT │ │ KNOWLEDGE BASE │ │
│ │ (Behavior) │ │ (Information) │ │
│ └────────┬────────┘ └────────┬────────┘ │
│ │ │ │
│ └──────────┬───────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────┐ │
│ │ AI ENGINE │ │
│ │ (LLM Processing) │ │
│ └─────────────────────┘ │
│ │ │
│ ┌──────────┴──────────┐ │
│ ▼ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ VOICE │ │ TOOLS │ │
│ │ (TTS/STT) │ │ (Actions) │ │
│ └─────────────────┘ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
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 |
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 |
Model Settings
The AI "brain" configuration:
First Message
The greeting when the agent answers:
Hello! Thank you for calling ABC Company. How can I assist you today?
Best practices:
- 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
Connect information sources. See Knowledge Base section.
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 |
| 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
Tip: Match voice to your brand:
- Professional services → Calm, mature voice
- Youth brands → Energetic, younger voice
- Healthcare → Warm, reassuring voice
Agent Tools
Tools extend what your agent can do beyond conversation. Access via the Tools tab in agent settings.
Available Tools
| Tool | Purpose | Configuration |
|---|---|---|
| Call Forwarding | Transfer to human operator | Name, forwarding number, trigger condition |
| Book Appointment | Schedule via Cal.com | API key, Event ID, SMS confirmation option |
| 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") |
Book Appointment (Cal.com)
Schedule appointments using Cal.com calendar integration:
| Setting | Description |
|---|---|
| Name | Scheduler name |
| General Condition | When to offer booking |
| API Key | Your Cal.com API key |
| Event ID | Cal.com event identifier |
| Book an appointment | If disabled, only checks availability |
| Confirmation | No confirmation / SMS confirmation |
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 |
Agent Actions
Actions allow your agent to perform tasks based on conversation data. Access via 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 |
| 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):
<script src="https://widget.hanc.ai/floating.js" agent-id="YOUR_AGENT_ID"></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:
<script src="https://widget.hanc.ai/inline.js" agent-id="YOUR_AGENT_ID"></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
Testing Agents
Quick Actions (Overview Tab)
| Action | Description |
|---|---|
| Talk to agent | Test via browser (WebRTC) - no phone needed |
| Demo | Open demo page for sharing |
| 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 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
Do's
✅ 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
Don'ts
❌ 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 — Writing effective prompts
Related Topics
- Knowledge Base — Information sources for agents
- Phone Numbers — Connecting agents to phone lines
- Analytics — Performance monitoring
- Templates — Ready-to-use configurations