fx-private-relay/docs/end-to-end-local-phone-dev.md

End-to-end Local Phone Development

Relay uses Twilio HTTP APIs for phone numbers, texts, and calls. So, a full local end-to-end phone setup works like this:

sequenceDiagram

    555-555-5555->>Twilio: SMS
    Twilio->>your-domain.ngrok.io (127.0.0.1): POST /api/v1/inbound_sms
    your-domain.ngrok.io (127.0.0.1)->>Twilio: POST /Accounts/${SID}/Messages.json
    Twilio->>999-999-9999: SMS

Requirements

• Twilio account
• (Suggested) Premium ngrok.com account

Overview

To make your local Relay SEND messages you will:

1. Create a Twilio account
2. Set up a "main" Relay number in Twilio
3. Send a test message

To make your local Relay RECEIVE messages you will also:

1. Use ngrok to publish your local app at a public domain
2. Set up a Relay SMS application in Twilio
3. Receive a test message

Send messages

Create a Twilio account

1. Make a regular Twilio account and "Upgrade" it so you can buy a number.
2. Go to the "Console" main page
3. Copy the "Account SID" value into your .env TWILIO_ACCOUNT_SID
4. Copy the "Auth Token" value into your .env TWILIO_AUTH_TOKEN

Set up a "main" Relay number in Twilio

Relay sends its own messages to users (e.g., the text message to verify their real number) from its own "main" phone number. So, you need to buy a main phone number for Relay and set it to your TWILIO_MAIN_NUMBER env var.

1. Go to the "Buy a number" page in your Twilio account.
2. Buy a number that has Voice, SMS, and MMS capabilities.
3. In your .env set TWILIO_MAIN_NUMBER='<your-number-in-es164-format>' (e.g., +12223334444)

Configure local to enable phone features in .env

1. Add PHONES_ENABLED=True
2. Add SUBSCRIPTIONS_WITH_PHONE="relay-phones"

Enable phones for the local user

A feature flag is required to use phones outside of production. This requirement was added to prevent "subscribing" to the phone service with test Stripe credentials. Twilio charges for each reserved phone number, even if Stripe is in testing mode.

To add the required flag for every account:

./manage.py waffle_flag phones --create --everyone

To add the required flag for some accounts, first sign-in to create the account. With the new user's email address, you can then configure the flag from the command line:

./manage.py get_or_create_user_group phone_users
./manage.py waffle_flag phones --create --append --group phone_users
./manage.py add_user_to_group user@example.com phone_users

Send a test message

Now you're ready to send a test message to make sure Twilio is configured correctly. The first message in the Relay phone flow is the verification code:

1. Sign in at http://127.0.0.1:8000/.
2. Go to the staging "Relay fonez" purchase page and buy a phone subscription for the user. (Use a Stripe testing card like 4242424242424242)
3. Use the POST /api/v1/realphone/ API endpoint to trigger a verification text message.
   • Go to http://127.0.0.1:8000/api/v1/docs/
   • Scroll down to POST /realphone/
   • Click "Try it out"
   • Enter your real number e.g., {"number": "+12223334444"} (Remove the placeholder verification_code property.)
   • Click "Execute" * You should receive a text message to your real number with a verification code.
4. Use the POST /api/v1/realphone/ API endpoint again to verify your real number. This time, submit your real number AND the verification code together:
   • {"number": "+12223334444", "verification_code": "123456"}

Receive messages

Use ngrok to publish your local app at a public domain

Relay receives webhook requests from Twilio, so your local Relay app needs to be accessible at a public domain. ngrok is a great tool to make this easier.

1. Follow the instructions on the ngrok download page.
2. Put this tunnel config in the tunnels section of your ~/.ngrok2/ngrok.yml file:

   relay:
        proto: http
        addr: 127.0.0.1:8000
        subdomain: pick-a-subdomain
   

   Note: You will need ngrok premium to get a static subdomain.
3. Add your-subdomain.ngrok.io to your .env DJANGO_ALLOWED_HOST
4. Set your .env SITE_ORIGIN to your-subdomain.ngrok.io
5. Run ngrok start relay
6. Hit https://your-subdomain.ngrok.io/api/v1/docs/ to check that it's working.

Set up a Relay SMS application in Twilio

Relay has a webhook URL to receive all text messages sent to all Relay numbers. Rather than set this webhook URL separately for every Relay number, Relay uses single SMS application to assign a single webhook URL value for the entire application. So, you need to create an SMS application in Twilio, assign your local app URL to its call and text webhooks, and set its app ID to your TWILIO_SMS_APPLICATION_SID env var.

1. Go to the "TwiML Apps" page in your Twilio account.
2. Click the "+" button in the upper-left to create an app.
   • Friendly name: "your-host Relay"
   • Voice request URL: https://your-host.ngrok.io/api/v1/inbound_call HTTP POST
   • "Show optional settings"
   • Voice status callback URL: https://your-host.ngrok.io/api/v1/voice_status
   • Messaging request URL: https://your-host.ngrok.io/api/v1/inbound_sms HTTP POST
   • "Show optional settings"
   • Messaging status callback URL: https://your-host.ngrok.io/api/v1/sms_status
3. Click "Save"
4. Click the newly-created app
5. Copy the SID value into your .env TWILIO_SMS_APPLICATION_SID

Now, when your Relay app buys mask phone numbers, they will automatically be configured with the proper webhook URLs for receiving SMS.

Set up a local Relay number to receive and forward messages

With ngrok and Twilio set up, you're now ready to set up a local Relay number to receive and forward messages to your real phone.

Until the UI flow is done, you'll need to use API endpoints to do this:

1. Go to http://127.0.0.1:8000/api/v1/docs/
2. Scroll down to the GET /relaynumber/suggestions endpoint.
3. Click "Try it out"
4. Click "Execute"
5. Scroll thru the same_prefix_options, other_areas_options same_area_options and random_options numbers and find a number you like.
6. Scroll up to the POST /relaynumber/ endpoint.
7. Click "Try it out"
8. Enter the number you want. E.g., {"number": "+12223334444"}
9. Click "Execute"
10. Send a text message to your mask number.

• You should see the Twilio webhook request in your local ngrok and you should receive the text message to your real phone!