{"id":34,"date":"2016-05-06T08:51:35","date_gmt":"2016-05-06T08:51:35","guid":{"rendered":"http:\/\/symbioticindia.in\/docu\/?p=34"},"modified":"2016-05-06T08:51:35","modified_gmt":"2016-05-06T08:51:35","slug":"a-simple-agi-scripting-engine-with-asterisk-java","status":"publish","type":"post","link":"http:\/\/symbioticindia.in\/docu\/2016\/05\/06\/a-simple-agi-scripting-engine-with-asterisk-java\/","title":{"rendered":"A simple AGI scripting engine with Asterisk-Java"},"content":{"rendered":"
ntroduction<\/strong><\/div>\n
Asterisk,<\/a> the well known free PBX, exposes great integration potentialities. Specifically , we’re interested in AGI (Asterisk Gateway Interface), a sort of API for scripting the engine.<\/div>\n
Today we’ll face a java interface for AGI: asterisk-java.<\/a> We’ll use this easy library to build a scripting engine. The used scripting language is BeanShell<\/a>, but you can virtually use any language supported by the Sun jdk (python,ruby,groovy, javascript etc.).<\/div>\n
\n
\n
\n

Asterisk-Java and AGI – some code<\/h4>\n<\/div>\n

The library asterisk-java is of immediate use; its simplest use is based on fastagi protocol, and though it also exposes a Manager API, fastagi will be enough for this article purposes . To build our scripting engine we just need to subclass “BaseAgiScript” and\u00a0 override its “service” method. From the AgiRequest object we’ll grab the parameter we’re interested in, “script”, which is just the name of a beanshell script we want to execute. We’ll then pass a reference of our class, the AgiRequest and the AgiChannel object to the beanshell interpreter, launch a global script that defines some utility functions (see below) and finally launch the requested script. The approach is quite flexible, our script engine doesn’t need to be on the same computer the pbx is on, and we can add\/modify our scripts on the fly without need for compilation or engine restart.<\/p>\n

<\/div>\n<\/div>\n<\/div>\n
package<\/span> org.beanizer.bagiserver;\r\n\r\n\r\nimport<\/span> bsh.EvalError;\r\nimport<\/span> java.io.FileNotFoundException;\r\nimport<\/span> java.io.IOException;\r\nimport<\/span> org.asteriskjava.fastagi.AgiChannel;\r\nimport<\/span> org.asteriskjava.fastagi.AgiException;\r\nimport<\/span> org.asteriskjava.fastagi.AgiRequest;\r\nimport<\/span> org.asteriskjava.fastagi.BaseAgiScript;\r\n\r\nimport<\/span> bsh.Interpreter;\r\n\r\npublic<\/span> class<\/span> BAgiServer extends<\/span> BaseAgiScript{<\/span>\r\n    \r\n    public<\/span> BAgiServer<\/span>(<\/span>)<\/span> {<\/span>\r\n    }<\/span>\r\n\r\n    public<\/span> void<\/span> service<\/span>(<\/span>AgiRequest request, AgiChannel channel)<\/span>\r\n    throws<\/span> AgiException {<\/span>\r\n        \r\n        Interpreter interp=<\/span>new<\/span> Interpreter<\/span>(<\/span>)<\/span>;\r\n        try<\/span> {<\/span>\r\n            String script=<\/span>(<\/span>(<\/span>request.getParameter<\/span>(<\/span>\"<\/span>script<\/span>\"<\/span>)<\/span>!<\/span>=<\/span>null<\/span>)<\/span> &<\/span>&<\/span> !<\/span>(<\/span> request.getParameter<\/span>(<\/span>\"<\/span>script<\/span>\"<\/span>)<\/span>.equals<\/span>(<\/span>\"<\/span>\"<\/span>)<\/span> )<\/span> )<\/span><\/span><\/pre>\n
\t\t\t\t\t\t\t\t? request.getParameter<\/span>(<\/span>\"<\/span>script<\/span>\"<\/span>)<\/span> : \"<\/span>..\/scriptlib\/default<\/span>\"<\/span>;\r\n            interp.source<\/span>(<\/span>\"<\/span>scriptlib\/bagi_import.bsh<\/span>\"<\/span>)<\/span>;\r\n            interp.set<\/span>(<\/span>\"<\/span>bagi<\/span>\"<\/span>,this<\/span>)<\/span>;\r\n            interp.set<\/span>(<\/span>\"<\/span>request<\/span>\"<\/span>,request)<\/span>;\r\n            interp.set<\/span>(<\/span>\"<\/span>channel<\/span>\"<\/span>,channel)<\/span>;\r\n            \r\n            interp.source<\/span>(<\/span>\"<\/span>scripts\/<\/span>\"<\/span>+<\/span> script +<\/span>\"<\/span>.bsh<\/span>\"<\/span>)<\/span>;\r\n            \r\n        }<\/span> catch<\/span> (<\/span>FileNotFoundException ex)<\/span> {<\/span>\r\n            ex.printStackTrace<\/span>(<\/span>)<\/span>;\r\n        }<\/span> catch<\/span> (<\/span>IOException ex)<\/span> {<\/span>\r\n            ex.printStackTrace<\/span>(<\/span>)<\/span>;\r\n        }<\/span> catch<\/span> (<\/span>EvalError ex)<\/span> {<\/span>\r\n            ex.printStackTrace<\/span>(<\/span>)<\/span>;\r\n        }<\/span>\r\n    }<\/span>\r\n   \r\n}<\/span> <\/span><\/pre>\n
A “fastagi-mapping.properties” file must exists on the classpath of the scripting engine and should contain something like this:<\/p>\n
server.agi = BAgiServer\r\n\r\n<\/pre>\n
where “server.agi” is the agi script name called from asterisk, to be mapped to “BagiServer”, our class name.<\/p>\n
We also need to add a call to our engine from asterisk’s dialplan, so in “extensions.conf” we’ll add something like:<\/p>\n
\r\nexten => 1200,1,Agi(agi:\/\/localhost\/server.agi?script=scriptname)\r\n\r\n<\/pre>\n
where “1200” can be an extension number of your choice, “localhost” is the server your scripting engine is hosted on, “server.agi” is the name we’ve mapped for our scripting engine and “scriptname” is the name of the beanshell script we want to invoke(without .bsh extension).<\/p>\n
When someone will try to call extension “1200”, the specified agi script will be executed.<\/p>\n
In our source code you can see we’re using two directories relative to the base classpath of BAgiServer:<\/p>\n
 <\/p>\n
    \n
  • “scriptlib”, wich contains scripts “default”(called if no script name is passed as parameter), and “bagi_import” ( where we put generic functions we can use from other scripts).<\/li>\n
  • “scripts” , containing all the user defined scripts.<\/li>\n<\/ul>\n
    Obviously these paths are arbitrary and you can choose differently. Now let’s have a look at our beanshell scripts.<\/p>\n
    \n
    bagi_import.bsh<\/div>\n
    \nThis is an utility script automatically included each time the engine gets called, so we should put here all the general purpose functions. Here is how it is now:<\/p>\n<\/div>\n<\/div>\n
    <\/pre>\n
    \r\nimport<\/span> org.asteriskjava.fastagi.AgiChannel;\r\nimport<\/span> org.asteriskjava.fastagi.AgiException;\r\nimport<\/span> org.asteriskjava.fastagi.AgiRequest;\r\nimport<\/span> org.asteriskjava.fastagi.BaseAgiScript;\r\n\r\nimport<\/span> org.beanizer.bagiserver.BAgiServer;\r\n\r\nBAgiServer bagi;\r\nAgiRequest request;\r\nAgiChannel channel;\r\n\r\nsay<\/span>(<\/span>String string)<\/span>{<\/span>\r\n    java.rmi.server.UID uid=<\/span>new<\/span> java.rmi.server.UID<\/span>(<\/span>)<\/span>;\r\n    String command=<\/span>\"<\/span>echo<\/span> '<\/span>\"<\/span> +<\/span> string +<\/span> \"<\/span>'<\/span> |<\/span> text2wave<\/span> -scale<\/span> 8<\/span> -o<\/span> \"<\/span>+<\/span> \"<\/span>\/tmp\/<\/span>\"<\/span>+<\/span>uid.toString<\/span>(<\/span>)<\/span> +<\/span>\"<\/span>.ulaw<\/span> -otype<\/span> ulaw<\/span> -<\/span>\"<\/span>;     \r\n    channel.exec<\/span>(<\/span>\"<\/span>System<\/span>\"<\/span>,command )<\/span>;\r\n    channel.streamFile<\/span>(<\/span>\"<\/span>\/tmp\/<\/span>\"<\/span> +<\/span>uid.toString<\/span>(<\/span>)<\/span>)<\/span>;\r\n    channel.exec<\/span>(<\/span>\"<\/span>System<\/span>\"<\/span>,\"<\/span>rm<\/span> \/tmp\/<\/span>\"<\/span>+<\/span> uid.toString<\/span>(<\/span>)<\/span> +<\/span>\"<\/span>.ulaw<\/span>\"<\/span> )<\/span>;\r\n}<\/span>\r\nanswer<\/span>(<\/span>)<\/span>{<\/span>\r\n    channel.answer<\/span>(<\/span>)<\/span>;\r\n}<\/span>\r\nhangup<\/span>(<\/span>)<\/span>{<\/span>\r\n    channel.hangup<\/span>(<\/span>)<\/span>;\r\n}<\/span>\r\ngetDigits<\/span>(<\/span>int<\/span> number)<\/span>{<\/span>\r\n    StringBuffer sb=<\/span>new<\/span> StringBuffer<\/span>(<\/span>)<\/span>;\r\n    for<\/span>(<\/span>int<\/span> t=<\/span>0<\/span>;t<<\/span>number;t+<\/span>+<\/span>)<\/span>{<\/span>\r\n        sb.append<\/span>(<\/span>channel.waitForDigit<\/span>(<\/span>10000<\/span>)<\/span>)<\/span>;\r\n    }<\/span>\r\n    return<\/span> sb.toString<\/span>(<\/span>)<\/span>;\r\n}<\/span>\r\n\r\nwait<\/span>(<\/span>int<\/span> millis)<\/span>{<\/span>\r\n    (<\/span>new<\/span> Thread<\/span>(<\/span>)<\/span>)<\/span>.sleep<\/span>(<\/span>millis)<\/span>;\r\n}<\/span> <\/span><\/pre>\n
    Here we basically import some useful classes, instantiate BAgiServer,AgiRequest and AgiChannel, and then define some functions. These just do what their names say, note how most of the time we just wrap AgiChannel’s methods (“answer” and “hangup” i.e.).<\/p>\n
    “getDigits”, makes use of the method “waitForDigit” of AgiChannel to wait for the user to input a number of digits specified by the function parameter and returns the entire number as a string.<\/p>\n
    “say”, is used to achieve text-to-speech. Instead of using festival or flite, here we use a lighter approach. Using the “exec” method of AgiChannel we launch “text2wave” on the pbx host (so text2wave must be installed there), and save the resulting sound file in a tmp directory with a random name.<\/p>\n
    We then use “streamFile” to stream the sound to the user and finally delete the sound file from the tmp directory.<\/p>\n
    <\/pre>\n
    \n
    default.bsh<\/div>\n
    This is called when no script to be executed has been specified.<\/p>\n
    \r\nanswer<\/span>(<\/span>)<\/span>;\r\nwait<\/span>(<\/span>1000<\/span>)<\/span>;\r\nsay<\/span>(<\/span>\"<\/span>No<\/span> script<\/span> defined<\/span>\"<\/span>)<\/span>;\r\nwait<\/span>(<\/span>1000<\/span>)<\/span>;\r\nhangup<\/span>(<\/span>)<\/span>;\r\n<\/span>\r\n<\/span><\/pre>\n
    \n<\/div>\n
    As you can see, it makes use of the functions defined in bagi_import.bsh.\u00a0 It answers the call, waits for a second, says a phrase, waits another second and then hangs up.<\/p>\n<\/div>\n
    \n
    test.bsh<\/div>\n
    And now an example of a user defined script. This script must reside in the “scripts” directory, and the agi call from asterisk should be something like this:<\/p>\n
    exten => 1200,1,Agi(agi:\/\/localhost\/server.agi?script=test)<\/pre>\n
    And here is the code:<\/p><\/div>\n<\/div>\n<\/div>\n<\/div>\n
     <\/p>\n
    \r\n<\/span><\/span>import<\/span> org.asteriskjava.fastagi.command.*;\r\nanswer<\/span>(<\/span>)<\/span>;\r\nwait<\/span>(<\/span>1000<\/span>)<\/span>;\r\nsay<\/span>(<\/span>\"<\/span>Please,<\/span> enter<\/span> extension<\/span> code<\/span>\"<\/span>)<\/span>;\r\nString code =<\/span> getDigits<\/span>(<\/span>3<\/span>)<\/span>;\r\nsay<\/span>(<\/span>\"<\/span>Trying<\/span> to<\/span> call<\/span> extension:<\/span>\"<\/span>)<\/span>;\r\nchannel.sayDigits<\/span>(<\/span>code)<\/span>;\r\nchannel.exec<\/span>(<\/span>\"<\/span>ChannelRedirect<\/span>\"<\/span>, channel.getName<\/span>(<\/span>)<\/span> +<\/span> \"<\/span>|from-internal|<\/span>\"<\/span> +<\/span> code +<\/span> \"<\/span>|1<\/span>\"<\/span>)<\/span>;\r\nhangup<\/span>(<\/span>)<\/span>;\r\n<\/span><\/pre>\n
    I’m sure you can appreciate how easy it is now to write a script. In this case the script answers and waits for a while, then asks for an extension number to be dialed, reads aloud the dialed code and then tries to redirect the call to the requested extension, using th “ChannelRedirect” asterisk command. Then it hangs up.<\/p>\n
    If you want to test this approach, here are a couple of guidelines:<\/p>\n