Skip to content
This repository

Tropo Webapi's Java implementation

branch: master
README.md

Tropo Webapi Java

Java library to interact with Tropo's Webapi.

Overview

This is a very lightweight library that will help you to create applications that interact with Tropo from your Java based server. This library offers a type-safe object model that helps you to create requests to Tropo without having to deal with JSON at all. This way, you can minimize the errors that may happen due to invalid JSON being sent or parsed.

Additionally, this library implements the session method from Tropo Rest API which means it can be used from Java web or stand-alone applications to execute remote scripts. For example you can integrate this library with a Java Swing application to do simple but powerful tasks like sending SMS, sending voice calls, transfering calls, etc.

Requirements

Current version is 0.3.1.

License

MIT License

Requirements

You can install this library in any Java application or application server. The library depends primarily on Json-lib and Commons Httpclient. These libraries also depend on other artifacts. The following listing shows all the libraries that need to be present in an application that uses Tropo's Java Webapi:

* commons-beanutils-1.8.1.jar
* commons-collections-3.2.1.jar
* commons-lang-2.5.jar
* commons-logging-1.1.1.jar
* commons-httpclient-3.1.jar
* json-lib-2.4-jdk15.jar
* ezmorph-1.0.6.jar

All libraries have been included in the dist/dependencies folder.

Using the Maven artifact

If you want to use the Maven artifact from your own projects you can add the following dependency to your project's pom.xml:

  <dependency>
    <groupId>com.voxeo.tropo</groupId>
    <artifactId>tropo-webapi-java</artifactId>
    <version>0.3.1</version>
  </dependency>

You will have also to link to our public maven Repository:

  <repositories>
    <repository>
      <id>tropo-public</id>
      <name>Uncle Tropos's Public Maven Repo</name>
      <url>http://maven.tropo.com:8081/nexus/content/groups/public</url>
    </repository>
  </repositories>

You can also check the build status of the project at any time from our public CI server.

Building it from Source

Tropo Java Webapi is based in Maven. Once that you have maven installed you can easily build this library by running the following command from the project's root folder:

mvn package

Examples

You can find loads of examples on how to use this library from the [unit tests folder|https://github.com/tropo/tropo-webapi-java/tree/master/src/test/java]. There is more than 100 different examples there. Below you will find a few examples.

Say Hello and render text to the HTTP Servlet response object:

HttpServletResponse response = ...
Tropo tropo = new Tropo();
tropo.say("1234");
tropo.render(response)

Launch an application (can also be done from stand-alone apps) :

    String token = "bb308b34ed83d54cab226f4af7969e4c7d7d9196cdb3210b5ef0cb345616629005bfd05efe3f4409cd496ca2";
    Tropo tropo = new Tropo();
    TropoLaunchResult result = tropo.launchSession(token);

Launch an application and send some arguments (like for example passing an SMS number to a Tropo hosted file that sends SMS)

    String token = "bb308b34ed83d54cab226f4af7969e4c7d7d9196cdb3210b5ef0cb345616629005bfd05efe3f4409cd496ca2";
    Tropo tropo = new Tropo();
    Map params = new HashMap();
    params.put("number","623767896");
    TropoLaunchResult result = tropo.launchSession(token, params);

With Tropo's Java Webapi you can build Tropo apps with type-safety and traditional Java syntax:

    // Example 1
    Tropo tropo = new Tropo();
    RecordAction record = tropo.record("foo","http://sendme.com/tropo",true,true,"#");
    record.transcription(ID("bling"), URL("mailto:jose@voxeo.com"), EMAIL_FORMAT("encoded"));
    record.say(VALUE("Please say your account number"));
    record.choices(VALUE("[5 DIGITS]"));

    // Example 2
    Tropo tropo = new Tropo();
    tropo.on(EVENT("error"), NEXT("/error.json")); // For fatal programming errors. Log some details so we can fix it
    tropo.on(EVENT("hangup"), NEXT("/hangup.json")); // When a user hangs or call is done. We will want to log some details.
    tropo.on(EVENT("continue"), NEXT("/next.json"));
    tropo.say("Hello");
    tropo.startRecording(URL("http://heroku-voip.marksilver.net/post_audio_to_s3?filename=foo.wav&unique_id=bar"));
    // [From this point, until stop_recording(), we will record what the caller *and* the IVR say]
    tropo.say("You are now on the record.");
    // Prompt the user to incriminate themselve on-the-record
    tropo.say("Go ahead, sing-along.");
    tropo.say("http://denalidomain.com/music/keepers/HappyHappyBirthdaytoYou-Disney.mp3");

    // Example 3
    Tropo tropo = new Tropo();
    tropo.hangup();

At the same time, Tropo's Java Webapi defines a complete DSL to create applications in a much less verbosely manner. You can choose whatever syntax you are more comfortable with:

    // Example 1
    Tropo tropo = new Tropo();
    tropo
        .ask(NAME("foo"),BARGEIN(true),TIMEOUT(30.0f),REQUIRED(true)).and(
            Do.say("Please say your account number"),
            Do.on(EVENT("success"),NEXT("/result.json")),
            Do.choices(VALUE("[5 DIGITS]")));

    // Example 2
    Tropo tropo = new Tropo();
    tropo
        .conference(NAME("foo"),ID("1234"),MUTE(false),SEND_TONES(false),EXIT_TONE("#")).and(
            Do.on(EVENT("join")).say("Welcome to the conference")
        );

    // Example 3
    Tropo tropo = new Tropo();
    tropo.call(TO("foo"), FROM("bar"), NETWORK(Network.SMS), CHANNEL(Channel.TEXT), TIMEOUT(10.0f), ANSWER_ON_MEDIA(false)).and(
        Do.headers(new String[]{"fooKey","fooValue"}, new String[]{"barKey","barValue"}),
        Do.startRecording(URL("http://foobar"), METHOD("POST"), FORMAT(Format.MP3), USERNAME("jose"), PASSWORD("passwd")));

    // Example 4
    Tropo tropo = new Tropo();
    tropo.message(TO("foo"), FROM("bar"), NETWORK(Network.SMS), CHANNEL(Channel.TEXT), TIMEOUT(10.0f), ANSWER_ON_MEDIA(false)).and(
        Do.headers(new String[]{"fooKey","fooValue"}, new String[]{"barKey","barValue"}),
        Do.startRecording(URL("http://foobar"), METHOD("POST"), FORMAT(Format.MP3), USERNAME("jose"), PASSWORD("passwd")),
        Do.say("Please say your account number"));

Below you can also find a very trivial servlet POST method:

protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {

    Tropo tropo = new Tropo();
    tropo.say("Hello from Tropo. This is our first application.");
    tropo.render(response);
}

And of course, you can read Tropo's session from the request and use it in your Java apps. Again, no Json knowledge required!

protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {

    Tropo tropo = new Tropo();
    TropoSession session = tropo.session(request);
    System.out.println("Call id: " + session.getCallId());
}
Something went wrong with that request. Please try again.