GettingStarted.adoc

Getting started

Installation

Before start you should add dependency to your Java-based project. For Gradle build system add:

repositories {
    jcenter()
}
dependencies {
    compile 'com.eztexting:eztexting-api-client:X.Y.Z'
}

for Maven build add following lines to your pom xml:

<!-- callfire maven repo -->
<repositories>
    <repository>
        <id>callfire-com</id>
        <name>callfire-com</name>
        <url>http://dl.bintray.com/callfire-com/maven</url>
    </repository>
</repositories>
<!-- dependency -->
<dependencies>
    <dependency>
        <groupId>com.eztexting</groupId>
        <artifactId>eztexting-api-client</artifactId>
        <version>X.Y.Z</version>
    </dependency>
</dependencies>

After these steps eztexting-api-client should appear in your project dependencies along with other transitive ones.

In case you want to build it yourself:

    $ git clone https://github.com/CallFire/eztexting-api-client-java.git
    $ cd eztexting-api-client-java
    $ gradlew build clientFatJar

it will create 4 jars in build/libs directory:

    eztexting-api-client-X.Y.Z.jar
    eztexting-api-client-X.Y.Z-all.jar - client jar with all dependencies inside
    eztexting-api-client-X.Y.Z-javadoc.jar
    eztexting-api-client-X.Y.Z-sources.jar

Overview

To create client instance just provide your account’s login and password. Client uses HTTPS connection. By default it connects to EzTexting site, but you can specify any other related brand: ClubTexting, GroupTexting, TellMyCell, etc.

Example how to get your account’s credit balance:

public class TestEzTextingApi {
    public static void main(String[] args) {
        EzTextingClient client = new EzTextingClient("api_login", "api_password");
        CreditBalance balance = client.creditsApi().checkBalance();
        System.out.println("balance: " + balance);
    }
}

List of API classes:

    EzTextingClient client = new EzTextingClient("api_login", "api_password");
    client.contactsApi(); - add/get/update/delete contacts
    client.creditsApi(); - check balance, buy credits
    client.groupsApi(); - managing contact groups
    client.inboxApi(); - managing your inbox messages and folders
    client.keywordsApi(); - check availability, rent a keyword
    client.mediaLibraryApi(); - managing Media Library files
    client.messagingApi(); - send SMS/MMS/Voice broadcast messages
    client.toolboxApi(); - different helpful APIs, currently it only has a Carrier Lookup operation.

Error handling

The EzTexting Developers API uses standard HTTP response codes for responses. These HTTP codes indicate whether or not an API operation is successful.

Status Code 200 is the desired response code. A standard JSON response will follow.

Codes in the 400s range detail all of the errors a EzTexting Developer could encounter while using the API. Bad Request, Rate Limit Reached, and Unauthorized are some of the sorts of responses in the 400s block.

Codes in the 500s range are error responses from the EzTexting system. If an error has occurred anywhere in the execution of a resource that was not due to user input, a 500 response will be returned with a corresponding JSON error body. In that body will contain a message detailing what went wrong.

All API methods throw following exceptions (all are RuntimeException):

• EzTextingClientException - in case error has occurred in client

• EzTextingApiException - in case API cannot be queried for some reason and server returned error

EzTextingApiException has errors property with details why errors has occurred.

NOTE. Currently some APIs return incorrect response codes, e.g. 403 instead of 400 or 404, this leads to wrong exception. We are working on API fixes.

Debug & logging

In case you want to see requests/responses which client sends/receives from EzTexting platform you should set DEBUG level for com.eztexting package, then you’ll see something like that in your logs:

2015/11/21 19:02:47:355 EEST [DEBUG] RestApiClient - GET request to https://app.eztexting.com/incoming-messages/123?format=json with params: User=winnie&Password=the-pooh
2015/11/21 19:02:48:722 EEST [DEBUG] RestApiClient - received entity
{
	"Response":{
		"Status":"Success",
		"Code":200,
		"Entry": {
			"TYPE":"SMS",
			"ID":123,
			"PhoneNumber":"3312943691",
			"Subject":"",
			"Message":"test",
			"New":true,
			"FolderID":"13",
			"ContactID":"",
			"ReceivedOn":"10-04-2012 9:06 AM"
		}
	}
}

If you don’t have any logger implementation in classpath you can simply use commons-logging SimpleLog which are shipped with EzTexting client. See example of usage below:

System.setProperty("org.apache.commons.logging.Log", "org.apache.commons.logging.impl.SimpleLog");
System.setProperty("org.apache.commons.logging.simplelog.showdatetime", "true");
System.setProperty("org.apache.commons.logging.simplelog.log.com.eztexting", "DEBUG");