# Voice Agents

Stand up an after-hours room support hotline. End-clients pick up the conference room phone, dial your number, and get an AVCodex agent that knows their rack, their codebase, and their commissioning history. No 2 a.m. truck rolls for a stuck Q-SYS core.

---

Turn your AVCodex agent into a voice agent that handles phone calls. Users call a dedicated phone number and have natural voice conversations with your AI. Field techs use it hands-free in the rack. End-clients use it as a 24/7 support line.

> **Note:** Voice Agents require a **Builder plan** or higher. No approval step is needed. Open your agent's **Build** page and toggle on Voice Mode to get started.

## What Voice Agents Can Do

- **Inbound calls**: End-clients or techs call your number to talk to your AVCodex agent
- **Natural conversation**: Real-time speech-to-text and text-to-speech powered by OpenAI
- **Multiple voices**: Choose from 9 different voice options
- **Custom greetings**: Set how your agent introduces itself when it answers
- **Web voice mode**: Enable voice chat in your web embed too, useful when a tech is on a ladder with a phone clipped to a belt

## Getting Started

Once voice is enabled for your account, the Voice card will appear on your Build page.

  **1.**
    **Open Voice Settings**

    Go to your agent's **Build** page. You'll see a **Voice** card in the sidebar (only visible if voice is enabled for your organization).

  **2.**
    **Enable Voice Mode**

    Toggle on **Enable Voice Mode** to activate voice capabilities for your agent.

  **3.**
    **Select a Voice**

    Choose from the available OpenAI voices. Each has a different tone and personality.

  **4.**
    **Set Your Greeting**

    Enter a **Welcome Greeting**, the message your agent speaks when it answers a call.

  **5.**
    **Get a Phone Number**

    Click **Select Number** to open the phone number selection dialog:

    1. Choose your country (US or Canada currently available)
    2. Optionally filter by area code or city
    3. Click **Search Numbers** to see available options
    4. Select a number from the list
    5. Click **Save** to provision it

  **6.**
    **Test Your Voice Agent**

    Call your new phone number to test the experience. Your AVCodex agent will answer with your greeting and respond to your voice. Try: "the projector in Boardroom 3 isn't waking up."

## Voice Configuration Options

### Available Voices

Choose from these OpenAI voices:

| Voice | Description |
|-------|-------------|
| **Alloy** | Neutral, versatile |
| **Ash** | Clear, professional |
| **Ballad** | Warm, melodic |
| **Coral** | Friendly, approachable |
| **Echo** | Deep, authoritative |
| **Marin** | Natural, conversational (default) |
| **Sage** | Calm, thoughtful |
| **Verse** | Expressive, dynamic |
| **Cedar** | Balanced, reliable |

### Welcome Greeting

Set what your agent says when it answers a call:

```
Hi, you've reached the after-hours room support line for Acme AV.
Tell me which room you're in and what you're seeing.
```

Keep greetings short and friendly. End-clients calling about a frozen room controller want to get to their question quickly.

### Set as Default

Check **Set voice mode as the default interaction method** if you want users to start in voice mode when they open your web chat. Otherwise, they'll start in text chat mode and can switch to voice.

## Web Voice Mode

When voice is enabled, users can also use voice chat in your web embed:

- A microphone button appears in the chat interface
- Field techs can speak instead of typing (handy when hands are full of cable)
- Your agent responds with voice
- Works alongside regular text chat

## Best Practices

### Writing Voice-Optimized Prompts

Voice conversations differ from text chats. Optimize your system prompt:

**Do:**
- Use short, clear sentences
- Include common spoken phrases
- Handle "um", "uh", and partial sentences gracefully
- Provide brief, focused answers

**Don't:**
- Include long lists (hard to follow verbally)
- Use complex formatting (markdown, tables)
- Reference visual elements

**Example prompt addition:**
```
When responding via voice:
- Keep answers under 3 sentences when possible
- Ask clarifying questions if the request is unclear
- Use conversational language, not formal writing
- For multi-step procedures (like rebooting a Q-SYS Core),
  walk through one step at a time and wait for confirmation.
```

### Handling Common Scenarios

#### Silence or No Response
Configure your agent to handle silence gracefully:
```
If the user is silent for more than 5 seconds, gently prompt:
"Are you still there? Take your time. Tell me what room you're in."
```

#### Background Noise
Speech recognition may pick up background sounds (rack fans, HVAC, projector noise). Your agent should handle unclear input:
```
If you don't understand what was said, politely ask the user
to repeat themselves rather than guessing.
```

#### Call Transfers
If your use case requires transferring to humans:
```
If the user says the issue is mission-critical (a live event,
a CEO town hall, a courtroom session) or asks for a human,
provide the on-call dispatcher number and offer to have
someone call them back.
```

## Monitoring Conversations

Voice conversations appear in your AVCodex dashboard alongside text chats:

1. Go to **Chats** in your agent
2. Use the **Source** filter to select **Voice**
3. View full transcripts of what was said
4. See conversation timestamps and duration

## Pricing

Voice calls are billed based on usage:

| Component | Cost |
|-----------|------|
| Call minutes | $0.015/minute |
| Phone number | ~$1.15/month |
| AI processing | Included in your plan |

## Troubleshooting

### Voice Card Not Showing

The Voice card only appears on agents owned by organizations on a **Builder plan** or higher. If you're already on a qualifying plan and the card is missing, try a hard reload of the Build page.

### Calls Not Connecting

1. Verify you have a phone number assigned in Voice settings
2. Check that voice mode is enabled (toggle is on)
3. Ensure your AVCodex agent is published

### AI Can't Understand Users

1. Ask users to step away from the rack or close the IDF door, background noise hurts STT accuracy
2. Keep your system prompt focused on voice interactions
3. Test with different voices, some may work better for your use case

### Voice Sounds Robotic or Unnatural

1. Try a different voice from the dropdown
2. Ensure your greeting and prompts are conversational
3. Shorter responses generally sound more natural

### Long Pauses in Conversation

1. Check your AI model, faster models respond quicker
2. Reduce the complexity of your system prompt
3. Ensure your custom actions (if any) are performant. Pulling a 200-page manufacturer spec sheet on every turn will introduce lag.

## Using with MCP

You can manage voice agent configuration programmatically using the AVCodex MCP Server.

### Available Tools

| Tool | Description |
|------|-------------|
| `get_voice_config` | Get voice agent configuration |
| `update_voice_config` | Update voice settings (voice, language, etc.) |

### Example Prompts

```
"Show me the voice configuration for my room support bot"
"Change the voice to 'Sage' for a calmer tone"
"Enable Spanish support for my voice agent"
"What phone number is assigned to my agent?"
```

### Workflow: Voice Configuration

```
You: Show me the voice setup for my room support agent

AI: [Calls get_voice_config]

Voice Agent Configuration:
- Status: Enabled
- Phone Number: +1 (555) 123-4567
- Voice: Marin (natural, conversational)
- Language: English
- Welcome Greeting: "Hi! How can I help you today?"
- Web Voice Mode: Enabled

You: Change the voice to Sage for a calmer tone

AI: [Calls update_voice_config with voiceId="sage"]
Updated voice to "Sage". New calls will use this voice.
```

> **Note:** MCP server access requires a Builder plan or higher. See the [MCP Setup Guide](../guides/mcp/setup.md) to get started.

*AVCodex · Your AV expertise. Amplified by AI.*