Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Initial Commit

  • Loading branch information...
commit e44a7191538b2d1a1fc43a4828c4a20409556351 0 parents
Kyle Conroy authored

Showing 29 changed files with 1,302 additions and 0 deletions. Show diff stats Hide diff stats

  1. +130 0 Makefile
  2. +67 0 _exts/restdomain.py
  3. BIN  _exts/restdomain.pyc
  4. +44 0 availability.rst
  5. +71 0 code/api/signature-validation.php
  6. +7 0 code/quickstart/twiml/1.0/hello-monkey.php
  7. +22 0 code/quickstart/twiml/1.1/hello-monkey.php
  8. +23 0 code/quickstart/twiml/1.2/hello-monkey.php
  9. +16 0 code/quickstart/twiml/1.3/hello-monkey-handle-key.php
  10. +26 0 code/quickstart/twiml/1.3/hello-monkey.php
  11. +22 0 code/quickstart/twiml/1.4/hello-monkey-handle-key.php
  12. +12 0 code/quickstart/twiml/1.4/hello-monkey-handle-recording.php
  13. +30 0 code/quickstart/twiml/1.4/hello-monkey.php
  14. +257 0 conf.py
  15. +50 0 debugging.rst
  16. +9 0 errors.rst
  17. +15 0 errors/10001.rst
  18. +16 0 errors/10002.rst
  19. +33 0 home.rst
  20. +21 0 index.rst
  21. +170 0 make.bat
  22. +37 0 quickstart.rst
  23. +19 0 quickstart/twiml.rst
  24. +13 0 quickstart/twiml/hello-monkey-1.rst
  25. +12 0 quickstart/twiml/hello-monkey-2.rst
  26. +31 0 quickstart/twiml/hello-monkey-3.rst
  27. +27 0 quickstart/twiml/hello-monkey-4.rst
  28. +29 0 quickstart/twiml/hello-monkey.rst
  29. +93 0 security.rst
