Editing call lists

Editing parameters in real time

Sometimes you may need to edit some call list parameters during the progression of a call list. In this article, you will learn how to do this.

Voximplant allows editing the following parameters of the call list:

• start_at — updates the earliest time (UNIX timestamp in seconds) for the next attempt to be made
• attempts_left — updates the number of calling attempts left. If set to 0, the current attempt is considered the last, and the task is marked as failed. If not set explicitly, the current number of attempts left will be decreased by 1
• custom_data — updates the data source for the task. If no data is provided, the task data remains intact
• start_execution_time — updates the starting time for calling attempts. The calls cannot be made earlier than start_execution_time. The time format is HH:MM:SS (24-hour format), the time zone is UTC.
• end_execution_time — updates the ending time for calling attempts. The calls cannot be made later than end_execution_time. The time format is HH:MM:SS (24-hour format), the time zone is UTC.

To update the parameters, use the CallList.requestNextAttempt() method. It accepts the new parameters, applies them, and then performs another call attempt with new parameters.

How it works

Let us create an example to show how it works. You will need:

1. An application.
2. A scenario where you describe the logic.
3. A routing rule to launch the scenario.
4. A phone number to use as a caller ID.

Prepare the CSV table to pass to the scenario in the custom data field in the following format:

1
numbers;first_name;last_name
2
18881231231,18881231232;Elon;Musk

First, let us process the data from the CSV table. If the call connects, implement some logic, for example, read a message to the customer via TTS. You can find more information with examples in the main call list article.

If the call fails, let us update some parameters and retry. To do this, create an object with updated call list parameters (updatedCallListData in this example), then pass the object to the CallList.requestNextAttempt() method. This method makes a new calling attempt with updated parameters automatically.

Refer to this code example to understand how it works:

1
VoxEngine.addEventListener(AppEvents.Started, (e) => {
2
  const data = JSON.parse(VoxEngine.customData());
3
4
  // get the list of numbers from custom data
5
  const numbers = data['numbers'].split(',');
6
  // check which of the user numbers we need to dial
7
  let numberIndex = data['index'] || 0;
8
9
  const call = VoxEngine.callPSTN(numbers[numberIndex], 'some_caller_id');
10
11
  call.addEventListener(CallEvents.Connected, () => {
12
    // implement some logic here. for example,
13
    // read a message to your customer via TTS
14
15
    call.addEventListener(CallEvents.Disconnected, () => {
16
      // report success, terminate session
17
      CallList.reportResult('success', VoxEngine.terminate);
18
    });
19
  });
20
21
  call.addEventListener(CallEvents.Failed, () => {
22
    // number is unreachable, try another one next time
23
    numberIndex = (numberIndex + 1) % numbers.length;
24
    data['index'] = numberIndex;
25
26
    const updatedCallListData = {};
27
    // update any of the fields below or all of them at once
28
29
    // updates the data source for the task
30
    updatedCallListData['custom_data'] = JSON.stringify(data);
31
32
    // updates the number of calling attempts left
33
    updatedCallListData['attempts_left'] = 1;
34
35
    // updates the earliest time for the next attempt
36
    // in this case we set this to current time + 1 second
37
    updatedCallListData['start_at'] = Math.ceil(new Date().getTime() / 1000 + 1);
38
39
    // updates the starting time for calling attempts
40
    updatedCallListData['start_execution_time'] = '05:00:00';
41
42
    // updates the ending time for calling attempts
43
    updatedCallListData['end_execution_time'] = '18:00:00';
44
45
    CallList.requestNextAttempt(updatedCallListData, function (ev) {
46
      Logger.write(JSON.stringify(ev));
47
      VoxEngine.terminate();
48
    });
49
  });
50
});

Editing a task’s next attempt date

In addition to modifying the call list parameters in real time, you can specify the next attempt date for each task. In this case, the task does not start before the specified date.

You can specify the next attempt date in 3 ways:

1. In real time: just pass the next_attempt_time parameter into the EditCallListTask method, specifying the date in the 2024-10-31T15:00:13.567+03:00 format.

2. While creating the call list: specify a new column named next_attempt_time in the CSV sheet with call list tasks with the dates in the 2024-10-31T15:00:13.567+03:00 format.

3. In the VoxEngine scenario: pass the next_attempt_time parameter via the CallList.requestNextAttempt() method with the dates in the 2024-10-31T15:00:13.567+03:00 format. See the scenario example below to learn how to do it:

1
require(Modules.CallList);
2
VoxEngine.addEventListener(AppEvents.Started, function (e) {
3
  setTimeout(function () {
4
    updatedCallListSync();
5
    VoxEngine.terminate();
6
  }, 1000);
7
});
8
function updatedCallListSync() {
9
  const updatedCallListData = {};
10
  updatedCallListData['next_attempt_time'] = '2024-10-15T10:40:12.000+03:00';
11
  let response;
12
  try {
13
    Logger.write('[LOGGER] Update the call list');
14
    response = CallList.requestNextAttempt(updatedCallListData);
15
    Logger.write(JSON.stringify(response));
16
  } catch (error) {
17
    dashboard.clError();
18
    Logger.write('[LOGGER] Update error: ${error}');
19
  }
20
}

There are two restrictions for the next attempt date parameter:

1. You cannot pass any time in the past, in this case the call list does not accept the value and sets the next attempt date to the request time plus the specified interval between calls.
2. You cannot pass any time more than 9 months in the future, in this case the call list does not accept the value and sets the next attempt date to the request time plus the specified interval between calls.