mirror of
https://github.com/cwinfo/envayasms.git
synced 2024-11-14 20:30:26 +00:00
599 lines
21 KiB
Twig
Executable File
599 lines
21 KiB
Twig
Executable File
id: serverapi
|
|
title: Server API Reference
|
|
---
|
|
|
|
<p>
|
|
This page describes the application programming interface (API) between the EnvayaSMS app and your server. Deploying EnvayaSMS requires implementing a script on your server in accordance with this API.
|
|
</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.
|
|
</p>
|
|
|
|
<p>
|
|
Drupal users can also install the <a href='https://drupal.org/project/sms_envaya'>Drupal module</a> (developed by Mark Burdett / VozMob).
|
|
</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>Contents</h3>
|
|
|
|
<ul>
|
|
<li><a href='/serverapi/#overview'>API Overview</a></li>
|
|
<li><a href='/serverapi/#actions'>HTTP Request Format (Actions)</a></li>
|
|
<li><a href='/serverapi/#events'>HTTP Response Format (Events)</a></li>
|
|
<li><a href='/serverapi/#errors'>HTTP Response Error Format</a></li>
|
|
<li><a href='/serverapi/#amqp'>AMQP Message Format</a></li>
|
|
<li><a href='/serverapi/#testing'>Testing Your Implementation</a></li>
|
|
</ul>
|
|
|
|
<h3 id='overview'>API Overview</h3>
|
|
|
|
<p>
|
|
EnvayaSMS communicates with the server via HTTP POST requests, called <b>actions</b>. These actions include:
|
|
</p>
|
|
<ul>
|
|
<li>forwarding incoming messages to the server,</li>
|
|
<li>polling for outgoing messages,</li>
|
|
<li>notifying the server of the status of outgoing messages, and</li>
|
|
<li>notifying the server of a change in device status (such as battery level or power source).</li>
|
|
</ul>
|
|
|
|
<p>
|
|
All of these POST requests are made to the same URL (the "Server URL"), with data passed as normal POST parameters.
|
|
Each POST request has an "action" parameter that tells the server which action is being performed.
|
|
</p>
|
|
|
|
<p>
|
|
For each action sent by the phone, the server sends an HTTP response (as JSON).
|
|
If the action was successful, the response should contain zero or more <b>events</b>. Events include:
|
|
</p>
|
|
<ul>
|
|
<li>sending outgoing messages,</li>
|
|
<li>canceling outgoing messages that haven't been sent yet,</li>
|
|
<li>changing the settings for the EnvayaSMS app, and</li>
|
|
<li>displaying log messages in the EnvayaSMS app.</li>
|
|
</ul>
|
|
|
|
<p>
|
|
Optionally, EnvayaSMS can also connect directly to an AMQP server (such as RabbitMQ). This allows your server to push outgoing messages to the phone in real-time,
|
|
instead of requiring the phone to poll for messages at a fixed interval. Each message in AMQP queue is a single <em>event</em>, also encoded as JSON.
|
|
</p>
|
|
|
|
<p>
|
|
(Note: Prior to version 3.0, the HTTP response format was XML. <a href='/serverapi/upgrade30.html'>See information on upgrading to version 3.0</a>.)
|
|
</p>
|
|
|
|
<h3 id='actions'>HTTP Request Format (Actions)</h3>
|
|
|
|
|
|
<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>"log" ::= <text></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>"network" ::= <text></dt>
|
|
<dd>
|
|
The phone's current type of internet connectivity. Typically this is something like "MOBILE" or "WIFI".
|
|
</dd>
|
|
|
|
<dt>"settings_version" ::= <integer></dt>
|
|
<dd>
|
|
The current value of the "settings_version" setting.
|
|
(The server may optionally set this setting by pushing settings to the phone in a 'settings' event.)
|
|
<br /><br />
|
|
This allows the server to determine if it should push new settings to the phone, allowing
|
|
you to manage and update the app settings remotely (i.e. without manually typing them into the app).
|
|
</dd>
|
|
|
|
<dt>"now" ::= <long integer></dt>
|
|
<dd>
|
|
The current time in milliseconds since the Unix epoch at midnight, January 1, 1970 UTC, according to the phone's clock.
|
|
</dd>
|
|
|
|
<dt>"battery" ::= <integer></dt>
|
|
<dd>
|
|
The current percentage of the phone's battery level, from 0 to 100.
|
|
</dd>
|
|
|
|
<dt>"power" ::= <integer></dt>
|
|
<dd>
|
|
The current power source of the Android phone; 0=battery, 1=USB; 2=AC
|
|
</dd>
|
|
|
|
<dt>"action" ::= "outgoing" | "incoming" | "send_status" | "device_status" | "test" <br/>
|
|
| "amqp_started" | "forward_sent"</dt>
|
|
<dd>
|
|
The request action determines the purpose of the HTTP request:
|
|
|
|
<dl>
|
|
<dt>"outgoing":</dt>
|
|
<dd>
|
|
Poll the server for events (including, but not limited to, outgoing messages)
|
|
</dd>
|
|
|
|
<dt>"incoming":</dt>
|
|
<dd>
|
|
Forward an incoming message to the server (SMS, MMS, or call notification)
|
|
</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>
|
|
|
|
<dt>"amqp_started":</dt>
|
|
<dd>
|
|
The phone has established a real-time connection to an AMQP server.
|
|
</dd>
|
|
|
|
<dt>"forward_sent":</dt>
|
|
<dd>
|
|
Forwards a message to the server that was previously sent via the Android phone's
|
|
Messaging app.
|
|
</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, 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>"<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 <b>action=incoming</b>:
|
|
|
|
<dl>
|
|
<dt>"from" ::= <text></dt>
|
|
<dd>
|
|
The phone number of the message sender.
|
|
</dd>
|
|
|
|
<dt>"message_type" ::= "sms" | "mms" | "call"</dt>
|
|
<dd>
|
|
Whether this message is a SMS, MMS, or a notification of an incoming call.
|
|
</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.
|
|
For multipart SMS messages, this field contains all parts concatenated and may be longer than 160 characters.
|
|
(This field is empty for incoming call notifications.)
|
|
</dd>
|
|
|
|
<dt>"timestamp" ::= <long integer></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 <b>action=incoming and message_type=mms</b>:
|
|
|
|
<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>.
|
|
In cases when the original filename is not available, this filename is a random string.
|
|
</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 <b>action=outgoing</b>:
|
|
|
|
<dl>
|
|
<dt>
|
|
(None)
|
|
</dt>
|
|
</dl>
|
|
|
|
Additional parameters sent in POST requests with <b>action=send_status</b>:
|
|
|
|
<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" | "cancelled" | "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>
|
|
|
|
Additional parameters sent in POST requests with <b>action=device_status</b>:
|
|
|
|
<dl>
|
|
<dt>"status" ::= "power_connected" | "power_disconnected" <br />
|
|
| "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>
|
|
|
|
<dt>"send_limit_exceeded":</dt>
|
|
<dd>
|
|
EnvayaSMS is delaying sending outgoing messages because the rate limit for sending messages has been exceeded. (Installing additional expansion packs may be needed.)
|
|
</dd>
|
|
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
|
|
Additional parameters sent in POST requests with <b>action=forward_sent</b>:
|
|
|
|
<dl>
|
|
<dt>"to" ::= <text></dt>
|
|
<dd>
|
|
The phone number that the message was sent to.
|
|
</dd>
|
|
|
|
<dt>"message_type" ::= "sms"</dt>
|
|
<dd>
|
|
Currently only SMS messages are supported.
|
|
</dd>
|
|
|
|
<dt>"message" ::= <text></dt>
|
|
<dd>
|
|
The message body of the SMS.
|
|
</dd>
|
|
|
|
<dt>"timestamp" ::= <long integer></dt>
|
|
<dd>
|
|
The timestamp of the outgoing message, in milliseconds since midnight, January 1, 1970 UTC.
|
|
</dd>
|
|
</dl>
|
|
|
|
Additional parameters sent in POST requests with <b>action=amqp_started</b>:
|
|
|
|
<dl>
|
|
<dt>"consumer_tag" ::= <text></dt>
|
|
<dd>
|
|
The consumer tag of the AMQP connection.
|
|
<br />
|
|
<br />
|
|
The server can use this action to kick off old AMQP connections
|
|
(that weren't closed properly) before their heartbeat timeout expires.
|
|
With RabbitMQ, this can be done using the management API.
|
|
</dd>
|
|
</dl>
|
|
|
|
<h3 id='events'>
|
|
HTTP Response Format (Events)
|
|
</h3>
|
|
|
|
<p>
|
|
In response to a successful HTTP request (i.e., action), the server should return HTTP status code 200, with an <code>application/json</code> content type.
|
|
</p>
|
|
|
|
<p>
|
|
The response body should contain a JSON object with an <code>events</code> property, which is an array of events.
|
|
Each event is a JSON object, containing one or more properties.</p>
|
|
|
|
<p>
|
|
For example, the following response contains one 'send' event that instructs EnvayaSMS to send one message:
|
|
</p>
|
|
|
|
<pre>
|
|
{
|
|
"events":[{
|
|
"event":"send",
|
|
"messages":[{
|
|
"id":"4f7c9cea5e11b",
|
|
"to":"6507993371",
|
|
"message":"hello world'"
|
|
}]
|
|
}]
|
|
}
|
|
</pre>
|
|
|
|
<p>
|
|
All events contain at least the following property:
|
|
</p>
|
|
|
|
<dl>
|
|
<dt>"event" ::= "send" | "cancel" | "cancel_all" | "log" | "settings"</dt>
|
|
<dd>
|
|
This property determines the type of event:
|
|
<dl>
|
|
<dt>"send":</dt>
|
|
<dd>
|
|
Send one or more outgoing messages
|
|
</dd>
|
|
|
|
<dt>"cancel":</dt>
|
|
<dd>
|
|
Attempt to cancel an outgoing message that has been queued.
|
|
</dd>
|
|
|
|
<dt>"cancel_all":</dt>
|
|
<dd>
|
|
Attempt to cancel all outgoing messages that have been queued.
|
|
</dd>
|
|
|
|
<dt>"log":</dt>
|
|
<dd>
|
|
Display a message in the EnvayaSMS app log.
|
|
</dd>
|
|
|
|
<dt>"settings":</dt>
|
|
<dd>
|
|
Update some of EnvayaSMS's settings.
|
|
</dd>
|
|
|
|
</dl>
|
|
|
|
</dd>
|
|
|
|
</dl>
|
|
|
|
Additional properties for <b>send</b> events:
|
|
|
|
<dl>
|
|
<dt>"messages" ::= <array></dt>
|
|
<dd>An array of messages to send. Each message is an object with the following properties:
|
|
<dl>
|
|
<dt>"id" ::= <string> (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" ::= <string> (optional for incoming, required for outgoing)</dt>
|
|
<dd>
|
|
The phone number to send the SMS to.
|
|
<br />
|
|
<br />
|
|
This may be omitted (null) if the event is sent as a response to action=incoming.
|
|
In this case, the message will be sent as a reply to the original sender.
|
|
</dd>
|
|
<dt>"priority" ::= <integer> (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>
|
|
<dt>"message" ::= <string></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>
|
|
|
|
Additional properties for <b>cancel</b> events:
|
|
|
|
<dl>
|
|
<dt>"id" ::= <string></dt>
|
|
<dd>The ID of the message to cancel sending, previously sent via a "send" event.
|
|
</dl>
|
|
|
|
Additional properties for <b>cancel_all</b> events:
|
|
|
|
<p>(None)</p>
|
|
|
|
Additional properties for <b>log</b> events:
|
|
|
|
<dl>
|
|
<dt>"message" ::= <string></dt>
|
|
<dd>A string to display in the EnvayaSMS log.
|
|
</dl>
|
|
|
|
Additional properties for <b>settings</b> events:
|
|
|
|
<dl>
|
|
<dt>"settings" ::= <object></dt>
|
|
<dd><p>An object where each property name is the name of an EnvayaSMS setting, and each property's value is the new value for that setting.</p>
|
|
<p>The following settings are used within EnvayaSMS:</p>
|
|
|
|
<dl>
|
|
<dd>enabled ::= <boolean></dd>
|
|
<dd>server_url ::= <string></dd>
|
|
<dd>phone_number ::= <string></dd>
|
|
<dd>password ::= <string></dd>
|
|
<dd>outgoing_interval ::= <integer></dd>
|
|
<dd>keep_in_inbox ::= <boolean></dd>
|
|
<dd>call_notifications ::= <boolean></dd>
|
|
<dd>forward_sent ::= <boolean></dd>
|
|
<dd>network_failover ::= <boolean></dd>
|
|
<dd>test_mode ::= <boolean></dd>
|
|
<dd>auto_add_test_number ::= <boolean></dd>
|
|
<dd>ignore_shortcodes ::= <boolean></dd>
|
|
<dd>ignore_non_numeric ::= <boolean></dd>
|
|
<dd>amqp_enabled ::= <boolean></dd>
|
|
<dd>amqp_port ::= <integer></dd>
|
|
<dd>amqp_vhost ::= <integer></dd>
|
|
<dd>amqp_ssl ::= <boolean></dd>
|
|
<dd>amqp_user ::= <string></dd>
|
|
<dd>amqp_password ::= <string></dd>
|
|
<dd>amqp_queue ::= <string></dd>
|
|
<dd>amqp_heartbeat ::= <integer></dd>
|
|
<dd>market_version ::= <integer></dd>
|
|
<dd>market_version_name ::= <string></dd>
|
|
<dd>settings_version ::= <integer></dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h3 id='errors'>HTTP Response Error Format</h3>
|
|
|
|
<p>
|
|
If the phone's HTTP request failed for some reason, the server should return an appropriate HTTP error code (400-499 for client errors, 500-599 for server errors).
|
|
</p>
|
|
|
|
<p>
|
|
To show a detailed error message in the EnvayaSMS app logs, set the content type as <code>application/json</code> and return a JSON object
|
|
as the response body, like so:
|
|
</p>
|
|
<pre>
|
|
{
|
|
"error":{
|
|
"message:"Your error message"
|
|
}
|
|
}
|
|
</pre>
|
|
|
|
<h3 id='amqp'>
|
|
AMQP Message Format
|
|
</h3>
|
|
|
|
<p>
|
|
If you are using AMQP to push outgoing messages and other events to the phone in real time, the content type for each message
|
|
should be <code>application/json</code> and the body of each message should be a serialized JSON object representing a single
|
|
<em>event</em>, as defined in the <a href='/serverapi/#events'>preceding section</a>.
|
|
</p>
|
|
|
|
<h3 id='testing'>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>
|