getChannelVariable

The vcc.getChannelVariable function is used to retrieve the value of a specific channel variable during a call or within a script. Channel variables are often set by the IVR (Interactive Voice Response) system, external API calls, or routing rules before the script is loaded. This allows passing custom data or routing information directly into the agent script.

Description

vcc.getChannelVariable(variableName);

Channel variables can be set via inbound settings. See Inbound Calls section.

Parameters

• variableName (string): The name of the channel variable whose value you want to retrieve. Commonly used variables include IVR inputs, integration data, or specific routing variables (e.g., 'vcc_pin', 'vcc_field_skill').

Return values

• (string | null): Returns the value of the requested channel variable as a string. If the channel variable does not exist or has no value, it returns null or an empty string depending on the context.

Use cases with explanation

1. Retrieving Pre-Identified Caller Information from IVR

If the caller entered their customer ID or PIN in the IVR, you can retrieve this information to populate the agent’s screen automatically.

$().onLoad = function() {
    // Retrieve the PIN entered by the caller in the IVR
    const customerPin = vcc.getChannelVariable('vcc_pin');
    const isIdentified = vcc.getChannelVariable('vcc_foundByPin');

    if (isIdentified === 'TRUE' && customerPin) {
        // Automatically fill the customer ID field
        vcc.setFieldValue('customer_id', customerPin);
        vcc.getController('client_data', 'customer_id').refresh();
    }
};

Explanation: This script runs when the form loads. It checks if a PIN was found (vcc_foundByPin) and retrieves its value (vcc_pin). If valid, it updates a script field so the agent doesn’t need to ask for it again.

2. Passing Campaign or Skill Group Data to the Script

You can use channel variables to understand the context of the call, such as which specific skill group or campaign sub-type the call was routed from, and adjust the script behavior accordingly.

$().onLoad = function() {
    // Get the skill assigned to the channel
    const currentSkill = vcc.getChannelVariable('vcc_field_skill');
    
    // Check available skills in the dropdown and set the matching one
    var availableSkills = vcc.getFieldValues('skill_selector');
    availableSkills.forEach(function(item) {
        if (item.label === currentSkill) {
            vcc.setFieldValue('skill_selector', item.valueid);
            vcc.getController('routing_page', 'skill_selector').refresh();
        }
    });
};

Explanation: This case retrieves the routed skill from the channel variable vcc_field_skill. It then iterates through the dropdown options of a field named skill_selector and sets it to the matching skill, pre-selecting it for the agent.

3. Fetching Integration Data or External Variables

When a call triggers an external webhook or API before reaching the agent, the result can be saved into a channel variable. The script can then dynamically read and build external URLs (like CRM popups).

$().onLoad = function() {
    const orderNumber = vcc.getChannelVariable('vcc_order_number');
    const callUUID = vcc.getScriptVariable('global.uuid');
    
    if (orderNumber) {
        // Build a CRM URL using the retrieved channel variable
        const crmURL = 'https://crm.dummy-company.com/orders/view?order=' + orderNumber + '&callId=' + callUUID;
        
        // Open the CRM system automatically in the default browser
        vcc.openURLInDefaultBrowser(crmURL);
    }
};

Explanation: The function looks for vcc_order_number set on the channel. If it exists, it constructs a unique URL to the external CRM system and pops the record open automatically for the agent.

• Channel variables are read-only from the perspective of the script. They are meant to be consumed rather than modified directly with this function.
• Be careful with variable names: they are case-sensitive. Typically, built-in IVR variables or metadata start with vcc_.
• Always verify that the channel variable returns a valid value before using it, especially when using it for logical conditions, as different call flows might not populate every variable.