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

# AI Voice Agents

> Create and manage intelligent AI voice agents for automated phone conversations

## What are AI Voice Agents?

AI Voice Agents are intelligent conversational AI systems that can conduct natural phone conversations with your customers. They can understand speech, respond contextually, detect intents, and complete tasks autonomously.

## Key Features

<CardGroup cols={2}>
  <Card title="Natural Conversations" icon="comments">
    Engage in human-like conversations with context awareness
  </Card>

  <Card title="Intent Detection" icon="bullseye">
    Automatically detect and act on user intents
  </Card>

  <Card title="Multi-language" icon="language">
    Support for multiple languages and accents
  </Card>

  <Card title="Real-time Transcription" icon="closed-captioning">
    Live transcription and sentiment analysis
  </Card>
</CardGroup>

## Creating Your First Agent

### Step 1: Access Agent Configuration

1. Log in to your Mindhunters dashboard at `https://your-tenant.mindhunters.ai`
2. Navigate to **Agents** in the main menu
3. Click **"Create New Agent"**

### Step 2: Configure Basic Settings

<AccordionGroup>
  <Accordion title="Agent Name" icon="tag">
    Give your agent a descriptive name (e.g., "Customer Support Agent", "Appointment Scheduler")
  </Accordion>

  <Accordion title="Voice Selection" icon="microphone">
    Choose from multiple voice options:

    * **Gender**: Male, Female, Neutral
    * **Accent**: US, UK, Australian, etc.
    * **Tone**: Professional, Friendly, Formal
  </Accordion>

  <Accordion title="Language" icon="language">
    Select the primary language for conversations:

    * English (US, UK, Australian)
    * Spanish
    * French
    * German
    * And more...
  </Accordion>
</AccordionGroup>

### Step 3: Define Agent Behavior

The agent prompt defines how your AI behaves during conversations.

**Example Prompts:**

<CodeGroup>
  ```text Customer Support Agent theme={null}
  You are a helpful customer support agent for Acme Corporation.

  Your role:
  - Greet customers warmly
  - Listen to their concerns
  - Provide accurate information about products and services
  - Escalate complex issues to human agents when needed

  Guidelines:
  - Be polite and professional
  - Ask clarifying questions
  - Confirm understanding before taking action
  - Thank customers for their time

  If you cannot help, say: "Let me connect you with a specialist who can better assist you."
  ```

  ```text Appointment Scheduler theme={null}
  You are an appointment scheduling assistant.

  Your role:
  - Confirm the customer's identity
  - Check their availability
  - Schedule appointments for available time slots
  - Send confirmation details

  Available time slots:
  - Monday-Friday: 9 AM - 5 PM
  - Appointments are 30 minutes long

  Process:
  1. Greet and confirm customer name
  2. Ask about preferred date and time
  3. Check availability
  4. Confirm appointment details
  5. Provide confirmation number
  ```

  ```text Survey Collector theme={null}
  You are conducting a customer satisfaction survey.

  Ask these questions in order:
  1. On a scale of 1-10, how satisfied are you with our service?
  2. What did you like most about your experience?
  3. What could we improve?
  4. Would you recommend us to others?

  Guidelines:
  - Be friendly and conversational
  - Thank them for each response
  - Don't rush through questions
  - End with appreciation for their time
  ```
</CodeGroup>

### Step 4: Configure Intent Detection

Intents are specific actions or goals users express during conversations.

**Common Intents:**

| Intent              | Description                       | Example Phrases                              |
| ------------------- | --------------------------------- | -------------------------------------------- |
| transfer\_to\_human | User wants to speak with a person | "Can I talk to someone?", "I need a human"   |
| request\_callback   | User wants a callback             | "Call me back", "Can someone call me later?" |
| billing\_inquiry    | Questions about billing           | "Check my bill", "Payment question"          |
| cancel\_service     | User wants to cancel              | "Cancel my subscription", "Stop service"     |
| technical\_support  | Technical help needed             | "It's not working", "Technical issue"        |

**Setting up Intents:**

1. Go to Agent Settings → **Intents**
2. Click **"Add Intent"**
3. Define:
   * Intent name
   * Trigger phrases
   * Action to take (trigger webhook, transfer call, etc.)

### Step 5: Test Your Agent

Before deploying, test your agent:

1. Click **"Test Agent"** in the dashboard
2. Call the test number provided
3. Have a conversation
4. Review the transcription
5. Refine prompts and settings as needed

## Using Agents via API

