IVM Software Development Kit

This page is the software development kit (SDK) for the IVM Answering Attendant. It should be used by programmers who wish to write their own plugins or to use the IVM API.

This SDK is a very advanced topic. To create most ordinary IVR systems you should not need to do any programming. Follow the instructions in the IVM Manual, compare the example IVRs and, if required, use one of the prepared plugins.

Before attempting to write code you should familiarize yourself with:

IVM Software Development Kit Topics


About Plugins

IVM Plugins can be used to process information from a caller, or to provide information to a call (or both). Typical examples are database access, credit card authorization or hardware detection but there are an unlimited number of possibilities.

A number of useful plugins that have been written by our programmers are available for free download at www.nch.com.au/ivm/plugins.html. For more information about using Plugins see the IVM Help Manual Using Plugins page (Help->Help Contents).

Writing IVM Plugins

This documentation intended for programmers who wish to develop their own plugins for IVM.

Plugins can be written in any language that can make a 32 bit console-based command line executable for Windows. The examples below are written in C++ and Perl but Delphi, VB, and a number of other languages can be suitable.

A plugin is a console mode command line executable. It is run as an anonymous pipe by IVM when an OGM is opened.

Call variables are passed to the plugin as command line arguments. For example, if you make a plugin called "plugin.exe" you could set IVM to open "plugin.exe %linenumber% %cid% %variable1% %variable2%".

When an exe is run as a plugin, IVM waits for the plugin to return (exit). The plugin exe should return by the time the OGM has finished playing. If more time consuming tasks must be performed, your plugin should create/run another process and exit.

The return value can be any number of variables which are sent ("printed") by the plugin to STDOUT in name data pairs in the format used by HTTP. For example, "numbervariable=101&textvariable=Space+as+plus". For more information, refer to a book on cgi scripts. Often the most useful return value is name of the OGM that should play next. This variable can be used as the name of the "Go to OGM...".

Example using C++
This small plugin returns a random number. It can be useful at times if you want different OGMs to play to callers on a random basis.

The plugin has two optional arguments. The first determines the range of return values. The default is 10 which gives possible results 0 to 9. The second is the name of the return variable (default "rand").

#include <stdlib.h>
#include <iostream>

int main(int argc, char *argv[], char *[])
{
 cout << ((argc > 2) ? argv[2] : "rand");
 cout << "=";
 int RandomModulus = (argc > 1) ? atoi(argv[1]) : 10;
 randomize();
 cout << rand() % RandomModulus;
}

  Back to top

Example using Perl
print @ARGV > 1 ? $ARGV[1] : "rand";
print  "=";
$RandomModulus = (@ARGV > 0) ? int($ARGV[0]) : 10;
print (int(rand($RandomModulus)));

  Back to top

Example using Visual Basic
Note: The function GetRandomNumber is not shown here.
Public Sub Main()
   Dim StdIO As clsStdIO
   Set StdIO = New clsStdIO
   StdIO.StdOut "rand=" & GetRandomNumber
End Sub

  Back to top

Example using PHP
To run the plugin use:
Executable: C:\PHP\php.exe (or wherever you installed php - download from www.php.net)
Argument 1: -q (prevents HTTP headers being sent)
Argument 2:
Arguments 3+: Arguments to pass to PHP script

To get started, a simple PHP script like the following could be used:

<?php

if (argv[1] == 1234)

{

 print NextOGM=CorrectPIN ;

}

else

{

 print NextOGM=IncorrectPIN ;

}


?>

Then set Argument 3 to %PIN% for example (having collected the PIN into this variable in an earlier OGM) and set the Go to OGM& option to %NextOGM%.

  Back to top

Example in using Java
This is a similar plugin to the one for C++ but in java. To use a java plugin java must be the plugin name the compiled class the first argument followed by other arguments.

public class RandNumGen {
  public static void main(String[] args) {
   Calendar cal = Calendar.getInstance(java.util.TimeZone.getDefault());
   Random rand = new Random();
   rand.setSeed(cal.getTimeInMillis());    
   int numberOfOptions = Integer.parseInt(args[0])+1;
   System.out.print("rand=" + rand.nextInt(numberOfOptions));
 }
}

  Back to top

