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: Settings → Communications → 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 Settings read access to review Phone AI activity
• You have Settings write access 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 Settings Permission

Your permission controls which Phone AI actions you can use:

Permission	Available actions
Settings read	Open Phone AI and review Call Activity and transcripts
Settings write	Save settings, test the webhook, and activate Phone AI

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 Settings → Communications → 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 Settings → Communications → 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.

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.

Guest request	Phone AI behavior
Ask a general hotel question	Answers using the available hotel information
Request, cancel, or change a guest service	Accepts a clear confirmation, including “I confirm” or “I confirm it”
Request an action without a usable transcript	Directs the guest to the front desk

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. Phone AI rejects confirmations that alter the prepared request.

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 Settings → Communications → 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 you have Settings write access.
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.

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