Set Up Phone AI for Incoming Calls

Quick Setup

Connect one Twilio number, test its webhook, then activate Phone AI. This usually takes about 10 minutes.

This guide helps you answer incoming hotel calls with AVA and review each call transcript.

Go to: Communication Hub → Phone AI

Hotel-specific activation

Phone AI settings belong to the selected hotel. Each hotel needs its own Twilio number, saved credentials, and activation.

Quick Reference

Setting	What It Controls	What You See
Twilio Account SID	Selects the Twilio account	An identifier beginning with AC
Twilio phone number	Receives guest calls	A number with + and country code
Twilio Auth Token	Authorises AVA to verify and handle calls	A protected secret that is never shown again
Purpose	Records an optional note for this number	Your description on the setup page
Incoming-call webhook	Routes calls from Twilio to AVA	A copyable URL and Test webhook action
Phone AI switch	Activates or pauses AI call handling	Active or Not active
Call Activity	Lists calls and their state	Caller number, start time, status, and transcript

Before You Start

Confirm these requirements:

• You have phone_ai:read permission to review Phone AI activity
• You have phone_ai:manage permission to configure Phone AI
• You have a dedicated Twilio phone number
• You have the Twilio Account SID and Auth Token
• The phone number is written in E.164 format

Check Your Phone AI Permission

Your role controls which Phone AI actions you can use:

Permission	Available actions
phone_ai:read	Open Phone AI and review Call Activity and transcripts
phone_ai:manage	Save settings, test the webhook, and activate Phone AI

phone_ai:manage also grants phone_ai:read. Read access does not grant management access.

Ask an administrator to update your role if an action is unavailable.

Deployment requirement

Twilio must reach AVA through a public HTTPS address that supports WebSocket connections. Ask your AVA administrator to confirm this requirement for private or restricted deployments.

Verify the Public Phone AI URL

AVA creates the Twilio webhook and media stream URLs from the public Core address.

Environment	URL behavior	What you should check
Production	Uses the public HTTPS VOUCH_CORE_URL	The URL includes /core when your deployment uses that prefix
Local Docker	Uses the public SERVICE_HOME address and PUBLIC_PATH	The address points to your public ngrok tunnel

Media stream URL

AVA creates the secure wss:// media stream URL automatically. You only configure the copied incoming-call webhook in Twilio. Do not add query parameters to the generated media stream URL.

Ask your deployment administrator to correct these values if the copied webhook uses an internal hostname.

Connect the Phone AI Services

Ask your deployment team to complete these checks before enabling Phone AI:

• Keep the Core-to-Chat realtime route private. It is for internal service traffic only.
• Set INTER_SERVICE_SECRET in Chat Microservice to match Core's CHAT_MICROSERVICE_SECRET.
• Deploy Chat Microservice before Core. Streamliner can follow after Core is live.
• Roll back in reverse order if needed: Streamliner, Core, then Chat Microservice.

Keep the realtime route private

Do not expose the internal realtime route to the public internet. Twilio should connect through the public AVA webhook, not directly to Chat Microservice.

Protect the Auth Token

Treat your Twilio Auth Token like a password. AVA protects it after saving and never displays it again.

Save the Twilio Connection

1. Go to Communication Hub → Phone AI.

2. Stay on Setup.

3. Enter the Twilio Account SID.

4. Enter the Twilio phone number with + and country code.

5. Enter the Twilio Auth Token.

6. Add an optional Purpose.

7. Click Save settings.

   ✓ You see "Phone AI settings saved." ✓ The Auth Token field changes to its protected placeholder.

Replacing a token

Leave the Auth Token blank to keep the saved token. Enter a new token only when you need to replace it.

Route Incoming Calls from Twilio

1. On Setup, find Incoming-call webhook.

2. Click Copy.

3. Open the Twilio Console.

4. Open Phone Numbers and select the hotel number.

5. Under Voice configuration, set A call comes in to Webhook.

6. Paste the copied URL.

7. Select POST, then save the Twilio configuration.

   ✓ Twilio now sends incoming calls to the AVA webhook.

Webhook validation

AVA checks the Twilio request and the configured phone number before accepting calls. Use the exact number saved in AVA when configuring Twilio.

Test and Activate Phone AI

1. Return to Communication Hub → Phone AI.

2. Save any unsaved changes.

3. Click Test webhook.

4. Confirm the success message.

5. Turn on Enable Phone AI.

6. Click Save settings.

7. Call the Twilio number from another phone.

   ✓ Phone AI answers the incoming call. ✓ After the call ends, the call appears under Call Activity with its saved state. ✓ Select View transcript to review saved caller and AI messages.

Activation requirement

You must save the Account SID, phone number, and Auth Token before activation. The webhook test also stays disabled while changes are unsaved.

Review Call Activity

1. Open Call Activity.

2. Find the call by caller number and start time.

3. Review the call state.

4. Click View transcript.

5. Close the transcript when you finish.

   ✓ You can review the caller and assistant messages for that call.

Activity refresh

Call Activity loads when the page opens. Reopen or refresh the page after a new call ends.

