Call lists for automated calls

Voximplant’s Call Lists feature allows you to build even the most intricate scenarios with call campaigns in a matter of minutes. You can create a CSV table containing a call list that can be processed by a VoxEngine scenario.

In this article, we present a scenario where we call through a CSV table containing a customer list and provide each customer with their appointment time.

1. Create an application.
2. Create a scenario.
3. Create a routing rule and attach it to the scenario.
4. Prepare a call list CSV table with phone numbers and additional information.

CSV table for call lists contains phone numbers to be called and any additional information to be passed into a VoxEngine scenario. Here’s an example of a call list CSV table format:

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

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

If needed, you can add time intervals when the call list processing starts and ends 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

Call schedule

If you need to specify a custom schedule when to call a specific contact, add a call_schedule column into the table. It accepts the schedule in the JSON format.

Here is an example of the call schedule record:

{
  "call_schedule":
    [
      {
        "day_of_week": "mon", 
        "start": "10:10:00",
        "end": "11:00:00"
      },
      {
        "day_of_week": "tue", 
        "start": "10:10:00", 
        "end": "11:00:00"
      }
    ]
}

You can specify the same day of the week twice if you need two intervals within the same day. The day_of_week field can accept both full day of the week, or short 3-letter version.

Task priorities

You can specify priorities for the call list entries.

Changing priorities work only for incomplete tasks. If the priority is set, first a call list processes the prioritized tasks, then the task according to the call list strategy (first calling attempts or repeating calling attempts are prioritized). Tasks with the same priority are sorted by IDs.

To set the priorities, add the task_priority column to the call list CSV which should contain a numeric value of the record's priority. 0 is the highest priority.

If a priority is not set for a specific record, the call list engine defaults to 50. If the field contains a non-numeric value, the following error returns: The ‘task_priority’ parameter is invalid.

In the scenario, require the CallList module and create variables for all the fields from the CSV table. The scenario processes each table row at a time. In this example, we use the AI module to detect voicemail. Then, we use the speech synthesis feature to announce the appointment time.

Please take a look at the scenario example to understand how it works.

To initiate a call list, you must send a Management API request. For more information about our call lists management API, refer to our API reference.

Let us take a look at the createCallList request parameters:

The getCallListDetails request result looks the following:

"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

Use these methods after an unsuccessful calling attempt when you want to change task parameters and schedule another attempt instead of finishing the task.

Both methods update only the current task. They do not change global call list settings. Updated values apply to all remaining attempts for that task.

Editable fields

CallList.requestNextAttempt(data, callback)

Callback-style API. Invokes callback with Net.HttpRequestResult when the HTTP request completes (or immediately with an error if validation fails before send).

CallList.requestNextAttemptAsync(data)

Promise-based API. Resolves with Net.HttpRequestResult on success; rejects with the result object (or another error) when the request fails.

There are two ways to receive user feedback during a call: through voice and by pressing buttons. To process voice feedback, you can utilize our built-in voice recognition. For button feedback, you need to handle the ToneReceived event.

Handle DTMF tones

In our code example, let us prompt the customer to rate the service quality on a scale of 1 to 5 and then handle the corresponding event.

Handle user speech

Use Voximplant's voice recognition feature to handle the user's speech.

In our code example, require the ASR module and create a speech recognition instance via the createASR method. Then use the sendMediaTo method to send the customer's input to the instance.

You receive the result in the ASREvents.Result event. You can process the result as you need.

Please take a look at the code example to understand how it works:

The result is the following:

"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 also make HTTP requests from the scenario to pass the data to your backend in real-time. 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.

Q: My call list processing suddenly stopped, why?
A: Call lists do not work if your account balance is less than $1. After you replenish the balance, call lists resume automatically.

Q: I cannot delete my call list, why?
A: To delete a call list, pause it or wait until completion because you cannot delete a call list that is in progress.