mirror of
https://github.com/cwinfo/envayasms.git
synced 2024-11-14 20:30:26 +00:00
380 lines
11 KiB
HTML
Executable File
380 lines
11 KiB
HTML
Executable File
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<meta charset='utf-8'>
|
|
<title>KalSMS</title>
|
|
<link rel='stylesheet' type='text/css' href='styles/site.css' />
|
|
</head>
|
|
|
|
<body>
|
|
<a href="http://github.com/youngj/KalSMS"><img style="position: absolute; top: 0; right: 0; border: 0;" src="http://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub" /></a>
|
|
|
|
<div id="container">
|
|
|
|
<h1><a href="index.html">KalSMS</a>
|
|
|
|
<span class="small">
|
|
SMS/MMS gateway for Android
|
|
</span>
|
|
</h1>
|
|
|
|
<div class='menu'>
|
|
<a href='index.html'>Home</a>
|
|
·
|
|
<a href='install.html'>Install</a>
|
|
·
|
|
<a href='how.html'>How it Works</a>
|
|
·
|
|
<a href='serverapi.html'>API Reference</a>
|
|
·
|
|
<a href='comparison.html'>Comparison</a>
|
|
·
|
|
<a href='history.html'>History</a>
|
|
</div>
|
|
|
|
<h2>Server API Reference</h2>
|
|
|
|
<p>
|
|
KalSMS communicates with the server via HTTP POST requests that expect an XML response.
|
|
</p>
|
|
|
|
<p>
|
|
For convenience, KalSMS includes <a href='https://github.com/youngj/KalSMS/tree/master/server'>server libraries and example code</a>
|
|
for certain languages to simplify handling its POST requests and generating response XML.
|
|
</p>
|
|
|
|
<p>
|
|
If a server library is not yet available for your programming language, you can still use
|
|
KalSMS by implementing code in accordance with the API reference below.
|
|
We encourage you to contribute new libraries and example code back to the KalSMS project!
|
|
</p>
|
|
|
|
<h3>
|
|
HTTP Request Format
|
|
</h3>
|
|
|
|
<h4>Example requests</h4>
|
|
|
|
<p>
|
|
In each of the example requests below, the Server URL is <code style='white-space:nowrap'>http://192.168.70.1:3000/sg/kalsms</code>
|
|
and the phone number of the phone with KalSMS is <code>16505551212</code>.
|
|
</p>
|
|
|
|
<p>An incoming SMS from <code>6505551234</code> with message body "test":</p>
|
|
|
|
<pre>
|
|
POST /sg/kalsms HTTP/1.1
|
|
X-Kalsms-Signature: sAemG31uRllk/K9xck2WRNaF/WI=
|
|
Content-Length: 96
|
|
Content-Type: application/x-www-form-urlencoded
|
|
Host: 192.168.70.1:3000
|
|
Connection: Keep-Alive
|
|
|
|
from=6505551234&message_type=sms&message=test&version=2&phone_number=16505551212&action=incoming
|
|
</pre>
|
|
|
|
<p>An incoming MMS message:</p>
|
|
|
|
<pre>
|
|
TODO
|
|
</pre>
|
|
|
|
<p>Checking for outgoing SMS messages:</p>
|
|
|
|
<pre>
|
|
POST /sg/kalsms HTTP/1.1
|
|
X-Kalsms-Signature: 139CL71b7r1Zw/E2wcccWFviSlg=
|
|
Content-Length: 50
|
|
Content-Type: application/x-www-form-urlencoded
|
|
Host: 192.168.70.1:3000
|
|
Connection: Keep-Alive
|
|
|
|
action=outgoing&version=2&phone_number=16505551212
|
|
</pre>
|
|
|
|
<p>Notifying the server of the status of a sent message:</p>
|
|
|
|
<pre>
|
|
POST /sg/kalsms HTTP/1.1
|
|
X-Kalsms-Signature: 6uJtI6+QqlVBbUsR4T0WsQomods=
|
|
Content-Length: 80
|
|
Content-Type: application/x-www-form-urlencoded
|
|
Host: 192.168.70.1:3000
|
|
Connection: Keep-Alive
|
|
|
|
id=1536&status=sent&error=&action=send_status&version=2&phone_number=16505551212
|
|
</pre>
|
|
|
|
<h4>Specification</h4>
|
|
|
|
<p>
|
|
The following parameters are sent in all POST requests from KalSMS:
|
|
</p>
|
|
|
|
<dl>
|
|
<dt>"version" ::= <integer></dt>
|
|
<dd>
|
|
KalSMS's version code. This is an integer that will be incremented whenever
|
|
a new version of KalSMS is released. (It is not the same as the version name shown
|
|
on the Help screen.)
|
|
<br />
|
|
<br />
|
|
This allows the server to support phones running different API versions at the same time.
|
|
If a deployment has many phones running with KalSMS, the server should update its code first,
|
|
then the phones can be upgraded to the new version of KalSMS as convenient.
|
|
</dd>
|
|
|
|
<dt>"phone_number" ::= <text></dt>
|
|
<dd>
|
|
The phone number of the phone running KalSMS, as entered under Menu > Settings.
|
|
<br /><br />
|
|
This allows the server to differentiate between KalSMS clients if multiple phones
|
|
are running KalSMS.
|
|
</dd>
|
|
|
|
<dt>"action" ::= "outgoing" | "incoming" | "send_status"</dt>
|
|
<dd>
|
|
The request action determines the purpose of the HTTP request:
|
|
|
|
<dl>
|
|
<dt>"outgoing":</dt>
|
|
<dd>
|
|
Poll the server for outgoing messages
|
|
</dd>
|
|
|
|
<dt>"incoming":</dt>
|
|
<dd>
|
|
Forward an incoming SMS or MMS message to the server
|
|
</dd>
|
|
|
|
|
|
<dt>"send_status":</dt>
|
|
<dd>
|
|
Update the server on the status of sending an outgoing message
|
|
</dd>
|
|
</dl>
|
|
|
|
The other POST parameters sent depend on the request action.
|
|
</dd>
|
|
</dl>
|
|
|
|
The following HTTP Headers are sent in all POST requests from KalSMS:
|
|
|
|
<dl>
|
|
<dt>"X-Kalsms-Signature" ::= <text></dt>
|
|
<dd>
|
|
A signature of the request to verify the phone and the server share the same password.
|
|
(This doesn't protect against MITM snooping or replay attacks, so it is recommended to
|
|
use the <code>https://</code> protocol.)
|
|
<br />
|
|
<br />
|
|
The signature is calculated by the following algorithm:
|
|
|
|
<ol>
|
|
<li>Sort all POST parameters, not including file uploads,
|
|
by the name of the field (in the usual ASCII order).</li>
|
|
|
|
<li>Generate an input string by concatenating:
|
|
<ul>
|
|
<li>the server URL,</li>
|
|
<li>each of the sorted POST parameters with their corresponding values, and</li>
|
|
<li>the password,</li>
|
|
</ul>
|
|
with a comma in between each element, like so:
|
|
<br />
|
|
<code>"<serverURL>,<name1>,<value1>,<...>,<nameN>,<valueN>,<password>"</code>
|
|
</li>
|
|
|
|
<li>Generate the SHA-1 hash of the input string in UTF-8</li>
|
|
|
|
<li>Encode the SHA-1 hash using Base64 with no line breaks.</li>
|
|
</ol>
|
|
</dd>
|
|
</dl>
|
|
|
|
Additional parameters sent in POST requests with action=incoming:
|
|
|
|
<dl>
|
|
<dt>"from" ::= <text></dt>
|
|
<dd>
|
|
The phone number of the message sender.
|
|
</dd>
|
|
|
|
<dt>"message_type" ::= "sms" | "mms"</dt>
|
|
<dd>
|
|
Whether this message is an SMS or MMS.
|
|
</dd>
|
|
|
|
<dt>"message" ::= <text></dt>
|
|
<dd>
|
|
The message body of the SMS, or the content of the <code>text/plain</code> part of the MMS.
|
|
</dd>
|
|
</dl>
|
|
|
|
Additional parameters sent in POST requests with action=incoming and message_type=mms:
|
|
|
|
<dl>
|
|
<dt>"mms_parts" ::= <json_array></dt>
|
|
<dd>
|
|
Metadata for each part of the MMS. Each item in the JSON array is an object
|
|
with the following keys and values:
|
|
|
|
<dl>
|
|
<dt>"name" ::= <text></dt>
|
|
<dd>
|
|
The name of an additional form field where the content of the MMS part
|
|
is sent as an attached file.
|
|
</dd>
|
|
|
|
<dt>"cid" ::= <text></dt>
|
|
<dd>
|
|
The Content ID of the MMS part. This allows the server to resolve
|
|
references in the SMIL part of the MMS
|
|
(e.g. <code><img region="Image" src="cid:805"/></code>).
|
|
</dt>
|
|
|
|
<dt>"type" ::= "application/smil" | "text/plain" | "image/jpeg" | ...</dt>
|
|
<dd>
|
|
The Content Type of the MMS part.
|
|
</dd>
|
|
|
|
<dt>"filename" ::= <text></dt>
|
|
<dd>
|
|
The filename of the MMS part, as sent by the sender phone,
|
|
e.g. <code>"Image001.jpg"</code>.
|
|
</dt>
|
|
</dl>
|
|
|
|
(Additional fields with the content of each MMS part. Text parts
|
|
are encoded in UTF-8.)
|
|
</dt>
|
|
</dl>
|
|
|
|
Additional parameters sent in POST requests with action=outgoing:
|
|
|
|
<dl>
|
|
<dt>
|
|
(None)
|
|
</dt>
|
|
</dl>
|
|
|
|
Additional parameters sent in POST requests with action=send_status:
|
|
|
|
<dl>
|
|
<dt>"id" ::= <text></dt>
|
|
<dd>
|
|
The Server's ID for the outgoing message (from the <code>id</code> attribute
|
|
of an <a href='#sms'>sms</a> tag in a previous XML response from the server).
|
|
</dd>
|
|
|
|
<dt>"status" ::= "queued" | "failed" | "sent"</dt>
|
|
<dd>
|
|
The current status of the outgoing message.
|
|
</dd>
|
|
|
|
<dt>"error" ::= <text></dt>
|
|
<dd>
|
|
A description of the reason for the error, if the message
|
|
failed to send; or, an empty string if the message
|
|
has been sent successfully.
|
|
</dd>
|
|
</dl>
|
|
|
|
<h3>
|
|
HTTP Response Format
|
|
</h4>
|
|
|
|
<p>
|
|
For a successul request, the server should return HTTP status code 200.
|
|
If the signature check failed, the server should return status code 403.
|
|
Other status codes may be used to signify errors.
|
|
</p>
|
|
|
|
<h4>HTTP response for action=incoming and action=outgoing</h4>
|
|
|
|
Example:
|
|
<pre>
|
|
HTTP/1.1 200 OK
|
|
Content-Type: text/xml
|
|
Content-Length: 189
|
|
|
|
<?xml version='1.0' encoding='UTF-8'?>
|
|
<messages>
|
|
<sms id='1540' to='16505551213'>This is a test</sms>
|
|
<sms id='1541' to='16505551214'>This is a another test message.</sms>
|
|
</messages>
|
|
</pre>
|
|
|
|
Specification:
|
|
<p>
|
|
The Content-Type header should be text/xml, with the content as follows:
|
|
</p>
|
|
<dl>
|
|
<dt><messages></dt>
|
|
<dd>
|
|
The root XML element.
|
|
<br />
|
|
<br />
|
|
Attributes:
|
|
<dl><dt>none</dt></dl>
|
|
<br />
|
|
Content:
|
|
<dl>
|
|
<dt><sms>*</dt>
|
|
<dd>The SMS messages to send.</dd>
|
|
</dl>
|
|
</dd>
|
|
<dt id='sms'><sms></dt>
|
|
<dd>
|
|
Describes an outgoing SMS to send.
|
|
<br /><br />
|
|
Attributes:
|
|
<dl>
|
|
<dt>"id" ::= <text> (optional)</dt>
|
|
<dd>
|
|
An ID for this outgoing message. (KalSMS will send this
|
|
back to the server as the id field in a send_status request.)
|
|
</dd>
|
|
<dt>"to" ::= <text> (optional for incoming, required for outgoing)</dt>
|
|
<dd>
|
|
The phone number to send the SMS to. If omitted for
|
|
action=incoming, it will be sent as a reply to the original
|
|
sender.
|
|
</dd>
|
|
</dl>
|
|
<br />
|
|
Content:
|
|
<dl>
|
|
<dt>CDATA</dt>
|
|
<dd>
|
|
The content of the SMS message to send.
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h4>HTTP Response for action=send_status</h4>
|
|
|
|
Example:
|
|
<pre>
|
|
HTTP/1.1 200 OK
|
|
Content-Type: text/plain
|
|
Content-Length: 2
|
|
|
|
OK
|
|
</pre>
|
|
|
|
<p>
|
|
The response content for <code>send_status</code> requests is currently undefined and ignored.
|
|
HTTP status code 200 signifies success, and anything else signifies failure.
|
|
</p>
|
|
|
|
|
|
<div class="footer">
|
|
get the source code on GitHub : <a href="http://github.com/youngj/KalSMS">youngj/KalSMS</a>
|
|
</div>
|
|
|
|
</div>
|
|
|
|
</body>
|
|
</html> |