Set Up Voice Assistant Prompts

Quick Setup

Set a greeting, fallback reply, and instruction in about 5 minutes.

This guide helps you control what guests hear when they use the voice assistant.

It also explains how topic suggestions use Vertex RAG first when file IDs are present. When file IDs are missing, the helper still falls back to legacy retrieval. You can also tune voice response timing. The gateway now waits for a finalized transcript before using explicit audio turns.

Runtime default

If OPENAI_REALTIME_MODEL is unset, AVA uses gpt-realtime-2.1-mini. Set the variable explicitly if your team wants a different Realtime model.

Vertex AI platform

Voice replies use the same configured Vertex AI platform as chatbot replies. If voice answers look unexpected, confirm the platform setting first.

Go to: Chatbot → Voice Setup

---

Quick Reference

Setting	What It Controls	Guest Outcome
Voice Welcome Message	First spoken message in a voice session	Guests hear a clear hotel greeting
Voice Default Answer	Reply when no reliable answer exists	Guests still get a polite response
Instruction	Tone and behavior guidance for voice AI	Replies match your hotel communication style
Topic Suggestions	Sidebar prompts for common guest questions	Guests see Vertex RAG suggestions or legacy fallback topics
RAG Request Timeout	Maximum wait for a voice answer	Slow replies keep running until the max limit
First Chunk Timeout	Wait for the first streamed answer chunk	Long pauses stop stalled AI replies earlier
Stream Idle Timeout	Wait between streamed chunks	Broken streams fail before they hang forever

Plan Access

• Voice setup requires a paid plan.
• Free-tier accounts see an upgrade prompt and cannot save voice settings.

To upgrade, go to Settings → Billing & Subscription.

Before You Start

Confirm these requirements:

• You have permission to manage chatbot setup
• Your plan includes AI chatbot features
• You know your preferred greeting and fallback wording
• Your technical team knows the current voice gateway timeout settings

Configure Voice Messages

1. Go to Chatbot → Voice Setup

2. In Voice Messages, update Voice Welcome Message

3. Update Voice Default Answer

4. Click Save on each card

   ✓ A success message appears. ✓ A saved timestamp appears beside the button.

Set the Voice Instruction

1. On the same page, find Voice Instruction

2. Describe tone, phrasing rules, and fallback behavior

3. Click Save

   ✓ The instruction is stored for future voice replies.

If the instruction is blank

Saving a blank instruction applies the default friendly voice instruction.

Handle Optional Voice Helpers

The voice sidebar asks the gateway for suggested topics.

When the request includes Vertex RAG file IDs, AVA reads those documents first. Other optional voice helpers, like transcript lexicon and knowledge coverage, use the same pattern. When file IDs are missing, AVA uses the legacy vector store instead. Explicit audio turns now wait for a finalized transcript before they can trigger RAG. This prevents unrelated tool calls when the microphone is silent or unavailable.

This keeps the voice flow moving instead of showing a 502 error.

What you see: The topics list is empty or looks stale.

Fix:

1. Keep the voice session open and continue the conversation
2. Refresh the page if you expect newer suggestions
3. Confirm the related chatbot document is marked Active
4. Confirm the voice request includes Vertex RAG file IDs
5. Confirm the gateway can reach the chat microservice

What changed

Voice helpers now fail open. Guests can still continue, even if helper data is unavailable.

Audio turns do not trigger the expected reply

What you see: A guest speaks, but the assistant ignores the turn or answers late.

Fix:

1. Confirm the microphone is working and is not muted
2. Wait for the transcript to finalize before testing again
3. Start a new voice session if the turn was superseded
4. Redeploy the voice gateway after any runtime changes

Why this happens

The gateway rejects explicit audio tool calls until it has a finalized transcript. This avoids unrelated RAG lookups from silent or incomplete audio turns.

Tune Voice Response Timing

Use these gateway settings when voice answers feel too slow or stall mid-reply.

Setting	What It Controls	Default
VOICE_GATEWAY_RAG_REQUEST_TIMEOUT_MS	Maximum time for a full RAG request	60000
VOICE_GATEWAY_RAG_FIRST_CHUNK_TIMEOUT_MS	Time to wait for the first streamed chunk	30000
VOICE_GATEWAY_RAG_STREAM_IDLE_TIMEOUT_MS	Time to wait between streamed chunks	15000

How the timeouts work

• Streaming replies use the first-chunk timeout first.
• After the first chunk, idle timeout protects active streams.
• Non-streaming replies use only the max request timeout.
• The gateway raises the default max request timeout to 60 seconds.

When to adjust them

What you see: The assistant stops before a slow answer finishes.

Fix:

1. Increase VOICE_GATEWAY_RAG_FIRST_CHUNK_TIMEOUT_MS
2. Increase VOICE_GATEWAY_RAG_REQUEST_TIMEOUT_MS if answers still time out
3. Increase VOICE_GATEWAY_RAG_STREAM_IDLE_TIMEOUT_MS if streams pause between chunks
4. Redeploy the voice gateway after changing environment values

What you see: Answers keep running, but nothing arrives for a while.

Fix:

1. Lower VOICE_GATEWAY_RAG_FIRST_CHUNK_TIMEOUT_MS
2. Lower VOICE_GATEWAY_RAG_STREAM_IDLE_TIMEOUT_MS
3. Keep the max request timeout high enough for your AI provider

Recommended Message Pattern

1. Keep Voice Welcome Message short and natural
2. Keep Voice Default Answer polite and action-oriented
3. Use Instruction for stable rules, not one-time announcements

Good default answer example

"I’m sorry, I don’t have that information right now. Please ask the front desk team for help."

Troubleshooting

Save fails with "Invalid content"

What you see: You click Save and get a validation error.

Fix:

1. Confirm the field is plain text
2. Remove very long text blocks
3. Try saving again

Voice replies do not match your instruction

What you see: Guests hear responses that do not follow your expected tone.

Fix:

1. Open Instruction and make rules more specific
2. Click Save
3. Start a new voice session and test again

Voice setup page is missing

What you see: You cannot find Voice Setup in the sidebar.

Fix:

1. Confirm your plan includes AI chatbot tools
2. Confirm your role has chatbot setup permissions
3. Refresh the page after access changes

Topic suggestions look empty

What you see: The voice sidebar shows no suggested topics.

Fix:

1. Continue using the voice flow
2. Check whether the related chatbot document is still Processing
3. Verify the gateway can reach the chat microservice
4. Review cached topic settings if the list stays stale

Still Stuck?

Contact success@vouch-technologies.com if:

• ❌ Saves keep failing after retries
• ❌ Voice responses ignore saved prompts
• ❌ Voice replies still time out after adjusting gateway settings
• ❌ The issue continues for more than 30 minutes

Helpful to include:

• Screenshot of your Voice Setup page
• Exact text you tried to save
• The timeout values currently in use
• Time the issue started

Related Guides

• Set Up Your Chatbot
• Manage Chatbot Documents
• Create a Live Chat Link for Guests