The twiml interface

The TwiML Interface

Basics

The Twiml object is simply a container for all the various verbs that TwiML supports. As well, the Twiml object contains a Response object, which is used to construct your TwiML responses by adding the verbs you'd like and then sending them back to Twilio.

var Twiml = require('twilio').Twiml;

The Response object, as well as each of TwiML's verbs, is represented and documented below.

The Response object

Overview

The Response object handles constructing, marshalling, and sending TwiML responses to Twilio.

If you're using The High-Level Interface, you'll never have to instantiate a Response object yourself. Instead, you'll receive a Response object, ready to append() to, from any of the Events that are issued from the client.

If you want to use The Lower-Level Interface, you may instantiate a Response object. In this case, it accepts no arguments.

Methods

append(node)

The append method appends a new TwiML element to the bottom of the response.

var r = new Twiml.Response();
r.append(new Twiml.Say('Hello, there! Enter your ATM card PIN');
r.append(new Twiml.Gather());

The append method is chainable. The above can be rewritten:

r.append(new Twiml.Say('Hello, there! Enter your ATM card PIN').append(new Twiml.Gather());

toString()

The toString method stringifies the TwiML response.

var r = new Twiml.Response(); r.append(new Twiml.Say('Hello, there! Enter your ATM card PIN').append(new Twiml.Gather()); console.log(r.toString());

This would output to your console:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
        <Say>
                Hello, there! Enter your ATM card PIN
        </Say>
        <Gather/>
</Response>

send()

When The High-Level Interface passes you a Response object, it has instantiated it with an HTTP response object that represents your response to Twilio. If using The High-Level Interface, call send() when you are ready to ship your constructed Response to Twilio.

The Say object

The Say object represents the TwiML element.

var s = new Twiml.Say(body, attributes);

The body argument is a required, string argument that will be the text that Twilio renders as speech to the person on the end of the line. attributes is an optional map of XML attributes for this Say element. See the Twilio Say documentation for possible attributes.

Example

console.log((new Twiml.Say('Hello', {voice: 'man', language: 'en'})).toString());

Your console would see:

<Say voice="main" lanugage="en">
    Hello
 </Say>

The Play object

The Play object represents a Twilio element.

var p = new Twiml.Play(body, attributes);

The body argument is the URL of the file you wish Twilio to play. attributes is an optional map representing XML attributes for this Play element.

Example

console.log((new Twiml.Play('http://mp3.com/', {loop: 2})).toString());

Your console would show:

<Play loop="2">
      http://mp3.com/
</Play>

The Gather object

The Gather object represents a Twilio element.