Welcome to VoiceGuide IVR Software

VoiceGuide was designed to allow fast and easy creation of Inbound and Outbound IVR and Messaging systems which can be easily tailored to individual needs.

VoiceGuide's Graphical Script Designer contains a range of highly functional modules to allow rapid creation and easy administration, and scripted Voicemail and ACD features facilitate a wide range of Inbound/Outbound Self Service and Agent Assisted IVR solutions to be deployed.

Fully working evaluation version of the VoiceGuide IVR software can be downloaded, allowing full evaluation of the software before purchasing.

Free Support is provided on the public Support Forum which is monitored by our support staff.


Which VoiceGuide Version to Use

Latest version of VoiceGuide is v7.x

VoiceGuide v7.x can use VoIP, and can control analog and T1/E1 ISDN trunks.

Table below lists some of the common devices used in IVR systems, the types of telephone lines used with these devices, and the appropriate VoiceGuide version to use for each scenario:

Device | Lines Used | VoiceGuide Version
Dialogic cards | Analog, T1/E1 ISDN | VoiceGuide v7 / v6 - select the "Dialogic cards" option during install.
(none used) | VoIP - SIP | VoiceGuide v7 - select the "VoIP/HMP" option during install
Dialogic DNI/HMP cards | T1/E1 ISDN | VoiceGuide v7 - select the "VoIP/HMP" option during install
CAPI cards | BRI ISDN | VoiceGuide v5 (TAPI version)
Voice Modems | Analog | VoiceGuide v5 (TAPI version)
TAPI devices | Various | VoiceGuide v5 (TAPI version)


VoiceGuide Minimum System Requirements

When running on a physical system:

  • Win2019, Win2016, Win2012, Win2008 R2 SP1, Win10, Win8.1, Win7 SP1
  • .NET 4.7
  • CPU: Intel i3
  • RAM: 4GB
  • HD: 100GB

When running on a Virtual Machine (HMP - VoIP based deployments only):

  • VMware ESXi 4.1 or later
  • 1 dedicated CPU core
  • Win2019, Win2016, Win2012, Win2008 R2 SP1, Win10, Win8.1, Win7 SP1
  • .NET 4.7
  • RAM: 4GB
  • HD: 100GB


Installing VoiceGuide v7 for VoIP / HMP

VoiceGuide v7.x can use VoIP (SIP) to handle calls over the network interface.

No physical cards are needed for deploy a VoIP/SIP only system.

VoIP/SIP deployment can be made on:

  • Physical server
  • VMware ESXi Virtual Machine
  • Amazon Web Services (AWS)
  • Microsoft Azure
  • Microsoft Hyper-V
  • Cloud hosted VMware ESXi Virtual Machine

Dialogic HMP licenses are needed in addition to VoiceGuide licenses.
Please contact sales@voiceguide.com regarding purchasing of Dialogic HMP licenses.

HMP can also use Dialogic HMP Interface Boards to allow HMP systems to connect to physical T1/E1/Analog lines.

Deploying on Cloud

Supported Cloud environments:

  • Amazon Web Services (AWS)
  • Microsoft Azure
  • Cloud hosted VMware ESXi Virtual Machine

VMware ESXi Cloud providers can be found here: https://cloud.vmware.com/providers

eg: Google Cloud VMware Engine, CenturyLink

Installing Dialogic HMP

Dialogic HMP 3.0 drivers should be installed before installing VoiceGuide.

Before installing HMP ensure that all available Windows Updates have been applied. Use the Windows Update app from Windows' Settings or Control Panel to check for any outstanding updates and complete their installation before proceeding with HMP install.

Dialogic HMP requires that the HPET (High Precision Event Timer) is enabled on the system. The following command should be ran at the "Command Prompt (Admin)" to enable the HPET:

bcdedit /set useplatformclock true

and Windows must be restarted afterwards.

HMP must be installed using an Administrator account, or using "Run as Administrator".

After HMP installation Windows should be restarted.

Changing HMP Version

Existing HMP must be fully uninstalled (do not save any configuraton settings), then Windows must be restared to complete uninstall. Only then can the new version of HMP be installed. After HMP installation Windows should be restarted.

After Installing Dialogic HMP

Confirm Dialogic Configuration Manager (DCM) can start the Dialogic service.

It is best if only one network interface is enabled on the system.
If more than one network interface is enabled on the system then Dialogic HMP must use the 'First' network interface for all VoIP/SIP communications.

On systems that have an option to set 'C-State' (power mode) in BIOS, the C-State must be disabled (set to C0). i.e. the CPU is 100% turned on.

If Dialogic HMP service has problems starting then you should ensure that there is no other VoIP software installed on the system that would interfere with HMP operation, and that no anti-virus type software is blocking the service start.

If there are still problems, try fully disabling the Windows' User Access Control and then reinstalling the Dialogic drivers. Windows' User Access Control is disabled in the Windows Registry, by setting the EnableLUA parameter to 0.

To re-install Dialogic drivers you need to first fully uninstall, selecting 'Do not save configuration', and restart system after uninstall. After installing the Dialogic drivers the system needs to be restarted again.

If using HMP Interface Boards please ensure that the 'Device -> Restore Defaults' is done for all the cards present in system as well as for the 'HMP_Software' device and the 'Configured Devices' root. This is done using Dialogic DCM.

It's recommended to set the Dialogic service to start automatically. This can be set using DCM 's Settings -> System/Device autostart -> Start System menu, or by using the Windows' Control Panel -> System and Security -> Administrative tools -> Services applet.

HMP comes with a 1 port Evaluation license. Please contact sales@voiceguide.com regarding purchasing of HMP licenses.

VMware ESXi

If deployment is made on VMware ESXi virtual machine, VMware's Latency Sensitivity for that machine should be set to "High".

To set Latency Sensitivity to "High":

  1. Right-click the virtual machine and click Edit Settings.
  2. Click VM Options and click Advanced.
  3. Select a setting from the Latency Sensitivity drop-down menu.
  4. Click OK.

Note: Some ESXi versions require full CPU reservation and Memory reservation to allow Latency Sensitivity to be set to "High".

T1/E1/Analog HMP Systems

For systems which use Dialogic HMP Interface Boards to connect with T1/E1/Analog lines please refer to installation and configuration instructions for the board which is used.

Softphones

NOTE: The testing softphone MUST NOT be installed on the same system as Dialogic HMP.
It must be installed on some other system.
There can be no other SIP software that uses SIP 5060 port installed on same system as Dialogic HMP.
Only one software can use the SIP 5060 port at a time.

One softphone that can dial the IP address directly is MicroSIP: https://www.microsip.org

Once MicroSIP is installed the IP address by itself can be just entered as the number to call, and MicroSIP will dial that IP address directly.

Note: The 'Full' version of MicroSIP should be used. The 'Lite' versions of MicroSIP cannot dial the IP address directly.

Another softphone that can dial the IP address directly is Linphone: http://www.linphone.org

With Linphone the SIP address to be dialed must be prefixed with "sip:" eg: sip:10.1.1.19 will dial IP address 10.1.1.19 directly.

Also please select Linphone's Options->Preferences menu, and set the following:
Network Settings tab : Media Encryption is set to 'None'
Codecs tab: only enable the PCMU and PCMA codecs, and disable the rest.

Another older softphone that can also dial the IP address directly is SJPhone.
Once SJPhone is installed the IP address by itself can be just entered as the number to call, and SJPhone will dial that IP address directly.

Trace SIP Messages

WireShark can be used to confirm that SIP packets are arriving at VoiceGuide/HMP system.

To isolate SIP traffic the following should be specified in WireShark's Filter text box:

sip

To isolate SIP and RTP traffic the following should be specified in WireShark's Filter text box:

sip || rtp

To save the isolated traces go to WireShark's File->Export Specified Packets menu and save the displayed packets as .pcapng format.

Installing VoiceGuide

Dialogic's HMP drivers must be installed before proceeding with VoiceGuide installation.

VoiceGuide needs to be installed using the Administrator account.

If not logged in as Administrator then right click on VoiceGuide install .EXE and select 'Run as administrator' :

The VoiceGuide installer will then start:

Then default "VoIP / SIP" option will result in the VoiceGuide installer setting up configuration files for the Dialogic HMP based VoIP/SIP systems:

Then select whether by default the system should use ULaw or Alaw format when recording files, and which format 'system sound files' should VoiceGuide use.

VoiceGuide will play back many different format sound files, and this selection will not restrict what sound files can be played, but this selection decides whether ULaw or Alaw format will be used when recording. Matching VoiceGuide's record sound format with the format used by telephone service provider results in best quality sound recordings.

Also, playing sound files in the same format as what the telephone service provider uses means that the files will not need to be transcoded or resampled when sent over the telephone service provider's network. This helps in achieving the best possible quality sound playback.

Next select the directory into which VoiceGuide should be installed.
If you select a directory other than the default directory then the VoiceGuide's Config.xml setting that specifies the callflow that is to be used on each channel will need to be updated with that directory details. (and VoiceGuide service restarted afterwards).

The files will then be installed:

When installation is complete the final screen will appear:

And the Script Designer will be started, loading the default demo callflow.
(The callflows/scripts to use are set in the Config.xml file):

The IVR icon will also appear in the icon tray at the bottom right of the screen.
Once the VoiceGuide Service starts a still green arrow will show on that icon:

If VoiceGuide was installed into the default directory you should now be able to call into the system and have VoiceGuide answer the incoming call and take the caller though the demo script set in Config.xml (the Credit Card Payment script).

Clicking VoiceGuide's IVR tray icon shows a context menu that allows user to control the VoiceGuide service, and start various VoiceGuide applications:

Testing VoiceGuide

Make a test call into the system as described before: by dialing the IP address of the system from VoIP phone, or from a softphone on another system.

VoiceGuide should answer the call and start the demonstration 'Credit Card Payment' script, which asks caller to enter some details (card number, amount etc.) and the plays the entered information back to the caller.

The demonstration script is located in VoiceGuide's \Scripts\Credit Card Payment\ subdirectory.

After you hear the demonstration script answer the call you are now ready to start creating your own scripts, make outgoing calls etc.
The Script Designer and other VoiceGuide applications can be started by right-clicking on the IVR tray icon and selecting from the context menu.

If not running as a user with Administrator privileges then you will not be able to stop and start the VoiceGuide service using the VoiceGuide Service Monitor applet from the icon tray.
To stop/start the VoiceGuide IVR service you will need to go to Control Panel -> System and Security -> Administrative tools -> Services

Configuring VoiceGuide

VoiceGuide configuration is set using the following files: VG.INI and Config.xml
VG.INI file is located in VoiceGuide's main directory.
Config.xml file is located in VoiceGuide's \conf\ subdirectory.

Config.xml is used to set what lines/channels are opened by VoiceGuide and what script is to be used when answering incoming calls on each of those lines/channels.

Sample Config files are provided showing how to set up the Config.xml file for larger systems.

If not running as Administrator then some permission changes may need to be made to allow editing of Config.xml, VG.INI, etc. files.

In Windows Explorer:

  1. Right click on the VoiceGuide directory
  2. Select Properties
  3. Go to the Security tab
  4. Make the necessary changes

Alternatively, the text editor application used to edit the Config.xml, VG.INI, etc. files would need to be started using the 'Run as administrator' option. Then Windows will not block the saving of new versions of Config.xml, VG.INI, etc. files.

Answering External Calls

VoiceGuide can 'register' itself with PBXs and VoIP Servers. Configuration of the registration parameters is made in Config.xml, in the VoIP_Registrations and VoIP_Authentications sections.

Please see the VoIP/SIP LINE REGISTER section of the manual for detailed information on how to configure VoiceGuide's SIP registration.

Setting Transport Protocol and Port

Default transport protocol is UDP. Most VoIP systems use UDP for SIP communications. If the VoIP systems with which VoiceGuide is to communicate use TCP instead, then VoiceGuide can be configured to use TCP by setting the following entry in VG.INI's [SIP] section:

E_SIP_DefaultTransport=ENUM_TCP

Port used can be set using the sip_signaling_port entry.

Firewall Configuration

Firewall needs to be set to allow incoming SIP and RTP packets from the SIP provider's IP addresses to these local ports:

5060, 5061 (UDP/TCP)
49150-60000 (UDP)

WireShark and Firewall logs are useful in debugging VoIP connectivity issues. If you are encountering problems with receiving IP communications from remote end you can try to temporarily disable the firewall to see if the issue is the firewall or some other routing issue.

Wav file format

Most VoIP service providers use uLaw in their G.711 connections.
Sound file format should match the encoding format used over the connection, hence if uLaw encoding is used then the sound files should be .WAV format with uLaw encoding (8kHz, 8 bit, Mono, uLaw).
And if ALaw encoding is used then the sound files should be .WAV format with ALaw encoding (8kHz, 8 bit, Mono, ALaw).

This will result in exact same bytes from the .WAV sound file to be sent in the outgoing RTP packets, and the exact bytes received over in the RTP stream will be saved into any recorded sound files.
This allows exact control over quality of sound played over the VoIP connection.

Installing Dialogic HMP

1. Starting the Dialogic HMP will show the following window:

2. Click Next to continue.

3. Click Next to accept the default install folder for program files.

4. Click Next to accept the default install folder for data files.

5. Check the Core Runtime Package option and then Click Next to continue.

6. Click Yes to accept installation of required 3rd-party software.

7. Click Next to accept the default program folder.

8. Click Next to accept the selected options and continue.

9. The computer must be rebooted after the installer is finished.
Select Yes, I want to restart my computer now and then click Finish.
The computer will now be restarted.

Installing Dialogic HMP License

1. Starting the Dialogic HMP License Manager will show the following window:

2. Click Browse, as indicated below:

3. Windows File Explorer window will open. Browse to and select your license file.
After the file was selected its path will be displayed in the "License File Name" text box:

4. Click Activate License. Window below will show advising what additional steps still need to be taken before the new license can be used.

5. Click OK and exit the License Manager.
The license will now need to be 'Assigned' as per the instructions in the last window.
Please continue with the "Assigning the Dialogic HMP License" instructions below:

Assigning the Dialogic HMP License

After selecting the new license in the HMP License Manager, the following steps need to be performed in the DCM:

1. From the Start menu, run the Dialogic Configuration Manager - DCM.
Ensure the Dialogic HMP service is stopped.
Click on the "HMP_Software" entry in the DCM to select it:

2. Click Device -> Restore Defaults menu.

3. The screen below will show:

4. Click Yes. The "Assign Firmware File" windows will open:

5. Select the license which you want to use and then click OK.
Another Window will open for a few seconds:

6. On completion the "Restore device defaults successful" message will be shown at the bottom of the DCM Window:

7. License has now been assigned and HMP is fully licensed.
You can now start the HMP service and the VoiceGuide service.


Installing VoiceGuide v7 for Traditional Telephone Lines (Analog/T1/E1)

Installing Dialogic Drivers

Dialogic Drivers (System Release) for use with VoiceGuide can be downloaded from the VoiceGuide Downloads page.
Please always refer to the Dialogic’s Release Notes and/or Installation Notes to determine what Operating System may be used.

The Dialogic card should be placed in system, and the telephone lines should be attached to the cards before the Dialogic System Release drivers are installed.
The Dialogic System Release Drives will detect the cards present in system upon installation.
Please refer to installation and configuration instructions for the board which is used.

Dialogic Drivers install asks user to select options to install. It is best to just select all the options available.

If using a 32-bit version of Windows, the Physical Address Extensions (PAE) need to be disabled. Dialogic install program will display an alert if it detects that PAE is enabled on system.

After installing the Dialogic System Release the machine needs to be restarted.

After restarting the system open the Dialogic Configuration Manager (DCM) and confirm that the Dialogic card has been dtected and that the Dialogic service can be started.

If the Dialogic card is not found by the Dialogic Configuration Manager (DCM) then check whether the card has been detected by the Windows' Device Manager.
If the Windows' Device Manager is showing a yellow exclamation mark next to the Dialogic card then you can try selecting the driver to be used by the card manually. To update the driver right-click on the Dialogic device in the Windows' Device Manager and the click Update Driver. Select to "Browse my Computer" for the correct driver, and browse to "C:\Program Files (x86)\Dialogic\driver\64-bit" folder. Then click Next and the Windows' Device Manager should find the right file and load the driver. The DCM should then be able to find the card when you reopen the DCM app.

If there are problems starting the Dialogic service please ensure that the Windows account used has sufficient privileges and the install was started using 'Ran as Administrator' option.
If there are still problems then please fully disable the Windows' User Access Control and then reinstall the Dialogic System Release drivers. Windows' User Access Control is disabled in the Windows Registry, by setting the EnableLUA parameter to 0.

After Installing Dialogic Drivers

Once Dialogic System Release Driver has been installed and the Dialogic Configuration Manager (DCM) can be started OK:

The Dialogic service should be set to start automatically. Use DCM 's Settings -> System/Device autostart -> Start System menu, or by using the Windows' Control Panel -> System and Security -> Administrative tools -> Services

Only after the Dialogic System Release drivers are installed on the system and the the Dialogic service is started can the VoiceGuide installation proceed.

Updating Dialogic Drivers

To install a new version of the Dialogic System Release you need to first fully uninstall the current version.
When un-installing please select the 'Do not save configuration' option, and restart system after uninstall.
You will then be able to install new version of the Dialogic System Release drivers.
After installing the Dialogic System Release the machine needs to be restarted.

Installing VoiceGuide

Dialogic System Release drivers must be installed first.

VoiceGuide needs to be installed using the Administrator account.

If not logged in as Administrator then right click on VoiceGuide install .EXE and select 'Run as administrator' :

The VoiceGuide installer will then start:

The Deployment Type needs to be set to:

Analog, T1/E1 ISDN

This will instruct VoiceGuide installer to set up configuration files for Analog/T1/E1 based systems that use traditional Dialogic cards:

Then select whether by default the system should use ULaw or Alaw format when recording files, and which format 'system sound files' should VoiceGuide use:

VoiceGuide will play back many different format sound files, and this selection will not restrict what sound files can be played, but this selection decides whether ULaw or Alaw format will be used when recording. Matching VoiceGuide's record sound format with the format used by telephone service provider results in best quality sound recordings.

Also, playing sound files in the same format as what the telephone service provider uses means that the files will not need to be transcoded or resampled when sent over the telephone service provider's network. This helps in achieving the best possible quality sound playback.

Next select the directory into which VoiceGuide should be installed.
If you select a directory other then the default directory then the VoiceGuide's Config.xml setting that specifies the callflow that is to be used on each channel will need to be updated with that directory details. (and VoiceGuide service restarted afterwards).

The files will then be installed:

When installation is complete the final screen will appear:

And the Script Designer will be started, loading the default demo callflow.
(The callflows/scripts to use are set in the Config.xml file):

The IVR icon will also appear in the icon tray at the bottom right of the screen.
Once the VoiceGuide Service starts a still green arrow will show on that icon:

If VoiceGuide was installed into the default directory you should not be able to call into the system and have VoiceGuide answer the incoming call and take the caller though the demo script set in Config.xml (the Credit Card Payment script).

Clicking VoiceGuide's IVR tray icon shows a context menu that allows user to control the VoiceGuide service, and start various VoiceGuide applications:

Configuring VoiceGuide

VoiceGuide configuration is set using the following files: VG.INI and Config.xml
VG.INI file is located in VoiceGuide's main directory.
Config.xml file is located in VoiceGuide's \conf\ subdirectory.

Config.xml is used to set what lines/channels are opened by VoiceGuide and what script is to be used when answering incoming calls on each of those lines/channels.

The default Config.xml file opens the first 4 ports of an analog Dialogic card. If an analog Dialogic card is installed then immediately after installing VoiceGuide you will be able to call into the system on any of the 4 ports and you will hear VoiceGuide answer the call and start a demonstration 'Credit Card Payment' script.

If a card other then a 4 port analog card is used then the Config.xml file in VoiceGuide's \conf\ subdirectory will need to be changed to match the card. Sample Config.xml files are provided in that directory as well, showing how Config.xml should be set if a card other then a 4 port analog card is used.

If not running as Administrator then permission changes may need to be made to allow editing of Config.xml, VG.INI, etc. files.

In Windows Explorer:

  1. Right click on the VoiceGuide directory
  2. Select Properties
  3. Go to the Security tab
  4. Make the necessary changes

Alternatively, the text editor application used to edit the Config.xml, VG.INI, etc. files would need to be started using the 'Run as administrator' option. Then Windows will not block the saving of new versions of Config.xml, VG.INI, etc. files.

After you hear the demonstration script answer the call you are now ready to start creating your own scripts, make outgoing calls etc.
The Script Designer and other VoiceGuide applications can be started by right-clicking on the IVR tray icon and selecting from the context menu.

If not running as Administrator then you will not be able to stop and start the VoiceGuide service using the VoiceGuide Service Monitor applet from the icon tray.
To stop/start the VoiceGuide IVR service you will need to go to Control Panel -> System and Security -> Administrative tools -> Services

Wav file format

When using VoiceGuide v7.x it is best if sound files used are uLaw or ALaw encoded (both 8kHz, 8 bit, Mono, in .WAV file).

uLaw or ALaw format is selected at install time.

Systems located in North America and Japan should use the uLaw format.

Systems located in the rest of the world use ALaw format.

These are the two formats used by telephone companies to transmit voice over the traditional Analog and T1/E1 connections, and using this sound format will result in little or no distortion of the sound when it is transmitted over the telephone service provider's network.


Installing VoiceGuide v6 for Traditional Telephone Lines (Analog/T1/E1)

NOTE: For new systems it is recommended that VoiceGuide v7 is used.

Installing Dialogic Software

We recommend using Dialogic's System Release 6.0 drivers.

VoiceGuide v6 will still work if Dialogic's System Release 5.1.1 + SR5.1.1SP1 drivers are used, but note that most of Dialogic's newest cards require System Release 6.0 drivers.

Please always refer to the Dialogic's Release Notes and/or Installation Notes to determine what Operating System may be used with these drivers.

The Dialogic card should be placed in system before the Dialogic System Release drivers are installed.

The Dialogic System Release Drives will detect the cards present in system upon installation.

The Dialogic service must then be started. This can be done using the Dialogic Configuration Manager (Windows' Start -> Dialogic) or using the Windows' Control Panel -> System and Security -> Administrative tools -> Services list.

The Dialogic service should be set to start automatically. Use DCM 's Settings -> System/Device autostart -> Start System menu, or by using the Windows' Control Panel -> Administrative tools -> Services

Only after the Dialogic System Release drivers are installed on the system can the Dialogic service is started can the VoiceGuide installation proceed.

Installing VoiceGuide

Dialogic System Release drivers must be installed and started before installing VoiceGuide v6(see above).

VoiceGuide v6.x comes pre-configured to be used with the first 4 ports of an analog Dialogic card.

If an analog Dialogic card is installed then immediately after installing VoiceGuide you will be able to call into the system and you will hear VoiceGuide answer the call and start a demonstration Credit Card Payment script.

Dialogic lines which VoiceGuide should be using are set in the Config.xml file.
Config.xml file is located in VoiceGuide's \Data\ subdirectory.

If a card other then a 4 port analog card is used then you will need to first change the Config.xml file in VoiceGuide's \data\ subdirectory before starting VoiceGuide. Sample replacement Config.xml files are provided in that directory as well, showing how Config.xml should be setup if a card other then a 4 port analog card is used.

After you hear the demonstration script answer the call you are now ready to start creating your own scripts. Refer to the Script Design section of the Help file.

Running VoiceGuide

Before running VoiceGuide you need to ensure that the Dialogic service has fully started. Confirming that the service status is 'Started' can be done using the Dialogic Configuration Manager (Windows' Start -> Dialogic) or using the Windows' Control Panel -> System and Security -> Administrative tools -> Services list.

Wav file format

When using VoiceGuide v6.x all sound files should be in format: PCM 8kHZ, 8 bit, Mono.


Installing VoiceGuide v5.x using TAPI/WAVE Devices

Please note that we do not recommend using voice modems. Voice modems are not really designed to implement professional IVR/Dialer/Voicemail systems.

Many voice modems have one or more of the following problems:

  • Poor sound quality/volume.
  • Unreliable DTMF tone detection.
  • Cannot do call transfers as hookflash length is too long or too short.
  • Mistakenly detect a disconnect tone while playing or recording messages and hangup a call halfway through playing/recording of sound file.
  • Unable to interrupt the playing of a sound file halfway through.

The sound quality of various modems varies greatly. In general external modems work better then internal modems.

As TAPI devices on the market change frequently we cannot provide a definitive list of current 'best' TAPI devices. We have found that the quality of sound playback and recording can vary between different versions of the same modem, and it will sometimes depend on which version of Windows the modems is installed. When selecting your voice modem we recommend trying a few modems if possible and choosing the best one. The problems faced by many users in finding an adequate sounding voice modem is the reason why many users opt to use telephony cards instead.

Voice modems can be used under Win98/ME, Win2000 and WinXP.

Please ensure that the device's Wave Driver has installed correctly. Without this driver installed VoiceGuide will not regard the device as as a Voice capable device. To check that the wave drivers are installed you will need to view the Windows Device Driver Manager.

Windows 9x/Me
  1. Open the Windows Control Panel
  2. Double click on the System Icon
  3. Click the Device Manager TAB
  4. Click the + next to Sound, video and game controllers.

Check if the "Wave Device for Voice Modem" driver appears.

Windows 2000/XP
  1. Open the Windows Control Panel
  2. Double click on the System Icon
  3. Click the Hardware TAB and Device Manager button
  4. Click the + next to Sound, video and game controllers.

Check if the "UniModem Half-Duplex Audio Device" driver appears.

If the wave drivers have not been installed for your voice modem then you should update or reinstall your modem drivers. You should also double check if the modem does in fact support voice (note: many 'speakerphone' modems do not support 'voice').

Running the Setup Wizard

The Setup Wizard will discover all the TAPI capable telephony devices and will allow you to select which devices you would like to use with VoiceGuide:

Next you need to select the Scripts which will be used by VoiceGuide when an incoming call arrives on the selected devices. To begin with we'd recommend you select the demonstration script in VoiceGuide's "/Scripts/Credit Card Payment" directory:

When Setup Wizard configuration has completed you should now be able to start VoiceGuide and call into the system to hear it answer the call and lead you through the selected VoiceGuide script.

You can open the "/Scripts/Credit Card Payment" in the Graphical Design Environment to see how the script has been put together.

Sound file format

When using a TAPI/WAVE device all sound files should be in format: PCM 8kHZ, 16 bit, Mono.


Installing v5.x (TAPI version) on systems using CAPI cards

VoiceGuide v5 can be used to control CAPI capable hardware.

Most CAPI capable cards are BRI ISDN cards which can support 2, 4 or 8 ports. If T1/E1 ISDN systems are considered then VoiceGuide v7 should be used.

Popular CAPI cards are:

AVM (Fritz!Card, B1, C2, C4, T1, Fritz!GSM, etc)

Eicon (BRI-2M, 4BRI-8M, etc)

Eicon cards also come with their own TAPI/Wave drivers, which can be used directly by VoiceGuide.

Some CAPI devices do not come with their own TAPI/Wave drivers, and in these cases in order for them to be able to be used by VoiceGuide a 3rd party product is needed: ComISDN, which is essentially a converter between the CAPI interface and TAPI/Wave interface, allowing programs that use the TAPI/Wave interface to work with any CAPI based hardware.

Install order

1. Install the CAPI hardware.

2. Download and Install the ComISDN TSP from https://n-g-media.com/, and configure it to control the CAPI hardware.

3. Install VoiceGuide (select the "TAPI" install option),

Configuring ComISDN

The ComISDN TSP can be configuration window is accessed using:

Open Start -> Settings -> Control Panel then click "Phone and Modem Options" or "Telephony", and then under "Advanced" or "Telephony Drivers", select "ComISDN Service Provider" and click "Configure".

The ISDN Interface Properties window will appear:

The main setting that needs to be confirmed as having been correctly set is the "Network audio protocol". If not set correctly the sound played will sound distorted.

To set the Network Audio Protocol select the Computer (root) and then click "Properties".

By default, ComISDN will use "u-Law" if it detected that the version of Windows installed is a US, Canadian or Japan one. For all other countries, it will use "A-Law".

If Windows has not been configured with the correct country setting then it is possible that this setting is incorrect and will need to be set manually. please ensure that it is set to "u-Law" if you are located in US, Canada or Japan, and set it to "A-Law" if you are located in other countries. It may also want to confirm with the telephone company or PBX supplier which protocol should be used - or just try them both and see which one sounds better.

Running the Setup Wizard

The Setup Wizard will discover all the TAPI capable telephony devices and will allow you to select which devices you would like to use with VoiceGuide:

Next you need to select the Scripts which will be used by VoiceGuide when an incoming call arrives on the selected devices. To begin with we'd recommend you select the demonstration script in VoiceGuide's "/Scripts/Credit Card Payment" directory:

When Setup Wizard configuration has completed you should now be able to start VoiceGuide and call into the system to hear it answer the call and lead you through the selected VoiceGuide script.

You can open the "/Scripts/Credit Card Payment" in the Graphical Design Environment to see how the script has been put together.

Wav file format

All sound files used on a VoiceGuide v5 system should be in format: PCM 8kHZ, 16 bit, Mono. Other file formats will not play.


SIP REGISTER

VoiceGuide can register itself with the SIP provider of choice, resulting in VoiceGuide receiving calls directed to registered telephone numbers and being able to place outgoing calls using the registered accounts.

The VoIP registrations are specified in the Config.xml file, in section <VoIP_Lines>

<VoIP_Lines> contains two sections: <VoIP_Registrations> and <VoIP_Authentications>.

<VoIP_Registrations> can contain multiple <VoIP_Registration> sections, and
<VoIP_Authentications> can contain multiple <VoIP_Authentication> sections.

Section <VoIP_Registration>:

<VoIP_Registration>
<Protocol>SIP</Protocol>
<RegServer>ServerAddress</RegServer>
<RegClient>RegisteredClient</RegClient>
<LocalAlias>LocalAlias</LocalAlias>
<Expires>Seconds</Expires>
</VoIP_Registration>

<Protocol> | Defaults to SIP if not set.
<RegServer> | IP address of the registration server or the domain name of the registration server. If domain name is specified then HMP will resolve the domain name to IP address before issuing the registration request. If domain name is used you must ensure that the DNS is configured to allow domin name to be resolved.
<RegClient> | RegClient is usually specified in one of the below formats: AuthUsername AuthUsername@Realm AuthUsername@RegServerIPAddress RegClient is used in the From: and the To: fields of SIP Register request.
<LocalAlias> | Local Alias is usually specified in one of the below formats telephone_number@local_ip_address telephone_number@local_host_name user@local_ip_address user@local_host_name The local_ip_address should be the public IP address as visible by the SIP Registrar. Value of LocalAlias is used in the Contact: field of SIP REGISTER request. If this is not set correctly then you may not get ACK returned by SIP Switch in the INVITE-OK-ACK exchange at start of call. NOTE: Some SIP Registrars ignore the Contact: field provided and set their own instead. In those cases the LocalAlias setting must match the Contact: field in the SIP Registrar's reply. The Contact: fields in SIP REGISTER requests and the replies must match in order for the SIP Registration to work. WireShark should be used to confirm contents of the SIP Registraton messages exchanged.
<Expires> | If set, this value is used in the Expires: field of SIP Register request. If this field is not set the default value of 60 seconds is used. Expiry settings are often overruled by SIP Registrar. HMP uses Expiry value as advised by SIP Registrar.

<VoIP_Authentication> holds information about the SIP digest authentication. It contains:

<VoIP_Authentication>
<Realm>Domain</Realm>
<Identity>AccountName</Identity>
<AuthUsername>AuthUser</AuthUsername>
<AuthPassword>AuthPassword</AuthPassword>
</VoIP_Authentication>

<Realm> | The "realm" for which this authentication applies. Leave blank if this athentication can be used for any realm. The "realm" is included by SIP Server/PBX in its "401-Unauthorized" / "407-Authentication Required" reponses in the 'Authenticate: Digest' field.
<Identity> | Account for which this authentication applies. Only set this field if you are registering multiple accounts with same SIP Registrar and require a different authentication to be used for each account. If specified then this authentication entry will only be used if Identity matches the To: field contents in the "401-Unauthorized" / "407-Authentication Required" response from the registration server.
<AuthUsername> | Username used for authentication.
<AuthPassword> | Password used for authentication.

The Dialogic HMP service must also be restarted after any changes to <VoIP_Registration> or <VoIP_Authentication> entries.
Dialogic HMP service restart is necessary to clear the old Registration/Authentication entries that have been previously loaded into HMP.
If Dialogic HMP service is not restarted then the previously loaded Registration and Authentication entries will take precedence.

WireShark can be used to confirm what SIP packets are exchanged between the SIP server and the VoiceGuide/HMP system. WireShark traces are usually necessary in determining causes of any registration failures.

SIP registration and authentication examples can be found in the Config.xml file. Information used for SIP registration is very similar for all SIP switches/providers.

Below are some examples as well:

CallCentric (www.callcentric.com)

<VoIP_Lines>

<VoIP_Registrations>
<VoIP_Registration>
<Protocol>SIP</Protocol>
<RegServer>callcentric.com</RegServer>
<RegClient>177711111111@callcentric.com</RegClient>
<LocalAlias>177711111111@10.1.1.9</LocalAlias>
</VoIP_Registration>
</VoIP_Registrations>

<VoIP_Authentications>
<VoIP_Authentication>
<Realm></Realm>
<Identity></Identity>
<AuthUsername>177711111111</AuthUsername>
<AuthPassword>Password</AuthPassword>
</VoIP_Authentication>
</VoIP_Authentications>

</VoIP_Lines>

Flowroute (www.flowroute.com)

The IP address in LocalAlias needs to be the publicly visible IP address of the system.

<VoIP_Lines>

<VoIP_Registrations>
<VoIP_Registration>
<Protocol>SIP</Protocol>
<RegServer>sip.flowroute.com</RegServer>
<RegClient>90427345@flowroute.com</RegClient>
<LocalAlias>90427345@145.37.125.84</LocalAlias>
</VoIP_Registration>
</VoIP_Registrations>

<VoIP_Authentications>
<VoIP_Authentication>
<Realm></Realm>
<Identity></Identity>
<AuthUsername>90427345</AuthUsername>
<AuthPassword>password01</AuthPassword>
</VoIP_Authentication>
</VoIP_Authentications>

</VoIP_Lines>

Asterisk / FreeSWITCH

The registration config below demonstrates how VoiceGuide would register to accept calls to a particular extension (ext 3000).

PBX was installed on another server on same local network. PBX server's IP address was: 10.1.1.11 VoiceGuide is installed on IP address 10.1.1.9

<VoIP_Lines>

<VoIP_Registrations>
<VoIP_Registration>
<Protocol>SIP</Protocol>
<RegServer>10.1.1.11</RegServer>
<RegClient>3000@10.1.1.11</RegClient>
<LocalAlias>3000@10.1.1.9</LocalAlias>
</VoIP_Registration>
</VoIP_Registrations>

<VoIP_Authentications>
<VoIP_Authentication>
<Realm></Realm>
<Identity></Identity>
<AuthUsername>3000</AuthUsername>
<AuthPassword>1234</AuthPassword>
</VoIP_Authentication>
</VoIP_Authentications>

</VoIP_Lines>

Skype Connect

<VoIP_Lines>

<VoIP_Registrations>
<VoIP_Registration>
<Protocol>SIP</Protocol>
<RegServer>sip.skype.com</RegServer>
<RegClient>99051000000000@sip.skype.com</RegClient>
<LocalAlias>99051000000000@sip.skype.com</LocalAlias>
</VoIP_Registration>
</VoIP_Registrations>

<VoIP_Authentications>
<VoIP_Authentication>
<Realm></Realm>
<Identity></Identity>
<AuthUsername>99051000000000@</AuthUsername>
<AuthPassword>Password</AuthPassword>
</VoIP_Authentication>
</VoIP_Authentications>

</VoIP_Lines>


T1 ISDN and E1 ISDN

Installing and Starting Dialogic T1/E1 cards

Please refer to installation instructions supplied with your card, and contact the card supplier if you encounter any issues starting the Dialogic service.

Dialogic's "Quick Install Card" document has information on how the various switches on the Dialogic card need to be set at card installation time.

It is recommended that at working T1/E1 trunk is attached to the card's RJ48C port before starting the Dialogic service. Otherwise the Dialogic service may not start. A 'loopback' connector may often be used instead of the working T1/E1 trunk.

Note: RJ48C connectors look the same as RJ45 connectors, but the wiring is different. RJ48C wiring uses pins 1 and 2 for "Receive from Network" channel, and pins 4 and 5 for "Transmit to Network" channel.

Selecting ISDN Protocol

The appropriate ISDN protocol in the Dialogic Configuration Manager (DCM) system needs to be selected. After selecting the appropriate ISDN protocol, and starting the Dialogic service the system should now be able to receive calls. Screenshot below shows where in the DCM the ISDN protocol is set for a JCT card:

The telephone company or PBX/Switch administrators will advise which ISDN protocols are available on the trunks they supply.

It is recommend that calls are presented on the trunk(s) in a 'round robin'/'circular' order. This would result in the incoming calls being evenly distributed across all available channels.

Usually the Dialogic cards are expected to be set up in 'User' mode.

Below table shows what protocol selection should be made for Dialogic JCT series cards:
T1 ISDN Protocol | Mode: User or Network | ISDN Protocol in JCT
QSIG-T1 | User | QTU
QSIG-T1 | Network | QTN
NI2 | User | NI2
NI2 | Network | NT1
4ESS | User | 4ESS
4ESS | Network | NT1
5ESS | User | 5ESS
5ESS | Network | NT1
DMS | User | DMS
DMS | Network | NT1

E1 ISDN Protocol | Mode: User or Network | ISDN Protocol in JCT
NET5 (Euro-ISDN) | User | CTR4
NET5 (Euro-ISDN) | Network | NE1
QSIG-E1 | User | QTE
QSIG-E1 | Network | QNT

Testing ISDN Line

The Dialogic ISDIAG.EXE application can be used to test the T1/E1 lines and obtain ISDN traces.

When using the "DMV" family cards. eg: DMV480, DMV600, etc. the Dialogic ISDNTRACE.EXE application can be used obtain ISDN traces.

Any ISDN traces captured can be converted into readable format using Dialogic's ISDTRACE.EXE utility.

ISDIAG

Dialogic provides the isdiag.exe command line application which will allow you to test if the ISDN connection is functioning and can capture the ISDN layer trace as well. Isdiag.exe will only work on 'Springware' Dialogic cards, ie. 'JCT' series cards. Isdiag.exe is located in directory C:\Program Files\Dialogic\bin

To test an E1 connection the isdiag.exe would usually be started like this at the DOS Command Prompt:

isdiag 1 1 e s v

To test a T1 connection the isdiag.exe would usually be started like this at the DOS command prompt:

isdiag 1 1 t s v

The examples above would allow user to receive and make calls on that first channel of first T1/E1 interface only. You will need to confirm with the Telco that they will send a call on that channel after the ISDN D channel is restarted.
ISDN's D channel is restarted when isdiag is restarted, or when Dialogic Service is restarted.

Screenshot below shows menu displayed when isdiag is started:

Isdiag displays current state of ISDN trunk at top right. All the error flags should be "0".

eg. if the number under DCH is "1" this indicates a D channel error (D channel not present).

VoiceGuide should not be started when using isdiag.exe, as isdiag.exe itself opens the channel on the ISDN trunk.

If you are unable to receive/make calls and play/record sound files with isdiag then you will need to contact your Dialogic supplier to establish why the hardware they provided does not work on your T1/E1 trunks. It is unlikely that VoiceGuide will work if isdiag cannot receive and make calls.

isdiag.exe can be used to capture traces of the ISDN messages as well. The log files produced by isdiag.exe need to be converted into human-readable form by using the isdtrace.exe application.

ISDNTRACE

Dialogic provides the ISDNTRACE.EXE application which can capture a trace of the ISDN messages. Isdntrace will only work on DM3/DMV type Dialogic cards. Isdntrace is located in Dialogic's \bin\ subdirectory.

The ISDN traces are used to confirm what ISDN parameters are sent by the Telco on that ISDN line, and to confirm what parameters are being sent out by VoiceGuide when an outbound call is made. The outgoing parameters should usually match what is sent by the Telco's switch.

To use isdntrace to obtain the trace of the ISDN layer messages please follow the following steps.

1. Stop VoiceGuide.

2. Restart Dialogic Service.

3. Start isdntrace using this command .

isdntrace -b0 -d1 -f c:\myisdnlog

4. Start VoiceGuide.

5. Make a call into VoiceGuide. Hangup after VoiceGuide answers.

6. Make a call out of VoiceGuide, loading the call using the "Outbound Call Loader".

7. After calls is ended press "q" in the isdntrace Command Prompt window to exit isdntrace.

8. Trace file would be created in C:\, name of file begins with "myisdnlog".

Configuring VoiceGuide

The channels which VoiceGuide is to use are specified in Config.xml file (see VoiceGuide's \conf\ subdirectory).

Sample Config.xml files are provided, and cover the most common deployment scenarios.

In the Config.xml file the Protocol just needs to be set to ISDN

It is recommended that all channels are opened: 23 on a T1 ISDN line, and 30 on an E1 ISDN line.

Some PBXs and Switches will not properly handle the calls unless all channels on the line are opened.

A sample ConfigLine.xml file for use with ISDN systems is also provided. Analog system related settings have been removed from that file, and ISDN related settings have been added in.

ISDN Outgoing Calls

Setting the ISDN protocol to the correct value is usually sufficient for outgoing calls to function as well. Some telephone companies however have specific non-standard requirements for outgoing calls.

This section outlines the configuration options available within VoiceGuide to allow the user to explicitly specify the individual settings on outgoing calls.

Most of these requirements relate to the structure and the information contained within the "Setup" message sent to the switch when a new call is made. VoiceGuide offers extensive control over the information sent within the Setup message, allowing easy configuration of the system to match requirements of the Telco switch or PBX.

The Setup message parameters are configurable using the ConfigLine.xml file, in section <ConfigLine><isdn><msgSetup>.

Below is an example of what this section looks like, with the default values set.

<isdn>
<msgSetup>
<defsrc>NONE</defsrc>
<defcc>
<cc_bc_xfer_cap>BEAR_CAP_SPEECH</cc_bc_xfer_cap>
<cc_bc_xfer_mode>ISDN_ITM_CIRCUIT</cc_bc_xfer_mode>
<cc_bc_xfer_rate>BEAR_RATE_64KBPS</cc_bc_xfer_rate>
<cc_usrinfo_layer1_protocol>ISDN_UIL1_G711ULAW</cc_usrinfo_layer1_protocol>
<cc_usr_rate>ISDN_NOTUSED</cc_usr_rate>
<cc_destination_number_type>NAT_NUMBER</cc_destination_number_type>
<cc_destination_number_plan>UNKNOWN_NUMB_PLAN</cc_destination_number_plan>
<cc_destination_sub_number_type>OSI_SUB_ADDR</cc_destination_sub_number_type>
<cc_origination_number_type>NAT_NUMBER</cc_origination_number_type>
<cc_origination_number_plan>UNKNOWN_NUMB_PLAN</cc_origination_number_plan>
<cc_origination_phone_number></cc_origination_phone_number>
<cc_origination_sub_number_type>OSI_SUB_ADDR</cc_origination_sub_number_type>
<cc_origination_sub_phone_number></cc_origination_sub_phone_number>
<cc_facility_feature_service>ISDN_NOTUSED</cc_facility_feature_service>
<cc_facility_coding_value>ISDN_NOTUSED</cc_facility_coding_value>
</defcc>
<defgc>
<gc_destination_address></gc_destination_address>
<gc_destination_address_type>NAT</gc_destination_address_type>
<gc_destination_address_plan>UNKNOWN</gc_destination_address_plan>
<gc_destination_sub_address></gc_destination_sub_address>
<gc_destination_sub_address_type>UNKNOWN</gc_destination_sub_address_type>
<gc_destination_sub_address_plan>UNKNOWN</gc_destination_sub_address_plan>
<gc_origination_address></gc_origination_address>
<gc_origination_address_type></gc_origination_address_type>
<gc_origination_address_plan></gc_origination_address_plan>
<gc_origination_sub_address></gc_origination_sub_address>
<gc_origination_sub_address_type></gc_origination_sub_address_type>
<gc_origination_sub_address_plan></gc_origination_sub_address_plan>

<gc_chan_info_medium_id>1</gc_chan_info_medium_id>
<gc_chan_info_medium_sel>MEDIUM_PREF</gc_chan_info_medium_sel>

<gc_call_info_category>SUB_NOPRIOR</gc_call_info_category>
<gc_call_info_address_info>ENBLOC</gc_call_info_address_info>
<gc_ext_data></gc_ext_data>
</defgc>
</msgSetup>
</isdn>

The <defsrc> setting selects whether the "CC" or "GC" approach (or neither) will be used to configure Setup message. Both approaches set almost the same information, but some Dialogic cards require the use of CC approach and some require the GC approach, which is why the option to use one or the other is offered. Setting the <defsrc> filed to NONE should always be tried first. This will result in the default settings for the selected ISDN protocol being used - the protocol set in Dialogic's Configuration Manager (DCM).

The DM3/DMV series cards can only use the "GC" setting parameters.

Settings used for individual fields within the <ConfigLine><isdn><msgSetup> section are detailed below:

Valid Settings

Field | Values
defsrc | CC, GC, NONE
cc_bc_xfer_cap | BEAR_CAP_SPEECH, BEAR_CAP_UNREST_DIG, BEAR_REST_DIG
cc_bc_xfer_mode | ISDN_ITM_CIRCUIT
cc_bc_xfer_rate | BEAR_RATE_64KBPS, BEAR_RATE_128KBPS, BEAR_RATE_384KBPS, BEAR_RATE_1536KBPS, BEAR_RATE_1920KBPS, PACKET_TRANSFER_MODE
cc_usrinfo_layer1_protocol | SDN_UIL1_CCITTV.110, ISDN_UIL1_G711ULAW, ISDN_UIL1_G711ALAW, ISDN_UIL1_G711ADPCM, ISDN_UIL1_G722G725, ISDN_UIL1_H261, ISDN_UIL1_NONCCITT, ISDN_UIL1_CCITTV120, ISDN_UIL1_CCITTX31
cc_usr_rate | ISDN_UR_EINI460, ISDN_UR_56000, ISDN_UR_64000, ISDN_UR_134, ISDN_UR_12000
cc_destination_number_type | EN_BLOC_NUMBER, INTL_NUMBER, NAT_NUMBER, LOC_NUMBER, OVERLAP_NUMBER
cc_destination_number_plan | UNKNOWN_NUMB_PLAN, ISDN_NUMB_PLAN, TELEPHONY_NUMB_PLAN, PRIVATE_NUMB_PLAN
cc_destination_sub_number_type | OSI_SUB_ADDR, USER_SPECIFIED_SUB_ADDR, IA_5_FORMAT
cc_origination_number_type | EN_BLOC_NUMBER, INTL_NUMBER, NAT_NUMBER, LOC_NUMBER, OVERLAP_NUMBER
cc_origination_number_plan | UNKNOWN_NUMB_PLAN, ISDN_NUMB_PLAN, TELEPHONY_NUMB_PLAN, PRIVATE_NUMB_PLAN
cc_origination_phone_number | Default CallerID phone number for outgoing calls made using this channel can be specified here.
cc_origination_sub_number_type | OSI_SUB_ADDR, USER_SPECIFIED_SUB_ADDR, IA_5_FORMAT
cc_origination_sub_phone_number | Default CallerID phone sub-number for outgoing calls made using this channel can be specified here
cc_facility_feature_service | ISDN_NOTUSED, ISDN_FEATURE, ISDN_SERVICE
cc_facility_coding_value | ISDN_CPN_PREF, ISDN_SDN, ISDN_BN_PREF, ISDN_ACCUNET, ISDN_LONG_DIS, ISDN_INT_800, ISDN_CA_TSC, ISDN_ATT_MULTIQ
gc_destination_address_type | TRANSPARENT, NAT, INTL, LOC, IP, URL, DOMAIN, EMAIL
gc_destination_address_plan | UNKNOWN, ISDN, TELEPHONY, PRIVATE
gc_destination_sub_address_type | UNKNOWN, OSI, USER, IA5
gc_destination_sub_address_plan | UNKNOWN
gc_origination_address | Default CallerID phone number for outgoing calls made using this channel can be specified here.
gc_origination_address_type | TRANSPARENT, NAT, INTL, LOC, IP, URL, DOMAIN, EMAIL
gc_origination_address_plan | UNKNOWN, ISDN, TELEPHONY, PRIVATE
gc_origination_sub_address | Default CallerID phone sub-number for outgoing calls made using this channel can be specified here.
gc_origination_sub_address_type | UNKNOWN, OSI, USER, IA5
gc_origination_sub_address_plan | UNKNOWN
gc_chan_info_medium_id | Specifies the timeslot to be connected.
gc_chan_info_medium_sel | MEDIUM_PREF, MEDIUM_EXCL
gc_call_info_category | SUB_NOPRIOR, SUB_PRIOR, MAINT_EQUIP, COIN_BOX, OPERATOR, DATA, CPTP, SPECIAL, MOBILE, VPN
gc_call_info_address_info | ENBLOC, OVERLAP

VoiceGuide ISDN Tracing

VoiceGuide can also initiate a trace the ISDN D-channel messages.

A file titled ktTelControl_TraceSelect.txt needs to be placed in "C:\" with the contents of the file indicating which Dialogic's board D-channel is to be traced.

Example contents should be:

isdn_trace_dtiB1

which indicates which interface board should have it's D-channel traced.

VoiceGuide will create the traces in "C:\", with the trace files named in this format: isdn_trace_dtiB1_0325_203334.log

Traces can be converted into readable format using Dialogic's ISDTRACE.EXE utility.


T1 and E1 using RobbedBit/CAS/R2 Protocols

Installing and Starting the Dialogic T1/E1 cards

Please refer to installation instructions supplied with your card, and contact eh card supplier if you encounter any issues starting the Dialogic service.

It is recommended that at working T1/E1 trunk is attached to the card's RJ45 port before starting the Dialogic service. Otherwise the Dialogic service may not start. A 'loopback' connector may often be used instead of the working T1/E1 trunk.

JCT series Dialogic cards

To configure the Dialogic "JCT" series T1/E1 cards to work with a Robbed Bit or CAS or R2 type line the following steps must be taken:

  1. The Parameter File must be specified in the Dialogic Configuration Manager.
  2. Config.xml file must have the correct protocol specified in the <Protocol> field.
  3. Optionally Dialogic's spandti.prm and voice.prm configuration files may need to be edited

Screenshot below shows where in the DCM the Parameter File is set:

The example screenshot above shows the r2_300.prm file being used on the E1 line.

A common setting for the T1 Robbed Bit lines is us_240.prm

More information on the various configuration options which can be used to configure the "JCT" series cards can be found in this Dialogic help file: springware_config_win_v1.pdf

DMV series Dialogic cards

To configure the Dialogic "DMV" series T1/E1 cards to work with a Robbed Bit or CAS or R2 type line the protocol family is chosen in the "Trunk Configuration" tab in the Dialogic's Configuration Manager.

The specific protocol (eg: pdk_us_mf_io ) is the specified in the VoiceGuide's Config.xml file, in the <Protocol> field.

More information on the various configuration options which can be used to configure the "DMV" series cards can be found in this Dialogic help file: dm3_pci_config_win_v1.pdf

Information on the various diagnostics programs which can be used to debug the DMV cards' operation can be found in this Dialogic help file: dm3_diagnostics_win_v7.pdf

Configuring VoiceGuide

The channels which VoiceGuide is to use are specified in Config.xml file (see VoiceGuide's \conf\ subdirectory).

Sample Config.xml files are provided, and cover the most common deployment scenarios.

In the Config.xml file the Protocol files needs also needs to be set to the Dialogic protocol file which has been designed to work with the type of protocol used on the line. Common setting is pdk_us_mf_io for T1 Robbed Bit lines. The protocol .cdp files can be edited to change the Dialogic card behavior. Refer to Dialogic documentation for information on .cdp file structure and their fields.


Configuring Text to Speech (TTS)

Only the Trial and Enterprise versions of VoiceGuide support Text to Speech (TTS).
The Professional version of VoiceGuide does not support TTS.

VoiceGuide can use:

  • SAPI compatible TTS engines
  • Google Cloud Platform TTS engines
  • MRCPv2 TTS engines
  • Native integrations to select TTS engines also supported

Please contact sales@voiceguide.com to discuss which TTS engine would best suit your requirements.

SAPI

To use SAPI TTS engine, the EngineType entry in VG.INI's section [TTS] must be set to SAPI:

[TTS]
EngineType=SAPI

And the SAPI_Engine entry needs to be set to the SAPI TTS Engine to use. eg:

[TTS]
SAPI_Engine=Cepstral Allison-8kHz

List of SAPI TTS engines installed on the system is saved in the ktTts trace log file.
The ktTts trace log file is created in VoiceGuide's \log\ subdirectory.
The section that lists all SAPI TTS engines installed on the system looks something like this:

124244.953 2812 tts voice 0 : Microsoft Mary
124244.953 2812 tts voice 1 : Microsoft Mike
124244.953 2812 tts voice 2 : Microsoft Sam
124244.953 2812 tts voice 3 : Cepstral Allison-8kHz
124244.953 2812 tts voice 4 : Sample TTS Voice

 The name of the engine is listed after the "tts voice X : " tag.
The example listing above shows that the following TTS engines are installed on the system:

Microsoft Mary
Microsoft Mike
Microsoft Sam
Cepstral Allison-8kHz
Sample TTS Voice

so any of the above can be specified as the value of the SAPI_Engine entry in the VG.INI file.

Format of the WAV file which the SAPI TTS engine should generate can be set in VG.INI, section [TTS], field SpStreamFormat. eg:

[TTS]
SAPI_SpStreamFormat=8khz8

The above "8khz8" entry is used to request that SAPI TTS generates 8kHz 8-bit PCM WAV files.
Other possible settings are:

8khz8
8khz16
11khz8
11khz16
16khz8
16khz16
alaw_8
ulaw_8

NOTE: SAPI SDK's TTSApp application should not be used to determine whether VoiceGuide can use the installed SAPI TTS engine.
Indeed it is possible for SAPI SDK's TTSApp application to fail in generating the TTS, while VoiceGuide service still being able to use that SAPI TTS engine successfully.

Google Cloud Platform

To use Google Cloud's TTS engine the VG.INI [TTS] EngineType entry must be set to:

EngineType=Google

Full path to the Google Cloud Platform's Credentials file must then be specified in the VG.INI [GCP] CredentialsFile setting. eg:

CredentialsFile=C:\SomeDirectory\IVRTTS1-e79d6258b5fd.json

The Voice to use can be selected using TTS_LanguageCode, TTS_SsmlGender and TTS_Name settings. eg:

TTS_LanguageCode=en-US
TTS_SsmlGender=Female
TTS_Name=en-US-Wavenet-C

If TTS_Name is left blank Google will chose a voice based on the TTS_LanguageCode and TTS_SsmlGender settings.
Google has multiple voices for most TTS_LanguageCode/TTS_SsmlGender combinations.
Setting TTS_Name allows selecting a specific voice from the many options available.
Please refer to Google's documentation for valid TTS_Name options.
VoiceGuide's vgEngine trace file will also show the list available Google Cloud voices.

eg. Possible TTS_Name settings for en-US Female voices are:
en-US-Wavenet-C, en-US-Wavenet-E, en-US-Wavenet-F, en-US-Standard-C, en-US-Standard-E

The above settings can be changed at any time during the call by setting corresponding $RVs to new value:

TTS_SsmlGender : $RV[TTS_GCP_SsmlGender]
TTS_LanguageCode : $RV[TTS_GCP_LanguageCode]
TTS_Name : $RV[TTS_GCP_Name]

Note that when using Google TTS, network delays between IVR system and Google's servers may result in slight delay before TTS is played. This delay is usually under 1 second.

MRCP / MRCPv2

To use MRCP/MRCPv2 TTS engines the VG.INI [TTS] EngineType entry must be set to:

EngineType=MRCP

Other required settings are MRCP_Profile and MRCP_Language

The MRCP Profile and Language etc can be dynamically set during the call, by setting new values to $RVs:

$RV[tts_MRCP_Profile]
$RV[tts_MRCP_Language]

Please contact VoiceGuide for detailed instructions on setting up MRCP based TTS engines and profiles.

Dynamically changing TTS Engine

The TTS Engine type used can also be dynamically set during the call, by setting new values to $RV:

$RV[tts_EngineType]

This allows the script to dynamically select which TTS engine type should be used at any time during the call.
The voices to be used by each engine can also be dynamically set during the call, as outlined in previous sections.

VoiceGuide v5 / v6

For VoiceGuide v5/v6 the default SAPI TTS voice can be set using the Speech applet from the Windows Control Panel:

If the Speech applet above cannot be seen in the Control Panel then it can be found in this location:
C:\Program Files\Common Files\Microsoft Shared\Speech\sapi.cpl

On VoiceGuide v5/v6 systems the SAPI TTS engine installation can be verified by using the SAPI SDK's TTSApp program:

Start -> Programs -> Microsoft Speech SDK 5.1 -> Tools -> TTSApp

Then select the TTS engine and press the "Save to .wav" button.
If the .WAV file was created and contains TTS generated sound data then the SAPI TTS engine is usable by VoiceGuide v5/v6.


Call Transfers and Conferencing

VoIP - SIP

VoiceGuide supports SIP REFER transfers (RFC 3515).

'Tromboned' type transfers are also supported, where VoiceGuide will dial out on another line and connect the two calls together. Using the 2-line-conference type transfer lets VoiceGuide monitor the conversation and react to any selections made during the connection. Afterwards the conference is ended VoiceGuide can take both parties through further separate IVR scripts.

T1, E1, ISDN Trunks

VoiceGuide supports ISDN 'Two B Channel' Transfers (TBCT)

'Tromboned' type transfers are also supported, where VoiceGuide will dial out on another line and connect the two calls together. Using the 2-line-conference type transfer lets VoiceGuide monitor the conversation and react to any selections made during the connection. Afterwards the conference is ended VoiceGuide can take both parties through further separate IVR scripts.

Traditional Analog Lines and 'Robbed Bit' T1 and E1

VoiceGuide can do call transfers on traditional telephone lines in a number of different ways. Most common type of transfer is called a "hookflash transfer". To do this transfer manually from a telephone handset the operator usually just presses the 'flash' button, then dials the telephone number to which the call is to be transferred and then hangs up.

When using hookflash transfers some systems will require you to wait until the destination answers the call before being able to hang up, and some systems will require you to wait only until the destination extension is ringing before hanging up. Some systems will allow you to hangup straight away. Some systems do not support hookflash transfers at all and in such cases you'll need to make a call on another line and have VoiceGuide connect the incoming and outgoing calls together internally to route the call to a new number. These are called 'Tromboned' transfers.

The Help file's section on the Call Transfer module lists all the different ways in which VoiceGuide can do call transfers.

Before trying to get VoiceGuide to do the transfers it's best to first establish exactly how transfers can be made on your system. Note down step by step what needs to be done and what buttons need to be pressed on your system to make the transfer happen if you just use a telephone handset yourself. Once this is all established you can then go ahead and configure VoiceGuide to do exactly the same things to effect a transfer.

VoiceGuide comes with pre-programmed settings for signals which your PBX or Telephone Network uses to place calls on hold and to forward or conference calls which work for most PBXs, but your PBX / Telephone Network may require different settings. If you do not know what those signals are, you will probably need to ask your PBX supplier or call your Telephone Company.

On almost all systems the 'hookflash' (also known as 'flash') signal is used in one way or another. Hookflash is just the action of hanging up the call on-hook for a very short time and then picking up the handset again. The length of the hookflash required differs from system to system - the length used by your Modem or Telephony Card will have to match that required by your PBX / Telephone Network, otherwise the transfers/conferences will not work. If the hookflash is set too short then it will not be noticed by the PBX (the caller will just hear a short click on the line) and if the hookflash is set too long then the PBX will interpret it as a receiver hanging up and will end the call (the caller will then hear just silence or a disconnect tone) and the extension dialed afterwards may be treated by the PBX/Switch as a new call. Note that if the PBX/Switch treats the dialed extension as a new call then the dialed extension number may ring. The time of ringing can be very short (if blind transfer is used) or until the call is answered or times out (if monitored or announced transfer is used).

Most modems cannot vary the length of their hookflash, and if their default length does not match the length required by your PBX / Telephone Network then you will not be able to use that modem to transfer/conference calls.

Telephony Cards allow the hookflash length to be set by the user – ensuring that a Telephony Card can be configured to allow it to successfully perform call transfers and conferencing. This is why it is highly recommended to use a Telephony Card if your application needs to do call transfers / conferencing.

Setting PBX control strings

In VoiceGuide Script Designer click on the Edit menu and select PBX Command Strings.

The signals sent to your PBX or Telephone Network can be configured here. VoiceGuide will generate the specified signals to command the PBX / Telephone Network to perform call transfers and conferences.

The "!" character represents a hookflash.

The screen capture above shows a typical configuration which should work for many systems. You should confirm that these settings are OK with your PBX supplier or your Telephone Company, and change them if your PBX supplier or your Telephone Company indicates that they should be changed.

After changing the PBX strings VoiceGuide will need to be restarted to read in the new settings.

If hookflash transfer is not working

If you are encountering problems performing a hookflash transfer please try the following:

Step 1 : Is it possible to do a Hookflash transfer on that line ?

Try attaching a normal analog telephone handset to the line and see if you are able to perform the transfer by just pressing the 'Flash' button and then dialing the destination extension number. If the PBX/Switch does play the dial tone after the hookflash is pressed the it is possible to perform hookflash transfers on that line. After confirming the Switch/PBX react to a hookflash try dialing the transfer destination number and confirm if the dialed number starts ringing (the original caller should be on hold all this time - and usually hearing some on-hold music). Next see if the destination extension will keep ringing if you hang up the phone. If it does keep on ringing after the party performing the transfer hangs up then it looks like you are able to do a "Blind Hookflash Transfer". If the destination extension stops ringing when you hangup the phone then it looks like on this system the destination extension needs to be answered before the extension performing the transfer hangs up - so only monitored or Announced hookflash transfers will work.

If you have verified that it is possible to perform hookflash transfers on the line you are using then you can now move onto confirming if the telephony device used by VoiceGuide is issuing the correct length hookflash.

Step 2 : Is the hookflash length correct ?

Use the VoiceGuide script to answer the original call and use the Call Transfer module to attempt a call transfer. If the hookflash is set too short then it will not be noticed by the PBX (the caller will just hear a short click on the line and will not be put on hold) and if the hookflash is set too long then the PBX will interpret it as a receiver hanging up and will end the call (the caller will then hear just silence or a disconnect tone) and then when the hookflash finishes it will be interpreted by the PBX/Switch as the line going off-hook and treated by the PBX/Switch as a new call (not a transfer), with the extension dialed afterwards just treat as a the number dialed on this new call.

Step 3 : Is the PBX/Switch correctly receiving the transfer destination number ?

It is also possible that there is not enough delay between the hookflash and the dialed extension, in which case the leading dialed digit(s) may not be detected by the PBX/Switch, so the PBX/Switch will have an incomplete number to dial. VoiceGuide leaves enough of a pause between hookflash and dialed number to not let this happen but if you think this may be occurring then you can add one or more commas before the extension number, like this:

,1234

Each comma usually represents a delay of around 2 seconds. You can also use a Play module to issue the hookflash followed pause(s) and extension number. To do a hookflash transfer to extension 1234 the following may be specified in a Play module: !,1234 or !,,1234 etc.

Setting Hookflash Length

When using VoiceGuide for Dialogic the hookflash length is set in Config.xml file, in the Parameters_DxBd section. The following section of Config.xml should be edited:

<Parameters_DxBd>
...
<Parameter>
<Description>Flash time during dialing (10ms units)</Description>
<Key>DXBD_FLASHTM</Key>
<Value>10</Value>
<Default>10</Default>
</Parameter> ...
</Parameters_DxBd>

A setting of 10 means 100ms. The setting is in 10ms units.

Setting Hookflash length on Dialogic cards using the .PRM file

Determine which parameter file is used by the Dialogic Configuration Manager and then change the hookflash length specified in that parameter file.
The release/installation notes which came with the card should inform you what Parameter File you should be specifying in the DCM - if you do not have the release notes then contact the supplier and they should be able to advise you which .PRM file to use.
If you have not specified the parameter file explicitly in the Dialogic DCM's "ParameterFile" setting then you can determine which parameter file is being used based on what "Country" is specified. The filename of the parameter file loaded for a D/4PCI is xx_d4p.prm where "xx" is based on what country is selected.
Eg: If country setting is "Australia/NZ" then the prefix is "an" and the parameter file for a D/4PCI is an_d4p.prm

You will need to change the line:

# PARAM 52:(DECIMAL WORD) 50 # Hook Flash/earth recall duration
to:

PARAM 52:(DECIMAL WORD) 10 # Hook Flash/earth recall duration
ie: remove the # at the beginning and change 50 to 10. Parameter is in 10ms units, so a setting of 10 will indicate 100ms.

Dialogic service must be restarted to read in the parameter file.


Configure Databases and Data Sources

VoiceGuide can interact with any database or data source.
Any .NET Data Provider, ODBC Source or OLE DB can be used.

.NET and OLE DB Databases and Data Sources

Only a valid Connect String needs to be specified. No other configuration is needed.
A good resource for connection strings is: https://www.connectionstrings.com/

ODBC Data Sources

If using the ODBC interface the ODBC driver should be specified in the Connect string, or an ODBC data source must be configured in Windows.

Note that for VoiceGuide v7 and later it is preferable to use the ADO.NET Data Provider, as this method is usually faster then using ODBC approach.

If using ODBC you must ensure that the 32-bit ODBC driver for your database has been installed.
VoiceGuide is a 32-bit application and needs to use 32-bit ODBC drivers (not 64-bit ODBC drivers).

Two versions of the ODBC Administrator

There are two versions of the ODBC Administrator on current versions on Windows.
A 32-bit version and 64-bit version.

The 32-bit version is at: C:\Windows\SysWoW64\Odbcad32.exe
(64-bit version is at: C:\Windows\System32\Odbcad32.exe)

You must use the 32-bit version of ODBC Administrator when creating the ODBC connections.
Only the 32-bit ODBC drivers and DSNs set up using the 32-bit ODBC Administrator are accessible to 32-bit applications.
(VoiceGuide is a 32-bit application).

Please read this: http://support.microsoft.com/kb/942976 for more information.

On older 32-bit versions of the Windows the ODBC Administrator can be opened from the Control Panel.

The ODBC Data Source Administrator looks like this:

Select the 'System DSN' tab.
The ODBC DSNs need to be created as a "SYSTEM" type DSNs in order to allow them to be accessible from Windows Services.
(VoiceGuide runs as a Windows Service),

After clicking the the 'Add' button you will be asked to select the ODBC driver to use:

Select the driver which corresponds to the database you want to add, and press Finish.
Your database's ODBC Driver should now take you through the rest of the Data Source setup process - the options presented in this stage will be different for each different database source. Please consult your database user's manual for further instructions.

(If your database's driver is not listed then you should exit and install your database's ODBC drivers first)

If for example we select to use the ODBC Driver provided for MS Access then that driver's configuration screen will show next:

In the example above we selected an Access database Products.mdb and have called our Data Source 'Products'. Further parameters (eg database's password) can be set using the 'Advanced' options button.

Each different database type will have a different configuration screen. eg. the MS SQL Server's ODBC configuration screen looks like this:

After setting up the new ODBC Data Source, it will appear in the list of System Data Sources:

This ODBC Data Source is now ready to be used.

The Database Query module can be used to access ODBC Data Sources from a VoiceGuide script, or you can use the Data Access components from the Run VBScript module


Tone Detection

When used on analog lines it is important to ensure that the system correctly detects the various tones played on the line: busy, disconnect, etc.

Setting tone specifications can be done in VoiceGuide's 'Tone Config File', or on Dialogic driver level using .TSF files. Tone files are set on a per-line basis in VoiceGuide's Config.xml file.

VoiceGuide's Tone Config File (XML)

When using this approach do not specify a TSF file in Dialogic's DCM. TSF settings take precedence over the 'Tone Config File' definitions.

Audacity http://www.audacityteam.org/ can be used to determine the frequencies and cadences of the tones played from the tone recordings.

Sample tone file :

<?xml version="1.0" encoding="iso-8859-1"?>
<Tones>

<Tone ID="TID_BUSY1">
<Notes>Australia Telstra</Notes>
<Freq1>425</Freq1>
<Freq1Dev>50</Freq1Dev>
<Freq2>0</Freq2>
<Freq2Dev>0</Freq2Dev>
<On>37</On>
<OnDev>5</OnDev>
<Off>37</Off>
<OffDev>5</OffDev>
<Count>2</Count>
</Tone>

<Tone ID="TID_BUSY2">
<Notes>General US Tone</Notes>
<Freq1>500</Freq1>
<Freq1Dev>200</Freq1Dev>
<Freq2>525</Freq2>
<Freq2Dev>175</Freq2Dev>
<On>50</On>
<OnDev>40</OnDev>
<Off>50</Off>
<OffDev>40</OffDev>
<Count>4</Count>
</Tone>

<Tone ID="TID_DIAL_LCL">
<Notes>General US Tone</Notes>
<Freq1>400</Freq1>
<Freq1Dev>125</Freq1Dev>
<Freq2>0</Freq2>
<Freq2Dev>0</Freq2Dev>
<On>0</On>
<OnDev>0</OnDev>
<Off>0</Off>
<OffDev>0</OffDev>
<Count>0</Count>
</Tone>

<Tone ID="TID_DIAL_INTL">
<Notes>General US Tone</Notes>
<Freq1>400</Freq1>
<Freq1Dev>125</Freq1Dev>
<Freq2>0</Freq2>
<Freq2Dev>0</Freq2Dev>
<On>0</On>
<OnDev>0</OnDev>
<Off>0</Off>
<OffDev>0</OffDev>
<Count>0</Count>
</Tone>

<Tone ID="TID_DIAL_XTRA">
<Notes>General US Tone</Notes>
<Freq1>400</Freq1>
<Freq1Dev>125</Freq1Dev>
<Freq2>0</Freq2>
<Freq2Dev>0</Freq2Dev>
<On>0</On>
<OnDev>0</OnDev>
<Off>0</Off>
<OffDev>0</OffDev>
<Count>0</Count>
</Tone>

<Tone ID="TID_DISCONNECT">
<Notes>Australia Telstra Disconnect Tone</Notes>
<Freq1>425</Freq1>
<Freq1Dev>50</Freq1Dev>
<Freq2>0</Freq2>
<Freq2Dev>0</Freq2Dev>
<On>37</On>
<OnDev>5</OnDev>
<Off>37</Off>
<OffDev>5</OffDev>
<Count>2</Count>
</Tone>

<Tone ID="TID_FAX1">
<Notes>Fax Tone 1</Notes>
<Freq1>2150</Freq1>
<Freq1Dev>50</Freq1Dev>
<Freq2>0</Freq2>
<Freq2Dev>0</Freq2Dev>
<On>25</On>
<OnDev>25</OnDev>
<Off>0</Off>
<OffDev>0</OffDev>
<Count>0</Count>
</Tone>

<Tone ID="TID_RNGBK1">
<Notes>Ringback 1</Notes>
<Freq1>438</Freq1>
<Freq1Dev>138</Freq1Dev>
<Freq2>0</Freq2>
<Freq2Dev>0</Freq2Dev>
<On>130</On>
<OnDev>105</OnDev>
<Off>580</Off>
<OffDev>415</OffDev>
<Count>0</Count>
</Tone>

<Tone ID="TID_RNGBK2">
<Notes>Ringback 1</Notes>
<Freq1>438</Freq1>
<Freq1Dev>138</Freq1Dev>
<Freq2>438</Freq2>
<Freq2Dev>138</Freq2Dev>
<On>130</On>
<OnDev>105</OnDev>
<Off>580</Off>
<OffDev>415</OffDev>
<Count>0</Count>
</Tone>

</Tones>

Dialogic's TSF File

For information on how to create a TSF file please see Dialogic's PBXpert utility. After creating the TSF file you will need to specify in Dialogic's DCM for the card to use the TSF file. Do this by setting the TSFFileName property (Files tab) to point to the filename. You will also need to enable the reading in of the file by setting the TSFFileSuppot property (Misc tab) to 'Yes'.


Detecting End of Call

On systems using VoIP - SIP or T1/E1 ISDN end of call is detectable by:

- End of call message.
- Timeout awaiting input from caller.
- Sometimes Disconnect tones are played.

On systems using Traditional Analog Lines end of call is detectable by:

- Disconnect tone on the line.
- Loop Current Drop on the line.
- Special DTMF tone played by PBX/Switch.
- Timeout awaiting input from caller.

End of Call Message
VoIP and ISDN systems can use digital signalling to immediately indicate end of call when the other party hangs up the handset.
This is the most reliable way of obtaining end of call indication, and is usually received immediately when remote party hangs up.
VoiceGuide will then end the script and hangup as well.
Note that some VoIP providers may not send the 'Disconnected'/'Bye' message.

Loop Current Drop
Loop current drop is used by some telephone companies and PBXs to indicate end of call.
Dialogic cards can detect loop current drop and VoiceGuide will immediately hang up the call when loop current drop occurs.

Timeout awaiting input from caller
When there is no response (keypresses etc.) from the caller within a certain time then VoiceGuide will hangup the call
(but if 'timeout' or 'fail' paths are defined in current module then those paths will be taken instead).

Disconnect Tone
A tone is usually played on the line when the other party hangs up. This tone is known as a 'disconnect tone'.
Some PBXs send a DTMF tone (usually tone "D") to indicate end of call.
Dialogic drivers come pre-programmed with sets tones that they will detect as 'end-of-call' tones, but can also be be configured for what disconnect tones to listen for.

Determining the Disconnect tone frequency and cadence :

To find out what disconnect tone is played by your telephone company when the other party hangs up you can use VoiceGuide's Record module.
Use a script with a Record module in it, and when the Record module starts recording just hang up. The recording will now include what is heard by the system after the other party hangs up.
Then analyze the frequencies using any of the more advanced sound editors

eg: when using Audacity (https://www.audacityteam.org/) :

1. Open the file in Audacity
2. Highlight the section of the sound file where the tone is present (the "ON" part of the tone)
3. Go to "View" menu and select "Plot Spectrum"
4. Note at what frequency the peak(s) is/are.
5. Highlight the entire section when tone is ON and check the interval, looking at the selection's timing data at bottom of Audacity's window.
6. Highlight the entire section when tone is OFF and check the interval, looking at the selection's timing data at bottom of Audacity's window.

Screenshot below shows Audacity with a disconnect tone with the ON part of the disconnect tone highlighted.
The Selection interval timing is displayed at the bottom of the window - in this case the ON part of the tone lasts about 250milliseconds (0.250 seconds).

Below screenshot shows the Frequency analysis window which is shown when Audacity's "View"-> "Plot Spectrum" menu is selected.

The peak is at 428Hz.

Screenshot below shows Audacity with a disconnect tone with the OFF part of the disconnect tone highlighted. The Selection interval timing is displayed at the bottom of the window - in this case the OFF part of the tone lasts about 750milliseconds (0.750 seconds).

Based on the above information the disconnect tone in he example above is a single tone of 428Hz which lasts about 250ms and then a period of silence which lasts about 750ms.

The recommended settings for Dialogic cards to detect this tone reliably would be:
Freq1: | 428
Freq1 dev: | 40
Freq2: | 0
Freq2 dev: | 0
On time: | 25
On time dev: | 5
Off time: | 75
Off time dev: | 5
Repetition count: | 3

When specifying the On/Off times (cadence times) for Dialogic the lengths of time are in units of 10milliseconds, so a value of 25 represents 250milliseconds.

For allowed variances (deviations) in frequency and time it's usually appropriate to use about 10% of the value for variance. For 'cadence' usually a value of 5 is OK (a value of 5 is 50 milliseconds). If trying to detect a continuous tone which does not have ON/OFF cadence you should set the "Repetition Count" to be 0 and the OFF time to 0 as well.

Setting tones in ConfigLine.xml :

The Disconnect tone must be set in ConfigLine.xml file which can be found in VoiceGuide's \data\ subdirectory.

The Tone definitions which should be edited is the DISCONNECT_USER_1 or DISCONNECT_USER_2 (DISCONNECT_TAPI1 or DISCONNECT_TAPI2 in VoiceGuide v6). The TID_DISCONNECT tone definition is only used on outbound calls, and it can also be changed if required.

An example entry in ConfigLine.xml:

<Tone Name="DISCONNECT USER 1">
<Notes>Disconnect Tone</Notes>
<ID>DISCONNECT_USER_1</ID>
<Freq1>428</Freq1>
<Freq1Dev>50</Freq1Dev>
<Freq2>0</Freq2>
<Freq2Dev>0</Freq2Dev>
<On>25</On>
<OnDev>5</OnDev>
<Off>75</Off>
<OffDev>5</OffDev>
<Count>3</Count>
</Tone>

DTMF Disconnect tones :

Detection of DTMF disconnect tones : VoiceGuide is configured by default to react to DTMF key "D" as an indication of disconnect. Selection of which DTMF tone should be used by VoiceGuide as a disconnection tone can be made in the [PBX] section of the VG.INI file.

In general Dialogic cards are pretty good at correctly detecting disconnect tones and if the tones are defined with low tolerance bands then the probability of false detections is low. If the tolerance bands however are set widely, allowing a wide range of tones and/or frequencies then false detections of disconnect tones can occur just while a person is speaking or a sound file is being played. As disconnect tone detections will result in the call being ended immediately it is imperative that the possibility of false detections is as low as possible.

One of the situations where disconnect tone definition parameters need to be set broadly is when a number of different disconnect tones needs to be detected. To setup the system to detect a variety of tones it would be necessary to record all the tones which you want the system needs to detect, analyze them with Audacity to find out the frequencies and timings and then come up with the one global setting which will be able to detect them all - keeping in mind that the broader the tolerances the higher the chance of false busy detections. In situations like these using T1/E1 ISDN lines would be a better solution.

NB. VoiceGuide allows for a different ConfigLine.xml file to be used for each channel - so each channel can have it's own tone configurations. Use <ConfigLine> tag within the <Channel> entry to specify the LinesConfig.xml file specific for that channel. eg:

<Channel>
<Name>dxxxB1C1</Name>
<Protocol>pdk_na_an_io</Protocol>
<RingsBeforeAnswer>0</RingsBeforeAnswer>
<script>C:\Scripts\MyScript.vgs</Script>
<AllowDialOut>1</AllowDialOut>
<ConfigLine>C:\MyConfigs\ConfigForUsCalls.xml</ConfigLine>
</Channel>

End of Call Detection: Special DTMF tone played by PBX/Switch

Some PBXs and Switches can be set up to play a DTMF tone on the line when the PBX/Switch detects that the other party has hung up. The DTMF tone chosen to indicate that is usually the "D" tone.

Most telephone handsets do not have the DTMF A, B, C and D tones on their keypad, so the callers cannot generate these tones themselves.

If the PBX or Switch is capable of generating DTMF tone at end of call then we highly recommend using this approach as it is a very reliable way of informing VoiceGuide immediately when the call has finished.

The DTMF Disconnect Tone for which VoiceGuide will listen and use as an indication of end of call can be set by selecting "PBX Command Strings" from the "Edit" menu in VoiceGuide Script Designer:


Distinctive Ringing

Some traditional analog phone lines (POTS lines) can be set up so that calls to 2 or more telephone numbers will be sent to them, with the recipient being able to tell which number was dialed by the different ring tone played when calls to different numbers arrive. These different ring types are called "Distinctive Ringing"

VoiceGuide can be setup to detect the different type of Ringing and make this information available to the script.

For VoiceGuide to detect the different rings, the cadences of the rings need to be specified in a ConfigLine.xml file. Here is the relevant section of that file with one ring tone defined.

<DistinctiveRings>
<DistinctiveRing>
<Name>TestPBXDoubleRing</Name>
<ID>TestPbxStandard</ID>
<Description></Description>
<Notes></Notes>
<Cadence>
<On>55</On>
<OnDev>10</OnDev>
<Off>55</Off>
<OffDev>10</OffDev>
</Cadence>
<Cadence>
<On>55</On>
<OnDev>10</OnDev>
<Off>285</Off>
<OffDev>10</OffDev>
</Cadence>
</DistinctiveRing>
</DistinctiveRings>

The time intervals are all specified in 10ms units. The above example shows the definition of a ring that is on for 550ms, the off for 550ms, then on again for 550ms and off for 2850ms, with the pattern repeating afterwards. This definition is loaded by VoiceGuide at startup, and incoming Ring signals (on analog lines) are compared to see if they match any of the definitions.

If a ring matches on of the definitions then the $RV[DISTINCT_RING] variable is set to hold the Name value of the ring definition entry. eg. if the ring matches the example definition above then VoiceGuide will set $RV[DISTINCT_RING] to hold a value of: TestPBXDoubleRing also $RV[DISTINCT_RING_TestPBXDoubleRing] will be set to hold a value of True

Note that VoiceGuide must be set to answer at the beginning of 3rd ring or later in order to be able to hear enough rings to match up their cadence with the example sequence. The 'answer after X rings' setting must always be at least 1 more then the number of Cadence entries in the DistinctiveRing definition.

Confirming the Distinct Ring cadence is loaded properly

Here is the relevant extract from the VoiceGuide log file showing the details of the cadence loaded by Voiceguide at startup.

074958.48 0 init load Distinct Ring definitions start [C:\Projects\vg32\data\ConfigLine.xml]
074958.49 0 init distinct ring definitions found:1
074958.49 0 init ring 1 [TestPBXDoubleRing] total cadences:2
074958.49 0 init distinct ring 1 [TestPBXDoubleRing] cadence 1 [55:10,55:10][110:20]
074958.49 0 init distinct ring 1 [TestPBXDoubleRing] cadence 2 [55:10,285:10][340:20]
074958.49 0 init load Distinct Ring definitions end

Relevant log section showing matching incoming ring

Here is the relevant extract from the VoiceGuide log file showing the details of the incoming call, the ring timings and VoiceGuide matching them against loaded cadence templates. At the end of the trace we can see VoiceGuide matched the cadence against the definition of ring tone, and has added $RV[DISTINCT_RING] to that line's RV set.

Note that with Dialogic cards the cadences are matched using ring rising edge timings. In the example below the rising edge of the second ring arrived 1200ms seconds after the rising edge of first ring, and the 3rd ring arrived 3430ms seconds after the rising edge of the second ring. This fell within the allowed 1st cadence of 900ms-1300ms and the allowed second cadence of 3200ms to 3600ms.

112418.28 1 ring 1
112418.28 1 ring time since last ring event (sec): 0.00
112418.28 1 rings=1, min rings before answer=4 (iCallerIdHasArrived=0)
112418.28 1 tw DialogicEvent 134,TDX_CST,0,0,0,DE_RINGS,ET_RON,
112418.28 1 event ScriptEventCode TDX_CST, code=134, state=0
112419.48 1 ring 2
112419.48 1 ring time since last ring event (sec): 1.20
112419.48 1 ring match against pattern 1, cadences=1
112419.48 1 ring template 1, cadence 1 = [110|20] edge time=1203.3
112419.48 1 ring match distinct ring pattern 1 cycle 1 ok
112419.48 1 rings=2, min rings before answer=4 (iCallerIdHasArrived=0)
112419.48 1 tw DialogicEvent 134,TDX_CST,0,0,0,DE_RINGS,ET_RON,
112419.48 1 event ScriptEventCode TDX_CST, code=134, state=0
112422.92 1 ring 3
112422.92 1 ring time since last ring event (sec): 3.43
112422.92 1 ring match against pattern 1, cadences=2
112422.92 1 ring template 1, cadence 1 = [110|20] edge time=120.3
112422.92 1 ring match distinct ring pattern 1 cycle 1 ok
112422.92 1 ring template 1, cadence 2 = [340|20] edge time=343.4
112422.92 1 ring match distinct ring pattern 1 cycle 2 ok
112422.92 1 ring full match ring pattern 1 (2 cadences)
112422.92 1 rv add [DISTINCT_RING]{TestPBXDoubleRing}

The ring timing marks : "ring time since last ring event" allow you to examine any new ring types' cadences and set the Distinctive Ring definitions accordingly.

Note that with Dialogic cards the cadences are matched using ring rising edge timings, so it is not really essential to correctly set the ON and OFF values, as long as the sum of the ON and OFF values within the cadence matches the time to the next ring rising edge. The <OnDev> and <OffDev> values are also summed to give the overall allowed time deviation.


Configuring Cisco Call Manager (Cisco Unified CM) connection to VoiceGuide

SIP Trunk Method

SIP Trunk is the appropriate approach for allowing multiple simultaneous calls to be routed between Cisco and VoiceGuide.

First a SIP Trunk must be set up, and then the Route to that SIP Trunk must be configured.

Create SIP Trunk

In Cisco Unified CM Administration select Device > Trunk from the top menu then click Add New to begin adding a new SIP trunk.

Set Trunk type to SIP Trunk

Set Device Protocol to SIP

Then click Next to continue.

On the new screen enter Device Name and Description and select the Device Pool (Default is usually fine).

Also ensure that the Media Termination Point Required option is set.

If transcoding is required then a Media Resource Group List needs to be selected as well.

In the SIP Information section set the following entries need to be set:

Destination Address : IP address of VoiceGuide IVR server

Destination Port : 5060

Preferred Codec : 711ulaw

Security Profile : Non Secure SIP

SIP Profile : Standard SIP Profile

Preferred transport method is UDP

Click Save button at end of form and then click OK on the pop-up window to complete.

Create a Route Pattern to the SIP Trunk

Select Call Routing > Route/Hunt > Route Pattern then click Add New.

Then set the Route Pattern. eg. route pattern 2xx will cause all 3-digit calls beginning with “2” to be routed to the SIP Trunk.

The Gateway/Route should be set to the SIP Trunk that was just created previously.

Click the Save icon at the top of the form and then click OK on the pop-up windows to complete.

SIP Device Method

If a small number of lines are connected to CUCM then a number of Users can be created on the CUCM and VoiceGuide can be set up to Digest Authenticate itself with CUCM to use these lines.

Setup a new Phone Security Profile in order to enable Digest Authentication for SIP devices:

Click on the System menu, open the Security sub-menu and select Phone Security Profile.

Click on the Add New button.

Set the Phone Security Profile Type to Third-party SIP Device (Basic) and click on Next

Provide a Name and a Description for this profile, e.g.: "Third-party SIP Device Basic - Digest Authentication". It is important to check the Enable Digest Authentication checkbox and click on Save

Now create a new user:

Select User Management > End User from the top menu then click Add New to begin adding a new User.

Enter all details including Digest Credentials

Select Device > Phone from the top menu then click Add New to begin adding a new Phone.

Set Phone Type to Third-party SIP Device (Basic) and click on Next

Set Phone Button Template to Third-party SIP Device(Basic)

Set User ID to the created user's name.

Scroll down to the bottom of the page and set the Protocol Specific Information:

Device security profile: Set it to the created profile

SIP Profile: Set it to Standard SIP Profile

Digest user: Select the created user

After the phone is created, the Phone Configuration page will show up.
On this page you can see that there is no Directory Number set for this phone.
Click on Line [1] - Add new DN to create a directory number

Provide a directory number, e.g.: 6001 and click on Save

After the Directory Number is created, you can assign the created Phone device to a specific End User.
To do so, click on End user at the User Management menu.

Click on Find to search for the created user.

Click on the user name to view its details

Scroll down the End User Configuration page and find the Device Information section. By default, no device is associated to this user. To associate a device to this user, click on Device Association

You will get to the User Device Association page. Click on Find to search for the created device

Select the previously created device by clicking on the checkbox before its device name and click on Save Selected/Changes

Now you need to go back to the user settings page. At the related links section you can choose which page you want to jump to. Select the Back to User option to step back to the user's settings and click on Go

At the End User Configuration page you can see the assigned device name at the Controlled Devices list. Click on Save to save the settings

Monitoring SIP Traffic

WireShark (www.wireshark.org) can be used to verify that SIP packets are arriving at VoiceGuide server.

To filter for SIP packets specify:

sip

in the WireShark's filter text box.


Command Line Options

VoiceGuide v7.x runs as a Windows Service only. This section only applies to v5.x and v6.x of VoiceGuide.

-icon : Will minimize the application to the system tray

-hide : Will hide the main application window

-min : Will minimize the window to the taskbar

Script Designer

The filename of the script to be edited can be passed as a parameter on the command line


VoiceGuide and Dialogic HMP licenses

VoiceGuide and Dialogic HMP licenses can be purchased using the online order form at www.VoiceGuide.com

Registering VoiceGuide

To register VoiceGuide copy the provided 4 line license code to the License Details window in the VoiceGuide License Manager, press 'Activate', and then restart the VoiceGuide service.

Registering Dialogic HMP

Place the Dialogic HMP file somewhere on the VoiceGuide system and follow the steps below to enable HMP license:

  1. Stop VoiceGuide service
  2. Stop Dialogic service
  3. Apply the HMP license using the HMP License Manager.
  4. Follow instructions that will show on screen to “Restore Defaults”:
  5. To “Restore Defaults” right click on the “HMP_Software” node in DCM and select “Restore Device Defaults”
  6. A window will show. Select your new license filename.
  7. Start Dialogic service
  8. Start VoiceGuide service.


Unique System Identifier (Unique ID)

The Unique ID is based on either the Dialogic card serial number, or the Network adapters MAC address.

VoiceGuide v7

To find out the 'Unique ID' for the system go to Start -> Program Files -> VoiceGuide menu and start the License Manager, which will display the Unique ID.
The Dialogic service must be started before starting the License Manager in order for the Unique ID to show.

If Dialogic card is used the VoiceGuide v7 license will be linked to the Dialogic card, and the license will work when that Dialogic card is present in the system.
If moving software to new system then the licensed Dialogic card needs to be moved to new system as well.

For VoIP deployments that do not use a Dialogic card the VoiceGuide v7 license will be linked to the network adapter, and the license will work when that network adapter is used for VoIP communication.
For VoIP deployments it is recommended that a PCIe network card is used for VoIP communication, and motherboard based network interfaces are disabled.
Using a PCIe network card allows easy moving of the software from one system to another - but just moving that PCIe network card to the new system.

VoiceGuide v6 and v5

To find out the Unique ID for the system go to the Help menu and select 'Register VoiceGuide' option:

The registration screen will then appear with the various Unique IDs showing:

5 digit Unique IDs beginning with a letter 'M' are linked to the Network Card.
5 digit Unique IDs beginning with a letter 'H' are linked to the Hard Disk.
8 digit Unique IDs are linked to the Dialogic card.

In the example screenshot above, three Unique IDs are shown on the registration screen: M0932, MBD56 and FD060112. The first two Unique IDs are based on network cards in the system and the third one is based on the Dialogic card in the system.

For systems which use a Dialogic card it is recommended to link the license to the Dialogic card. This will allow the VoiceGuide license to be used in the new system that Dialogic card is moved to.

For systems which do not use a Dialogic card and where the ability to easily move the license from one machine to another is required it is recommended that a PCIe based network adapter is used (or a 'USB to Ethernet' network adapter). Moving the PCIe adapter to new system will then allow use of the licensed version of the software on the new system.

NB: There are no letters 'O' in any of the Unique IDs - if it looks like a zero then it is a zero.


VoiceGuide IVR Scripting

A Script specifies what the system is to do when an incoming call arrives, or an outgoing call is answered.
VoiceGuide provides a Graphical Script Designer to simplify script design and allow easy modification of existing scripts.
For example, to play a sound file, and then play a different file depending on which key the customer has pressed the script would look like this:

The modules above all play different sound files. There are other modules which perform other actions. eg: ask for caller's input, record sound files, interact with databases, interact with web services, run other programs, act as voicemail boxes, and more.

To create a system which you need is as simple as drag-and-dropping the modules which do the actions that you need on the screen and then specifying what events and actions result in Script taking caller from one module to another.


Graphical Script Designer

VoiceGuide's Graphical Script Designer allows creation of the IVR callflow by drag-and-dropping the function modules onto the screen and specifying how the caller will be taken through the script by editing the properties of each module.

NOTE: The script designer will not work under 'Aero' themes used by Windows7/Win2008/Vista. The workaround is to use 'Windows Basic' or 'Windows Classic' themes, or select 'Disable desktop composition' from vgScriptDesigner.exe's "Right Click->Properties->Compatibility" tab.

An example below shows a simple script being edited.

Adding new modules
The toolbar on the side of the window is used to select what modules to add to the script. To add a module select the module type to add, and then click on the script's workspace. To stop adding modules select the 'arrow' button.

See here more information on modules.

Deleting modules
Select the module to delete and press the [image] button.

Creating paths between modules
Select the start module and press the 'Properties' button located in the top right corner of the module. This will bring up the module's Properties pages. The path options are set in the text box on the Paths tab of the Properties window.

See here more information on paths.

Running scripts
If the edited script is currently used by VoiceGuide then just saving the script will result in VoiceGuide using the new version of the script for any new calls arriving on the lines on which that script is active.


Module Types

VoiceGuide scripts can be put together using a variety of function modules:
Play Sound File
Record Sound File
Get Number
Say Number
Transfer Call
Make Call
Web Service
Send Email
Database Query
Run Program
Time Switch
Evaluate Expression
Run VB Script
Hangup Call

VoiceGuide Voicemail system can be accessed from anywhere in the VoiceGuide scripts. Callers can be directed to various parts of the Voicemail system, depending on whether they want to leave messages, listen to the messages in their mailbox, or just browse through the Voicemail boxes on the system.
Record a message for a particular Voicemail box
Access the messages in a particular Voicemail box
Browse through the Voicemail system, leaving messages in various Voicemail boxes


Paths

Paths is the name given to the transitions between the Script Modules.

Creating new paths

To create a new path, press the Properties button on the module from which the path will start, and go to the Paths tab.

Paths are specified using the format:

on {Trigger} goto [Module Title]

The text in the Paths window can be edited directly, or you can use the Add New Path help frame.

Selection Paths

Taken when caller has made a matching selection. This can be a keypress or a series of keypresses, a keyword or phrase recognised by the Speech Recognition system, matching data retrieved from database or web service, or data returned by external program or VBScript/JavaScript etc.

Timeout Paths

A Timeout path will be taken if a caller has not made a selection within the specified number of seconds. A Timeout path with a wait time of zero seconds will be taken immediately after the last sound file in the module has completed playing.

Paths to Voicemail System

Paths can direct the caller to a Voicemail Box, Voicemail Box Menu or Voicemail Retrieve Menu, eg:

When specifying the Voicemail Box as the destination, the Voicemail Box number must be specified as well. make sure that the Voicemail Box specified exists and has been configured using the Voicemail System Manager.

Returning from the Voicemail system

If you would like the caller to go to a certain module after returning from the Voicemail system then you can specify a return module. The Path definition needs to be:

on {Trigger} goto [Voicemail System Module] Return [Module Title]

Eg: if after Retrieving Voicemail the caller should be sent to the main menu again, the path will look like this:

If the titles of the modules are too long to fit on one line, the path description will wrap around to the following lines. This is OK.

Branching to other scripts and calling subscripts

The Enterprise and Evaluation versions of VoiceGuide can call subscripts.

To branch (goto) to a script you can specify a path like this:

on {event} goto [script filename|module name]

eg:

on {1} goto [c:\scripts\myscript.vgs|PlayWelcome]

To run a subscript (gosub) to a script you can specify a path:

on {event} gosub [script filename|module name]

eg:

on {1} gosub [c:\scripts\myscript.vgs|PlayWelcome]

The script name or the module name can be left blank. If the Script Filename is left blank then the current script is assumed, and if the Module Name is left blank then the script's default starting module is used.

eg: on {1} gosub [|PlayWelcome]

on {1} gosub [c:\scripts\myscript.vgs|]

Note: If the [|module name] notation is used, the path to the destination module will not be drawn. This can be used to visually de-clutter highly linked scripts.

To specify what module should be the next module once the subscript returns the "return" path option should be used.
If the "return" path option is not used when the subscript returns then VoiceGuide will start running the default start module in the returned to script.

To specify a return module:

on {event} gosub [script filename|module name] return [return script filename|return module name]

The Return script can be a different script. eg:

on {1} gosub [c:\scripts\admin.vgs|Verify Caller] return [c:\TakeOrder.vgs|Main Menu]

The return script can be omitted if you would like the subscript to return to the same script. eg:

on {1} gosub [c:\scripts\utils.vgs|Lookup Status] return [Read Out Current Status]

To return from a subscript use a path like this in the subscript:

on {event} return

eg: on {4} return

The various goto/gosub/return paths are briefly demonstrated in the sample scripts in VoiceGuide's \scripts\more sample scripts\paths directory.

Using Result Variables in Paths

$RVs can be used in Paths expressions.

Any $RVs in paths are evaluated before the Paths are looked at to determine what action is taken after an event arrives.

eg: this approach would work: on {$RV[option1]} goto [some module] on {$RV[option2]} goto [some other module] on {$RV[option3]} goto [and so on] where $RV[option1] - $RV[option3] are assigned keypad digits or other events triggers. This approach would also work: on {1} goto [$RV[option1]] on {2} goto [$RV[option2]] on {3} goto [$RV[option3]] where $RV[option1] - $RV[option3] are assigned module titles. Entire path expressions can also be assigned to an $RV. eg: a single $RV can have this value assigned to it: on {1} goto [some module] on {2} goto [some other module] on {timeout 5} goto [and so on] and then that $RV can be used in the Paths list (along with other paths/$RVs if needed).

Subscripts using COM/WCF interface

Please see the VoiceGuide COM/WCF Reference section in this Help file for information on how the goto/gosub/return commands can be issued to VoiceGuide from external applications.


Result Variables

Result Variables store information on activity in each module during the call.
These Result Variables ($RVs) can then be used later in the VoiceGuide script, allowing the VoiceGuide script to act based on the information in the previously set $RVs.

Result Variables can also be accessed and created/set by external systems, using VoiceGuide's COM/WCF/REST/etc interfaces.
This is one of the mechanisms by which external systems can directly monitor and control the progress of the VoiceGuide script in real-time.

Please refer to each module's reference for more information on $RVs created by that module.
VoiceGuide's vgEngine trace files also contain details of all created/set $RVs.

Where can Result Variables be used

$RVs can be used anywhere in the VoiceGuide script. eg:

  • Specifying the 'trigger' and the destination modules in Paths leaving a module,
  • Filenames of sound files which are to be played or recorded,
  • What digits/dates/amounts are to be spoken to the caller in the Say Number module,
  • Looking up information in a database,
  • As parameters when calling other programs, web services, etc.
  • Evaluate Expression modules,
  • Send Email module: in destination Email address, Title, Message Body and Attachment Filename.

Note

If a Result Variable is used in the script that has not yet been defined, it will be replaced with nothing (an empty string), not a digit zero.

eg: If you use expression:

C:\sound_files\info_$RV[InformationNumber].wav

and the script has not yet defined $RV[InformationNumber] then the resulting string after the Result Variables are replaced will be:

C:\sound_files\info_.wav

If Result Variables are used 'Comparison' type expressions in Evaluate Expression modules, it is usually best to use quotes around the RVs which may be empty.
Also, quotes should be used when using RVs in a VBScript in situations where replacement with an empty string could potentially lead to syntax errors unless quotes have been used.

Often Used Result Variables

$RV[module title]

Used to access the 'main' information associated by a particular module. eg:

Module Type | Result Variable will contain
Play | The key pressed by the caller
Get Number Sequence | The number entered by the caller
Record | The last recorded filename.

All modules create more then one Result Variable. Please see documentation for each module type and the vgEngine trace file to see what $RVs are created by each module.

The module Result Variables are created for the duration of the call, and all modules running on that line during the call will be able to access them. Even if the script jumps to another script then the next script will still be able to access the Result Variables created by any previous script during current call.

$RV_CIDNUMBER

Caller's Telephone Number.

On traditional analog telephone lines the CallerID information is usually sent between the first and the second ring.
Hence on analog systems the calls must be answered after second ring.
On VoIP and ISDN systems CallerID is provided at beginning of the call.

$RV_CIDNAME

Caller's Name (if available).

On traditional analog telephone lines the CallerID information is usually sent between the first and the second ring.
Hence on analog systems the calls must be answered after second ring.
On VoIP and ISDN systems CallerID is provided at beginning of the call.

$RV_DNIS

Telephone number called by the caller. Provided on VoIP and ISDN lines.
$RV_DNIS is often used to determine which script should handle the call.
eg: an Evaluate Expression module can be used to goto to different scripts based on $RV_DNIS value.
See here for DNIS Routing example.

$RV_DIALEDNUMBER

On outbound call this variable stores the telephone number which was dialed.

$RV_LINEID

Identification number of the line device which is handling this call. The ID number refers to an internal line ID number - not the position in which that line's status is displayed in VoiceGuide's status window.

$RV_PORT

Line Device's position is VoiceGuide's line status listing. The first line/port has $RV_PORT of 1, the second line/port has $RV_PORT of 2, etc.

Some Other Result Variables :

$RV_STARTTIME | The Date and Time the call was started. The 'Medium' Date format and the 'Long' Time format is used. These formats can be set in the Windows' Control Panel - Regional Settings applet.
$RV_CALLLENGTH | Number of seconds since the call started. Checking the value of this variable during the running of the script can be used to limit length of the call. Also see $RV[CallMaxTime]
$RV_CALLSTATE | Current state of call.
$RV_STATUSDISPLAYED | What is currently displayed in the Line Status Monitor.
$RV_CurrentModule | Title of the current module the script is in.
$RV_PreviousModule | Title of the previous module, ie: from which module the script arrived at the current module.
$RV_CRN | Call Reference Number as used by Dialogic (in hexadecimal format).
$RV_CALLCOUNTER | Counter incremented for each call.
$RV_RINGCOUNT | Number of rings an incoming call has rung so far. This variable can be used to determine at which point to answer the call if the script was started with the "Start the script before answering the call" option.
$RV_LastKeyPress | Last Key that was pressed, or “timeout” if a timeout event fired.
$RV_EventList | Events which occurred during the call, including timestamps.
$RV_EventListXml | Events which occurred during the call (XML Format)
$RV_EventListJson | Events which occurred during the call (JSON format)
$RV_CallFlowProgress | Events and state changes that occurred on the call.
$RV_LINESINUSE | Number of lines currently busy on calls.
$RV_LIC_LINES | Number of lines system is licensed for.
$RV_LIC_TYPE | Professional, Professional+Dialer, Enterprise or Enterprise+Dialer
$RV_SOFT_VERSION | Version number of software running.
$RV[RUNAFTERHANGUP] | The filename of the script ran when the caller hangs up. This filename can be set in the Evaluate Expression module. Setting of $RV[RUNAFTERHANGUP] is only valid during the current script. This "OnHangup Script" setting is wiped whenever a goto/gosub is made to another script, and the new script's "OnHanup Script" setting is used.
$RV[ModuleTitle_RowCount]
$RV[ModuleTitle_ColIdx_RowIdx] | Please see the Database Query module for more information on the two Result Variables above.
$RV_PathScript | The path to the location where the script is located. Does not include the "\" at the end.
$RV_PathVoiceGuide | The path to the location where the VoiceGuide application is located. Does not include the "\" at the end.
$RV[CallMaxTime] | Used to set the maximum time (seconds) a call is allowed to be present on the system. eg. setting this $RV to 1200 will result in VoiceGuide hanging up the call automatically if the call is on the system for over 20 minutes.
$RV[VoicemailMessage] | The last recorded voicemail message during this call. Returns the filename of the last recorded voicemail message regardless of in which voicemail box it was recorded. The message must be recorded during the current call for them to be accessible using this Result Variable.
$RV[VoicemailMessageXXXX] | The last recorded voicemail message during this call. Returns the filename of the last recorded voicemail message in a particular voicemail box - which is specified by replacing XXXX with the number of the voicemail box. The message must be recorded during the current call for them to be accessible using this Result Variable.
$RV[VmbId] | ID of the last voicemail box that was accessed (either logged into or message left for).

Global RVs

Global RV can be preset in VG.INI, in section [Scripts], using an expression that lists multiple RVs on one line, like this:

GlobalRV=[SomeOption]{true}[MyValue]{23}[SomeEmail]{admin@mydomain.com}

These RVs will then be loaded and set when the VoiceGudie service starts and can be used in scripts. eg. If using example above then $RV[SomeOption] can be used in the scripts.

Current Date/Time Result Variables

$RV_WEEKDAY | Weekday. 1 to 7. 1 is Monday, 7 is Sunday.
$RV_DD | Day. 2 digit value : 01 to 31
$RV_MM | Month. 2 digit value : 01 to 12
$RV_YY | Year. 2 digit year value
$RV_HH | Hour. 2 digit value : 00 to 23
$RV_12HH | 12H Hour. 2 digit value : 01 to 12
$RV_NN | Minute. 2 digit value : 00 to 59.
$RV_SS | Second. 2 digit value : 00 to 59
$RV_MS | Millisecond. 3 digit value : 000 to 999
$RV_AMPM | AM or PM
$RV_UTCZ | UTC time. ISO 8601 Z (Zulu) time. eg: 2021-10-27T18:03:59Z
$RV_UTCK | UTC time with local timezone offest. eg: 2021-10-27T18:03:59+11:00
$RV_MONTHNAME | January, February, etc.
$RV_HOUR | Hour. 1 to 12
$RV_MINUTE | Minute: 0 to 59
$RV_SECOND | Second: 0 to 59
$RV_TimeStamp_Long | Localle based 'Long' timestamp
$RV_TimeStamp_Short | Localle based 'Short' timestamp
$RV_DateStamp_Long | Localle based 'Long' datestamp
$RV_DateStamp_Short | Localle based 'Short' datestamp
$RV_MONTH | January, February, etc.
$RV_YEAR | 4 digit year
$RV_DATE | Localle based default date/time stamp

eg. you can use this expression to create a date and time 'timestamp' :

$RV_YY$RV_MM$RV_DD$RV_HH$RV_NN$RV_SS.$RV_MS

Script Branching (Goto/Gosub/Return) related Result Variables

These RVs are set when a Goto or Gosub branch is made to another script:

$RV[ScriptEnd_Time]
$RV[ScriptEnd_Goto_Script]
$RV[ScriptEnd_Goto_Module]
$RV[ScriptStart_Time]
$RV[ScriptStart_CalledFrom_Script]
$RV[ScriptStart_CalledFrom_Module]

SIP Headers

The headers of incoming SIP calls can be accessed using these $RVs:

$RV[sip_header_callid]
$RV[sip_header_contact_display]
$RV[sip_header_contact_uri]
$RV[sip_header_content_disposition]
$RV[sip_header_content_encoding]
$RV[sip_header_content_length]
$RV[sip_header_content_type]
$RV[sip_header_diversion_uri]
$RV[sip_header_event]
$RV[sip_header_expires]
$RV[sip_header_from]
$RV[sip_header_from_display]
$RV[sip_header_referred_by]
$RV[sip_header_refer_to]
$RV[sip_header_remove]
$RV[sip_header_replaces]
$RV[sip_header_request_uri]
$RV[sip_header_to]
$RV[sip_header_to_display]

Other SIP headers to retrieve can be set in VG.INI section [SIP] entry: MonitoredHeaders
eg:

[SIP]
MonitoredHeaders=User-Agent|Diversion

will result in these $RVs being created and holding the value of corresponding header:

$RV[sip_header_User-Agent]
$RV[sip_header_Diversion]

Outbound dialing related Result Variables

$RV[OutDial_Result] | When the outgoing call has been answered, or the number of retries has been used up, this RV stores the type of outcome. Possible values are: Contacted_Human, Contacted_AM Contacted_Pager, Contacted_Fax, Uncontactable_OnDontDialList, SIT_Reorder, SIT_NoCircuit, SIT_CustIrReg, SIT_Unknown, SIT_Unavailable, Uncontactable_NoAnswer
$RV[OutDial_RetriesLeft] | Number of retries left for an outgoing call. If this is the last call attempt then this RV will have a value of 0.
$RV[OutDial_ID] | ID associated with that call's entry in the callque table.]
$RV[OutDial_GUID] | GUID associated with that call's entry in the callque table.
$RV[OutDial_CampaignName] | Campaign Name specified for that call when call was loaded into the system.
$RV[AmWelcMsg_RecLen100ms] | Length of Answering Machine message. in 100ms units. eg: a value of 40 would indicate answering machine message was 4 seconds long.
$RV_CALLTRACK_ContactName | Name attached to loaded number.
$RV_CALLTRACK_ContactData1 | Data1 attached to loaded number.
$RV_CALLTRACK_ContactData2 | Data2 attached to loaded number.
$RV_CALLTRACK_CampaignName | Campaign Name for the call.
$RV_CALLTRACK_History | Summary of major events for this dialed number.

Conference & Call Transfers related Result Variables

$RV[Conf_DevName_X] | The device name of party X in a conference call. eg: $RV[Conf_DevName_2] would be the device name of device carrying the 2nd leg of a call in the "Dial and Conference" call.
$RV[Conf_LineID_X] | The Line number of party X in a conference call. eg: $RV[Conf_LineId_2] would be the Line ID number of device carrying the 2nd leg of a call in the "Dial and Conference" call.

ACD Agent related Result Variables

$RV_ACD_AGENTID | ID of ACD agent to whom this call is connected to.
$RV_ACD_AGENTNAME | Name of ACD agent to whom this call is connected to.
$RV_ACD_AGENTPHONE | Telephone/Extension number of ACD agent to whom this call is connected to.
$RV_ACD_AGENTSKILLS | Skills assigned to ACD agent to whom this call is connected to.


Call Start

It is sometimes desirable to carry out some processing before the call is answered. Quite often the purpose of this processing is to determine whether the call should be answered or not.

VoiceGuide script can be configured to start running without answering the telephone line. This allows VoiceGuide to conduct any database or web service lookups etc. based on provided CallerID in order to determine how the call should be handled.

To select this option use the "Script Properties" menu entry from the "Edit" menu in the Graphical Design Environment, then check the "Start the script without answering call" box.

For a given script to answer all incoming calls leave the "Start the script without answering call" box unchecked (this is the default setting for each new script).

Modules allowed before the call is answered

Any modules that do not need to play a sound file can be used. eg:
Database Query
Web Service Call
Time Switch
Evaluate Expression
Run Program
Send Email
Make Call
Run VB Script
Hangup the Call

Arriving at the "Hangup Call" module results in the script finishing and the call never being answered.

Answering the call

Calling any module which plays or records a sound file or transfers the call will result in a call being answered.

Reaching the following modules in the script will effectively answer the call:
Play Sound File
Record Sound File
Get Number
Say Number
Transfer Call


Call Finish

It is sometimes desirable to perform some functions at the time when the call finishes, regardless of at which point in the script the call ended. Usually such a script will perform 'clean-up' type operations like database updates, call other programs, send out emails or schedule outbound calls.

VoiceGuide can be instructed to run a separate script when the call has finished using the "Script Properties" option from the "Edit" menu in the Graphical Design Environment.

Below shows the script "C:\My Scripts\Update Databases.vgs" is to be called when the currently edited script is finished:

Modules allowed in the Cleanup/OnHangup script

Only certain types of modules can be used in a Cleanup script. As the call has already ended, modules which play or record sound files or expect user input cannot be used.

The following modules can be used:
Database Query
Web Service Call
Time Switch
Evaluate Expression
Run Program
Send Email
Make Call
Run VB Script
Hangup

Changing the Cleanup/OnHangup script at runtime

It is sometimes desirable to change the Cleanup script depending on user selections or other factors. To change the script we need to assign the new filename to the $RV[RUNAFTERHANGUP] Result Variable. The Evaluate Expression module can be used to do this:

Result Variables

All Result Variables from the script which was handling the call are available to the 'Cleanup' script. This allows all information entered by caller or retrieved/created by the original script to be used in the call cleanup script.


Multi Language Systems

When implementing multi-language systems:

  • Script prompts need to be recorded in multiple languages.
  • If using any of VoiceGuide's pre-recorded system prompts, then a new set of system prompts needs to be recorded in the new language as well.

Script Sound Files

Usually towards the beginning of the script a module like this would be used:

The user selection would then be available by using the $RV[Get Language] Result Variable.
This result variable can then be used to select the right language version of the file for the script to play.

eg: language files can be placed in separate directories:

C:\MyScripts\$RV[Get Language]\Intro.wav

Would be translated by VoiceGuide to either:
C:\MyScripts\1\Intro.wav
C:\MyScripts\2\Intro.wav
C:\MyScripts\3\Intro.wav
where the three files are recorded in English, Spanish and French respectively.

or, the sound files to play can be specified like this:

C:\MyScripts\Intro_$RV[Get Language].wav

Above would be translated by VoiceGuide to indicate either:
C:\MyScripts\Intro_1.wav
C:\MyScripts\Intro_2.wav
C:\MyScripts\Intro_3.wav

VoiceGuide System Sound Files

VoiceGuide's default system sound files are stored in the VoiceGuide’s "\system\voice\" subdirectory.

To select a different set of system files to be used for the current call, the path pointing to the new system directory current for this call needs to be written to the $RV[DIRSYSTEMVOICE] Result Variable.

The path has to be written in double quotes. Note that only DIRSYSTEMVOICE is specified in the "Assign to Result Variable" text box, not $RV[DIRSYSTEMVOICE].


Protected Scripts

Saving VoiceGuide Script as 'Protected Script' encrypts the script file.

Protected Scripts can only be viewed/edited if the password is known.

Protected Scripts should be used if the VoiceGuide Script contains sensitive information, like database or web service access passwords etc.

When running Protected Scripts VoiceGuide will decrypt the script in memory, preventing the sensitive information from being disclosed.

Protected Scripts have the .VGP suffix.


Sound Files

The format of sound files which are to be used depends on which version of VoiceGuide is used.

Versions 7.x | Recommended: .WAV ULaw 8kHz 8-bit Mono, .WAV ALaw 8kHz 8-bit Mono. Can also use: .WAV PCM: 8kHz, 11kHz, 16kHz, 22kHz, 44kHz, 32kHz and 48kHz. On VoIP and ISDN systems it is recommended to use the same .WAV format as the VoIP/ISDN connection (ULAw or ALaw). This way no transcoding will be done on the played file, and the trasnmitted sound data will be a byte-for-byte copy of the original sound file contents, giving the best possible sound playback quality. Preferred sound file format (ULAw or ALaw) is selected at install time.
Versions 6.x | .WAV : PCM 8kHz, 8-bit, Mono. Can also use .VOX files: 8kHz, 4bit, ADPCM.
Versions 5.x | .WAV : PCM 8kHz, 16-bit, Mono. Note: When using VoiceGuide versions 5.x with Dialogic TAPI/WAVE drivers then the sound files must be recorded in the format used by the Dialogic Wave driver, which is .WAV PCM 11kHz, 8bit, Mono.

Sound Recording Software

One popular sound recording software is Audacity: https://www.audacityteam.org

eg: To save a recording as a WAV ULaw 8kHz 8-bit Mono file using Audacity:

  1. Start Audacity and open the sound file.
  2. If the file is stereo, convert to Mono using menu: Tracks > Mix > Mix Stereo Stereo Down to Mono.
  3. Set Project Rate Hz (bottom left) to 8000
  4. Select menu: File > Export > Export as WAV
  5. Choose "U-Law" Encoding.
  6. Edit the file name and be sure it ends in ".wav".
  7. Click Save.
  8. Click OK

System Sound Files

VoiceGuide comes with a number of pre-recorded system files which are installed in directory \system\voice\
The format of the sound files installed may depend on what options were selected during install.

An alternative system directory can be specified in the script by assigning the directory path to the DIRSYSTEMVOICE Result Variable.
Please see the Multilanguage section for more information on this.

The sound files say “Pound Key” to indicate the “#” key. Alternate copies of the sound files have been supplied if you would like VoiceGuide to use “Hash Key” to indicate the “#” key. To use these files, just copy the alternate files over the system files used by VoiceGuide. The alternate files have "_HashKey" appended to their filename.

Files in \system\voice\ contain the following recordings:

0-23, 30, 40, 50, 60, 70, 80, 90 | These files contain the digit which corresponds to the name of the file.
AcceptAutoCall | This is an automated telephone call, please press any number on the telephone keypad to accept this call
am | am - as in "8:30 AM"
and | ...and...
beep1 | A short beep played before recording sound files.
billion | billion
cents | cents
dollars | dollars
ErrorPlayingFile | There has been an error playing this file, please check the file format
GetNbrsConfirmIntro | You have entered the following number:
GetNbrsConfirmMenu | Please press '1' if that is correct, or press '2' if you would like to re-enter the number
hundred | hundred
MaxRecTime | I'm sorry, the maximum record time has been reached
million | million
minus | minus
month01 ... month12 | January ... December
place01 ...place31 | first ... thirty first
pm | pm as in 5:30 pm
point | point - as in the decimal point
press | press
pressplz | please press
RecMsgMenu | Please press '1' to replay the message, '2' to delete the message and record again, or '3' to save this message and go back to the voicemail box menu
SoundFileNotFound | The sound file specified could not be found
thousand | thousand
trillion | trillion
transferto | to be transferred to
TsfrCallFrom | This is a transferred call
TsfrAskAccept | Please press 1 to accept the call, or press any other number to reject it
ACD |
acd_EstWaitTimeIsLessThen | Your estimated wait time is less then
acd_EstWaitTimeIs | Your estimated wait time is
acd_Minute | minute.
acd_Minutes | minutes.
acd_YouAre | You are ...
acd_InTheQueue | ...in the queue.
acd_LongWaitTimes | We are experincing longer then normal wait times.
acd_IfYouDoNotWantToWait | If you do not want to wait, you can request a callback.
acd_NotLosePlaceAndCallBack | You will not lose your place in the queue and the system will call you back once you have reached the start of the queue.
acd_NotLosePlace | You will not lose your place in the queue.
acd_PleaseSayYourName | Please say your full name after the tone and press any key when you have finished.
acd_WeHaveRecorded | The name we have recorded is:
acd_Press1orRecAgain | Please press 1 if that is correct or press any other key to record again.
acd_WeHaveYourNumber | Please press 1 if you would like us to call you back on the phone number from which you are calling from, or press any other key to enter the contact phone number.
acd_EnterPhoneNumber | Please enter the phone number on which you would like us to call you back.
acd_YouHaveEntered | You have entered:
acd_Press1orEnterAgain | Please press 1 to confirm, or press any other key to re-enter the number.
acd_SystemWillCallBack | The system will call you back once you have reached the start of the queue.
acd_WeWillCallBackOn | We will call you back on ...
acd_InApprox | ... in approximately ...
acd_ThisIsACallFor | This is a callback telephone call for...
acd_When | When...
acd_WhenAtTelephonePress1 | ... is on the line please press 1 to continue.
acd_YouWillNowBeConnected | Thank you, you will now be connected.
acd_ThankYou | Thank You.
Automated Attendant |
aa_connectto | To be connected to
aa_getextorspell | If you know the extension number of the person to which you would like to be transferred please enter it now, otherwise please press 1 to spell the name of the person to whom you want to be transferred using your telephone keypad , or press 0 to be transferred to the operator.
aa_nomatchext | This extensions does not exist
aa_nomatchext2 | Extension could not be found
aa_nomatchnames | No matching names can be found
aa_press0operator | or press 0 to speak with the operator
aa_press0reception | or press 0 to speak with reception
aa_spellname | Please enter the first 4 characters of the persons name, spelling the surname using the keys on your telephone keypad.
aa_spellname2 | Please enter the first 4 characters of the persons surname, spelling the surname using the keys on your telephone keypad.
aa_transferringto | Transferring you now to...
aa_xfernoanswer | The call was not answered, press 1 to leave a message in the voicemail box, or press 2 to try another extension. You can press 0 to speak with the operator.
aa_xferextbusy | The extension is busy, press 1 to leave a message in the voicemail box, or press 2 to try another extension. You can press 0 to speak with the operator.
Voicemail |
VmbAccessGetVmbId | Please enter the voicemail box number for which you want to leave the message and then press the pound key
VmbAccessGetVmbIdRetrieve | Please enter your voicemail box number and then press the pound key
VmbAccessGetVmbPin | Please enter your 4 digit PIN number and then press the pound key
VmbAccessInvalidVmbId | This voicemail box does not exist
VmbAccessInvalidVmbPin | I'm sorry, the PIN number you have entered was incorrect
VmbAccessListenMsgMenu | Please press '1' to replay the message, '2' to save the current message and listen to the next message, '3' to delete the current message and listen to the next message, or press '0' to return to the voicemail box menu
VmbAccessMenu | Press '1' to listen to new messages, '2' to listen to saved messages, press '3' to change your greeting message, or press '4' to change your mailbox PIN number.
VmbAccessNewMessagesAnd | ... new messages and ...
VmbAccessNoMessages | No Messages
VmbAccessNoNewMessages | There are no new messages
VmbAccessNoSavedMessages | There are no saved messages
VmbAccessNoWelcMsg | You currently do not have a personalized welcoming message
VmbAccessSavedMessages | ... saved messages
VmbAccessWelcMsgMenu | Press '1' to play the current greeting message, '2' to record a new welcoming message, '3' to save the current message and exit and '4' to delete the current message and exit
VmbAccessWelcMsgRecPrompt | Record your new welcoming message after the tone, when you have finished recording press '1'
VmbAccessYouHave | You have ...
VmbAdminName_Menu | Press '1' to play the current name, '2' to record a new name, '3' to save the current name and exit or '4' to delete the current name and exit
VmbAdminName_NoName | You currently do not have a name recorded for this mailbox
VmbForwardAskAccept | This is the VoiceGuide voicemail system. You have a new voicemail message. Press '1' to hear your new message.
VmbForwardPhonePrompt1 | The current forwarding phone number is:
VmbForwardPhonePrompt2 | Enter the phone number to which your voicemail messages will be forwarded, and press the pound key when you have finished. You can press the pound key to stop forwarding your voicemail messages or press the star key to keep your current forwarding phone number.
VmbForwardPhonePrompt3 | You currently do not have a forwarding phone number set up.
VmbForwardPhoneConfirm1 | You have entered the following phone number:
VmbForwardPhoneConfirm2 | Please press 1 to confirm, or press 2 to re-enter the phone number.
VmbForwardPhoneChangedOK | The forwarding phone number has been updated.
VmbDoesNotExist | This mailbox does not exist
VmbPinChangedOK | Your PIN number has been changed
VmbPinEnterNew | Please enter your new PIN number
VmbPinEnterNew2 | Please re-enter the PIN number
VmbPinNotMatching | The two entered PIN numbers do not match
VmbWelcomeMsgDefault | Please record your message after the tone
VmSendMainMenu | Please press 2 to delete the recorded message and start recording again, 3 to save the recorded message and start entering the destination voicemail groups or 4 to delete the recorded message and return to the voicemail box main menu.
VmSendGetNextDest | Please enter the next destination followed by the pound key, or just press the pound key if you have finished entering all destinations.
VmSendSuccess | Messages have been sent.
VmSendRecPrompt | Please record the message after the tone. When you have finished recording please press the Pound key.
VmSendGetNextDest | Please enter the next next recipient followed by the pound key, or just press the pound key if you have finished entering all recipients
VmSendMainMenu | Please press 1 to play the recorded message, 2 to delete the message and record again, 3 to save the message and start entering recipients, or press 0 to delete the recorded message and return to the voicemailbox menu.
VmSendRecPrompt | Please record the message you would like to send after the tone. when you have finished recording please press the pound key.
VmSendSuccess | Messages have been sent


Testing IVR Scripts

The best way to test the IVR system is to dial into it just like the caller would.

A good approach to test the script while developing is to setup VoiceGuide in VoIP mode, and dial into it by just dialing the IP address of the machine on which VoiceGuide is installed using a VoIP phone or a soft phone from another PC.

or

Use a small PBX appliance and plug the analog lines from the small PBX into the Dialogic card.

Automated Testing

VoiceGuide can be used to create scripts which can test IVR systems by dialing into them and running a test script which simulates callers responses.

Please contact sales@voiceguide.com for more information on designing such automated IVR testing solutions.


Play Module

The Play module can:

  • Play a sound file,
  • Speak the typed text (Text to Speech),
  • Speak the specified text file (Text to Speech),
  • Play DTMF tones
  • Send Hookflash signal

While playing the module will listen for a response from the caller. You can select the number of times the message will be re-played, and the pause between the replays.

Result Variables can be used when specifying the sound file to be played. In the example below the file played will be different depending on what selection the caller made in the 'Get Language' module.

Multiple sound files can be selected to be played by separating the successive files by commas. eg:

prompts\1.wav, prompts\2.wav

would result in two files from the script's prompts subdirectory being played (1.wav and 2.wav) one after another.

If the sound files are specified without a full path then VoiceGuide will search for the sound files in the script's directory, or in a script's \voice\ subdirectory (if it exists).

If one or more of the sound files to be played cannot be found then VoiceGuide will see if a path SoundFileNotFound is defined in the module.
If the path SoundFileNotFound is defined then that path will be taken.
If the path SoundFileNotFound is not defined then VoiceGuide will play the system sound file SoundFileNotFound.wav in place of the sound files that cannot be found.

Text to Speech

The text entered in the "Text to speak" box will be spoken. XML tags can be used when specifying the text to be spoken. For full details on the XML tags which can be used please refer to Microsoft's SAPI 5 specification, or to your TTS engine's reference.

If a text file is specified in the ”Sound File” text box then VoiceGuide will read in the text file and will speak (TTS) the contents of that file.
The text file should have a .TXT suffix.

Paths

Paths specify which module the caller will go to if a matching response is made by the caller. eg:

A Timeout path is taken if no key has been pressed within the specified number of seconds after the last replay of sound file(s) has completed. If no Timeout path is specified and no selection is made within 10 seconds of the last message replay finishing, VoiceGuide will hang up the call.

While sound file is playing, keyspresses can be used to skip forward/back or to adjust playback speed and volume. Special PLAY ACTION type paths need to be specified to achieve this:

on {Trigger} goto [PLAY ACTION - Pause]
on {Trigger} goto [PLAY ACTION - Resume]
on {Trigger} goto [PLAY ACTION - Jump Forward]
on {Trigger} goto [PLAY ACTION - Jump Back]
on {Trigger} goto [PLAY ACTION - Jump To Start]
on {Trigger} goto [PLAY ACTION - Jump To End]
on {Trigger} goto [PLAY ACTION - Speed Increase]
on {Trigger} goto [PLAY ACTION - Speed Decrease]
on {Trigger} goto [PLAY ACTION - Speed Reset]
on {Trigger} goto [PLAY ACTION - Volume Up]
on {Trigger} goto [PLAY ACTION - Volume Down]
on {Trigger} goto [PLAY ACTION - Volume Reset]
on {Trigger} goto [PLAY ACTION - Speed Volume Reset]
eg:
on {4} goto [PLAY ACTION - Jump Back]
etc.

The skip forward/back size can be adjusted by setting a value of following Result Variables in the Evaluate Expression module:

$RV[playaction_skipbackbytes]
$RV[playaction_skipforwardbytes]

Playing DTMF tones and Hookflash

The Play module can also play DTMF tones, and send Hookflash signals. To specify the DTMF tones to send, type in the DTMF tone sequence in the “Sound File” text box. An exclamation mark “!” indicates a hookflash, and a comma “,” indicates a pause, whilst characters “0-9“ and “A-D“ are used to indicate DTMF tones

When using Dialogic cards any combination of DTMFs, hookflashes and pauses can be specified on the one line and the Dialogic card will play them correctly.

TAPI devices can usually only specify either a hookflash or DTMF tones in a Play module. This means that in order to have a TAPI device send a hookflash followed by DTMF tones you may need to use two Play modules one after another. The first Play module would just contain the hookflash, and the next module will contain the DTMF string. You should then use a Timeout path to link the two modules together (eg: on {Timeout 1} goto [Dial Number] ). In this situation using the Timeout path allows you to specify exactly how long after the hookflash will the DTMF tones be dialed. Pause characters cannot be used at all with many TAPI devices.

Automated DNIS based file selection

VoiceGuide allows per-DNIS sound file specification.

If DNIS is supplied on the call then VoiceGuide will see if a "DNIS-tagged" derived filename exists. The "DNIS-tagged" derived filename is the original filename with a "_DNIS" inserted just before the ".wav" in the filename.

eg. if the Play module is configured to play a file welcome.wav and the DNIS on the call is 1234 then VoiceGuide will first search for file welcome_1234.wav If welcome_1234.wav does not exist then VoiceGuide will play the sound file welcome.wav

NB: DNIS is an expression indicating the number dialed by the caller, and is only really available on ISDN and VoIP systems. On analog systems a close replacement of this functionality can be achieved by using $RVs within the filename to be played, and setting that $RV value previously, based on Inband Signaling or user selection etc.


Record Module

Records to a sound file.

Recording will finish when any of the following occurs:

  • silence is detected
  • the caller hangs up
  • a key that has a path defined for it is pressed
  • a set timeout is reached

Following can be specified in the ‘Sound File to Record’ text box:

  • Full filename of the destination file
    Recording will be made into the specified file. If a file with this name exists already then it will be overwritten.
  • Just the directory into which the recordings are to be placed
    A filename will be generated and the recording will be placed in the specified directory.
    The directory name must finish with a “\”
  • Leave the entry blank
    A filename will be generated and the recording will be placed in the script’s directory

If the destination filename is not specified the file name generated will follow this template:

MMDDHHNNSS_LineId_Port_CallerID.wav

where:

MM : 2 digit month
DD : 2 digit day
HH : 2 digit hour
NN : 2 digit minute
SS : 2 digit second
LineId : LineId of line handling the call
CallerID : Caller's telephone number

Record Length

The Timeout path is used to specify the maximum length of recording.

eg: the screenshot below of the module's paths tab shows that that module a "timeout 30" path.
If recording length reaches 30 seconds then recording will be stopped and that path will be taken.

Also, if the caller presses any of the keys that have paths defined for it, the recording will terminate and the caller will be sent to the module specified in the path (in this case all paths lead back to the Main Welcome module.

Silence Detection

The recording will stop if silence is detected. The following type of path can be used to tell VoiceGuide which module to go to next if a silence is detected;

on {silence} goto [module title]

Minimum silence length and volume parameters can be set by editing the VG.INI configuration file, in section [PlayRecordConfig]. From VG.INI file:

;SilenceDetectLength: 40=4 seconds
SilenceDetectLength=40

;SilenceDetectLevel: range: 0-100
;0 - disable silence detection, 100 - detect loud background noise as silence
SilenceDetectLevel=10

The silence detection settings can be set from within the script as well, by assigning values to Result Variables SilenceDetectLevel and SilenceDetectLength

This can be done using the Evaluate Expression module, or setting them in any other way that Result Variables can be set.
eg. To disable silence detection using the Evaluate Expression module:

Transcription

To have the recorded sound transcribed into text the Result Variable:

Transcribe_Record_Module

must be set to a value of: "True" or "1".

VoiceGuide will use a Speech-to-Text engine to transcribe the text.
The text will be saved in the same filename as the sound file, but with the ".WAV" suffix changed to ".TXT".

Event Transcribe_End will fire when the transcription completes.
Paths can be set to react to this event. eg:

on {Transcribe_End} goto [Process Transcribed Text]

Result Variables

$RV[ModuleTitle] | Filename of the recorded sound file. Includes the full directory path.
$RV[ModuleTitle_EndRecCause] | Reason why recording was stopped.
$RV[ModuleTitle_RecLen100ms] | Length of Recording in 100ms units (eg. a value of 75 equals seven and a half seconds).
$RV[ModuleTitle_Transcribe_File] | Filename of the text file that holds the transcription. Includes the full directory path.
$RV[ModuleTitle_Transcribe_Text] | Transcription text.

Call Recording - Recording Conversations

The Record_2Lines_Start function can be used to record both sides of the conversation.
Record_2Lines_Start supports recording of both sides of a bridged conference call.
Record_2Lines_Start also supports recording of both sides of the Caller<->IVR connection - recording what IVR plays to the caller and the caller's responses.


Get Numbers

Plays a sound file, and then captures a sequence of numbers entered by the caller.
Caller can indicate that they have finished entering the numbers by pressing the "#" key, or module can complete when entered number reaches a certain length, or when it times out awaiting further input.
Module can optionally run a verification check on the entered number.
Module can also optionally play back the entered number for customer verification.

Sound files

Multiple sound files can be selected to be played by separating the successive files by commas. eg:

prompts\1.wav,prompts\2.wav

would result in two files from the prompts subdirectory being played (1.wav and 2.wav) one after another. If you do not want a sound file to be played at all you can also specify “none” in the sound file text field.
If Text to Speech (TTS) is enabled then a text file can be specified in the ”Sound File” text box and VoiceGuide will read in the text file and will speak (TTS) the contents of that file.

Play back entered number and ask caller to confirm

If this option is selected and the caller has entered something then VoiceGuide will play back the entered number and ask the caller to confirm it. The caller will need to press '1' to confirm the entry, any other keypress will result in VoiceGuide asking for the caller to enter the number again.

Minimum entered number length

The minimum length of there entered number which this module expects to receive from user.

Maximum entered number length

The maximum length of the entered number which this module should wait for. Once this many digits have been entered the module will immediately perform the next action - be it taking the best matching path or running any selected confirmation and verification options.

Verify Entered Number Tab

Quite often it is desirable to determine if the entered number satisfies some criteria, and if it does not then the option should be given to the caller to enter the number again. A VBScript can be specified here to check if the number passes any required checks/tests.

For example to check that the entered number is between 13 and 16 characters long and begins with either a 3 or a 4 the following VBScript would be used:

set vg = CreateObject("vgServices.CommandLink")
iLen = Len("$RV_ENTEREDNUMBER")
sFirstChar = Left("$RV_ENTEREDNUMBER",1)
if iLen<13 or iLen>16 or (sFirstChar <> "3" and sFirstChar <> "4") then
sResult = "verify_failed"
else
sResult = "verify_passed"
end if
vg.Run_ResultReturn $RV_LINEID, sResult
set vg = Nothing

For more information on VBScripts and how they are used from within VoiceGuide please refer to this Help file's entry on Run VBScript module.

the value of sResult should be set to either "verify_passed" or "verify_failed".
This is the method by which VoiceGuide is informed whether the verification of the entered number passed or failed.

If "verify_failed" is returned back to VoiceGuide then VoiceGuide will either play the sound file(s) specified in the "file to play if entered number is wrong length or verification failed" text box, or if that text box is not set it will just play the main prompt asking the caller to enter the number again.
If the verification script starts playing another file before returning "verify_failed" then VoiceGuide will just wait for caller to start entering the number again, without starting to play any other sound files. This allows customized advice sound files to be played depending on the cause of failed verification.

$RV_ENTEREDNUMBER contains the number just entered by the caller. In the verification script use $RV_ENTEREDNUMBER instead of the $RV[ModuleName] style $RV. When the verification script is ran the $RV[ModuleName] result variable has not yet been set.

Paths

Here is an example of valid paths:

Success Path

If any of the paths match the entered number exactly then that path is taken, otherwise the 'Success' path will be taken.
If the 'Success' path is not defined and none of the other paths match the entered number exactly then the caller will be asked to enter the number again.

Fail Path

Taken if the caller has not entered any numbers, ie. caller just presses the "#" key or VoiceGuide times out awaiting first number entry.
If the 'Fail' path is not defined then the system will hang up the call.

Timeout Paths

The timeout between key presses is set by default to 6 seconds. Default timeout values used by this module can be changed in VG.INI file - in the [moduleGetNbrs] section.

If a ‘Timeout’ path is specified then that path overrides the default inter-digit key press timeout, and that path will be taken whenever a timeout occurs awaiting a key press.

'Exact Match' Paths

If any of the paths match the entered number exactly then that path is taken immediately. It will be taken immediately even if the path does not satisfy the minimum and maximum number length limits. The "Confirm entered number" option will also be ignored, and no verification script will be ran.

Note: Manual editing of the path trigger entry loaded by script designer in the {} brackets will be necessary to specify the ‘exact number’ used. ie. the exact_number placeholder loaded by the script designer needs to be replaced with the actual number combination to trigger on.

'*' Paths

If an "on {*} " path is defined then pressing the * key results in VoiceGuide assigning a "*" to the Result Variable for the module and going down the "on {*} " path. This feature can be used to easily implement a "press * to correct" option - just point the "On {*} " path back to the same module and then when caller presses the * key they will be able to just start entering the number again from start.

If a "on {*} " path is not specified then the * key will be included in the string of numbers captured by the module.

Result Variables

Main RVs created by the 'Get Numbers' module:

$RV[moduleTitle]
Stores the characters entered by caller.

$RV[moduleTitle_PathTaken]
Stores which path was taken when exiting the module. This could be "success", "fail", "Timeout", "*" or the entered number if the exact path match was made.

Protecting Entered Data

The keypresses made by caller in a Get Numbers module will by default be displayed in the Line Status Monitor and saved in VoiceGuide's log files.

Their display and saving can be prevented using settings in VG.INI, or by issuing directives during the call.

The following settings can be used, in section [moduleGetNbrs] in VG.INI file:

StatusDispMaxLen
MaskKeys

StatusDispMaxLen setting affects the Line Status Monitor only. Setting StatusDispMaxLen to X will stop numbers X digits or longer from being shown in the Line Status Monitor.
eg:
StatusDispMaxLen=4 will stop numbers 4 digits or longer from being shown in the Line Status Monitor.
StatusDispMaxLen=1 will stop all keypresses from being shown in the Line Status Monitor.

MaskKeys setting can be used to specify further security options.
The following options can be specified:

script : will stop all keypresses from being stored in script logs (.vgl/.xml/.json/.csv logs)
callevent : will stop all keypresses from being stored in CallEvents log
status : will stop keypresses from being shown in the Line Status Monitor

eg: to set all 3 options set the MaskKeys to:

MaskKeys=script,callevent,status

StatusDispMaxLen and MaskKeys can also be set dynamically during the call, by setting the following Result Variables:

$RV[ini_moduleGetNbrs_StatusDispMaxLen]
$RV[ini_moduleGetNbrs_MaskKeys]

The $RVs can be set using an Evaluate Expresion module, or using any other method available for setting of $RVs.

Furthermore, if required, the VoiceGuide vgEngine, ktTel etc. logs can have their verbosity (log level) reduced or be turned off altogether using settings in section [Log] in VG.INI file.

Notes

1. When entering numbers it is usually best to ask callers to press a # key or * key to indicate they have finished entering the number. Using such terminating characters allows you to act immediately after the # or * is pressed, without the need to rely on timing-out awaiting next keystroke to determine when caller has finished entering number.


Say Numbers Module

The Say Numbers module can speak the supplied number as:
Digits | "12345" would be spoken as "one two three four five". Up to forty digits will be spoken.
Amount Dollars | "12345" would be spoken as "twelve thousand three hundred forty five dollars". Amounts up to twelve digits long will be spoken.
Amount Cents | "12345" would be spoken as "one hundred twenty three dollars forty five cents". Amounts up to fourteen digits long will be spoken.
Amount Cents, Decimal Point | "12" would be spoken as "twelve dollars zero cents". "12.3" would be spoken as "twelve dollars thirty cents". "12.34" would be spoken as "twelve dollars thirty four cents". Amounts up to fourteen digits long will be spoken. This setting is usually used for speaking amounts retrieved from databases.
Number | "12345" would be spoken as "twelve thousand three hundred forty five". Numbers up to twelve digits long will be spoken.
DateMMDD | "0123" would be spoken as "twenty third January". Only the first four digits of the supplied string are looked at.
DateDDMM | "2301" would be spoken as "twenty third January". Only the first four digits of the supplied string are looked at.
DateMMDDHHNN | "01231456" would be spoken as "twenty third January two fifty six pm". Only the first eight digits of the supplied string are looked at.
DateDDMMHHNN | "23011456" would be spoken as "twenty third January two fifty six pm". Only the first eight digits of the supplied string are looked at.
TimeHHNN | "1745" would be spoken as "five forty five pm", "0730" would be spoken as "seven thirty am"
TimeHHNN 24 | "1745" would be spoken as "seventeen forty five"

Result Variables can be used when specifying what number is to be spoken. Sound files to be played before and after the spoken number can also be selected. Result Variables can also be used in those filenames.

If a filename is specified then VoiceGuide will read in the file contents and read the data specified in the first line of the file.

If Digits, Amount or Number options are selected, and the number to be spoken starts with a "-", then the word "minus" will be spoken first before speaking the reset of the number.

If Date or Time options are selected , and the supplied number is the wrong length or does not make sense in the context of the selected option (eg: the supplied number is 8933 and the DateMMDD option is selected) then nothing will be played and the Fail path will be taken. If the Fail path is not defined then the Success path will be taken. If neither the Fail or Success paths are defined then VoiceGuide will hang up the call.

The Date/Time checking feature allows the Say Number module to be used for verifying validity of any caller-entered times and dates. The Time Switch module can also be used for checking the validity of date/time entered by caller.

Sound files played before & after the number

The sound files used in the module have to be of the same format as VoiceGuide current 'system' sound files (usually found in VoiceGuide's \system\voice\ subdirectory). This would be either "ALaw 8kHz 8bit Mono", or "ULaw 8kHz 8bit Mono".

Multiple sound files can be selected to be played by separating the successive files by commas. eg:

prompts\1.wav, prompts\2.wav

would result in two files from the prompts subdirectory being played (1.wav and 2.wav) one after another.

Changing the way Say Number module speaks numbers

Users can edit the way in which the numbers are spoken, or even add their own Say Number functions.

In VoiceGuide v5 and v6 the way the numbers are spoken can be changed by editing the file: lib_num2wav.vbs located in VoiceGuide's \system\vbs\ subdirectory. This is useful if it is required to say numbers/amounts in a language other then English. Please read the lib_num2wav.vbs file for more information.

In VoiceGuide v7 a DLL file is used to generate the list of WAV files needed to speak the number. The DLL is called vgLib_SayNumbers.dll and is located in VoiceGuide's \system\dll\ subdirectory. The source code (in C#) and full MS Visual Studio project file required to build the DLL can be found in this VoiceGuide subdirectory: \system\dll\Source\vgLib_SayNumbers. After building the new DLL just place it in VoiceGuide's \system\dll\ subdirectory and restart VoiceGuide in order for VoiceGuide to start using the new DLL.

In VoiceGuide v7 you can also select to have the system use the lib_num2wav.vbs to generate the spoken number by changing the VG.INI file setting. In VG.INI, section [moduleSayNumbers], change the entry WavListGenerator from DLL to VBScript.


Send Email Module

This module will send an Email message.

You can specify the Destination, Title, Message Body and an Attachment File. Result Variables can be used.

Example:

If the message needs to be sent to multiple email addresses the individual addresses must be separated by semicolons ";" or commas ","
Other information may be set in the Misc tab, including return email address, CC, BCC.

The two Send Method tabs specify which SMTP servers (primary and backup) the email should be sent through.

Please note that many SMTP gateways require that you specify a valid return email address before they will accept and send the email.

VoiceGuide can send emails by connecting to an SMTP server, or a server that supports SSL secure STMP connections started using STARTTLS (TLS Security). SMTPS servers are not supported.

Most STARTTLS connections are made using port 587. If a different port is to be used for a STARTTLS connection then the server name should be prefixed with ssl: to indicate that STARTTLS is to be used.

eg:

ssl:smtp.gmail.com

Gmail supports STARTTLS connections for outgoing emails, so if you encounter problems with your local SMTP server not supporting STARTTLS then a free Gmail account can be used to send out the emails.

If the email was queued to be sent then the Success path will be taken. If there were problems with queuing the email then the Fail path will be taken. Note that a 'Success' result does not indicate that email was successfully sent out or delivered. A 'Success' result just indicates that the email was queued for sending.

What the above paths do:
on {Success} goto [Confirm Email Sent] | Go to module "Confirm Email Sent"
on {Fail} goto [Say Error] | Go to module "Say Error"

Result Variables

The following Result Variables are created by this module:

$RV[module title]

Will store the destination email address.

$RV[module title_Subject]

Will store the email message subject.

$RV[module title_Message]

Will store the email message body text.

$RV[module title_Attachment]

Will store the filename of the attached file sent.

$RV[module title_SendResult]

Will store whether sending of the email was successful or not. Stores 'OK' if the message was sent, or stores an error code if the message could not be sent. An error code of 3 means that Microsoft Outlook/Exchange/Messaging was not running at the time.


Database Query Module

The Database module can access databases and data files. Any information retrieved is made available for use by subsequent modules.

Following technologies can be used to interact with databases:

  • .NET Data Providers (ADO.NET)
  • ODBC
  • OLE DB

All databases support at least one of the above interfaces.

Module Parameters

.NET Data Provider | Used to specify the .NET Data Provider to use. Can be left blank if using ODBC or OLE DB.
Connect String | Connect String to use.
SQL Query | The SQL statement to run, or the rage of cells to retrieve from Excel.

Result Variables can be used in all of the above fields.

Below are some examples illustrating the different Connect String which can be used to access various databases. More examples of connect strings can be found at: http://www.connectionstrings.com

.NET : MS SQL Server

Data Provider: System.Data.SqlClient
Connect String: Data Source=myServerAddress;Initial Catalog=myDataBase;User Id=myUsername;Password=myPassword;

.NET : MySQL

Data Provider: MySql.Data.MySqlClient
Connect String: Server=myServerAddress;Database=myDataBase;Uid=myUsername;Pwd=myPassword;

.NET : SQLite

Data Provider: System.Data.SQLite
Connect String: Data Source=C:\MyPath\MyDatabase.db

ODBC : MS SQL Server

Connect String: Driver={SQL Server Native Client 10.0};Server=myServerAddress;Database=myDataBase;Uid=myUsername;Pwd=myPassword;

ODBC : MySQL

Connect String: Driver={MySQL ODBC 5.1 Driver};Server=myServerAddress;Database=myDataBase;User=myUsername;Password=myPassword;Option=3;

ODBC : Oracle

Connect String: Driver={Oracle in OraHome92};Server=myServerAddress;Dbq=myDataBase;Uid=myUsername;Pwd=myPassword;

ODBC : DSN Data Sources

Connect String: DSN=myDataSourceName;

NOTE: on 64 bit systems the 32-bit "ODBC Data Source Administrator" must be used to create the data source. The 32 bit "ODBC Data Source Administrator" can be found at C:\Windows\SysWOW64\odbcad32.exe

OLEDB : MS Access

Connect String: Provider=Microsoft.ACE.OLEDB.12.0;Data Source=C:\mydatabase.accdb;

OLEDB : MS Excel

Connect String: Provider=Microsoft.ACE.OLEDB.12.0;Data Source=c:\myFolder\myExcel2007file.xlsx; Extended Properties="Excel 12.0 Xml;HDR=NO;IMEX=1";

Password Security

If passwords need to be provided as part of the database connect string, it is recommended that entire VoiceGuide script is saved as a Protected Script.
This way the passwords will be encrypted and not readable unless the VoiceGuide script password is known.

Query Results

The results of the database query are accessible using Result Variables.
The following Result Variables can be used to access data retrieved by a Db Query module:

$RV[ModuleTitle_ColumnIndex_RowIndex]

eg: module GetOrderDetails uses a query:

SELECT tel, email FROM Customer WHERE custid='$RV[GetCustId]'

After running above query:
$RV[GetOrderDetails_tel_1] (or $RV[GetOrderDetails_1_1] ) can be used to access the contents of the tel column, and
$RV[GetOrderDetails_email_1] (or $RV[GetOrderDetails_2_1] ) can be used to access the contents of the email column for first returned customer.

$RV[GetOrderDetails_tel_2] can be used to access the contents of the tel column for second customer, etc.

The following Result Variable can be used to access the number of database entries which were returned:

$RV[ModuleTitle_RowCount]

And if there in an error with connecting to database or running the SQL then the error details will be stored in this $RV:

$RV[ModuleTitle_error]

Play Tab

If "Wait Until SQL Command Completes" option is selected, the sound file specified in the Play tab will be played while the database query is performed.

Paths:

Three paths can be selected from this module:
Success | Some data was retrieved/updated/matched.
Fail | No data was retrieved/updated/matched.
Timeout | Command took longer then the specified Timeout.
Error | There was an error in connecting to database or executing the SQL command

Retrieving Data

As an example lets take an application where the caller would like to get a list of people from specified area code, and retrieve some details about them.

Suppose the caller has entered the postal area code in a Get Numbers module titled 'Ask for ZIP'.
This entered data would be stored in $RV[Ask for ZIP]
We can now use $RV[Ask for ZIP] as part of an SQL query to retrieve details.
Say we use a Database Query module titled GetClientDetails and use this SQL Query:

SELECT ClientName, BalanceOwing, WorkPhone, MobilePhone FROM Clients WHERE PostalCode='$RV[Ask for ZIP]'

The count of how many clients were found would be stored in: $RV[GetClientDetails_RowCount]
The first client's details would be accessible using:
$RV[GetClientDetails_ClientName_1] through to $RV[GetClientDetails_MobilePhone_1]
alternatively, these $RVs can also be used to read the retrieved data:
$RV[GetClientDetails_1_1] through to $RV[GetClientDetails_4_1]

Say Number modules can be used to play the numeric information, like the balance and telephone numbers. TTS can be used to play the text information.

Inserting Data

The following SQL statement shows how to insert data into Payments table. In this example the Payments table has the following fields (amongst others): CustomerID, PayAmount, CardNumber, ExpDate.
The values to be inserted into the database have been entered by the user in previous modules and Result Variables are used to in the expression.
The result variables will be replaced by VoiceGuide by the actual entered data before the SQL statement is executed.

INSERT INTO Payments (CustomerID, PayAmount, CardNumber, ExpDate) VALUES ('$RV[GetCustId]', '$RV[GetPayAmount]', '$RV[GetCardNumber]', '$RV[GetExpiryDate]')

Updating Data

The following SQL statement shows how to modify data in the Payments table. The Payments table has has the following fields (amongst others) CustomerID, PaymentStatus. The result variables will be replaced by VoiceGuide by the actual entered data before the SQL statement is executed.

UPDATE Payments SET PaymentStatus='Paid' WHERE CustomerID='$RV[GetCustId]'

In the examples above we have used single quotes as part of the WHERE and VALUES sections of the SQL statement. Single quotes should be used when referring to string or text fields in the database. When referring to number fields the single quotes should not be used: eg:

UPDATE Products SET UnitPrice=$RV[AddToPrice] WHERE ProductID=$RV[GetProductId]

Running Stored Procedures

Stored Procedures can be ran using the SQL EXEC statement:

EXEC UpdateStatusToPaid '$RV[GetCustId]'

More advanced Stored Procedure calls can be performed using VBScript - for which the 'Run VBScript' module can be used.

Working with BLOBs

VoiceGuide allows BLOB handling. BLOBs are usually used to store sound or graphics files or other large data files.

To specify a BLOB data element at insert the following needs to be to be specified as part of the SQL statement:

<BLOB><file>filename</file></BLOB>

eg:

INSERT INTO VmMsgs (Vmb, MsgKey, WavBlob) VALUES (1111, '$RV[MsgID]', <BLOB><file>$RV[Rec]</file></BLOB>)

To specify a BLOB data element for retrieval the following needs to be to be specified as part of the SQL statement:

<BLOB><dbcolumn>ColumnName</dbcolumn><file>filename</file></BLOB>

eg:

SELECT Vmb, <BLOB><dbcolumn>WavBlob</dbcolumn><file>c:\retrievedBLOB.wav</file></BLOB> FROM VmMsgs WHERE MsgKey='$RV[MsgID]';

BLOB reading/writing is only supported if .NET Data Providers are used to connect to the database.

A sample script which writes and reads .WAV sound files as BLOB to/from database is provided in VoiceGuide's "scripts\Database BLOB WriteRead" subdirectory.

Books on SQL

A good introductory book on SQL is:
"SQL Queries for Mere Mortals" by Michael J. Hernandez, John Viescas
ISBN 9780201433364

Microsoft Excel Example

The DB Query module can also retrieve data directly from an Excel file.

Excel range query specification follows this format :

SELECT * FROM [SheetName$StartCell:EndCell]

For an application which allows people to query a daily roster the Excel spreadsheet may look something like this:

The caller would enter their Roster Number - which corresponds to the row in the Excel spreadsheet, and then we could retrieve the information in the 'start time' and the 'end time' columns using the following query:

SELECT * FROM [Sheet2$B$RV[Get Roster Number]:C$RV[Get Roster Number]]

The returned data would be saved in Result Variables. If the database query module's title was GetTimes then the Start Time would be accessed using $RV[GetTimes_1_1] and the End Time would be accessed using $RV[GetTimes_2_1]

If we had each day of the week on a different page, we could also ask the customer to enter the day that they want to enquire about, and then our Query would be:

SELECT * FROM [Sheet$RV[GetDay]$B$RV[Get Roster Number]:C$RV[Get Roster Number]] Please note that to retrieve only the value of a single cell (say B5 on Sheet2) the cell address still needs to be specified as a range, so the cell location expression should be: "Sheet2$B5:B5" (Using "Sheet2$B5" will result in an error returned by Excel)


Run Program Module

This module will run the specified program. Result Variables can be used when specifying the program's name and the parameters passed to the program.

Run Program Tab

The Program name and parameters passed to the program are specified here.

Play Tab

If "Wait Until Program Finishes" option is selected, the sound file specified in the Play tab will be played while the started program is executing. The playing of the sound file will be stopped as soon as the the program finishes.

Paths Tab
Wait until program finishes | If the result file contains some data, then the "Success" path is taken. If the result file is empty then the "Fail" path is taken. If the program could not be started then the "Fail' path is taken.
Don't Wait | If the program was started successfully then the "Success" path is taken. If the program could not be started then the "Fail' path is taken.

After reading in the result file, VoiceGuide will rename the file by adding a ".last" to the filename.

Timeout Paths

When used in Run Program module, a Timeout Path can be used to limit the maximum amount of time the module will wait for the called program to finish (when "Wait until program finishes" option is selected). When the timeout is reached the module will close the program it has called, and go the module specified in the Timeout Path.

Returning data from ran program back to VoiceGuide

There are two ways in which the ran program can return data back to VoiceGuide:

  • Calling VoiceGuide's COM/WCF functions. eg: Run_ResultReturn

or:

  • Creating a 'Result File' which is then read in by VoiceGuide.

Result Files

If "Wait Until Program Finishes" option is selected, then VoiceGuide will wait until the program completes and afterwards VoiceGuide will look for the result file which can be optionally created by the called program. The file can be created in the script's directory, or in the directory where the program was ran from, or in VoiceGuide's \data\ subdirectory.
The file must be named VGRUNRESULT_LineNumber.TXT

The LineNumber is the ID of the line which is executing the Run Program module, and it can be passed to your program using the $RV_LINEID Result Variable.

The result file can be used to return results back to VoiceGuide. This file should contain the list of the Result Variables that you want VoiceGuide to read in, along with their values.

The syntax for the VGRUNRESULT_LineNumber.TXT file is:

[Result Variable Name]{Result Variable Value}

Multiple Result Variables can be specified. For Example, the following contents:

[RvName1]{Value1}[RvName2]{Value2}[RvName3]{Value3}[RvName4]{Value4}

Would return 4 Result Variables to VoiceGuide, whose values would be whatever is contained in the curly brackets. All Result Variables must be listed on a single line.

Task Start Modes

VoiceGuide can start the program as a Simple Process, or run it as a Logged In User, or use the Shell to run it.

The default option is set in VG.INI, section [moduleRunProgram], entry: StartTask_Mode

Mode preference can also set during the call by setting this Result Variable: $RV[ini_moduleRunProgram_StartTask_Mode]

Allowed settings are:

simple
logged_in_user
shell
cmd

Example 1:

A custom written utility ReadData.exe to retrieve information about a product has been written and the system has a Get Number Sequence module called Get Data Type which is used to ask caller to select what data is to be retrieved. The ReadData.exe is then called with the information entered in Get Data Type passed as a parameter.

Result File is then be used to return the retrieved data. ReadData.exe writes the following data into the file:

The above will create 3 new Result Variables in VoiceGuide, which can be accessed using:

$RV[Product_Price]
$RV[Product_InStock]
$RV[Product_OnOrder]

whose values are:

1495
7
50

respectively. These Result Variables can then be used is Say Numbers modules to speak out this information to the caller.

Example 2:

The Run Program module can be used to write out data that the caller has entered into a file. The command below will write out the 3 pieces of data gathered in Get Number Sequence modules out into the file output.txt:

command.com /c echo $RV[GetUserId], $RV[GetProductID], $RV[GetOrderAmount] >> c:\output.txt

Use ">" instead of ">>" if you would like to overwrite the output.txt file instead of appending to it.

Always specify the full path of the file to which the output is echoed - if you do not specify the full path sometimes the output file will not be in the scripts' directory.

Note: If writing to same log file from subsequent modules in same script or from multiple lines then it's preferable to use the Run VB Script module to write log files, as the DOS echo command does not handle concurrent writing to the same file well.

Example 3:

Sound Recorder application specifying that it should play the specified sound file and then close afterwards using this command line:

sndrec32 /play /close c:\test.wav

The Media Player application can also be used for this purpose:

mplayer /play /close c:\test.wav

If you are finding that the program does not run as VoiceGuide cannot find it then try specifying the full path to where your program is on your system. For example, the Media Player program on some systems is actually in:

C:\Program Files\Windows Media Player\mplayer2.exe

which would make the actual command line required to be used in the Run Module:

C:\Program Files\Windows Media Player\mplayer2.exe /play /close c:\test.wav

Example 4:

Send a message to another computer, alerting a particular user of an event. eg. when the caller on the VoiceGuide system is about to be transferred to their extension.

net send someusername "VG call from $RV_CIDNUMBER"

Example 5:

Running batch files (.bat) : To run a batch file from a Run Program module it is best to create a shortcut (a link) to the batch file and run the shortcut itself. You may need to use the actual name of the file as shown when doing a DIR listing in the DOS Command Prompt window.


Run Script Module

This module will run a VBScript or JavaScript or JScript.

After starting the script this module can:

  • Continue, without waiting for script to complete.
  • Wait until script completes.
  • Wait until script and sound file completes.

Continue, without waiting for script to complete option

VoiceGuide will immediately continue down the "Success" path once script was started successfully. If script could not be started successfully then the "Fail" path is taken. If the path that VoiceGuide should be following is not defined then VoiceGuide will hang up the call.

Wait until script completes option

VoiceGuide will wait until the script finishes running, or a response from the executing script is received.

Script can send responses back to VoiceGuide while it is executing by calling one VoiceGuide's ActiveX/COM functions. The functions which are considered to return a result back to VoiceGuide are: Run_ResultReturn(), Script_Gosub(), Script_Goto(), Script_Return(). For more information on VoiceGuide's ActiveX/COM interface please see the COM Interface section of Help file.

Once VoiceGuide detects that a script has completed and no COM response was received beforehand then VoiceGuide will see if a "Result File" has been created by the script. If one has been created then VoiceGuide will read in it's contents and then determine what to do next based on the contents of the file.

The syntax of the Result File is the same as that used by the Run Program module. Please refer to the Run Program module Help file's section for more information.

A "Success" or Result Variable list must be returned to VoiceGuide (either though a Run_ResultReturn COM function or a Result File) in order for it to go down the Success path.
If no result is returned then the "Fail" path is taken after the VBScript completes.
Calls to Script_Gosub(), Script_Goto() and Script_Return() functions result in immediate running of the next module.

Any sound files still playing when VBScript completes will be stopped.

Wait until script and sound file completes option

VoiceGuide will wait until the script finishes running (or a response from the executing script is received) and until the sound file playing completes. Sound file to play can be specified either using the "sound file to play" text box or can be started from with the script itself using the Play_Start COM function.

Other functionality is similar to the "Wait until script completes" option above.

Limiting maximum execution time

To limit the length of time the script is allowed to run for, a Timeout Path should be defined. If the script does not finish before the timeout occurs the script will be terminated and the timeout path will be taken. The timeout value is in seconds and should not be set to 0 - a value of 0 will result in the script being aborted immediately after it is started, without giving it any chance to run.
Minimum timeout value used should be 2 seconds.

Play Tab

If "Wait Until script Finishes" option is selected, the sound file specified in the Play tab will be played while the started program is executing.

VBScript

VBScript is the default language used by the Run Script module, and the VBScript interpreter will be used if no special tags are specified on the first line of the script file.
VBScript is a scripting language developed by Microsoft. It is similar to Visual Basic for Applications (VBA) used in Microsoft Office.
VoiceGuide can run VBScripts internally, using the built-in VBScript-ClearScript engine.
VoiceGuide can also run VBScripts using an external interpreter, which by default is WSH's cscript.exe

VoiceGuide's interface can be called from VBScript using the predefined object: vgo like this:

The vgo object is automatically created and made available to all VBScripts ran by VoiceGuide internally by the ClearScript engine.

If running the VBScripts using the external interpreter the VoiceGuide's vgServices.CommandLink COM object needs to be created in order to be able to access the VoiceGuide interface.
eg:

It is fine to create vgServices.CommandLink COM object in VBScript's ran internally by the ClearScript engine, but using the predefined vgo object is faster.

VBScript Books:

VBScript Step by Step - Ed Wilson

"VBScript in a Nutshell" by Ron Petrusha, Matt Childs, Paul Lomax

Here is a VBScript editor which can be used to develop scripts before moving them over the the Run Script module: www.vbsedit.com.

JavaScript

VoiceGuide can run JavaScript internally, using the built-in V8-ClearScript engine.

To have the module execute JavaScript, the first line of the script must begin with this:

"//JavaScript" indicates to VoiceGuide that the contents of this module are JavaScript and not the default VBScript.
V8 JavaScript engine is used to interpret JavaScript code.

If no special tags are specified on the first line, then module will execute the code as VBScript.

VoiceGuide's interface can be called from JavaScript using the predefined object: vgo like this:

The vgo object is automatically created and made available to all JavaScripts ran by VoiceGuide.

COM objects cannot be created in JavaScript.

JScript

JScript is Microsoft's version of JavaScript.
VoiceGuide can run JScripts internally, using the built-in JScript-ClearScript engine.
COM objects can be created in JScript.

To have the module execute JScript, the first line of the script must begin with this:

"//JScript" indicates to VoiceGuide that the contents of this module are JScript and not the default VBScript.
ClearScript's JScriptEngine is used to interpret JavaScript code.

VoiceGuide's interface can be called from JScript using the predefined object: vgo like this:

The vgo object is automatically created and made available to all JScripts ran by VoiceGuide.

VoiceGuide's vgServices.CommandLink interface COM object can be created in JScript, this however would be rarely required as the vgo object is available. Example is provided for completeness:

Using Result Variables

Result Variables can be used throughout the script.

Before running the Script, VoiceGuide will first see if there are any Result Variables specified within the script, and if there are then VoiceGuide will first replace them with their current values and run the resulting script then.

If the Result Variable is not defined then VoiceGuide will replace it with an empty string.
For this reason it is often desirable to have the Result Variables used with quotes specified around them.

eg: If Caller ID information did not arrive then VoiceGuide will replace $RV_CIDNUMBER with an empty string before letting the script run.

So, if Caller ID information did not arrive then this script code:

would be changed to

Which is not valid VBScript and hence an error will occur.

But if you write the code using quotes around the RVs, like this:

and Caller ID information did not arrive,
then the resulting VBScript which VoiceGuide actually runs would be:

Which is a valid VBScript and when running it no errors will be generated and the script will work as expected.

Result Variables should not be directly used in places where replacement with a blank would cause a syntax error.
Instead a variable which gets set to the RV value beforehand should be used in those situations.
That way there is no syntax error and the check for whether RV holds any data can be made earlier in the script and the appropriate action taken if RV does not hold a value.

Notes:

After the Result Variables have been replaced in the script, the new script can be optionally saved in VoiceGuide's \temp\ sub-directory, named as vbs_LineId_ThisCallScriptIndex.vbs Viewing this file will allow you to confirm that Result Variable replacement was done correctly.

This saving to .vbs file can be enabled/disabled in VG.INI, in [moduleRunScript] section.

How VoiceGuide's Run Script module runs the Scripts

By default VoiceGuide uses its own built-in script interpreter to run scripts from the Run Script module.
This built-in script interpreter is based on Microsoft's ClearScript engine.

VoiceGuide can be instructed to use an external application to execute the script instead.
An external interpreter is chosen if the script that is to be ran uses objects that cannot be handled by the internal interpreter. Some Database related COM objects fall into this category.
The external interpreter often used is Windows' own C:\Windows\SysWOW64\cscript.exe

Configuring VoiceGuide to always use the 'external interpreter' can be done by setting the entry Engine in VG.INI's [moduleRunScript] section to cscript
Like this:

[moduleRunScript]
Engine=cscript

Another approach is to set the $RV[ini_moduleRunScript_Engine] in the VoiceGuide script to cscript just before running the Run Script module that needs to use the external interpreter, and then set it to ClearScript for following Run Script modules to use the internal interpreter.
This allows the setting of interpreter to be used by the Run Script module to be done dynamically, during the call.

Running VBScripts from Command Line

VBScript .vbs files can also just be executed by by using the Windows' wscript.exe and cscript.exe utilities.

On current versions of Windows (which are all 64-bit) open a command prompt (best to use the 'Administrator Command Prompt'),
then change directory to the VoiceGuide's \temp\ sub-directory and run this command line:

C:\Windows\SysWOW64\wscript.exe vbs_x_y.vbs

Where vbs_x_y.vbs is the filename of the .vbs file which you wish to run.

VoiceGuide is 32-bit software so any VBScripts that use the VoiceGuide COM interface need to be ran using the 32-bit version of VBScript interpreter.

On 64-bit systems if you change the Registry Key:

Computer\HKLM\SOFTWARE]\Classes\VBSFile\Shell\Open\Command

to use the 32-bit C:\Windows\SysWOW64\cscript.exe or C:\Windows\SysWOW64\wscript.exe then the .vbs files can be ran by just being double-clicked.

On 32-bit versions of Windows the .vbs files can be ran by just double clicking on them.

Examples

Following are some examples of VBScripts which can be ran in the Run Script module.
VoiceGuide's Voicemail system also uses the Run Script modules extensively.
See VoiceGuide's \system\vm\ directory.

Example : Save to File

The VBScript below will append a line of text to the file C:\LogCall.txt - the line of text will contain information about start of the call, caller's telephone number and information entered by caller in module "EnterClientNumber". Result Variables are used in this script to allow information from VoiceGuide to be visible to the VBScript.

Example : Read from File

The VBScript below will read the contents of file C:\CurrentPrices.txt and will assign them to VoiceGuide Result Variable $RV[ReadInPrice]

Example : Read from Excel

The VBScript below retrieves information from an Excel spreadsheet.

Example: Save to Excel

The VBScript below saves information to an Excel spreadsheet.

Example : Creating Result File

The VBScript below demonstrates how the $RV_LINEID Result Variable is used to generate a Result file from which the data is read back into VoiceGuide. Please note that using the COM function Run_ResultReturn() is a preferable way of returning information to VoiceGuide (it's faster) - but a result file can be used if there is no other way.

It is recommended that the full path to the result file be specified, otherwise the Windows' current 'default' path will be used by the file subsystem - and that does not always point to the same path as the script's.

Example : MS Access Database read/write

Retrieving data from an MS Access database using an SQL query, and then updating the same record with new values:

Example : MS SQL Server Database read/write

A script like this can be used :

Example : Stored Procedure defined in the database (no parameters)

Let's assume that you have defined in your database a stored procedure named RetrieveUserNames that returns a recordset but takes no parameters. (note this example assumes that the database connection cn and VoiceGuide CommandLink vg are defined outside this function). The following code will retrieve the records.

Example : Stored Procedures defined in the database (with parameters)

Let's assume that you have defined in your database a parameterized stored procedure query named UpdateUser as follows:

The only thing you need to do is to match the order and data type of the parameters that are 'appended' to the command object with those of the MS Access query.

Example : Retrieving data from an ASMX / SOAP Web Service

NOTE: We recommend using the Web Service module when interacting with web services.

The VBScript below retrieves the WSDL from the ASMX / SOAP Web Service provided by cdyne.com, and then calls the Web Service function

GetCityWeatherByZIP.

In this example the ZIP code 10004 (New York, NY) was used.

Returned data is then formatted as a Result Variable list and returned to VoiceGuide.

Microsoft's SOAP Toolkit must be installed on system to use the MSSOAP.SoapClient30 COM object.

The Result Variables list returned would be something like this:

[Success]{true}[ResponseText]{City Found}[State]{NY}[City]{New York}[WeatherStationCity]{White Plains}[WeatherID]{4}[Description]{Sunny}[Temperature]{46}[RelativeHumidity]{17}[Wind]{NW16G26}[Pressure]{30.20F}[Visibility]{}[WindChill]{}[Remarks]{}

Example : Retrieving data from a HTTP / REST Web Service using HTTP GET

NOTE: We recommend using the Web Service module when interacting with web services.

Request to a Web Service can be made directly to the service/function URL.

eg. a GET call to cdyne.com GetCityWeatherByZIP function can be made directly to this HTTP address:

http://wsf.cdyne.com/WeatherWs/Weather.asmx/GetCityWeatherByZIP?ZIP=10004

and since the GetCityWeatherByZIP function returns data in XML format we can use the XML functions to to extract the required data.

Example : Uploading data to HTTP / REST Web Service using HTTP POST

NOTE: We recommend using the Web Service module when interacting with web services.

Request to a Web Service can be made directly to the service/function URL.

eg. a POST call to cdyne.com GetCityWeatherByZIP function can be made directly to this HTTP address:

http://wsf.cdyne.com/WeatherWs/Weather.asmx/GetCityWeatherByZIP and since the GetCityWeatherByZIP function returns data in XML format we can use the XML functions to to extract the required data.

eg. a new ticket in the zendesk.com system can be created using a HTTP POST call to URI:

https://yourname.zendesk.com/api/v1/tickets.xml

with ticket data provided as data attached to the POST:

Example : Screen Scraping from Web Page

If the required information is not available through a web service but is shown on the web page itself, a screen-scraping approach can be used.

The VBScript below retrieves stock market levels from www.finance.yahoo.com and returns this data to VoiceGuide. (Please see the Web Site Scraping demo script).


Web Service Module

This module lets VoiceGuide communicate with HTTP and HTTPS Web Services.

Following request types can be used:

  • GET
  • POST
  • DELETE
  • PUT
  • UPDATE

Module supports setting of:

  • URL Address
  • Post Data
  • Headers
  • Authentication

After issuing the request to the Web Service, VoiceGuide can:

  • Continue, without waiting for web service query to complete.
  • Wait until web service query completes.
  • Wait until web service query and sound file completes.

Continue, without waiting for web service to complete :
VoiceGuide will immediately continue down the "Success" path once the web service query was started successfully. If web service query could not be started successfully then the "Fail' path is taken. If the path that VoiceGuide should be following is not defined then VoiceGuide will hang up the call.

Wait until web service query completes :
VoiceGuide will wait until the web service query completes. Any sound files still playing when the web service query completes will be stopped.

Wait until web service and sound file completes :
VoiceGuide will wait until the web service completes and until the sound file playing completes.

Limiting maximum execution time

To limit the length of time the system waits for the web service to return, a Timeout Path should be defined. If the web service does not return before the timeout occurs the web service query will be terminated and the timeout path will be taken. \The timeout value is in seconds and should be set to a value of 1 or higher.

Play Tab

If "Wait Until Web Service Completes" option is selected, the sound file specified in the Play tab will be played while the web service query is performed.

Using Result Variables

Before running the web service VoiceGuide will first see if there are any Result Variables specified within the web service's HTTP address (URI), Post Data, Headers etc. and if present then VoiceGuide will first replace them with their current values.

If the Result Variable is not defined then VoiceGuide will replace it with an empty string.

If after replacing the Result Variables in Data ad/or Headers the outcome points to a valid file then the contents of that file will be read in, any $RVs within that read in file contents replaced, and that result will then be used as the Data and/or Header for that Web Service interaction.

Returned Result Variables

A Result Variables ($RV) is created for each data item returned by the Web Service. The $RVs are named:

$RV[ModuleTitle_XPathToDataNode]

Where XPathToDataNode is the XPath or JsonPath to the returned data.

It is recommended to look at VoiceGuide's vgEngine log (in VoiceGuide'S \log\ subdirectory) to establish what $RVs are created when a particular web service is called. Created $RVs will not all be saved in the Script's Log.

The following $RVs are always created:

$RV[ModuleTitle_Result_Code] : Returned Status code

$RV[ModuleTitle_Result_Desc] : Returned Status description

$RV[ModuleTitle_Result_Data] : Data received from by the web service

$RV[ModuleTitle_Result_Data_QE_Doubled] : Data received, with all Double Quote characters " replaced (escaped) with "" . This $RV can be used in scripting modules etc.

$RV[ModuleTitle_Result_Data_QE_Backslash] : Data received, with a backslash \ added before all Double Quote characters " This $RV can be used in scripting modules etc.

The Headers of the returned response are also saved as Result Variables.

Individual data elements also have $RVs created for them.

Please consult VoiceGuide's vgEngine log (in VoiceGuide'S \log\ subdirectory) to establish what $RVs are created when a particular web service is called.

If other information needs to be retrieved from the returned data then VBScript modules can be used to process the returned data, which is stored in $RV[ModuleTitle_Result_Data] etc. $RVs.

Paths

The following are valid path options:

  • Success/Fail
  • HTTP Response Codes
  • Timeout

eg: The following HTTP Response Code paths are all valid:

on {200} goto [Say all went OK]
on {OK} goto [Say all went OK]
on {406} goto [Say trans not accepted]
on {Not Acceptable} goto [Say trans not accepted]

$RV[moduleTitle_PathTaken]
Stores which path was taken when exiting the module.

Script Examples

Sample scripts are provided in VoiceGuide's \Scripts\Web Service\ subdirectory.
Script provided there demonstrate the use of the various HTTP request methods.
See here for another example of use.

Example : GET Request (XML returned)

If the response to a HTTP GET request is:

<?xml version="1.0" encoding="utf-8" ?>
<WeatherReturn xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Success>true</Success>
<ResponseText>City Found</ResponseText>
<State>NY</State>
<City>New York</City>
<WeatherStationCity>White Plains</WeatherStationCity>
<WeatherID>4</WeatherID>
<Description>Sunny</Description>
<Temperature>46</Temperature>
<RelativeHumidity>17</RelativeHumidity>
<Wind>NW16G26</Wind>
<Pressure>30.20F</Pressure>
<Visibility />
<WindChill />
<Remarks />
</WeatherReturn>

Then the following Result Variables would be created by VoiceGuide for this response (module's title is "getweather"):

$RV Created | $RV Value
$RV[getweather_Success] | true
$RV[getweather_ResponseText] | City Found
$RV[getweather_State] | NY
$RV[getweather_City] | New York
$RV[getweather_WeatherStationCity] | White Plains
$RV[getweather_WeatherID] | 4
$RV[getweather_Description] | Sunny
$RV[getweather_Temperature] | 46
$RV[getweather_RelativeHumidity] | 17
$RV[getweather_Wind] | NW16G26
$RV[getweather_Pressure] | 30.20F
$RV[getweather_Visibility] |
$RV[getweather_WindChill] |
$RV[getweather_Remarks] |

The above Result Variables can then be used for the remainder of the call.

Example : GET Request (JSON returned)

If the response to a HTTP GET request is:

{
"cod":"200",
"message":0.0254,
"cnt":39,
"list":[
{
"dt":1493002800,
"main":{
"temp":297.06,
"temp_min":295.641,
"temp_max":297.06,
"pressure":1027.34,
"sea_level":1033.43,
"grnd_level":1027.34,
"humidity":81,
"temp_kf":1.42
},
"weather":[
{
"id":800,
"main":"Clear",
"description":"clear sky",
"icon":"01d"
}
],
"clouds":{
"all":0
},
... etc.

Then the following Result Variables ($RVs) would be created by VoiceGuide for this response (module's title is "getweather"):

$RV Created | $RV Value
$RV[getweather_cod] | 200
$RV[getweather_message] | 0.0254
$RV[getweather_cnt] | 39
$RV[getweather_list_1_dt] | 1493002800
$RV[getweather_list_1_main_temp] | 295.641
$RV[getweather_list_1_main_temp_min] | 296.06
$RV[getweather_list_1_main_temp_max] | 297.06
$RV[getweather_list_1_main_pressure] | 1027.34
$RV[getweather_list_1_main_sea_level] | 1033.43
$RV[getweather_list_1_main_grnd_level] | 1027.34
$RV[getweather_list_1_main_humidity] | 81
$RV[getweather_list_1_main_temp_kf] | 1.42
$RV[getweather_list_1_weather_1_id] | 800
$RV[getweather_list_1_weather_1_main] | Clear
$RV[getweather_list_1_weather_1_description] | clear sky
$RV[getweather_list_1_weather_1_icon] | 01d
$RV[getweather_list_1_clouds_all] | 0
etc. | etc.

Above example was taken by accessing the OpenWeatherMap.org API at: http://api.openweathermap.org/data/2.5/forecast?id=6619279&APPID=6ef9cb723afa6226e5e7628d83094aec

Example : POST Request : Add Ticket to Zendesk

Zendesk (http://www.zendesk.com/) provides a HTTP REST API.

Following example shows show VoiceGuide's Web Service module can be used to add a new ticket to your Zendesk account:

NB. this POST request will require authentication, and hence would require that your own Zendesk account is set up first. The URL would need to be modified accordingly.

Example : POST Request to ASMX Web Service

Issuing a SOAP 1.2 POST request to an ASMX Web Service:

Then SOAP XML structures to use is displayed when the Web Services' ASMX URL is viewed in a web browser.

Most ASMX Web Services support SOAP 1.2 format. Issuing a SOAP 1.1 format POST request is only slightly different:

HTTPS

TLS 1.1 and TLS 1.2 are supported (in VoiceGuide v7.6 and later). The older TLS 1.0 and SSL3 are also supported.

Client Certificates

To have the Web Service module use a "Client Certificate" from a Windows Certificate Store specify this in the Web Service module 'Options' text box: MyCertFriendlyName The "MyCertFriendlyName" must match the "Friendly Name" setting set for that certificate in the Windows Certificate Store. To have the Web Service module use a "Client Certificate" from a .pfx file specify this in the Web Service module 'Options' text box: c:\mydir\myfilename.pfx
myPassword

Token Based Authentication

Web Services that use Token Based Authentication will need to be accessed using two 'Call Web Service' modules.
The first module would be used to obtain the token (by passing to web service the login credentials) and the subsequent modules can use the tone to call the web service API.
The token is sometimes supplied in the headers section.
'Call Web Service' module supports setting of custom headers, and hence supports passing of Authentication Tokens in that way as well.

Password Security

If passwords need to be used to access the web service, it is recommended that entire VoiceGuide script is saved as a Protected Script.
This way the passwords will be encrypted and not readable unless the VoiceGuide script password is known.


Time Switch Module

This module is used to direct the caller to a different part of the script based on Date or Time of Day.

The screenshot above shows a time range to covering 9am till 5pm on Saturday and Sunday. The Date/Time to Check field is left blank so the current time when the script is executed will be used. When specifying the 'times on selected days' the start time must be earlier in the day then the stop time.

Paths Chosen

The path "True" is taken if the current time falls within the specified time range, otherwise the "False" path is taken.

Date/Time to Check

Most of the time this field will be left blank as usually the intention is to check what is the current time and if it falls within the specified time range.

If the module is used to check whether a date/time entered by caller or retrieved from the database falls within a certain range then the date to be checked should be specified in this text field.

The format in which the date is to be specified will vary according to your computers settings for preferred date/time format. If specifying date and time then usually one of the following formats will be OK (hours are specified in a 24 hour format) :

MM/DD, YYYY HH:NN
DD/MM, YYYY HH:NN
MM/DD/YYYY HH:NN
DD/MM/YYYY HH:NN
HH:NN

If the date is not specified then current date is used.

How can the caller enter date/time? Usually by just entering the required information in a series of Get Numbers modules and then having all the data entered concatenated together:

$RV[GetMonth]/$RV[GetDay], $RV[GetYearYYYY] $RV[GetHour24]:00

If date is retrieved from database you should ensure that the correct format is supplied.

If the date/time format supplied is invalid then the "False" path is taken.

Note

Evaluate Expression module can also be used to set up time-switching.


Transfer Call Module

The Transfer Call module will transfer the call to another extension or telephone number.

All types of call transfers are supported:

  • 'Dial and Conference' / 'Trombone' / 'Bridge' transfers
  • 'Group' transfers
  • Transfers to ACD queues
  • SIP REFER transfers (used on VoIP - SIP)
  • 'Hookflash' transfers (used on Analog lines)
  • TBCT transfers (used on ISDN trunks)
  • 3-way transfers

Result Variables can be used when specifying the transfer destination etc.

Dial and Conference / Tromboned Transfers

Supported on all VoIP systems and JCT and DMV series cards (eg. D/41JCT, D/120JCT, DMV160, D/240JCT, DMV600B etc.)
The D4PCIU* family cards do not support "Dial and Conference".

The Dialer add-on is required to use the "Dial and Conference" option.

Dial and Conference - Blind

  1. Dials the second number on another line.
  2. Connects the two calls together.

VoiceGuide will immediately take the Success path if it is defined, otherwise VoiceGuide will wait and hang up when:

  • busy
  • maximum connection time is reached
  • digit "*" is pressed during conversation

Dial and Conference - Monitored

  1. Dials the number on another line.
  2. Listens to see if the outgoing call is answered by a human or an answering machine. If a human or answering machine answer is detected then VoiceGuide connects the two calls together. If an announce message is specified the announce message is played to the call recipient before the call is connected.

If call is answered VoiceGuide will take the Success path. If call is not answered VoiceGuide will take the Fail path.
VoiceGuide can also wait in the module and hang up when:

  • either line hangs up
  • maximum connection time is reached
  • digit "*" is pressed during conversation

Dial and Conference - Announced

  1. Dials the number on another line.
  2. When call is answered VoiceGuide plays a message (message is settable in script), and waits for a keypress from the called person indicating whether they accept the call or not. "1" is used to accept the call, any other digit keypress indicates that the call is declined.

If call is accepted VoiceGuide will take the Success path. If call is not accepted VoiceGuide will take the Fail path.
VoiceGuide can also wait in the module and hang up when:

  • either line hangs up
  • maximum connection time is reached
  • digit "*" is pressed during conversation

Dial and Conference Options

Following user settable fields are available in Transfer module when "Dial and Conference" transfers are used:

  • On-hold sound file to play while connection is made
  • Line selection list
  • When to connect the two callers
  • Options

The Options field can be used to specify the outgoing CallerID used for the call by using the XML syntax.
eg: specifying <CallerId>5551234</CallerId> would result in CallerId to be set to 5551234 on outgoing calls.
Note that the CallerID settings in Config.xml would take precedence if set.

Dial and Conference on VoIP

If the Headers fields need to be added/modified in the outgoing SIP INVITE packet then these can also be specified in the Call Options field when loading the outgoing call. To add a SIP header a "<sip-header>" entry needs to be specified in the Call Options field.
eg: to add a "MyHeader" header, this entry could be added to the Call Options field:

<sip-header>MyHeader: "somevalue" <sip:123456@sip.router.com></sip-header>

Ring Group Transfer

Multiple parties can be dialed at the same time, with call connected to the party that answers first.
As soon as one call is answered all other calls are hung up.
This option can only be used on "Dial and Conference" type transfers.

To perform a Ring Group Transfer the multiple telephone numbers are specified separated by the & character.

eg:

5551111&5552222&5553333&5554444

Will result in calls to 4 numbers being placed, with the original caller then connected to the party that answers first.

ACD Queue Transfer

Call can be placed in ACD queue, and from the queue the call will then be transferred to an agent when the appropriate agent becomes available.
To place call in an ACD queue the following expression is used: acd:QueueName

eg:

acd:sales

VoiceGuide will search for agents that are qualified to receive calls from specified queue, and the call is then connected (using a 'tromboned' connection) to the agent.
To receive ACD calls, agents need to use the 'VoiceGuide Agent' application on their PC.

SIP REFER Transfer (RFC 3515)

To perform the RFC3515 REFER transfer select "Blind Hookflash Transfer" option and specify the IP/URI address of the transfer destination.

Two B-Channel Transfer (TBCT)

VoiceGuide v7 can perform TBCT transfers on ISDN lines which support this feature. To perform a TBCT transfer a 'Dial and Conference' transfer type needs to be selected, and then in the 'Dial and Conference Options' text box you need to include either:

<tbct_on>2ND_LEG_ALERTING</tbct_on>

or

<tbct_on>2ND_LEG_CONNECTED</tbct_on>

The <tbct_on>2ND_LEG_ALERTING</tbct_on> option will result in TBCT command being issued to the switch at the time when the 2nd leg of the call is in Alerting phase (2nd number begins to ring), and the <tbct_on>2ND_LEG_CONNECTED</tbct_on> option will result in TBCT commend being issued to the switch at the time when the 2nd leg of the call has connected (2nd call was answered).

Running Scripts on Outgoing Call Legs

By default no script runs on the port that is used to make the outgoing call for the 2-line "Dial and Conference" transfer.
If needed, a script on that port can be started using the Script_Goto command.
This may be useful if for example it is required that the outgoing leg of the transferred call continues after the call on the original leg has ended.

Event Paths

The following event paths can be taken from the module:
SUCCESS | the call was transferred successfully
FAIL | the call was not transferred, or transfer was declined
BUSY | number was busy
FAX | call was answered by a fax
NOANSWER | there was no answer
NODIALTONE | there was no dialtone
NORINGBACK | call was not answered and no ringback was heard
OPERATOR | SIT tone was heard indicating number is most likely disconnected
CONNECT | transfer completed successfully
AM | transfer completed successfully with Answering Machine answering the call
VOICE | transfer completed successfully with a live Human answering the call
CADENCE | transfer completed successfully based on cadence analysis
LOOPCURRENT | transfer completed successfully based on loop current detection

Timeout Paths

The following timeout paths can be set:
NOANSWER | Call was not answered within the specified timeout. If this timeout occurs time the 2nd leg of call is disconnected and the original caller is taken to the specified module. eg: on {noanswer 20} goto [try another number]
CALLTIME | Sets maximum call time. If this timeout occurs time the 2nd leg of call is disconnected and the original caller is taken to the specified module. eg: on {calltime 3600} goto [max calltime reached]
TIMEOUT | If the NOANSWER and CALLTIME timeout paths are not set then this timeout path is used instead (if defined). When this timeout is reached the 2nd leg of call is not automatically disconnected. This timeout path can be used to play messages to either side of call during the call. etc. eg: on {timeout 600} goto [play 10min warning]

Result Variables

For Tromboned transfers the following $RVs are created on both lines:

$RV[Conf_DevName_1]
$RV[Conf_LineId_1]
$RV[Conf_LineNbr_1]
$RV[ModuleTitle_DevName_1]
$RV[ModuleTitle_LineId_1]
$RV[ModuleTitle_LineNbr_1]

$RV[Conf_DevName_2]
$RV[Conf_LineId_2]
$RV[Conf_LineNbr_2]
$RV[ModuleTitle_DevName_2]
$RV[ModuleTitle_LineId_2]
$RV[ModuleTitle_LineNbr_2]

These $RVs can be further used to manage the connected calls in the future. vgEngine trace file contains more information on other $RVs created during the call transfer process.

Hookflash Transfers

Hookflash Transfer - Blind

  1. Dials the signal specified (usually just a hookflash),
  2. Dials the telephone number,
  3. Hangs up immediately

The caller will now be connected to another extension. VoiceGuide no longer monitors the call.

Some PBXs/Switches require that the destination extension starts ringing before VoiceGuide can hang up. When using such systems it may be necessary to add a comma or two at the end of the destination number to make VoiceGuide pause for a while after dialing the number and before hanging up the call.

Some PBXs/Switches require that the destination extension is answered before VoiceGuide can hangup. In such situations the "Announced" or "Monitored" transfer option will need to be used.

Hookflash Transfer - Monitored

  1. Dials the signal specified (usually just a hookflash),
  2. Dials the telephone number,
  3. Listens to see if a call is answered by a human or an answering machine. If a human or answering machine answer is detected then VoiceGuide hangs up, which completes the transfer. If no answer is detected or the extension is busy then VoiceGuide will dial the 'retrieve call from announced transfer' signal (usually just a hookflash) and go down the Fail path.

Hookflash Transfer - Announced

  1. Dials the signal specified (usually just a hookflash),
  2. Dials the telephone number,
  3. Plays a message announcing the Caller's ID, and awaits the selection from the called person whether to accept the call or not. "1" is used to accept the call, any other digit is used to decline the call. If "VoiceGuide for Dialogic" is used then the announce message will only start when VoiceGuide detects that the outgoing call has been answered.
  4. If the call is accepted VoiceGuide will dial the 'complete announced call transfer' signal (usually nothing is needed) and hang up and allow the two new parties to continue conversation. If the Success path is defined then that path will be taken, but script should be designed in such a way that VoiceGuide hangs up soon, so that the two parties can speak to one another.
    5. If the call is declined, the called party does not answer, or the extension is busy then VoiceGuide will dial the 'retrieve call from announced transfer' signal (usually just a hookflash) and then the "Fail" path is taken. If other more appropriate path is defined then that path is taken instead.

Note:

On Analog lines, when specifying the number to dial you can use commas ',' to indicate pauses in the dialing sequence. To include a pause between the hookflash and the telephone number being dialed a number of commas can be added before the phone number. Like this:

,,8843

On ISDN and VoIP connections commas cannot be used.

If your system requires other specialized PBX signaling keep in mind that Hookflash and DTMF signals can also be generated using the “Play” module.
“!” is used to generate a hookflash and digits are used to generate DTMF tones.

Timeout paths between successive Play modules can be used if specific delays between successive PBX signals are required.

3 Way Conference Calls

3-Way Call Service must be enabled on the telephone line by the telephone company or PBX administrator before you can use this feature.

Some telephone systems do not allow 3 Way Blind Conference Calling, and will only allow a 3 way conference call connection to be made when the called person has answered the phone. In those situations you must use the 3 Way Announced Conference Call option.

3 Way Conference - Blind

  1. Dials the signal specified (usually just a hookflash),
  2. Dials the telephone number,
  3. Dials the signal as specified in 'Complete blind conference call' setting (usually "!3")
  4. Waits until the call is finished.
VoiceGuide will take the Success path if it is defined, otherwise VoiceGuide will wait and hang up when:
  • either party hangs up.
  • maximum conference time limit is reached (settable in VG.INI file)
  • digit "*" is pressed during conversation

3 Way Conference - Monitored

  1. Dials the signal specified (usually just a hookflash),
  2. Dials the telephone number,
  3. Listens to see if a call is answered by a human or an answering machine. If a human or answering machine answer is detected that VoiceGuide hangs up. If no answer is detected then VoiceGuide will dial the 'retrieve call from announced transfer' signal (usually just a hookflash).
  4. If a human or answering machine answer is detected VoiceGuide will dial the 'complete announced conference' signal (usually "!3"). Then if the Success path is defined then that path will be taken, otherwise VoiceGuide will wait until end of call. If no answer is detected or the extension is busy then VoiceGuide will dial the 'retrieve call from announced conference' signal and then the Fail path is taken (If other more appropriate path is defined then that path is taken instead).

If call is accepted VoiceGuide will take the Success path if it is defined, otherwise VoiceGuide will wait and hang up when:

  • either party hangs up.
  • maximum conference time limit is reached (settable in VG.INI file)
  • digit "*" is pressed during conversation

3 Way Conference - Announced

  1. Dials the signal specified (usually just a hookflash),
  2. Dials the telephone number,
  3. Plays a message announcing the Caller's ID, and awaits the selection from the called person whether to accept the call or not. "1" is used to accept the call, any other digit is used to decline the call. If "VoiceGuide for Dialogic" is used then the announce message will only start when VoiceGuide detects that the outgoing call has been answered.
  4. If the call is accepted VoiceGuide will dial the 'complete announced conference' signal (usually "!3"). Then if the Success path is defined then that path will be taken, otherwise VoiceGuide will wait until end of call. If the call is declined, the called party does not answer, or the extension is busy then VoiceGuide will dial the “retrieve call from announced conference” signal and then the Fail path is taken.

If call is accepted VoiceGuide will take the Success path if it is defined, otherwise VoiceGuide will wait and hang up when:

  • either party hangs up.
  • maximum conference time limit is reached (settable in VG.INI file)
  • digit "*" is pressed during conversation

End of Call Detection

End of call detection on analog lines is done by listening for disconnect tone. Some phone companies hold off with playing the disconnect tone until some time after hangup, and sometimes the delay before the disconnect tone is played differs depending on whether the person who hung up was the one who made the call or received the call.

To be able to hangup calls immediately the phone company must either play the disconnect tone immediately after either party hangs up, or you should use VoIP or T1/E1 ISDN lines.

'Announced' transfers timeout

The default length for how long VoiceGuide will await a confirmation to receive a call is 30 seconds. If you would like to change this, specify a timeout path in the 'Announced' modules to indicate the number of seconds you would like VoiceGuide to wait.

Troubleshooting

If the call transfers are not working for you please go through this checklist:

  1. Can you do the call transfer manually on that line using a normal telephone handset?
  2. Is the hookflash the right length? (ie. is the original caller placed on hold?)
  3. Do settings in VG's "PBX Command Strings" config screen match the keys you need to press when doing it manually?
  4. If transfers are still not working please post a question on our online Support Forum.

  • Full detailed step-by-step description of how you just did the call transfer manually on this system
  • Your VoiceGuide script
  • VG.INI file
  • Copy of the trace log capturing the entire call


Evaluate Expression Module

Used to direct the script to a different module based on the value of Result Variable, Boolean expression or an Arithmetic expression specified. This module is used when the call is to go to different parts of script depending on:

  • Caller ID
  • Time and Date of the call
  • Information entered by caller
  • Information retrieved using DB Query / Web Service / Run Program / Run Script modules
  • Any VBScript expression (see here for complete list of functions)

The result of the evaluated expression will be assigned to the $RV[module title] Result Variable.

Optionally the result can also be assigned to a user specified Result Variable. This is useful when implementing counters or other more advanced call flow management.

The name of the user specified Result Variable can be anything. The user specified variable can be accessed in other parts of the script using $RV[user specified variable] format.

Selecting "Make Global RV" will make the created variable a "Global Result Variable". Global RVs need only be used if many different lines want to be able to read/set a central globally available variable which is retained by VoiceGuide as long as the software is running and does not get reset when any new calls arrive on any lines. (This option is used only in rare circumstances).

Selecting the "Store results in log file" option will ensure the results will be stored along with other call details. If the option is not selected the Result Variables will still be accessible within other parts of the script, but they will not be saved in the call log.

Paths Chosen:

If a Result Variable or an Arithmetic expression is specified:

  • if any of the paths match the result exactly then that path will be taken.
  • If none of the Paths match the value exactly, but the result is non-empty then the "True" path will be taken.
  • If the result is empty, then the "False" path will be taken.
  • If the result is a '0', then the "False" path will be taken.

If a Boolean expression is specified:

  • A "True" or a "False" path will be taken depending on what was the result of the expression.

Example 1:

The Evaluate Expression can be used to switch to different parts of the script based on Caller ID. To switch based on the caller's phone number use $RV_CIDNUMBER as the Result Variable to be evaluated :

And when specifying the paths, use the telephone number in the { } section.

eg: If $RV_CIDNUMBER was used, and you want to handle calls from number 5625551234 in a special way, the path to send all the calls from this number to a particular module would be:

on {5625551234} goto [List Administrator Options]

you could also use:

on {} goto [NoCallerId]

or

on {False} goto [NoCallerId]

both of which will match if CallerID number is blank.

on {True} goto [CallerIdWasSent]

will be taken if CallerID was provided but no specified path explicitly matched the number:

Example 2:

The Evaluate Expression module is used to check the PIN entered in previous Get Number module titled "Get PIN".

And the paths in this case are defined as:

What do the paths do:
on {False} goto [Get PIN] | If for some reason no PIN was entered, and $RV[Get PIN] holds no numbers, then goto the Get PIN module
on {1234} goto [Voicemail Box 2032] return [Main Menu] | If the entered PIN was 1234 then go to the Voicemail box number 2032, and then when the caller has finished leaving the message return the caller to the Main Menu module
on {5678} goto [Voicemail Box 8423] return [Main Menu] | If the entered PIN was 5678 then go to the Voicemail box number 8423, and then when the caller has finished leaving the message return the caller to the Main Menu module
on {True} goto [Invalid PIN] | A PIN was entered and $RV[Get PIN] does hold some entered number, but that number does not match exactly any of the paths specified. Go to the Invalid PIN module.

It is a good idea to always specify the TRUE and FALSE paths, since VoiceGuide will hang up the call if it cannot find a valid path to go to the next module.

Example 3:

The Evaluate Expression module can also be used to perform calculations.

Eg: To calculate whether the number of widgets ordered is more then the available amount you can use the following expression:

($RV[LokupStockAvail_1_1]- $RV[GetOrderAmount]) >= 0

A True or a False path will be taken depending on what was the result of the expression.

Example 4:

The Evaluate Expression module can also be used to compare strings. An example of valid expression to evaluate is:

"$RV[DB_Retrieve_1_1]"="Available"

A True or a False path will be taken depending on what was the result of the above expression

Example 5:

If you need to evaluate a Result Variable that holds a string, and select different paths depending on the string’s value then the string will need to be specified using quotes or “CStr()” function:

"$RV[DB_Retrieve_1_1]"

or:

Cstr($RV[DB_Retrieve_1_1])

you will need to use and use the different possible values of this variable when specifying the On ( ‘Paths’ where the script

Example 6:

The “+” or the “&” operator can also be used to concatenate strings together.

eg: The following is a valid expression to use:

["1_" & Cstr($RV_DAY) & "_2"]

The result is going to be(on a Saturday):

1_6_2

Example 7:

If comparing dates the # character should be used around the date expressions.

eg: The following expression determines if current date is between 7th July 2017 and 31 December 2018:

(#7/7/2017# <= #$RV_MONTH/$RV_DATE/$RV_YEAR#) and (#$RV_MONTH/$RV_DATE/$RV_YEAR# <= #31/12/2018#)

Example 8:

To add the value of the number entered in module "GetValue1" to the value of the number entered in module "GetValue2" the following expression would be used:

$RV[GetValue1] + $RV[GetValue2]

The result will be assigned to the result variable name for the module, or can be assigned to a Result Variable specified in the "Assign result to following Result Variable" field.

Example 9:

Evaluate expression can be used as a sophisticated Time-Switch as well. eg. To check if the current day is either New Year's Day or Christmas Day the following expression can be used:

(("$RV_DD" = "01") and ("$RV_MM" = "01")) or (("$RV_DD" = "25") and ("$RV_MM" = "12"))

Example 10:

Evaluate Expression module can be used to implement a counter to check the number of times the caller goes though certain parts of the call flow. This example demonstrates how a counter can be implemented.

A user defined Result Variable is created and its value is set to zero. Note that as the Result Variable was assigned a value of 0, the 'False' path will be taken from this module.

The counter in incremented by retrieving the current value of the user defined Result Variable, adding 1 to this current value, and then saving the result back into the user defined Result Variable.

The value saved by this Evaluate Expression module is then used in the Paths section to determine the next module the script should branch to.

List of functions which can be used:

Any VBScript type expression can be evaluated using the Evaluate Expression module. The full list of functions/operators/constants/keywords etc which can be used can be found at:

http://www.w3schools.com/asp/asp_ref_vbscript_functions.asp

Functions which can be used in the Evaluate Expression module:
Date/Time Functions |
CDate | Converts a valid date and time expression to the variant of subtype Date
Date | Returns the current system date
DateAdd | Returns a date to which a specified time interval has been added
DateDiff | Returns the number of intervals between two dates
DatePart | Returns the specified part of a given date
DateSerial | Returns the date for a specified year, month, and day
DateValue | Returns a date
Day | Returns a number that represents the day of the month (between 1 and 31, inclusive)
FormatDateTime | Returns an expression formatted as a date or time
Hour | Returns a number that represents the hour of the day (between 0 and 23, inclusive)
IsDate | Returns a Boolean value that indicates if the evaluated expression can be converted to a date
Minute | Returns a number that represents the minute of the hour (between 0 and 59, inclusive)
Month | Returns a number that represents the month of the year (between 1 and 12, inclusive)
MonthName | Returns the name of a specified month
Now | Returns the current system date and time
Second | Returns a number that represents the second of the minute (between 0 and 59, inclusive)
Time | Returns the current system time
Timer | Returns the number of seconds since 12:00 AM
TimeSerial | Returns the time for a specific hour, minute, and second
TimeValue | Returns a time
Weekday | Returns a number that represents the day of the week (between 1 and 7, inclusive)
WeekdayName | Returns the weekday name of a specified day of the week
Year | Returns a number that represents the year

Conversion Functions
Asc | Converts the first letter in a string to ANSI code
CBool | Converts an expression to a variant of subtype Boolean
CByte | Converts an expression to a variant of subtype Byte
CCur | Converts an expression to a variant of subtype Currency
CDate | Converts a valid date and time expression to the variant of subtype Date
CDbl | Converts an expression to a variant of subtype Double
Chr | Converts the specified ANSI code to a character
CInt | Converts an expression to a variant of subtype Integer
CLng | Converts an expression to a variant of subtype Long
CSng | Converts an expression to a variant of subtype Single
CStr | Converts an expression to a variant of subtype String
Hex | Returns the hexadecimal value of a specified number
Oct | Returns the octal value of a specified number

Format Functions
FormatCurrency | Returns an expression formatted as a currency value
FormatDateTime | Returns an expression formatted as a date or time
FormatNumber | Returns an expression formatted as a number
FormatPercent | Returns an expression formatted as a percentage

Math Functions
Abs | Returns the absolute value of a specified number
Atn | Returns the arctangent of a specified number
Cos | Returns the cosine of a specified number (angle)
Exp | Returns e raised to a power
Hex | Returns the hexadecimal value of a specified number
Int | Returns the integer part of a specified number
Fix | Returns the integer part of a specified number
Log | Returns the natural logarithm of a specified number
Oct | Returns the octal value of a specified number
Rnd | Returns a random number less than 1 but greater or equal to 0
Sgn | Returns an integer that indicates the sign of a specified number
Sin | Returns the sine of a specified number (angle)
Sqr | Returns the square root of a specified number
Tan | Returns the tangent of a specified number (angle)

Array Functions
Array | Returns a variant containing an array
Filter | Returns a zero-based array that contains a subset of a string array based on a filter criteria
IsArray | Returns a Boolean value that indicates whether a specified variable is an array
Join | Returns a string that consists of a number of substrings in an array
LBound | Returns the smallest subscript for the indicated dimension of an array
Split | Returns a zero-based, one-dimensional array that contains a specified number of substrings
UBound | Returns the largest subscript for the indicated dimension of an array

String Functions
InStr | Returns the position of the first occurrence of one string within another. The search begins at the first character of the string
InStrRev | Returns the position of the first occurrence of one string within another. The search begins at the last character of the string
LCase | Converts a specified string to lowercase
Left | Returns a specified number of characters from the left side of a string
Len | Returns the number of characters in a string
LTrim | Removes spaces on the left side of a string
RTrim | Removes spaces on the right side of a string
Trim | Removes spaces on both the left and the right side of a string
Mid | Returns a specified number of characters from a string
Replace | Replaces a specified part of a string with another string a specified number of times
Right | Returns a specified number of characters from the right side of a string
Space | Returns a string that consists of a specified number of spaces
StrComp | Compares two strings and returns a value that represents the result of the comparison
String | Returns a string that contains a repeating character of a specified length
StrReverse | Reverses a string
UCase | Converts a specified string to uppercase

Other Functions
CreateObject | Creates an object of a specified type
Eval | Evaluates an expression and returns the result
IsEmpty | Returns a Boolean value that indicates whether a specified variable has been initialized or not
IsNull | Returns a Boolean value that indicates whether a specified expression contains no valid data (Null)
IsNumeric | Returns a Boolean value that indicates whether a specified expression can be evaluated as a number
IsObject | Returns a Boolean value that indicates whether the specified expression is an automation object
RGB | Returns a number that represents an RGB color value
Round | Rounds a number
ScriptEngine | Returns the scripting language in use
ScriptEngineBuildVersion | Returns the build version number of the scripting engine in use
ScriptEngineMajorVersion | Returns the major version number of the scripting engine in use
ScriptEngineMinorVersion | Returns the minor version number of the scripting engine in use
TypeName | Returns the subtype of a specified variable
VarType | Returns a value that indicates the subtype of a specified variable

VBScript Keywords
Empty | Used to indicate an uninitialized variable value. A variable value is uninitialized when it is first created and no value is assigned to it, or when a variable value is explicitly set to empty. Example: Dim x 'the variable x is uninitialized! x="ff" 'the variable x is NOT uninitialized anymore x=Empty 'the variable x is uninitialized! Note: This is not the same as Null!!
IsEmpty | Used to test if a variable is uninitialized. Example: If (IsEmpty(x)) 'is x uninitialized?
Nothing | Used to indicate an uninitialized object value, or to disassociate an object variable from an object to release system resources. Example: Set myObject=Nothing
Is Nothing | Used to test if a value is an initialized object. Example: If (myObject Is Nothing) 'is it unset? Note: If you compare a value to Nothing, you will not get the right result! Example: If (myObject = Nothing) 'always false!
Null | Used to indicate that a variable contains no valid data. One way to think of Null is that someone has explicitly set the value to "invalid", unlike Empty where the value is "not set". Note: This is not the same as Empty or Nothing!! Example: x=Null 'x contains no valid data
IsNull | Used to test if a value contains invalid data. Example: if (IsNull(x)) 'is x invalid?
True | Used to indicate a Boolean condition that is correct (True has a value of -1)
False | Used to indicate a Boolean condition that is not correct (False has a value of 0)

Operators which can be used in Evaluate Expression module:
Addition (+) | Sum two numbers.
And | Perform a logical conjunction on two expressions.
Assignment (=) | Assign a value to a variable or property.
Concatenation (&) | Force string concatenation of two expressions.
Division (/) | Divide two numbers and return a floating point result.
Eqv | Perform a logical equivalence on two expressions.
Exponentiation (^) | Raise a number to the power of an exponent.
Imp | Perform a logical implication on two expressions.
Integer Division (\) | Divide two numbers and return an integer result.
Is | Compare to object reference values.
Mod | Divide two numbers and return the remainder.
Muliplication (*) | Multiply two numbers.
Negation (-) | Indicate the negative value of a numeric expression.
Not | Perform logical negation of an expression.
Or | Perform logical disjunction on two expressions.
Xor | Perform a logical exclusion on two expressions.
Subtraction (-) | Find the difference between two numbers.


Fax

VoiceGuide v7 can send and receive faxes. All current Dialogic cards support fax send and receive functionality.

Sending Fax

A Play module can be used to send a fax. Just specify a PDF or TIFF or JPEG file as the file to be "played" by a Play module. The Play module will begin fax transmission immediately if a .tif/.tiff/.pdf/.jpg source file is specified.

Once fax sending is complete the success path will be taken and the script can continue. Please note that the remote end will usually hangup after receiving the fax, so any post fax sending updates etc. should be performed in the "After Hangup" script.

Its simplest if TIFF files are used for the outgoing fax. The TIFF file must be in "Fax Group 3" format and have a horizontal resolution of 1728 pixels across the page. Vertical pixel count will depends on length of fax page, but a standard page is 2200 pixels long. The DPI resolution of the TIFF file should be 200. Some sample TIFF files are provided in the directories of the sample VoiceGuide scripts that perform fax sending.

Any PDF file can be used as input as well. If faxing PDF files you must aggregate Ghostscript with VoiceGuide by placing Ghostscript's gswin32c.exe and gsdll32.dll file into VoiceGuide's \gs\ subdirectory. Ghostscript can be downloaded from http://www.ghostscript.com

Receiving Fax

A Record module can be used to receive a fax. To make the Record module receive a fax just specify the filename to end in .pdf suffix or end in .tif suffix. The Record module will begin fax reception immediately if a .pdf target file or a .tif target file is specified.

The received fax is automatically saved both in in the PDF and in the TIFF file formats.

After receiving the fax VoiceGuide will create a PDF version of the received fax, and will also perform OCR on the fax and scan the fax for any barcodes. The OCR text and text from decoded barcodes is then stored as Result Variables. During OCR VoiceGuide will also try to identify the "To:" and "From:" fields and make the text that follows them available through Result Variables as well. VoiceGuide will also save the fax header line as a separate Result Variable.

The following Result Variables are created when a fax is received:

$RV[ModuleTitle_fax] | Filename of the sent or received fax.
$RV[ModuleTitle_fax_pdf] | Filename of the PDF file create after TIF->PDF conversion.
$RV[ModuleTitle_fax_tif] | Filename of the TIF file used as a source for PDF conversion.
$RV[ModuleTitle_ocr] | Full OCR of the received fax.
$RV[ModuleTitle_ocr_header] | Fax Header line which usually contains the Date/Time, CSID (Call Subscriber ID), fax number, and page number.
$RV[ModuleTitle_ocr_to_1] | First word after the "To:"
$RV[ModuleTitle_ocr_to_2] | First two words after the "To:"
$RV[ModuleTitle_ocr_from_1] | First word after the "From:"
$RV[ModuleTitle_ocr_from_2] | First two words after the "From:"
$RV[ModuleTitle_barcode_1] | Contents of the first barcode encountered on the fax page.
$RV[ModuleTitle_barcode_2] | Contents of the second barcode encountered on the fax page.
$RV[ModuleTitle_barcode_count] | Number of barcodes found on the fax.
$RV[ModuleTitle_barcode_all] | Contents of all the barcodes encountered on the fax page, delimited by "|".

To have VoiceGuide save the PDF filed in 'searchable PDF' format please contact sales@voiceguide.com

To install the barcode recognition add-on please contact sales@voiceguide.com

Fax Routing

The OCR and barcode decoding allow advanced automated fax routing to be done, automatically forwarding the received document by:

  • Email
  • Printing to selected printer
  • Ftp
  • Re-faxing to another number (optionally with additional pages added to original fax)
  • any other processing called from command line or VBScript

Note that as the call is usually ended immediately after the fax is received, the fax routing should be done from the "After Hangup" script. The "After Hangup" script can look at the OCR $RVs as well as the $RVs containing the CallerID or the DNIS (number dialed by caller) and decide how to forward the fax, and then perform the email or printing or loading of a new outbound call etc. This allows fax routing to be done based on any combination of:

  • CallerID
  • DNIS
  • CSID (Call Subscriber ID) of the machine sending the fax
  • To: or From: fields in the received fax
  • Any other text in the received fax
  • Barcodes in the received fax
  • Time/Day etc


Make Outbound Call Module

This module will make an outgoing call on another line to the phone number specified, and run the specified script or sound file when the call is answered.<

Note: More advanced call scheduling features can be accessed by loading the calls using the Dialer's 'Out Dial' XML file method, WCF/COM/REST interfaces, or inserting call data directly into the VoiceGuide database.

The Dialer option must be enabled to allow VoiceGuide to perform any outbound dialing.

You can specify the telephone number to call, the welcome message to play when the call has been made, the VoiceGuide script to run once the call has been accepted, and custom Result Variables which can be used by the called script.

Result Variables can be used when specifying any of the entries in this module. <>

Phone

The phone number to dial.

Welcome

Optional. Prompt played to caller caller to accept the call. The welcome message asks the called person whether they want to accept the call or not. The called person should press '1' on their telephone keypad to indicate that they want to accept the call. Hence any welcome message should advise to 'Press 1' to accept the call'.

If the welcome message is not specified then the default VoiceGuide welcome message will be played. If welcome message is set to 'none' then no welcome message will be played and VoiceGuide will go directly to running the script.

Script

Which script will be ran once the call is accepted, or the sound file to be played.

Variables

Result Variables which can be accessed by the called script. Use these to pass any information (eg. callers contact details) to the script which will be used when the outbound call is made. The format of this field is [RvName]{RvValue}. Multiple Result variables can be specified by listing the name-value pairs as needed.

In the properties page screen capture above we see that the caller's problem reference number is being passed to the FirstLevelEscalation.vgs script. The reference number would have been generated previously in module CallerRef, and $RV[CallerRef] will be replaced with the actual reference number when the call is queued. The reference number can then be accessed using $RV[CallerRefNumber] in the FirstLevelEscalation.vgs script.

Lines Used

If the outbound call may only be made on particular phone lines then these lines should be listed here. Lines should be specified as a comma delimited list of "LineIDs" (eg: 6,7,8) or of the Dialogic line identifiers (eg: dxxxB1C2,dxxxB1C3). If any of the lines are allowed to to be used then this setting should be left blank.

Retries

The number times the number will be redialed before abandoning attempts to contact the number. For example, if the number of retries is set to 2, with 5 minutes between redials then the phone number will be called 3 times in total (1 call + 2 redials).

Escalation Dialing

In case VoiceGuide is unable to contact anybody at the first phone number supplied, alternative phone numbers and scripts can be specified. This is useful if:

  • A person you want to contact can be under different numbers.
  • Problem escalation situations, where if one person is unavailable then further people will be called until one of the people on the list answers the call.

Alternative Contact and Second Alternative Contact tabs are used to specify alternative contact numbers. Once the number of retries for one number is exhausted, the next alternative number will be dialed.

Notes:

For instructions on how to set your own escalation dialing without using the Make Call module, see the VoiceGuide Dialer section of this help file.

Paths

The 'Success' path is taken if the call was scheduled. If for any reason the call could not be scheduled, the 'Fail' path will be taken

Scheduling Calls

The Send Phone Message module schedules the call to be made immediately. If you need to schedule a call to be made at a later time VoiceGuide's COM function Dialer_OutDialQueAdd needs to be used. This function can be called from within a Run VB Script module.

The future date/time needs to be specified in format "YMMDDHHNN" in Dialer_OutDialQueAdd's lActivateTime parameter.

eg. To specify a date/time exactly 3 days in future you can use the following VB Script snippet:

dDate = DateAdd("d", 3, Now)
sYear = Right(Year(dDate), 1)
sCallTime = sYear * 100000000 + Month(dDate) * 1000000 + Day(dDate) * 10000 + Hour(dDate) * 100 + Minute(dDate)

and then you use sCallTime when calling Dialer_OutDialQueAdd

You can hard code the hour and minute settings if you want the call to be made at a certain time. eg to call at 10:30am the sCallTime formula would become:

sCallTime = sYear * 100000000 + Month(dDate) * 1000000 + Day(dDate) * 10000 + 1030


Send Pager Message Module

This module will queue a pager message to be sent.

Dialer option must be enabled to allow VoiceGuide to perform any outbound dialing and pager message delivery.

The pager message will be sent as soon as VoiceGuide has a line available to make a call on. When sending the message VoiceGuide will dial the Telephone number specified, and then will start dialing the digits specified in the Message text box.

VoiceGuide will pause for a couple of seconds after dialing the telephone number and before dialing the message. If this pause is not long enough, extra wait time can be specified by tying commas at the beginning of the message. The example in the captured screen above has two commas.

The length of a pause generated by each comma differs from system to system and its best to determine by trial and error the number of commas to use in order to have reliable pager message delivery from your VoiceGuide system to your pager provider.

Also in the example above a Result Variable was used in the message. This shows how data entered by the caller in one part of the script can be sent as part of a pager message.

Lines Used

If the outbound call may only be made on particular phone lines then these lines should be listed here. Lines should be specified as a comma delimited list of "LineIDs" (eg: 6,7,8) or of the Dialogic line identifiers (eg: dxxxB1C2,dxxxB1C3). If any of the lines are allowed to to be used then this setting should be left blank.

Paths

The 'Success' path is taken if the call to the pager was scheduled. If for any reason the call could not be scheduled, the 'Fail' path will be taken.


Hangup the Call

Hangs up the current call.

On ISDN systems the 'Cause Value' which is sent at the time of call disconnection can be specified by setting the $RV[DropCall_CauseValue]

Evaluate Expression module can be used to assign a cause value to $RV[DropCall_CauseValue] :

Possible cause values are:
Cause Value Tag
Cause Value Sent
UNASSIGNED_NUMBER | hex: 01 - Cause 01
NO_ROUTE | hex: 02 - Cause 02
NO_ROUTE_TO_DEST | hex: 03 - Cause 03
SEND_SPECIAL_ITONE | hex: 04 - Cause 04
MISDIALLED_TRUNK_PFX | hex: 05 - Cause 05
CHANNEL_UNACCEPTABLE | hex: 06 - Cause 06
CALL_AWARDED_IN_EST_CHAN | hex: 07 - Cause 07
PREEMPTION | hex: 08 - Cause 08
PREEMPTION_CHAN_RESERVED | hex: 09 - Cause 09
QOR_PORTED_NUMBER | hex: 0E - Cause 14
NORMAL_CLEARING | hex: 10 - Cause 16
USER_BUSY | hex: 11 - Cause 17
NO_USER_RESPONDING | hex: 12 - Cause 18
NO_ANSWER_FROM_USER | hex: 13 - Cause 19
SUBSCRIBER_ABSENT | hex: 14 - Cause 20
CALL_REJECTED | hex: 15 - Cause 21
NUMBER_CHANGED | hex: 16 - Cause 22
REDIR_NEW_DESTINATION | hex: 17 - Cause 23
REJECTED_FEATURE_DEST | hex: 18 - Cause 24
EXCHANGE_ROUTING_ERR | hex: 19 - Cause 25
NON_SELECTED_USR_CLEAR | hex: 1A - Cause 26
DEST_OUT_OF_ORDER | hex: 1B - Cause 27
INVALID_NUMBER_FORMAT | hex: 1C - Cause 28
FACILITY_REJECTED | hex: 1D - Cause 29
RESP_TO_STAT_ENQ | hex: 1E - Cause 30
UNSPECIFIED_CAUSE | hex: 1F - Cause 31
NO_CIRCUIT_AVAILABLE | hex: 22 - Cause 34
NETWORK_OUT_OF_ORDER | hex: 26 - Cause 38
PFM_CONN_OUT_OF_SERVICE | hex: 27 - Cause 39
PFM_CONN_OPERATIONAL | hex: 28 - Cause 40
TEMPORARY_FAILURE | hex: 29 - Cause 41
NETWORK_CONGESTION | hex: 2A - Cause 42
ACCESS_INFO_DISCARDED | hex: 2B - Cause 43
REQ_CHANNEL_NOT_AVAIL | hex: 2C - Cause 44
PRE_EMPTED | hex: 2D - Cause 45
CALL_BLOCKED | hex: 2E - Cause 46
RESOURCE_UNAVAILABLE | hex: 2F - Cause 47
QOS_UNAVAILABLE | hex: 31 - Cause 49
FACILITY_NOT_SUBSCRIBED | hex: 32 - Cause 50
BEARER_INCOMPAT_SERVICE | hex: 33 - Cause 51
OUTGOING_CALL_BARRED | hex: 34 - Cause 52
OUTGOING_BARRED_IN_CUG | hex: 37 - Cause 53
INCOMING_CALL_BARRED | hex: 36 - Cause 54
INCOMING_BARRED_IN_CUG | hex: 37 - Cause 55
BEAR_CAP_NOT_AUTHL | hex: 39 - Cause 57
BEAR_CAP_NOT_AVAIL | hex: 3A - Cause 58
INCONSISTANT_OUTB_INFO | hex: 3E - Cause 62
SERVICE_NOT_AVAIL | hex: 3F - Cause 63
CAP_NOT_IMPLEMENTED | hex: 41 - Cause 65
CHAN_NOT_IMPLEMENTED | hex: 42 - Cause 66
FACILITY_NOT_IMPLEMENT | hex: 45 - Cause 69
RESTRICTED_DIG_INFO_ONLY | hex: 46 - Cause 70
SERVICE_NOT_IMPLEMENTED | hex: 4F - Cause 79
INVALID_CALL_REF | hex: 51 - Cause 81
CHAN_DOES_NOT_EXIST | hex: 52 - Cause 82
BAD_CALL_ID_FOR_SUS_CALL | hex: 53 - Cause 83
CALL_ID_NOT_IN_USE | hex: 54 - Cause 84
NO_SUSPENDED_CALL | hex: 55 - Cause 85
CALL_ID_CLEARED | hex: 56 - Cause 86
NOT_MEMBER_OF_CUG | hex: 57 - Cause 87
INCOMPATIBLE_DEST | hex: 58 - Cause 88
NONEXISTENT_CUG | hex: 5A - Cause 90
INVALID_TRANS_NETWORK | hex: 5B - Cause 91
INVALID_MSG_UNSPEC | hex: 5F - Cause 95
MANDATORY_IE_MISSING | hex: 60 - Cause 96
NONEXISTENT_MSG | hex: 61 - Cause 97
WRONG_MESSAGE | hex: 62 - Cause 98
BAD_INFO_ELEM | hex: 63 - Cause 99
INVALID_ELEM_CONTENTS | hex: 64 - Cause 100
WRONG_MSG_FOR_STATE | hex: 65 - Cause 101
TIMER_EXPIRY | hex: 66 - Cause 102
MANDATORY_IE_LEN_ERR | hex: 67 - Cause 103
MSG_W_UNRECOGNIZED_PARAM | hex: 6E - Cause 110
PROTOCOL_ERROR | hex: 6F - Cause 111
INTERWORKING_UNSPEC | hex: 7F - Cause 127

Alternatively, the decimal value itself can be assigned to the $RV[DropCall_CauseValue]

eg: Assigning 54 to $RV[DropCall_CauseValue] would have the same effect as assigning INCOMING_CALL_BARRED to $RV[DropCall_CauseValue]

This allows for other custom codes, which do not have a predefined tag, to be sent.

Definition of the various standard cause codes can be found in the ITU-T's Q.850 recommendation: http://www.itu.int/rec/T-REC-Q.850/en

ITU-T's Q.931 (ISDN) recommendation itself can be found at: http://www.itu.int/rec/T-REC-Q.931-199805-I/en


Reporting : Dashboards

Pre-configured VoiceGuide IVR and ACD dashboards can be accessed at these locations:

http://localhost:7140/dash/ivr.html

http://localhost:7140/dash/dialer.html

http://localhost:7140/status/port-grid.html

http://localhost:7140/dash/acd-agent-list.html

http://localhost:7140/dash/acd-agent-grid.html

http://localhost:7140/dash/acd-agent-list-2.html

"localhost" would need to be replaced with VoiceGuide system's IP address if dashboard is viewed remotely.

The dashboards are user configurable and retrieve system data from VoiceGuide through VoiceGuide's REST API.

Creation of new custom Dashboards is also supported. New dashboards can be added to the system by creating a new dashboard definition file and placing it in VoiceGuide's \system\web\dash\ subdirectory. The newly created dashboard can then be accessed using:

http://localhost:7140/dash/my-new-dashboard.html


Reporting : REST API

VoiceGuide's REST API can be used to retrieve current and historical data for IVR and ACD systems.
Generation of PDF reports is also supported through the REST API.

VoiceGuide's REST API can be accessed at this location:

http://localhost:7131/v1/

"localhost" is replaced with system's IP address if REST API is accessed remotely.

REST API for IVR data:

http://localhost:7131/v1/ivr/ports
http://localhost:7131/v1/ivr/ports/{id}

http://localhost:7131/v1/ivr/calls
http://localhost:7131/v1/ivr/calls/group/live
http://localhost:7131/v1/ivr/calls/group/historical
http://localhost:7131/v1/ivr/calls/[in|out]
http://localhost:7131/v1/ivr/calls/[in|out]/[count|labels|detail]

REST API for Dialer data:

http://localhost:7131/v1/dialer
http://localhost:7131/v1/dialer/labels
http://localhost:7131/v1/dialer/detail
http://localhost:7131/v1/dialer/pdf
http://localhost:7131/v1/dialer/campaigns
http://localhost:7131/v1/dialer/campaigns/{id}
http://localhost:7131/v1/dialer/state

REST API for ACD data:

http://localhost:7131/v1/acd/queues
http://localhost:7131/v1/acd/queues/{id}
http://localhost:7131/v1/acd/agents
http://localhost:7131/v1/acd/agents/{id}

WSDL endpoints for API and other services:

http://localhost:7131/v1?wsdl
http://localhost:7131/LineCommandLink?wsdl
http://localhost:7131/PortCommandLink?wsdl
http://localhost:7131/PortStatus?wsdl
http://localhost:7131/AcdService?wsdl


Reporting : Line Status Monitor

VoiceGuide Line Status Monitor is a Windows application that shows real-time status of each port.


Reporting : Scheduling Automated Generation of IVR and ACD Reports

VoiceGuide allows for automated scheduling of creation of PDF reports and forwarding of them to specified email list.

Automated reporting is configured in Config.xml file, located in VoiceGuide's /conf/ subdirectory.


Voicemail Introduction

VoiceGuide has a built in a fully-featured voicemail system, and can support an unlimited number of voicemail boxes.

Voicemail Features:

  • Auto-attendant system allowing spelling of user's names and diverting to voicemail if extension is not answered.
  • Each mailbox can have a personalized greeting message, which can be changed remotely.
  • Each mailbox can have a personalized name/description, which can be changed remotely.,
  • Voicemail messages can be retrieved remotely.
  • Messages can be forwarded to other voicemail boxes and/or broadcast groups automatically, or as specified by listener of message.
  • Messages can be be forwarded to an email address automatically as an attached Wave file.
  • Messages can be be forwarded to another phone number automatically. The forwarding telephone number can be changed remotely by the voicemail box owner.
  • Messages can be uploaded by FTP to selected FTP server.
  • Voicemail box owners can change their PIN number remotely.
  • Broadcast Groups, allowing the sending of broadcast messages to selected groups of people.
  • Message Lamp for the extension associated with the mailbox is turned ON when new messages arrive and OFF when messages are listened to.
  • All Voicemail system details stored in XML format, allowing easy integration with other systems.

Voicemail boxes have to first be created before they can be used. The Voicemail Manager tool is used to create and manage the voicemail boxes.

The voicemail boxes and menus can be accessed from any module. Paths can be specified to go to:

  1. A particular voicemail box,
  2. Menu which will ask the caller to enter the Voicemail box for which they want to leave a message,
  3. Retrieve Menu where the caller will be asked their voicemail box number and voicemail PIN before being able to retrieve messages.
  4. Auto Attendant which allows callers to spell the name of the voicemail box owner, and will then transfer the call to related extension (if defined), and if extension does not answer will divert call to related voicemail box.

An example below shows how the paths can be defined:

You can indicate to which module in the script the caller is to return to after leaving the voicemail system by appending Return [module title] after the path specification. The Return option will need to be typed in by hand. eg:

Once the caller has finished recording and/or retrieving messages and presses ' 0' to exit from the voicemail system, the script will then go to the module specified in the Return option. See here for more information on the Return option.

Modifying the Voicemail System

The Voicemail system is written as a set of VoiceGuide scripts located in VoiceGuide's \system\vm\ directory. These scripts can be edited giving the user full control and freedom over any modifications and extensions which may be required of the voicemail system.

Only the Enterprise (and Evaluation) versions of VoiceGuide use the modifiable scripted version of the voicemail - ie: the .vgs scripts in the \system\vm\ directory.

The Standard and Professional versions of VoiceGuide use the non-modifiable version of the voicemail system.


Voicemail Manager

Using the Voicemail Manager you can browse through the voicemail boxes, and change any of their settings:

  • create/remove voicemail boxes,
  • play/delete/record messages left in individual voicemail boxes,
  • play/delete/record the greeting messages for individual voicemail boxes.
  • edit the forwarding email address for new voicemail messages
  • edit the forwarding phone number for new voicemail messages
  • edit the pager telephone number
  • edit the message distribution lists.

To add a new voicemail box select the 'Add/Modify' tab, and fill out the mailbox details and forwarding information.

Field | Description

Number

Voicemail box numbers (VMB IDs) can be up to 6 digits long, allowing up to 1,000,000 voicemail boxes on the system. In most applications 4 digit digit voicemail ID's are used, allowing up to 10,000 mailboxes.

PIN

Voicemail box access PIN number length is set to 4 digits. If no PIN is specified the caller will be asked to specify the PIN the first time they log into the voicemail box.

Name

Name of the voicemail box owner. This is the name which can be spelled by caller when using the Auto Attendant's 'spell name' feature.

Ext

Extension number associated with this voicemail box. This is the extension number to which caller will be transferred when using the Auto Attendant's 'spell name' feature.

Comments

Administrator's Comments.

Groups

Voicemail groups to which this mailbox belongs to. Voicemail groups are used when sending broadcast messages, and when browsing voicemail boxes' welcoming messages.

Forward tel

Any new messages will be forwarded to the phone number specified.

VG Dialer option must be enabled to allow VoiceGuide to dial out and deliver any new voicemail messages.

Email

If a forwarding Email address is specified, all recorded messages for this mailbox will be sent by Email to the address specified. If the message needs to be sent to multiple email addresses the individual addresses must be separated by semicolons "

Copy To | What other Voicemail boxes any messages left in this voicemail box should be copied to. The list can include individual voicemail boxes or Distribution Lists.

Pager tel

The telephone number dialed to deliver a numeric pager message.

VG Dialer option must be enabled to allow VoiceGuide to dial out and deliver any new voicemail messages.

Pager msg

The message sent to the pager. VoiceGuide will pause for a couple of seconds after dialing the telephone number and before dialing the message. If this pause is not long enough, extra wait time can be specified by tying commas at the beginning of the message. The example in the captured screen above has three commas.

The length of a pause generated by each comma differs from system to system and its best to determine by trial and error the number of commas to use in order to have reliable pager message delivery from your VoiceGuide system to your pager provider.

Also in the example above a Result Variable was used in the message. This shows how the caller's ID or any other data entered by the caller in another part of the script can be sent as part of a pager message.

Email

If a forwarding Email address is specified, all recorded messages for this mailbox will be sent by Email to the address specified. If the message needs to be sent to multiple email addresses the individual addresses must be separated by semicolons "

Run | What program to run after a message has been left for this voicemail box. This can be used to start 3rd party command line utilities to forward alerts to alphanumeric pagers, or to mobile phones via SMS. Another possible use is for post-processing of recorded message or forwarding of the recorded message through other means. (The filename of the just recorded message can be accessed using the $RV[VoicemailMesasgeXXXX] Result Variable - it returns the filename of the last recorded voicemail message in a particular voicemail box - which is specified by replacing XXXX with the number of the voicemail box.)

Distribution Lists

Messages recorded in the voicemail system can be sent to individual voicemail boxes or Distribution Lists. Distribution Lists are by default global and available for use to anyone. This screenshot shows how the Distribution Lists are defined:

Voicemail configuration file

The voicemail information is stored in file VmBoxList.xmlin the Data subdirectory.

The Voicemailbox data is stored in an XML format, allowing easy viewing and manipulation of this data by users own tools.

Any changes made to the Voicemail configuration file by the Voicemail Manager or by any other program will also be loaded by VoiceGuide immediately after the new version of the file is saved. This allows for outside programs to add and delete voicemail boxes at will.

Email Forwarding

The Voicemail Manager allows you to define the standard template for the Subject and Body of the emails sent with forwarded recorded messages.

The Email's Subject and Body can also be customized on a per voicemail box basis by creating these test files in VG's \system\vm\ subdirectory:

\system\vm\EmailForwardTemplate_XXXX_subject.txt
\system\vm\EmailForwardTemplate_XXXX_body.txt

Where XXXX is to be replaced by the voicemail box number.

If the Voicemail-box specific files subject or body can be found then the following files will be used if they exist:

\system\vm\EmailForwardTemplate_subject.txt
\system\vm\EmailForwardTemplate_body.txt

RV's can be used within these template files as well.

The voicemail scripts can also be modified to append information to the message body - please examine the voicemail scripts to see how this is done.

Note

Voicemail Manager reads the contents of the VmBoxList.xmlfile on start, and saves all the information on exit - overwriting the previous VmBoxList.xml. This means that any changes made to VmBoxList.xmlby voicemail users managing their accounts (changing PINs or Forwarding numbers) by any other programs while the Voicemail Manager is open will be lost.

Hence it is recommended that Voicemail Manager only be used only at times when no callers are performing administration functions on their Voicemail account.

The voicemail introduction messages are stored by default in VG's \data\VmWelc\ subdirectory.
The messages left in voicemail boxes are stored by default in VG's \data\VmSave\ subdirectory.


Voicemail Menus

This is a summary of what keys can be used in the various voicemail menus. A .PDF file (VoicemailMenus.pdf) showing the menus in a graphical format is also supplied in VoiceGuide's directory.

Greeting Message Menu

While listening to the greeting message the following keys can be used:
Stop playing the greeting message, and start recording a message
Group browse to the previous voicemail box and play it's greeting message
Replay the greeting message for this voicemail box
Group browse to the next voicemail box and play it's greeting message
Go to Voicemail Login Menu
Exit the voicemail system
Stop recording and play the menu which speaks the options listed above

Leave Message Menu

This is a menu used when recording a message to be left as voicemail, or editing that recorded message. To access this menu the keys [image] or [image] must be pressed after the message has been recorded.
Stop recording and play the recorded message
Delete the recorded message and start recording again
Save the recorded message and play the greeting message for this voicemail box again
Delete the recorded message and group browse to the previous voicemail box and play it's greeting message
Delete the recorded message and play the greeting message for this voicemail box again
Delete the recorded message and group browse to the next voicemail box and play it's greeting message
Save the recorded message and go to Voicemail Login Menu
Save the recorded message and exit the voicemail system
Stop recording and play the menu which speaks the options listed above

Voicemail Login

When logging into the voicemail box, a prompt will be played asking for the voicemail ID, and then for the PIN number to be entered. If the two have been entered correctly then the Voicemail Box Main Menu will be played.

Voicemail Box Main Menu

After entering the voicemail box ID and PIN, the following keys can be used:
Listen to new voicemail messages
Listen to saved voicemail messages
Administer the greeting message
Change voicemail box PIN
Change the forwarding telephone number
Record a message and send it to other voicemail boxes
Administer voicemail box name
Exit and go to Login Menu
Exit the voicemail system
Play the message counts

Retrieve Messages Menu

When listening to new or saved messages, the following keys can be used:
Replay the current message
Save the current message and play the next message
Delete the current message and play the next message
Play the previous message.
Replay the current message
Play the next message.
Play the date and time when the message was recorded, and the Caller ID of who left the message.
Exit and go to Login Menu
Forward current message to other voicemail boxes
Return to Voicemail Access Menu

Administer Greeting Message Menu

When recording voicemail box's greeting message the following keys can be used:
Replay the current greeting message
Delete the current greeting message and record a new greeting message
Save the current greeting message and return to Voicemail Access Menu
Delete the current greeting message and return to Voicemail Access Menu

Administer Mailbox Name/Description Menu

When recording voicemail box's name/description the following keys can be used:
Replay the current greeting name
Delete the current name and record a new name
Save the current name and return to Voicemail Access Menu
Delete the current name and return to Voicemail Access Menu

Record Message Menu

When recording a message to be sent to other voicemail boxes or distribution lists.
Stop recording and play the recorded message
Delete the recorded message and start recording again
Save the recorded message and start entering the recipients of the voicemail message. These can be individual voicemail boxes or distribution lists. Please see the "Select Message Recipients Menu" on how the recipients of the message are specified.
Delete the recorded message and return to the Voicemail box Administration Menu
Save the recorded message and exit the voicemail system
Stop recording and play the menu which speaks the options listed above

Select Message Recipients Menu

This menu allows the caller to select further recipients of the message just recorded. Once in this menu the caller must enter the voicemail group numbers or the voicemail box numbers.

After entering each group number or voicemail box number the caller must enter the "#" key. After the last destination is entered the caller must press the "#" key twice, and they will be returned to the Voicemail box Administration Menu.

Changing the keys used

The Voicemail system is written as a set of VoiceGuide scripts located in VoiceGuide's \system\vm\ directory. These scripts can be edited giving the user full control to make any modifications and extensions which may be required. This includes changing of the keys used to access various voicemail system commands and features.

Only the Enterprise (and Evaluation) versions of VoiceGuide use the modifiable scripted version of the voicemail - ie: the .vgs scripts in the \system\vm\ directory.

The Standard and Professional versions of VoiceGuide use the non-modifiable version of the voicemail system.


Voicemail Message Lamps

VoiceGuide can instruct the PBX to turn on the telephone extension's 'message lamp' when a new voicemail message has arrived, and to turn off the 'message lamp' once the message has been heard.

In VoiceGuide Script Editor got to the Edit menu and select go PBX Command Strings option, then click on the Message Lamps tab. The following should be displayed:

The top section is used to select when the signals to the PBX to turn the message lamps on/off should be sent.

The "Dial Strings" section is used to define what are the DTMF signals which VoiceGuide needs to send to the PBX to turn the message lamps on/off.

In the example shown in the above screenshot VoiceGuide has been configured to send DTMF tones *4,Ext (where Ext is the Extension number) when the first new voicemail message arrives and *5,Ext when the voicemail box owner has saved or deleted all of the 'New' voicemail messages.

The sending of the DTMF tones is done by VoiceGuide picking up one of the lines and dialing the DTMF tones specified. Eg. if in the above example the extension number was 1234 then to turn the lamp ON VoiceGuide would pick up a line and dial *4,1234 (with the comma indicating a short pause). It is possible to limit on what lines VG is allowed to send these lamp on/off messages. The lines on which the sending of message lamp messages is allowed can be specified by just typing in the Line IDs separated by commas. If the line selection text box is left blank then any of the currently available lines will be used.

The Message Lamp feature is only enabled in the 'Evaluation' and 'Enterprise+Dialer' versions of VoiceGuide.


Outbound IVR

VoiceGuide can dial out and play messages or run a VoiceGuide IVR script once the call has been answered.
Outgoing calls can be scheduled using any of these methods:

  • Call Loader app
  • Send Phone Message module in a VoiceGuide script.
  • Using VoiceGuide WCF/COM interface function Dialer_OutDialQueAdd.
  • Saving list of numbers to be called in an Out Dial File, which VoiceGuide reads in automatically.
  • Adding dial entries directly into the VoiceGuide OutDial Database.

VoiceGuide can detect whether a real person or an answering machine has answered the call.
Different messages or scripts can be specified in either case.
When an answering machine answers the call the message or script will start after the welcoming message stops playing.

Call Loader

Here is a screenshot of the Call Loader application, with some telephone numbers to call entered:

Phone numbers
The telephone numbers to be dialed can be typed directly into this text box. The numbers should be entered one per line. eg:

2125551111
2125552222
2125553333

A range of numbers can be specified by using "X" in the number to be dialed.
eg: 4155557XXX results in one thousand telephone numbers to be called: 415-555-7000 to 415-555-7999

Optionally, additional information like Name and other Data can be attached to each phone number, using the pipe: '|' or "Tab" characters to separate the fields. Like this:

Number|Name|Data1|Data2

Number Name Data1 Data2

eg:

2125551234|Bob Brown

2125551234|Bob Brown|6549148|Reminder1

The data attached to each number is accessible within the ran scripts using $RV_CALLTRACK_* Result Variables.
Other information can also be attached to outgoing calls batch/campaign by setting the 'Result Variables' for those calls. See the 'Scripts' tab, 'Script Data' section.

Phone Numbers File
Allows to select the text file from which to import the list of numbers to call. The file should contain each number on its own new line.
The "X" notation is still supported when loading numbers from a file. eg: entry 21255588XX would result in one hundred numbers being called: 212-555-8800 to 212-555-8899

Live Person Answer
VoiceGuide script to be started or sound file top be played when the call is answered by a real person.
Specifying the starting module can be made using notation: Script Filename|Module Title

Answering Machine Answer
When the call is answered by an answering machine or voicemail system, VoiceGuide will play this message/script.

If an answering machine is detected VoiceGuide will wait until the answering machine's welcome message finishes before starting the script/sound file specified here.

If the "Answering Machine" message option is not set then VoiceGuide will play the "Live person answer" script in cases where answering amchine is detected.

The "Answering Machine" option can also be set to:
RETRY | VoiceGuide will hangup if an answering machine is encountered. Call will be attempted again later - up to the maximum number of redials allowed.
IGNORE | The script/file specified when the live person answers will be used.
DISABLE | Answering Machine detection is disabled. VoiceGuide will start the "Live Person Answer" script immediately when call is picked up.

If T1/E1 ISDN or VoIP is used, the telephone company usually also advises immediately when the call is connected, ie: when the 'handset is picked up', before the person or machine answering call even trasnmits any sound on the line.

So on T1/E1 ISDN and VoIP systems if the "Answering Machine" message option is not set (or set to 'DISABLE') then VoiceGuide will play the "Live person answer" script immediately when then handset is picked up.

Answering Machine detection relies on listening to the first one or two words spoken by the person/device answering the call.
Decision is based on whether the first one or two words sounded like they were spoken by a live person, or by an answering machine.
This means that VoiceGuide waits until it hears the first one or two words being spoken before it can decide whether a live person or a machine answered the call.

Call Options
The Options field can be used for other special settings. Eg. to specify the outgoing CallerID used for the call. Including this setting: <CallerId>5551234</CallerId> would result in CallerId to be set to 5551234 on outgoing calls (lines used must support the setting of outgoing CallerID).

NOTE: Some SIP services require that the CallerID be set to the account number, to let their systems identify what account is making the outgoing call.
eg: <CallerId>9905234421234323@sip.skype.com</CallerId>

Fax to Send
If a fax is specified then VoiceGuide will send the specified fax on this call. This can be a .PDF or a .TIFF file. Note that when this field is specified VoiceGuide will start playing the Fax Calling Tone immediately after the number is dialed and only a fax send will be attempted during the call.
Do Not Call List (DNC List)
File containing a list of telephone numbers which will never be called by VoiceGuide, even if they were inadvertently specified in the "Phone numbers to be called" file or text box. The file must contain each number on a separate line.

Result Variables
Result Variables can be attached to the call, and can then be used by the scripts which run when outgoing call is answered.
The format of this field is [RvName]{RvValue}. Multiple Result Variables can be specified by listing as many name-value pairs as needed. eg: [rv1]{val1}[rv2]{val2}[rv3]{val3}
This allows any custom information/settings to be linked to, and used by, the outgoing calls.

Others
There are many other options that can be set using the Call Loader app:
Time Scheduling, Port Selection, Priority Level, actions to take when NotAnswered or RetriesExhausted events occur, Call Headers and CallerID etc.
Call Escalations
Escalation calls need to be set using the Out Dial File method

Result Files

In addition to CDR Logs, Database Logs and Script Logs, outcome of all outgoing calls is saved in VoiceGuide's \data\ subdirectory.

OutDial_Contacted_Human.txt
List of calls answered by a real person.

OutDial_Contacted_AM.txt
List of calls answered by an answering machine.

OutDial_Contacted_Fax.txt
List of calls answered by a fax machine person.

OutDial_Uncontactable_NoAnswer.txt
List of calls which were not answered and rung out awaiting answer.

OutDial_Uncontactable_Busy.txt
List of calls which were not answered as the busy tone was heard.

OutDial_Uncontactable_OnDontDialList.txt
List of calls which were not made as the telephone number was on the supplied "Do Not Call list".

OutDial_Uncontactable_NoDialer.txt
List of calls which were not dialed as the Dialer option is not enabled.

OutDial_SIT_Reorder.txt
List of calls for which the Special Information Tone (Reorder) was played by the phone company.

OutDial_SIT_NoCircuit.txt
List of calls for which the Special Information Tone (No Circuit) was played by the phone company.

OutDial_SIT_CustIrReg.txt
List of calls for which the Special Information Tone (CustIrReg) was played by the phone company.

OutDial_SIT_Unknown.txt
List of calls for which an unknown Special Information Tone was played by the phone company.

Out Dial File

An 'OutDial' file can also be used to load the outbound calls to be made by VoiceGuide. When the file is created, VoiceGuide will read in the file and delete it after reading it's contents.

‘OutDial’ file can be created in VoiceGuide's \data\ subdirectory, or in directory specified in VG.INI, section [VGDialer], entry: OutDialFilePath

The filename must begin with "OutDial" and have the ".xml" suffix.
Eg: OutDial_080521175323a.xml

Multiple 'OutDial' files can be created at the same time, and will be read in by VoiceGuide within about a second of them being created. All outdial files created within less then a few seconds of each other should have unique names - to avoid the possibility of a file being overwritten by newer version while it is still being read in by VoiceGuide.

It is advisable to first create the file under a different name - that does not have the 'OutDial' prefix in its filename, and after the file writing/copying is completed then rename the file to the OutDial*.xml format. This would ensure that VoiceGuide would not attempt to open the file while it's contents are still being written to by another process.

Out Dial File Syntax
The syntax of the OutDial file as used by VoiceGuide v7 is:

<OutDialEntry>
<PhoneNumber>sPhoneNumber</PhoneNumber>
<PhoneNumberPrefix>sPhoneNumberPrefix</PhoneNumberPrefix>
<ActivateTime>sCallTime</ActivateTime>
<DayTimeStart>sDayTimeStart</DayTimeStart>
<DayTimeStop>sDayTimeStop</DayTimeStop>
<DaysCallAllowed>sDaysCallAllowed</DaysCallAllowed>
<PortSelection>sPortSelection</PortSelection>
<CampaignName>sCampaignName</CampaignName>
<Priority>iPriority</Priority>
<OnAnswerLive>sOnAnswerLive</OnAnswerLive>
<OnAnswerMachine>sOnAnswerMachine</OnAnswerMachine>
<OnAnswerFax>sOnAnswerFax</OnAnswerFax>
<OnNotAnswered>sOnNotAnswered</OnNotAnswered>
<OnRetriesExhausted>sOnRetriesExhausted</OnRetriesExhausted>
<AnswerTimeout>iAnswerTimeout</AnswerTimeout>
<RetriesLeft>iRetriesLeft</RetriesLeft>
<RetriesDelay>iRetriesDelay</RetriesDelay>
<RV>sRV</RV>
<CallOptions>sCallOptions</CallOptions>
<Escalation>
sEscalation
</Escalation>
</OutDialEntry>

Where:
sPhoneNumber | Phone number to be dialed.
sPhoneNumberPrefix | Prefix to the phone number to be dialed. Prepended to the phone number before dialing.
sActivateTime | Time the call is to be made. Format is YYYY-MM-DD HH:NN:SS If this setting is blank or is omitted then the call will commence immediately. Format may also be: Now+X where X is the number of minutes from the current time that the call should be scheduled for.
sDayTimeStart | Time of the day from which this number can be dialed. Format is: HHNN and the time is specified in 24-hour format. eg: 0800 would mean: this number may be called after 8am. If this setting is blank or is omitted then the call will be allowed to be made from midnight onwards.
sDayTimeStop | Time of the day after which this number can no longer be dialed. Format is: HHNN and the time is specified in 24-hour format. eg: 2100 would mean: do not dial this number after 9pm. If this setting is blank or is omitted then the call will be allowed to be made right up to midnight.
sDaysCallAllowed | On which days of the week can this number be dialed. Format is : [Mo][Tu][We][Th][Fr][Sa][Su] eg: MoWe would mean: this number may only be called on Mondays and Wednesdays. If this setting is blank or is omitted then the call will be allowed to be made on every day of the week.
sPortSelection | If the outbound call may only be made on particular phone lines then the ports to which those lines are attached should be listed in this setting. The ports should be specified as a comma delimited list of physical ports (eg: 1,2,3). If any of the lines are allowed to be used then this setting should be left blank. eg: 3,4,5 would indicate that the outgoing call can only be made on third, fourth or fifth port.
sCampaignName | User defined name campaign name associated with this call. Used to assist in segregating of outgoing calls based on their porpoise or source etc.
iPriority | At what priority level the calls should be made. A lower number indicates a higher priority. ie: 1 is the highest priority, then 2 etc etc. Number of priority levels is unlimited.
sOnAnswerLive | VoiceGuide script or sound file which will be used when the call is answered by a real person The full path to this script or sound file must be specified. Specifying the starting module can be made using notation: Script Filename|Module Title
sOnAnswerMachine | VoiceGuide script or sound file which will be used when the call is answered by an answering machine. The full path to this sound file or script must be specified. If this setting is blank or is omitted then the sOnAnswerLive setting will be used. If the word none is specified, then no file will be played and the call will be hung up. The call will still be considered as having been completed. If the word retry is specified, then the no file will be played and the call will be hung up, and dialed again at a later time (up to the maximum number of retries).
sOnAnswerFax | Fax to send. This can be a .PDF or a .TIFF file. Note that when this field is specified VoiceGuide will start playing the Fax Calling Tone immediately after the number is dialed. The OnAnswerLive and OnAnswerMachine will be ignored, as only a fax send will be attempted during the call.
sOnNotAnswered | VBScript or .EXE/.COM/.BAT/etc. to run when the outgoing call has not been answered.
sOnRetriesExhausted | VBScript or .EXE/.COM/.BAT/etc. to run when the outgoing call has not been answered and there are no more retries left. This command is ran in addition to the OnNotAnswered command.
iAnswerTimeout | How many seconds VoiceGuide will wait for the call to be answered. If this setting is blank or is omitted then the answer timeout will be set to 60 seconds.
iRetriesLeft | How many times VoiceGuide will re-dial the phone number, before abandoning trying to contact this number. If iRetriesLeft is set to 0 then only one call will be made. If this setting is blank or is omitted then a value of 2 will be used. (ie: up to 3 call attempts in total)
iRetriesDelay | How many minutes VoiceGuide will wait between successive attempts (if iCallRetries is set to 1 or more). If this setting is blank or is omitted then a value of 5 will be used.
strRV | List of custom Result Variables which can be used by the VoiceGuide script above. The format of this field is [RvName]{RvValue}. Multiple Result variables can be specified by listing as many name-value pairs as needed. eg: [rv1]{val1}[rv2]{val2}[rv3]{val3}
sCallOptions | Used for the specifying of custom call options. eg. CallerID to be sent.
sEscalation | Alternate numbers to be dialed if the call has not been answered. Once the number of retries calling sPhoneNumber is exhausted, then then alternative escalation number will be dialed immediately. Format is in <OutDialEntry>...</OutDialEntry> structure format - this allows for multiple escalations to be specified, each with its own custom settings.

Example 1 : Simple message delivery to a single number.

Any simple message / script delivery.

Scenario: Call telephone number 5553423, and run script d:\scripts\alarm.vgs when call is answered. Call is to be made immediately. The OutDial file should contain:

<OutDialEntry>
<PhoneNumber>5553423</PhoneNumber>
<OnAnswerLive>d:\scripts\alarm.vgs</OnAnswerLive>
</OutDialEntry>

If the call is not answered then the number will be called up to two more times at 5 minute intervals.

Example 2 : Scheduling a call for a particular time.

Wake up calls.
Appointment reminder service.
Any announcements which need to be sent out at a particular time.

Scenario: Call telephone number 5553328 at 6:30 in the morning on 12th June 2018 and run the script d:\scripts\todays_specials.vgs - passing to the script Result Variables which that script uses (in this case it will be pricing of the items on special for this customer). If an Answering Machine answers then run a modified version of the script which just plays the prices and leaves contact details (d:\scripts\todays_specials_AM.vgs). The OutDial file should contain:

<OutDialEntry>
<PhoneNumber>5553328</PhoneNumber>
<ActivateTime>2018-06-12 06:30:00</ActivateTime>
<OnAnswerLive>d:\scripts\todays_specials.vgs</OnAnswerLive>
<OnAnswerMachine>d:\scripts\todays_specials_AM.vgs</OnAnswerMachine>
<RV>[ClientID]{123456}[PriceWidget]{125}[PriceDelivery]{7.50} </RV>
</OutDialEntry>

Example 3 : Ensuring call is made during particular days/hours.

Surveys.
Distributing information to a large client base.
Whenever making a large number of calls and need to ensure that calls are only made between the hours allowed.

Scenario: Call the telephone number 5553328 at between 10am and 6pm on any weekday, and run script d:\scripts\paymentoverdue.vgs - passing to the script Result Variables which that script uses (in this case the customer ID and the amount owing). If an Answering Machine answers then run a modified version of the script which just plays the amount owing and leaves contact details (d:\scripts\paymentoverdue_AM.vgs). The OutDial file should contain:

<OutDialEntry>
<PhoneNumber>5553328</PhoneNumber>
<DayTimeStart>1000</DayTimeStart>
<DayTimeStop>1800</DayTimeStop>
<DaysCallAllowed>MoTuWeThFr</DaysCallAllowed>
<OnAnswerLive>d:\scripts\paymentoverdue.vgs</OnAnswerLive>
<OnAnswerMachine>d:\scripts\paymentoverdue_AM.vgs</OnAnswerMachine>
<RV>[ClientID]{4453566}[AmountOwing]{14325}</RV>
</OutDialEntry>

Specifying the days on which calls can be made and the time range during which the call can be made is useful if a large number of calls are queued and there is a need to ensure that the system will not make the calls on odd days or hours.

When specifying a large number of calls it is usually easier to use the Telephone Number Loader program, or loading the calls directly into the database.

Example 4 : Escalated Calls

Delivering information to on-call staff, with supervisor escalation if calls by main staff not answered.
Follow-me message delivery - where a number of possible contact numbers is given.
Whenever a message needs to be delivered to one of a range of telephone numbers.

Scenario 1: Call the number 5551111 immediately and run the script d:\scripts\alert.vgs - passing to the script Result Variables which that script uses (in this case it will be information on a problem reported by customer). If the number does not answer then wait 5 minutes and try calling it again. If after 3rd call attempt the number still does not answer then try calling 5552222 - again calling up to 3 times at 5 minute intervals. If an answering machine answers the call then start the d:\scripts\alert.vgs script as well (script should be designed to just play the information to caller). If on 3rd call attempt the second number still does not answer then run a VB Script d:\scripts\notanswered.vbs

The OutDial file should contain:

<OutDialEntry>
<PhoneNumber>5551111</PhoneNumber>
<OnAnswerLive>d:\scripts\alert.vgs</OnAnswerLive>
<RetriesLeft>2</RetriesLeft>
<RetriesDelay>5</RetriesDelay>
<RV>[ClientID]{554}[Severity]{2}[ContactTel]{5559743}</RV>
<Escalation>
<OutDialEntry>
<PhoneNumber>5552222</PhoneNumber>
<OnAnswerLive>d:\scripts\alert_level2.vgs</OnAnswerLive>
<RetriesLeft>2</RetriesLeft>
<RetriesDelay>5</RetriesDelay>
<RV>[ClientID]{554}[Severity]{2}[ContactTel]{5559743}</RV>
<OnRetriesExhausted>d:\scripts\notanswered.vbs</OnRetriesExhausted>
</OutDialEntry>
</Escalation>
</OutDialEntry>

Scenario 2: Message Delivery to a Live Person only :
Call the number 5551111 immediately and run the script d:\scripts\alert.vgs - passing to the script Result Variables which that script uses (in this case it will be information on a problem reported by customer). If the number cannot be reached or if an answering machine answers the call then immediately call another number instead (5552222) and if that number is not answered by a live person then call a third number (5553333). If a live person could not be reached on any of these numbers then wait 10 minutes and try calling all 3 numbers again. If after the second call attempt to all 3 numbers no live person could be reached then run a VB Script d:\scripts\notanswered.vbs In this scenario it is acceptable to deliver the message to a Line Person only, calls answered by Answering Machines will not be regarded as successful message delivery calls and no message will be left on the answering machine.

The OutDial file should contain:

<OutDialEntry>
<PhoneNumber>5551111</PhoneNumber>
<OnAnswerLive>d:\scripts\alert.vgs</OnAnswerLive>
<OnAnswerMachine>retry</OnAnswerMachine>
<RetriesLeft>0</RetriesLeft>
<RV>[ClientID]{554}[Severity]{2}[ContactTel]{5559743}</RV>
<Escalation>
<OutDialEntry>
<PhoneNumber>5552222</PhoneNumber>
<OnAnswerLive>d:\scripts\alert.vgs</OnAnswerLive>
<OnAnswerMachine>retry</OnAnswerMachine>
<RetriesLeft>0</RetriesLeft>
<RV>[ClientID]{554}[Severity]{2}[ContactTel]{5559743}</RV>
<Escalation>
<OutDialEntry>
<PhoneNumber>5553333</PhoneNumber>
<OnAnswerLive>d:\scripts\alert.vgs</OnAnswerLive>
<OnAnswerMachine>retry</OnAnswerMachine>
<RetriesLeft>0</RetriesLeft>
<RV>[ClientID]{554}[Severity]{2}[ContactTel]{5559743}</RV>
<Escalation>
<OutDialEntry>
<PhoneNumber>5551111</PhoneNumber>
<CallTime>Now+10</CallTime>
<OnAnswerLive>d:\scripts\alert.vgs</OnAnswerLive>
<OnAnswerMachine>retry</OnAnswerMachine>
<RetriesLeft>0</RetriesLeft>
<RV>[ClientID]{554}[Severity]{2}[ContactTel]{5559743}</RV>
<Escalation>
<OutDialEntry>
<PhoneNumber>5552222</PhoneNumber>
<OnAnswerLive>d:\scripts\alert.vgs</OnAnswerLive>
<OnAnswerMachine>retry</OnAnswerMachine>
<RetriesLeft>0</RetriesLeft>
<RV>[ClientID]{554}[Severity]{2}[ContactTel]{5559743}</RV>
<Escalation>
<OutDialEntry>
<PhoneNumber>5553333</PhoneNumber>
<OnAnswerLive>d:\scripts\alert.vgs</OnAnswerLive>
<OnAnswerMachine>retry</OnAnswerMachine>
<RetriesLeft>0</RetriesLeft>
<RV>[ClientID]{554}[Severity]{2}[ContactTel]{5559743}</RV>
<OnRetriesExhausted>d:\scripts\notanswered.vbs</OnRetriesExhausted>
</OutDialEntry>
</Escalation>
</OutDialEntry>
</Escalation>
</OutDialEntry>
</Escalation>
</OutDialEntry>
</Escalation>
</OutDialEntry>
</Escalation>
</OutDialEntry>

The above script will result in the numbers being called in the following order : 5551111, then if no answer dial 5552222, and if no answer then dial 5553333, then wait for 10 minutes, and repeat calling 5551111 then 5552222 then 5553333. Dialing of further numbers would stop as soon as one of the calls is answered.


Detecting Outgoing Call Answer

How VoiceGuide detects that an outgoing call has been answered depends on what telephone lines/trunks are used.

Analog

Dialogic cards can detect when a call has been answered and can distinguish if a call has been answered by a live person or by an answering machine. When the recipient of call starts saying something the Dialogic card can determine whether the call has been answered by a human or by a machine/voicemail. VoiceGuide will then run the appropriate script.

If answering machine detection is disabled then the Dialogic card will just wait for any spoken sounds (live or machine), and once it hears anything (or ringback has gone away) then the call will be reported as answered. The ringback tone for which the Dialogic card is to listen out for needs to be correctly specified. The default value will work for most ringbacks, but sometimes it will be necessary to set the ringback tone definition in ConfigLine.xml file.

If recipient of call does not say anything after answering the call (or there is just silence on the line) then the Dialogic card will deduce that the call has been answered only when it realizes that the 'ringback' signal has gone away.

If the Dialogic card does not correctly detect the ringback tone on the line, then after a timeout (about 8 seconds) it will report the outgoing call as connected even though the outgoing line is still ringing.

Digital T1/E1 ISDN, VoIP (SIP)

On T1/E1 and VoIP connections VoiceGuide will know the instant the call recipient picks up the handset or presses the 'answer call' button.

VoiceGuide script will be immediately started if Dialogic's answering machine detection is not enabled.

If Dialogic's answering machine detection is enabled, then Dialogic will wait to hear what is said on the line by the call recipient, and then based on what it hears Dialogic will determine whether the call has been answered by a human or by a machine. VoiceGuide will then run the appropriate script.

If answering machine detection is enabled and recipient of call does not say anything after answering the call, then the Dialogic card will timeout out after a few seconds and report the call as connected.

Similarly, an indication that the destination telephone is busy or disconnected is sent back to the digital card from the network immediately - allowing for quick abandoning of those calls and dialing of another number if needed.

The sound quality of VoIP connections is sometimes not as good as when Analog or Digital trunks are used, and hence the precision with which answering machines vs. live persons are detected is sometimes worse then on Analog or Digital systems.

Detecting Answering Machines

Dialogic can distinguish if a call has been answered by an answering machine or by a human. No other telephony cards/drivers can do that as well as Dialogic and that is why Dialogic platform is the best choice for systems which do outbound dialing.

VoiceGuide uses Dialogic's answering machine detection mechanism to distinguish whether a person or an answering machine has answered the call. Dialogic's answering machine detection uses frequency based analysis and detection of whether the speech is coming from live person or answering machine is made in about 1 second. If Dialogic informs VoiceGuide that it has detected an answering machine / voicemail, then VoiceGuide will wait for the sound prompt on the line to finish before playing the answering machine message or starting the script.

Answering Machine detection is enabled by default. The following keywords can be used in the "Answering Machine" text field to modify this behaviour:
RETRY | VoiceGuide will hang up and dial again (up to the maximum number of redials allowed).
IGNORE | VoiceGuide will start the "Live Person Answer" script if answering machine detected.
DISABLE | Answering Machine detection is disabled. VoiceGuide will start the "Live Person Answer" script immediately when call is picked up.

If Answering Machine was detected, the $RV[AmWelcMsg]) will store the length of the Answering Machine message (in 100ms units).

False reports of an Answer Machine answer when a Live Peron actually answered the call:

On poor quality lines (usually low quality VoIP and mobile phone connections) Dialogic will sometimes mistakenly report that an answering machine/voicemail answered the call when in fact the call was answered by a real person. The reason for this is that the low quality of the connection makes the voice of the person answering the call sound very similar to the sound quality usually expected from an answering machine.

Background noise can also play a factor in false detection of answering machines (eg: radio playing in background, machine noise, etc).

False reports of a Live Person answer when an Answer Machine actually answered the call:

If the answering machines/voicemails welcoming message is recorded in high quality then it is possible for Dialogic to mistake it for a real person answering the call. The commonly used analog based answering machines are usually correctly detected by Dialogic.

One approach to work around false live person detections would be to first play in the "Live Answer" script a short message that says for example: "This is a call from XYZ" and then us a Record type module to start recording. Set the silence length that ends the recording in that module to be short - about one second or half a second. In the record module itself use a "on {silence} goto... " path and point the actual start of the script. When the recording finishes due to silence and the actual script starts then the first message played will be recorded on the answering machine/voicemail, or heard by the caller. This approach will result in system waiting till answering machine finishes playing, and people answering the call will only hear a short pause of 1-1.5 seconds between the fist and second sound file being played.

Fine tuning Dialogic Answer Detection Parameters

With VoiceGuide configuration files it is possible to set all entries in the Dialogic DX_CAP structure, which includes Dialogic's low level settings that affect the Answering Machine / Live Answer detection parameters:

ca_cnosig
ca_noanswer
ca_pamd_failtime
 etc.

There are about 30-40 settings in the DX_CAP structure, all of which are accessible, allowing total control (on a per-call basis) over how Dialogic performs the detection.

For more information on the fields in the DX_CAP structure please refer to Dialogic's documentation - the "Voice API" section.

To change settings from the default values used by VoiceGuide an XML style expression needs to be specified in the "Call Options" field. Example of the expression used is show below:

<DX_CAP><ca_cnosig>500</ca_cnosig><ca_pamd_failtime>200</ca_pamd_failtime></DX_CAP>

Detecting end of Answering Machine message:

Silence detection is used to detect end of answering machine messages.

The level and length of the silence that will trigger 'end-of-message' event is set in VG.IN in section [VGDialer], settings: AM_SilenceDetectLength and AM_SilenceDetectLevel.

This silence detection length and level can also be set on a per-call basis, using Result Variables: $RV[SilenceDetectLvl] and $RV[SilenceDetectLen].

eg: adding this to the "ResultVariables" field of the outgoing call:

[SilenceDetectLvl]{5}[SilenceDetectLen]{30}

will set the detect level to 5 (level can be between 1 and 100, 0 to turn off detection), and SilenceDetectLen's "30" setting represents 3 seconds (SilenceDetectLen is in 100ms units)

Recording of Answering Machine messages:

The latest answering machine message for call made on each port is saved as a "rec_am_*.wav" sound file in VoiceGuide's \temp\ subdirectory.

To have every answering machine message saved in \temp\ subdirectory, set: AM_RecUnique=1 in VG.INI, in section [VGDialer]


Outbound calls on VoIP lines

When placing an outgoing call the IP address or domain of the Switch/PBX which will be routing the call needs to be specified.

For example, when dialing another extension on the VoIP Switch/PBX the number dialed would be in the format: extension@ip_address_of_voip_switch

eg:

204@10.1.1.11

According to how the VoIP switch is set up, the "extension" could also be an external phone number.

when dialing through a VoIP provider, often the VoIP provider's SIP server domain/address needs to be specified. eg:

15551231234@callcentric.com

Note:
The Network Adapter's DNS settings must not have any uncontactable DNS entries.
Otherwise the domain names used on outgoing calls may not be resolved,
and DNS NAPTR record queries done as part of responding with Authentication details will fail.
If HMP is unable to perform the DNS NAPTR record query, then a domain-name addressed outgoing call that requires Authentication will fail.

CallerID / "From:" field

When making an outgoing call on a VoIP line it is usually necessary to specify the CallerID to be used on the outgoing call. This advises the switch relaying the VoIP call as to which account/subscriber is making the call.

The CallerID is set in the SIP header's "From:" field.

The CallerID ("From:" field) on outgoing calls can be specified using the <CallerID> tag in the call's Options, in this format:

<CallerID>accountnumber@voipprovider</CallerID>

eg: to place a call through a PBX which is installed on a server with IP of 10.1.1.11, and with which the user/extension 2000 has been registered by VoiceGuide, the following entry would need to be included in the Options field:

<CallerID>2000@10.1.1.11</CallerID>

Sometimes just the user ID (or the registered telephone number) is sufficient, eg:

<CallerID>5625551234</CallerID>

And to place a call through a VoIP provider with which the account was registered by VoiceGuide, an entry that includes the domain name of the provider needs to be used. eg: with CallCentric, this would need to be used:

<CallerID>5551234@callcentric.com</CallerID>

and with Skype SIP Connect, a CallerID definition similar to this would need to be used:

<CallerID>990510045673275@sip.skype.com</CallerID>

In the Outbound Call Loader app the Call Options are set in the "Call Options" text box, located at the bottom of the "Script" page.

If loading the calls using the XML method th Call Options are set in the <CallOptions> field.

Authentication

VoIP switch will often require to authenticate the user before allowing the outbound call to be made.

IP-based authentication does not require any additional configuration in VoiceGuide.

If Digest authentication is used then it is necessary to specify the Registration and Authentication parameters.
Please see here: VoIP Line Registraton

User Specified Headers

If specific headers need to be added/modified in the outgoing SIP INVITE packet then these can also be specified in the call's options when loading the outgoing call.
To add a SIP header a "<sip-header>" entry needs to be specified as part of the call's options.
eg: to add a "MyHeader" header, this entry could be added:

<sip-header>MyHeader: "somevalue" <sip:123456@sip.router.com></sip-header>

eg:
"sip-session-expires" and "sip-min-se" entries can also be specified like this:

<sip-session-expires>999</sip-session-expires>
<sip-min-se>55</sip-min-se>

(or these header entries could be just added using the "<sip-header>" approach)

Multiple headers can be specified. Below is a valid options entry:

<CallerID>12121212@sip.mycarrier.com</CallerID>
<sip-session-expires>999</sip-session-expires>
<sip-min-se>55</sip-min-se>
<sip-header>Remote-Part-ID: "Flowroute" <sip:123412341234@sip.flowroute.com;party=calling;screen=yes;privacy=on</sip-header>
<sip-header>X-Tag: mySpecialCallTag123</sip-header>
<sip-header>Diversion: <sip:333444555@sip.mycarrier.com></sip-header>

Where to set Call Options

Call options can be set the "Call Options" text box in the Outbound Call Loader app, or in the <CallOptions> field in the OutDial XML file, like this:

<CallOptions>
<CallerID>12121212@sip.mycarrier.com</CallerID>
<sip-session-expires>999</sip-session-expires>
<sip-min-se>55</sip-min-se>
<sip-header>Remote-Part-ID: "Flowroute" <sip:123412341234@sip.flowroute.com;party=calling;screen=yes;privacy=on</sip-header>
<sip-header>X-Tag: mySpecialCallTag123</sip-header>
<sip-header>Diversion: <sip:333444555@sip.mycarrier.com></sip-header>
<CallOptions>

WireShark can be used to verify that the headers have been set in the outgoing INVITE packets as expected.


Ring Group Calls

A Ring Group Call is a form of dialing multiple numbers at the same time, with only with the party that answers first proceeding with the call.
When the first call is answered all other outgoing calls in the Ring Group are hung up.

To place a Ring Group Call the multiple telephone numbers are specified separated by the & character.

eg:

5551111&5552222&5553333&5554444

Will result in calls to 4 numbers being placed, with the call only proceeding with the party that answers first.

User Selected Calls

The winning Ring Group Call can be user selected, instead of automatically determioned by first call answer.
User selection allows creation of Ring Group solutions where the winning call is selected upon positive call acceptence from call recipient.
eg: by pressing a key on a telephone keypad.

If the below is set in the outgoing call's Options, then the Ring Group Calls will not be hung up upon first call answer:

<ringgroup>hangup_on_api_call</ringgroup>

but will only be hung up when the following Action API call is made:

vgo.Action $RV_LINEID, "ringgroup_hangup_others", 0, 0, 0, "", "", ""

the LineID parameter is used to specify the LineID of the winning call that is allowed to continue, with all other calls in the Ring Group hung up.
Note that this means that other recipients of the Ring Group calls may have their calls abruptly ended - if thery have answered the call but were not the first one to 'accept' it.

To prevent such abrupt hangups it is possible to handle the Ring Group issued hangup by specifying a {ringgroup_hangup} path in the modules where ring gropup call recipients may be in when the winning line issues the "ringgroup_hangup_others" Action.

eg:

on {ringgroup_hangup} goto [play_disconnect_message]

Result Variables

$RV_RingGroup holds the unique Ring Group ID. Ring Group ID is the same for all the calls belonging to the same Ring Group.


Predictive Dialers

Predictive Dialers are automated dialing systems designed to reach contacts and connect them to agents upon call answer.

VoiceGuide can be used to create all the various types of Predictive Dialing systems, by modifying the scripts used by the VoiceGuide dialer on outgoing calls. A VoiceGuide based system can blend inbound, outbound, and voice messaging campaigns as well as run multiple simultaneous campaigns.

Predictive Outbound IVR

The rate at which the Outbound IVR calls are made is dependant on how many agents are predicted to be available at the time when call recipients may request transfer to agent.

Click to Callback

Web page can include a "Call me" button to immediately initiate an outbound call from VoiceGuide, and once call answered and call recipient is verified VoiceGuide can connect the call to agent.

Predictive Dialer

Rate of calls is determined by number of agents predicted to be available when calls are predicted to be answered. If no agents are immediately available to connect to answered call then VoiceGuide can take contact through a personalized IVR script until an agent becomes available.

Power Dialer

Start multiple simultaneous calls per employee at the moment agents are ready. If more calls are answered then expected then VoiceGuide can take contact through an IVR script personalized with customer related information until an agent becomes available.

Progressive / Automated / Preview Dialer

At the moment agents are ready, a single record is displayed for employee review prior to connection and that single number is automatically called. This approach only eliminates the need for agent to manually enter the number to be called, but ensures that an agent will always be ready to speak to the the person answering the call.


VoiceGuide Database

VoiceGuide uses a database to store details of queued outgoing calls, CDRs, reportable statistics, etc.

VoiceGuide will by default use an SQLite database, which is sufficient for most applications.
The SQLite database file is called vgDb.db and is located in VoiceGuide's \data\ subdirectory.

Sometimes it is desirable that VoiceGuide uses a different database engine instead.

To use another database engine:

  1. Create the main Database object to be used by VoiceGuide.
  2. Specify the connection string in VoiceGuide's Config.xml, in section <Dialer>

VoiceGuide will create all the necessary Tables/Indexes/etc the first time it uses the user specified database.

The <Dialer> section should be placed inside the Config.xml's <VoiceGuideConfig> section.

MS SQL Server

Example Config.xml <Dialer> section for MS SQL Server:

<Dialer>
<OutDialQue_ADODB_Provider>System.Data.SqlClient</OutDialQue_ADODB_Provider>
<OutDialQue_Database>vgDb</OutDialQue_Database>
<OutDialQue_ConnectString>Data Source=10.1.1.78,1433;Database=$DATABASE;User ID=someuser;Password=somepassword;</OutDialQue_ConnectString>
<OutDialQue_PortToUse_LinkField></OutDialQue_PortToUse_LinkField>
<OutDialQue_SqlPrefix></OutDialQue_SqlPrefix>
<OutDialQue_SqlSuffix></OutDialQue_SqlSuffix>
</Dialer>

After setting the Config.xml to appropriate values you will need to create the database (schema) object named vgDb (or whatever the name specified in the <OutDialQue_Database> section is). Use the Microsoft SQL Server Management Studio to create the database object.

Configuring MS SQL Server

If the SQL Server is on a system separate to VoiceGuide then it needs to be configured to allow external connections. Also the system's firewall needs to be set to pass though the external connection requests to the database.

MySQL

When using MySQL as the VoiceGuide backend DB you should first install the MySQL ADO.NET Data Provider.

Here is an example Config.xml <Dialer> section for MySQL:

<Dialer>
<OutDialQue_ADODB_Provider>MySql.Data.MySqlClient</OutDialQue_ADODB_Provider>
<OutDialQue_Database>vgDb</OutDialQue_Database>
<OutDialQue_ConnectString>Database="$DATABASE";Data Source="10.1.1.9";User Id="someuser";Password="somepassword";</OutDialQue_ConnectString>
<OutDialQue_PortToUse_LinkField></OutDialQue_PortToUse_LinkField>
<OutDialQue_SqlPrefix>SELECT</OutDialQue_SqlPrefix>
<OutDialQue_SqlSuffix>LIMIT 1</OutDialQue_SqlSuffix>
</Dialer>

After setting the Config.xml to appropriate values you will need to create the database (schema) object named vgDb (or whatever the name specified in the <OutDialQue_Database> section is). You can use the MySQL Workbench to create the database schema object. You must ensure that the user specified in the Connection string has the rights to fully work with and manage the vgDb schema.

Best way to configure and test the ADO.NET connection is to just start the VoiceGuide "Outbound Call Loader" application. On startup the Outbound Call Loader will connect to the database object and run the Db_Create_MySql.Data.MySqlClient.sql script creating the Tables and Indexes. You can then use the Outbound Call Loader to load new calls into the system, or try loading the calls into the database yourself directly.

The<OutDialQue_SqlPrefix> and <OutDialQue_SqlSuffix> values are used when VoiceGuide constructs the SQL query to find the suitable call in the PortToUse table.

To enable priority sorting of calls on MySQL the OutDialQue_SqlSuffix setting should be set to:

<OutDialQue_SqlSuffix>ORDER BY Priority ASC LIMIT 1</OutDialQue_SqlSuffix>

Please note that priority sorting of calls can increase the time taken to retrieve the next call details if large number of calls is queued.

Oracle

When using Oracle as the VoiceGuide backend DB you should install Oracle's ADO.NET Data Provider (Oracle.DataAccess.Client).

Here is an example Config.xml <Dialer> section for Oracle:

<Dialer>
<OutDialQue_ADODB_Provider>Oracle.DataAccess.Client</OutDialQue_ADODB_Provider>
<OutDialQue_Database>vgDb</OutDialQue_Database>
<OutDialQue_ConnectString>Data Source=(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=10.1.1.26)(PORT=1521))(CONNECT_DATA=(SERVER=DEDICATED)(SERVICE_NAME=$DATABASE)));User Id=HR;Password=hr;</OutDialQue_ConnectString>
<OutDialQue_PortToUse_LinkField>Disable</OutDialQue_PortToUse_LinkField>
<OutDialQue_SqlPrefix>SELECT</OutDialQue_SqlPrefix>
<OutDialQue_SqlSuffix></OutDialQue_SqlSuffix>
</Dialer>

At this stage we would recommend disabling the PortToUse table if Oracle is used.

Postgres 9.2.x

Here is an example Config.xml <Dialer> section for Postgres 9.2.x (and later):

<Dialer>
<OutDialQue_ADODB_Provider>Npgsql</OutDialQue_ADODB_Provider>
<OutDialQue_Database>vgDb</OutDialQue_Database>
<OutDialQue_ConnectString>Server=10.1.1.36;User Id=postgres;Password=postgres;Database=vgDb;</OutDialQue_ConnectString>
<OutDialQue_PortToUse_LinkField></OutDialQue_PortToUse_LinkField>
<OutDialQue_SqlPrefix>SELECT</OutDialQue_SqlPrefix>
<OutDialQue_SqlSuffix>LIMIT 1</OutDialQue_SqlSuffix>
</Dialer>

For a Postgress installation on the same machine the IP address 127.0.0.1 should be used:

<Dialer>
<OutDialQue_ADODB_Provider>Npgsql</OutDialQue_ADODB_Provider>
<OutDialQue_Database>vgDb</OutDialQue_Database>
<OutDialQue_ConnectString>Server=127.0.0.1;Port=5432;User Id=postgres;Password=postgres;Database=vgDb;</OutDialQue_ConnectString>
<OutDialQue_PortToUse_LinkField></OutDialQue_PortToUse_LinkField>
<OutDialQue_SqlPrefix>SELECT</OutDialQue_SqlPrefix>
<OutDialQue_SqlSuffix>LIMIT 1</OutDialQue_SqlSuffix>
</Dialer>

If Postgres is installed on another server you will need to configure Postgres to allow remote access. This is done by editing Postgres pg_hba.conf configuration file.

Best way to configure and test the ADO.NET connection is to just start the VoiceGuide "Outbound Call Loader" application. On startup the Outbound Call Loader will connect to the database object and run the Db_Create_Npgsql.sql script creating the Tables and Indexes. You can then use the Outbound Call Loader to load new calls into the system, or try loading the calls into the database yourself directly.

SQLite

For completeness, here is an example Config.xml <Dialer> section which is used by default to connect to an SQLite database:

<Dialer>
<OutDialQue_ADODB_Provider>System.Data.SQLite</OutDialQue_ADODB_Provider>
<OutDialQue_Database>C:\Program Files (x86)\VoiceGuide\data\vgDb.db</OutDialQue_Database>
<OutDialQue_ConnectString>Data Source=$DATABASE</OutDialQue_ConnectString>
<OutDialQue_PortToUse_LinkField></OutDialQue_PortToUse_LinkField>
<OutDialQue_SqlPrefix>SELECT</OutDialQue_SqlPrefix>
<OutDialQue_SqlSuffix>LIMIT 1</OutDialQue_SqlSuffix>
</Dialer>

Call Prioritization

Priority ordering is specified by using the ORDER BY clause when selecting calls from the database. This clause is specified in the OutDialQue_SqlSuffix setting in the <Dialer> section of the Config.xml file:

<OutDialQue_SqlSuffix>ORDER BY Priority ASC</OutDialQue_SqlSuffix>

If you have a large number of calls loaded then ordering the retrieved calls by Priority can degrade call data retrieval speed. If you are seeing excessive call retrieval times from the database then removing this clause would speed up call retrieval.

If priority is being enabled and a large number of calls are being loaded then we'd recommend using a sever class database like SQL Server or MySql etc.

Loading Calls Directly

This section outlines how calls need to be loaded into the Dialer Database if you would like your own programs to load the calls instead of using the VoiceGuide Telephone Number Loader or the VoiceGuide WCF/COM function or XML file to load the calls.

The outbound calls database uses two tables: CallQue and PortToUse

Addition of new calls into the system involves placing new entries in both tables, with possible multiple entries in the PortToUse table, depending on what port selections need to be specified.

The PortToUse table is used to indicate on which ports the particular call can be made. If a call is allowed to be made on any of the systems ports then a single entry in the PortToUse table needs to be made, with the PortToUse. PortNumber field assigned a value of -1. Otherwise if call can only be made on some of the ports then a new row needs to placed in PortToUse for each port on which the outgoing call is allowed to be made. The telephony ports on the VoiceGuide system are numbered from 1.

By default the PortToUse table is used when establishing which call is to be made next. Scheduling information is still included in the CallQue table as there is an option of turning off the PortToUse table use altogether if there is no need to limit the ports on which the calls can be made.

It's recommended to use the Outbound Call Loader application to load some calls into the database and then examine the database tables to how the information is placed in the tables.

The SQL statements used can be seen in the vgDialListLoad trace files (see VG's \log\ subdirectory), and it's recommend that these traces be looked at by anybody wanting to see how the Dial List Loader is actually performing the inserts.

Here are the two main SQL statements used (with parameter placeholders):

INSERT INTO callque (GUID, PhoneNumber, PhoneNumberPrefix, ActivateTime, Priority, TimeStart_Mon, TimeStart_Tue, TimeStart_Wed, TimeStart_Thu, TimeStart_Fri, TimeStart_Sat, TimeStart_Sun, TimeStop_Mon, TimeStop_Tue, TimeStop_Wed, TimeStop_Thu, TimeStop_Fri, TimeStop_Sat, TimeStop_Sun, CampaignName, OnAnswerLive, OnAnswerMachine, OnAnswerFax, OnNotAnswered, OnRetriesExhausted, AnswerTimeout, RetriesLeft, RetriesDelay, RV, CallOptions, EscalationCalls)
OUTPUT Inserted.ID VALUES (@guid, @strNbrToDial, @strPhoneNumberPrefix, @dateActivateTime, @iPriority, @iTimeStart_Mon, @iTimeStart_Tue, @iTimeStart_Wed, @iTimeStart_Thu, @iTimeStart_Fri, @iTimeStart_Sat, @iTimeStart_Sun, @iTimeStop_Mon, @iTimeStop_Tue, @iTimeStop_Wed, @iTimeStop_Thu, @iTimeStop_Fri, @iTimeStop_Sat, @iTimeStop_Sun, @strCampaignName, @strOnAnswerLive, @strOnAnswerMachine, @strOnAnswerFax, @strOnNotAnswered, @strOnRetriesExhausted, @iAnswerTimeout, @iRetriesLeft, @iRetriesDelay, @strRV, @strOptions, @strEscalationCalls);

INSERT INTO porttouse (CallID, CallGUID, PortNumber, ActivateTime, Priority, TimeStart_Mon, TimeStart_Tue, TimeStart_Wed, TimeStart_Thu, TimeStart_Fri, TimeStart_Sat, TimeStart_Sun, TimeStop_Mon, TimeStop_Tue, TimeStop_Wed, TimeStop_Thu, TimeStop_Fri, TimeStop_Sat, TimeStop_Sun)
VALUES (@iCallID, @guid, @iPortNumber, @dateActivateTime, @iPriority, @iTimeStart_Mon, @iTimeStart_Tue, @iTimeStart_Wed, @iTimeStart_Thu, @iTimeStart_Fri, @iTimeStart_Sat, @iTimeStart_Sun, @iTimeStop_Mon, @iTimeStop_Tue, @iTimeStop_Wed, @iTimeStop_Thu, @iTimeStop_Fri, @iTimeStop_Sat, @iTimeStop_Sun);

All the call details are first inserted into the CallQue table, and then a subset of call information is inserted into the PortToUse table. After inserting a row into the CallQue table the value of the autogenerated ID field needs to be retrieved and the value of that ID field is used in the CallID field when inserting related rows into the PortToUse table. This can be done differently depending on what database is used.
In the INSERT INTO CallQue example above the ID retrieval is done using the SQL command OUTPUT Inserted.ID

The ID retrieval can also be be done on some databases using this SQL command:<

SELECT DISTINCT @@identity FROM callque

The above command can be issued at the same time as the Insert command, like this:

INSERT INTO callque (...) VALUES (...); SELECT DISTINCT @@identity FROM callque

An alternative approach instead of placing the CallQue.ID in the PortToUse.CallID column would be to use a GUID to link the PortToUse entries to the CallQue entry. Just generate a GUID and write the same GUID into the PortToUse.CallGUID column and into the CallQue.GUID column. A value of -1 can then be placed in the PortToUse.CallID column.

Loading Calls Directly - CallTrack table

CallTrack table is used to store a record of the outbound calls' progress, and information from that table is used to generate outbound call reports.

When loading calls directly an entry in CallTrack table should also be created if you would like to keep track of call progress information.

After inserting a row into the CallQue table the value of the autogenerated ID field needs to be retrieved and the value of that ID field should be used in the CallTrack.QueID field when inserting related rows into the CallTrack table.

An alternative approach: instead of placing the CallQue.ID in the CallTrack.QueID column would be to use a GUID to link the CallQue entries to the CallTrack entry. Just generate a GUID and write the same GUID into the CallTrack.QueGUID column and into the CallQue.GUID column.

Other Notes

<OutDialQue_PortToUse_LinkField> options are:

ID | ID is used to link the entries in the CallQue and PortToUse tables. Matching ID-CallID values need to be set in corresponding entries in CallQue and PortToUse tables.
GUID | The GUID value is used to link the entries in the CallQue and PortToUse tables. Matching GUID-CallGUID values need to be set in corresponding entries in CallQue and PortToUse tables.
Disable | Do not use PortToUse table. Call details only need to be loaded into the CallQue table. VoiceGuide will make outbound calls on any available ports. Config.xml can still be used to specify which ports are allowed to make outgoing calls.
not set | If this field is empty or not included at all then VoiceGuide will default to the ID setting.

The <OutDialQue_SqlPrefix> and <OutDialQue_SqlSuffix> values are used when VoiceGuide constructs the SQL query to find the suitable call in the PortToUse table.

The default value used if <OutDialQue_SqlPrefix> is blank is: SELECT TOP 1

The actual SQL scripts used by VoiceGuide to automatically create the database tables used by it can be found in VoiceGuide's \system\setup\ subdirectory. The default scripts used is named Db_Create.sql

ADO.NET Provider Specific versions of this script can be created. To make a Provider-specific script file the Provider name needs to be specified as part of the filename:

Db_Create_ProviderName.sql

eg:

Db_Create_System.Data.SqlClient.sql


CRM Integrations

VoiceGuide IVR can integrate with most CRM systems.

Integration is straightforward for CRMS that offer a REST interface.

Below example shows how VoiceGuide can perform OAuth2 authentication with SugarCRM, and then call the various functions in the SugarCRM REST API.

Version number of SugarCRM REST API that was tested was: v10

OAuth2 Authorisation

VoiceGuide script would use a Web Service module to issue a POST requires to the /oauth2/token REST API function, and provide the required data in JSON format.

The https address to POST to would be something like this:

https://YOURDOMAIN/rest/v10/oauth2/token

With the YOURDOMAIN part replaced with the domain name/IP of your SugarCRM installation.

The Data to be POSTed would be something like this:

{
"grant_type":"password",
"client_id":"sugar",
"client_secret":"",
"username":"MYUSERNAME",
"password":"MYPASSWORD",
"platform":"base"
}

With MYUSERNAME and MYPASSWORD replaced with a valid user/pass defined on your SugarCRM system.

Here is a screenshot of the Web Service module configuration screen:

When this module is ran SugarCRM will return data that will be saved into Result Variables. The OAuth2 access token will be saved in $RV[access_token]
This $RV[access_token] can then by used in subsequent modules that call other SugarCRM REST API functions to add/modify the various SugarCRM items (Accounts, Contacts, Leads, Tasks, Notes, Calls, Bugs, Cases etc.)

To add a new CALL object into SugarCRM a POST would be made to his https address:

https://YOURDOMAIN/rest/v10/calls

With the following data:

{
"name":"New VoiceGuide IVR call",
"description":"VoiceGuide IVR system received a new call",
"assigned_user_name":"Assigned User Name",
"contact_name":"Some Contact Name",
"contact_phone":"5551112222",
"contact_email":"support@voiceguide.com"
}

And the OAuth2 token would be set in the Headers options like this:

oauth-token: $RV[access_token]

Here are the screenshots showing module configuration:

Similar approach is used when creating new Accounts, Contacts, Leads, Tasks, Notes, Bugs, Cases etc.

Sample scripts showing creation/addition of the various SugarCRM objects can be found in VoiceGuide's \Scripts\CRM\ directory.


Speech Recognition

VoiceGuide can use Google Cloud to perform Speech-To-Text (STT) in either real-time, or transcribing recorded sound files.

VoiceGuide also supports any MRCPv2 compliant speech recognition engine.

Please contact sales@voiceguide.com to discuss your Speech Recognition requirements.

Configuring Dialogic Cards

If using Analog Dialogic cards then a special "CSP Enabled" Firmware file will need to be selected. Go the Dialogic Configuration Manager, bring up the properties page for the analog card and on the Misc tab select the following Firmware file:

D/41JCT : d41jcsp.fwl

D/120JCT : d120csp.fwl

Similarly, when using the Dialogic JCT series T1 and E1 cards the "CSP Enabled" Firmware needs to be selected in the Dialogic Configuration Manager. Further changes in dxxx resource specification in Config.xml file also need to be made when using T1 and E1 JCT cards. Please consult support@voiceguide.com when deploying Speech Recognition on T1 or E1 JCT family cards.

Installing the Speech Recognition engine

It is recommended that the Speech Recognition engine be installed on a separate server. Speech Recognition engines have high resource and CPU requirements and the high CPU load can degrade overall IVR performance if the Speech Recognition engine is installed on the same system.

MRCPv2 setup

An mrcp.xml configuration file needs to be placed in VoiceGuide's \conf\ subdirectory.

A sample mrcp config file is placed in the \conf\ subdirectory on installation. It is called "sample_mrcp.xml" and needs to be renamed to mrcp.xml and its entries updated with the correct IP addresses.
Please see comments in that file.

ASR Grammars

To have VoiceGuide recognize speech during a play, a grammar associated with this play module must be defined.
A grammar is defined by creating a text file which contains the grammar for the particular play module, and placing this file in the same directory where the script is located. The filename format is:

asr_ModuleTitle_srgs.txt

The ModuleTitle identifies for which Play module the grammar file is for.

The grammar file contents are read in when the Play module starts.

Other data files can be used to set MRCPv2 parameters and behaviour.
Please contact VoiceGuide Support for more information.

Speech Recognition Engine Responses

When VoiceGuide receives the response from the Speech Recognition Engine it will create the following Result Variables
$RV[ModuleTitle_ASR_Instance] | Contains the speech recognition engine's response. This is also called "Semantic Interpretation"
$RV[ModuleTitle_ASR_Input] | Contains the text of what the caller said.
$RV[ModuleTitle_ASR_Confidence] | Contains the confidence level. Indicates how confident the speech recognition engine is that the recognition is correct range 0-100

VoiceGuide will first see if a path matching the value stored in $RV[ModuleTitle_ASR_Instance] is found.
If the matching path is found then that path is taken.
Next VoiceGuide will first see if a path matching the value stored in $RV[ModuleTitle_ASR_Input] is found.
If the matching path is found then that path is taken.
Otherwise the Success path is taken if some response was returned, or a Fail path is taken if the recognition attempt was not successful.


Installing LumenVox Speech Recognition Engine

Please contact sales@voiceguide.com to arrange LumenVox licenses and access to LumenVox software.

Please refer to LumenVox documentation for LumenVox installation instructions.

The LumenVox MRCPv2 server by default uses port 5060 to accept incoming speech recognition requests. This is the same port used by most VoIP/SIP applications. When running the LumenVox MRCPv2 server with that default setting, no other VoIP/SIP applications should be running on same server.

Configuration Changes

Please refer to LumenVox documentation to establish required configuration settings.

If LumenVox is installed on a different server to VoiceGuide, then the IP address of LumenVox server must be specified in this LumenVox configuration file:

C:\Program Files\LumenVox\Engine\config\media_server.conf

in this entry:

mrcp_server_ip

Information about MRCPv2 parameters that can be set when performing the Speech Recogntion can be found in MRCPv2 RFC 6787 and in LumenVox documentation.


Logs

Script Logs

VoiceGuide can store a log of what the caller did during the course of the call. The script activity logs contain information like:

  • Date & time the call was made and when it completed.
  • Caller ID details (name and number)
  • All the numbers entered in the Play, Get Number Sequence and Say Number modules
  • Filenames of all the recorded messages
  • How many results were returned by the Database Query module
  • Evaluate Expression module results
  • Results of Run Program or Run Script modules
  • etc.

The logs are saved in 4 different formats:

.vgl | VoiceGuide Log Format - saved as a string of Result Variables
.csv | Comma delimited format
.json | JSON document body format
.xml | XML document body format

Script Logs can be turned off by specifying Scripts=OFF in VG.IN in section [Log]

Subscripts

Each script which is used during the call will have a log entry created in the script's corresponding log files. If the script is visited multiple times during a call then a new log entry will be made each time the script is used. This means that if a subscript is called multiple times during one call, it's call log will have multiple entries for the same call - with each entry having different 'start_time' and 'end_time' timestamps.

Create your own Call Log

Run Program or Run VBScript modules can be used to create custom Log files. Please refer to Help file's sections on those modules to see how these modules can be used to append information to a text file.

CDR Logs

Please see here for more information on CDR logs.

vgEngine, ktTel, ktTTs Logs

VoiceGuide system internal application logs are saved in VoiceGuide's \log\ subdirectory.

System logs can be turned off by specifying:

VoiceGuide=0
ktTel=0
ktTts=0
NumberLoader=0

in VG.IN in section [Log]


Call Detail Records (CDRs)

VoiceGuide v7 will create a CDR for all the calls which arrived or were made by the system.

The CDR logs are automatically saved in VoiceGuide's \cdr\ subdirectory, and are also saved in a database. There is also an option to save the CDR data to a Syslog.

The call information is stored in the following CDR format:

  1. account: An account code designation (string)
  2. src: Caller*ID number (string)
  3. dst: Destination extension (string)
  4. dcontext: Destination context/submenu (string)
  5. clid: Caller*ID with text (string)
  6. channel: Channel used (string)
  7. dstchannel: Destination channel if appropriate (string)
  8. lastapp: Last application if appropriate (string)
  9. lastdata: Last application data (arguments) (string)
  10. start: Start of call (date/time)
  11. answer: Answer of call (date/time)
  12. hangup: End of call (date/time)
  13. duration: Total time in system, in seconds (integer)
  14. billsec: Total time call is up, in seconds (integer)
  15. disposition: What happened to the call: ANSWERED, NO ANSWER, BUSY (string)
  16. amaflags: Billing flags (string)
  17. user: User data

The Result Variables defined during the call can be optionally saved in the lastdata field. To enable saving of $RVS in CDR logs add this to the [Log] section of the VG.INI file:

CDR_LastData_SaveRv=1

Contents of $RV[CDR_amaflags] will be placed in the 16th CDR field.

Contents of $RV[CDR_user] will be placed in the 17th CDR field.


Temporary Files

VoiceGuide v7 will save temporary files in \temp\ subdirectory.

Rec_Am_X.wav files are made during End Of Answering Machine Message detection.
X is the "LineID" of the line making the call.
There should be no more of these "Rec_Am" files then the number of lines on the system

TTS_X_Y.wav files are created during Text To Speech and contain the actual TTS generated sound that was played.
X is the "LineID" of the line and Y is the TTS generation counter during the call.
There should be no more of these "TTS" files then the number of lines on the system * max number of times the TTS is used during the call.

vbs_X_Y.wav files store the VBScript that was ran.
X is the "LineID" of the line and Y is the VBScript module counter during the call.
There should be no more of these "vbs" files then the number of lines on the system * max number of times the VBScript module is used during the call.
These files will only be created if SaveToFile option has been enabled in section [moduleRunScript] in VG.INI

js_X_Y.wav files store the Java Script that was ran.
X is the "LineID" of the line and Y is the VBScript module counter during the call.
There should be no more of these "js" files then the number of lines on the system * max number of times the JavaScript module is used during the call.
These files will only be created if SaveToFile option has been enabled in section [moduleRunScript] in VG.INI

The older versions of the files are overwritten by newer versions, so there is an upper limit of how many files can be in TEMP directory, and all the TEMP files store data related to last call on system made on that line only.


Action

Instructs VoiceGuide to perform the specified Action.

Syntax

result = object.Action(iLineId, sAction, iParam1, iParam2, iParam3, sParam1, sParam2, sParam3)

Part | Description
result | Returned value
object | VoiceGuide object
iLineId | Identification number of the line with which this function is associated. Set to 0 if not used.
sAction | Action to perform.
iParam1 | Integer parameter 1
iParam2 | Integer parameter 2
iParam3 | Integer parameter 3
sParam1 | String parameter 1
sParam2 | String parameter 2
sParam3 | String parameter 3

Example

set vg = CreateObject("vgServices.CommandLink")
vg.Action $RV_LINEID, "setchannelstate", 0, 0, 0, "outofservice", "", ""
set vg = Nothing


Bridge_Connect

Connects two calls together, allowing callers on the two lines to speak to each other.

Syntax

sResult = object.Bridge_Connect(iLineId1, iLineId2)

or

sResult = object.Bridge_Connect(sChName1, sChName2)

Part | Description
object | Required. VoiceGuide object
iLineId1 | Required. Identification number of the first line
iLineId2 | Required. Identification number of the second line
sChName1 | Required. The name of the first Dialogic channel.
sChName2 | Required. The name of the second Dialogic channel.
sResult | Optional. Empty string if function completed OK, otherwise it will contain the error description.

Notes

This command needs to be issued only once to connect two calls together. It does not matter which of the lines issues the call - both lines will be able to hear and speak to each other.

Examples

Example 1: Using 'Line ID' identifiers

set vg = CreateObject("vgServices.CommandLink")
vg.Bridge_Connect $RV_LINEID, iSecondLineId
vg.Run_ResultReturn $RV_LINEID, "Success"
set vg = Nothing

Example 2: Using Dialogic channel descriptors

set vg = CreateObject("vgServices.CommandLink")
vg.Bridge_Connect "dxxxB1C3", "dxxxB2C1"
vg.Run_ResultReturn $RV_LINEID, "Success"
set vg = Nothing

Example 3: Using Dialogic channel descriptors

set vg = CreateObject("vgServices.CommandLink")
vg.Bridge_Connect("dtiB1T21", "dtiB2T13")
vg.Run_ResultReturn $RV_LINEID, "Success"
set vg = Nothing


Bridge_Disconnect

Disconnects the two lines. Callers on the two lines will no longer be able to speak to each other.

Syntax

sResult = object.Bridge_Disconnect(iLineId1, iLineId2)

or

sResult = object.Bridge_Disconnect(sChName1, sChName2)

Part | Description
object | Required. VoiceGuide object
iLineId1 | Required. Identification number of the first line
iLineId2 | Required. Identification number of the second line
sChName1 | Required. The name of the first Dialogic channel.
sChName2 | Required. The name of the second Dialogic channel.
sResult | Optional. Empty string if function completed OK, otherwise it will contain the error description.

Notes

This command needs to be issued only once to disconnect the two calls. It does not matter which of the lines issues the call - both lines will not be able to hear and speak to each other any more.

Examples

Example 1: Using line ID numbers

set vg = CreateObject("vgServices.CommandLink")
vg.Bridge_Disconnect $RV_LINEID, iSecondLineId
vg.Run_ResultReturn $RV_LINEID, "Success"
set vg = Nothing

Example 2: Using Dialogic channel descriptors (Analog cards)

set vg = CreateObject("vgServices.CommandLink")
vg.Bridge_Disconnect "dxxxB1T3", "dxxxB4T1"
vg.Run_ResultReturn $RV_LINEID, "Success"
set vg = Nothing

Example 3: Using Dialogic channel descriptors (Digital cards)

set vg = CreateObject("vgServices.CommandLink")
vg.Bridge_Disconnect("dtiB1T21", "dtiB2T13")
vg.Run_ResultReturn $RV_LINEID, "Success"
set vg = Nothing


Conf_Add

Add participant to conference room.

Syntax

object.Conf_Add "LineId_InConf", "LineId_New", "PartyType_New", "Options"

Part | Description
object | VoiceGuide object
LineId_InConf | Any current conference participant. LineID can be used, or Dialogic dti or dxxx device name can be used.
LineId_New | New conference participant. LineID can be used, or Dialogic dti or dxxx device name can be used.
PartyType_New | Type of conference connection. Can be: full or monitor or pupil or coach
Options | Extra parameters.

Example

set vg = CreateObject("vgServices.CommandLink")
vg.Conf_Add $RV[conf_owner], $RV_LINEID, "full", ""
set vg = Nothing


Conf_Change

Change participant type.

Syntax

object.Conf_Change "LineId_InConf", "PartyType_New", "Options"

Part | Description
object | VoiceGuide object
LineId_InConf | Any current conference participant. LineID can be used, or Dialogic dti or dxxx device name can be used.
PartyType_New | Type of conference connection that this party is to be changed to. Can be: full or monitor or pupil or coach
Options | Extra parameters.

Example

set vg = CreateObject("vgServices.CommandLink")
vg.Conf_Change $RV[caller4], "full", ""
set vg = Nothing


Conf_Create

Create Conference room.

Syntax

object.Conf_Create "LineId1", "PartyType1", "LineId2", "PartyType2", "LineId3", "PartyType3", "Options"

Part | Description
object | VoiceGuide object
LineId1 | 1st conference participant. LineID can be used, or Dialogic dti or dxxx device name can be used.
PartyType1 | Type of conference connection. Can be: full or monitor or pupil or coach
LineId2 | 2nd conference participant. LineID can be used, or Dialogic dti or dxxx device name can be used.
PartyType2 | Type of conference connection. Can be: full or monitor or pupil or coach
LineId3 | 3rd conference participant. LineID can be used, or Dialogic dti or dxxx device name can be used.
PartyType3 | Type of conference connection. Can be: full or monitor or pupil or coach
Options | Extra Conference Room parameters.

Notes

Additional participants can be added using the Conf_Add command.

Example

Creates a conference room with one participant.

set vg = CreateObject("vgServices.CommandLink")
vg.Conf_Create $RV_LINEID, "full", 0, "", 0, "", ""
set vg = Nothing


Conf_Remove

Remove a participant from a conference room.

Syntax

object.Conf_Remove "LineId_InConf", "Options"

Part | Description
object | VoiceGuide object
LineId_InConf | Any current conference participant. LineID can be used, or Dialogic dti or dxxx device name can be used.
Options | Extra parameters.

Example

set vg = CreateObject("vgServices.CommandLink")
vg.Conf_Remove $RV[caller4], ""
set vg = Nothing


Dialer_MakeCall

Attempts to make a call on one of the available lines. If no lines are available to make the call immediately then an error will be returned.

This function does not save any call details in the OutDialQue database.

Syntax

object.Dialer_MakeCall sPhoneNumber, sLineSelection, sBridgeAfterDialing

Part | Description
object | Required. VoiceGuide object
sPhoneNumber | Required. The telephone number to be called
sLineSelection | Required. If the outbound call may only be made on particular phone lines then these lines should be listed in this setting. If left blank then any available lines will be used. Line IDs may be specified as a comma delimited list of "LineIDs" (eg: 6,7,8) or using XML notation, (eg: <LineId>2</LineId><LineId>3</LineId>) or specified as a comma delimited list of the Dialogic line identifiers ( eg:dxxxB1C2,dxxxB1C3 ).
sBridgeAfterDialing | Required. Line ID, or name of Dialogic channel to bridge the call with after the number has been dialed.
sScriptToRunAfterDialing | Required. Which script is to be started on the line after dialing the number. Leave blank to have the script currently assigned to the line to be started. If none is specified then no script will be used.

Returns

Returns the name of the LineID of line on which the call was made.

Remarks

Please see the VoiceGuide's Help file's section on Auto Dialing for information on the other ways in which outgoing calls can be scheduled in VoiceGuide.

Example 1

Scenario : Dial number 5551234 and after last digit is dialed bridge with call on current line.

set vg = CreateObject("vgServices.CommandLink")
vg.Dialer_MakeCall "0,5551234", "", "$RV_LINEID", ""
vg.Run_ResultReturn $RV_LINEID, "Success"
set vg = Nothing


Dialer_OutDialQueAdd

Adds a new entry to Dialer's OutDialQue database. The call will be made as outgoing lines become available, and the time before the call is made may depend on how many other entries are currently loaded in the OutDialQue database. No return information about when the call will be actually made is provided when this function returns.

If no other entries are in the OutDialQue database and there are outgoing lines available then the call will be made immediately.

Syntax:

object.Dialer_OutDialQueAdd sPhoneNumber, sPhoneNumberPrefix, sActivateTime, sDayTimeStart, sDayTimeStop, sDaysCallAllowed, sLineSelection, sCampaignName, iPriority, sOnAnswerLive, sOnAnswerMachine, sFaxToSend, sOnNotAnswered, sOnRetriesExhausted, iAnswerTimeout, iRetriesLeft, iRetriesDelay, sRV, sCallOptions, sEscalationCalls

Part

Description

object

VoiceGuide object

sPhoneNumber

Thetelephone number to be called

sPhoneNumberPrefix

Optional prefix dialed before the telephone number.

ActivateTime

Date and Time when the call should be made.

In v7 the time can be specified as a string in any locally valid date/time format. This format is recognized worldwide: YYYY-MM-DD HH:NN:SS AM/PM the AM/PM sign can be omitted if using 24-hout time notation. The YMMDDHHNN format can also be used.

In v6 the time can be specified as a number in format YMMDDHHNN.

DayTimeStart

Time of the day before which the call to this number should not be made.

In v7 the time can be specified as a string in any locally valid date/time format. This format is recognized worldwide: HH:NN:SS AM/PM the AM/PM sign can be omitted if using 24-hout time notation. The HHNN format can also be used.

In v6 the time can be specified as a number in format HHNN. eg: 8am would be specified as the number 800. To allow this telephone number to be dialed from midnight onwards set to 0

DayTimeStop

Time of the day after which the call to this number should not be made.

In v7 the time can be specified as a string in any locally valid date/time format. This format is recognized worldwide: HH:NN:SS AM/PM the AM/PM sign can be omitted if using 24-hour time notation. The HHNN format can also be used.

In v6 the time can be specified as a number in format HHNN. eg: 9pm would be specified as the number 2100. To allow this telephone number to be dialed at any time of day set to 0

sDaysCallAllowed

Days of the week when the call can be made. Specify each day using the first two characters of that day eg: to call on weekdays only specify "MoTuWeThFr". If not used (ie: can call on all days) set to empty string ""

sLineSelection

If the outbound call may only be made on particular phone lines then these lines should be listed in this setting. Line IDs may be specified as a comma delimited list of "LineIDs" (eg: 6,7,8 ) or using XML notation, (eg: <LineId>2</LineId><LineId>3</LineId> ) or specified as a comma delimited list of the Dialogic line identifiers (eg:dxxxB1C2,dxxxB1C3 ). If left blank then any available lines will be used.

sCampaignName

Campaign name associated with this call. Used for users own categorizing of calls. Can be left as an empty string.

iPriority

At what priority level the calls should be made. A lower number indicates a higher priority. ie: 1 is the highest priority, then 2, then 3 ... etc. Number of priority levels is unlimited.

sOnAnswerLive

VoiceGuide script to run when the call is answered by a real person.

sOnAnswerMachine

Sound file (or VoiceGuide script) to be played if the call is answered by an answering machine. The sound file will be played after the answering machine's welcome message finishes. If not used set to empty string ""

sFaxToSend

.PDF/.TIF/.TIFF file to send, or VoiceGuide script to be started immediately after dialing. If this setting specified then the sOnAnswerLive and sOnAnswerMachine are effectively ignored, as when sending fax the fax calling tone has to be sent immediately after dialing. If not used set to empty string ""

sOnNotAnswered

.EXE/.COM/.BAT or .VBS (VBScript) to run when the call has not been answered. If not used set to empty string ""

sOnRetriesExhausted

.EXE/.COM/.BAT or .VBS (VBScript) to run when the call has not been answered and there are no more retries left. If not used set to empty string ""

iAnswerTimeout

How many seconds will the Dialer wait for the call to be answered. Default value of 60 will be used if this entry is set to 0

iCallRetriesLeft

How many more times will the Dialer attempt to call this number if the next call is unsuccessful. To only make one call attempt set to 0

iRetriesDelay

How many minutes will the Dialer wait before attempting to call again. If not used set to 0

sRV

Result Variables which will be available to the VoiceGuide script used on this call. If not used set to empty string ""

sCallOptions

XML formatted options string. If not used set to empty string ""

sEscalationCalls

Can be used to specify multiple escalations levels. XML format is used to specify the escalation calls. Please see the VoiceGuide's help file's section on the 'Out Dial' file for details on the XML format used to specify call details. If not used then set to empty string "".

Notes

Version 7 Examples:

Example 1

Straightforward example.

set vg = CreateObject("vgServices.CommandLink")
vg.Dialer_OutDialQueAdd "ext1002@10.1.1.4", "", "2009-11-28 9:00:00 AM", "9:00 AM", "5:00 PM", "", "", "BookingConfirmCampaign", 1, "c:\ConfirmBooking.vgs", "c:\CallBackDetails.wav", "", "c:\ifNotAnswered.vbs", "c:\ifRetriesExhausted.vbs", 90, 2, 30, "[CustomerID]{44563}", "", ""
set vg = Nothing


Line_Hangup

End the call on the specified line.

Syntax

object.Line_Hangup iLineId

Part | Description
object | VoiceGuide object
iLineId | Identification number of the line. If set to 0 then the first device controlled by VoiceGuide will have it's call terminated. If set to -1 al devices controlled by VoiceGuide will have the calls terminated.

Notes

There must be an incoming call on the line.

Example

set vg = CreateObject("vgServices.CommandLink")
vg.Line_Hangup $RV_LINEID
set vg = Nothing


Line_Pickup

Answer an incoming call and run VoiceGuide script.

Syntax

object.Line_Pickup iLineId, sVgScriptToRun

Part | Description
object | Required. VoiceGuide object
iLineId | Required. Identification number of the line. If set to 0 then the first device controlled by VoiceGuide will answer the call.
sVgScriptToRun | Required. VG Script to run after answering call

Notes

There must be an incoming call on the line.

Example

set vg = CreateObject("vgServices.CommandLink")
vg.Line_Pickup $RV_LINEID, "C:\Scripts\CallRec\RecCall1.vgs"
vg.Run_ResultReturn $RV_LINEID, "Success"
set vg = Nothing


Play_Start

Plays a sound file on the specified line.

Syntax

object.Play_Start iLineId, sSoundFiles

Part | Description
object | VoiceGuide object
iLineId | Identification number of the line
sSoundFiles | The sound file to be played. Multiple sound files can be specified, separated by commas.

Notes

There must be an active call on the line. If any other sound files are being played or recorded on the line at the time they are stopped and the new file is played.

Example

set vg = CreateObject("vgServices.CommandLink")
vg.Play_Start $RV_LINEID, "c:\confirm.wav"
vg.Run_ResultReturn $RV_LINEID, "Success"
set vg = Nothing


Play_Stop

Stop playing a sound file on the specified line.

Syntax

object.Play_Stop iLineId

Part | Description
object | VoiceGuide object
iLineId | Identification number of the line

Notes

There must be an active call on the line.

Example

set vg = CreateObject("vgServices.CommandLink")
vg.Play_Stop $RV_LINEID
vg.Run_ResultReturn $RV_LINEID, "Success"
set vg = Nothing


Record_Stop

Stop recording the sound file on the specified line.

Syntax

object.Record_Stop iLineId

Part | Description
object | VoiceGuide object
iLineId | Identification number of the line

Notes

There must be an active call on the line.

Example

set vg = CreateObject("vgServices.CommandLink")
vg.Record_Stop $RV_LINEID
vg.Run_ResultReturn $RV_LINEID, "Success"
set vg = Nothing


Record_Start

Start Recording the sound on the specified line.

Syntax

object.Record_Start iLineId, sSoundFile, iPlayBeep

Part | Description
object | VoiceGuide object
iLineId | Identification number of the line
sSoundFile | The filename of the sound file to be recorded
iPlayBeep | 1 if a 'beep' is to be played before recording, 0 is no 'beep' is to be played

Notes

There must be an active call on the line. If any other sound files are being played or recorded on the line at the time they are stopped and the new file is recorded.

Example

set vg = CreateObject("vgServices.CommandLink")
vg.Record_Start $RV_LINEID, "c:\newfile.wav", 1
vg.Run_ResultReturn $RV_LINEID, "Success"
set vg = Nothing


Record_2Lines_Start

Start Recording the sound from two sources into the specified file. Can be used to record:

  • Both sides of a bridged/conferenced call, or
  • Caller's interaction with the IVR

    • Can also record each side of the call into separate files. Those separate files can then be used to create a trasncription of the call that identifies what each party said.

    Syntax

    object.Record_2Lines_Start iLineIdRec, iLineId1, iLineId2, sSoundFile, sOptions

    Part | Description
object | VoiceGuide object
iLineIdRec | LineID or device name of the line handling the recording process.
iLineId1 | LineID or device name of the first line to be recorded
iLineId2 | Identification number of the second line to be recorded
sSoundFile | Filename of the created sound file
sOptions | Options

    Options

    play_beep : Play a beep tone when recording

    ab_split : Make separate 'A' side and 'B' side recordings as well as the main recording.

    stt_after_record : Make separate 'A' side and 'B' side recordings as well as the main recording.

    Note:

    In the examples below the predefined vgo object is used, instead of creating the "vgServices.CommandLink" object.

    Example : Record a bridged call between two parties.

    vgo.Record_2Lines_Start $RV_LINEID, $RV_LINEID, $RV[Conf_LineId_2], "c:\recfile.wav", ""

    Example : Record caller's interaction with the IVR. Everything caller says/presses and everything the IVR plays will be recorded.

    A "Pool" of voice resources must be set up in order to use this functionality. One "Pool" voice resource is used for this call.

    vgo.Record_2Lines_Start $RV_LINEID, $RV_LINEID, $RV_LINEID,, "c:\recfile.wav", ""

    Example : Record a bridged call into the 3 separate files: Main, A-Side, B-Side.

    A "Pool" of voice resources must be set up in order to use this functionality. Two "Pool" voice resource are used for this call.

    vgo.Record_2Lines_Start $RV_LINEID, $RV_LINEID, $RV[Conf_LineId_2], "c:\newfile.wav", "ab_split"

    Note : To create a "Pool" of voice resources the <Pools> section would need to be placed inside the node of the Config.xml file.
    Voice devices then must be allocated to the pool. Voice devices allocated to the pool cannot be assigned to any line/channel.

    <Pools>
    <Pool_Voice>
    <Device_Voice>dxxxB11C1</Device_Voice>
    <Device_Voice>dxxxB11C2</Device_Voice>
    <Device_Voice>dxxxB11C3</Device_Voice>
    <Device_Voice>dxxxB11C4</Device_Voice>
    <Device_Voice>dxxxB12C1</Device_Voice>
    <Device_Voice>dxxxB12C2</Device_Voice>
    <Device_Voice>dxxxB12C3</Device_Voice>
    <Device_Voice>dxxxB12C4</Device_Voice>
    </Pool_Voice>
    </Pools>


Run_ResultReturn

Returns information from the called Program or script back to VoiceGuide - indicating what path VoiceGuide should take next from the "Run Program" or "Run VBScript" modules.

Syntax

object.Run_ResultReturn iLineId, sResult

Part | Description
object | VoiceGuide object
iLineId | Identification number of the line
sResult | Result returned to VoiceGuide. Can be "success", "fail", "true", "false" or a string of Result Variables. If set to empty string then the Fail path will be taken

Notes

Used to return results if VoiceGuide is currently awaiting results from a called Program or Script.

If a list of $RVs is returned then a Success path will be taken.

When used in the Run VBScript modules: the jump to next module is taken immediately when Run_ResultReturn is called, so Run_ResultReturn usually should be the last function in the script (before 'set vg = Nothing')

Example 1

set vg = CreateObject("vgServices.CommandLink")
vg.Run_ResultReturn $RV_LINEID, "Success"
set vg = Nothing

Example 2

set vg = CreateObject("vgServices.CommandLink")
vg.Run_ResultReturn $RV_LINEID, "[MarketDow]{9,321}[MarketNasdaq]{1,702}[MarketSP500]{990}"
set vg = Nothing


RvGet

Returns value of the specified Result Variable.

Syntax

sValue = object.RvGet(iLineId, sRv)

Part | Description
object | VoiceGuide object
iLineId | Identification number of the line
sRv | Result Variable who's value is to be returned. The leading dollar sign can be omitted. eg. in case of $RV[GetCardDetails] just the RV[GetCardDetails] can be specified, and in case of a system RV like $RV_CALLLENGTH just the RV_CALLLENGTH can be specified. Omitting the dollar sign is necessary if RvGet() is used from within VoiceGuide, as any fully specified RVs will be replaced with their value before the script is ran.
sValue | Value of the specified Result Variable. If this Result Variable is not currently defined on the line then an empty string is returned.

Notes

Result Variables are reset at the beginning of a new call. Hence they are available for querying after the call has finished, but before a new call has begun on the same line.

RvGet() should only really be used from VoiceGuide's VB Script if that VB script polls for a value of a particular Result Variable in a loop. If the value of the Result Variable is not expected to change during the running of the script then the actual Result Variable should be used directly in the script, without the need of a RvGet function.

Example 1

Running from an external application.

set vg = CreateObject("vgServices.CommandLink")
'see how long the call on line who's LineID is 6 has been going on for:
sReturnValue = vg.RvGet(6, "$RV_CALLLENGTH")
set vg = Nothing
MsgBox sReturnValue

Example 2

Running from an external application.

set vg = CreateObject("vgServices.CommandLink")
'get the RV [GetCardDetails] defined on LineID 6:
sReturnValue = vg.RvGet(6, "$RV[GetCardDetails]")
set vg = Nothing
MsgBox sReturnValue

Example 3

Running from VoiceGuide's VB Script module. Note that the $ has been omitted in the $RV, as if it is included then the $RV will be replaced with value of $RV[GetCardDetails] on the current line, before the VBScript is ran.

Example below will read $RV_CALLLENGTH from a call on another line:

set vg = CreateObject("vgServices.CommandLink")
sReturnValue = vg.RvGet($RV[SecondLineId], "RV_CALLLENGTH")
vg.Run_ResultReturn $RV_LINEID, "[OtherLineCallLength]{" & sReturnValue & "}"
set vg = Nothing

Example 4

Running from VoiceGuide's VB Script module. Note that the $ has been omitted in the $RV, as if it is included then the $RV will be replaced with value of $RV[GetCardDetails] on the current line, before the VBScript is ran.

Example below will read $RV[GetCardDetails] from a call on another line:

set vg = CreateObject("vgServices.CommandLink")
sReturnValue = vg.RvGet($RV[SecondLineId] "RV[GetCardDetails]")
vg.Run_ResultReturn $RV_LINEID, "[OtherLineCardDetails]{" & sReturnValue & "}"
set vg = Nothing


RvGet_All

Returns all the Result Variables current for the specified line.

Syntax

sResult = object.RvGet_All iLineId

Part | Description
object | VoiceGuide object
iLineId | Identification number of the line
sResult | Result Variables currently defined for the selected line.

Notes

Result Variables are reset at the beginning of a new call. Hence they are available for querying after the call has finished, but before a new call has begun on the same line.

Example

set vg = CreateObject("vgServices.CommandLink")
sReturnedData = vg.RvGet_All($RV_LINEID)
vg.Run_ResultReturn $RV_LINEID, sReturnedData
set vg = Nothing


RvGet_AllXml

Returns all the Result Variables current for the specified line in XML-ish format

Syntax

sResult = object.RvGet_AllXml iLineId

Part | Description
object | VoiceGuide object
iLineId | Identification number of the line
sResult | Result Variables currently defined for the selected line. Returned on XML-ish format

Notes

The returned data defines each variable in XML format, but no XML headers or footers are supplied.

Result Variables are reset at the beginning of a new call. Hence they are available for querying after the call has finished, but before a new call has begun on the same line.

Example

set vg = CreateObject("vgServices.CommandLink")
sReturnValue = vg.RvGet_AllXml($RV_LINEID)
vg.Run_ResultReturn $RV_LINEID, "Success"
set vg = Nothing
MsgBox sReturnValue


RvSet

Sets the value of a Result Variable. If the Result Variable does not exit then it is created.

Syntax

object.RvSet iLineId, sRv, vValue

Part | Description
object | VoiceGuide object
iLineId | Identification number of the line
sRv | Name of the Result Variable
vValue | New value of the Result Variable

Notes

Result Variables are reset at the beginning of a new call.

Example

set vg = CreateObject("vgServices.CommandLink")
vg.RvSet $RV_LINEID, "ThisCallersRating", "medium"
vg.Run_ResultReturn $RV_LINEID, "Success"
set vg = Nothing


RvSet_RvList

Creates a number of new Result Variables. If any of the Result Variables already exist then their value will be updated.

Syntax

object.RvSet_RvList iLineId, sRvList

Part | Description
object | VoiceGuide object
iLineId | Identification number of the line
sRvList | Result Variable List. Can be in "[]{}" format, or XML, or JSON

sRvList Formats Supported

[]{} | [RV_Name1]{RV_Value1}[RV_Name2]{RV_Value2}... etc. Multiple Key-Value pairs can be specified using multiple []{} entries.
XML | Valid XML data
JSON | Valid JSON data

Example:

set vg = CreateObject("vgServices.CommandLink")
'sets two Result variables - which will be able to be accessed 'later as $RV[CallersRating] and $RV[CallersPreference]
vg.RvSet_RvList $RV_LINEID, "[MembershipLevel]{Silver}[Balance]{370.45}"
vg.Run_ResultReturn $RV_LINEID, "Success"
set vg = Nothing

Then the following Result Variables will be created:

$RV[MembershipLevel] will hold a value of: "Silver"
$RV[Balance] will hold a value of: "370.45"

Example:

If this JSON input is supplied in sRvList parameter:

{
"name" : "Alice Smith",
"location" : "245 Main St"
"roster" :
[
{
"weekday" : "Monday",
"date" : "2023-05-22",
"start" : "14:00",
"end" : "22:00"
},
{
"weekday" : "Tuesday",
"date" : "2023-05-23",
"start" : "08:00",
"end" : "16:00"
},
{
"weekday" : "Wednsday",
"date" : "2023-05-24",
"start" : "08:00",
"end" : "12:00"
}
]
}

Then the following Result Variables will be created:

$RV[name] will hold a value of: "Alice Smith"
$RV[location] will hold a value of: "245 Main St"
$RV[roster_1_weekday] will hold a value of: "Monday"
$RV[roster_1_date] will hold a value of: "2023-05-22"
$RV[roster_1_start] will hold a value of: "14:00"
$RV[roster_1_end] will hold a value of: "22:00"
$RV[roster_2_weekday] will hold a value of: "Tuesday"
$RV[roster_2_date] will hold a value of: "2023-05-23"
$RV[roster_2_start] will hold a value of: "08:00"
$RV[roster_2_end] will hold a value of: "16:00"
$RV[roster_3_weekday] will hold a value of: "Wednsday"
$RV[roster_3_date] will hold a value of: "2023-05-24"
$RV[roster_3_start] will hold a value of: "08:00"
$RV[roster_3_end] will hold a value of: "12:00"

JSON input uses fewer tags to describe data, and thus usually results in shorter $RV names being generated for similar data.
Compare $RVs created from JSON input with $RVs created from XML input below.

Example:

If this XML input is supplied in sRvList parameter:

<employee>
<name>Alice Smith</name>
<location>245 Main St</location>
<roster>
<job>
<weekday>Monday</weekday>
<date>2023-05-22</date>
<start>14:00</start>
<end>22:00</end>
</job>
<job>
<weekday>Tuesday</weekday>
<date>2023-05-23</date>
<start>08:00</start>
<end>16:00</end>
</job>
<job>
<weekday>Wednsday</weekday>
<date>2023-05-24</date>
<start>08:00</start>
<end>12:00</end>
</job>
</roster>
</employee>

Then the following Result Variables will be created:

$RV[employee_name] will hold a value of: "Alice Smith"
$RV[employee_location] will hold a value of: "245 Main St"
$RV[employee_roster_job_1_weekday] will hold a value of: "Monday"
$RV[employee_roster_job_1_date] will hold a value of: "2023-05-22"
$RV[employee_roster_job_1_start] will hold a value of: "14:00"
$RV[employee_roster_job_1_end] will hold a value of: "22:00"
$RV[employee_roster_job_2_weekday] will hold a value of: "Tuesday"
$RV[employee_roster_job_2_date] will hold a value of: "2023-05-23"
$RV[employee_roster_job_2_start] will hold a value of: "08:00"
$RV[employee_roster_job_2_end] will hold a value of: "16:00"
$RV[employee_roster_job_3_weekday] will hold a value of: "Wednsday"
$RV[employee_roster_job_3_date] will hold a value of: "2023-05-24"
$RV[employee_roster_job_3_start] will hold a value of: "08:00"
$RV[employee_roster_job_3_end] will hold a value of: "12:00"

Example:

Here is an example VBScript that reads in contents of file and passes the file's contents to the RvSet_RvList function:

set fso = CreateObject("Scripting.FileSystemObject")
set fileHandle = fso.OpenTextFile("c:\mydir\data.json")
sFileContents = fileHandle.ReadAll
set fileHandle = Nothing
set fso = Nothing

set vg = CreateObject("vgServices.CommandLink")
vg.RvSet_RvList $RV_LINEID, sFileContents
vg.Run_ResultReturn $RV_LINEID, "Success"
set vg = Nothing


Script_Gosub

Call a VoiceGuide subscript, specifying the script filename and start module. Specify which script and module should be ran once the subscript returns.

Syntax

object.Script_Gosub iLineId, sDestScript, sDestModule, sRvList, sReturnScript, sReturnModule

Part | Description
object | VoiceGuide object
iLineId | Identification number of the line
sDestScript | The filename of the VoiceGuide script where the subscript is located. If the subscript is in the same VoiceGuide script as the calling module then this entry can be left blank.
sDestModule | Name of the starting module.
sRvList | List of Result Variables and their values. Each RV-Value pair is in format [Name]{Value} a number of RV-Value pairs can be specified one after another.
sReturnScript | The filename of the VoiceGuide script where the system should return to after finishing the subscript. If the subscript is in the same VoiceGuide script as the calling module then this entry can be left blank.
sReturnModule | Name of the return module.

Notes

If the module names are blank then the default starting modules in the script are used.

When used in the Run VBScript modules: the jump to next module is made immediately when Script_Gosub is called, so Script_Gosub usually should be the last function in the script (before 'set vg = Nothing')

Example 1

set vg = CreateObject("vgServices.CommandLink")
'Gosub to a new script and return to module VmMmMenuPlay in the current script
vg.Script_Gosub $RV_LINEID, "vmAdmin.vgs", "", "", "", ""
set vg = Nothing

Example 2

set vg = CreateObject("vgServices.CommandLink")
'Gosub to a new scriopt and return to module VmMmMenuPlay in the current script
vg.Script_Gosub $RV_LINEID, "vmAdmin.vgs", "VmAdminWelcMsgMenuPlay", "", "", "VmMmMenuPlay"
set vg = Nothing


Script_Goto

Jump to new VoiceGuide script and/or module.

Syntax

object.Script_Goto iLineId, sDestScript, sDestModule, sRvList

Part | Description
object | VoiceGuide object
iLineId | Identification number of the line
sDestScript | The filename of the VoiceGuide script where the module subscript is located. If the subscript is in the same VoiceGuide script as the calling module then this entry can be left blank.
sDestModule | Name of the starting module. If left blank then the script's default starting module is used.
sRvList | List of Result Variables and their values. Each RV-Value pair is in format [Name]{Value} a number of RV-Value pairs can be specified one after another.

Notes

If the module names are blank then the default starting modules in the script are used.

When used in the Run VBScript modules: the jump to next module is made immediately when Script_Goto is called, so Script_Goto usually should be the last function in the script (before 'set vg = Nothing')

Example

set vg = CreateObject("vgServices.CommandLink")
vg.Script_Goto $RV_LINEID, "GetPayment.vgs", "", ""
set vg = Nothing


Script_Return

Returns control of the call to the calling script.

Syntax

object.Script_Return iLineId, sRvList

Part | Description
object | VoiceGuide object
iLineId | Identification number of the line
sRvList | List of Result Variables and their values. Each RV-Value pair is in format [Name]{Value} a number of RV-Value pairs can be specified one after another.

Notes

Effectively pops the return destination script/module of the call stack and start execution at that script/module.

When used in the Run VBScript modules: the jump to next module is made immediately when Script_Return is called, so Script_Return usually should be the last function in the script (before 'set vg = Nothing')

Example 1

set vg = CreateObject("vgServices.CommandLink")
vg.Script_Return $RV_LINEID, ""
set vg = Nothing

Example 2

set vg = CreateObject("vgServices.CommandLink")
vg.Script_Return $RV_LINEID, "[PersonalDataVerified]{True}"
set vg = Nothing


Serial_Tx

Transmits data over a serial port.

Syntax

object.Serial_Tx iSerialPortNumber, sTx

Part | Description
object | VoiceGuide object
iSerialPortNumber | Serial port number.
sTx | String to be sent on the Serial port.

Notes

Default parameters for the serial connection can be set in VG.INI file, using section [Serial]:

[Serial]
CommPort=1
Handshaking=0
InBufferSize=1024
InputMode=1
NullDiscard=False
ParityReplace=?
RThreshold=1
RTSEnable=False
Settings=9600,N,8,1

Calls to Serial_Tx function will then send send the specified data over the Serial port. The Serial port will be opened during the sending of data and closed immediately afterwards.

Example

set vg = CreateObject("vgServices.CommandLink")
vg.Serial_Tx 1, "This is a test sent from VoiceGuide."
set vg = Nothing


Trace

Adds an entry to VoiceGuide's vgEngine trace log.

Syntax

object.Trace iLineId, sLogInfo

Part | Description
object | Required. VoiceGuide object
iLineId | Required. Identification number of the line with which this log entry is associated. Set to 0 if not used.
sLogInfo | Required. Text to be added to vgEngine trace.

Example

set vg = CreateObject("vgServices.CommandLink")
vg.Trace $RV_LINEID, "Hello World!"
set vg = Nothing


Vm_Event

Indicate an event has occurred affecting a particular voicemail box, or an action should be taken affecting a particular voicemail box.

Syntax

object.Vm_Event iLineId, sEvent, sVmbId, sParam1, sParam2, sParam3

Part | Description
object | VoiceGuide object
iLineId | Identification number of the line
sEvent | Event/Action type. Allowed values are: FORWARD, MSG_NEW, MSG_NONEWMSGS, MSG_NOSAVEDMSGS, LOGIN, LOGOUT
sVmbId | The ID of the Voicemail box to which the Event/Action applies.
sParam1 | Event/Action specific parameter. Set to blank if not used.
sParam2 | Event/Action specific parameter. Set to blank if not used.
sParam3 | Event/Action specific parameter. Set to blank if not used.

For examples of use please see the VoiceGuide Scripted Voicemail System script files.


Vm_VmbConfig_Get

Retrieves a property value for a particular voicemail box.

Syntax

sCurrentValue = object.Vm_VmbConfig_Get(sVmbId, sTag)

Part | Description
object | VoiceGuide object
sVmbId | The ID of the Voicemail box who's property is to be retrieved.
sTag | The name of the property to be retrieved.
sCurrentValue | The current value of the property.

Notes

Returns the information stored for the specified property. The actual information returned will be the contents in the VmBoxList.xml file between <sTag> and </sTag> for the selected Voicemail Box.

Example

set vg = CreateObject("vgServices.CommandLink")
sPin = vg.Vm_VmbConfig_Get("0001" "Pin")
vg.Run_ResultReturn $RV_LINEID, "[ThisUserPin]{" & sPin & "}"
set vg = Nothing


Vm_VmbConfig_Set

Set a property for a particular voicemail box.

Syntax

object.Vm_VmbConfig_Set sVmbId, sTag, sNewValue

Part | Description
object | VoiceGuide object
sVmbId | The ID of the Voicemail box who's property is to be set.
sTag | The title of the property to be set.
sNewValue | The new property value.

Notes

Sets the current value of the specified property. The new Value will be inserted in the VmBoxList.xml file between <sTag> and </sTag> for the selected Voicemail Box.

Example

set vg = CreateObject("vgServices.CommandLink")
vg.Vm_VmbConfig_Set "0001", "Pin", "1234"
vg.Run_ResultReturn $RV_LINEID, "Success"
set vg = Nothing


Inband Signaling

Many PBXs and Switches can send information about the call using Inband Signaling. This information may contain CallerID, number dialed, extension from which the call was transferred, reason for the transfer etc. Different PBXs and Switches support provision of different information via Inband Signaling.

VoiceGuide can be configured to detect Inband Signaling sent by the PBX at the beginning of the call and make this information available to scripts as Result Variables.

Inband Signaling is sent using a series of DTMF tones immediately after the call is answered. It is only sent to the recipient of the call and it does not matter after how many rings the call is answered - the signaling tones are sent immediately after call answer.

It is easy to check if Inband Signaling is sent on the line: place an extension headset against your ear and keep the 'handset on hook' switch depressed so that that handset can accept calls, then make a call to that extension and when the call arrives lift the hand off the 'handset on hook' switch - if there is any Inband Signaling sent you will hear it then a quick series of DTMF tones.
(You will not be able to hear the tones usually if you just normally pick up the handset as the playing of the tones would have finished by the time you raise the handset to your ear)

To capture what tones are being sent on the line just set up a VoiceGuide script whose first module is a "Get Numbers" type module - that module will then capture the sent digits and what it captures will be stored in the Log File.

To enable inband signaling detection and interpretation in VoiceGuide an “Inband Signaling Definition File” needs to be created. This file defines what Inband Signaling VoiceGuide can expect to receive form the PBX and how it should be interpreted.

Creating an “Inband Signaling Definition File”

Creating an Inband Signaling definition files requires precise knowledge of what PBX will send in various circumstances.

Inband Signaling detection is only supported in the Enterprise (and Evaluation) version of VoiceGuide.

An example file is shown below. Comments within the file explain the purpose of the “Pattern” and “RV” entries.

Pattern=[*][*][*]???????????[*][1-4]
RV=Inband_TOC,4,1,Inband_Calling,5,5,Inband_Called,10,5,Inband_Info,17,1
Pattern=[*][*][*]??????[*][1-4]
RV=Inband_TOC,4,1,Inband_Calling,5,5,Inband_Called,10,0,Inband_Info,11,1

When using the file above the following Result Variables will be available to the script:
$RV[Inband_TOC] | 4the character sent
$RV[Inband_Calling] | 5 characters starting from position 5
$RV[Inband_Called] | In case of forwarded call the 5 characters starting from position 10, or an empty string case of a direct call
$RV[Inband_Info] | Last character of the data string.

The “Pattern” entries are defined according to the rules Visual Basic for Applications LIKE operator pattern definition, major part of which is quoted below:

Selecting which “Inband Signaling Definition File” to use

To indicate that a particular “Inband Signaling Definition File” is to be used by the system the full path to the file must the specified in the VG.INI file, section [PBX], entry InbandSignalConfig. Eg:

[PBX]
InbandSignalConfig=InbandSignaling_SiemensHiPath3000_v1.2.txt

Inband Signaling Call Answering and Timings

If Inband Signaling is defined, VoiceGuide will wait for up to 2 seconds for DTMF tones to arrive. Maximum time between successive DTMF tones is 0.5 seconds. Once DTMF signaling stops VoiceGuide will perform the pattern matching and start running the script

If Inband Signaling does not arrive within 2 seconds of answering the call VoiceGuide will start running the script and the Result variables which would have been defined as a result of any pattern matches will be left undefined.

The 2 sec timeouts were found to be suitable for most systems, but it can be changed using the settings in VG.INI file. To change that setting please see the [PBX] section, entry InbandSignalWait.

Please contact support@voiceguide.com if an interdigit timeout other then 0.5 seconds is needed on your system

Signal Patterns Definition

The pattern-matching features allow you to use wildcard characters, character lists, or character ranges, in any combination, to match strings. The following table shows the characters allowed in pattern and what they match:
Characters in pattern | Matches in string
? | Any single character.
* | Zero or more characters.
# | Any single digit (0–9).
[charlist] | Any single character in charlist.
[!charlist] | Any single character not in charlist.

A group of one or more characters (charlist) enclosed in brackets ([ ]) can be used to match any single character in string and can include almost any character code, including digits.

Note To match the special characters left bracket ([), question mark (?), number sign (#), and asterisk (*), enclose them in brackets. The right bracket (]) can't be used within a group to match itself, but it can be used outside a group as an individual character.

By using a hyphen (–) to separate the upper and lower bounds of the range, charlist can specify a range of characters. For example, [A-Z] results in a match if the corresponding character position in string contains any uppercase letters in the range A–Z. Multiple ranges are included within the brackets without delimiters.

Other important rules for pattern matching include the following:

  • An exclamation point (!) at the beginning of charlist means that a match is made if any character except the characters in charlist is found in string. When used outside brackets, the exclamation point matches itself.
  • A hyphen (–) can appear either at the beginning (after an exclamation point if one is used) or at the end of charlist to match itself. In any other location, the hyphen is used to identify a range of characters.
  • When a range of characters is specified, they must appear in ascending sort order (from lowest to highest). [A-Z] is a valid pattern, but [Z-A] is not.
  • The character sequence [] is considered a zero-length string ("").

Signal Patterns Examples

In the example file shown above the pattern:

[*][*][*]???????????[*][1-4]

specifies a string which has a total length of 16 characters, beginning with “***” followed by 11 characters, followed by another “*” and then followed by a digit between 1 and 4.

The pattern of:

[*][*][*]??????[*][1-4]

specifies a string which has a total length of 11 characters, beginning with “***” followed by 6 characters, followed by another “*” and then followed by a digit between 1 and 4.

In the pattern definition we need to enclose “*” characters in square brackets, otherwise they would be interpreted as a special “Zero or more characters.” Indicator. The section Signal Patterns Definitions above has more information on how the various patterns can be defined.


Copyright, Legal Stuff & Disclaimer

VoiceGuide is Copyrighted by Katalina Technologies Pty. Ltd.

VoiceGuide is a Registered Trademark owned by Katalina Technologies Pty. Ltd.

The software is provided AS IS without warranty of any kind, whether express or implied, including, without limitation, warranties of merchantability or fitness for a particular purpose. The use of this software is entirely at the users own risk, and under the users own responsibility. Katalina Technologies shall have no liability to customer or any third party for any claim, loss or damage of any kind whether direct or indirect, including but not limited to lost profits, punitive, incidental, consequential or special damages, arising out of or in connection with the use or performance of the software and accompanying documentation.

An unlicensed evaluation copy of VoiceGuide may be used for evaluation purposes only. This covers every application component of VoiceGuide including but not limited to VoiceGuide Engine, VoiceGuide Script Designer and VoiceGuide Dialer.

No part of the VoiceGuide distribution package may be modified or distributed separately without express permission of Katalina Technologies Pty. Ltd.

Parties found breaching above conditions will be prosecuted to the maximum extent possible under the law.


VoiceGuide Applications

Some of the more popular applications are :

Surveys
List of people can be dialed and an asked to respond to questions.

Fax Back systems
Callers can select what information they are interested in, and the system will fax the selected documents to the fax number of caller's choice.

Data Entry
Callers can report various information to the system, and the data can be saved in a file, collated in a database, emailed or forwarded to other programs for further processing.

Information Lines
A series of sound files can be played to the caller, with the caller selecting what they want to hear next. Information can be retrieved from Databases and spoken to the caller. eg: In a 'Pricing and Availability' type application callers can be informed of the current price and amount in stock of an item they selected.

Problem Hotlines
A problem report can be accepted from an incoming call and a list of people alerted automatically of the problem. If some people are cannot be contacted within a certain time, the problem is escalated to their supervisors.

Auto Attendants
Callers select which department they wish to speak with, or which person they would like to contact directly. The system will then transfer the call directly to the selected extension.

Voicemail Systems
Fully featured voicemail system is supplied with VoiceGuide, and an unlimited number of voicemail boxes are allowed. New Voicemail messages can be forwarded to another phone or by email, and the owner can also be alerted by pager.


Admin_TraceLogAdd

NOTE: Deprecated. Please use Trace function instead.

Adds a log entry to VoiceGuide's vgEngine trace log.

Syntax

object.Admin_TraceLogAdd iLineId, iLogLevel, sLogInfo

Part | Description
object | Required. VoiceGuide object
iLineId | Required. Identification number of the line with which this log entry is associated. Set to 0 if not used.
iLogLevel | Required. Compared against VoiceGuide's trace level setting to determine if the log entry should be printed. Set to 0 for the trace log entry to be always printed.
sLogInfo | Required. the information to be printed

Notes

VoiceGuide's trace level is set using VG.INI file, section "TraceLog", entry "TraceLevel"

Example

set vg = CreateObject("vgServices.CommandLink")
vg.Admin_TraceLogAdd 0, 0, "This trace was printed from an external VB Script"
vg.Run_ResultReturn $RV_LINEID, "Success"
set vg = Nothing


VoiceGuide Outbound IVR Dialer

The Dialer add-on enables VoiceGuide to dial out and play a message or run a VoiceGuide script once the call has been answered. Outbound calls can be scheduled using any of these methods:

  • Dial List Loader program.
  • Send Phone Message module in a VoiceGuide script.
  • Using VoiceGuide WCF/COM interface function Dialer_OutDialQueAdd.
  • Saving list of numbers to be called in an 'Out Dial' file, which VoiceGuide reads in automatically.
  • Adding dial entries directly to the OutDialQue database.

When using Dialogic cards the system can detect whether a real person or an answering machine has answered the call. Different messages or scripts can be specified in either case. When an answering machine answers the call the message or script will start after the welcoming message stops playing.

When using a voice modem to dial out a prompt message needs to be specified which will be played in a loop until the person who answers the call presses key on their telephone keypad. This is because a voice modem cannot detect when a call is answered. Only after the called person presses the key on their telephone keypad will the message or script be played. If an answering machine answers calls placed using voice modems it will end up recording the prompt message being played in a loop.

Outbound Call Loader

Allows easy scheduling of calls.

Outgoing Call parameters set using the Dial List Loader:

Phone numbers

The telephone numbers to be dialed can be typed directly into this text box. The numbers should be entered one per line.
A range of numbers can be specified by placing an "X" in the number location which covers the desired range. eg: 5627XXX results in a thousand telephone numbers: 5627000 to 5627999 to be called. Typing 56274XX would result in a hundred numbers being called: 5627400 to 5627499.

Prefix

The number to add to before each of the numbers provided in the ‘Phone numbers’ text box or in the ‘list file’. This entry is used if a certain number has to be dialed to reach an outgoing line or if using an override code when dialing.

Phone Numbers File

Allows to select the text file from which to import the list of numbers to call. The file should contain each number on its own new line.

A range of numbers can be specified by placing an "X" in the number location which covers the desired range. eg: by typing 5627XXX we indicate that a thousand telephone numbers: 5627000 to 5627999 should be called. Typing 56274XX would result in a hundred numbers being called: 5627400 to 5627499.

Live Person Answer

What VoiceGuide script will be started or what sound file will be played when the call is answered by a real person. Specifying the starting module can be made using notation: Script Filename|Module Title

Answering Machine Answer

When the call is answered by an answering machine VoiceGuide will play this message/script. Answering machines can only be detected if a Dialogic card is used.

If an answering machine is detected VoiceGuide will wait until the answering machine's welcome message finishes before starting the script/sound file specified here.

RETRY : call will be attempted again if an answering machine is encountered (up to the maximum number of redials allowed).

IGNORE The script/file specified when the live person answers will be used.

DISABLE Detection of when the call has been answered is disabled.

Answering Machine detection relies on the Dialogic card listening to the first word spoken by the caller, and determining based on what it heard whether that word sounded like it was spoken by a live person answering the call, or whether that word sounded like it was spoken by an answering machine. This means that VoiceGuide needs to wait until he Dialogic card hears the word being spoken and then advises VoiceGuide of it's decision. This incurs a delay of about a second after the first word is spoken before VoiceGuide is advised whether to play the "real person" or the "answering machine" script.

If the call is made on T1/E1 ISDN lines (and usually VoIP) VoiceGuide is able to detect the exact time at which the call has been answered. If the "Answering Machine" message option is not set then VoiceGuide will commence playing of the "Live person answer" script immediately when then handset is picked up.

Fax to Send

If a fax is specified then VoiceGuide will send the specified fax on this call. This can be a .PDF or a .TIFF file. Note that when this field is specified VoiceGuide will start playing the Fax Calling Tone immediately after the number is dialed and only a fax send will be attempted during the call.
Do Not Call List (DNC List)

File containing a list of telephone numbers which will never be called by VoiceGuide, even if they were inadvertently specified in the "Phone numbers to be called" file or text box. The file must contain each number on a separate line.

Result Variables

Result Variables can be supplied to be used by the scripts which are ran once outgoing call is answered.
The format of this field is [RvName]{RvValue}. Multiple Result Variables can be specified by listing as many name-value pairs as needed. eg: [rv1]{val1}[rv2]{val2}[rv3]{val3}

Call Options

The Options field can be used for other special settings. Eg. to specify the outgoing CallerID used for the call. Including this setting: <CallerId>5551234</CallerId> would result in CallerId to be set to 5551234 on outgoing calls (lines used must support the setting of outgoing CallerID). For information on configuring ISDN lines to send out the CallerID Name as well please see: http://voiceguide.com/forums/index.php?showtopic=6079

Result Files

In addtion to CDR Logs and Script Logs, outcome of all outgoing calls is saved in VoiceGuide's \data\ subdirectory.

OutDial_Contacted_Human.txt
List of calls answered by a real person.

OutDial_Contacted_AM.txt
List of calls answered by an answering machine.

OutDial_Contacted_Fax.txt
List of calls answered by a fax machine person.

OutDial_Uncontactable_NoAnswer.txt
List of calls which were not answered and rung out awaiting answer.

OutDial_Uncontactable_Busy.txt
List of calls which were not answered as the busy tone was heard.

OutDial_Uncontactable_OnDontDialList.txt
List of calls which were not made as the telephone number was on the supplied "Do Not Call list".

OutDial_Uncontactable_NoDialer.txt
List of calls which were not dialed as the Dialer option is not enabled.

OutDial_SIT_Reorder.txt
List of calls for which the Special Information Tone (Reorder) was played by the phone company.

OutDial_SIT_NoCircuit.txt
List of calls for which the Special Information Tone (No Circuit) was played by the phone company.

OutDial_SIT_CustIrReg.txt
List of calls for which the Special Information Tone (CustIrReg) was played by the phone company.

OutDial_SIT_Unknown.txt
List of calls for which an unknown Special Information Tone was played by the phone company.

Out Dial file

An 'OutDial' file can also be used to add new telephone numbers to be dialed by VoiceGuide. When the file is created, VoiceGuide will read in the file and delete it after reading it's contents.

‘OutDial’ file can be created in VoiceGuide's \data\ subdirectory, or in directory specified in VG.INI, section [VGDialer], entry: OutDialFilePath

The filename must begin with "OutDial" and have the ".xml" suffix.
Eg: OutDial_080521175323a.xml

Multiple 'OutDial' files can be created at the same time, and will be read in by VoiceGuide within about a second of them being created. All outdial files created within less then a few seconds of each other should have unique names - to avoid the possibility of a file being overwritten by newer version while it is still being read in by VoiceGuide.

It is advisable to first create the file under a different name - that doe not have the 'OutDial' prefix in its filename, and after the file writing/copying is completed then rename the file to the OutDial*.xml format. This would ensure that VoiceGuide would not attempt to open the file while it's contents are still being written to by another process.

Out Dial Input file

The syntax of the OutDial file as used by VoiceGuide v7 is:

<OutDialEntry>
<PhoneNumber>sPhoneNumber</PhoneNumber>
<PhoneNumberPrefix>sPhoneNumberPrefix</PhoneNumberPrefix>
<ActivateTime>sCallTime</ActivateTime>
<DayTimeStart>sDayTimeStart</DayTimeStart>
<DayTimeStop>sDayTimeStop</DayTimeStop>
<DaysCallAllowed>sDaysCallAllowed</DaysCallAllowed>
<PortSelection>sPortSelection</PortSelection>
<CampaignName>sCampaignName</CampaignName>
<Priority>iPriority</Priority>
<OnAnswerLive>sOnAnswerLive</OnAnswerLive>
<OnAnswerMachine>sOnAnswerMachine</OnAnswerMachine>
<OnAnswerFax>sOnAnswerFax</OnAnswerFax>
<OnNotAnswered>sOnNotAnswered</OnNotAnswered>
<OnRetriesExhausted>sOnRetriesExhausted</OnRetriesExhausted>
<AnswerTimeout>iAnswerTimeout</AnswerTimeout>
<RetriesLeft>iRetriesLeft</RetriesLeft>
<RetriesDelay>iRetriesDelay</RetriesDelay>
<RV>sRV</RV>
<CallOptions>sCallOptions</CallOptions>
<Escalation>
sEscalation
</Escalation>
</OutDialEntry>

Where:

Phone number to be dialed.

Prefix to the phone number to be dialed. Prepended to the phone number before dialing.

Time the call is to be made. Format is YYYY-MM-DD HH:NN:SS If this setting is blank or is omitted then the call will commence immediately. Format may also be: Now+X where X is the number of minutes from the current time that the call should be scheduled for.

Time of the day from which this number can be dialed. Format is: HHNN and the time is specified in 24-hour format. eg: 0800 would mean: this number may be called after 8am. If this setting is blank or is omitted then the call will be allowed to be made from midnight onwards.

Time of the day after which this number can no longer be dialed. Format is: HHNN and the time is specified in 24-hour format.
eg: 2100 would mean: do not dial this number after 9pm. If this setting is blank or is omitted then the call will be allowed to be made right up to midnight.

On which days of the week can this number be dialed. Format is : [Mo][Tu][We][Th][Fr][Sa][Su] eg: MoWe would mean: this number may only be called on Mondays and Wednesdays. If this setting is blank or is omitted then the call will be allowed to be made on every day of the week.

If the outbound call may only be made on particular phone lines then the ports to which those lines are attached should be listed in this setting. The ports should be specified as a comma delimited list of physical ports (eg: 1,2,3). If any of the lines are allowed to to be used then this setting should be left blank.
eg: 3,4,5 would indicate that the outgoing call can only be made on third, fourth or fifth port.

User defined name campaign name associated with this call. Used to assist in segregating of outgoing calls based on their porpoise or source etc.

At what priority level the calls should be made. A lower number indicates a higher priority. ie: 1 is the highest priority, then 2 etc etc. Number of priority levels is unlimited.

VoiceGuide script or sound file which will be used when the call is answered by a real person The full path to this script or sound file must be specified. Specifying the starting module can be made using notation: Script Filename|Module Title

VoiceGuide script or sound file which will be used when the call is answered by an answering machine. The full path to this sound file or script must be specified. If this setting is blank or is omitted then the sOnAnswerLive setting will be used.
If the word none is specified, then no file will be played and the call will be hung up. The call will still be considered as having been completed.
If the word retry is specified, then the no file will be played and the call will be hung up, with the call not considered completed - further call attempts will be made.

Fax to send. This can be a .PDF or a .TIFF file. Note that when this field is specified VoiceGuide will start playing the Fax Calling Tone immediately after the number is dialed. The OnAnswerLive and OnAnswerMachine will be ignored as only a fax send will be attempted during the call.

VBScript or .EXE/.COM/.BAT/etc. to run when the outgoing call has not been answered.

VBScript or .EXE/.COM/.BAT/etc. to run when the outgoing call has not been answered and there are no more retries left. This command is ran in addition to the OnNotAnswered command.

How many seconds VoiceGuide will wait for the call to be answered. If this setting is blank or is omitted then the answer timeout will be set to 60 seconds.

How many times VoiceGuide will re-dial the phone number, before abandoning trying to contact this number. If iRetriesLeft is set to 0 then only one call will be made. If this setting is blank or is omitted then a value of 2 will be used. (ie: up to 3 call attempts in total)

How many minutes VoiceGuide will wait between successive attempts (if iCallRetries is set to 1 or more). If this setting is blank or is omitted then a value of 5 will be used.

List of custom Result Variables which can be used by the VoiceGuide script above. The format of this field is [RvName]{RvValue}. Multiple Result variables can be specified by listing as many name-value pairs as needed. eg: [rv1]{val1}[rv2]{val2}[rv3]{val3}

Used for the specifying of custom call options. eg. CallerID to be sent.

Alternate numbers to be dialed if the call has not been answered. Once the number of retries calling sPhoneNumber is exhausted, then then alternative escalation number will be dialed immediately. Format is in <OutDialEntry>...</OutDialEntry> structure format - this allows for multiple escalation numbers to be specified.

Example 1 : Simple message delivery to a single number

Uses :

Any simple message / script delivery.

Scenario: Call a telephone number 5553423, and run script d:\scripts\alarm.vgs when call is answered. Call is to be made immediately. The OutDial file should contain:

<OutDialEntry>
<PhoneNumber>5553423</PhoneNumber>
<OnAnswerLive>d:\scripts\alarm.vgs</OnAnswerLive>
</OutDialEntry>

If the call is not answered then the number will be called up to two more times at 5 minute intervals.

Example 2 : Scheduling a call for a particular time.

Uses :

Wake up calls.
Appointment reminder service.
Any announcements which need to be sent out at a particular time.

Scenario: Call the telephone number 5553328 at 6:30 in the morning on a 12th June 2008 and run the script d:\scripts\todays_specials.vgs - passing to the script Result Variables which that script uses (in this case it will be pricing of the items on special for this customer). If an Answering Machine answers then run a modified version of the script which just plays the prices and leaves contact details (d:\scripts\todays_specials_AM.vgs). The OutDial file should contain:

<OutDialEntry>
<PhoneNumber>5553328</PhoneNumber>
<ActivateTime>2008-06-12 06:30:00</ActivateTime>
<OnAnswerLive>d:\scripts\todays_specials.vgs</OnAnswerLive>
<OnAnswerMachine>d:\scripts\todays_specials_AM.vgs</OnAnswerMachine>
<RV>[ClientID]{123456}[PriceWidget]{125}[PriceDelivery]{7.50}</RV>
</OutDialEntry>

Example 3 : Ensuring call is made during particular days/hours.

Uses :

Surveys.
Distributing information to a large client base.
Whenever making a large number of calls and need to ensure that calls are only made between the hours allowed

Scenario: Call the telephone number 5553328 at between 10am and 6pm on any weekday, and run script d:\scripts\paymentoverdue.vgs - passing to the script Result Variables which that script uses (in this case the customer ID and the amount owing). If an Answering Machine answers then run a modified version of the script which just plays the amount owing and leaves contact details (d:\scripts\paymentoverdue_AM.vgs). The OutDial file should contain:

<OutDialEntry>
<PhoneNumber>5553328</PhoneNumber>
<DayTimeStart>1000</DayTimeStart>
<DayTimeStop>1800</DayTimeStop>
<DaysCallAllowed>MoTuWeThFr</DaysCallAllowed>
<OnAnswerLive>d:\scripts\paymentoverdue.vgs</OnAnswerLive>
<OnAnswerMachine>d:\scripts\paymentoverdue_AM.vgs</OnAnswerMachine>
<RV>[ClientID]{4453566}[AmountOwing]{14325}</RV>
</OutDialEntry>

Specifying the days on which calls can be made and the time range during which the call can be made is useful if a large number of calls are queued and there is a need to ensure that the system will not make the calls on odd days or hours.

When specifying a large number of calls it is usually easier to use the Telephone Number Loader program, rather then specifying all the numbers using the Out Dial file.

Example 4 : Escalated calls

Uses :

Delivering information to on-call staff, with supervisor escalation if calls by main staff not answered.
Follow-me message delivery - where a number of possible contact numbers is given.
Whenever a message needs to be delivered to one of a range of telephone numbers.

Scenario 1: Call the number 5551111 immediately and run the script d:\scripts\alert.vgs - passing to the script Result Variables which that script uses (in this case it will be information on a problem reported by customer). If the number does not answer then wait 5 minutes and try calling it again. If after 3rd call attempt the number still does not answer then try calling 5552222 - again calling up to 3 times at 5 minute intervals. If an answering machine answers the call then start the d:\scripts\alert.vgs script as well (script should be designed to just play the information to caller). If on 3rd call attempt the second number still does not answer then run a VB Script d:\scripts\notanswered.vbs. The OutDial file should contain:

<OutDialEntry>
<PhoneNumber>5551111</PhoneNumber>
<OnAnswerLive>d:\scripts\alert.vgs</OnAnswerLive>
<RetriesLeft>2</RetriesLeft>
<RetriesDelay>5</RetriesDelay>
<RV>[ClientID]{554}[Severity]{2}[ContactTel]{5559743}</RV>
  <Escalation>
    <OutDialEntry>
      <PhoneNumber>5552222</PhoneNumber>
      <OnAnswerLive>d:\scripts\alert.vgs</OnAnswerLive>
      <RetriesLeft>2</RetriesLeft>
      <RetriesDelay>5</RetriesDelay>
      <RV>[ClientID]{554}[Severity]{2}[ContactTel]{5559743}</RV>
      <OnRetriesExhausted>d:\scripts\notanswered.vbs</OnRetriesExhausted>
    </OutDialEntry>
  </Escalation>
</OutDialEntry>

Scenario 2: Message delivery to a Line Person only : Call the number 5551111 immediately and run the script d:\scripts\alert.vgs - passing to the script Result Variables which that script uses (in this case it will be information on a problem reported by customer). If the number cannot be reached or if an answering machine answers the call then immediately call another number instead (5552222) and if that number is not answered by a live person then call a third number (5553333). If a live person could not be reached on any of these numbers then wait 10 minutes and try calling all 3 numbers again. If after the second call attempt to all 3 numbers no live person could be reached then run a VB Script d:\scripts\notanswered.vbs In this scenario it is acceptable to deliver the message to a Line Person only, calls answered by Answering Machines will not be regarded as successful message delivery calls and no message will be left on the answering machine. The OutDial file should contain:

<OutDialEntry>
<PhoneNumber>5551111</PhoneNumber>
<OnAnswerLive>d:\scripts\alert.vgs</OnAnswerLive>
<OnAnswerMachine>retry</OnAnswerMachine>
<RetriesLeft>0</RetriesLeft>
<RV>[ClientID]{554}[Severity]{2}[ContactTel]{5559743}</RV>
  <Escalation>
    <OutDialEntry>
      <PhoneNumber>5552222</PhoneNumber>
      <OnAnswerLive>d:\scripts\alert.vgs</OnAnswerLive>
      <OnAnswerMachine>retry</OnAnswerMachine>
      <RetriesLeft>0</RetriesLeft>
      <RV>[ClientID]{554}[Severity]{2}[ContactTel]{5559743}</RV>
      <Escalation>
        <OutDialEntry>
          <PhoneNumber>5553333</PhoneNumber>
          <OnAnswerLive>d:\scripts\alert.vgs</OnAnswerLive>
          <OnAnswerMachine>retry</OnAnswerMachine>
          <RetriesLeft>0</RetriesLeft>
          <RV>[ClientID]{554}[Severity]{2}[ContactTel]{5559743}</RV>
          <Escalation>
            <OutDialEntry>
              <PhoneNumber>5551111</PhoneNumber>
              <CallTime>Now+10</CallTime>
              <OnAnswerLive>d:\scripts\alert.vgs</OnAnswerLive>
              <OnAnswerMachine>retry</OnAnswerMachine>
              <RetriesLeft>0</RetriesLeft>
              <RV>[ClientID]{554}[Severity]{2}[ContactTel]{5559743}</RV>
              <Escalation>
                <OutDialEntry>
                  <PhoneNumber>5552222</PhoneNumber>
                  <OnAnswerLive>d:\scripts\alert.vgs</OnAnswerLive>
                  <OnAnswerMachine>retry</OnAnswerMachine>
                  <RetriesLeft>0</RetriesLeft>
                  <RV>[ClientID]{554}[Severity]{2}[ContactTel]{5559743}</RV>
                  <Escalation>
                    <OutDialEntry>
                      <PhoneNumber>5553333</PhoneNumber>
                      <OnAnswerLive>d:\scripts\alert.vgs</OnAnswerLive>
                      <OnAnswerMachine>retry</OnAnswerMachine>
                      <RetriesLeft>0</RetriesLeft>
                      <RV>[ClientID]{554}[Severity]{2}[ContactTel]{5559743}</RV>
                      <OnRetriesExhausted>d:\scripts\notanswered.vbs</OnRetriesExhausted>
                    </OutDialEntry>
                  </Escalation>
                </OutDialEntry>
              </Escalation>
            </OutDialEntry>
          </Escalation>
        </OutDialEntry>
      </Escalation>
    </OutDialEntry>
  </Escalation>
</OutDialEntry>

The above script will result in the numbers being called in the following order : 5551111, then if no answer dial 5552222, and if no answer then dial 5553333, then wait for 10 minutes, and repeat calling 5551111 then 5552222 then 5553333. Dialing of furhter numbwers would stop as soon as one of the calls is answered.

Please note that the above script will only work if Dialogic cards are used - detection of whether a Human or an Answering Machine answers the call can only be made by a Dialogic card - Voice modems report all outgoing calls as 'Connected to a Human' immediately after dialing the number.


Send DDE Command

This module sends commands and data to other programs using DDE (Dynamic Data Exchange). You may use Result Variables and this module to pass to other programs information about the Callers ID, or about the selections which the caller has made.
The module uses a Visual Basic type way of specifying the destination application and the command or data to be sent.

Topic:
 This entry includes the destinations Application Name and Subject (otherwise referred to as Service and Topic). Both need to be specified in this field, separated by the | character.

Item:
To what Item will the sent data or command will refer to. Some applications do not require this to be specified, and hence in some cases this entry can be left blank.

Execute / Poke:
Used to select the type of DDE message which is to be sent.

Command
 If the Execute Command option is selected, this field holds the actual command transmitted to the destination application.

Data
 If the Poke Data option is selected, this field holds the actual data which will be poked into the specified Item.

If any errors are encountered during the DDE exchange the Fail path will then be taken. Otherwise if the DDE message is sent successfully then the Success path will be taken.

Examples 1:
To put a value 234 in cell A1 of Sheet1 of a currently open Excel document, select "Poke Data" and then set the following fields:

Topic: Excel|Sheet1
Item: R1C1
Data: 234

Examples 2:
To select Sheet1 in the currently open document in Excel select "Execute Commend" and then set the following fields:

Topic: Excel|System
Item:
Command: [ACTIVATE("SHEET1")]