Skip to main content

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. During a guest turn, AVA shows voice lookup progress no more than once.

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​

SettingWhat It ControlsGuest Outcome
Voice Welcome MessageFirst spoken message in a voice sessionGuests hear a clear hotel greeting
Voice Default AnswerReply when no reliable answer existsGuests still get a polite response
InstructionTone and behavior guidance for voice AIReplies match your hotel communication style
Topic SuggestionsSidebar prompts for common guest questionsGuests see Vertex RAG suggestions or legacy fallback topics
RAG Request TimeoutMaximum wait for a voice answerSlow replies keep running until the max limit
First Chunk TimeoutWait for the first streamed answer chunkLong pauses stop stalled AI replies earlier
Stream Idle TimeoutWait between streamed chunksBroken 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.

Use Guest Stay and Housekeeping Requests​

The voice assistant can use verified current-stay details to answer guest questions. For a static room QR session, AVA refreshes the link before voice use when exactly one active in-house stay matches the scanned room. AVA also allows one native DUE_OUT stay to match when your PMS capability contract supports that status. Otherwise, static room QR lookup matches CHECKED_IN stays only. The lookup uses the exact room value encoded in the QR code. For a static location QR session, AVA keeps location context only. It does not perform reservation verification, stay linking, or reservation-based video enrichment. It can also help guests request configured guest services.

Guest requestVoice assistant behavior
Ask about the current stayUses the verified reservation context available for that guest
Ask for a guest serviceRecaps the exact request aloud and asks the guest to confirm before submitting it
Request lacks required detailsExplains what information is missing or offers available services
Ask about a room before check-inDoes not expose the pre-check-in room number through the voice flow
Use a location QR sessionUses location context without reservation details
Confirmation is required

Only an explicit guest confirmation submits or cancels a guest service request. If the conversation changes, the guest must confirm the request again. After confirmation, AVA submits the prepared request that the guest reviewed. Natural confirmations such as “I confirm” and “I confirm it” are accepted. AVA does not accept a confirmation that changes the prepared request. The assistant recaps the prepared request aloud before asking for confirmation. This is an audio-only flow. The voice flow never refers to anything shown, displayed, or on screen. It also never refers to content above, below, or any other visual cue. The guest only confirms the spoken request and never provides internal request fields. If a request cannot be validated, the assistant keeps the guest-safe explanation. It can ask for missing details or offer services configured for the hotel.

Test guest voice requests​

  1. Start a voice session with a verified current-stay test reservation.

  2. Ask a question about the stay.

  3. Ask for a guest service, such as extra towels.

  4. Listen for the assistant to recap the exact request aloud.

  5. Say “I confirm” or “I confirm it” without changing the request.

    ✓ The assistant answers with available stay information. ✓ The assistant recaps the request without referring to a screen or display. ✓ The request submits only after confirmation.

Ask for a service without all required details during testing.

✓ The assistant explains what information it needs. ✓ The assistant can offer available services instead of giving a generic refusal.

Use a pre-check-in test reservation to confirm that its room number stays private.

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.

SettingWhat It ControlsDefault
VOICE_GATEWAY_RAG_REQUEST_TIMEOUT_MSMaximum time for a full RAG request60000
VOICE_GATEWAY_RAG_FIRST_CHUNK_TIMEOUT_MSTime to wait for the first streamed chunk30000
VOICE_GATEWAY_RAG_STREAM_IDLE_TIMEOUT_MSTime to wait between streamed chunks15000

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

The guest service request does not submit​

What you see: The assistant recaps a guest service request, but no request is submitted.

Fix:

  1. Answer the assistant's confirmation question clearly.
  2. Repeat the guest service request if the conversation changed topics.
  3. Start a new voice session if the confirmation prompt expired.
  4. Contact support if a confirmed request still does not submit.

The assistant refers to a screen or display​

What you see: The assistant mentions something shown, displayed, above, or below.

Fix:

  1. Ask the assistant to recap the complete request aloud.
  2. Confirm the spoken request only when every detail is correct.
  3. Contact support if the assistant continues using visual references.

The assistant does not accept a changed confirmation​

What you see: The guest confirms, but adds a different time, quantity, or service detail.

Fix:

  1. Let the assistant prepare the updated request.
  2. Wait for the assistant to repeat the complete request.
  3. Say “I confirm” or “I confirm it” without changing the request.

The assistant asks for more request details​

What you see: The assistant asks for missing information or suggests available services.

Fix:

This is expected when the housekeeping request cannot be validated yet. Provide the requested details, then confirm the complete request.

A pre-check-in room number is spoken​

What you see: The assistant speaks a room number before the guest checks in.

Fix:

  1. End the voice session.
  2. Record the guest's reservation and call details.
  3. Contact support immediately for review.

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