Learn how to leverage the Twilio API and TwiML to conduct automated phone surveys.Start Tutorial
Have you ever wondered how to create an automated survey that can be answered over phone or SMS?
This tutorial will show how to do it using Twilio API.
The end user calls or sends an SMS to the survey's phone number.
Twilio gets the call or text and makes an HTTP request to your application asking for instructions on how to respond.
After each question, Twilio makes another request to your server with the user's input, which your application stores on its database.
After storing the answer, our server will instruct Twilio to
the user to the next question or finish the survey.
In order to perform automated surveys we first need to have questions on it. For your convenience, the application's repository already includes one survey that can be loaded into the database. You can take a look at the Readme File for detailed instructions.
You can modify the questions from the survey by editing the bear_survey.json file located in the root of the repository and re-running the app.
It is helpful to visualize your interaction with a user during a survey as a loop. The chart below shows how that interaction will be handled. (click to enlarge):
The user can answer a question for your survey over the phone using either their phone's keypad or by voice. After each interaction, Twilio will make an HTTP request to your web application with either the string of keys the user pressed or a URL to a recording of their voice input.
For SMS surveys the user will answer questions just by replying with another SMS to the Twilio number that sent the question.
It's up to the application to process, store and respond to the user's input.
Let's dive into this flow to see how it actually works.
To initiate the interview process, we need to configure one of our Twilio numbers to send our web application an HTTP request when we get an incoming call or text.
Click on one of your numbers and configure Voice and Message URLs that point to your server.
In our code, the routes are
Right after receiving a call or an SMS, Twilio will send a request to the URL specified on the number's configuration
/voice/connect for calls and
/sms/connect for sms).
Each of these endpoints will receive the request and return
a welcome message to the user. When users call the Twilio number
our application will use the
Say verb. For users that respond via SMS, the
application will use a
Message Verb. It will also include a
Redirect verb to the question's endpoint to continue with the survey flow.
After Hearing the welcome message, the user will be redirected to the first question.
Each type of question will produce different instructions on how to proceed.
If the question is of "numeric" or "yes-no" kind then we use the
verb. However, if we expect the user to record an answer we use the
verb. Both verbs take an
action attribute and a
Twilio will use both attributes to define our response's endpoint that will be used as callback. That endpoint will be responsible to receive and store the caller's answer.
During the Record verb creation, we also ask for a Transcription. Twilio will process the recording and extract useful text. When transcription is done it will make a request to our response's endpoint.
To ask questions over SMS we just need to use the
TwiML verb. When the user starts a new survey, he/she will receive a welcome message and
also a message with the first question.
When the user is interacting over SMS we don't have something like an ongoing call session with a well defined state.
It becomes harder to know if an SMS is answering question 2 or 20, since all requests will be fired to
/sms/connect main endpoint.
To solve that, we can use Twilio Cookies
to keep track of what question is being answered at the moment.
After the user has finished inputting voice commands or pressing keys, Twilio just sends a request telling what happened and asking for further instructions.
At this point, we need to recover data from Twilio's request parameters and store them.
Recovered parameters vary according to the questions, they can be:
Bodycontains the text message from answer over SMS.
Digitscontains the keys pressed for a numeric question.
RecodingUrlcontains the URL for listening a recorded message.
TranscriptionTextcontains the result of a recording transcription.
Finally we redirect to our Question controller, which will ask the next question on the loop.
This is done on
Now, let's see how to visualize the results.
You can access the survey results in the application's root route.
The results will be shown grouped by survey results. For recorded answers you can click on a playback icon to listen to the user's answer.
Also, the transcribed answer will be shown when available for recorded voice answers.
If you have configured one of your Twilio numbers to the application built in this tutorial you should be able to take the survey and see the results under the 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.
Thanks for checking this tutorial out! If you have any feedback to share with us, we'd love to hear it. Contact the Twilio Developer Education Team to let us know what you think.