mirror of
https://github.com/cwinfo/envayasms.git
synced 2024-11-15 04:40:26 +00:00
480 lines
14 KiB
HTML
Executable File
480 lines
14 KiB
HTML
Executable File
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<meta charset='utf-8'>
|
|
<title>EnvayaSMS: Server API Reference</title>
|
|
<link rel='stylesheet' type='text/css' href='/styles/site.css' />
|
|
</head>
|
|
|
|
<body>
|
|
<a href="http://github.com/youngj/EnvayaSMS"><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">
|
|
|
|
<a style='float:left' href="/"><img src='/media/icon.png' height='72' width='72' style='margin-right:10px' /></a>
|
|
<h1 style='padding-top:13px'><a href="/">EnvayaSMS</a>
|
|
|
|
<span class="small">
|
|
SMS gateway for Android
|
|
</span>
|
|
|
|
</h1>
|
|
|
|
<div class='menu' style='clear:both;padding-top:5px'>
|
|
<a href='/'>Home</a>
|
|
·
|
|
<a href='/install/'>Install</a>
|
|
·
|
|
<a href='/how/'>How it Works</a>
|
|
·
|
|
<a class='active' href='/serverapi/'>API Reference</a>
|
|
·
|
|
<a href='/comparison/'>Comparison</a>
|
|
·
|
|
<a href='/faq/'>FAQ</a>
|
|
·
|
|
<a href='/history/'>History</a>
|
|
</div>
|
|
|
|
<h2>Server API Reference</h2>
|
|
|
|
<p>
|
|
EnvayaSMS communicates with the server via HTTP POST requests that expect an XML response.
|
|
</p>
|
|
|
|
<p>
|
|
For convenience, EnvayaSMS includes <a href='https://github.com/youngj/EnvayaSMS/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
|
|
EnvayaSMS by implementing code in accordance with the API reference below.
|
|
We encourage you to contribute new libraries and example code back to the EnvayaSMS 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/app</code>
|
|
and the phone number of the phone with EnvayaSMS is <code>16505551212</code>.
|
|
</p>
|
|
|
|
<p>An incoming SMS from <code>6505551234</code> with message body "test":</p>
|
|
|
|
<pre>
|
|
POST /sg/app HTTP/1.1
|
|
X-Request-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 with an <code>image/jpeg</code> part and a <code>text/plain</code> part with message 'Test':</p>
|
|
|
|
<pre style='white-space:pre-wrap'>
|
|
POST /sg/app HTTP/1.1
|
|
X-Request-Signature: OgpiQet9guVhEp+0klrONR8qGNs=
|
|
Content-Length: 13087
|
|
Content-Type: multipart/form-data; boundary=i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
|
|
Host: 192.168.70.1:3000
|
|
Connection: Keep-Alive
|
|
|
|
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
|
|
Content-Disposition: form-data; name="from"
|
|
Content-Type: text/plain; charset=UTF-8
|
|
Content-Transfer-Encoding: 8bit
|
|
|
|
+16505551234
|
|
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
|
|
Content-Disposition: form-data; name="message"
|
|
Content-Type: text/plain; charset=UTF-8
|
|
Content-Transfer-Encoding: 8bit
|
|
|
|
Test
|
|
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
|
|
Content-Disposition: form-data; name="message_type"
|
|
Content-Type: text/plain; charset=UTF-8
|
|
Content-Transfer-Encoding: 8bit
|
|
|
|
mms
|
|
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
|
|
Content-Disposition: form-data; name="mms_parts"
|
|
Content-Type: text/plain; charset=UTF-8
|
|
Content-Transfer-Encoding: 8bit
|
|
|
|
[{"type":"application/smil","filename":"01smil","cid":"<0000>","name":"part0"},{"type":"text/plain","filename":"Text01.txt","cid":"<569>","name":"part1"},{"type":"image/jpeg","filename":"Image0001.jpg","cid":"<570>","name":"part2"}]
|
|
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
|
|
Content-Disposition: form-data; name="version"
|
|
Content-Type: text/plain; charset=UTF-8
|
|
Content-Transfer-Encoding: 8bit
|
|
|
|
3
|
|
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
|
|
Content-Disposition: form-data; name="phone_number"
|
|
Content-Type: text/plain; charset=UTF-8
|
|
Content-Transfer-Encoding: 8bit
|
|
|
|
16505551212
|
|
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
|
|
Content-Disposition: form-data; name="action"
|
|
Content-Type: text/plain; charset=UTF-8
|
|
Content-Transfer-Encoding: 8bit
|
|
|
|
incoming
|
|
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
|
|
Content-Disposition: form-data; name="part0"; filename="01smil"
|
|
Content-Type: application/smil; charset=UTF-8
|
|
Content-Transfer-Encoding: binary
|
|
|
|
<smil>
|
|
<head>
|
|
<layout>
|
|
<root-layout height="160" width="128"/>
|
|
<region fit="meet" height="70%" id="Image" left="0%" top="30%" width="100%"/>
|
|
<region fit="scroll" height="30%" id="Text" left="0%" top="0%" width="100%"/>
|
|
</layout>
|
|
</head>
|
|
<body>
|
|
<par dur="8000ms">
|
|
<text region="Text" src="cid:569"/>
|
|
<img region="Image" src="cid:570"/>
|
|
</par>
|
|
</body>
|
|
</smil>
|
|
|
|
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
|
|
Content-Disposition: form-data; name="part1"; filename="Text01.txt"
|
|
Content-Type: text/plain; charset=UTF-8
|
|
Content-Transfer-Encoding: binary
|
|
|
|
Test
|
|
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
|
|
Content-Disposition: form-data; name="part2"; filename="Image0001.jpg"
|
|
Content-Type: image/jpeg
|
|
Content-Transfer-Encoding: binary
|
|
|
|
<em>BINARY IMAGE DATA</em>
|
|
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO--
|
|
</pre>
|
|
|
|
<p>Checking for outgoing SMS messages:</p>
|
|
|
|
<pre>
|
|
POST /sg/app HTTP/1.1
|
|
X-Request-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/app HTTP/1.1
|
|
X-Request-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 EnvayaSMS:
|
|
</p>
|
|
|
|
<dl>
|
|
<dt>"version" ::= <integer></dt>
|
|
<dd>
|
|
EnvayaSMS's version code. This is an integer that will be incremented whenever
|
|
a new version of EnvayaSMS 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 EnvayaSMS, the server should update its code first,
|
|
then the phones can be upgraded to the new version of EnvayaSMS as convenient.
|
|
</dd>
|
|
|
|
<dt>"phone_number" ::= <text></dt>
|
|
<dd>
|
|
The phone number of the phone running EnvayaSMS, as entered under Menu > Settings.
|
|
<br /><br />
|
|
This allows the server to differentiate between EnvayaSMS clients if multiple phones
|
|
are running EnvayaSMS.
|
|
</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 EnvayaSMS:
|
|
|
|
<dl>
|
|
<dt>"X-Request-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>
|
|
|
|
In addition, the request contains form fields with the content of each MMS part,
|
|
with names as listed in the <code>mms_parts</code> field. 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 successful 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. (EnvayaSMS 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/EnvayaSMS">youngj/EnvayaSMS</a>
|
|
</div>
|
|
|
|
</div>
|
|
|
|
<script type="text/javascript">
|
|
|
|
var _gaq = _gaq || [];
|
|
_gaq.push(['_setAccount', 'UA-25868450-2']);
|
|
_gaq.push(['_trackPageview']);
|
|
|
|
(function() {
|
|
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
|
|
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
|
|
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
|
|
})();
|
|
|
|
</script>
|
|
|
|
</body>
|
|
</html> |