# ex_twilio_bootstrap

Bootstraps a Twilio application and telephone number upon startup to ease development of TwiML applications

## Installation

Add ex_twilio_bootstrap to your `mix.exs` dependencies:

def deps do
  [{:ex_twilio_bootstrap, github: "joshuafleck/ex_twilio_bootstrap"}]

Now, list the :ex_twilio_bootstrap application as your application dependency:

def application do
  [applications: [:ex_twilio_bootstrap]]

## Configuration

1. Ensure you've configured [ex_twilio]( to use your Twilio account credentials.
1. The default configurations may be overridden by setting any of the following in your `config/config.exs` file:

config :ex_twilio_bootstrap,
  # The public URL of your server (definitely override this)
  public_url: ""
  # The friendly name of the Twilio application
  application_friendly_name: "ex_twilio_bootstrap",
  # The friendly name of the Twilio telephone number
  telephone_number_friendly_name: "ex_twilio_bootstrap",
  # The iso (2-char) country code to which your telephone number will be local
  iso_country_code: "GB"

## Usage

When you application is started, ex_twilio_bootstrap will log into your Twilio
account and check the following:

1. Do you have an programmable voice application named per the configured `application_friendly_name`?
  - If yes, set its `/voice` and `/sms` URLs to use the configured `public_url` respectively
  - If no, creates a programmable voice application setting its URLs as described above
1. Do you have a phone number named per the `telephone_number_friendly_name`?
  - If yes, set its voice and messaging URLs to point to those of the application described in the previous step
  - If no, purchases a local telephone number in the country of the configured `iso_country_code` setting its URLs as described above **Note: this will charge your Twilio account**

Your application may access the application or telephone number settings via the following

# Fetches the application's settings
TwilioBootstrap.Application.get # => %ExTwilio.Application{account_sid: "...
# Fetches the telephone number's settings
TwilioBootstrap.TelephoneNumber.get # => %ExTwilio.IncomingPhoneNumber{account_sid: "...

Making a call or sms to your new telephone number will result in Twilio making a callback request to your application for TwiML on the following URLs:

- **Call** `{public_url}/voice`
- **SMS** `{public_url}/sms`

### Exposing your bootstrapped application to the web

[ex_ngrok]( provides a means for opening up your local Twilio application to the web, including allowing Twilio callbacks to be tunnelled to your local server. You can use ex_twilio_bootstrap with ex_ngrok to immediately begin testing a TwiML application with live calls by doing the following:

1. Add [ex_ngrok]( to your application
1. Add [ex_twilio_bootstrap](#Installation) to your application
1. In your application's `config/config.exs` file, dynamically set the `public_url` by fetching it from ex_ngrok:

config :ex_twilio_bootstrap,
  public_url: fn -> Ngrok.public_url end

Your programmable voice application will now be updated to use the url of the Ngrok tunnel created by ex_ngrok every time your application is started.