CallFire API v2.0 Java SDK

Requirements:

Dependencies:

Project page

Getting started

Installation

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


dependencies {
    compile 'com.callfire:callfire-api-client:X.Y.Z'
}

for Maven build add following lines to your pom xml:


<dependencies>
    <dependency>
        <groupId>com.callfire</groupId>
        <artifactId>callfire-api-client</artifactId>
        <version>X.Y.Z</version>
    </dependency>
</dependencies>

where X.Y.Z - current available version, you can find it on releases page After these steps callfire-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/callfire-api-client-java.git
    $ cd callfire-api-client-java
    $ gradlew build clientFatJar

it will create 4 jars in build/libs directory:

    callfire-api-client-X.Y.Z.jar - only client classes without dependencies
    callfire-api-client-X.Y.Z-all.jar - client jar with all dependencies inside
    callfire-api-client-X.Y.Z-javadoc.jar
    callfire-api-client-X.Y.Z-sources.jar

Overview

To create client instance just provide API login and password. API credentials should be configured on Account -> Settings -> API Access page. Client uses HTTPS connection and Basic Authentication.

Example how to get account information using client:

public class TestCallfireApi {
    public static void main(String[] args) {
        CallfireClient client = new CallfireClient("api_login", "api_password");
        Account account = client.meApi().getAccount();
        System.out.println(account);
    }
}

.List of API classes:

    CallfireClient client = new CallfireClient("api_login", "api_password");
    client.meApi();
    client.ordersApi();
    client.keywordsApi();
    client.keywordLeasesApi();
    client.numbersApi();
    client.numberLeasesApi();
    client.agentsApi();
    client.agentGroupsApi();
    client.batchesApi();
    client.callsApi();
    client.textsApi();
    client.mediaApi();
    client.campaignSoundsApi();
    client.ivrBroadcastsApi();
    client.callBroadcastsApi();
    client.textBroadcastsApi();
    client.textAutoRepliesApi();
    client.contactsApi();
    client.contactListsApi();
    client.dncApi();
    client.dncListsApi();
    client.webhooksApi();

Error handling

The CallFire 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 CallFire 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 CallFire 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):

CallfireApiException has apiErrorMessage property with details of occurred error, here is fields listing:

    Integer httpStatusCode;
    Integer internalCode;
    String message;
    String developerMessage;
    String helpLink;

Configuration

Proxy

Starting from version 1.7.3 users have possibility to make API calls go through proxy, here is an example how to configure it:

        CallfireClient.getClientConfig().put(ClientConstants.PROXY_ADDRESS_PROPERTY, "localhost:3128");
        CallfireClient.getClientConfig().put(ClientConstants.PROXY_CREDENTIALS_PROPERTY, "proxyuser:proxypass");
        // now create client
        CallfireClient client = new CallfireClient("api_user", "api_pass");
        System.out.println("Account" + client.meApi().getAccount());

IMPORTANT. You must add proxy address property and proxy credentials (if needed) before client instantiation!

Proxy address port is optional, 8080 is used by default.

Debug & logging

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

2015/10/21 19:02:47:355 EEST [DEBUG] RestApiClient - GET request to https://api.callfire.com/v2/me/account with params: []
2015/10/21 19:02:48:722 EEST [DEBUG] RestApiClient - received entity
{
  "id" : 1234567890,
  "email" : "john@callfire.com",
  "name" : "test",
  "firstName" : "John",
  "lastName" : "Doe",
  "permissions" : [ "ACCOUNT_HOLDER" ]
}

If you don't have any logger implementation in classpath you can simply use commons-logging SimpleLog which are shipped with Callfire 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.org.apache", "DEBUG");
System.setProperty("org.apache.commons.logging.simplelog.log.com.callfire", "DEBUG");