PHP Tutorial
View Full Screen
Click-to-Call

Click-to-call enables your company to convert web traffic into phone calls with the click of a button. Learn how to implement it in minutes.

Start Tutorial

How It Works

Let's go over the steps necessary to implement click-to-call in our application:

Click-to-call Diagram

  1. A website visitor wants to connect to your organization. She submits a web form with her phone number to receive a call connecting her to your sales or support team.

  2. Your web application receives the form submission. An HTTP request is initiated from your application to Twilio to initiate an outbound call.

  3. Twilio receives the request and initiates a call to the user's phone number.

  4. User receives the call.

  5. After the call connects, Twilio asks our application for TwiML instructions. Our TwiML instructs Twilio to connect the user to our sales or support teams.

What We Will Learn

This How-To demonstrates initializing a call using the Twilio REST API and creating TwiML call logic using the Say and Dial verbs.

Sound like a plan? Let's get started!

Our Laravel Application

In this example, we're using the Laravel framework for PHP. If you're new to using Laravel, you might want to check out this post on our developer blog.

For this application, all of our server-side logic will live in routes.php. We will only need three routes, with the following jobs:

  • display the home page
  • handle the AJAX form submission from our UI
  • render TwiML instructions for an outbound call to our user

We also have a PHP file in the views directory of the sample application that renders a simple HTML form for accepting a user's phone number, and a bit of JavaScript to help drive the UI.

But before we can do any of that fun stuff, we need to configure our application with a Twilio number we can use to make outbound calls, plus our Twilio account credentials. Let's see how we might do that in a Laravel application.

Configuring our Application

Laravel's configuration systems provide conventions for where and how your application's configuration will be loaded and exposed to your application. The primary location for environment configuration is .env.php in the root directory of your Laravel application.

If you have this example code locally, open env.php, and then edit this file with the appropriate values for your application. Your account credentials can be found on your dashboard:

  • TWILIO_ACCOUNT_SID : Replace XXX with your account SID - this is like your username for the Twilio API
  • TWILIO_AUTH_TOKEN : Replace YYY with your auth token - this is like your password for the Twilio API
  • TWILIO_NUMBER : Replace +16128675309 with a Twilio number from your account

As constituted, this configuration file will pull in system environment variables in a fashion suited for deployment on Heroku, or any other environment that supports system environment variables for configuration. Okay, now that our app is configured, let's move on to the code. We'll begin by showing how we render the home page for this application.

Rendering the Home Page

Our first route simply responds to an HTTP GET request to the root URL of our application. It uses Laravel's View system to render a plain PHP template that will contain the HTML for our user interface.

The Home Page Template

This file contains the HTML markup for our simple UI. It contains a few link tags to pull in CSS from Twitter Bootstrap to make our page look a little nicer, plus some script tags to pull in our application logic, jQuery, and a jQuery plugin for styling phone number input fields.

In the highlighted section, we can see that we set up a form to accept the user's phone number. The form doesn't have an action or method defined in markup, since we plan on submitting the form via JavaScript.

Let's look at the JavaScript we use to submit the form.

Creating a Better Phone Input

Immediately on the document ready event, we use a jQuery plugin to create an input field that will validate phone numbers and help insert proper country codes for the phone number our user enters.

This step is not strictly necessary, but validating a user's phone number input on the client side is generally a good idea.

AJAX Form Submit

Here, we are capturing the form's submit event, and sending an AJAX POST request to our Laravel application.

On line 14, we prevent the browser from following its default submit behavior. On line 17, we use jQuery's AJAX function to send an HTTP POST request to /call on our server, containing the phone number the user entered as a form-encoded POST parameter. When the request completes, we simply display an alert containing the message we get back, as JSON, from the server.

That's pretty much it for the front-end - let's take a look at the PHP code that contains the logic behind the /call route.

Outbound Call Route

Back on the server, we define a route that handles HTTP POST requests to the /call URL. This is the PHP code that we're calling via our AJAX request in the browser.

Create an Authenticated Twilio REST API Client

The Twilio helper library for PHP provides a simple interface for Twilio's REST API that takes care of making HTTP requests, authentication, and content negotiation. Here, we create a new client using our account SID and auth token configured in .env.php.

Place the Outbound Call

Here, we use the REST API client make the phone call to our application's user. As inputs, we provide a Twilio number we control in our account, the user's phone number which we got from the AJAX form submission, and a URL to our Internet-accessible Laravel application.

The URL parameter is another route in our Laravel app that Twilio will request once our outbound call is connected. This route should return XML in a format we call TwiML - TwiML tells Twilio how to drive an outbound call, or respond to an incoming call or message.

Let's check out our TwiML generating route now.

TwiML Route

Here, we define a route called /outbound that will contain TwiML instructions for our call. Ultimately, as you can see on lines 63-65, we will be returning XML as a response from this route.

The Twilio library, however, provides us a helper class that might make building TwiML responses a bit easier. Let's take a look at how to create and use one.

Using the TwiML Builder

The TwiML Builder Class allows us to programmatically generate TwiML responses that we can use in our route. Here, we create a TwiML response object, and then use it to generate a Say tag in the TwiML response we send back.

On the next line that's commented out, you can see how you would use the Dial tag to forward the call to another number. This is a common click-to-call use case - your server-side code might at this point load a customer's data from a CMS, and maybe intelligently route the call to the right sales rep or support person.

All Done

Congrats! You just learned how to build a working Click-to-Call solution. To improve upon this you could add two-factor authentication to your app, or create an interactive survey to follow-up with your customer.

Thanks for checking out this tutorial! If you have any feedback to share with us, we'd love to hear it. Tweet @twilio to let us know what you think.

    Exit Full Screen