uk.co.textmarketer.RestAPI
Class RestClient

java.lang.Object
  uk.co.textmarketer.RestAPI.RestClient

public class RestClient
extends java.lang.Object

The RESTful API is an advanced version of the simple SMS API giving you greater flexibility with enhanced tools and services. As with all our developer solutions, we also offer support if you have any integration questions.

RESTful API

Copyright © 2012 Text Marketer Ltd

Client class to access Text Marketer RESTful API

Version:

1.3

Author:

Marco Morais

Field Summary

static boolean	ENV_PRODUCTION
static boolean	ENV_SANDBOX

Constructor Summary

RestClient(java.lang.String username, java.lang.String password, boolean env)
Constructor for the RestClient class.

Method Summary

boolean	addGroup(java.lang.String group) Create a new group.
int	addNumbersToGroup(java.lang.String group, java.lang.String numbers) Add a number/numbers to a 'send group' (excluding 'merge' groups).
java.util.Hashtable<java.lang.String,java.lang.String>	createSubAccount(java.lang.String companyName, java.lang.String notificationMobile, java.lang.String notificationEmail, java.lang.String username, java.lang.String password, java.lang.String promoCode, boolean overrideRates) Create a new account (requires additional permissions on your account, please contact Text Marketer to apply)
java.util.Hashtable<java.lang.String,java.lang.String>	deleteSMS(java.lang.String scheduled_id) Delete a scheduled text message.
int	getCredits() Get the number of credits currently available on your account.
DeliveryReport[]	getDeliveryReport(java.lang.String name) Retrieve individual delivery report shows the current known status of all messages sent on a given day, or for a particular campaign.
DeliveryReport[]	getDeliveryReport(java.lang.String name, java.util.Date start, java.util.Date end) Retrieve individual delivery report shows the current known status of all messages sent on a given day, or for a particular campaign.
DeliveryReport[]	getDeliveryReport(java.lang.String name, java.lang.String custom) Retrieve individual delivery report shows the current known status of all messages sent on a given day, or for a particular campaign.
DeliveryReport[]	getDeliveryReport(java.lang.String name, java.lang.String custom, java.util.Date start, java.util.Date end) Retrieve individual delivery report shows the current known status of all messages sent on a given day, or for a particular campaign.
java.lang.String[]	getDeliveryReports() Retrieve a list of available delivery report names.
java.lang.String[]	getGroup(java.lang.String group) Get all the numbers in the group, if there are any.
java.util.Hashtable<java.lang.String,java.lang.String>[]	getGroups() Get a list of available 'send groups' - pre-defined groups containing a list of mobile numbers to send a message to.
java.util.Hashtable<java.lang.String,java.lang.String>	getKeyword(java.lang.String keyword) Get the availability of a given reply keyword.
int	getLastErrorCode() Return the last error code raised from the last RestClient call
java.lang.String	getLastErrorMessage() Return the last error message raised from the last RestClient call
java.util.Hashtable<java.lang.String,java.lang.String>	getLastErrors() Return the all the errors raised from the last RestClient call
java.lang.String	getXML() Return the last xml string returned from the last RestClient call
boolean	isLoginValid() Make a call to TM Rest API Gateway to test if the username and password are correct.
java.util.Hashtable<java.lang.String,java.lang.String>	sendSMS(java.lang.String message, java.lang.String mobile_number, java.lang.String originator, int validity, java.lang.String email, java.lang.String custom, java.util.Date schedule) Send a text message to the specified recipient.
java.util.Hashtable<java.lang.String,java.lang.String>	transferCreditsToAccount(int quantity, java.lang.String target) Transfer credits from one account to another account, using the account number for the target.
java.util.Hashtable<java.lang.String,java.lang.String>	transferCreditsToUser(int quantity, java.lang.String target_username, java.lang.String target_password) Transfer credits from one account to another account, using the username for the target.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ENV_SANDBOX

public static final boolean ENV_SANDBOX

See Also:

Constant Field Values

ENV_PRODUCTION

public static final boolean ENV_PRODUCTION

See Also:

Constant Field Values

Constructor Detail

RestClient

public RestClient(java.lang.String username,
                  java.lang.String password,
                  boolean env)

Constructor for the RestClient class.

Parameters:

username - your API Gateway Username

password - your API Gateway Password

env - possible values RestClient.ENV_SANDBOX or RestClient.ENV_PRODUCTION

Example:

RestClient tmClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);

Method Detail

