[Summary view] [Print] [Text view]

   1  .. _usage-twiml:
   2  
   3  ==============
   4  TwiML Creation
   5  ==============
   6  
   7  TwiML creation begins with the :class:`Services_Twilio_Twiml` verb. Each
   8  succesive verb is created by calling various methods on the response, such as
   9  :meth:`say` or :meth:`play`. These methods return the verbs they create to ease
  10  the creation of nested TwiML.
  11  
  12  .. code-block:: php
  13  
  14      $response = new Services_Twilio_Twiml;
  15      $response->say('Hello');
  16      print $response;
  17  
  18  .. code-block:: xml
  19  
  20      <?xml version="1.0" encoding="UTF-8"?>
  21      <Response>
  22        <Say>Hello</Say>
  23      <Response>
  24  
  25  Primary Verbs
  26  =============
  27  
  28  Response
  29  --------
  30  
  31  All TwiML starts with the `<Response>` verb. The following code creates an empty response.
  32  
  33  .. code-block:: php
  34  
  35      $response = new Services_Twilio_Twiml;
  36      print $response;
  37  
  38  .. code-block:: xml
  39  
  40      <?xml version="1.0" encoding="UTF-8"?>
  41      <Response></Response>
  42  
  43  Say
  44  ---
  45  
  46  .. code-block:: php
  47  
  48      $response = new Services_Twilio_Twiml;
  49      $response->say("Hello World");
  50      print $response;
  51  
  52  .. code-block:: xml
  53  
  54      <?xml version="1.0" encoding="UTF-8"?>
  55      <Response>
  56        <Say>Hello World</Say>
  57      </Response>
  58  
  59  Play
  60  ----
  61  
  62  .. code-block:: php
  63  
  64      $response = new Services_Twilio_Twiml;
  65      $response->play("https://api.twilio.com/cowbell.mp3", array('loop' => 5));
  66      print $response;
  67  
  68  .. code-block:: xml
  69  
  70      <?xml version="1.0" encoding="UTF-8"?>
  71      <Response>
  72        <Play loop="5">https://api.twilio.com/cowbell.mp3</Play>
  73      <Response>
  74  
  75  Gather
  76  ------
  77  
  78  .. code-block:: php
  79  
  80      $response = new Services_Twilio_Twiml;
  81      $gather = $response->gather(array('numDigits' => 5));
  82      $gather->say("Hello Caller");
  83      print $response;
  84  
  85  .. code-block:: xml
  86  
  87      <?xml version="1.0" encoding="UTF-8"?>
  88      <Response>
  89        <Gather numDigits="5">
  90          <Say>Hello Caller</Say>
  91        </Gather>
  92      <Response>
  93  
  94  Record
  95  ------
  96  
  97  .. code-block:: php
  98  
  99      $response = new Services_Twilio_Twiml;
 100      $response->record(array(
 101        'action' => 'http://foo.com/path/to/redirect',
 102        'maxLength' => 20
 103      ));
 104      print $response;
 105      
 106  .. code-block:: xml
 107  
 108      <?xml version="1.0" encoding="UTF-8"?>
 109      <Response>
 110        <Record action="http://foo.com/path/to/redirect" maxLength="20"/>
 111      </Response>
 112  
 113  Message
 114  -------
 115  
 116  .. code-block:: php
 117  
 118      $response = new Services_Twilio_Twiml;
 119      $response->message('Hello World', array(
 120        'to' => '+14150001111',
 121        'from' => '+14152223333'
 122      ));
 123      print $response;
 124  
 125  .. code-block:: xml
 126  
 127      <?xml version="1.0" encoding="UTF-8"?>
 128      <Response>
 129        <Message to="+14150001111" from="+14152223333">Hello World</Message>
 130      </Response>
 131  
 132  Dial
 133  ----
 134  
 135  .. code-block:: php
 136  
 137      $response = new Services_Twilio_Twiml;
 138      $response->dial('+14150001111', array(
 139        'callerId' => '+14152223333'
 140      ));
 141      print $response;
 142  
 143  .. code-block:: xml
 144  
 145      <?xml version="1.0" encoding="UTF-8"?>
 146      <Response>
 147        <Dial callerId="+14152223333">+14150001111</Dial>
 148      </Response>
 149  
 150  Number
 151  ~~~~~~
 152  
 153  Dial out to phone numbers easily.
 154  
 155  .. code-block:: php
 156  
 157      $response = new Services_Twilio_Twiml;
 158      $dial = $response->dial(NULL, array(
 159        'callerId' => '+14152223333'
 160      ));
 161      $dial->number('+14151112222', array(
 162        'sendDigits' => '2'
 163      ));
 164      print $response;
 165  
 166  .. code-block:: xml
 167  
 168      <?xml version="1.0" encoding="UTF-8"?>
 169      <Response>
 170        <Dial callerId="+14152223333">
 171          <Number sendDigits="2">+14151112222</Number>
 172        </Dial>
 173      </Response>
 174  
 175  Client
 176  ~~~~~~
 177  
 178  .. code-block:: php
 179  
 180      $response = new Services_Twilio_Twiml;
 181      $dial = $response->dial(NULL, array(
 182        'callerId' => '+14152223333'
 183      ));
 184      $dial->client('client-id');
 185      print $response;
 186  
 187  .. code-block:: xml
 188  
 189      <?xml version="1.0" encoding="UTF-8"?>
 190      <Response>
 191        <Dial callerId="+14152223333">
 192          <Client>client-id</Client>
 193        </Dial>
 194      </Response>
 195  
 196  Conference
 197  ~~~~~~~~~~
 198  
 199  .. code-block:: php
 200  
 201      require("Services/Twilio.php");
 202      $response = new Services_Twilio_Twiml;
 203      $dial = $response->dial();
 204      $dial->conference('Customer Waiting Room', array(
 205          "startConferenceOnEnter" => "true",
 206          "muted" => "true",
 207          "beep" => "false",
 208      ));
 209      print $response;
 210  
 211  .. code-block:: xml
 212  
 213      <?xml version="1.0" encoding="UTF-8"?>
 214      <Response>
 215          <Dial>
 216              <Conference startConferenceOnEnter="true" muted="true" beep="false">
 217                  Customer Waiting Room
 218              </Conference>
 219          </Dial>
 220      </Response>
 221  
 222  Sip
 223  ~~~
 224  
 225  To dial out to a Sip number, put the Sip address in the `sip()` method call.
 226  
 227  .. code-block:: php
 228  
 229      require("Services/Twilio.php");
 230      $response = new Services_Twilio_Twiml;
 231      $dial = $response->dial();
 232      $sip = $dial->sip();
 233      $sip->uri('[email protected]?X-Header-1=value1&X-Header-2=value2', array(
 234          "username" => "admin",
 235          "password" => "1234",
 236      ));
 237      print $response;
 238  
 239  .. code-block:: xml
 240  
 241      <?xml version="1.0" encoding="UTF‐8"?>
 242      <Response>
 243          <Dial>
 244              <Sip>
 245                  <Uri username='admin' password='1234'>
 246                      [email protected]?X-Header-1=value1&X-Header-2=value2
 247                  </Uri>
 248              </Sip>
 249          </Dial>
 250      </Response>
 251  
 252  
 253  Secondary Verbs
 254  ===============
 255  
 256  Hangup
 257  ------
 258  
 259  .. code-block:: php
 260  
 261      $response = new Services_Twilio_Twiml;
 262      $response->hangup();
 263      print $response;
 264      
 265  .. code-block:: xml
 266  
 267      <?xml version="1.0" encoding="UTF-8"?>
 268      <Response>
 269        <Hangup />
 270      </Response>
 271  
 272  Redirect
 273  --------
 274  
 275  .. code-block:: php
 276  
 277      $response = new Services_Twilio_Twiml;
 278      $response->redirect('http://twimlets.com/[email protected]');
 279      print $response;
 280      
 281  .. code-block:: xml
 282  
 283      <?xml version="1.0" encoding="UTF-8"?>
 284      <Response>
 285        <Redirect>http://twimlets.com/[email protected]</Redirect>
 286      </Response>
 287  
 288  
 289  Reject
 290  ------
 291  
 292  .. code-block:: php
 293  
 294      $response = new Services_Twilio_Twiml;
 295      $response->reject(array(
 296        'reason' => 'busy'
 297      ));
 298      print $response;
 299      
 300  .. code-block:: xml
 301  
 302      <?xml version="1.0" encoding="UTF-8"?>
 303      <Response>
 304        <Reject reason="busy" />
 305      </Response>
 306  
 307  
 308  Pause
 309  -----
 310  
 311  .. code-block:: php
 312  
 313      $response = new Services_Twilio_Twiml;
 314      $response->say('Hello');
 315      $response->pause("");
 316      $response->say('World');
 317      print $response;
 318  
 319  .. code-block:: xml
 320  
 321      <?xml version="1.0" encoding="UTF-8"?>
 322      <Response>
 323        <Say>Hello</Say>
 324        <Pause />
 325        <Say>World</Say>
 326      </Response>
 327  
 328  Enqueue
 329  -------
 330  
 331  .. code-block:: php
 332  
 333      $response = new Services_Twilio_Twiml;
 334      $response->say("You're being added to the queue.");
 335      $response->enqueue('queue-name');
 336      print $response;
 337  
 338  .. code-block:: xml
 339  
 340      <?xml version="1.0" encoding="UTF-8"?>
 341      <Response>
 342          <Say>You're being added to the queue.</Say>
 343          <Enqueue>queue-name</Enqueue>
 344      </Response>
 345  
 346  The verb methods (outlined in the complete reference) take the body (only text)
 347  of the verb as the first argument. All attributes are keyword arguments.