IVM Software Development KitThis 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 PluginsIVM 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 PluginsThis 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; } Example using Perlprint @ARGV > 1 ? $ARGV[1] : "rand"; print "="; $RandomModulus = (@ARGV > 0) ? int($ARGV[0]) : 10; print (int(rand($RandomModulus))); Example using Visual BasicNote: The function GetRandomNumber is not shown here.Public Sub Main() Dim StdIO As clsStdIO Set StdIO = New clsStdIO StdIO.StdOut "rand=" & GetRandomNumber End Sub Example using PHPTo 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%. Example in using JavaThis 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)); } } Debugging PluginsIf you have problems with attempting to use your plugin:
Plugin Development ServicesIf 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.Using the IVM APIThe 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 IVMBefore 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: Sending Commands to IVMCommands 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; } IVMAPI CommandsEach 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 Changing IVM SettingsAll 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.Adding other functions to the IVM APIIf 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.Command Line OptionsCommand line options are used to control the running of IVM from a batch file or another application. The following options are supported: -on -off -ogm ogmname -outbound nnnnnnnn -ogmoutboundanswer ogmname -ogmoutboundmachine ogmname -outboundlist filename filename -set variables Examples: IVM.exe -ogm OGM1 -on IVM.exe -outbound 5551234567 IVM.exe phonesystem.ivr -on Other InformationIf 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. |