Documentation Index

Fetch the complete documentation index at: https://docs.natterbox.com/llms.txt

Use this file to discover all available pages before exploring further.

Use SSO to log in and access the Help Center, where you can create and manage your support tickets to reduce your resolution times.

How to configure direct extension dialling for users and groups

Prev Next

This guide explains how to build a routing policy that allows callers to dial a known user or group extension directly. The policy plays a prompt, captures the caller's input, validates it against Salesforce, and connects the call if a match is found.

Use case

Direct extension dialling is ideal when your callers already know the extension of the person or team they want to reach. Rather than navigating menus or waiting in a queue, the caller simply enters the extension number and is connected immediately.

Common scenarios include:

  • Internal staff dialling into a main line and routing themselves to a colleague's extension.

  • Repeat customers who have been given a direct extension for their account manager.

  • Partner organisations with pre-shared group extensions for specific departments.

How it works

The call flow follows this sequence:

  1. The caller hears a prompt asking them to enter a 4-digit extension followed by the # key.

  2. The system captures the input using an IVR pattern match.

  3. A Salesforce query checks the nbavs__User__c object for a matching nbavs__SipExtension__c value.

  4. If no user match is found, a second query checks the nbavs__Group__c object for a matching nbavs__Extension__c value.

  5. If a match is found in either object, the call is connected to that extension.

  6. If no match is found, the caller hears an error message and the script returns false, allowing the policy to continue to the next app or container.

Prerequisites

  • User extensions assigned  under each user's Extension field.

  • Group extensions assigned (if you want group dialling) under each group's Extension field.

Policy Builder setup

The extension dialling logic is handled entirely within a Script Engine app. You will need to place it inside an Action container within your routing policy.

  1. Open your routing policy in the Policy Builder.

  2. Add an Action container where you want the extension dialling to occur (for example, after a welcome greeting).

  3. Inside the Action container, add a Script Engine app.

  4. Name the app (e.g. "Extension Dialling").

  5. Paste the Lua script (below) into the script field.

  6. Save the policy.

The Lua script

The script below handles the full extension dialling workflow — prompting the caller, validating input against Salesforce, and connecting the call. Expand the accordion to view the full script.

Full Lua script — direct extension dialling

enable_debug('email')

function question(say, voice, timeout) 
    print("DEBUG: Starting IVR loop")
    
    local ivr = {} 
    local FIRST = 1  
    
    ivr[FIRST] = {} 
    ivr[FIRST].name = 'Extension' 
    
    -- Using \\d to safely capture any 4 digits
    ivr[FIRST].pattern = '^(\\d{4})#$' 
  
    local res = nil 
    while res == nil or res == false do 
        res = session.ivr(ivr, say, voice, timeout, 'myIVR') 
        
        if type(res) == "table" then
        else
            session.say(' Sorry that number is not a valid extension ') 
        end
    end 
    return res['value'] 
end 
 
function checkExtension(extension) 

    local userSoql = "SELECT nbavs__SipExtension__c FROM nbavs__User__c WHERE nbavs__SipExtension__c = '"..extension.."'" 
    local userSfRes = connector.sf_query(connectorId, userSoql, 'UserExtension') 
 
    if userSfRes == false then
    end
 
    local FIRST = 1
    if userSfRes ~= false and type(userSfRes) == "table" and userSfRes[FIRST] ~= nil then 
        return true 
    end 
    

    local groupSoql = "SELECT nbavs__Extension__c FROM nbavs__Group__c WHERE nbavs__Extension__c = '"..extension.."'"
    local groupSfRes = connector.sf_query(connectorId, groupSoql, 'GroupExtension')
    
    if groupSfRes == false then
    end
    
    if groupSfRes ~= false and type(groupSfRes) == "table" and groupSfRes[FIRST] ~= nil then
        return true
    end
    
    return false 
end 
 
function connect(extension) 
    local dialString = {} 
    local FIRST = 1
    
    dialString[FIRST] = {} 
    dialString[FIRST].method = "NUMBER" 
    dialString[FIRST].target = tostring(extension) 
    dialString[FIRST].start = 0 
    dialString[FIRST].timeout = 30 
    dialString[FIRST].screen = false 
 
    session.connect(dialString, 33) 
end 


local res = question(' Please Enter the Extension you wish to reach followed by the # Key', nil, 7000) 

if res and checkExtension(res) then 
    connect(res) 
else 
    session.say(' We are sorry, but that extension could not be found in the system. ')
    return false 
end 

return true

Script breakdown

The script is split into three core functions. Here's what each one does:

question() — capture caller input

This function plays the TTS prompt and listens for the caller to enter 4 digits followed by #. It uses a regex pattern (^(\\d{4})#$) to validate the input. If the input doesn't match (e.g. fewer than 4 digits or no # key), the caller hears an error message and is prompted again in a loop.

Key parameters:

  • say — the TTS message played to the caller.

  • voice — the TTS voice to use (set to nil to use the account default).

  • timeout — how long (in milliseconds) to wait for input before re-prompting.

checkExtension() — validate against Salesforce

This function runs two SOQL queries via the Salesforce Connector:

  1. First, it queries the nbavs__User__c object for a user with a matching nbavs__SipExtension__c.

  2. If no user is found, it queries the nbavs__Group__c object for a group with a matching nbavs__Extension__c.

If either query returns a result, the function returns true. Otherwise, it returns false.

connect() — route the call

This function builds a dial string targeting the matched extension number and connects the call using session.connect(). The call rings for 30 seconds before timing out.

Key parameters in the dial string:

  • method — set to "NUMBER" to dial the extension directly.

  • target — the extension number to connect to.

  • timeout — ring duration in seconds (default: 30).

  • screen — set to false (no call screening).

Customisation options

Parameter

Default value

Description

Extension length

4 digits

Change the pattern \\d{4} to \\d{3} for 3-digit extensions or \\d{5} for 5-digit extensions.

Timeout (IVR)

7000 ms

How long the system waits for the caller to enter digits. Increase for callers who may need more time.

Timeout (ring)

30 seconds

How long the destination extension rings before timing out. Adjust in the dialString.timeout value.

TTS prompt

"Please Enter the Extension…"

Customise the spoken prompt in the question() function call at the bottom of the script.

Error message

"We are sorry, but that extension could not be found…"

Customise the failure message in the final session.say() call.

Troubleshooting

The caller hears "not a valid extension" repeatedly

This means the IVR pattern is not matching the caller's input. Check that:

  • The caller is pressing exactly 4 digits followed by #.

  • The pattern in the script matches your extension length (default is 4 digits).

  • The timeout value (7000 ms) is long enough for the caller to finish typing.

The extension is valid but the call doesn't connect

Check the following:

  • The user/group extension field in Salesforce actually contains the value the caller entered (check for formatting differences).

💡

Tip: Enable enable_debug('email') (already included at the top of the script) to receive debug output via email. This makes it much easier to trace issues in production. Just populate your email address in the designated field.

What happens after the script

If the script returns true (successful connection), the call ends naturally when either party hangs up. If the script returns false (extension not found), the call passes to the next app or container in your routing policy. You can use this to route failed attempts to a receptionist, queue, or voicemail.