Before learning more about ChatON API documentation and samples, make sure you are familiar with ChatON API Terms and Conditions.

The documentation for getting started with ChatON API provides the necessary information you need to get familiar with the ChatON API features. It will also help you to figure out different ways you can utilize them for your own mobile applications:

Step 1: Learn about ChatON API features

With ChatON API, you can integrate various ChatON capabilities into your own applications - invite ChatON buddies to play games together by sending invitation, etc.

ChatON API consists of Server API and Client API:

• Client API allows 3^rd party applications to directly call or invoke a specific functionality provided by ChatON application itself, meaning the 3^rd party application must be installed on a same Android device where ChatON application is already installed.
  3^rd party application can directly invoke specific ChatON Client's UI - prompt buddy selection UI for sending text message and image, etc.
  Client APIs are available to public and do not require any Access Key (unlike Server API).
• With Server API, 3^rd party applications can implement ChatON capabilities from different types of applications such as mobile Web client or mobile native application. Server API is currently offered as closed beta which requires partnership request approval - please refer to Step 2 for details

Step 2: Request API Access key ^[1]

Anyone can use the ChatON Client API for their application, because ChatON Client API are publically available without the API Access Key.

But API Access key for ChatON Server API is only issued for corporate partner. If you need additional Client APIs or are interested in becoming a corporate partner, Please contact us using by 'Partnership Request' menu.
Go to 'PartnershipRequest' menu

^[1] If you’re only using Client APIs, please skip to Step3

Step 3: Design your Application Integration with ChatON API Specification

Review ChatON API specification document and design how your application will utilize ChatON API features or integrate with ChatON application.

Client API

Client API provides 3^rd party applications with features that allows them to communicate with ChatON application via “ChatONAPI.jar”. Please note that ChatON Client API is only available for Android devices currently (iOS version will be available soon).
Client API allows 3^rd party applications to use or invoke some of ChatON application’s features. Therefore, in order to use ChatON Client API, 1) the 3^rd party application must be installed on a same Android device where ChatON application is already installed and 2) the user of the 3^rd party application must be a ChatON service subscriber.

Client API consists of Message API Class, and Utility API Class :

1. Message API Class allows you to invoke ChatON's buddy list and chat room for sending messages.
2. Utility API Class provides features such as, checking whether ChatON application is installed or launch ChatON application download page if otherwise.

With the lower versions of ChatON client, Client APIs may not function properly. To prevent abnormal behavior, users are recommended to have the latest version of ChatON Client installed. You will be able to guide the users to upgrade ChatON Client if "NotAvailableClientAPIException" exception is caught or "ChatONAPI.RESULT_CODE_FAIL_API_NOT_AVAILABLE" error code is returned from the APIs.

API Group	API	Description
Message	Send Text Message	API used to send a Text message to specific buddies.
	Send Text Message With URL	API used to send a Text message with URL to specific buddies.
	Send Multimedia Message	API used to send a Multimedia message to specific buddies.
	Send Multimedia Message With Text	API used to send a Multimedia message with Text message to specific buddies.
	Send Message for 3rd application	API used to send a content with direct link of a 3rd party application, which will allow ChatON users to launch the 3rd party application via the link.
Utility	Is ChatON Installed	API used to check whether ChatON app is already installed.
	Open ChatON Download Page	API used to open a ChatON download page.

Go to Client API specification

Table 1 Client API summary

Server API

Server API is a set of REST APIs that allows 3^rd Party applications to communicate with ChatON API server. The supported communication protocol between 3^rd Party application and ChatON API server is Hypertext Transfer Protocol over Secure Socket Layer (HTTPS) connection. All the requests and responses are in JSON format. Also, when gzip compression is used, it must be indicated within the header.

Server API consists of Connect API group, Graph API group and Message API group :

1. Connect API group provides features to authenticate/authorize users, get information of nearest ChatON API server and register any information related to a 3^rd party application that the user is currently using
2. Graph API group provides features to access Buddy list, buddy profile, my profile.
3. Message API group provides features to send message to ChatON Client, create chat rooms, invite a buddy to a chat room, send a text message, close chat room, and get a list of chat rooms that a user is currently participating in.

Step 4: Implement or Integrate your Application Using ChatON API

Below is an example of using Client API to create sample Android application.

You must have Android programming experience in order to fully understand the steps below. For more information on Android programming, please refer to Android developer’s site
(http://developer.android.com/reference/android/package-summary.html).

Recommended initial flow

When you use ChatON Client API for your application, we recommend you to follow the below steps first.

1. Check if ChatON is installed on the user’s phone before your application calls ChatON Client APIs.
   - Use Is ChatON Installed API
2. If ChatON is not installed, open the ChatON download page where you can download.
   - Use Open ChatON Download Page API

Development environment:

-	Details
Android SDK Version	9 or above
Resolution	all
ChatON Version	v1.10 or above

Developing an Android application

To check the existence of ChatON application in the device using ChatON Client API, please follow below steps:

1. Create a new project.
2. Add ChatONAPI.jar under libs directory in the created project.
   
3. Add a Button in the Main Layout.

   <?xml version="1.0" encoding="utf-8"?>
     <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
       android:layout_width="match_parent"
       android:layout_height="match_parent"
       android:orientation="vertical" >
     
     <Button
       android:id="@+id/buttonIsChatONInstalled"
       android:layout_width="fill_parent"
       android:layout_marginTop="5dip"
       android:layout_height="50dip"
       android:text="Is chaton installed ?"
       android:onClick="clickHandler" />
   
     </LinearLayout>

4. Add clickHandler with following codes.

   public void clickHandler(View v) {
   
     switch(v.getId()) {
       case R.id.buttonIsChatONInstalled:
       // call API
       boolean isInstalled = UtilityAPI.isChatONInstalled(this);
   
       // check result
       if( isInstalled ) {
         Toast.makeText(this, "ChatON is installed !!", Toast.LENGTH_SHORT)
         .show();
       } else {
         Toast.makeText(this, "ChatON is not installed !!", 
         Toast.LENGTH_SHORT).show();
       }
       break;
     }
   }

5. Install and execute the APK created after building the project.
   

The Sample Application also provides below additional features:

Please send technical inquiries or questions to chaton.dev@samsung.com.

Step 5: Register your Application in the Application Market

You can register your application according to the application marketplace’s registration process of your choice. We recommend you to embed ChatON logo as a part your application’s logo. Please refer to the below download link for the logo guidelines.

Download ChatON logo image and guidelines