JMango Webservice Documentation

From JMangoWiki

JMango webservice SOAP API is available from this URL: jmangoSOAP

This interface allows JMango developers to systematically integrate with JMango gateway via SOAP calls to compile as well as send JMango application messages to the mobile client. The web management interface on the other hand provides quick starting tool to develop JMango application script, view reports of messages as well as applications, manage application routing etc.

This manual gives a generic description of each SOAP method, documentation on compiled API library for Java, .Net and other platforms will be provided separately.

For references on error codes, please refer to Webservice error codes

Contents 1 authenticate 1.1 Description 1.2 Inputs 1.3 Outputs 2 ping 2.1 Description 2.2 Inputs 2.3 Outputs 3 checkMobileEnabled 3.1 Description 3.2 Inputs 3.3 Outputs 4 compileApplication 4.1 Description 4.2 Inputs 4.3 Outputs 5 compileAndSendApplication 5.1 Description 5.2 Inputs 5.3 Outputs 6 checkSentStatus 6.1 Description 6.2 Inputs 6.3 Outputs 7 checkMobileEnabledForApplication 7.1 Description 7.2 Inputs 7.3 Outputs 8 resendDownloadMessage 8.1 Description 8.2 Inputs 8.3 Outputs 9 resetMobileSoftware 9.1 Description 9.2 Inputs 9.3 Outputs 10 sendText 10.1 Description 10.2 Inputs 10.3 Outputs

authenticate

Description

Authenticate a developer user via username and password. An authentication token is returned that can be used in the subsequent web service calls to validate the user.

Inputs

• username is the username of the developer account.
• password is the password of the developer account.

Outputs

• authToken is the authentication token string for the authenticated session. This will be Null if there is any error, i.e. errorCode is not SUCCESS (0)
• errorCode is a number indicating whether there is any error and the type of error if the authentication fails. If this value is 0, the authentication is successful, otherwise, see the error code references.

ping

Description

This call renews the current authentication token for another time out period.

Inputs

• authToken the authentication token to be renewed.

Outputs

• errorCode the error code, 0 means successful while none zero value is an error. See Webservice error codes reference for further details.

checkMobileEnabled

Description

Checks if a mobile number has been registered with JMango gateway. If the mobile number is registered, JMango client software has been installed successfully on this mobile device.

Inputs

• authToken the authentication token for the current session.
• mobileNumber the mobile number to be checked. This cannot be null, otherwise an error code will be returned.

Outputs

• enabled is the boolean value indicating whether the mobile number has been registered with JMango gateway.
• errorCode indicates if there is error, see Webservice error codes

compileApplication

Description

Use this method to compile JMango application script to check if it is compiled successfully as well as checking the number of messages to be sent out as the result.

Inputs

• authToken is the authentication token for the current session.
• source is the text content of the script. This text value should have lines separated by a new line character.
• appName is the name of the application defined in the JMango web management interface. This application name defines the routing for SMS messages to be sent to JMango client.
• countMessages, if set this to true, the number of messages is set in the output parameter numOfMessages

Outputs

• errorCode indicates if there is any error, SUCCESS (0) code indicates no error, see Webservice error codes.
• compileErrors is the comma separated list of errors found when the script source is compiled. Each of the errors should indicate the line that the error occur.
• numOfMessages is the output that is corresponding to the number of SMS messages to be sent for this application script. The value is only meaningful if the countMessages flag was set in the input parameters.

compileAndSendApplication

Description

This method compiles the application script and sends the resulting SMS messages to the mobile numbers as defined in the input parameter. Two types of errors might occur, which are compile error and sent error. The sent references of the SMS messages are returned in the output parameters, developers can check the sent status by subsequent call to checkSentStatus using the sent reference.

Inputs

• authToken, source, appName, destinations: these are the same as input parameter in compileApplication
• destinations this is a comma separated list of all the mobile numbers that the compiled application is to be sent to.

Outputs

• errorCode indicates if there is any error, SUCCESS (0) code indicates no error, see Webservice error codes.
• compileErrors is the comma separated list of errors found when the script source is compiled. Each of the errors should indicate the line that the error occur.
• sentErrors is the comma separated list of errors occurred during sending of messages. There might be sent errors if errorCode is not SUCCESS (0).
• sentReference a comma separated list of sent reference codes for the messages to all the destinations. Each of this reference code can be used in checkSentStatus call to check the progress of the message.
• numOfMessages is the output that is corresponding to the number of SMS messages to be sent for this application script. The value is only meaningful if the countMessages flag was set in the input parameters.

checkSentStatus

Description

This method checks if the progress of the message sent based on the sent reference code. This code is returned as part of other method calls such as sendDownloadLinkToMobiles, compileAndSendApplication, etc..

Inputs

• authToken the authentication token of the current authenticated session.
• sentReference the reference of message sent.

Outputs

• errorCode the error code if the method request is not successful, see Webservice error codes for further details. This is only relevant if it is not SUCCESS (0) code.
• sentStatus the status of message sent. This is one of the following values.
  • 0 is SUBMITTED - message has been submitted to JMango gateway but not yet processed.
  • 1 is QUEUEING - message has been progressed to the queue and waiting to be processed.
  • 2 is PROCESSING - message is being processed.
  • 3 is SENT - message has been processed successfully.
  • 4 is ERROR - message has been processed but there is some error. Details of the error can be accessed via web management interface.
• sentMessage this return value varies depending on the channel of delivery. This should normally be considered as further information on the successfully sent status.

checkMobileEnabledForApplication

Description

The method is used to check if a mobile number is enabled to an application. This is checked based on inbound messages only.

Inputs

• authToken see authenticate method.
• mobileNumber and appName the mobile number and application name user want to check

Outputs

• enabled whether the mobile number is enabled to the application or not
• errorCode this is the generic error code - see Webservice error codes

resendDownloadMessage

Description

This method resend WAPPUSH message with the original download link of JMango mobile client software to the listed mobile numbers.

Inputs

• authToken see authenticate method.
• mobileNumber the mobile number that the WAPPUSH message will be resent to.
• appName the name of application developer want to use in order to send the WAPPUSH message.

Outputs

• errorCode indicates if there is any error, SUCCESS (0) code indicates no error, see Webservice error codes.
• errorMessage the error message that associates with the error code.

resetMobileSoftware

Description

This method is used to reset a mobile number. This means that the system will treat that mobile number as a new client. In the next time a JMango script is sent to the mobile number, a WAPPUSH message will be sent along with script for user to reinstall JMango mobile client software. The functionality is useful in some specific cases (such as user changes mobile phone and still keep the number)

Inputs

• authToken see authenticate method.
• mobileNumber the mobile number that will be reset.
• appName.

Outputs

• errorCode indicates if there is any error, SUCCESS (0) code indicates no error, see Webservice error codes.
• errorMessage the error message that associates with the error code.

sendText

Description

This method is used to send a text message to a list of mobile number.

Inputs

• authToken see authenticate method.
• text content of text message.
• appName the application that developer want to use in order to send text message.
• destinations this is a comma separated list of all the mobile numbers that the text message will be sent to.

Outputs

• errorCode this is the generic error code - see Webservice error codes
• sentErrors a comma separated list of errors occurred during the sending of application download link.
• sentReference a comma separated list of sent reference codes for the text messages to all the destinations. Each of this reference code can be used in checkSentStatus call to check the progress of the message.
• numOfMessages is the total number of messages sent once this call has been executed. In case of no error, this should be equal to the number of destinations set in the inputs.