Once your agent is created, you can initiate calls programmatically:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://your-tenant.mindhunters.ai/api/v1/call \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "agentId": "550e8400-e29b-41d4-a716-446655440000",
      "participant": {
        "number": "+1234567890",
        "name": "John Doe"
      },
      "greetingMessage": "Hello! This is a call from Acme Corp."
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://your-tenant.mindhunters.ai/api/v1/call', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      agentId: '550e8400-e29b-41d4-a716-446655440000',
      participant: {
        number: '+1234567890',
        name: 'John Doe'
      },
      greetingMessage: 'Hello! This is a call from Acme Corp.'
    })
  });

  const data = await response.json();
  console.log('Call initiated:', data.data.id);
  ```

  ```python Python theme={null}
  import requests

  url = "https://your-tenant.mindhunters.ai/api/v1/call"
  headers = {
      "Authorization": "Bearer YOUR_API_TOKEN",
      "Content-Type": "application/json"
  }
  payload = {
      "agentId": "550e8400-e29b-41d4-a716-446655440000",
      "participant": {
          "number": "+1234567890",
          "name": "John Doe"
      },
      "greetingMessage": "Hello! This is a call from Acme Corp."
  }

  response = requests.post(url, headers=headers, json=payload)
  call_data = response.json()
  print(f"Call initiated: {call_data['data']['id']}")
  ```
</CodeGroup>

## Agent Analytics

Track agent performance in real-time:

### Available Metrics

* **Total Calls**: Number of calls handled
* **Average Duration**: Mean call length
* **Success Rate**: Percentage of successful completions
* **Intent Detection**: Most common intents triggered
* **Sentiment Analysis**: Overall sentiment distribution
* **Transcription Quality**: Speech recognition accuracy

### Viewing Analytics

1. Go to **Agents** → Select your agent
2. Click **"Analytics"** tab
3. Choose date range
4. Export data as needed

## Best Practices

<AccordionGroup>
  <Accordion title="Write Clear Prompts" icon="pencil">
    * Be specific about agent's role and capabilities
    * Include example responses
    * Define boundaries (what agent should NOT do)
    * Use bullet points for clarity
  </Accordion>

  <Accordion title="Test Thoroughly" icon="vial">
    * Test with various conversation scenarios
    * Include edge cases and unusual requests
    * Test with different accents and speech patterns
    * Review transcriptions for accuracy
  </Accordion>

  <Accordion title="Handle Escalations" icon="arrow-up">
    * Always provide a path to human assistance
    * Set up transfer intents
    * Configure callback options
    * Train agents when to escalate
  </Accordion>

  <Accordion title="Monitor Performance" icon="chart-line">
    * Review transcriptions regularly
    * Track success and failure rates
    * Identify common issues
    * Iterate on prompts based on data
  </Accordion>

  <Accordion title="Respect Privacy" icon="shield">
    * Don't collect unnecessary personal information
    * Inform users they're speaking with AI
    * Comply with recording consent laws
    * Follow GDPR and data privacy regulations
  </Accordion>
</AccordionGroup>

## Common Use Cases

### Customer Support

```text Agent Prompt theme={null}
You are a customer support agent for [Company Name].

Capabilities:
- Answer questions about products and services
- Help with account issues
- Process refund requests
- Schedule callbacks

If customer needs:
- Password reset → Guide them to reset link
- Refund → Collect order number and reason
- Technical issue → Transfer to tech support
- Billing question → Verify account and provide info

Always be patient, empathetic, and helpful.
```

### Appointment Scheduling

```text Agent Prompt theme={null}
You are an appointment booking assistant for [Business Name].

Process:
1. Greet customer: "Hello! I can help you schedule an appointment."
2. Confirm their name and phone number
3. Ask for preferred date and time
4. Check availability (Mon-Fri, 9 AM-5 PM)
5. Confirm appointment details
6. Provide confirmation number

If slot unavailable, offer 2-3 alternatives.
If they need to reschedule, collect existing appointment details first.
```

### Lead Qualification

```text Agent Prompt theme={null}
You are a sales qualification assistant.

Your goal: Qualify leads by gathering information.

Questions to ask:
1. What product/service are you interested in?
2. What's your timeline for making a decision?
3. What's your budget range?
4. Who else is involved in the decision?

Based on answers:
- High priority: Budget >$10k, timeline <30 days → Schedule demo
- Medium priority: Budget $5-10k → Send information packet
- Low priority: Just researching → Add to newsletter

Be conversational, not interrogative.
```

## Troubleshooting

### Agent Not Responding

* Check agent is activated
* Verify phone number format (E.164)
* Check API token is valid
* Review error logs in dashboard

### Poor Transcription Quality

* Ensure good audio quality
* Check for background noise
* Verify language setting matches caller
* Test with different voice options

### Intent Not Detecting

* Add more trigger phrases
* Make phrases more specific
* Test intent configuration
* Review transcriptions for actual phrases used

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference">
    See full API documentation
  </Card>

  <Card title="Webhooks" icon="webhook" href="/webhooks">
    Get real-time conversation updates
  </Card>

  <Card title="Campaigns" icon="bullhorn" href="/guides/services/campaigns">
    Create agent-powered campaigns
  </Card>

  <Card title="Monitoring" icon="chart-line" href="/monitoring">
    Track agent performance
  </Card>
</CardGroup>