Plugin: External script

External script is a way to create your own logic application without interfering and messing up with Kalkun code.

A great example using this feature (which is also included in Kalkun sources) is below.

---

How to turn Kalkun into awesome mobile dictionary app

Original post from Azhari Harahap (back2arie): Howto turn Kalkun into awesome mobile dictionary app.

Let’s play a little with Kalkun and explore what it can do. :D Kalkun now not just an SMS management app, you can forward sms to your email, send SMS from other app using cURL, and even cooler, intercept incoming sms and process it with external script.

Let me show you how it works, for example we will create mobile dictionary app, yes! you translate text using SMS and no more a 100+ pages old style dictionary book. :P

OK, for this experiment we’ll using:

• Kalkun 0.2.10, with External script to process incoming message from user and cURL script to send the translated text back to user, php-cli also needed to run php script from command line.

• The translator itself, we will use GTranslate, a php wrapper for Google Translate API, yes! we will use the powerful Google Translate, you can even translate a whole text, not just a single word. Please note that translate process need internet connection on Kalkun server to the Google server.

I’m assuming that you use *nix environment (Windows user might have to experiment a little bit more harder here) and Kalkun already configured with gammu-smsd and you already can send and receive SMS.

OK, first we will create the translator script using php, let’s name it translator.php, for this example I will use Indonesia to English translation.

Note: I’ve modified the gtranslate-api-php a little bit, cause somehow it can’t run via php-cli

define('GTranslate_path', "/path/to/gtranslate-api-php/GTranslate.php");
define('Kalkun_API_path', "/path/to/kalkun/scripts/cURL/Kalkun_API.php");

$arg_list = $_SERVER['argv'];
$arg_count = count($arg_list);

if($arg_count > 2)
{
$phone_number = $arg_list[1];
unset($arg_list[0]);
unset($arg_list[1]);

// build the text
$translate_string = implode(' ',$arg_list);

require(GTranslate_path);
try
{
$gt = new Gtranslate;
$gt->setRequestType('curl');
$gt->setLanguageFile('languages.ini');
$translated_string = $gt->indonesian_to_english($translate_string);

// Send translated text by SMS
include_once(Kalkun_API_path);
$config['base_url'] = "http://localhost/kalkun/index.php/";
$config['session_file'] = "/tmp/cookies.txt";
$config['username'] = "kalkun";
$config['password'] = "kalkun";
$config['phone_number'] = $phone_number;
$config['message'] = $translated_string;
$sms = new Kalkun_API($config);
$sms->run();
}
catch (GTranslateException $ge)
{
echo $ge->getMessage();
}
}

As you can see, the script takes $_SERVER['argv'] which came from argument when the script called, for example:

php translator.php 123456 Apa kabar?

The argument list will be (every argument divide by space character):

• Argument 0: translator.php
• Argument 1: 123456
• Argument 2: Apa
• Argument 3: kabar?

The script remove the argument 0, set argument 1 (phone number) to another variable, and concatenate argument 2 and so on with php implode function to make full string. Send the string to Google Translate and receive the translated string, finally send it back to user via Kalkun “API”.

OK, the translator is ready, now we need to config Kalkun to intercept incoming sms and send it to the translator using External script.

Open up application/plugins/external_script/config/external_script.php and add:

$script = array();
$script['intepreter_path'] = '/bin/sh';
$script['name'] = '/path/to/translate.sh';
$script['key'] = 'content';
$script['type'] = 'contain';
$script['value'] = 'translate';
$script['parameter'] = 'phone|content';
array_push($config['external_script'], $script);
unset($script);

Don’t forget to install the plugin in kalkun to activate it.

As you can see, the script will triggered if the sms content contains “translate” string, phone number and content itself will be send as parameter. For example the sms came from 123456 and sms content is:

translate Apa kabar?

So the shell script will be executed as follows:

/bin/sh /path/to/translate.sh 123456 translate Apa kabar?

And the last step is create the translate.sh shell script to call the translate.php via php-cli.

#!/bin/sh

PHP=/usr/bin/php # php cli path
TRANSLATOR=/path/to/translator.php # translator.php path

# execute it and pass all arguments
$PHP $TRANSLATOR $@

That’s it and enjoy.