PHP Tutorial
View Full Screen
Automated surveys with Laravel

Learn how to leverage the Twilio API and TwiML to conduct automated phone surveys.

Start Tutorial

About this application

This Laravel 5 sample application demonstrates using Twilio and TwiML to deliver a survey that can be completed via voice call. The survey actually works via SMS text messages, too, but we're going to focus on the looping logic necessary to conduct an interview over the phone.

In this tutorial, we'll highlight the code that interacts with Twilio and in turn makes the application tick. To run this sample app yourself, download the code and follow the instructions on GitHub.

Let's get started! Click the right arrow above to move to the next step of the tutorial.

See Also:

Configure the application

In order to store the Survey responses will need a PostgreSQL database. Rename .env.example to .env to configure access to your local database.

Now that the database is configured we can load a survey into it.

See Also:

Create a survey

In order to perform automated surveys we first need to have some questions to ask. For your convenience, the application's repository already includes one survey that can be loaded into the database using the included survey:loadartisan command.

We want users to take our survey, so next we are going implement the interaction of the caller with the application.

See Also:

Respond to a Phone Call

Whenever one of your Twilio phone numbers receives a call, Twilio will make an HTTP request to the voice URL configured under it.

For this application Twilio should be configured to request the application's /first_survey endpoint. Since our app only handles one survey, the endpoint will reply with a redirect to the location of the first survey it finds. The URL for this survey should look something like /survey/<some_id>. Twilio is a well-behaved HTTP client and will follow the redirect and thus make another request.

Next we will handle the request made after the redirect.

See Also:

Welcome the caller to the survey

Before we get started with the survey, we want to welcome the user. We will immediately serve up the first question by using the <Say> verb followed by the <Redirect> verb. The contents of the <Redirect> tag should be the URL of the survey's first question.

Now that we have welcomed the user it's time to start asking questions.

See Also:

Ask the caller a question

Asking the question is pretty straightforward, but we also need to record the response.

Recording the answer is slightly more involved. If the question is of kind "voice" then we use the <Record> verb. However, if we expect dialpad input we use the the <Gather> verb. Both verbs take an action attribute and a method attribute. Twilio's client will use both attributes to make a request we can use to store the caller's answer to the question.

The action URL will be /question/<question_id>/question_response for both TwiML verbs. We also include a ?Kind=<question kind> URL parameter so we can identify the question kind before we store it in the database.

Now that the caller has answered our question we want to store her answer.

See Also:

Store a question's answer

When the caller has finished entering her response, Twilio will make a request to this controller including all the call parameters we will need . For this sample application we will store the RecordingUrl or Digits parameter for voice and yes-no/numeric answers accordingly. For this sample we will also save the CallSid so we can uniquely identify a call.

Most surveys include more than a single question so we must now redirect the user to the next question in this survey.

Redirect the user to the next question

Now we need to locate the next question. This is rather straightfoward since we have the same request as in the previous step therefore we have access to the same information. We merely need to find the question after the current one and reply with a redirect with the next question's URL as the target.

However, we need to handle the case where there's no next question. In this case we simply say "good-bye" and hangup.

The application's users might want to see the answers to their survey so we're implementing that next.

See Also:

Display the survey results

For this route we simply query the database through an Eloquent query scope and then display the information within a Blade template. We display a panel for every individual call. It's worth mentioning we also redirect the application's root route to this route.

See Also:

Where to next?

It's done! If you have configured one of your voice-enable Twilio numbers to the application built in this tutorial you should be able to take the survey and see the results under root route of the application. We hope you found this sample application useful. If you're a PHP developer working with Twilio, you might enjoy these other tutorials:

Click to Call
Put a button on your web page that connects visitors to live support or sales people via telephone.

Two-Factor Authentication Improve the security of Laravel's built-in login functionality by adding two-factor authentication via text message.

Did this help?

As always, we'd love to hear what you thought of this tutorial! Shoot us a note to let us know what you liked and what we can do better. See you next time!

    Exit Full Screen