API

What is it good for?

Let say that you have some application like Point Of Sale, SAP, ERP, or other application that contains information about your client or friends, and somehow you want to reach them via SMS. OK, you have install Kalkun and it’s runs well, but how you send SMS with contact from other application? add/import it to Kalkun phonebook? Hmmm, it’s OK if you have only a few contact, but how about hundred or thousand contact? Your data will become redundant and hard to maintain.

Base PHP API

It is pretty easy, you just need to include Kalkun_API.php file (located on scripts/cURL/) and send some parameters and done.

include_once("Kalkun_API.php");

// some logic here, eg: database query to get phone number, and looping it
// ...

$config['base_url'] = "http://localhost/kalkun/index.php/"; // Kalkun URL
$config['session_file'] = "/tmp/cookies.txt"; // session file, must be writeable
$config['username'] = "username"; // Username on Kalkun
$config['password'] = "password";
$config['phone_number'] = "123456"; // Your client/friend phone number
$config['message'] = "Test message from API"; // SMS content

$sms = new Kalkun_API($config);
$sms->run();

// Other job
// ...

As you can see, all you need is to change the config parameters based on your configuration.

base_url: your Kalkun URL, don’t forget the index.php/
session_file: a file that save your session a.k.a login credential, it must be writeable by web server user
username and password: your login credential for Kalkun, not your application
phone_number: destination phone number, you’ve to get it from your application (through database query)
message: the SMS content

That's it!

Note: This only works on PHP script, of course you can use it (with some modification) with other language that support cURL or standard POST method.

REST API

This API can be used via simple HTTP GET method, for example:

http://kalkun-url/index.php/plugin/rest_api/send_sms?phoneNumber=123456&message=testing

If you want to set a SenderID, add this additional parameter to the URL : &SenderID=

Note: This is a plugin, you need to enable before use it.

XMLRPC

Sample XMLRPC client call using CodeIgniter XML-RPC Classes:

$this->load->library('xmlrpc');
$server_url = site_url('http://kalkun-url/index.php/plugin/xmlrpc/send_sms');		
		
$this->xmlrpc->server($server_url, 80);
$this->xmlrpc->method('send_sms');
$this->xmlrpc->set_debug(TRUE);
		
$request = array('+1234', 'Testing XMLRPC');
$this->xmlrpc->request($request);

if (!$this->xmlrpc->send_request())
{
    echo $this->xmlrpc->display_error();
}
else
{
    print_r($this->xmlrpc->display_response());
}

Note: This is a plugin, you need to enable before use it.

JSONRPC

Note: This is a plugin, you need to enable before use it.

For testing you may use RESTClient available as a browser extension.

for kalkun v0.8 (JSONRPC 2.0)

(since https://github.com/kalkun-sms/Kalkun/commit/cd206521d90e1eeb4fb6121570ddac6d586a9f76)

RESTClient usage:

• Method: POST
• Custom Headers: Content-Type: application/json
• URL: http://kalkun-url/index.php/plugin/jsonrpc/send_sms
• Body: {"jsonrpc":"2.0","id":551,"method":"sms.send_sms","params":{"phoneNumber":"+1234","message":"Testing JSONRPC"}}

Json query with curl example:

Command:

curl -X POST -H 'Content-Type: application/json' -i 'http://localhost/kalkun/index.php/plugin/jsonrpc/send_sms' --data '{"jsonrpc":"2.0","id":551,"method":"sms.send_sms","params":{"phoneNumber":"+1234","message":"Testing JSONRPC"}}'

Output:

HTTP/1.1 200 OK
Date: ******
Server: Apache/2.4.51
Set-Cookie: kalkun_ci_session=*****; expires=*****; Max-Age=1209600; path=/; HttpOnly
Expires: ******
Cache-Control: no-store, no-cache, must-revalidate
Pragma: no-cache
Content-Length: 52
Content-Type: application/json

{"jsonrpc":"2.0","id":551,"result":"Message queued"}

for kalkun v0.7 (JSONRPC 1.1)

RESTClient usage:

• Method: POST
• URL: http://kalkun-url/index.php/plugin/jsonrpc/send_sms
• Body: {"method":"sms.send_sms", "params":{"phoneNumber":"+1234","message":"Testing JSONRPC"}}

SOAP

Access the API (API Endpoint) at: http://kalkun-url/index.php/plugin/soap/api

WSDL URL is located at http://kalkun-url/index.php/plugin/soap/api/wsdl

Sample SOAP request:

Request Header:

POST /kalkun/index.php/plugin/soap/api HTTP/1.0
Host: localhost
User-Agent: NuSOAP/0.9.5 (1.123)
Content-Type: text/xml; charset=ISO-8859-1
SOAPAction: "http://kalkun-url/index.php/plugin/soap/api/sendMessage"
Content-Length: 612

<?xml version="1.0" encoding="ISO-8859-1"?>   
<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"     
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"     
xmlns:xsd="http://www.w3.org/2001/XMLSchema"     
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"     
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"     
xmlns:ns9011="urn:Api">    
<SOAP-ENV:Body>    
<ns9011:sendMessage xmlns:ns9011="urn:Api">
<destinationNumber xsi:type="xsd:string">1234</destinationNumber>
<message xsi:type="xsd:string">This is test from SOAP</message>
</ns9011:sendMessage>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>