isLoginValid

public boolean isLoginValid()
                     throws RestClientException

Make a call to TM Rest API Gateway to test if the username and password are correct.

Returns:

boolean TRUE if login valid, FALSE if username or password not correct

Throws:

RestClientException - on error

Example:

RestClient tmClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
    if(tmClient.isLoginvalid())
        System.out.println("Login is OK!");
} catch(RestClientException e) {
    System.out.println(e.getMessage());
}

getCredits

public int getCredits()
               throws RestClientException

Get the number of credits currently available on your account.

Returns:

number of credits currently available on your account.

Throws:

RestClientException - on error

Example:

RestClient tmClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
    credits = tmClient.getCredits();
    System.out.println("Account have " + credits + " credits.");
} catch(RestClientException e) {
    System.out.println(e.getMessage());
}

sendSMS

public java.util.Hashtable<java.lang.String,java.lang.String> sendSMS(java.lang.String message,
                                                                      java.lang.String mobile_number,
                                                                      java.lang.String originator,
                                                                      int validity,
                                                                      java.lang.String email,
                                                                      java.lang.String custom,
                                                                      java.util.Date schedule)
                                                               throws RestClientException

Send a text message to the specified recipient. GSM character set

Parameters:

message - The textual content of the message to be sent. Up to 612 characters from the GSM alphabet. The SMS characters we can support is documented at GSM character set. Please ensure that data is encoded in UTF-8.

mobile_number - The mobile number of the intended recipient, in international format, e.g. 447777123123. Only one number is allowed. To send a message to multiple recipients, you must call the API for each number.

originator - A string (up to 11 alpha-numeric characters) or the international mobile number (up to 16 digits) of the sender, to be displayed to the recipient, e.g. 447777123123 for a UK number.

validity - An integer from 1 to 72, indicating the number of hours during which the message is valid for delivery. Messages which cannot be delivered within the specified time will fail.

email - Optional. Available to txtUs Plus customers only. Specifies the email address for incoming responses. If you specify an email address, you must specify an originator that is a txtUs Plus number that is on your account, or you will get an error response.

custom - Optional. An alpha-numeric string, 1-20 characters long, which will be used to 'tag' your outgoing message and will appear in delivery reports, thus facilitating filtering of reports.

schedule - Optional. Date parameter to schedule the message to send at a given time.

Returns:

Hash table with keys: message_id, scheduled_id, credits_used and status

Throws:

RestClientException - on error

Example:

RestClient tmClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
    Hashtable result = tmClient.sendSMS("Hello SMS World!", "447777123123", "Hello World", 72, "", "");
    System.out.println("Used " + result.get("credits_used") + " Credits, ID: " + result.get("message_id") + ",  Scheduled ID: " + result.get("scheduled_id") + ", Status: " + result.get("status"));
} catch(RestClientException e) {
    System.out.println(e.getMessage());
}

transferCreditsToAccount

public java.util.Hashtable<java.lang.String,java.lang.String> transferCreditsToAccount(int quantity,
                                                                                       java.lang.String target)
                                                                                throws RestClientException

Transfer credits from one account to another account, using the account number for the target.

Parameters:

quantity - The number of credits to transfer from the source account to the target account.

target - The account number of the account to transfer the credits to

Returns:

Hash table with keys: source_credits_before, source_credits_after, target_credits_before and target_credits_after

Throws:

RestClientException - on error

Example:

RestClient tmClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
    Hashtable result = tmClient.transferCreditsToAccount(3, "902");
    System.out.println("Transfered 3 Credits (have " + result.get("source_credits_after") + " now), to account 902, now with " + result.get("target_credits_after") + "Credits");
} catch(RestClientException e) {
    System.out.println(e.getMessage());
}

transferCreditsToUser

public java.util.Hashtable<java.lang.String,java.lang.String> transferCreditsToUser(int quantity,
                                                                                    java.lang.String target_username,
                                                                                    java.lang.String target_password)
                                                                             throws RestClientException

Transfer credits from one account to another account, using the username for the target.

Parameters:

quantity - The number of credits to transfer from the source account to the target account.

target_username - The username of the account to transfer the credits to.

target_password - The password of the account to transfer the credits to.

Returns:

Hash table with keys: source_credits_before, source_credits_after, target_credits_before and target_credits_after

Throws:

RestClientException - on error

Example:

