Voice Agents

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.

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.

Voice Configuration Options

Available Voices

Choose from these OpenAI voices:

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.

Require Caller Verification

Phone caller ID (the number a call appears to come from) can be spoofed. If your voice agent can look up or change something for a specific caller, Require caller verification adds a second identity check: a 6-digit code from an authenticator app (like Google Authenticator or Authy), the same kind of code used for two-factor login on most websites.

This feature uses time-based one-time passwords (TOTP, RFC 6238): the industry standard for authenticator apps. When enabled, callers must pass a TOTP verification challenge before the agent will use any of its tools, even if ANI (automatic number identification) matches a known caller.

How It Works

Caller Experience

Enrolled callers:

• Provide their current TOTP code during the call (usually takes 10-20 seconds)
• Code changes every 30 seconds, so they need to read it while it’s still valid
• After 5 wrong attempts, they must wait 15 minutes before trying again
• Can manage or revoke their enrolled authenticator anytime from their account page

Un-enrolled callers:

• Hear your agent explain that caller verification is required (you control the exact wording via your system prompt)
• If you’ve configured SMS, they may receive a text with a link to enroll
• Can then go to the enrollment page, scan the QR code, and confirm (takes about 1 minute)
• After enrolling, they can hang up and call back to verify

Callers without SMS or enrollment capability:

• Should be handled per your system prompt (offer alternative verification, transfer to a human, etc.)
• The feature fails safely: the agent simply won’t use tools, and callers know why

Setting Up Caller Verification

If a caller needs tool access (looking up their account, booking an appointment, etc.),
ask them to provide their 6-digit verification code from their authenticator app
(Google Authenticator, Authy, or similar). The code changes every 30 seconds.

If they don't have one enrolled, explain that they can enroll by going to
the Account & Security page in the web chat.

Managing Enrollment

Callers manage their TOTP secret from the Account & Security page in your app’s web chat:

• Enroll: Scan the QR code with an authenticator app and confirm with one code
• Rotate: Generate a new secret (useful if you lose access to your authenticator app). The new secret takes effect immediately and the old one becomes invalid.
• Revoke: Delete your enrollment. You’ll need to enroll again before your next call.

Enrollment is app-specific. A caller enrolled on your app will not be verified on another app: each app maintains independent enrollments.

Security Notes

• Secrets are encrypted at rest in the database
• Verification codes are 6 digits (1 million possibilities) and valid for only 30 seconds
• The server uses a standard TOTP window of ±1 time step (60 seconds total window) to tolerate clock skew
• Each code can be used only once per call (single-use enforcement prevents replay attacks)
• Failed verification attempts are rate-limited (max 5 per call, then 15-minute lockout)
• The agent never sees the secret or the expected code: only the server does
• Verification is tied to the call session; there are no persistent authenticated sessions

Compatibility

Any RFC 6238-compliant authenticator app works:

• Google Authenticator (Android, iOS)
• Authy (Android, iOS, browser)
• Microsoft Authenticator (Android, iOS)
• Duo Mobile (Android, iOS)
• FreeOTP (Android, iOS)
• andOTP (Android)
• And any other standard TOTP client

Troubleshooting

Callers say their code is wrong even though they entered it correctly:

Authenticator codes are time-based (30-second window). If they’re reading slowly or there’s network delay, the code may have expired. Coach them to read the code and have the agent enter it within 10 seconds. The server accepts codes from a 60-second window (current ±1 step), which usually covers clock skew, but if they’re on the boundary it can help to re-read the code quickly.

Un-enrolled callers don’t know how to enroll:

Your system prompt and initial agent response are key. Be explicit: “To proceed, you’ll need to enroll a free authenticator app. I can send you a link via text if you’d like.” Make sure the enrollment page is easy to find (it’s in their account/security settings).

Too many lockouts (5 failed attempts per call):

Lockout is 15 minutes to prevent brute-force. If callers are consistently failing, coach them on the 30-second timing and consider a more forgiving UX in your system prompt (e.g., offering to call them back later, or transferring to a human).

This is unrelated to call transfers or Smart Routing — it’s purely about whether the agent will use tools on a caller’s behalf.

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:

Troubleshooting

Voice Card Not Showing

The Voice card only appears on apps 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 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

Using with MCP

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

Available Tools

Example Prompts

"Show me the voice configuration for my 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 app?"

Workflow: Voice Configuration

You: Show me the voice setup for my customer service app

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.