Understand saved AI speech

The saved transcript follows what Phone AI actually says during the call. It can include one short progress phrase before the main answer. The approved checking phrase is “Please allow me a moment to check that for you.” Phone AI delivers this phrase once, without repeating it while the check continues. It avoids casual fillers such as “Hmm,” “Sure,” or “Okay.” When Phone AI cannot resolve an enquiry, it says, “Our apologies. Please speak with our front desk team for further assistance.” You may see separate AI entries for progress phrases and the final response. These entries help you review the complete spoken conversation.

Handle Guest Service Requests

Phone AI can answer general hotel questions during calls. Supported guest service actions require a reliable call transcript and clear guest confirmation. Phone AI waits for the guest's finalized transcript before deciding whether the guest agreed. For date-sensitive requests, Phone AI uses the hotel's current date, time, and timezone. When the caller is a checked-in guest, Phone AI uses the available salutation-aware greeting.

Guest request	Phone AI behavior
Ask a general hotel question	Answers using the available hotel information
Request, cancel, or change a guest service	Uses the guest's later, natural-language agreement with the exact prepared request
Request an action without a usable transcript	Directs the guest to the front desk

Cancel an existing guest request

When a guest asks to cancel a request, Phone AI first checks the guest's own request list. It uses the recent conversation and the request details held by AVA to identify references such as “that request.” If more than one request matches, Phone AI asks the guest which request they mean. It then reads back a cancellation preview before asking for confirmation. The request changes only after the guest confirms that exact cancellation in a later turn.

Cancellation safety

Phone AI does not cancel a request from a promise such as “I will cancel it now.” It must identify a listed request, prepare its cancellation, and receive a later confirmation.

Answer questions from hotel information

At the start of a phone call, Phone AI loads a bounded set of facts from sources enabled for AI Phone. It can answer a question directly when those facts fully and clearly cover it. For follow-up questions, Phone AI uses recent conversation context to resolve references such as “it” or “there”. It delegates the latest request when the answer is incomplete, uncertain, conflicting, changing, personal, or action-based. It also delegates when the startup facts are unavailable or missing.

Answer local questions with public search

When hotel documents do not cover a nearby-place question, Phone AI can search the public internet. This fallback covers nearby malls, dining, transport, attractions, and directions. The search uses the hotel's documented name and address as its starting point. Phone AI asks for clarification when the guest's starting point is too vague.

Guest question	Phone AI behavior
Ask about a nearby public place	Searches public sources and gives a spoken answer with nearby options
Ask for directions from an unclear origin	Asks the guest to clarify the starting point
Ask about hotel policy, personal stay details, or an action	Uses the trusted hotel or front-desk route instead
Public search is unavailable	Keeps supported hotel facts or gives the approved front-desk response

The spoken answer does not read source links aloud. Mirrored call answers can include clickable citations when the call surface displays them. Private room numbers, booking references, aliases, and guest details are never sent to public search.

Search availability

Your deployment administrator can disable this fallback with OPENAI_LIVE_LOCAL_SEARCH_ENABLED=false. Hotel-document answers and trusted guest-service routes continue to use their existing behavior.

What happens	Guest experience
Facts fully cover the question	Phone AI gives a concise answer without a front-desk handoff
Facts only partly cover the question	Phone AI directs the guest to the front desk
The question is personal, changing, or action-based	Phone AI directs the guest to the front desk
Startup facts are missing or unavailable	Phone AI directs the guest to the front desk

You do not need to change Phone AI settings for this fact loading. Keep the relevant source enabled for AI Phone in Chatbot Documents.

General policy questions, such as late checkout or luggage storage, can be answered directly when the hotel facts fully cover them. This also works without a verified stay. Requests to arrange late checkout, check personal eligibility, or confirm availability go to the front desk.

When Phone AI previews a service request, it names each item or service with its quantity, date, and time. It does not speak internal codes, IDs, reference numbers, or labels such as “amenities request.” If a guest says the exact name of one catalogue entry, Phone AI resolves it to that entry's code. Name matching ignores capitalization. If several entries share that name, Phone AI asks the guest to choose instead. Repeated names include a number, such as “Hand Towel (1)” and “Hand Towel (2)”. The guest must choose the numbered name when duplicate entries appear.

Handle wake-up call dates

Guests can use relative dates when requesting a wake-up call. Phone AI interprets those dates using the hotel's configured timezone. If the guest gives only a time, Phone AI asks which day they mean.

Verify Timezone in Settings → Essentials → Hotel Basic Details before testing.

No action is submitted without confirmation

If transcription is unavailable, Phone AI does not submit, cancel, or change a guest service request. The guest receives a front-desk handoff instead. One guest turn cannot both prepare and confirm a request. Phone AI judges whether a later guest turn agrees with the prepared request. Questions, hesitation, corrections, or unrelated words do not confirm it. Phone AI rejects confirmations that alter the prepared request. It asks in one short sentence, such as “Please confirm you're requesting one bath towel.” For cancellations, it asks, “Please confirm you'd like to cancel your bath towel request.” It says nothing before or after that confirmation sentence. After a clear confirmation, Phone AI keeps the prepared request while it processes the delegated housekeeping action. If the guest's agreement is unclear, Phone AI discards the prepared request before asking again. The next confirmation prompts Phone AI to prepare and read back the same request again. The guest must confirm that new read-back.

