twilio-labs · settermjd · Jun 30, 2026 · Jun 30, 2026
@@ -0,0 +1 @@
+Refer to [AGENTS.md](../AGENTS.md) for all repo instructions.
@@ -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 <your-phone-number-sid> \
+  --sms-url https://<your-ngrok-id>.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: <sender>. Body: <original message>`
+
+## 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
@@ -0,0 +1 @@
+@AGENTS.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: <number>. Body: <message>`.
+
+## 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 <your-phone-number-sid> \
+  --sms-url https://<your-ngrok-id>.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://<your-ngrok-id>.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
+```
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Refer to [AGENTS.md](../AGENTS.md) for all repo instructions.