Debugging Plugins

If you have problems with attempting to use your plugin:
  • Run the plugin from the command line and check it returns the data as required.
  • After a failed call with the Call Test Simulator view the Most Recent Call Log from the IVM. All data sent to and returned from the plugin is logged on the Most Recent Call Logs.

  Back to top

Plugin Development Services

If you cannot write your own plugin (or do not have time), you can retain one of our associate programmers to develop it for you. Costs start from around $US150 depending on complexity. To request a quote, please see www.nch.com.au/development. Alternatively you could retain an IVM Expert from the new IVM Experts Connection www.nch.com.au/ivm/experts.html.

  Back to top

Using the IVM API

The IVM API is used to let other programs control the IVM (unlike plugins where the IVM runs other programs).

You need IVM v 2.30 or above to use this API. All examples and demonstrations below are shown in C++ but we hope you will have no difficulty in implementing the same functions using other languages (for example Visual Basic). The procedures below use a number of Windows API functions (eg. FindWindowEx, SendMessage etc.). If you need to know more about these functions and how to use them, refer to the Microsoft Windows API documentation.

Running IVM
Before any of the function calls below can be called, IVM must be running. The easiest way to do this is to set IVM to run automatically (see Settings).

However, if for some reason you need to launch it from your program use WinExec, ShellExecute or CreateProcess to open:
  "C:\Program Files\NCH Swift Sound\IVM\ivm.exe"
If you want it to run on the tray of the task bar add the argument /logon like this:
  "C:\Program Files\NCH Swift Sound\IVM\ivm.exe" /logon
If your program does launch IVM, you will need to wait for it to create its window before FindWindow will succeed (see below).

  Back to top

Sending Commands to IVM
Commands are sent to the IVM Main Window. You first need to find the window "IVM Answering Attendant" using FindWindowEx and then use SendMessage to send a IVM Command Message to it (hex 7fff). Use code like this:

#define IVMAPI_WINDOWCAPTION "IVM Answering Attendant"

#define WM_IVMAPI_COMMAND 0x7fff

int IVMAPISendCommand(int iIVMCommand, LPARAM ExtraData)
{
  HWND hwndIVM = FindWindowEx(NULL, NULL, NULL, IVMAPI_WINDOWCAPTION);
  if (hwndIVM == NULL) {
    // IVM not running.
    // Either attempt to run IVM 
    // or spit out error message here...
    return 0;
  }
  return SendMessage(hwndIVM, WM_IVMAPI_COMMAND, iIVMCommand, ExtraData);
}

Most commands do not use the ExtraData parameter so we can also define:

inline int IVMAPISendCommandSimple(int iIVMCommand) 
             { return IVMAPISendCommand(iIVMCommand, 0); }

If the command requires a string, you must use a Windows ATOM object to pass the string as shown in the following code. It is important to note your code must delete the ATOM using GlobalDeleteAtom after SendMessage returns.

int IVMAPISendCommandString(int iIVMCommand, const char* szStringToSend)
{
  ATOM atomExtraInfo = GlobalAddAtom(szStringToSend);
  int iReturnValue = IVMAPISendCommand(iIVMCommand, (LPARAM)atomExtraInfo);
  GlobalDeleteAtom(atomExtraInfo);
  return iReturnValue;
}

  Back to top

IVMAPI Commands
Each command has a number which is sent to the IVM using one of the above IVMAPISendCommand functions.

inline int IVMAPIGetVersion() { return IVMAPISendCommandSimple(0); }
// Returns the current API version which is currently 1.
// If 0 is returned the IVM or API is not available.
// If 2 or above is returned please contact us for updated documentation.

inline void IVMAPITurnOn() { IVMAPISendCommandSimple(1); }
// Turns IVM On (so it answers calls).

inline void IVMAPITurnOff() { IVMAPISendCommandSimple(2); }
// Turns IVM Of (so it will not answer calls).