RestClient tmClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
    Hashtable result = tmClient.transferCreditsToUser(3, "targetusername", "targetuserpass");
    System.out.println("Transfered 3 Credits (have " + result.get("source_credits_after") + " now), to account targetusername, now with " + result.get("target_credits_after") + "Credits");
} catch(RestClientException e) {
    System.out.println(e.getMessage());
}

getKeyword

public java.util.Hashtable<java.lang.String,java.lang.String> getKeyword(java.lang.String keyword)
                                                                  throws RestClientException

Get the availability of a given reply keyword.

A reply keyword allows you receive incoming text messages to your account by providing people with a keyword, which they text to the short code 88802, e.g. text 'INFO' to 88802 to see this in action.

Parameters:

keyword - The keyword to check is availability

Returns:

Hash table with keys: available and recycle.

Throws:

RestClientException - on error

Example:

RestClient tmClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
    Hashtable result = tmClient.getKeyword("gold");
    System.out.println("The 'gold' keyword is available (" + result.get("available") + "), recycled ("+ result.get("recycle") + ")");
} catch(RestClientException e) {
    System.out.println(e.getMessage());
}

getGroups

public java.util.Hashtable<java.lang.String,java.lang.String>[] getGroups()
                                                                   throws RestClientException

Get a list of available 'send groups' - pre-defined groups containing a list of mobile numbers to send a message to.

Also lists 'stop groups' - numbers in these groups will never be sent messages.

Every account has at least one stop group, so that your recipients can always opt out of receiving messages from you. This is a legal requirement.

Returns:

Hash table array, each hash table with keys: id, numbers, name and is_stop.

Throws:

RestClientException - on error

Example:

RestClient tmClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
    Hashtable[] result = tmClient.getGroups();
    for(Hashtable group: result) {
        System.out.println("Group ID: " + group.get("id"));
        System.out.println("Group numbers: " + group.get("numbers"));
        System.out.println("Group name: " + group.get("name"));
        System.out.println("Group IS STOP: " + group.get("is_stop"));
    }
} catch(RestClientException e) {
    System.out.println(e.getMessage());
}

getGroup

public java.lang.String[] getGroup(java.lang.String group)
                            throws RestClientException

Get all the numbers in the group, if there are any.

Parameters:

group - Group name or group ID to get the numbers of

Returns:

array of String with the numbers of the group

Throws:

RestClientException - on error

Example:

RestClient tmClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
    String[] numbers = tmClient.getGroup("directors");
    for(String number: numbers)
        System.out.println("Number: " + number);
} catch(RestClientException e) {
    System.out.println(e.getMessage());
}

addNumbersToGroup

public int addNumbersToGroup(java.lang.String group,
                             java.lang.String numbers)
                      throws RestClientException

Add a number/numbers to a 'send group' (excluding 'merge' groups).

Parameters:

group - name or group ID to add the numbers to

numbers - The MSISDN (mobile number) you wish to add, if you want to add more then one use a comma delimited list

Returns:

Return the number of added numbers to the selected group

Throws:

RestClientException - on error

Example:

RestClient tmClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
    int numAdded = tmClient.addNumbersToGroup("My Group", "447777000001,447777000002,44777700000");
    System.out.println("Added " + numAdded + " to My Group");
} catch(RestClientException e) {
    System.out.println(e.getMessage());
}

addGroup

public boolean addGroup(java.lang.String group)
                 throws RestClientException

Create a new group.

Parameters:

group - the new Group name to be created

Returns:

Return true if the group is added with success

Throws:

RestClientException - on error

Example:

RestClient tmClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
    if(tmClient.addGroup("New Group"))
        System.out.println("'New Group' added with success.");
} catch(RestClientException e) {
    System.out.println(e.getMessage());
}

getDeliveryReports

public java.lang.String[] getDeliveryReports()
                                      throws RestClientException

Retrieve a list of available delivery report names.

Returns:

String array with all the reports names

Throws:

RestClientException - on error

Example:

RestClient tmClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
    String[] reports = tmClient.getDeliveryReports();
    for(String report: reports)
        System.out.println("Report name: " + report);
} catch(RestClientException e) {
    System.out.println(e.getMessage());
}

getDeliveryReport

public DeliveryReport[] getDeliveryReport(java.lang.String name)
                                   throws RestClientException

Retrieve individual delivery report shows the current known status of all messages sent on a given day, or for a particular campaign.

Whereas the function getDeliveryReports() gets a list of available delivery report names, including delivery reports for campaigns.

Parameters:

