SIGN UP

Automated telephone surveys and notifications

Automated telephone surveys and notifications

Building automated telephone surveys and notifications has never been easier - with VoxImplant you can build even complex scenarios in minutes. A special feature called CallLists should be used for that purpose. Every record in a CSV file is sent with the CreateCallList request will be processed with a VoxEngine scenario, the result can be stored and accessed using the GetCallListDetails method of the HTTP API.

The process can be divided into a few parts: 1. Creating a CSV file with the list of phone numbers and additional data that can be passed to a scenario 2. Creating a Voximplant application with a scenario that will process every line of the CSV file and a rule for this scenario 3. Making a request to the HTTP API to start automated calling process

Designing CSV-file structure

First of all, you need to design your CSV file that will be sent to HTTP API, its data will be passed to VoxEngine scenario as customData in form of a JSON-string, that can be converted into a JavaScript object. The first line of the file will contain parameter names, let's see the example for sending automated notifications about the scheduled appointment:

first_name;last_name;phone_number;appointment_date
John;Snow;16501234567;November 15th
David;Ericsson;16501234568;November 16th

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

VoxEngine scenario

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

require(Modules.CallList); // Enable CallList module
require(Modules.AI);

  let call;
  let first_name;
  let last_name;
  let phone_number;
  let caller_id = "+1234567890"; // Rented or verified phone number
  let appointment_date;
  let playbackCounter = 0;

// AppEvents.Started dispatched for each CSV record
VoxEngine.addEventListener(AppEvents.Started, function (e) {
  let data = VoxEngine.customData(); // <-- data from CSV string in JSON format
  data = JSON.parse(data);
  first_name = data.first_name;
  last_name = data.last_name;
  phone_number = data.phone_number;
  appointment_date = data.appointment_date;
  Logger.write(`Calling ${first_name} ${last_name} on ${phone_number}`);
  // Make a call
  call = VoxEngine.callPSTN(phone_number, caller_id);
  // Trying to detect voicemail
  call.addEventListener(CallEvents.AudioStarted, function(){
    AI.detectVoicemail(call)
      .then(voicemailDetected)
      .catch(()=>{
        Logger.write('Voicemail not detected');
      })
  });
  // Add event listeners
  call.addEventListener(CallEvents.Connected, handleCallConnected);
  call.addEventListener(CallEvents.Failed, handleCallFailed);
  call.addEventListener(CallEvents.Disconnected, handleCallDisconnected);
});

function voicemailDetected(e) {
  // Voicemail?
  if (e.confidence >= 75) {
    VoxEngine.CallList.reportError('Voicemail', VoxEngine.terminate);
  }
}

// Call connected successfully
function handleCallConnected(e) {
  connected = true;
  setTimeout(function () {
    e.call.say(`Hello ${first_name}! Your appointment scheduled for ${appointment_date}`, 
      Language.US_ENGLISH_FEMALE);
  }, 500);
  e.call.addEventListener(CallEvents.PlaybackFinished, handlePlaybackFinished);
}

function handleCallDisconnected(e) {
  // Tell CallList processor about successful call result
  CallList.reportResult({
    result: true,
    duration: e.duration,
    rating: rating,
  }, VoxEngine.terminate);
}

// Playback finished
function handlePlaybackFinished(e) {
  e.call.removeEventListener(CallEvents.PlaybackFinished, handlePlaybackFinished);
  playbackCounter++;
  // If the message was played 4 times - hangup
  if (playbackCounter === 4) {
    e.call.hangup();
  } else {
    // Play one more time
    setTimeout(function () {
      e.call.say(`Your appointment scheduled for ${appointment_date}`, 
        Language.US_ENGLISH_FEMALE);
      e.call.addEventListener(CallEvents.PlaybackFinished, handlePlaybackFinished);
    }, 2000);
  }
}

function handleCallFailed(e) {
  // Tell CallList processor that we couldn't get call connected
  // depending on the request options it will either try to launch the scenario again after some time
  // or will write the result (failed call) into result_data column of the CSV file with results
  CallList.reportError({
    result: false,
    msg: 'Failed',
    code: e.code
  }, VoxEngine.terminate);
}

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

Launching automated dialing 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, 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;John;16501234567;Snow;;;"{""result"":true,""duration"":27}";"2014-11-24 19:21:39";1;2;Processed
November 16th;David;16501234568;Ericsson;;;"{""result"":true,""duration"":20}";"2014-11-24 19:21:39";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:

function handleCallConnected(e) {
  connected = true;
  e.call.handleTones(true); // <-- enable input processing
  setTimeout(function () {
    e.call.say(`Hello ${first_name}! Thank you for visiting our store, ` +
      `please rate the customer service quality from 1 to 5.`, 
      Language.US_ENGLISH_FEMALE);
  }, 500);
  e.call.addEventListener(CallEvents.PlaybackFinished, handlePlaybackFinished);
  e.call.addEventListener(CallEvents.ToneReceived, handleToneReceived);
}

let rating;

function handleToneReceived(e) {
  e.call.removeEventListener(CallEvents.PlaybackFinished, handlePlaybackFinished);
  e.call.stopPlayback();
  rating = e.tone;
  e.call.say('Thank you for your answer!', Language.US_ENGLISH_FEMALE);
  e.call.addEventListener(CallEvents.PlaybackFinished, function (e) {
    e.call.hangup();
  });
}

function handleCallDisconnected(e) {
  CallList.reportResult({
    result: true,
    duration: e.duration,
    rating: rating,
  }, VoxEngine.terminate);
}

// Playback finished
function handlePlaybackFinished(e) {
  e.call.removeEventListener(CallEvents.PlaybackFinished, handlePlaybackFinished);
  playbackCounter++;
  if (playbackCounter === 4) {
    e.call.hangup();
  } else {
    setTimeout(function () {
      e.call.say('Please rate the customer service quality from 1 to 5.', 
        Language.US_ENGLISH_FEMALE);
      e.call.addEventListener(CallEvents.PlaybackFinished, handlePlaybackFinished);
    }, 2000);
  }
}

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
John;16501234567;Snow;;;"{""result"":true,""duration"":27,""rating"":""3""}";"2014-11-24 20:17:13";1;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.

Tags:ivrpstn
B6A24216-9891-45D1-9D1D-E7359CEB8282 Created with sketchtool.

Comments(0)

Add your comment

Please complete this field.

Recommended

Sign up for a free Voximplant developer account or talk to our experts
SIGN UP