inline void IVMAPISelectAnswerOGM(const char* szOGMName) 
                { IVMAPISendCommandString(3, szOGMName); }
// Selects the current default answer OGM.

inline void IVMAPIAddOutboundNumber(const char* szNumber) 
                 { IVMAPISendCommandString(4, szNumber); }
// Adds another number to call in the outbound calls list.
// szNumber can include the number to call
// and extra variables for use during the call.
//    eg. 5551234567&msgid=666&customer=999
inline void IVMAPISetGlobalVariable(const char* szVariables) 
                 { IVMAPISendCommandString(5, szVariables); }
// Sets IVM Global variables. The variables are http encoded in the format
// variable=value&variable2=value2&variable3=value3 
//    eg. site=mainnch&SystemPromptsFolder=c:\defaultIVM

  Back to top

Changing IVM Settings
All IVM settings are contained in the registry. Run regedit.exe to view the 'raw' settings. To change these settings from within your program use the Windows API command RegSetValueEx.

  Back to top

Adding other functions to the IVM API
If you need to be able to control other functions of the IVM from within your program (which cannot be done with a plugin), you can retain us to add the feature for you. Costs start from around $US300 depending on complexity. To request a quote, please see www.nch.com.au/development.

  Back to top

Command Line Options

Command line options are used to control the running of IVM from a batch file or another application. The following options are supported:

-on
turns on IVM to start answering calls.

-off
stops IVM from answering calls.

-ogm ogmname
sets the OGM named ogmname as the default OGM.

-outbound nnnnnnnn
adds the phone number nnnnnnn to the list of outbound calls and starts dialing the list of outbound calls. Note you may need to surround the phone number in double quotes if it contains spaces or other special characters, example -outbound "(01) 555 1234567"

-ogmoutboundanswer ogmname
sets the OGM that will be used if an outbound call is answered by a person.

-ogmoutboundmachine ogmname
sets the OGM that will be used if an outbound call is answered by an answering machine.

-outboundlist filename
replaces the list of outbound call phone numbers with the list in the file filename and starts dialing the list. The list should be in the format
phonenumber1;phonenumber2;phonenumer3;phonenumber4
example: 5551234567;5559876543;5551111111;5552222222;5553333333;(01) 55554444444;(02)5557777777

filename
loads the specified filename as an IVR file.

-set variables
sets global variables for use in OGMs. The string if variables is http encoded and in the format
variable=value&variable2=value2&variable3=value3
Please note if you use & to combine variables you must enclose the string in double quotes.
example: -set “site=mainnch&SystemPromptsFolder=c:\defaultIVM”

Examples:

IVM.exe -ogm OGM1 -on
will start IVM with OGM1 and immediately start answering.

IVM.exe -outbound 5551234567
will add phone number 5551234567 to the list of outbound numbers and start dialling.

IVM.exe phonesystem.ivr -on
will load the IVR file phonesystem.ivr and start answering calls using the default OGM.

  Back to top

Other Information

If you have problems writing your application, please see www.nch.com.au/support.

We now maintain a list of IVM Experts on the new IVM Experts Connection www.nch.com.au/ivm/experts.html. These are computer professional who know how to program the IVM and who can be retained to assist to set up complex IVM systems. You can also request to be listed if you are one of those professionals.

We also offer corporate software development services if you want us to do the development for you or if you need more substantial changes to the IVM. Costs start from around $US100 for a simple function but can increase to $10,000+ for development of a complete new release application. Request a quote from www.nch.com.au/development.

We can also rebrand IVM with your logo and details for a small fee (see https://www.nch.com.au/reseller for more information).

You can distribute the IVM install file with your software (but you may not under any circumstances distribute registration keys or seek to undermine the registration system). See the IVM license terms (on the Help file). Normally your customers would purchase the IVM directly from us. We also provide easy license terms if you do need to distribute registered versions of the IVM. Please see https://www.nch.com.au/reseller under the Software Blanket license heading.

  Back to top