[![Build Status](](
[![Hex Version](](
[![Inline docs](](

Generate TwiML for your [Twilio]( integration, right inside
Elixir! Built to be used with [Telephonist](, 
but it can be used entirely on its own.

## Installation

ExTwiml can be installed through mix as a hex package. First, update your 
dependencies in `mix.exs`.

defp deps
  [{:ex_twiml, "~> 2.0.1"}]

If you prefer, you can depend on the latest version from Github:

defp deps
  [{:ex_twiml, github: "danielberkompas/ex_twiml"}]

Then run `mix deps.get`, and ExTwiml will be installed.

## Usage

Import the `ExTwiml` module into your module, and then use the `twiml` macro to 
generate your TwiML, like so:

defmodule YourModule do
  import ExTwiml

  def render do
    twiml do
      play "/assets/welcome.mp3"
      gather digits: 4, finish_on_key: "#" do
        say """
        Please enter the last four digits of your credit card number, followed 
        by the pound sign.
        """, voice: "woman"

You can then render the TwiML by calling `YourModule.render/0`. The output will 
be a binary in this format:

<?xml version="1.0" encoding="UTF-8"?>
  <Gather digits="4" finishOnKey="#">
    <Say voice="woman">
      Please enter the last four digits of your credit card number, followed by
      the pound sign.

The `twiml` macro simply returns a binary (or string), so you're not limited to
the pattern above. Just use `twiml` wherever you need a TwiML string.

## Supported Verbs and Nouns
See the [Twilio Documentation]( for a
complete list of verbs supported by Twilio. ExTwiml has built in macros for the
following verbs and nouns:

- [Say](
- [Play](
- [Gather](
- [Record](
- [Sms](
- [Dial](
    - [Number](
    - [Sip](
    - [Client](
    - [Conference](
    - [Queue](
- [Enqueue](
- [Leave](
- [Hangup](
- [Redirect](
- [Reject](
- [Pause](
- [Message](
    - [Body](
    - [Media](
- [Redirect](

Supported verbs can be called in three forms:

# Verbs that support nesting, like <Gather> and <Dial>:
verb option_1: "value", option_2: "value" do
    # Nested verbs here
# => "<Verb option1="value" option2="value">Nested verbs here</Verb>":

# Verbs that don't support nesting, like <Say>
twiml do
  verb "Inner text", option_1: "value", option_2: "value"
# => "<Verb option1="value" option2="value">Inner text</Verb>"

# Verbs that have no inner content, like <Reject>:
reject reason: "busy"
# => "<Reject reason="busy" />"

To maximize compatibility with future versions of the TwiML spec, ExTwiml
**does not** validate the attributes passed to the various verbs to ensure that
they are supported by Twilio. You'll need to do this yourself.

### Unsupported Verbs?
If the Twilio API adds a verb and I haven't yet added support for it, you can do
two things:

1. Submit a PR to add it
2. Use the `tag` macro in the meantime while the PR is reviewed

The tag macro can be used to create arbitrary XML tags in the output, like this:

tag :custom, option_1: "value" do
  tag :speak, do: "Whatever you say, boss!"
# => "<Custom option1="value"><Speak>Whatever you say, boss!</Speak></Custom>"

## Contributing

Contributions are welcome!

1. Fork the repository
2. Code up your changes
3. Submit a PR back here with your fix.