diff --git a/forward-message/.github/copilot-instructions.md b/forward-message/.github/copilot-instructions.md new file mode 100644 index 000000000..fe342a78c --- /dev/null +++ b/forward-message/.github/copilot-instructions.md @@ -0,0 +1 @@ +Refer to [AGENTS.md](../AGENTS.md) for all repo instructions. diff --git a/forward-message/AGENTS.md b/forward-message/AGENTS.md new file mode 100644 index 000000000..d5875ab6d --- /dev/null +++ b/forward-message/AGENTS.md @@ -0,0 +1,75 @@ +# Forward Message + +Demonstrates how to forward an incoming SMS to one or more phone numbers using Twilio Serverless Functions and TwiML. + +## Environment Variables + +`.env` is included with placeholder values. Update it before running. Never commit `.env`. + +| Variable | Where to find | Format | +| -------- | ------------- | ------ | +| `FORWARDING_NUMBERS` | Phone numbers you control — the destinations for forwarded SMS | Comma-separated E.164 values: `+15551234567,+15557654321` | +| `TWILIO_SMS_WEBHOOK_URL` | Pre-set to `/forward-message` — do not change | `/forward-message` | + +## Commands + +```bash +# Install Twilio CLI serverless plugin (once) +twilio plugins:install @twilio-labs/plugin-serverless + +# Initialize a new project from this template +# --skip-credentials skips the credential prompt (Serverless injects them at runtime) +twilio serverless:init example --template=forward-message --skip-credentials && cd example +# Edit .env — replace placeholder FORWARDING_NUMBERS with real E.164 numbers + +# Start the server +twilio serverless:start + +# Expose locally via ngrok (run separately — install and authenticate at https://ngrok.com) +ngrok http 3000 + +# Configure the SMS webhook on your Twilio number +# Find your phone number SID: +twilio api:core:incoming-phone-numbers:list +# Set the webhook (replace URL with your ngrok URL or deployed URL): +twilio api:core:incoming-phone-numbers:update \ + --sid \ + --sms-url https://.ngrok.app/forward-message \ + --sms-method POST + +# Deploy +twilio serverless:deploy --service-name forward-message +``` + +## Project Structure + +- `functions/forward-message.protected.js` — main handler; forwards incoming SMS to each number in `FORWARDING_NUMBERS` +- `tests/forward-message.test.js` — Jest unit tests (run from the monorepo root, not this directory) +- `.env` — environment variables (never commit) + +## Agent Boundaries + +**Always:** + +- 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 +- Always use `--template=forward-message` when initializing a new project + +**Never:** + +- Run the app with missing or placeholder credentials +- Hardcode credentials or phone numbers in source files +- Run with placeholder values still in `.env` + +## Verify It's Working + +1. Text any message to your Twilio phone number +2. Every number listed in `FORWARDING_NUMBERS` should receive an SMS in the format: `From: . Body: ` + +## Twilio Resources + +- [Twilio Console](https://console.twilio.com) — credentials, phone numbers, webhook configuration +- [Twilio Serverless Toolkit](https://www.twilio.com/docs/labs/serverless-toolkit) — deploy and manage Serverless Functions +- [TwiML for Messaging](https://www.twilio.com/docs/sms/twiml) — reference for the MessagingResponse used in this template +- [Programmable SMS](https://www.twilio.com/docs/sms) — SMS API reference diff --git a/forward-message/CLAUDE.md b/forward-message/CLAUDE.md new file mode 100644 index 000000000..43c994c2d --- /dev/null +++ b/forward-message/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/forward-message/README.md b/forward-message/README.md index dae84c9d4..c7471f5ce 100644 --- a/forward-message/README.md +++ b/forward-message/README.md @@ -1,15 +1,82 @@ # Forward Message -This Function in `forward-message.js` returns the TwiML required to forward an incoming SMS message to a single number or each number in a comma-separated list set in the environment variables. +This application forwards an incoming SMS message to a single number or each number in a comma-separated list set in the environment variables. The forwarded message includes the original sender's number and message body in the format: `From: . Body: `. + +## Pre-requisites + +- A [Twilio account](https://www.twilio.com/try-twilio) with an active phone number that can receive SMS ### Environment variables -This Function expects one environment variable to be set. +`.env` is included with placeholder values. Update `FORWARDING_NUMBERS` before running. Never commit `.env`. + +| Variable | Description | Required | +| :- | :- | :- | +| `FORWARDING_NUMBERS` | A list of numbers [in E.164 format](https://support.twilio.com/hc/en-us/articles/223183008-Formatting-International-Phone-Numbers) to forward incoming messages to, separated by commas | Yes | +| `TWILIO_SMS_WEBHOOK_URL` | The webhook path — pre-set to `/forward-message`, do not change | Yes | + +## Running the project + +1. Install the [Twilio CLI](https://www.twilio.com/docs/twilio-cli/quickstart#install-twilio-cli) +1. Install the [serverless toolkit](https://www.twilio.com/docs/labs/serverless-toolkit/getting-started) + +```shell +twilio plugins:install @twilio-labs/plugin-serverless +``` + +1. Initialize the project from the template + +```shell +twilio serverless:init example --template=forward-message --skip-credentials && cd example +``` + +1. Edit `.env` and replace the placeholder `FORWARDING_NUMBERS` with your real E.164 number(s) + +1. Start the server + +```shell +twilio serverless:start +``` + +Check the developer console and terminal for any errors, and make sure you've set your environment variables. + +### Configuring your Twilio phone number + +You can configure the webhook via the Twilio CLI (recommended) or the Console. + +**Via CLI:** + +Find your phone number SID: + +```shell +twilio api:core:incoming-phone-numbers:list +``` + +Then update the SMS webhook: + +```shell +twilio api:core:incoming-phone-numbers:update \ + --sid \ + --sms-url https://.ngrok.app/forward-message \ + --sms-method POST +``` + +**Via Console:** + +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 "Messaging Configuration": + - Set "A Message Comes In" to **Webhook** + - Enter your URL: `https://.ngrok.app/forward-message` (or your deployed URL) + - Set HTTP method to **POST** +4. Click **Save** + +## Deploying -| Variable | Meaning | -| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `FORWARDING_NUMBERS` | A list of numbers [in E.164 format](https://support.twilio.com/hc/en-us/articles/223183008-Formatting-International-Phone-Numbers) you want to forward incoming messages to, separated by commas | +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) -### Parameters +With the [Twilio CLI](https://www.twilio.com/docs/twilio-cli/quickstart): -This Function expects the incoming request to be a messaging webhook. The parameters that will be used are `From` and `Body`. +```shell +twilio serverless:deploy --service-name forward-message +```