Get Started

Twilio Client Quickstart

Making Outgoing Calls

Cool, you have now used Twilio Client to call into your browser and have a conversation. Rock on!

Now, let’s make a more useful application that can actually do something by passing arbitrary data from the browser to your TwiML script. Let's say that you want the browser to dial and connect you to any phone number. That's easy to do; here's how:

  • Add a text box to the web page at hello-client-monkey.cshtml so that you can enter a phone number.
  • Pass that phone number along in the Twilio.Device.connect() call.
  • Update the hello-client-twiml.cshtml script to serve a TwiML snippet that contains a <Dial> verb with the phone number you passed in from the browser.

We grab the phone number from an HTML text box, put it in an array of parameters with the key PhoneNumber, and pass those parameters to Twilio.Device.connect() when you click the 'Call' button. Simple!

hello-client-monkey-4.cshtml
@using Twilio;
@{
    // put your Twilio API credentials here
    string accountSid = "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
    string authToken = "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy";

    // put your Twilio Application Sid here
    string appSid = "APzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz";

    var capability = new TwilioCapability(accountSid, authToken);
    capability.AllowClientOutgoing(appSid);
    capability.AllowClientIncoming("jenny");
    string token = capability.GenerateToken();
}

<!DOCTYPE html>
<html>
  <head>
    <title>Hello Client Monkey 4</title>
    <script type="text/javascript"
      src="//static.twilio.com/libs/twiliojs/1.2/twilio.min.js"></script>
    <script type="text/javascript"
      src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js">
    </script>
    <link href="http://static0.twilio.com/packages/quickstart/client.css"
      type="text/css" rel="stylesheet" />
    <script type="text/javascript">

        Twilio.Device.setup('@token');

        Twilio.Device.ready(function (device) {
            $("#log").text("Ready");
        });

        Twilio.Device.error(function (error) {
            $("#log").text("Error: " + error.message);
        });

        Twilio.Device.connect(function (conn) {
            $("#log").text("Successfully established call");
        });

        Twilio.Device.disconnect(function (conn) {
            $("#log").text("Call ended");
        });

        Twilio.Device.incoming(function (conn) {
            $("#log").text("Incoming connection from " + conn.parameters.From);
            // accept the incoming connection and start two-way audio
            conn.accept();
        });

        function call() {
            // get the phone number to connect the call to
            params = { "PhoneNumber": $("#number").val() };
            Twilio.Device.connect(params);
        }

        function hangup() {
            Twilio.Device.disconnectAll();
        }
    </script>
  </head>
  <body>
    <button class="call" onclick="call();">
      Call
    </button>

    <button class="hangup" onclick="hangup();">
      Hangup
    </button>

    <input type="text" id="number" name="number"
      placeholder="Enter a phone number to call"/>

    <div id="log">Loading pigeons...</div>
  </body>
</html>

Now, the TwiML script needs to receive the PhoneNumber parameter given to it when Twilio makes a request to the Voice URL. Let's change the hello-client-twiml.cshtml file to read the PhoneNumber parameter and insert that value into the <Dial> verb. If the PhoneNumber parameter isn't given, we can default to calling "jenny" as we did before. The complete TwiML script is shown below with the new and changed lines highlighted.

hello-client-twiml-2.cshtml
@using System.Text.RegularExpressions;
@{
    Response.ContentType = "text/xml";

    // put a phone number you've verified with Twilio to use as a caller ID number
    string callerId = "+1xxxxxxxxxx";

    // put your default Twilio Client name here, for when a phone number isn't given
    string number   = "jenny";

    // get the phone number from the page request parameters, if given
    if (Request["PhoneNumber"] != null) {
        number = Request["PhoneNumber"];
    }

    // wrap the phone number or client name in the appropriate TwiML verb
    // by checking if the number given has only digits and format symbols
    string numberOrClient;
    var m = Regex.Match(number, @"^[\d\+\-\(\) ]+$");
    if (m.Success) {
        numberOrClient = string.Format("<Number>{0}</Number>", number);
    } else {
        numberOrClient = string.Format("<Client>{0}</Client>", number);
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial callerId="@callerId">
          @Html.Raw(numberOrClient)
    </Dial>
</Response>

Once again, let's load that URL in your browser to make sure the script renders the TwiML snippet correctly. But this time, specify the PhoneNumber parameter like this: http://companyfoo.com/hello-client-twiml.cshtml?PhoneNumber=14158675309

Since we want to be able to call phone numbers or other clients, we've made the TwiML script accept either. If the PhoneNumber parameter's value is all digits (or plusses, dashes, parentheses and spaces), we'll assume it's a phone number. In that case, we put the value of the PhoneNumber parameter inside a <Number> noun. Otherwise, we'll assume it's a client, so we put the value inside a <Client> noun.

Notice that we added a `callerId` attribute to the `<Dial>` verb. To call a phone from the browser using Twilio Client you **must** specify a caller ID. Without this attribute, the call will fail and an "invalid callerId value" error will appear in your Twilio Debugger. Any of your Twilio phone numbers or verified caller IDs will work.

If you want to call a traditional telephone, you'll need to either buy a Twilio number or verify a number you already own to use as the caller ID when calling from Twilio Client. Please note that the Twilio Sandbox number will not work as a valid caller ID.

So, go ahead and load up hello-client-monkey.cshtml, enter your cell phone number in the box and press the 'Call' button. Your phone will ring and you can talk to yourself... Huzzah!

But with Twilio Client, who needs a phone? Now, it’s about time to make a call between two browsers.


Next: Making Browser-to-Browser Calls »