Merge pull request #648 from dylanfrankcom/update-voice-ivr-agents

Refresh Voice IVR readme and agent guidance

Author: settermjd

voice-ivr/.github/copilot-instructions.md

@@ -0,0 +1 @@
+Refer to [AGENTS.md](../AGENTS.md) for all repo instructions.

voice-ivr/AGENTS.md

@@ -1,86 +1,74 @@
-# Voice IVR - Agent Guidelines
+# Voice IVR
 
-This document provides AI assistants with essential information for working with the Voice IVR project.
+This sample demonstrates a phone tree (IVR) using Twilio Voice and Programmable SMS, where callers navigate options by keypad or speech-to-text to reach sales, hear hours, or receive an address by SMS.
 
-## Project Overview
+## Environment Variables
 
-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.
+Copy `.env.example` to `.env`. Never commit `.env`.
 
-## 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.
+```bash
+cp .env.example .env
+```
 
-### 2. Critical Parameters
+| Variable | Where to find | Format |
+| -------- | ------------- | ------ |
+| `MY_PHONE_NUMBER` | The phone number you want the Sales option to forward calls to — use your own mobile during development | E.164 format: `+15551234567` |
 
-Never modify these critical parameters without explicit instructions:
+> Note: `ACCOUNT_SID` and `AUTH_TOKEN` are injected automatically by Twilio Serverless and do not need to be set in `.env`.
 
-- `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
+## Commands
 
-### 3. Sensitive Data
+```bash
+# Install Twilio CLI serverless plugin (once)
+twilio plugins:install @twilio-labs/plugin-serverless
 
-Never expose or hardcode these sensitive details:
+# Initialize a new project from this template
+twilio serverless:init example --template=voice-ivr && cd example
 
-- Phone numbers (use environment variables)
-- Twilio account credentials
-- Customer information received during calls
+# Run locally
+twilio serverless:start
 
-## Coding Conventions
+# Expose webhooks locally
+# Requires ngrok — install and authenticate at https://ngrok.com before running
+ngrok http 3000
+# Set the resulting HTTPS URL + /voice-ivr as the webhook in Twilio Console (Voice → A Call Comes In → POST)
 
-**TwiML must be returned via callback**: All functions must call `callback(null, twiml)` to return TwiML responses. Never use `return twiml` directly.
+# Deploy to Twilio Serverless
+twilio serverless:deploy
 
-```javascript
-const twiml = new Twilio.twiml.VoiceResponse();
-twiml.say('Message to speak');
-callback(null, twiml); // Required pattern
+# Test
+npm test
 ```
 
-## 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.
+## Project Structure
 
-## Common Tasks
+- `functions/voice-ivr.protected.js` — entry point; presents the IVR menu via TwiML `<Gather>`
+- `functions/handle-user-input.protected.js` — handles digit/speech input; forwards call, reads hours, or sends SMS
+- `.env.example` — environment variable template
+- `tests/` — Jest test suite
 
-### Adding a New Menu Option
+## Agent Boundaries
 
-To add a new menu option (e.g., "Support"):
+**Always:**
 
-1. Add new option in `voice-ivr.protected.js`:
-   ```javascript
-   gather.say('Press 4 or say Support to get technical help');
-   ```
+- Confirm `.env` is configured before running any command
+- Use the Environment Variables section to guide the user to each credential — don't ask them to find values without direction
+- Confirm the app is running before asking the user to test it
 
-2. Add speech recognition and handler in `handle-user-input.protected.js`:
-   ```javascript
-   // In speech normalization section
-   if (UserInput.toLowerCase().includes('support')) {
-     UserInput = '4';
-   }
+**Never:**
 
-   // In switch statement
-   case '4':
-     twiml.say('Connecting you to our support team');
-     twiml.dial(context.SUPPORT_PHONE_NUMBER);
-     break;
-   ```
+- Run the app with missing or placeholder credentials
+- Hardcode credentials or phone numbers in source files
+- Skip the `cp .env.example .env` step
 
-3. Add any necessary environment variable to `.env`:
-   ```
-   SUPPORT_PHONE_NUMBER=+15551234567
-   ```
+## Verify It's Working
 
-4. Add any required unit tests
+1. Call your Twilio phone number. You should hear the IVR prompt offering three options.
+2. Press `1` (or say "Sales") — the call should forward to the number set in `MY_PHONE_NUMBER`. Press `3` (or say "Address") — you should receive an SMS with the address to the caller's number within a few seconds.
 
-## Further Resources
+## Twilio 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)
+- [Twilio Console](https://console.twilio.com) — credentials, phone numbers, webhook configuration
+- [Twilio Voice TwiML](https://www.twilio.com/docs/voice/twiml) — TwiML verb reference
+- [Twilio Serverless Toolkit](https://www.twilio.com/docs/labs/serverless-toolkit) — deploy and manage Twilio Functions
+- [Programmable SMS](https://www.twilio.com/docs/sms) — SMS API reference

voice-ivr/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

voice-ivr/README.md

@@ -1,23 +1,15 @@
 # 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:
+This application implements a phone tree (IVR) using Twilio Voice and Programmable SMS. When a caller dials your Twilio number they hear three options — Talk to Sales, Hours of Operation, or Address — and can select one by pressing a digit or speaking the option name. Sales calls are forwarded to a configurable phone number, hours are read back via text-to-speech, and the address is delivered as an SMS to the caller.
 
-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
-
-The user can select an option by dialing or saying the appropriate number.
-
-The application is fully customizable, allowing you to edit the available options and responses.
-
-**For AI coding assistants:** See [AGENTS.md](./AGENTS.md) for implementation guidelines, do-not-touch areas, coding conventions, and common task recipes.
+**For AI coding assistants:** See [AGENTS.md](./AGENTS.md) for setup and implementation guidelines.
 
 ## Prerequisites
 
-- An [ngrok][ngrok_url] account
-- A [Twilio account](try_twilio_url) with an active phone number that can send SMS
+- An [ngrok](https://ngrok.com) account
+- A [Twilio account](https://www.twilio.com/try-twilio) with an active phone number that can send SMS
 
-### Environment variables
+## Environment variables
 
 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.
 
@@ -58,7 +50,7 @@ Check the developer console and terminal for any errors, and make sure you've se
 
 ### 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):
+To test with a real Twilio phone number, you need to expose your local server to the internet. You can use [ngrok](https://ngrok.com):
 
 ```bash
 ngrok http 3000
@@ -101,6 +93,3 @@ 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