The <Pause> verb waits silently for a specified number of seconds, or one second by default. It's simply used like this, with the length of time for waiting specified in the length attribute:

<Pause length="5" />

This verb is a very simple one. It is used from a queue's waitUrl (see the preceding section), and it lets us remove the caller from the queue and run some alternative TwiML instead.

As a crude example, let's add a caller to our support queue but add a we're now closed-style message after our <Enqueue> verb:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Say>Please wait and one of our team member will be with you shortly.</Say>
  <Enqueue waitUrl="waiting.php">Support</Enqueue>
  <Say>We're now closed – please call back tomorrow.</Say>
  <Hangup />
</Response>

Once the caller is joined to the Support queue, the execution of our TwiML document will be stopped and Twilio will loop over the TwiML in waiting.php, waiting for the call to be dequeued instead.

Only if and when the caller leaves this queue will we continue to execute our TwiML so that the <Say> block gets run.

We might want to remove callers from the queue at 6 p.m. when our customer support lines close. Lets write some TwiML in waiting.php with the help of a little PHP. To do this, take a look at the following code:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <?php if (intval(date("H")) >= 18) { ?><Leave />
  <?php } else { ?>
  <Play>http://com.twilio.sounds.music.s3.amazonaws.com/ClockworkWaltz.mp3</Play>
    <Say>You are currently in position <?php echo $_POST['QueuePosition']; ?> in the queue.</Say>
  <?php } ?>
</Response>

Here, we check whether the hour on a 24-hour clock is more than 18 (that is, 6 p.m.). If it is, we leave the queue (so that our final bit of TwiML in the previous snippet gets run), or else, we play some hold music and then announce the caller's current position. waiting.php will simply be requested again and again while a caller queues.

The <Number> noun lets you call a traditional phone number; nest one or more these under your <Dial> verb in order to call it.

One of the most interesting features here is that you can actually try multiple phone numbers. For example, imagine a situation, such as in the following code sample, where you want to try multiple numbers for your customer support phone line:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Say>Please wait while we connect you to one of the customer support team. Please note that calls will be recorded.</Say>
  <Dial record="record-from-answer" action="recording.php">
    <Number>+441290211999</Number>
    <Number>+441290211998</Number>
  </Dial>
  <!—Let's hang up when the dialled call is over --!>
  <Hangup />
</Response>

With this TwiML, Twilio will attempt to call both of the numbers. As soon as someone picks up, it'll stop trying the other.

The <Number> noun also provides some advanced functionality that lets you control what happens when the dialed party has answered the call, such as the sendDigits and url attributes:

Let's go through examples of both of those options.

First, we'll look at url; we'll start with our TwiML for the actually incoming call, just like we did previously:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Say>Please wait while we connect you to one of customer support team. Please note that calls will be recorded.</Say>
  <Dial record="record-from-answer" action="recording.php">
    <Number url="intro.php">+441290211999</Number>
    <Number url="intro.php">+441290211998</Number>
  </Dial>
  <!—Let's hang up when the dialed call is over --!>
  <Hangup />
</Response>

A intro.php file will be played to our customer support agents once they've picked up the call but before the call is actually connected through, letting them reject the call if it's inconvenient:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Gather timeout="5" action="digits.php" numDigits="1">
    <Say>This is an incoming customer support call – press any key on your phone in the next 5 seconds to accept the call, or otherwise hang up.</Say>
  </Gather>
  <Hangup />
</Response>

We'll play a message to the customer support agent and then wait for their input. If they press a digit at the prompt, we'll move on to the digits.php TwiML file. Otherwise, the call will be rejected and thus hung up, leaving Twilio to keep trying the other number in the <Dial> block.

Lastly, we'll need to create a digits.php file to deal with the called party's input:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Say>Thanks – you'll now be connected.</Say>
</Response>

The agent will be played a quick message, and then Twilio will actually connect the dialed party to the original call.

The sendDigits attribute is useful when we want to dial some digits once the called party picks up. This is useful for automating other phone menus and services, or for dialing an extension, as follows:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial record="record-from-answer" action="recording.php">
    <Number sendDigits="wwwww100">+441290211999</Number>
  </Dial>
</Response>

Here, we'll dial our number, but when they pick up, we'll wait for 2.5 seconds (each w character represents a half-second pause) and then dial 100, our imaginary extension.

Apart from dialing through to physical phones, we can also make calls on Twilio over Session Initiation Protocol (SIP). SIP is a standard, or perhaps the standard for Internet telephony, connecting together a range of phone networks.

The <Sip> verb effectively acts as a cheaper complement to making calls over PSTN using the <Number> noun at less than half the cost of calling a US phone number.

We'd dial a SIP URI (which identifies a particular client on a particular SIP server) as follows:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial record="record-from-answer" action="recording.php">
    <Sip>sip:[email protected]</Sip>
  </Dial>
</Response>

The <Sip> verb works with all of the various <Dial> verb options we've seen previously for calls using the <Number> noun. For example, we can ask to record calls or set a timeout from the <Dial> verb.

The URL attribute is also available on the <Sip> noun and works in exactly the same way as it works for <Number>, letting us add call screening and other such features with ease.

There are lots of niche options available to you when you're working with SIP in Twilio that aren't worth covering in this book; examples include, forcing the TCP or UDP transport for the connection and sending custom headers with the SIP request.

<Sip username="twilio" password="twiliorocks">sip:[email protected]</Sip>