130 Makefile
... ... @@ -0,0 +1,130 @@
  1 +# Makefile for Sphinx documentation
  2 +#
  3 +
  4 +# You can set these variables from the command line.
  5 +SPHINXOPTS =
  6 +SPHINXBUILD = sphinx-build
  7 +PAPER =
  8 +BUILDDIR = _build
  9 +
  10 +# Internal variables.
  11 +PAPEROPT_a4 = -D latex_paper_size=a4
  12 +PAPEROPT_letter = -D latex_paper_size=letter
  13 +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
  14 +
  15 +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
  16 +
  17 +help:
  18 + @echo "Please use \`make <target>' where <target> is one of"
  19 + @echo " html to make standalone HTML files"
  20 + @echo " dirhtml to make HTML files named index.html in directories"
  21 + @echo " singlehtml to make a single large HTML file"
  22 + @echo " pickle to make pickle files"
  23 + @echo " json to make JSON files"
  24 + @echo " htmlhelp to make HTML files and a HTML help project"
  25 + @echo " qthelp to make HTML files and a qthelp project"
  26 + @echo " devhelp to make HTML files and a Devhelp project"
  27 + @echo " epub to make an epub"
  28 + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
  29 + @echo " latexpdf to make LaTeX files and run them through pdflatex"
  30 + @echo " text to make text files"
  31 + @echo " man to make manual pages"
  32 + @echo " changes to make an overview of all changed/added/deprecated items"
  33 + @echo " linkcheck to check all external links for integrity"
  34 + @echo " doctest to run all doctests embedded in the documentation (if enabled)"
  35 +
  36 +clean:
  37 + -rm -rf $(BUILDDIR)/*
  38 +
  39 +html:
  40 + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
  41 + @echo
  42 + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
  43 +
  44 +dirhtml:
  45 + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
  46 + @echo
  47 + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
  48 +
  49 +singlehtml:
  50 + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
  51 + @echo
  52 + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
  53 +
  54 +pickle:
  55 + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
  56 + @echo
  57 + @echo "Build finished; now you can process the pickle files."
  58 +
  59 +json:
  60 + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
  61 + @echo
  62 + @echo "Build finished; now you can process the JSON files."
  63 +
  64 +htmlhelp:
  65 + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
  66 + @echo
  67 + @echo "Build finished; now you can run HTML Help Workshop with the" \
  68 + ".hhp project file in $(BUILDDIR)/htmlhelp."
  69 +
  70 +qthelp:
  71 + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
  72 + @echo
  73 + @echo "Build finished; now you can run "qcollectiongenerator" with the" \
  74 + ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
  75 + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/TwilioAPI.qhcp"
  76 + @echo "To view the help file:"
  77 + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/TwilioAPI.qhc"
  78 +
  79 +devhelp:
  80 + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
  81 + @echo
  82 + @echo "Build finished."
  83 + @echo "To view the help file:"
  84 + @echo "# mkdir -p $$HOME/.local/share/devhelp/TwilioAPI"
  85 + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/TwilioAPI"
  86 + @echo "# devhelp"
  87 +
  88 +epub:
  89 + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
  90 + @echo
  91 + @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
  92 +
  93 +latex:
  94 + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
  95 + @echo
  96 + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
  97 + @echo "Run \`make' in that directory to run these through (pdf)latex" \
  98 + "(use \`make latexpdf' here to do that automatically)."
  99 +
  100 +latexpdf:
  101 + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
  102 + @echo "Running LaTeX files through pdflatex..."
  103 + make -C $(BUILDDIR)/latex all-pdf
  104 + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
  105 +
  106 +text:
  107 + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
  108 + @echo
  109 + @echo "Build finished. The text files are in $(BUILDDIR)/text."
  110 +
  111 +man:
  112 + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
  113 + @echo
  114 + @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
  115 +
  116 +changes:
  117 + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
  118 + @echo
  119 + @echo "The overview file is in $(BUILDDIR)/changes."
  120 +
  121 +linkcheck:
  122 + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
  123 + @echo
  124 + @echo "Link check complete; look for any errors in the above output " \
  125 + "or in $(BUILDDIR)/linkcheck/output.txt."
  126 +
  127 +doctest:
  128 + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
  129 + @echo "Testing of doctests in the sources finished, look at the " \
  130 + "results in $(BUILDDIR)/doctest/output.txt."
67 _exts/restdomain.py
... ... @@ -0,0 +1,67 @@
  1 +# -*- coding: utf-8 -*-
  2 +"""
  3 + sphinx.domains.ruby
  4 + ~~~~~~~~~~~~~~~~~~~
  5 +
  6 + The Ruby domain.
  7 +
  8 + :copyright: Copyright 2010 by SHIBUKAWA Yoshiki
  9 + :license: BSD, see LICENSE for details.
  10 +"""
  11 +
  12 +import re
  13 +
  14 +from docutils import nodes
  15 +from docutils.parsers.rst import directives
  16 +
  17 +from sphinx import addnodes
  18 +from sphinx.roles import XRefRole
  19 +from sphinx.locale import l_, _
  20 +from sphinx.domains import Domain, ObjType, Index
  21 +from sphinx.directives import ObjectDescription
  22 +from sphinx.util.compat import Directive
  23 +from sphinx.util.docfields import Field, GroupedField, TypedField
  24 +
  25 +
  26 +class RestObject(ObjectDescription):
  27 + """
  28 + Description of a general Rest object.
  29 + """
  30 + has_arguments = False
  31 +
  32 +
  33 +class RestResource(RestObject):
  34 + """
  35 + Description of a Rest Reosource
  36 + """
  37 + has_arguments = True
  38 +
  39 +
  40 +class RestXRefRole(XRefRole):
  41 + pass
  42 +
  43 +
  44 +class RestDomain(Domain):
  45 + """Rest language domain."""
  46 + name = 'rest'
  47 + label = 'REST'
  48 + object_types = {
  49 + 'attribute': ObjType(l_('attribute'), 'attr'),
  50 + 'resource': ObjType(l_('resource'), 'resc'),
  51 + }
  52 +
  53 + directives = {
  54 + 'resource': RestResource,
  55 + 'attribute': RestObject,
  56 + }
  57 +
  58 + roles = {
  59 + 'resc': RestXRefRole(),
  60 + }
  61 +
  62 + initial_data = {
  63 + 'resources': {}, # fullname -> docname, objtype
  64 + }
  65 +
  66 +def setup(app):
  67 + app.add_domain(RestDomain)
BIN  _exts/restdomain.pyc
Binary file not shown
44 availability.rst
Source Rendered
... ... @@ -0,0 +1,44 @@
  1 +============================
  2 +Availability and Reliability
  3 +============================
  4 +
  5 +Fallback URLs
  6 +---------------
  7 +
  8 +Twilio maintains a redundant, clustered architecture designed to ensure reliable high availability service. This is only half of the challenge. Because of the distributed nature of a Twilio application, your web application must be reliable and highly available as well. To aid you in this task, Twilio allows the configuration of "Fallback" URLs on incoming phone numbers via your Account Portal or the REST API's IncomingPhoneNumbers resource.
  9 +
  10 +A Fallback URL is a URL that Twilio requests in the event of a fatal error while executing your call. If Twilio is unable to retrieve or execute TwiML from your web server, a request is immediately made to the appropriate Fallback URL. Twilio will submit the 'ErrorCode' and 'ErrorUrl' parameters, indicating the error code of the failure and what URL the failure occurred on. You can reply to the fallback URL request with more TwiML, returning a custom application error message, or attempting to recover and continue your call or SMS session.
  11 +
  12 +Example Use Cases
  13 +>>>>>>>>>>>>>>>>>>
  14 +
  15 +Primary Web Server Failover
  16 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  17 +
  18 +**Problem**: you want to make sure your Twilio application continues to accept calls, even if
  19 +your primary web server goes down.
  20 +
  21 +**Solution**: Configure your incoming phone number's Voice URL to ``http://www.mysite.com/index`` and Voice Fallback URL to ``http://fallback.mysite.com/index``. If Twilio requests ``http://www.mysite.com/index`` and receives an HTTP error or connection failure, it will then request ``http://fallback.mysite.com/index``. If the fallback URL responds with valid TwiML, Twilio will use it to continue the call as if there was no problem.
  22 +
  23 +Custom Error Message
  24 +~~~~~~~~~~~~~~~~~~~~~~~
  25 +**Problem**: You do not want your callers to hear the default Twilio application error message.
  26 +
  27 +**Solution**: Create an error TwiML document to <Say> or <Play> a custom error message. Configure the Voice Fallback URL for your phone number to point at this document's URL. If Twilio encounters a fatal error, callers will hear your custom failure message instead of Twilio's.
  28 +
  29 +.. code-block:: xml
  30 +
  31 + <?xml version="1.0" encoding="UTF-8" ?>
  32 + <Response>
  33 + <Say>
  34 + An application error has occured.
  35 + Please call back later
  36 + </Say>
  37 + </Response>
  38 +
  39 +Catching Errors
  40 +~~~~~~~~~~~~~~~
  41 +
  42 +**Problem**: You want to be notified of errors as they occur.
  43 +
  44 +**Solution**: Configure your Fallback URL to point at a URL that looks for the 'ErrorCode' and 'ErrorUrl' parameters. Your application can log these errors, email you an alert, etc. You can respond to the request with TwiML containing an error message for the caller or attempt to recover and continue with the call.
71 code/api/signature-validation.php
... ... @@ -0,0 +1,71 @@
  1 +<?php
  2 + // This function calculates the HMAC hash of the data with the key passed in
  3 + // Note: hash_hmac requires PHP 5 >= 5.1.2 or PECL hash:1.1-1.5
  4 + // Or http://pear.php.net/package/Crypt_HMAC/
  5 + function calculate_twilio_signature($key, $data) {
  6 + $sig = base64_encode(hash_hmac("sha1", $data, $key, true));
  7 + return $sig;
  8 + }
  9 +
  10 +
  11 + // this function assembles the data to sign from the $_SERVER and $_POST superglobals
  12 + function build_twilio_data_string() {
  13 +
  14 + // Our data string starts with the full URL
  15 +
  16 + // Note, that if your URL uses an implied "index" document (index.php), then apache
  17 + // often adds a slash to the SCRIPT_URI while Twilio's original request will not have a slash
  18 + // Example: if Twilio requested http://mycompany.com/twilio
  19 + // and that url is handled by an index.php script
  20 + // Apache/PHP will report the URI as being: http://mycompany.com/twilio/
  21 + // But the hash should be calculated without the trailing slash
  22 +
  23 + // Also note, if you're using URL rewriting, then you should check to see that
  24 + // PHP is reporting your SCRIPT_URI and QUERY_STRING correctly.
  25 +
  26 + $string_to_sign = $_SERVER['SCRIPT_URI'];
  27 +
  28 + // if there's a query string, add it here along with the question mark
  29 + if(strlen($_SERVER['QUERY_STRING']))
  30 + $string_to_sign .= "?{$_SERVER['QUERY_STRING']}";
  31 +
  32 + // Now, if it's a POST, then we need to add the POST parameters
  33 + // alphabetized to the data string
  34 + if(isset($_POST)) {
  35 +
  36 + // copy the post data
  37 + $data = $_POST;
  38 +
  39 + // sort the array by keys
  40 + ksort($data);
  41 +
  42 + // append them to the data string in order with no delimiters
  43 + foreach($data AS $key=>$value)
  44 + $string_to_sign .= "$key$value";
  45 +
  46 + }
  47 +
  48 + return $string_to_sign;
  49 +
  50 + }
  51 +
  52 + // Use your Twilio AuthToken here. Case matters.
  53 + $MY_KEY = "1234567890ABCDEF";
  54 +
  55 + // Get the signature sent by twilio in the HTTP Headers
  56 + // PHP exposes HTTP headers in the $_SERVER superglobal array
  57 + // in all upper case, with underscores instead of dashes, with the word "HTTP_" prefixed
  58 + $expected_signature = $_SERVER["HTTP_X_TWILIO_SIGNATURE"];
  59 +
  60 + // Build the data string to sign
  61 + $data_to_sign = build_twilio_data_string();
  62 +
  63 + // sign it
  64 + $calculated_signature = calculate_twilio_signature($MY_KEY, $data_to_sign);
  65 +
  66 + // if signatures match, then it's authenticated
  67 + if($calculated_signature == $expected_signature)
  68 + echo "Match!";
  69 + else
  70 + echo "Uh oh";
  71 + ?>
7 code/quickstart/twiml/1.0/hello-monkey.php
... ... @@ -0,0 +1,7 @@
  1 +<?php
  2 + header("content-type: text/xml");
  3 + echo "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";
  4 +?>
  5 +<Response>
  6 + <Say>Hello Monkey</Say>
  7 +</Response>
22 code/quickstart/twiml/1.1/hello-monkey.php
... ... @@ -0,0 +1,22 @@
  1 +<?php
  2 +
  3 + // make an associative array of callers we know, indexed by phone number
  4 + $people = array(
  5 + "+14158675309"=>"Curious George",
  6 + "+14158675310"=>"Boots",
  7 + "+14158675311"=>"Virgil",
  8 + "+14158675312"=>"Marcel"
  9 + );
  10 +
  11 + // if the caller is known, then greet them by name
  12 + // otherwise, consider them just another monkey
  13 + if(!$name = $people[$_REQUEST['From']])
  14 + $name = "Monkey";
  15 +
  16 + // now greet the caller
  17 + header("content-type: text/xml");
  18 + echo "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";
  19 +?>
  20 +<Response>
  21 + <Say>Hello <?php echo $name ?>.</Say>
  22 +</Response>
23 code/quickstart/twiml/1.2/hello-monkey.php
... ... @@ -0,0 +1,23 @@
  1 +<?php
  2 +
  3 + // make an associative array of callers we know, indexed by phone number
  4 + $people = array(
  5 + "+14158675309"=>"Curious George",
  6 + "+14158675310"=>"Boots",
  7 + "+14158675311"=>"Virgil",
  8 + "+14158675312"=>"Marcel"
  9 + );
  10 +
  11 + // if the caller is known, then greet them by name
  12 + // otherwise, consider them just anohter monkey
  13 + if(!$name = $people[$_REQUEST['From']])
  14 + $name = "Monkey";
  15 +
  16 + // now greet the caller
  17 + header("content-type: text/xml");
  18 + echo "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";
  19 +?>
  20 +<Response>
  21 + <Say>Hello <?php echo $name ?>.</Say>
  22 + <Play>http://demo.twilio.com/hellomonkey/monkey.mp3</Play>
  23 +</Response>
16 code/quickstart/twiml/1.3/hello-monkey-handle-key.php
... ... @@ -0,0 +1,16 @@
  1 +<?php
  2 +
  3 + // if the caller pressed anything but 1 send them back
  4 + if($_REQUEST['Digits'] != '1') {
  5 + header("Location: hello-monkey.php");
  6 + die;
  7 + }
  8 +
  9 + // the user pressed 1, connect the call to 310-555-1212
  10 + header("content-type: text/xml");
  11 + echo "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";
  12 +?>
  13 +<Response>
  14 + <Dial>+13105551212</Dial>
  15 + <Say>The call failed or the remote party hung up. Goodbye.</Say>
  16 +</Response>
26 code/quickstart/twiml/1.3/hello-monkey.php
... ... @@ -0,0 +1,26 @@
  1 +<?php
  2 +
  3 + // make an associative array of callers we know, indexed by phone number
  4 + $people = array(
  5 + "+14158675309"=>"Curious George",
  6 + "+14158675310"=>"Boots",
  7 + "+14158675311"=>"Virgil",
  8 + "+14158675312"=>"Marcel"
  9 + );
  10 +
  11 + // if the caller is known, then greet them by name
  12 + // otherwise, consider them just anohter monkey
  13 + if(!$name = $people[$_REQUEST['From']])
  14 + $name = "Monkey";
  15 +
  16 + // now greet the caller
  17 + header("content-type: text/xml");
  18 + echo "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";
  19 +?>
  20 +<Response>
  21 + <Say>Hello <?php echo $name ?>.</Say>
  22 + <Play>http://demo.twilio.com/hellomonkey/monkey.mp3</Play>
  23 + <Gather numDigits="1" action="hello-monkey-handle-key.php" method="POST">
  24 + <Say>To speak to a real monkey, press 1. Press any other key to start over.</Say>
  25 + </Gather>
  26 +</Response>
22 code/quickstart/twiml/1.4/hello-monkey-handle-key.php
... ... @@ -0,0 +1,22 @@
  1 +<?php
  2 +
  3 + // if the caller pressed anything but 1 or 2 send them back
  4 + if($_REQUEST['Digits'] != '1' and $_REQUEST['Digits'] != '2') {
  5 + header("Location: hello-monkey.php");
  6 + die;
  7 + }
  8 +
  9 + // otherwise, if 1 was pressed we Dial 3105551212. If 2
  10 + // we make an audio recording up to 30 seconds long.
  11 + header("content-type: text/xml");
  12 + echo "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";
  13 +?>
  14 +<Response>
  15 +<?php if ($_REQUEST['Digits'] == '1') { ?>
  16 + <Dial>+13105551212</Dial>
  17 + <Say>The call failed or the remote party hung up. Goodbye.</Say>
  18 +<?php } elseif ($_REQUEST['Digits'] == '2') { ?>
  19 + <Say>Record your monkey howl after the tone.</Say>
  20 + <Record maxLength="30" action="hello-monkey-handle-recording.php" />
  21 +<?php } ?>
  22 +</Response>
12 code/quickstart/twiml/1.4/hello-monkey-handle-recording.php
... ... @@ -0,0 +1,12 @@
  1 +<?php
  2 +
  3 + // tell the caller that they should listen to their howl
  4 + // and play the recording back, using the URL that Twilio posted
  5 + header("content-type: text/xml");
  6 + echo "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";
  7 +?>
  8 +<Response>
  9 + <Say>Thanks for howling... take a listen to what you howled.</Say>
  10 + <Play><?php echo $_REQUEST['RecordingUrl']; ?></Play>
  11 + <Say>Goodbye.</Say>
  12 +</Response>
30 code/quickstart/twiml/1.4/hello-monkey.php
... ... @@ -0,0 +1,30 @@
  1 +<?php
  2 +
  3 + // make an associative array of callers we know, indexed by phone number
  4 + $people = array(
  5 + "+14158675309"=>"Curious George",
  6 + "+14158675310"=>"Boots",
  7 + "+14158675311"=>"Virgil",
  8 + "+14158675312"=>"Marcel"
  9 + );
  10 +
  11 + // if the caller is known, then greet them by name
  12 + // otherwise, consider them just anohter monkey
  13 + if(!$name = $people[$_REQUEST['From']])
  14 + $name = "Monkey";
  15 +
  16 + // now greet the caller
  17 + header("content-type: text/xml");
  18 + echo "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";
  19 +?>
  20 +<Response>
  21 + <Say>Hello <?php echo $name ?>.</Say>
  22 + <Play>http://demo.twilio.com/hellomonkey/monkey.mp3</Play>
  23 + <Gather numDigits="1" action="hello-monkey-handle-key.php" method="POST">
  24 + <Say>
  25 + To speak with a real monkey, press 1.
  26 + Press 2 to record your own monkey howl.
  27 + Press any other key to start over.
  28 + </Say>
  29 + </Gather>
  30 +</Response>
257 conf.py
... ... @@ -0,0 +1,257 @@
  1 +# -*- coding: utf-8 -*-
  2 +#
  3 +# Twilio API documentation build configuration file, created by
  4 +# sphinx-quickstart on Wed Feb 23 13:09:31 2011.
  5 +#
  6 +# This file is execfile()d with the current directory set to its containing dir.
  7 +#
  8 +# Note that not all possible configuration values are present in this
  9 +# autogenerated file.
  10 +#
  11 +# All configuration values have a default; values that are commented out
  12 +# serve to show the default.
  13 +
  14 +import sys, os
  15 +
  16 +# If extensions (or modules to document with autodoc) are in another directory,
  17 +# add these directories to sys.path here. If the directory is relative to the
  18 +# documentation root, use os.path.abspath to make it absolute, like shown here.
  19 +#sys.path.insert(0, os.path.abspath('.'))
  20 +
  21 +# -- General configuration -----------------------------------------------------
  22 +
  23 +# If your documentation needs a minimal Sphinx version, state it here.
  24 +#needs_sphinx = '1.0'
  25 +sys.path.append(os.path.abspath('_exts'))
  26 +
  27 +# Add any Sphinx extension module names here, as strings. They can be extensions
  28 +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
  29 +extensions = ['restdomain']
  30 +
  31 +# Add any paths that contain templates here, relative to this directory.
  32 +templates_path = ['_templates']
  33 +
  34 +# The suffix of source filenames.
  35 +source_suffix = '.rst'
  36 +
  37 +# The encoding of source files.
  38 +#source_encoding = 'utf-8-sig'
  39 +
  40 +# The master toctree document.
  41 +master_doc = 'index'
  42 +
  43 +# General information about the project.
  44 +project = u'Twilio API'
  45 +copyright = u'2011, Kyle'
  46 +
  47 +# The version info for the project you're documenting, acts as replacement for
  48 +# |version| and |release|, also used in various other places throughout the
  49 +# built documents.
  50 +#
  51 +# The short X.Y version.
  52 +version = '2010-04-01'
  53 +# The full version, including alpha/beta/rc tags.
  54 +release = '2010-04-01'
  55 +
  56 +# The language for content autogenerated by Sphinx. Refer to documentation
  57 +# for a list of supported languages.
  58 +#language = None
  59 +
  60 +# There are two options for replacing |today|: either, you set today to some
  61 +# non-false value, then it is used:
  62 +#today = ''
  63 +# Else, today_fmt is used as the format for a strftime call.
  64 +#today_fmt = '%B %d, %Y'
  65 +
  66 +# List of patterns, relative to source directory, that match files and
  67 +# directories to ignore when looking for source files.
  68 +exclude_patterns = ['_build']
  69 +
  70 +# The reST default role (used for this markup: `text`) to use for all documents.
  71 +#default_role = None
  72 +
  73 +# If true, '()' will be appended to :func: etc. cross-reference text.
  74 +#add_function_parentheses = True
  75 +
  76 +# If true, the current module name will be prepended to all description
  77 +# unit titles (such as .. function::).
  78 +#add_module_names = True
  79 +
  80 +# If true, sectionauthor and moduleauthor directives will be shown in the
  81 +# output. They are ignored by default.
  82 +#show_authors = False
  83 +
  84 +# The name of the Pygments (syntax highlighting) style to use.
  85 +pygments_style = 'sphinx'
  86 +
  87 +# A list of ignored prefixes for module index sorting.
  88 +#modindex_common_prefix = []
  89 +
  90 +
  91 +# -- Options for HTML output ---------------------------------------------------
  92 +
  93 +# The theme to use for HTML and HTML Help pages. See the documentation for
  94 +# a list of builtin themes.
  95 +html_theme = 'default'
  96 +
  97 +# Theme options are theme-specific and customize the look and feel of a theme
  98 +# further. For a list of options available for each theme, see the
  99 +# documentation.
  100 +#html_theme_options = {}
  101 +
  102 +# Add any paths that contain custom themes here, relative to this directory.
  103 +#html_theme_path = []
  104 +
  105 +# The name for this set of Sphinx documents. If None, it defaults to
  106 +# "<project> v<release> documentation".
  107 +#html_title = None
  108 +
  109 +# A shorter title for the navigation bar. Default is the same as html_title.
  110 +#html_short_title = None
  111 +
  112 +# The name of an image file (relative to this directory) to place at the top
  113 +# of the sidebar.
  114 +#html_logo = None
  115 +
  116 +# The name of an image file (within the static path) to use as favicon of the
  117 +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
  118 +# pixels large.
  119 +#html_favicon = None
  120 +
  121 +# Add any paths that contain custom static files (such as style sheets) here,
  122 +# relative to this directory. They are copied after the builtin static files,
  123 +# so a file named "default.css" will overwrite the builtin "default.css".
  124 +html_static_path = ['_static']
  125 +
  126 +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
  127 +# using the given strftime format.
  128 +#html_last_updated_fmt = '%b %d, %Y'
  129 +
  130 +# If true, SmartyPants will be used to convert quotes and dashes to
  131 +# typographically correct entities.
  132 +#html_use_smartypants = True
  133 +
  134 +# Custom sidebar templates, maps document names to template names.
  135 +#html_sidebars = {}
  136 +
  137 +# Additional templates that should be rendered to pages, maps page names to
  138 +# template names.
  139 +#html_additional_pages = {}
  140 +
  141 +# If false, no module index is generated.
  142 +#html_domain_indices = True
  143 +
  144 +# If false, no index is generated.
  145 +#html_use_index = True
  146 +
  147 +# If true, the index is split into individual pages for each letter.
  148 +#html_split_index = False
  149 +
  150 +# If true, links to the reST sources are added to the pages.
  151 +#html_show_sourcelink = True
  152 +
  153 +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
  154 +#html_show_sphinx = True
  155 +
  156 +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
  157 +#html_show_copyright = True
  158 +
  159 +# If true, an OpenSearch description file will be output, and all pages will
  160 +# contain a <link> tag referring to it. The value of this option must be the
  161 +# base URL from which the finished HTML is served.
  162 +#html_use_opensearch = ''
  163 +
  164 +# This is the file name suffix for HTML files (e.g. ".xhtml").
  165 +#html_file_suffix = None
  166 +
  167 +# Output file base name for HTML help builder.
  168 +htmlhelp_basename = 'TwilioAPIdoc'
  169 +
  170 +
  171 +# -- Options for LaTeX output --------------------------------------------------
  172 +
  173 +# The paper size ('letter' or 'a4').
  174 +#latex_paper_size = 'letter'
  175 +
  176 +# The font size ('10pt', '11pt' or '12pt').
  177 +#latex_font_size = '10pt'
  178 +
  179 +# Grouping the document tree into LaTeX files. List of tuples
  180 +# (source start file, target name, title, author, documentclass [howto/manual]).
  181 +latex_documents = [
  182 + ('index', 'TwilioAPI.tex', u'Twilio API Documentation',
  183 + u'Kyle', 'manual'),
  184 +]
  185 +
  186 +# The name of an image file (relative to this directory) to place at the top of
  187 +# the title page.
  188 +#latex_logo = None
  189 +
  190 +# For "manual" documents, if this is true, then toplevel headings are parts,
  191 +# not chapters.
  192 +#latex_use_parts = False
  193 +
  194 +# If true, show page references after internal links.
  195 +#latex_show_pagerefs = False
  196 +
  197 +# If true, show URL addresses after external links.
  198 +#latex_show_urls = False
  199 +
  200 +# Additional stuff for the LaTeX preamble.
  201 +#latex_preamble = ''
  202 +
  203 +# Documents to append as an appendix to all manuals.
  204 +#latex_appendices = []
  205 +
  206 +# If false, no module index is generated.
  207 +#latex_domain_indices = True
  208 +
  209 +
  210 +# -- Options for manual page output --------------------------------------------
  211 +
  212 +# One entry per manual page. List of tuples
  213 +# (source start file, name, description, authors, manual section).
  214 +man_pages = [
  215 + ('index', 'twilioapi', u'Twilio API Documentation',
  216 + [u'Kyle'], 1)
  217 +]
  218 +
  219 +
  220 +# -- Options for Epub output ---------------------------------------------------
  221 +
  222 +# Bibliographic Dublin Core info.
  223 +epub_title = u'Twilio API'
  224 +epub_author = u'Kyle'
  225 +epub_publisher = u'Kyle'
  226 +epub_copyright = u'2011, Kyle'
  227 +
  228 +# The language of the text. It defaults to the language option
  229 +# or en if the language is not set.
  230 +#epub_language = ''
  231 +
  232 +# The scheme of the identifier. Typical schemes are ISBN or URL.
  233 +#epub_scheme = ''
  234 +
  235 +# The unique identifier of the text. This can be a ISBN number
  236 +# or the project homepage.
  237 +#epub_identifier = ''
  238 +
  239 +# A unique identification for the text.
  240 +#epub_uid = ''
  241 +
  242 +# HTML files that should be inserted before the pages created by sphinx.
  243 +# The format is a list of tuples containing the path and title.
  244 +#epub_pre_files = []
  245 +
  246 +# HTML files shat should be inserted after the pages created by sphinx.
  247 +# The format is a list of tuples containing the path and title.
  248 +#epub_post_files = []
  249 +
  250 +# A list of files that should not be packed into the epub file.
  251 +#epub_exclude_files = []
  252 +
  253 +# The depth of the table of contents in toc.ncx.
  254 +#epub_tocdepth = 3
  255 +
  256 +# Allow duplicate toc entries.
  257 +#epub_tocdup = True
50 debugging.rst
Source Rendered
... ... @@ -0,0 +1,50 @@
  1 +=============
  2 +Debugging
  3 +=============
  4 +
  5 +.. toctree::
  6 + :hidden:
  7 +
  8 + errors
  9 +
  10 +Writing an application on Twilio is easy as momma's pie. But here are a few tips we've found helpful...
  11 +
  12 +Check the Logs
  13 +-----------------
  14 +Twilio logs information about it's interaction with your application, including all errors and warnings. You can check the contents of those logs to help you debug. There are two ways to do this:
  15 +
  16 +* UI: Visit the `Twilio Debugging Interface <http://www.twilio.com/user/account/debugger>`_
  17 +* Web Service: Use the :ref:`Notifications REST API` to query for logs.
  18 +
  19 +Check the Response Body
  20 +----------------------------
  21 +
  22 +While all errors and warnings are available in the the `Twilio debugging interface <http://www.twilio.com/user/account/debugger>`_, the REST API will also return a Twilio REST Exception XML block which contains the HTML error code, Twilio-specific error code, error message, and a link to the Error Code Reference.
  23 +
  24 +.. code-block:: xml
  25 +
  26 + <?xml version="1.0"?>
  27 + <TwilioResponse>
  28 + <RestException>
  29 + <Status>400</Status>
  30 + <Message>Dial: Invalid phone number format </Message>
  31 + <Code>13223</Code>
  32 + <MoreInfo>http://www.twilio.com/docs/errors/13223</MoreInfo>
  33 + </RestException>
  34 + </TwilioResponse>
  35 +
  36 +All Twilio-specific errors are listed in the :doc:`errors`
  37 +
  38 +The Browser Is Your Friend
  39 +--------------------------------
  40 +
  41 +Remember, you're just writing a web application. There's nothing Twilio does that you can't test right there in your browser. Visit the URLs in your web browser, and see that you don't have any errors.
  42 +
  43 +* Firefox treats XML files really nicely, highlighting any invalid XML in your document. We're not forcing you to use Firefox or anything, we're just saying it's cool... that's all.
  44 +* Using Firefox, you can easily see if your application is returning valid XML. Firefox will show you encoding or other errors in your XML, which is helpful.
  45 +* Mimic Twilio's data passing by manually adding data to your URLs. For example, if you ask Twilio to digits and the action is http://www.myapp.com/handleDigits.php, you can open your browser to http://www.myapp.com/handleDigits.php?Digits=1 to verify what happens if the user presses 1.
  46 +
  47 +Debug Output From your Application
  48 +-------------------------------------
  49 +
  50 +Make sure your application isn't sending debug output, because that will nearly always cause problems XML validation problem. You can, however, wrap any such output in XML comment blocks... they're the same as HTML comment blocks: <!-- COMMENTS HERE --><br/>
9 errors.rst
Source Rendered
... ... @@ -0,0 +1,9 @@
  1 +==============================
  2 +Error and Warning Dictionary
  3 +==============================
  4 +
  5 +.. toctree::
  6 + :glob:
  7 + :maxdepth: 1
  8 +
  9 + errors/*
15 errors/10001.rst
Source Rendered
... ... @@ -0,0 +1,15 @@
  1 +====================================
  2 +Error 10001 - Account is not active
  3 +====================================
  4 +
  5 +This account has been disabled and may not be used until it is reactived.
  6 +
  7 +Possible Causes
  8 +>>>>>>>>>>>>>>>
  9 +* Lack of funds
  10 +* Violation of the Terms of Service or Acceptable Use Policy
  11 +
  12 +Possible Solutions
  13 +>>>>>>>>>>>>>>>>>>>
  14 +* Check your account balance. Refill funds if necessary.
  15 +* Contact Twilio customer support to inquire further.
16 errors/10002.rst
Source Rendered
... ... @@ -0,0 +1,16 @@
  1 +============
  2 +Error 10002
  3 +============
  4 +
  5 +Trial account does not support this feature
  6 +---------------------------------------------
  7 +
  8 +Your account is currently in Trial mode and does not have access to this feature.
  9 +
  10 +Possible Causes
  11 +>>>>>>>>>>>>>>>>>>>
  12 +* Attempting to use a premium feature with a trial account
  13 +
  14 +Possible Solutions
  15 +>>>>>>>>>>>>>>>>>>
  16 +* Upgrade to a full account to remove this error
33 home.rst
Source Rendered
... ... @@ -0,0 +1,33 @@
  1 +=============
  2 +TWILIO DOCS
  3 +=============
  4 +
  5 +Getting Started?
  6 +----------------
  7 +Start making calls and sending SMS messages in minutes
  8 +
  9 +
  10 +Quickstarts
  11 +>>>>>>>>>>>>>
  12 +A set of simple tutorials on how to make and receive phone calls and send and receive SMS messages.
  13 +
  14 +HowTo's and Examples
  15 +>>>>>>>>>>>>>>>>>>>>>
  16 +Fully working Twilio apps in a variety of languages for you to download and test drive yourself
  17 +
  18 +API Reference
  19 +--------------
  20 +Detailed docs on Twilio's APIs
  21 +
  22 +REST Reference
  23 +>>>>>>>>>>>>>>>
  24 +Make calls, send SMS, buy and manage phone numbers. Here, Twilio acts like an HTTP server
  25 +
  26 +TwiML Reference
  27 +>>>>>>>>>>>>>>>>
  28 +
  29 +Control live phone calls and respond to SMS messages. Here, Twilio acts like an HTTP client (web browser)
  30 +
  31 +Helper Libraries
  32 +>>>>>>>>>>>>>>>>>>>
  33 +Libraries that help you interact with Twilio in all your favorite languages: PHP, Python, Ruby, Java and C#.Contents:
21 index.rst
Source Rendered
... ... @@ -0,0 +1,21 @@
  1 +.. Twilio API documentation master file, created by
  2 + sphinx-quickstart on Wed Feb 23 13:09:31 2011.
  3 + You can adapt this file completely to your liking, but it should at least
  4 + contain the root `toctree` directive.
  5 +
  6 +Twilio Documentation Contents
  7 +======================================
  8 +.. toctree::
  9 + :maxdepth: 1
  10 +
  11 + quickstart
  12 + howtos
  13 + twiml
  14 + rest
  15 + helperlibs
  16 + debugging
  17 + security
  18 + availability
  19 + download
  20 +
  21 +
170 make.bat
... ... @@ -0,0 +1,170 @@
  1 +@ECHO OFF
  2 +
  3 +REM Command file for Sphinx documentation
  4 +
  5 +if "%SPHINXBUILD%" == "" (
  6 + set SPHINXBUILD=sphinx-build
  7 +)
  8 +set BUILDDIR=_build
  9 +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
  10 +if NOT "%PAPER%" == "" (
  11 + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
  12 +)
  13 +
  14 +if "%1" == "" goto help
  15 +
  16 +if "%1" == "help" (
  17 + :help
  18 + echo.Please use `make ^<target^>` where ^<target^> is one of
  19 + echo. html to make standalone HTML files
  20 + echo. dirhtml to make HTML files named index.html in directories
  21 + echo. singlehtml to make a single large HTML file
  22 + echo. pickle to make pickle files
  23 + echo. json to make JSON files
  24 + echo. htmlhelp to make HTML files and a HTML help project
  25 + echo. qthelp to make HTML files and a qthelp project
  26 + echo. devhelp to make HTML files and a Devhelp project
  27 + echo. epub to make an epub
  28 + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
  29 + echo. text to make text files
  30 + echo. man to make manual pages
  31 + echo. changes to make an overview over all changed/added/deprecated items
  32 + echo. linkcheck to check all external links for integrity
  33 + echo. doctest to run all doctests embedded in the documentation if enabled
  34 + goto end
  35 +)
  36 +
  37 +if "%1" == "clean" (
  38 + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
  39 + del /q /s %BUILDDIR%\*
  40 + goto end
  41 +)
  42 +
  43 +if "%1" == "html" (
  44 + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
  45 + if errorlevel 1 exit /b 1
  46 + echo.
  47 + echo.Build finished. The HTML pages are in %BUILDDIR%/html.
  48 + goto end
  49 +)
  50 +
  51 +if "%1" == "dirhtml" (
  52 + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
  53 + if errorlevel 1 exit /b 1
  54 + echo.
  55 + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
  56 + goto end
  57 +)
  58 +
  59 +if "%1" == "singlehtml" (
  60 + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
  61 + if errorlevel 1 exit /b 1
  62 + echo.
  63 + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
  64 + goto end
  65 +)
  66 +
  67 +if "%1" == "pickle" (
  68 + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
  69 + if errorlevel 1 exit /b 1
  70 + echo.
  71 + echo.Build finished; now you can process the pickle files.
  72 + goto end
  73 +)
  74 +
  75 +if "%1" == "json" (
  76 + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
  77 + if errorlevel 1 exit /b 1
  78 + echo.
  79 + echo.Build finished; now you can process the JSON files.
  80 + goto end
  81 +)
  82 +
  83 +if "%1" == "htmlhelp" (
  84 + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
  85 + if errorlevel 1 exit /b 1
  86 + echo.
  87 + echo.Build finished; now you can run HTML Help Workshop with the ^
  88 +.hhp project file in %BUILDDIR%/htmlhelp.
  89 + goto end
  90 +)
  91 +
  92 +if "%1" == "qthelp" (
  93 + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
  94 + if errorlevel 1 exit /b 1
  95 + echo.
  96 + echo.Build finished; now you can run "qcollectiongenerator" with the ^
  97 +.qhcp project file in %BUILDDIR%/qthelp, like this:
  98 + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\TwilioAPI.qhcp
  99 + echo.To view the help file:
  100 + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\TwilioAPI.ghc
  101 + goto end
  102 +)
  103 +
  104 +if "%1" == "devhelp" (
  105 + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
  106 + if errorlevel 1 exit /b 1
  107 + echo.
  108 + echo.Build finished.
  109 + goto end
  110 +)
  111 +
  112 +if "%1" == "epub" (
  113 + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
  114 + if errorlevel 1 exit /b 1
  115 + echo.
  116 + echo.Build finished. The epub file is in %BUILDDIR%/epub.
  117 + goto end
  118 +)
  119 +
  120 +if "%1" == "latex" (
  121 + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
  122 + if errorlevel 1 exit /b 1
  123 + echo.
  124 + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
  125 + goto end
  126 +)
  127 +
  128 +if "%1" == "text" (
  129 + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
  130 + if errorlevel 1 exit /b 1
  131 + echo.
  132 + echo.Build finished. The text files are in %BUILDDIR%/text.
  133 + goto end
  134 +)
  135 +
  136 +if "%1" == "man" (
  137 + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
  138 + if errorlevel 1 exit /b 1
  139 + echo.
  140 + echo.Build finished. The manual pages are in %BUILDDIR%/man.
  141 + goto end
  142 +)
  143 +
  144 +if "%1" == "changes" (
  145 + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
  146 + if errorlevel 1 exit /b 1
  147 + echo.
  148 + echo.The overview file is in %BUILDDIR%/changes.
  149 + goto end
  150 +)
  151 +
  152 +if "%1" == "linkcheck" (
  153 + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
  154 + if errorlevel 1 exit /b 1
  155 + echo.
  156 + echo.Link check complete; look for any errors in the above output ^
  157 +or in %BUILDDIR%/linkcheck/output.txt.
  158 + goto end
  159 +)
  160 +
  161 +if "%1" == "doctest" (
  162 + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
  163 + if errorlevel 1 exit /b 1
  164 + echo.
  165 + echo.Testing of doctests in the sources finished, look at the ^
  166 +results in %BUILDDIR%/doctest/output.txt.
  167 + goto end
  168 +)
  169 +
  170 +:end
37 quickstart.rst
Source Rendered
... ... @@ -0,0 +1,37 @@
  1 +===================================
  2 +Twilio Quickstart Guide
  3 +===================================
  4 +
  5 +The Quickstarts are short simple guides intended to help you get started using Twilio's voice and SMS APIs.
  6 +
  7 +Incoming Calls
  8 +--------------------------
  9 +
  10 +Hello Monkey: TwiML Quickstart
  11 +
  12 +The Hello Monkey Quickstart provides an introduction to the Twilio Markup Language (TwiML). The demo walks though the process of building a system to handle incoming calls that greets callers by name, plays an audio file, connects the call to another phone number, and lets callers leave an audio recording.
  13 +
  14 +.. toctree::
  15 + :maxdepth: 1
  16 +
  17 + quickstart/twiml
  18 + Hello Monkey <quickstart/twiml/hello-monkey>
  19 + Hello Monkey 1.1<quickstart/twiml/hello-monkey-1>
  20 + Hello Monkey 1.2<quickstart/twiml/hello-monkey-2>
  21 + Hello Monkey 1.3<quickstart/twiml/hello-monkey-3>
  22 + Hello Monkey 1.4<quickstart/twiml/hello-monkey-4>
  23 +
  24 +Outgoing Calls
  25 +--------------------------
  26 +
  27 +Twilio REST API Quickstart
  28 +
  29 +The Twilio REST API Quickstart demonstrates how to build an application that initiates an outgoing phone call and gets a list of previous calls using the Twilio REST API.
  30 +
  31 +
  32 +Incoming and Outgoing SMS Messages
  33 +--------------------------------------
  34 +
  35 +Twilio SMS Quickstart
  36 +
  37 +The Twilio SMS Quickstart demonstrates how to build an application that sends and receives SMS messages using Twilio Markup Language (TwiML) and the Twilio REST API.
19 quickstart/twiml.rst
Source Rendered
... ... @@ -0,0 +1,19 @@
  1 +===================================
  2 +Twilio Markup Language Quickstart
  3 +===================================
  4 +
  5 +Overview
  6 +-----------
  7 +The goal of this quickstart is to understand how Twilio lets you control phone calls using the Twilio Markup Language (TwiML).
  8 +
  9 +Twilio Markup Language
  10 +------------------------
  11 +Twilio Markup Language (TwiML) defines a simple set of instructions for letting your PHP/Java/Ruby/C#/Python/etc web application control live phone calls. New TwiML instructions are fetched by Twilio from your server at the start of each phone call and then again each time there is input from the phone. Just like a web browser, whenever the phone connected to Twilio performs an action such as a key press, Twilio makes a request to your server with the new data asking your application for a new set of TwiML instructions.
  12 +
  13 +For example, when someone calls your Twilio-powered phone number, Twilio looks up the voice URL of the web application you've previously configured for that phone number and makes a request to the server, providing information about who called and asking the web server what to do on that call. Your web app can then respond with a set of TwiML instructions that begin an interactive dialog between Twilio and your web server.
  14 +
  15 +How Twilio Interacts with Your Application
  16 +---------------------------------------------
  17 +When a new phone call starts or there is a user input e.g., a key press or a Dial ends, Twilio makes an HTTP GET or POST to your web server (as specified by your app). If you use HTTP POST, Twilio passes parameters as form-encoded variables in the body of the POST. If you use HTTP GET, parameters are passed in the URL query string.
  18 +
  19 +Let's look at a real example.
13 quickstart/twiml/hello-monkey-1.rst
Source Rendered
... ... @@ -0,0 +1,13 @@
  1 +================================
  2 +Hello Monkey, v1.1
  3 +================================
  4 +
  5 +Ok, that was fun. Seriously, it was. But let's raise the stakes a bit. When someone calls, we are going to try to greet the caller by name:
  6 +
  7 +.. literalinclude:: /code/quickstart/twiml/1.1/hello-monkey.php
  8 + :language: php
  9 +
  10 +In this example, the code inspects the From parameter passed by Twilio in the request to get the Caller ID of the caller. We then check to see if the caller is known looking up the number in the **$people** array to extract their name. We then Say their name or the word 'Monkey' if their Caller ID isn't known.
  11 +
  12 +If you add your phone number and name to the **$people** array you can listen to Twilio greet you by name. Note that the phone numbers in the $people array have +1 prepended to them. '1' is the international country code for the US and Canada and the '+' formats the number in `E.164 <http://en.wikipedia.org/wiki/E.164>`_ format which is used by Twilio when passing you phone numbers.Let's walk through creating your first application, Hello Monkey. We'll use PHP to construct this example, but almost any web development language could be used.
  13 +
12 quickstart/twiml/hello-monkey-2.rst
Source Rendered
... ... @@ -0,0 +1,12 @@
  1 +================================
  2 +Hello Monkey, v1.2
  3 +================================
  4 +
  5 +That's nice, now let's play the sound of a nice monkey howl for the caller after we greet them by name.
  6 +
  7 +.. literalinclude:: /code/quickstart/twiml/1.2/hello-monkey.php
  8 + :language: php
  9 +
  10 +This example uses the <Play> verb to fetch and play an MP3 file to the caller.
  11 +
  12 +A recorded monkey howl is great, but our callers want more. Let's give them the option to talk to a real primate.
31 quickstart/twiml/hello-monkey-3.rst
Source Rendered
... ... @@ -0,0 +1,31 @@
  1 +================================
  2 +Hello Monkey, v1.3
  3 +================================
  4 +
  5 +Hoot. Now, let's also ask the caller if she wants to talk to a real monkey. If she does, connect her to Koko, the famous Gorilla, whose phone number we happen to know is 310-555-1212 :)
  6 +
  7 +.. literalinclude:: /code/quickstart/twiml/1.3/hello-monkey.php
  8 + :language: php
  9 +
  10 +On line 24 we ask the caller to press a key to talk to a monkey or any other key to replay the menu.
  11 +
  12 +Notice how the <Say> block is nested inside a <Gather> block which starts on line 23.
  13 +
  14 +When Twilio sees a <Gather> block it starts looking for input from the caller's key pad. Because the <Say> is nested inside the <Gather>, Twilio will detect if caller presses a key even if the key is pressed while the <Say> is still running.
  15 +
  16 +When the caller presses a key, the pressed key is POSTed to the URL specified by the 'action' handler attribute of the <Gather> verb. In this case, the URL is hello-monkey-handle-key.php.
  17 +
  18 +.. literalinclude:: /code/quickstart/twiml/1.3/hello-monkey-handle-key.php
  19 + :language: php
  20 +
  21 +The keys pressed by the caller are transferred to the action handler as the value of the Digits parameter. In this case, the POST HTTP method is used with the <Gather> block so the value is sent as as url-encoded POST parameter. PHP has a nice feature, the '$_REQUEST' array, that lets you grab the values of request parameters regardless of the request method type. This allows us to simulate the Twilio Digits request and test our response handler using HTTP GET, which is easier to use. For example, putting the following URL into your web browser simulates the caller pressing the digit '1':
  22 +
  23 + ``http://demo.twilio.com/hellomonkey/1.3/hello-monkey-handle-key.php?Digits=1``