EnvayaSMS communicates with the server via HTTP POST requests that expect an XML response.
For convenience, EnvayaSMS includes server libraries and example code for certain languages to simplify handling its POST requests and generating response XML.
Drupal users can also install the Drupal module (developed by Mark Burdett / VozMob).
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!
The EnvayaSMS Request Simulator is a standalone HTML file that allows you to simulate EnvayaSMS's HTTP requests entirely in your browser via JavaScript.
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.
In each of the example requests below, the Server URL is http://192.168.70.1:3000/sg/app
and the phone number of the phone with EnvayaSMS is 16505551212.
An incoming SMS from 6505551234 with message body "test":
POST /sg/app HTTP/1.1 X-Request-Signature: sAemG31uRllk/K9xck2WRNaF/WI= Content-Length: 140 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&age=23&network=WIFI×tamp=1317506831000
An incoming MMS message with an image/jpeg part and a text/plain part with message 'Test':
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
<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>
--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
BINARY IMAGE DATA
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RG--
Checking for outgoing SMS messages:
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
Notifying the server of the status of a sent message:
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
The following parameters are sent in all POST requests from EnvayaSMS:
https:// protocol.)
"<serverURL>,<name1>=<value1>,<...>,<nameN>=<valueN>,<password>"
action=incoming:
text/plain 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.)
action=incoming and message_type=mms:
<img region="Image" src="cid:805"/>).
"Image001.jpg".
mms_parts field. Text parts are encoded in UTF-8.
action=outgoing:
action=send_status:
id attribute
of an sms tag in a previous XML response from the server).
action=device_status:
For a successful request, the server should return HTTP status code 200.
Failed requests should return HTTP status codes between 400 and 499 inclusive.
Failed requests may optionally return an error message to display in the phone logs, as
a text/xml response like <response><error>...</error></response>
HTTP/1.1 200 OK Content-Type: text/xml Content-Length: 212 <?xml version='1.0' encoding='UTF-8'?> <response> <messages> <sms id='1540' to='16505551213'>This is a test</sms> <sms id='1541' to='16505551214'>This is a another test message.</sms> </messages> </response>Specification:
The Content-Type header should be text/xml, with the content as follows:
HTTP/1.1 200 OK Content-Type: text/plain Content-Length: 2 OK
HTTP status code 200 signifies success, and anything else signifies failure.
The response content for successful send_status requests is currently ignored, except that
requests with HTTP code 400-499 may return an error message as text/xml.