JMango HTTP REST Documentation

From JMangoWiki

JMango provides HTTP (REST) API to allow easy integration from legacy web scripting platform. Through this interface, external applications can:

  • Authenticate with the account details to obtain authentication token
  • Ping to revalidate the token, authentication token is normally expired after 30 mins.
  • Send JMango application script (Scriplet)
  • Send SMS Text Messages Send SMS text messages to mobile numbers
  • Compile Check if JMango scriptlet is correct and has no error before sending. Note that when calling Send, the scriptlet is also compiled first to check for any compile error.
  • Compile Messages the scriptlet is compiled to the SMS binary messages, based on this application developers can use their own way to send out SMS messages to the mobile devices.
  • Resend Download Message with the link to download JMango mobile client software.
  • Check Sent Status check status of message sent based on the reference of messages returned from the Send action.
  • Check Enabled Status check if the mobile number has been enabled with JMango mobile software.
  • Check Enabled Status For Application check if the mobile number has been enabled to an Application with JMango mobile software.
  • Reset Mobile Software

JMango HTTP API consumes both GET and POST methods in the same manner. Application developers however should avoid using GET method since GET parameter values are usually logged by web servers or proxy servers thus exposing username, password or other message details.

HTTP Status Code is normally 200 (OK) if there is no error, if there is any error occurred during processing of the request, the HTTP response code is Bad Request (302). HTTP response is to be interpreted as plain text data. Content-Type attribute of the response is set to "text/plain".


Contents

[edit]

Authentication

URL http://www.j-mango.com/jmangoservice/rest/authenticate?username=&password=

  • username account's username
  • password account's password

Return

  • If HTTP OK authenticated token ID, otherwise, returns Error code and error message.


[edit]

Ping

URL http://www.j-mango.com/jmangoservice/rest/ping?token=

  • token as returned from the "Authenticate" call.

Return

  • If token valid set HTTP OK (200)
  • Otherwise HTTP is not OK


[edit]

Send

URL http://www.j-mango.com/jmangoservice/rest/send?token=&mobiles=&source=&appname=

  • token as returned from the "Authenticate" call.
  • mobiles comma delimited list of mobile numbers to send JMango scriplet to, each mobile number should be international format without '+' prefix. For example, 61418366896.
  • source the script in text format. This should be escaped correctly based on HTTP URL encoded. JMango interpretes source with new line characters to separated lines in the source code.
  • appname the name of the "Application" context that the scriptlet is to be sent within. The scriplet response data will be returned to the target webapplication, email via this application context. This appname has to be owned by the user who is authenticated against the current token.

Return

  • If HTTP OK (200) returns the sent reference ids
  • If HTTP is not OK returns error code and error message in plain text


[edit]

Send SMS Text Messages

URL http://www.j-mango.com/jmangoservice/rest/sendtextmessage?token=&mobiles=&message=&appname=

  • token as returned from the "Authenticate" call.
  • mobiles comma delimited list of mobile numbers to send JMango scriplet to, each mobile number should be international format without '+' prefix. For example, 61418366896.
  • message Content of SMS text message to be sent out
  • appname the name of the "Application" context that the scriptlet is to be sent within. The scriplet response data will be returned to the target webapplication, email via this application context. This appname has to be owned by the user who is authenticated against the current token.

Return

  • If HTTP OK (200) returns the sent reference ids
  • If HTTP is not OK returns error code and error message in plain text
[edit]

Compile

URL http://www.j-mango.com/jmangoservice/rest/compile?token=&mobiles=&source=&appname=

  • Set of parameters are the same as in Send command.

Return

  • If no error sets HTTP OK (200) and returns number of messages to be
  • Otherwise HTTP is not OK returns error code and error message in plain text


[edit]

Compile Messages

URL http://www.j-mango.com/jmangoservice/rest/compilemessages?token=&mobiles=&source=&appname=

  • Set of parameters are the same as in Send command.

Return

  • If there is any error HTTP is set not OK returns error code and error message in plain text
  • Otherwise sets HTTP OK (200) and data for SMS messages to be sent as binary. Each SMS message is formated per response text line as in the following:

[Mobile Number] [User Data Header bytes] [User Data bytes]

Where "bytes" data is hexadecimal encoded. Such as to represent byte 0x01, the "bytes" data is encoded to "01".


[edit]

Resend Download Message

URL http://www.j-mango.com/jmangoservice/rest/resenddownloadmessage?token=&appname=&mobiles=

  • token as returned from the "Authenticate" call.
  • appname downloading of J-Mango cannot be done independently, it has to be done via a context - application.
  • mobiles comma delimited list of mobile numbers to send JMango scriplet to, each mobile number should be international format without '+' prefix. For example, 61418366896.

Return

  • If no error HTTP OK (200) returns a sent message.
  • Otherwise HTTP is not OK returns error code and error message in plain text
[edit]

Check Sent Status

URL http://www.j-mango.com/jmangoservice/rest/checkstatus?token=&sentref=

  • token as returned from the "Authenticate" call.
  • sentref as returned from the "Send" call.

Return returns a number indicating status of the message

  • 0 submitted but not yet sent.
  • 1 in processing queue
  • 2 being processed
  • 3 delivered successfully
  • 4 there is an error while delivering the message
[edit]

Check Enabled Status

URL http://www.j-mango.com/jmangoservice/rest/checkenabled?token=&mobile=

  • token as returned from the "Authenticate" call.
  • mobile the mobile number to be checked to see if it has JMango mobile software already installed.

Return true or false depending on enabling status.

[edit]

Check Enabled Status For Application

URL http://www.j-mango.com/jmangoservice/rest/checkenabledforapplication?token=&appname=&mobile=

  • token as returned from the "Authenticate" call.
  • mobile and application the mobile number and application context to be checked.

Return

  • If no error HTTP OK (200) returns true or false depending on enabling status.
  • Otherwise HTTP is not OK returns error code and error message in plain text
[edit]

Reset Mobile Software

URL http://www.j-mango.com/jmangoservice/rest/resetmobilesoftware?token=&appname=&mobile=

  • token as returned from the "Authenticate" call.
  • mobile and application the mobile number and application context to be reset.

Return

  • If no error HTTP OK (200) returns reset message.
  • Otherwise HTTP is not OK returns error code and error message in plain text
Retrieved from "http://www.jmango.com.au/jmangowiki/index.php/JMango_HTTP_REST_Documentation"