name - Name of the delivery report to retrieve or 'all' to retrieve all campaign/API report data

Returns:

DeliveryReport object array

Example:

RestClient tmClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
    DeliveryReport[] reports = tmClient.getDeliveryReport("all");
    for(DeliveryReport report: reports) {
        System.out.println(report);
        for(Hashtable row: report.getRows()) {
            System.out.println("\tMessage ID: " + row.get("message_id"));
            System.out.println("\tLast Updated: " + row.get("last_updated"));
            System.out.println("\tMobile Number: " + row.get("mobile_number"));
            System.out.println("\tStatus: " + row.get("status"));
            System.out.println("\tCustom Tag: " + row.get("custom"));
        }
    }
} catch(RestClientException e) {
    System.out.println(e.getMessage());
}

Throws:

RestClientException

getDeliveryReport

public DeliveryReport[] getDeliveryReport(java.lang.String name,
                                          java.lang.String custom)
                                   throws RestClientException

Retrieve individual delivery report shows the current known status of all messages sent on a given day, or for a particular campaign.

Whereas the function getDeliveryReports() gets a list of available delivery report names, including delivery reports for campaigns.

Parameters:

name - Name of the delivery report to retrieve or 'all' to retrieve all campaign/API report data

custom - Can specify a custom 'tag', which will restrict the search to those messages

Returns:

DeliveryReport object array

Example:

RestClient tmClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
    DeliveryReport[] reports = tmClient.getDeliveryReport("all", "test");
    for(DeliveryReport report: reports) {
        System.out.println(report);
        for(Hashtable row: report.getRows()) {
            System.out.println("\tMessage ID: " + row.get("message_id"));
            System.out.println("\tLast Updated: " + row.get("last_updated"));
            System.out.println("\tMobile Number: " + row.get("mobile_number"));
            System.out.println("\tStatus: " + row.get("status"));
            System.out.println("\tCustom Tag: " + row.get("custom"));
        }
    }
} catch(RestClientException e) {
    System.out.println(e.getMessage());
}

Throws:

RestClientException

getDeliveryReport

public DeliveryReport[] getDeliveryReport(java.lang.String name,
                                          java.util.Date start,
                                          java.util.Date end)
                                   throws RestClientException

Retrieve individual delivery report shows the current known status of all messages sent on a given day, or for a particular campaign.

Whereas the function getDeliveryReports() gets a list of available delivery report names, including delivery reports for campaigns.

Parameters:

name - Name of the delivery report to retrieve or 'all' to retrieve all campaign/API report data

start - Get delivery report from start Date

end - Get delivery report to end Date

Returns:

DeliveryReport object array

Example:

RestClient tmClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
    // Get all reports from Year 2012
    Calendar cal = Calendar.getInstance();
    cal.set(2012, 1, 1);
    DeliveryReport[] reports = tmClient.getDeliveryReport("all", cal.getTime(), new Date());
    for(DeliveryReport report: reports) {
        System.out.println(report);
        for(Hashtable row: report.getRows()) {
            System.out.println("\tMessage ID: " + row.get("message_id"));
            System.out.println("\tLast Updated: " + row.get("last_updated"));
            System.out.println("\tMobile Number: " + row.get("mobile_number"));
            System.out.println("\tStatus: " + row.get("status"));
            System.out.println("\tCustom Tag: " + row.get("custom"));
        }
    }
} catch(RestClientException e) {
    System.out.println(e.getMessage());
}

Throws:

RestClientException

getDeliveryReport

public DeliveryReport[] getDeliveryReport(java.lang.String name,
                                          java.lang.String custom,
                                          java.util.Date start,
                                          java.util.Date end)
                                   throws RestClientException

Retrieve individual delivery report shows the current known status of all messages sent on a given day, or for a particular campaign.

Whereas the function getDeliveryReports() gets a list of available delivery report names, including delivery reports for campaigns.

Parameters:

name - Name of the delivery report to retrieve or 'all' to retrieve all campaign/API report data

custom - Can specify a custom 'tag', which will restrict the search to those messages

start - Get delivery report from start Date

end - Get delivery report to end Date

Returns:

DeliveryReport object array

Example:

