cwinfo/envayasms
5
0
Fork 0
mirror of https://github.com/cwinfo/envayasms.git synced 2024-11-15 04:40:26 +00:00
Code Releases Activity
7ce12974bb
envayasms/serverapi/index.html
Jesse Young 7ce12974bb fix documentation bug for X-Request-Signature
2011-12-01 09:53:44 -08:00

580 lines
18 KiB
HTML
Executable File
Raw Blame History

<!DOCTYPE html>
<html>
<head>
<meta charset='utf-8'>
<meta http-equiv="cache-control" content="no-cache, must-revalidate" >
<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>
&middot;
<a href='/install/'>Install</a>
&middot;
<a href='/test/'>Test</a>
&middot;
<a href='/how/'>How it Works</a>
&middot;
<a class='active' href='/serverapi/'>API Reference</a>
&middot;
<a href='/faq/'>FAQ</a>
&middot;
<a href='/history/'>History</a>
&middot;
<a href='/community/'>Community</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>Testing Your Implementation</h3>
<p>
The <a href='https://raw.github.com/youngj/EnvayaSMS/master/server/php/example/www/test.html'>EnvayaSMS Request Simulator</a>
is a standalone HTML file that allows you to simulate EnvayaSMS's HTTP requests entirely in your browser via JavaScript.
</p>
<p>
Just copy the HTML file somewhere on your site, and open it in a web browser. The URL of the EnvayaSMS Request Simulator
must be on the same domain as the Server URL.
</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: 120
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&timestamp=1317506831000
</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=i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RG
Host: 192.168.70.1:3000
Connection: Keep-Alive
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RG
Content-Disposition: form-data; name="from"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
+16505551234
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RG
Content-Disposition: form-data; name="timestamp"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
1317506831000
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RG
Content-Disposition: form-data; name="message"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Test
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RG
Content-Disposition: form-data; name="message_type"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
mms
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RG
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"}]
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RG
Content-Disposition: form-data; name="version"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
3
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RG
Content-Disposition: form-data; name="phone_number"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
16505551212
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RG
Content-Disposition: form-data; name="action"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
incoming
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RG
Content-Disposition: form-data; name="part0"; filename="01smil"
Content-Type: application/smil; charset=UTF-8
Content-Transfer-Encoding: binary
&lt;smil&gt;
&lt;head&gt;
&lt;layout&gt;
&lt;root-layout height="160" width="128"/&gt;
&lt;region fit="meet" height="70%" id="Image" left="0%" top="30%" width="100%"/&gt;
&lt;region fit="scroll" height="30%" id="Text" left="0%" top="0%" width="100%"/&gt;
&lt;/layout&gt;
&lt;/head&gt;
&lt;body&gt;
&lt;par dur="8000ms"&gt;
&lt;text region="Text" src="cid:569"/&gt;
&lt;img region="Image" src="cid:570"/&gt;
&lt;/par&gt;
&lt;/body&gt;
&lt;/smil&gt;
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RG
Content-Disposition: form-data; name="part1"; filename="Text01.txt"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: binary
Test
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RG
Content-Disposition: form-data; name="part2"; filename="Image0001.jpg"
Content-Type: image/jpeg
Content-Transfer-Encoding: binary
<em>BINARY IMAGE DATA</em>
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RG--
</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" ::= &lt;integer&gt;</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" ::= &lt;text&gt;</dt>
<dd>
The phone number of the phone running EnvayaSMS, as entered under Menu &gt; Settings.
<br /><br />
This allows the server to differentiate between EnvayaSMS clients if multiple phones
are running EnvayaSMS.
</dd>
<dt>"log" ::= &lt;text&gt;</dt>
<dd>
Log messages printed to the EnvayaSMS console since the last successful HTTP request.
<br /><br />
You may wish to append this data to a log file to allow administrators
to see error details without needing physical access to the phone.
<br /><br />
EnvayaSMS does not guarantee that the server receives log messages in order. Occasionally,
the server may receive the same log message multiple times.
</dd>
<dt>"action" ::= "outgoing" | "incoming" | "send_status" | "device_status" | "test" </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>
<dt>"device_status":</dt>
<dd>
Notify the server of a change in the Android device's state.
</dd>
<dt>"test":</dt>
<dd>
Test the server connection.
</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" ::= &lt;text&gt;</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, in the format name=value for each name/value pair,</li>
<li>the password,</li>
</ul>
with a comma in between each element, like so:
<br />
<code>"&lt;serverURL&gt;,&lt;name1&gt;=&lt;value1&gt;,&lt;...&gt;,&lt;nameN&gt;=&lt;valueN&gt;,&lt;password&gt;"</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 <code>action=incoming</code>:
<dl>
<dt>"from" ::= &lt;text&gt;</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" ::= &lt;text&gt;</dt>
<dd>
The message body of the SMS, or the content of the <code>text/plain</code> part of the MMS.
For multipart SMS messages, this field contains all parts concatenated and may be longer than 160 characters.
</dd>
<dt>"timestamp" ::= &lt;long integer&gt;</dt>
<dd>
The timestamp of the incoming message, in milliseconds since midnight, January 1, 1970 UTC.
</dd>
</dl>
Additional parameters sent in POST requests with <code>action=incoming</code> and <code>message_type=mms</code>:
<dl>
<dt>"mms_parts" ::= &lt;json_array&gt;</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" ::= &lt;text&gt;</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" ::= &lt;text&gt;</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>&lt;img region="Image" src="cid:805"/&gt;</code>).
</dt>
<dt>"type" ::= "application/smil" | "text/plain" | "image/jpeg" | ...</dt>
<dd>
The Content Type of the MMS part.
</dd>
<dt>"filename" ::= &lt;text&gt;</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 <code>action=outgoing</code>:
<dl>
<dt>
(None)
</dt>
</dl>
Additional parameters sent in POST requests with <code>action=send_status</code>:
<dl>
<dt>"id" ::= &lt;text&gt;</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" ::= &lt;text&gt;</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>
Additional parameters sent in POST requests with <code>action=device_status</code>:
<dl>
<dt>"status" ::= "power_connected" | "power_disconnected" <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | "battery_low" | "battery_okay"</dt>
<dd>
This field describes a condition that has changed on the Android device.
<dl>
<dt>"power_connected":</dt>
<dd>
The phone is now connected to external power.
</dd>
<dt>"power_disconnected":</dt>
<dd>
This phone is no longer connected to external power.
</dd>
<dt>"battery_low":</dt>
<dd>
The phone's battery level has dropped below 15%.
</dd>
<dt>"battery_okay":</dt>
<dd>
The phone's battery level is now at least 20% (after dropping below 15%).
</dd>
</dl>
</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
&lt;?xml version='1.0' encoding='UTF-8'?&gt;
&lt;messages&gt;
&lt;sms id='1540' to='16505551213'&gt;This is a test&lt;/sms&gt;
&lt;sms id='1541' to='16505551214'&gt;This is a another test message.&lt;/sms&gt;
&lt;/messages&gt;
</pre>
Specification:
<p>
The <code>Content-Type</code> header should be <code>text/xml</code>, with the content as follows:
</p>
<dl>
<dt>&lt;messages&gt;</dt>
<dd>
The root XML element.
<br />
<br />
Attributes:
<dl><dt>none</dt></dl>
<br />
Content:
<dl>
<dt>&lt;sms&gt;*</dt>
<dd>The SMS messages to send.</dd>
</dl>
</dd>
<dt id='sms'>&lt;sms&gt;</dt>
<dd>
Describes an outgoing SMS to send.
<br /><br />
Attributes:
<dl>
<dt>"id" ::= &lt;text&gt; (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" ::= &lt;text&gt; (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>
<dt>"priority" ::= &lt;integer&gt; (optional)</dt>
<dd>
The priority level of the outgoing message. If your server is sending outgoing messages
faster than the phone can send them out, the priority level allows you to specify
the order to send them (e.g. so that you can send transactional SMS replies
before asynchronous notifications).
<br />
<br />
Larger integers represent higher priorities.
If omitted, the default priority level is 0.
<br />
<br />
Within a priority level, SMS messages are processed and sent in the order
they were received from the server, and from top to bottom within the XML rsponse.
</dd>
</dl>
<br />
Content:
<dl>
<dt>CDATA</dt>
<dd>
The content of the SMS message to send. If the content is longer than the maximum size of a single SMS (typically 160 characters),
it will automatically be sent as a multipart SMS.
</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>
View Git Blame Copy Permalink