Tell guests to contact the front desk when they need an action completed during a call without transcription.

Troubleshooting

The phone number is rejected

What you see: "Enter the Twilio phone number in E.164 format, including + and country code."

Fix:

1. Start the number with +.
2. Add the country code.
3. Remove spaces, brackets, and dashes.
4. Click Save settings again.

The webhook test is disabled

What you see: You cannot select Test webhook.

Fix:

1. Complete the Account SID, phone number, and Auth Token.
2. Click Save settings.
3. Wait for the saved confirmation.
4. Click Test webhook again.

The webhook test fails

What you see: "Unable to verify the Twilio webhook configuration."

Fix:

1. Copy the current Incoming-call webhook again.
2. Confirm Twilio uses that URL for A call comes in.
3. Confirm the method is POST.
4. Save in Twilio, then test again in AVA.

The copied webhook uses an internal URL

What you see: The copied URL contains an internal hostname or starts with http://.

Fix:

1. Ask your deployment administrator to set production VOUCH_CORE_URL to the public HTTPS Core address.

2. Confirm the value includes /core when your public deployment uses that prefix.

3. For local Docker, confirm the public ngrok address is configured through SERVICE_HOME and PUBLIC_PATH.

4. Reopen Communication Hub → Phone AI.

5. Copy the Incoming-call webhook again, then update Twilio.

   ✓ The copied webhook starts with https:// and uses a public address.

Calls do not appear in Call Activity

What you see: A test call ends, but no call appears for the selected hotel.

Fix:

1. Confirm you selected the hotel where Phone AI is active.
2. Confirm the Twilio number matches Twilio phone number exactly.
3. Reopen or refresh the Phone AI page after the call ends.
4. Run Test webhook again after saving the settings.
5. Ask your AVA administrator to confirm the public HTTPS address supports WebSocket connections.

Phone AI cannot be activated

What you see: The Enable Phone AI switch stays disabled.

Fix:

1. Confirm your role has phone_ai:manage permission.
2. Save all required Twilio settings.
3. Check that the phone number includes + and country code.
4. Refresh the page and try again.

A transcript does not open

What you see: "Unable to load this transcript."

Fix:

1. Close the transcript panel.
2. Refresh Call Activity.
3. Open the call again.
4. Contact support if other transcripts also fail.

A call has no transcript

What you see: "No transcript was saved for this call."

Fix:

1. Check another completed call under Call Activity.

2. Continue using Phone AI for general hotel questions.

3. Tell guests to contact the front desk for requests, cancellations, or changes.

4. Contact your AVA administrator if your deployment should save call transcripts.

   ✓ Phone AI can continue answering questions without a saved transcript. ✓ Confirmation-dependent guest actions go to the front desk instead.

Recent spoken text is missing

What you see: The transcript ends before the assistant's last spoken phrase.

Fix:

1. Wait a few seconds after the call ends.
2. Reopen or refresh Call Activity.
3. Open the call and select View transcript again.
4. Contact your AVA administrator if the phrase remains missing.

Phone AI gives an incomplete hotel answer

What you see: Phone AI mentions a related service but misses the detail you expected.

Fix:

1. Open Chatbot Documents.

2. Confirm the relevant source contains the complete service details.

3. Confirm the source is active and enabled for AI Phone.

4. Wait for knowledge processing to finish, then test again.

   ✓ Phone AI loads the enabled source for the call and answers fully covered questions directly.

Phone AI sends a hotel question to the front desk

What you see: Phone AI cannot answer a question that your hotel information should cover.

Fix:

1. Open Chatbot Documents.

2. Confirm the relevant source is active and enabled for AI Phone.

3. Wait for knowledge processing to finish before testing again.

4. Ask your AVA administrator to check the knowledge service if the source is ready.

   ✓ Phone AI answers fully covered questions from the hotel's enabled information.

Phone AI cannot answer a nearby-place question

What you see: Phone AI gives the front-desk response for a question about a nearby place.

Fix:

1. Confirm the hotel's documented address is complete and current.

2. Ask the guest to name a clear starting point for directions.

3. Confirm public local search is enabled for your deployment.

4. Retry the question with a nearby mall, restaurant, attraction, or transport stop.

   ✓ Phone AI searches only eligible public local topics when hotel documents do not answer them.

Still Stuck?

Contact success@vouch-technologies.com if:

• ❌ The saved webhook keeps failing its test
• ❌ Calls do not appear under Call Activity
• ❌ Phone AI does not answer after activation

Helpful to include:

• Screenshot of the setup status without secret values
• Twilio phone number
• Time of one test call
• Exact error message

Related Guides

• Set Up Voice Assistant Prompts
• Set Up Video Calls
• Set Up Your Chatbot