Skip to content

Commit 4ab1ad6

Browse files
settermjdsettermjd
authored
Merge pull request #651 from dylanfrankcom/update-forward-message-agents
Add agent instructions and update README
2 parents d4d1f2f + aa5f880 commit 4ab1ad6

4 files changed

Lines changed: 151 additions & 7 deletions

File tree

‎forward-message/.github/copilot-instructions.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Refer to [AGENTS.md](../AGENTS.md) for all repo instructions.

‎forward-message/AGENTS.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Forward Message
2+
3+
Demonstrates how to forward an incoming SMS to one or more phone numbers using Twilio Serverless Functions and TwiML.
4+
5+
## Environment Variables
6+
7+
`.env` is included with placeholder values. Update it before running. Never commit `.env`.
8+
9+
| Variable | Where to find | Format |
10+
| -------- | ------------- | ------ |
11+
| `FORWARDING_NUMBERS` | Phone numbers you control — the destinations for forwarded SMS | Comma-separated E.164 values: `+15551234567,+15557654321` |
12+
| `TWILIO_SMS_WEBHOOK_URL` | Pre-set to `/forward-message` — do not change | `/forward-message` |
13+
14+
## Commands
15+
16+
```bash
17+
# Install Twilio CLI serverless plugin (once)
18+
twilio plugins:install @twilio-labs/plugin-serverless
19+
20+
# Initialize a new project from this template
21+
# --skip-credentials skips the credential prompt (Serverless injects them at runtime)
22+
twilio serverless:init example --template=forward-message --skip-credentials && cd example
23+
# Edit .env — replace placeholder FORWARDING_NUMBERS with real E.164 numbers
24+
25+
# Start the server
26+
twilio serverless:start
27+
28+
# Expose locally via ngrok (run separately — install and authenticate at https://ngrok.com)
29+
ngrok http 3000
30+
31+
# Configure the SMS webhook on your Twilio number
32+
# Find your phone number SID:
33+
twilio api:core:incoming-phone-numbers:list
34+
# Set the webhook (replace URL with your ngrok URL or deployed URL):
35+
twilio api:core:incoming-phone-numbers:update \
36+
--sid <your-phone-number-sid> \
37+
--sms-url https://<your-ngrok-id>.ngrok.app/forward-message \
38+
--sms-method POST
39+
40+
# Deploy
41+
twilio serverless:deploy --service-name forward-message
42+
```
43+
44+
## Project Structure
45+
46+
- `functions/forward-message.protected.js` — main handler; forwards incoming SMS to each number in `FORWARDING_NUMBERS`
47+
- `tests/forward-message.test.js` — Jest unit tests (run from the monorepo root, not this directory)
48+
- `.env` — environment variables (never commit)
49+
50+
## Agent Boundaries
51+
52+
**Always:**
53+
54+
- Confirm `.env` is configured before running any command
55+
- Use the Environment Variables section to guide the user to each credential — don't ask them to find values without direction
56+
- Confirm the app is running before asking the user to test it
57+
- Always use `--template=forward-message` when initializing a new project
58+
59+
**Never:**
60+
61+
- Run the app with missing or placeholder credentials
62+
- Hardcode credentials or phone numbers in source files
63+
- Run with placeholder values still in `.env`
64+
65+
## Verify It's Working
66+
67+
1. Text any message to your Twilio phone number
68+
2. Every number listed in `FORWARDING_NUMBERS` should receive an SMS in the format: `From: <sender>. Body: <original message>`
69+
70+
## Twilio Resources
71+
72+
- [Twilio Console](https://console.twilio.com) — credentials, phone numbers, webhook configuration
73+
- [Twilio Serverless Toolkit](https://www.twilio.com/docs/labs/serverless-toolkit) — deploy and manage Serverless Functions
74+
- [TwiML for Messaging](https://www.twilio.com/docs/sms/twiml) — reference for the MessagingResponse used in this template
75+
- [Programmable SMS](https://www.twilio.com/docs/sms) — SMS API reference

‎forward-message/CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
@AGENTS.md

‎forward-message/README.md‎

Lines changed: 74 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,82 @@
11
# Forward Message
22

3-
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.
3+
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>`.
4+
5+
## Pre-requisites
6+
7+
- A [Twilio account](https://www.twilio.com/try-twilio) with an active phone number that can receive SMS
48

59
### Environment variables
610

7-
This Function expects one environment variable to be set.
11+
`.env` is included with placeholder values. Update `FORWARDING_NUMBERS` before running. Never commit `.env`.
12+
13+
| Variable | Description | Required |
14+
| :- | :- | :- |
15+
| `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 |
16+
| `TWILIO_SMS_WEBHOOK_URL` | The webhook path — pre-set to `/forward-message`, do not change | Yes |
17+
18+
## Running the project
19+
20+
1. Install the [Twilio CLI](https://www.twilio.com/docs/twilio-cli/quickstart#install-twilio-cli)
21+
1. Install the [serverless toolkit](https://www.twilio.com/docs/labs/serverless-toolkit/getting-started)
22+
23+
```shell
24+
twilio plugins:install @twilio-labs/plugin-serverless
25+
```
26+
27+
1. Initialize the project from the template
28+
29+
```shell
30+
twilio serverless:init example --template=forward-message --skip-credentials && cd example
31+
```
32+
33+
1. Edit `.env` and replace the placeholder `FORWARDING_NUMBERS` with your real E.164 number(s)
34+
35+
1. Start the server
36+
37+
```shell
38+
twilio serverless:start
39+
```
40+
41+
Check the developer console and terminal for any errors, and make sure you've set your environment variables.
42+
43+
### Configuring your Twilio phone number
44+
45+
You can configure the webhook via the Twilio CLI (recommended) or the Console.
46+
47+
**Via CLI:**
48+
49+
Find your phone number SID:
50+
51+
```shell
52+
twilio api:core:incoming-phone-numbers:list
53+
```
54+
55+
Then update the SMS webhook:
56+
57+
```shell
58+
twilio api:core:incoming-phone-numbers:update \
59+
--sid <your-phone-number-sid> \
60+
--sms-url https://<your-ngrok-id>.ngrok.app/forward-message \
61+
--sms-method POST
62+
```
63+
64+
**Via Console:**
65+
66+
1. Go to your [Twilio Console Phone Numbers](https://console.twilio.com/us1/develop/phone-numbers/manage/incoming)
67+
2. Select the phone number you want to use
68+
3. Under "Messaging Configuration":
69+
- Set "A Message Comes In" to **Webhook**
70+
- Enter your URL: `https://<your-ngrok-id>.ngrok.app/forward-message` (or your deployed URL)
71+
- Set HTTP method to **POST**
72+
4. Click **Save**
73+
74+
## Deploying
875

9-
| Variable | Meaning |
10-
| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
11-
| `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 |
76+
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)
1277

13-
### Parameters
78+
With the [Twilio CLI](https://www.twilio.com/docs/twilio-cli/quickstart):
1479

15-
This Function expects the incoming request to be a messaging webhook. The parameters that will be used are `From` and `Body`.
80+
```shell
81+
twilio serverless:deploy --service-name forward-message
82+
```

0 commit comments

Comments
 (0)