RestClient tmClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
    // Get all reports from Year 2012 with the custom tag 'test'
    Calendar cal = Calendar.getInstance();
    cal.set(2012, 1, 1);
    DeliveryReport[] reports = tmClient.getDeliveryReport("all", "test", cal.getTime(), new Date());
    for(DeliveryReport report: reports) {
        System.out.println(report);
        for(Hashtable row: report.getRows()) {
            System.out.println("\tMessage ID: " + row.get("message_id"));
            System.out.println("\tLast Updated: " + row.get("last_updated"));
            System.out.println("\tMobile Number: " + row.get("mobile_number"));
            System.out.println("\tStatus: " + row.get("status"));
            System.out.println("\tCustom Tag: " + row.get("custom"));
        }
    }
} catch(RestClientException e) {
    System.out.println(e.getMessage());
}

Throws:

RestClientException

createSubAccount

public java.util.Hashtable<java.lang.String,java.lang.String> createSubAccount(java.lang.String companyName,
                                                                               java.lang.String notificationMobile,
                                                                               java.lang.String notificationEmail,
                                                                               java.lang.String username,
                                                                               java.lang.String password,
                                                                               java.lang.String promoCode,
                                                                               boolean overrideRates)
                                                                        throws RestClientException

Create a new account (requires additional permissions on your account, please contact Text Marketer to apply)

Parameters:

companyName - The company name for the new account owner

notificationMobile - (Optional*) the mobile number of the account (*required if notificationEmail is not set)

notificationEmail - (Optional*) the email address of the account (*required if notificationMobile is not set)

username - (Optional) the username you wish to set on the new account - the API username will be the same

password - (Optional) the password you wish to set on the new account - the API password will be the same

promoCode - (Optional) a promotional code entitling the account to extra credits

overrideRates - If set to true, use the credits rates set on your main account (the account used to access the API), rather than the Text Marketer defaults.

Returns:

Hash table with keys: account_id, company_name, create_date, credits, notification_email, notification_mobile, username, api_username and api_password

Throws:

RestClientException -

Example:

RestClient tmClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
    Hashtable result = tmClient.createSubAccount("my subaccount", "44123456789", null, "subusername", "subpassword", null, false);
    System.out.println("Account ID: " + result.get("account_id"));
    System.out.println("Company Name: " + result.get("company_name"));
    System.out.println("Create Date: " + result.get("create_date"));
    System.out.println("Credits: " + result.get("credits"));
    System.out.println("Notification Email: " + result.get("notification_email"));
    System.out.println("Notification Mobile: " + result.get("notification_mobile"));
    System.out.println("Username: " + result.get("username"));
    System.out.println("Password: " + result.get("password"));
    System.out.println("API Username: " + result.get("api_username"));
    System.out.println("API Password: " + result.get("api_password"));
} catch(RestClientException e) {
    System.out.println(e.getMessage());
}

getXML

public java.lang.String getXML()

Return the last xml string returned from the last RestClient call

Returns:

Xml string from the last call to RestClient API

Example:

RestClient tmClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
    tmClient.getGroup("directors");
    xml = tmClient.getXML();
    System.out.println(xml);
} catch(RestClientException e) {
    System.out.println(e.getMessage());
}

getLastErrorCode

public int getLastErrorCode()

Return the last error code raised from the last RestClient call

Returns:

Error code integer or 0 if there is no error

getLastErrorMessage

public java.lang.String getLastErrorMessage()

Return the last error message raised from the last RestClient call

Returns:

Error message String or "" if there is no error

getLastErrors

public java.util.Hashtable<java.lang.String,java.lang.String> getLastErrors()

Return the all the errors raised from the last RestClient call

Returns:

Errors Hashtable with all the errors codes and messages

Example:

RestClient tmClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
    credits = tmClient.getCredits();
    System.out.println("Account have " + credits + " credits.");
} catch(RestClientException e) {
    Hashtable errors = tmClient.getLastErrors();
    for(Map.Entry error: errors.entrySet())
        System.out.println("Error code " + error.getKey() + ": " + error.getValue());
}

deleteSMS

public java.util.Hashtable<java.lang.String,java.lang.String> deleteSMS(java.lang.String scheduled_id)
                                                                 throws RestClientException

Delete a scheduled text message.

Parameters:

scheduled_id - The id of the scheduled text message, as returned by the sendSMS method.

Returns:

Hash table with keys: scheduled_id and status

Throws:

RestClientException - on error

Example:

RestClient tmClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
    Hashtable result = tmClient.deleteSMS();
    System.out.println("Scheduled ID:  " + result.get("scheduled_id") + ", Status: " + result.get("status"));
} catch(RestClientException e) {
    System.out.println(e.getMessage());
}