clearDtmf

The vcc.clearDtmf() function is used within the VCC Live Contact Center Script module to clear the Dual-Tone Multi-Frequency (DTMF) buffer. When processing caller keypad inputs during an active call, the system stores pressed keys in the global.dtmf script variable. Calling this function empties the buffer, ensuring that any subsequent DTMF capture starts fresh without interference from previous, unwanted, or accidental keypad presses.

Description

vcc.clearDtmf(): void

You can save the DTMF data, then ask the client for another DTMF input.

Parameters

This function does not accept any parameters.

Return values

This function does not return a value (returns undefined). Its sole purpose is to perform the action of clearing the internal DTMF input cache.

Use cases with explanation

Use case 1. Preparing a Clean State for a New Input Sequence

When requesting secure input from a caller, such as a verification code or a credit card PIN, it is vital to ensure that old key presses from earlier in the call are wiped out. Calling vcc.clearDtmf() before you begin polling for new digits guarantees you are only reading the digits pressed exactly when requested.

// Example: Starting a secure capture for a 4-digit PIN
function startPinCapture() {
  // Clear any residual DTMF digits from previous script elements
  vcc.clearDtmf();
  
  // Define a recurring loop to check for the required 4 digits
  checkPinInterval = vcc.setTimeout(checkPinInput, 1000);
}

function checkPinInput() {
  let dtmfInput = vcc.getScriptVariable("global.dtmf");
  if (dtmfInput.length === 4) {
    vcc.setFieldValue("pin_field", dtmfInput);
    // Proceed to validate or process the PIN
  } else {
    checkPinInterval = vcc.setTimeout(checkPinInput, 1000);
  }
}

Use case 2. Handling Input that Exceeds the Maximum Allowed Length

If a caller continuously presses keys and inputs more digits than expected (for instance, 6 digits when only 5 are needed), the input is effectively invalid. vcc.clearDtmf() can be utilized to gracefully reset the buffer so the caller is forced to start over, avoiding the need to prune the string manually.

// Example: Validating DTMF length against an expected number of digits
function validateInputLength(expectedLength) {
  let currentDtmf = vcc.getScriptVariable("global.dtmf");
  
  if (currentDtmf.length === expectedLength) {
    // Exact length reached, enable the submit button for the agent
    vcc.getController("payment_form", "submit_button").disabled = false;
  } else if (currentDtmf.length > expectedLength) {
    // Too many digits entered. Clear the buffer entirely so the caller tries again
    vcc.clearDtmf();
    // Also notify the agent
    vcc.setFieldValue("status_msg", "Too many digits. Buffer cleared. Please ask the caller to try again.");
    vcc.getController("payment_form", "status_msg").refresh();
    vcc.getController("payment_form", "submit_button").disabled = true;
  } else {
    // Still waiting for more digits
    vcc.getController("payment_form", "submit_button").disabled = true;
  }
}

Use case 3. Resetting Input State on Script Page Changes

When a contact center script guides agents and callers through multiple different pages (e.g., from generic support branching to a protected transaction page), ensuring that stray DTMF inputs do not act as accidental submissions on a new page is good practice. Utilizing vcc.clearDtmf() on the page’s onLoad hook establishes a safe baseline.

// Example: Clearing buffer upon entering a secure transaction page
$("transaction_page").onLoad = function () {
  // Wipe out any accidental button presses from previous menus
  vcc.clearDtmf();
  
  // Initialize standard display values for the new page
  vcc.setFieldValue("transaction_status", "Ready to capture new digits...");
  vcc.getController("transaction_page", "transaction_status").refresh();
};

Notes

• Variable Relationship: Executing vcc.clearDtmf() directly mutates the state tracked by vcc.getScriptVariable("global.dtmf"). Querying this variable immediately after clearing will yield an empty string ("").
• Timing Best Practices: Always use this function proactively before initiating asynchronous timer functions (e.g., setTimeout) that read the buffer. This mitigates race conditions where a caller might press a key just milliseconds before your polling loop begins.