# Voice Agents

Deploy your AI as a voice agent that can handle phone calls and real-time voice conversations.


Transform your Chipp AI into a voice agent that can handle phone calls. Users can call a dedicated phone number and have natural voice conversations with your AI.

<Callout type="info">
Voice Agents is currently in beta. To enable this feature for your account, contact **support@chipp.ai** and request access.
</Callout>

## What Voice Agents Can Do

- **Inbound calls**: Users call your number to talk to your AI
- **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 AI introduces itself when it answers
- **Web voice mode**: Enable voice chat in your web chatbot too

## Getting Started

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

<Steps>
  <Step title="1">
    <strong>Open Voice Settings</strong>

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

  <Step title="2">
    <strong>Enable Voice Mode</strong>

    Toggle on **Enable Voice Mode** to activate voice capabilities for your app.
  </Step>

  <Step title="3">
    <strong>Select a Voice</strong>

    Choose from the available OpenAI voices. Each has a different tone and personality.
  </Step>

  <Step title="4">
    <strong>Set Your Greeting</strong>

    Enter a **Welcome Greeting** - the message your AI speaks when it answers a call.
  </Step>

  <Step title="5">
    <strong>Get a Phone Number</strong>

    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
  </Step>

  <Step title="6">
    <strong>Test Your Voice Agent</strong>

    Call your new phone number to test the experience. Your AI will answer with your greeting and respond to your voice.
  </Step>
</Steps>

## 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 AI says when it answers a call:

```
Hi! I'm your AI assistant from Acme Corp. How can I help you today?
```

Keep greetings short and friendly. Users 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 chatbot on the web. 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 chatbot:

- A microphone button appears in the chat interface
- Users can speak instead of typing
- Your AI 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
```

### Handling Common Scenarios

#### Silence or No Response
Configure your AI to handle silence gracefully:
```
If the user is silent for more than 5 seconds, gently prompt:
"Are you still there? Feel free to ask me anything."
```

#### Background Noise
Speech recognition may pick up background sounds. Your AI 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 asks to speak to a human or says their issue
is urgent, provide your support phone number and offer
to have someone call them back.
```

## Monitoring Conversations

Voice conversations appear in your Chipp dashboard alongside text chats:

1. Go to **Chats** in your app
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

Voice is a beta feature that must be enabled for your organization. Contact support@chipp.ai to request access.

### 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 Chipp app is published

### AI Can't Understand Users

1. Ask users to speak clearly and reduce background noise
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