Skip to content

Commit c20e397

Browse files
settermjdsettermjd
authored
Merge pull request #652 from dylanfrankcom/update-forward-call-agents
Add agent docs and update forward-call README
2 parents 4ab1ad6 + 87793af commit c20e397

4 files changed

Lines changed: 151 additions & 7 deletions

File tree

‎forward-call/.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-call/AGENTS.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Forward Call
2+
3+
Demonstrates how to forward an incoming call to a specified phone number 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+
| `MY_PHONE_NUMBER` | Phone number you control — the destination for forwarded calls | E.164 format: `+15551234567` |
12+
| `TWILIO_VOICE_WEBHOOK_URL` | Pre-set to `/forward-call` — do not change | `/forward-call` |
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-call --skip-credentials && cd example
23+
# Edit .env — replace placeholder MY_PHONE_NUMBER with your real E.164 number
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 voice 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+
--voice-url https://<your-ngrok-id>.ngrok.app/forward-call \
38+
--voice-method POST
39+
40+
# Deploy
41+
twilio serverless:deploy --service-name forward-call
42+
```
43+
44+
## Project Structure
45+
46+
- `functions/forward-call.protected.js` — main handler; dials `MY_PHONE_NUMBER` via TwiML
47+
- `tests/forward-call.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-call` 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. Call your Twilio phone number
68+
2. The call should ring through to the number set in `MY_PHONE_NUMBER`
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 Voice](https://www.twilio.com/docs/voice/twiml) — reference for the VoiceResponse used in this template
75+
- [Programmable Voice](https://www.twilio.com/docs/voice) — Voice API reference

‎forward-call/CLAUDE.md‎

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

‎forward-call/README.md‎

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

3-
This Function in `forward-call.js` will return the [TwiML](https://www.twilio.com/docs/voice/twiml) required to forward an incoming call to a number that is set in the environment variables.
3+
This application forwards an incoming call to a number set in the environment variables.
4+
5+
## Pre-requisites
6+
7+
- A [Twilio account](https://www.twilio.com/try-twilio) with an active phone number that can receive calls
48

59
### Environment variables
610

7-
This Function expects one environment variable to be set.
11+
`.env` is included with placeholder values. Update `MY_PHONE_NUMBER` before running. Never commit `.env`.
12+
13+
| Variable | Description | Required |
14+
| :- | :- | :- |
15+
| `MY_PHONE_NUMBER` | The number to forward incoming calls to [in E.164 format](https://support.twilio.com/hc/en-us/articles/223183008-Formatting-International-Phone-Numbers) | Yes |
16+
| `TWILIO_VOICE_WEBHOOK_URL` | The webhook path — pre-set to `/forward-call`, 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-call --skip-credentials && cd example
31+
```
32+
33+
1. Edit `.env` and replace the placeholder `MY_PHONE_NUMBER` with your real E.164 number
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 voice webhook:
56+
57+
```shell
58+
twilio api:core:incoming-phone-numbers:update \
59+
--sid <your-phone-number-sid> \
60+
--voice-url https://<your-ngrok-id>.ngrok.app/forward-call \
61+
--voice-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 "Voice Configuration":
69+
- Set "A Call Comes In" to **Webhook**
70+
- Enter your URL: `https://<your-ngrok-id>.ngrok.app/forward-call` (or your deployed URL)
71+
- Set HTTP method to **POST**
72+
4. Click **Save**
73+
74+
## Deploying
875

9-
| Variable | Meaning |
10-
| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
11-
| `MY_PHONE_NUMBER` | The number you want to forward incoming calls to [in E.164 format](https://help.twilio.com/articles/223183008-Formatting-International-Phone-Numbers) |
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-call
82+
```

0 commit comments

Comments
 (0)