Smooch API Libraries for Ruby, Python & Java

Ever since we launched the Smooch API, we’ve had developers from the community writing simple wrapper code around it. Early on we built smooch-core-js, a javascript library for both the browser (we use it within Web Messenger) and Node.js servers since we are big Javascript fans and Smooch itself is built on Node.

But not everybody speaks (and loves 🔥 ) Javascript. So we set out to build API libraries for more languages to make it easier for developers to build on the Smooch API in their language of choice.

Today, we’re happy to launch official API libraries for Ruby, Python & Java and you can expect more to come.

Swagger API Specification

Using an API spec & code generators for building our API libraries sounded both attractive and scary. We surveyed the API specification standard landscape and tried RAML, Swagger/OpenAPI & API Blueprint. We choose Swagger for its code generator module, swagger-codegen. Using a code generator was the scary part of the project but swagger-codegen positively surprised us with the quality of the code it generates out of the box code and also with its template system which allowed us to tweak the end result to our liking.

We now have a complete Swagger API specification for Smooch. It lives inside this github repo and we’ll update it with every changes to the API. This means you can watch it to follow and easily be notified when we make changes to the API.

Setup and code samples

Our new libraries were built based on the spec and generated by swagger-codegen. All three come with complete code samples for every API endpoint. Here’s how you can install & use each to send a message including setting up the API authentication.

Ruby

Available as a gem:

sudo gem install smooch-api

require 'smooch-api'

SmoochApi.configure do |config|  
  # Configure API key authorization: jwt
  config.api_key['Authorization'] = 'YOUR JWT'
  config.api_key_prefix['Authorization'] = 'Bearer'
end

api_instance = SmoochApi::ConversationApi.new  
user_id = "user_id_example"

message_post_body = SmoochApi::MessagePost.new  
message_post_body.type = "text"  
message_post_body.text = "hello world"

begin  
  result = api_instance.post_message(user_id, message_post_body)
  p result
rescue SmoochApi::ApiError => e  
  puts "Exception when calling ConversationApi->post_message: #{e}"
end  

Python

Available via pip

sudo pip install smooch

import smooch  
from smooch.rest import ApiException  
from pprint import pprint

smooch.configuration.api_key['Authorization'] = 'YOUR_JWT'  
smooch.configuration.api_key_prefix['Authorization'] = 'Bearer'


api_instance = smooch.ConversationApi()  
user_id = 'user_id_example' 

message_post_body = smooch.MessagePost()  
message_post_body.type = 'text'  
message_post_body.text = 'hello world'

try:  
    api_response = api_instance.post_message(user_id, message_post_body)
    pprint(api_response)
except ApiException as e:  
    print("Exception when calling ConversationApi->post_message: %s\n" % e)

Java

Install via Maven by adding this dependency to your project's POM:

<dependency>  
    <groupId>io.smooch</groupId>
    <artifactId>api</artifactId>
    <version>1.1.0</version>
    <scope>compile</scope>
</dependency>  

For Gradle, add this dependency to your project's build file:

compile "io.smooch:api:1.1.0"

import io.smooch.client.ApiClient;  
import io.smooch.client.ApiException;  
import io.smooch.client.Configuration;  
import io.smooch.client.auth.*;  
import io.smooch.client.api.ConversationApi;

ApiClient defaultClient = Configuration.getDefaultApiClient();

ApiKeyAuth jwt = (ApiKeyAuth) defaultClient.getAuthentication("jwt");  
jwt.setApiKey("YOUR JWT");  
jwt.setApiKeyPrefix("Bearer");

ConversationApi apiInstance = new ConversationApi();  
String userId = "userId_example"; 

MessagePost messagePostBody = new MessagePost();  
messagePostBody.type = "text";  
messagePostBody.text = "hello world"

try {  
    PostMessagesResponse result = apiInstance.postMessage(userId, messagePostBody);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ConversationApi#postMessage");
    e.printStackTrace();
}

What next?

We are very excited to have this new foundational piece for our API. We plan on leveraging it to add libraries for more languages and also build interactive modules for our API reference.

Let us know which language you'd like us to support next and make sure to reach out with any feedback on the spec and these new API libraries or if you need help with our API.