Rate this page:

Automated telephone surveys and notifications

With VoxImplant you can build even complex scenarios with call campaigns in minutes. A special feature called Call Lists is used for that purpose. Every record in a CSV file representing a call list is processed by a VoxEngine scenario.

The process can be divided into 4 parts:

  1. Create a CSV file with the list of phone numbers and additional data that will be passed to a scenario
  2. Create a Voximplant application with a scenario and a rule
  3. Attach a phone number rented from Voximplant
  4. Start the automated calling process

Designing CSV file structure

First of all, you need to design your CSV file. Its data will be passed to the VoxEngine scenario as a JSON string and parsed thereafter. Here is an example of a call list for sending automated notifications about a scheduled appointment:

first_name;last_name;phone_number;appointment_date
Jon;Snow;+16501234567;November 15th
Daenerys;Targaryen;+16501234568;November 16th

The CSV file contains names of the callees, their phone numbers, and appointment dates; the first string describes parameter names.

If needed, add time intervals when the call list processing will start and end every day, UTC+0 24-h format: HH:mm:ss.

Jon;Snow;+16501234567;November 15th;17:00:00;22:00:00
Daenerys;Targaryen;+16501234568;November 16th;10:00:00;15:00:00
Please note

If your balance is under 1 USD, the call list processing won't start, or it will stop immediately. Once you top up your account, the lists will launch automatically.

VoxEngine scenario

Ok, we have our CSV file design, now we can create a VoxEngine scenario that will process every string of the file, make a call, and decide if this call was successful or not depending on the result report. If we report that it wasn't successful, the CallList processor can try again after some time (that can be set in HTTP request).

Scenario code

Scenario code

Save the scenario, create a VoxImplant application and an application rule that will attach the scenario to the application. No need to change the Pattern field – it's not used when the scenario is launched via an HTTP request.

Launching automated dialing

We can launch automated dialing in 2 ways:

  1. From the control panel
  2. Via an HTTP request

Launch from the control panel

Choose the Call lists section in your application menu, create a list (automatic or manual), upload the CSV file, and launch the list by running the rule if it’s manual (automatic lists are launched immediately after creation). The call results are available in the Call lists section as well. To get them, click the three-dot menu on the needed list and choose Download.

Launch via HTTP API

API method to launch dialing is described in the documentation, let's take a look at the parameters:

  • account_name — your VoxImplant account name
  • api_key — your VoxImplant API KEY
  • rule_id — id of the application rule that has the assigned scenario
  • priority — dialing priority, if you have more than one CallList
  • max_simultaneous — maximum number of simultaneously processed records from CSV file
  • num_attempts — number of dialing attempts, a new attempt will happen in case of CallList.reportError
  • name — CallList name, useful to differentiate different CallLists from each other
  • file_content — CSV file should be sent in the request body
  • interval_seconds — time for the next attempt (in seconds)
  • encoding — CSV file encoding, should be specified if different from UTF-8
  • delimiter — CSV file columns delimiter, default is ";" The getCallListDetails request result will look similar to (if calls were connected successfully):
"appointment_date";"last_name";"phone_number";"first_name";"__end_execution_time";"__start_execution_time";"result_data";"last_attempt";"attmepts_left";"status_id";status
November 15th;Jon;16501234567;Snow;;;"{""result"":true,""duration"":27}";"2021-05-24 19:21:39";1;2;Processed
November 16th;Daenerys;16501234568;Targaryen;;;"{""result"":true,""duration"":18}";"2021-05-24 19:22:10";1;2;Processed

What about surveys?

Ok, now we know how to make telephone notifications, but what if we need to make a telephone survey? It's rather easy to change the scenario we created before to start collecting data from callee input - we will modify handleCallConnected, handleCallDisconnected, and will add a new handleToneReceived function:

Telephone survey

Telephone survey

Speech recognition

If you want the clients to pronounce the rating rather than dial it, use the ASR module responsible for speech recognition.

We need to add the module: require(Modules.ASR); and modify handlePlaybackFinished where we will send speech captured in our call to ASR: call.sendMediaTo(asr). When speech is captured (we need just one word), we stop the sending process with call.stopMediaTo(asr).

Then we use the createASR method with Phrase hints to recognize words from the specified array. The last thing we do is handle the ASREvents.Result event that is triggered when the recognition result is received from ASR. If we recognize the answer, we stop ASR and hang up, otherwise we ask the client to repeat the answer again.

Survey with speech recognition

Survey with speech recognition

Here is the result:

"last_name";"phone_number";"first_name";"__end_execution_time";"__start_execution_time";"result_data";"last_attempt";"attmepts_left";"status_id";status
Jon;16501234567;Snow;;;"{""result"":true,""duration"":27,""rating"":""four""}";"2021-05-24 20:17:13";1;2;Processed
Snow;"November 15th";"+16501234567";Jon;;;"{""result"":true,""duration"":14,""rating"":""four""}";"2021-07-15 20:20:38";0;0;2;Processed;
Targaryen;"November 16th";"+16501234568";Daenerys;;;"{""result"":true,""duration"":27,""rating"":""five""}";"2021-07-15 20:21:37";0;0;2;Processed;

You can always use the ASR module to let your customers answer using voice or make calls via your SIP infrastructure by changing the callPSTN function to callSIP one. Don't forget that you can also make HTTP requests right from the scenario to pass the data to your backend in real-time. Feel free to change the scenarios according to your needs.

Extra tips

You can save the survey results to the customData parameter and then use it to get statistics, through the call_session_history_custom_data parameter of the GetCallHistory method.

Don't forget that you can also make HTTP requests right from the scenario to pass the data to your backend in real-time. Feel free to change the scenarios according to your needs.