Twilio's <Client> allows you to include voice capabilities within a web page or native app. This means that people can make and take calls from their own devices without using the legacy telephony networks or complicated SIP setups.

This makes it easy to build powerful telephony solutions, for example, browser-to-browser calling within a web application. However, part of the magic is that it's fully connected to the rest of Twilio's platform.

This means that we can set up Twilio Client in a browser and then take incoming calls to it over a traditional phone number. Twilio Client uses TwiML in exactly the same ways as we've already seen for both incoming and outbound calls.

By way of an example, you can imagine a phone conferencing service that uses this to enhance its functionality. Attendees and presenters on a call will be able to join in either through their browser using a headset, from their mobile phone via a custom app, or from any phone of their choice on a local phone number. All of this can be run through Twilio.

Each individual connected to Twilio with Twilio Client will have their own client identifier. It's unique within the scope of our Twilio account and is what we use to connect calls to a particular user. Connecting to a particular client within the context of a <Dial> verb is very simple indeed:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial record="record-from-answer" action="recording.php">
    <Client>the-client-identifier</Client>
  </Dial>
</Response>

Using Twilio, we can easily build our own custom phone conferencing tool to rival commercial alternatives.

Doing this is a great option as Twilio's APIs give you the power to perform all sorts of integrations and customizations. The <Conference> verb is really quite a complex noun as it allows you to wield almost all of the features you'd see in professional conferencing tools from your own code.

The <Conference> noun creates or adds a caller to a conference room of your choice. Simply use the noun and place the name of a room inside it. You don't have to create it ahead of time:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial>
    <Conference>Monday Morning Meeting</Conference>
  </Dial>
</Response>

Let's quickly cover the different options—there are a lot of them—and then dive into an example:

Let's build a basic conference where we'll have a passcode for presenters and a passcode for attendees. First, we'll create a TwiML file to handle incoming calls:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Gather timeout="10" action="digits.php" numDigits="6">
    <Say>Enter your six digit pass code to join the conference.<Say>
  </Gather>
  <Hangup />
</Response>

This file will play a message and wait for 10 seconds for the caller to enter a six-digit code.

If they fail to enter the code, we'll hang up. In the real world, we'd probably want to do something nicer than this. Otherwise, we'll make a POST request to digits.php with the Digits parameter containing what was entered on the keypad. Let's create the digits.php file:

<?php
$presenterCode = "123456";
$attendeeCode = "654321";
?>
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<?php if ($_POST['Digits'] == $presenterCode) { ?>
  <Say>Thank you, presenter. We'll connect you now.</Say>
  <Dial>
    <Conference endConferenceOnExit ="true">Room</Conference>
  </Dial>
<?php } else if ($_POST['Digits'] == $attendeeCode) { ?>
  <Say>Thank you – we'll add you to the conference now. You'll hear hold music until a presenter joins.</Say>
  <Dial>
    <Conference startConferenceOnEnter="false">Room</Conference>
  </Dial>
<?php } else { ?>
  <Say>Sorry, that conference doesn't exist. Goodbye.</Say>
  <Hangup />
<?php } ?>
</Response>

Here, we've got a fair bit of logic to go through:

From this, it should be evident that Twilio's conferencing is really quite powerful, especially when you use the various customizable options to deal with things such as recordings, moderation, and the waiting experience.

This final noun for <Dial> allows us to pull a call out of a queue to which we've added a call (that is, caller) with the <Enqueue> verb.

As with many of the previous nouns, we can specify a url attribute, pointing to a TwiML that will be played to the queued caller before they're put through to the person being dialed in.

Let's try it for ourselves:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial>
    <Queue url="alert.php">Support</Queue>
  </Dial>
</Response>

When this TwiML is executed, the caller will be connected to the next caller in the support queue after the person waiting in the queue has gone through the TwiML in alert.php.

Let's create an example alert.php file now, where we'll tell the person that their call will be recorded:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Say>Thank you for waiting – you're about to be connected to one of our support team members. All calls are recorded.</Say>
</Response>

The <Hangup> verb ends a call. It's just used on its own as a self-closing tag with no nouns or attributes. In the next example, we say goodbye and then hang up:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Say>Goodbye.</Say>
  <Hangup />
</Response>

The <Redirect> verb moves from executing the current TwiML to a different file on a different URL immediately, ignoring the rest of the TwiML in the current file.

Inside the <Redirect> verb, we provide the absolute URL or relative path of the TwiML file to be executed. We can also set the method attribute to GET; it defaults to POST:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Redirect method="GET">../other_twiml.php</Redirect>
</Response>

Nothing can be nested within the the <Redirect> verb, and any verbs after it are ignored as the redirect takes place right away.

The <Reject> verb, if placed as the very first verb in an incoming call, will prevent the call from being answered and will incur no cost whatsoever.

If placed elsewhere in the call, the call will hang up but we will still be charged up to that point.

The caller will hear an engaged or busy tone that we can customize through the reason attribute. We set the reason to rejected in order to play an engaged tone (which is the default) or set it to busy for a busy tone.

We can use this if we want to screen out certain types of calls. For example, imagine a situation where we're being spammed by a particular number:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <?php if ($_POST['From'] == "+447969123456") { ?>
    <Reject reason="busy" />
  <?php } else { ?>
    <Redirect method="GET">../other_twiml.php</Redirect>
  <?php } ?>
</Response>