Add AI-Ready updates to voice-ivr project

voice-ivr/.env.example

@@ -0,0 +1,9 @@
+# Your phone number for call forwarding (Sales option)
+# Enter in E.164 format: https://www.twilio.com/docs/glossary/what-e164
+# Use a test phone number during development
+MY_PHONE_NUMBER=+15551234567
+
+# Note: The following Twilio credentials are automatically provided by Twilio Serverless
+# and do not need to be set in your .env file:
+# - ACCOUNT_SID: Your Twilio Account SID (https://www.twilio.com/console)
+# - AUTH_TOKEN: Your Twilio Auth Token (https://www.twilio.com/console)

voice-ivr/AGENTS.md

@@ -0,0 +1,86 @@
+# Voice IVR - Agent Guidelines
+
+This document provides AI assistants with essential information for working with the Voice IVR project.
+
+## Project Overview
+
+The Voice IVR project implements an interactive voice response system using Twilio. The system allows callers to navigate a phone tree using keypad digits or speech recognition. When users call the Twilio number, they can choose between: talking to sales, hearing business hours, or receiving an SMS with the company address.
+
+## Documentation Links
+
+All Twilio documentation URLs in this guide can be accessed in markdown format by adding `.md` to the end of the URL.
+
+## Do-Not-Touch Areas
+
+### 1. Webhook Signature Verification
+
+The `.protected.js` suffix on function files indicates they require valid Twilio signatures. Never remove this protection or modify the validation logic. Twilio's serverless toolkit handles this automatically.
+
+### 2. Critical Parameters
+
+Never modify these critical parameters without explicit instructions:
+
+- `numDigits: 1` in voice-ivr.js - This ensures the system expects a single digit input
+- `input: 'speech dtmf'` in voice-ivr.js - This enables both speech and touch-tone input
+- Webhook paths (`voice-ivr` and `handle-user-input`) - These must match Twilio configurations
+
+### 3. Sensitive Data
+
+Never expose or hardcode these sensitive details:
+
+- Phone numbers (use environment variables)
+- Twilio account credentials
+- Customer information received during calls
+
+## Coding Conventions
+
+**TwiML must be returned via callback**: All functions must call `callback(null, twiml)` to return TwiML responses. Never use `return twiml` directly.
+
+```javascript
+const twiml = new Twilio.twiml.VoiceResponse();
+twiml.say('Message to speak');
+callback(null, twiml); // Required pattern
+```
+
+## Tests
+
+Run `npm test` from the repository root. Comprehensive test coverage exists in `tests/` for both functions, covering DTMF inputs, speech recognition, error handling, and SMS delivery.
+
+## Common Tasks
+
+### Adding a New Menu Option
+
+To add a new menu option (e.g., "Support"):
+
+1. Add new option in `voice-ivr.protected.js`:
+   ```javascript
+   gather.say('Press 4 or say Support to get technical help');
+   ```
+
+2. Add speech recognition and handler in `handle-user-input.protected.js`:
+   ```javascript
+   // In speech normalization section
+   if (UserInput.toLowerCase().includes('support')) {
+     UserInput = '4';
+   }
+
+   // In switch statement
+   case '4':
+     twiml.say('Connecting you to our support team');
+     twiml.dial(context.SUPPORT_PHONE_NUMBER);
+     break;
+   ```
+
+3. Add any necessary environment variable to `.env`:
+   ```
+   SUPPORT_PHONE_NUMBER=+15551234567
+   ```
+
+4. Add any required unit tests
+
+## Further Resources
+
+- [Twilio TwiML Voice Documentation](https://www.twilio.com/docs/voice/twiml)
+- [Twilio Speech Recognition](https://www.twilio.com/docs/voice/twiml/gather#speechmodel)
+- [Twilio SMS Documentation](https://www.twilio.com/docs/sms)
+- [Twilio Serverless Functions](https://www.twilio.com/docs/runtime/functions)

voice-ivr/README.md

@@ -1,34 +1,31 @@
 # Voice IVR
 
-This application allows users to navigate an IVR (phone tree) using keys or speech-to-text via a Twilio number. When a user calls the number, they are presented with three options: Talk to Sales, Hours of Operation, or Address. Selecting the first option forwards the call to a given phone number. The second provides an immediate voice response with relevant information. Choosing the third option triggers an SMS with the requested details. The application is fully customizable, allowing you to edit the available options and responses.
+This application allows users to navigate an IVR (phone tree) using keys or speech-to-text via a Twilio number. When a user calls the number, they are presented with three options:
 
-## Pre-requisites
+1. Talk to Sales: Forwards the call to a given phone number (set in `.env`)
+2. Hours of Operation: Provides an immediate voice response with opening hours information
+3. Address: Triggers an SMS with address details to the caller's phone number
 
-- A Twilio account - [sign up here](https://www.twilio.com/try-twilio)
-- A Twilio phone number
+The user can select an option by dialing or saying the appropriate number.
 
-### Environment variables
+The application is fully customizable, allowing you to edit the available options and responses.
 
-This project requires some environment variables to be set. To keep your tokens and secrets secure, make sure to not commit the `.env` file in git. When setting up the project with `twilio serverless:init ...` the Twilio CLI will create a `.gitignore` file that excludes `.env` from the version history.
+**For AI coding assistants:** See [AGENTS.md](./AGENTS.md) for implementation guidelines, do-not-touch areas, coding conventions, and common task recipes.
 
-In your `.env` file, set the following values:
+## Prerequisites
 
-| Variable          | Meaning                                                  | Required |
-| :---------------- | :------------------------------------------------------- | :------- |
-| `MY_PHONE_NUMBER` | The phone number that you want calls to be forwarded to. | yes      |
+- An [ngrok][ngrok_url] account
+- A [Twilio account](try_twilio_url) with an active phone number that can send SMS
 
-### Function Parameters
+### Environment variables
 
-`/voice-ivr` is protected and requires a valid Twilio signature.
+This project requires some environment variables to be set. To keep any tokens and secrets secure, make sure to not commit the `.env` file in git. When setting up the project with `twilio serverless:init ...` the Twilio CLI will create a `.gitignore` file that excludes `.env` from the version history.
 
-`/handle-user-input` is protected and requires a valid Twilio signature and expects the following parameters:
+Copy `.env.example`, and set the following values:
 
-| Parameter      | Description                      | Required |
-| :------------- | :------------------------------- | :------- |
-| `Digits`       | Automatically provided by Twilio | No       |
-| `SpeechResult` | Automatically provided by Twilio | No       |
-| `From`         | Automatically provided by Twilio | No       |
-| `To`           | Automatically provided by Twilio | No       |
+| Variable          | Meaning                                                  | Required |
+| :---------------- | :------------------------------------------------------- | :------- |
+| `MY_PHONE_NUMBER` | The "Sales" phone number that you want calls to be forwarded to. | yes      |
 
 ## Create a new project with the template
 
@@ -51,16 +48,59 @@ twilio serverless:init example --template=voice-ivr && cd example
 twilio serverless:start
 ```
 
+> **Tip**: Run `npm test` from the repository root to run tests. Other available commands: `npm run lint`, `npm run format`.
+
 5. Open the web page at https://localhost:3000/index.html and follow the instructions to test your application.
 
-ℹ️ Check the developer console and terminal for any errors, make sure you've set your environment variables.
+Check the developer console and terminal for any errors, and make sure you've set your environment variables.
+
+## Local Development & Testing
+
+### Exposing your local server
+
+To test with a real Twilio phone number, you need to expose your local server to the internet. You can use [ngrok](ngrok_url):
+
+```bash
+ngrok http 3000
+```
+Copy the HTTPS URL (e.g., `https://abc123.ngrok.io`)
+
+### Configuring your Twilio phone number
+
+1. Go to your [Twilio Console Phone Numbers](https://console.twilio.com/us1/develop/phone-numbers/manage/incoming)
+2. Select the phone number you want to use
+3. Under "Voice Configuration":
+   - Set "A Call Comes In" to **Webhook**
+   - Enter your public URL: `https://your-ngrok-url.ngrok.io/voice-ivr` (or your deployed URL)
+   - Set HTTP method to **POST**
+4. Click **Save**
+
+
+You can also use the Twilio CLI to configure your phone number's Voice URL.
+
+First, retrieve the phone number's SID (starts with `PN`):
+
+```bash
+twilio phone-numbers:list
+```
+
+Using the phone number SID and ngrok URL that you copied above:
+
+```bash
+twilio phone-numbers:update YOUR_PHONE_NUMBER_SID --voice-url="https://abc123.ngrok.io"
+```
+
+Now when you call your Twilio number, it will trigger the `/voice-ivr` function.
 
 ## Deploying
 
-Deploy your functions and assets with either of the following commands. Note: you must run these commands from inside your project folder. [More details in the docs.](https://www.twilio.com/docs/labs/serverless-toolkit)
+Deploy your functions and assets with the following command. Note: you must run these commands from inside your project folder. [More information about the serverless toolkit in the docs.](https://www.twilio.com/docs/labs/serverless-toolkit)
 
 With the [Twilio CLI](https://www.twilio.com/docs/twilio-cli/quickstart):
 
 ```
 twilio serverless:deploy
 ```
+
+[ngrok_url]: https://ngrok.com/
+[try_twilio_url]: https://www.twilio.com/try-twilio