Welcome to Teamchat SDK’s documentation!

Introduction

Teamchat SDK is a framework for Android, that helps any third party application to easily integrate with Teamchat messaging service. The SDK provides UI elements to display the groups for a user, and also the chat timeline for any selected group. It also supports few UI configurations such as setting different icons, colors, etc. The following sections describe various features of the SDK, such as authentication, getting groups, displaying groups, and chat timeline of a group.

Interface

Initialization

SDK exposes an object called Teamchat. This object provides an object oriented interface to the SDK. You can initialize by supplying an Application ID provided by Teamchat. This method should be called first before calling any other methods.

The following code demonstrates how to initiate Teamchat:

static void initializeWithAppID(String appID, TeamchatInitializationWithAppIDCompletionHandler handler, Context context);

Example:

Teamchat.initializeWithAppID("appID", new Teamchat.TeamchatInitializationWithAppIDCompletionHandler()
{
       @Override
       public void onTeamchatInitializationWithAppIDCompletion(boolean success, String message)
       {
               if(success)
               {
                       //success
               }
               else
               {
                       //error
               }
       }, this
);

Setting up remote notifications

GCM Registration ID should be set, to enable push notifications. Use the following API to setup remote notifications.

The following code demonstrates how to setup remote notifications:

static void setRemoteNotificationsDeviceToken(String regID, Context context);

Example:

Teamchat.setRemoteNotificationsDeviceToken("regID", this);

GCM Registration ID can be obtained using below code.

GoogleCloudMessaging gcm = GoogleCloudMessaging.getInstance(MainActivity.this);
regID = gcm.register("senderID");

Refer below link to set up the app to use GCM.

https://developers.google.com/cloud-messaging/android/client

Login

You can login to Teamchat in 2 ways.

By setting Authentication code, Email ID and UserID and host URL

Setting Authentication code

Before any other API on Teamchat can be called, you need to pass it the authentication code that you have got from a Teamchat authentication service. You can set the authentication code:

static void setAuthenticationCode(String authCode, Context context);
Parameter Type Description
authCode String The authentication code provided by Teamchat Service
context Context Application Context or Activity Context

Example:

static final String authCode = ”AUTH_CODE”;
Teamchat.setAuthenticationCode(authCode, this);
Setting User Email

Before any other API on Teamchat can be called, you need to pass it the user email that you have got from a Teamchat authentication service. You can set the email:

static void setUserEmailID(String emailID, Context context);
Parameter Type Description
emailID String Email ID
context Context Context

Example:

static final String emailID = ”emailID”;
Teamchat.setUserEmailID(emailID, this);
Setting User ID

Before any other API on Teamchat can be called, you need to pass it the user ID that you have got from a Teamchat authentication service. You can set the user id:

static void setUserID(String userID, Context context);
Parameter Type Description
userID String User ID
context Context Context

Example:

static final String userID = ”UserID”
Teamchat.setUserID(userID, this);
Setting Host URL

You can set the host URL using the following API:

static void setHostURL(String hostURL, Context context);
Parameter Type Description
hostURL String Host URL
context Context Context

Example:

Teamchat.setHostURL("HOST_URL", this);

Note:: Make sure the Host URL ends with ‘/’

(For example: http://demo.teamchat.com/)

Teamchat login.

Use the following API to launch login Activity.

static void login(Context context, LoginCompletionHandler handler);

If you set an email using ‘Teamchat.setUserEmailID(emailID, this);’, then the login page will have pre-filled email field without editing support.

Example:

Teamchat.login(LoginActivity.this, new Teamchat.LoginCompletionHandler()
{
       @Override
        public void onLoginCompletion(boolean success, String message)
        {
               if (success)
               {
                       //Success
               }
               else
               {
                       //Failure while logging into Teamchat.
               }
        }
);

Call this method wherever it is appropriate in your application.

_images/Login.png

Initializing Teamchat

After all the above mentioned, required parameters are set, or after successful login, this method should be called before any group creation or UI creation APIs on Teamchat can be called.

static void initWithCompletionHandler(TeamchatStartCompletionHandler handler, Context context);
Parameter Type Description
handler
TeamchatStart
CompletionHandler
Initialization is successfull, ‘success’ will be true.message will convey if any problem was encountered during initialization.
context Context Context

Example:

Teamchat.initWithCompletionHandler(new Teamchat.TeamchatStartCompletionHandler()
{
        @Override
        public void onTeamchatStartCompletionHandler(boolean success, String error, String messaeg)
        {
            if (success)
            {
               //Success
            }
            else
            {
               //Failure while initializing Teamchat.
            }
        }, this
);

While this asynchronous API is in progress, your app might want to show some progress to indicate Teamchat is being initialized.

Setting UI configurations

You can set navigation bar title, Chat Rooms List Item selector, and the chat browser icon in chat window as well as the icon to indicate rich media in the chat window. If you do not call any of these APIs, then the default values will be used.

static void setNavigationTitle(Context context, String title);
static void setChatListItemSelector(R.drawable.bg, this);
static void setMediaIcon(R.mipmap.search_view_close, this);
static void setChatletIcon(R.mipmap.search_view_right_icon, this);

Example:

Teamchat.setNavigationTitle(this, "My Title");
Teamchat.setChatListItemSelector(R.drawable.bg, this);
Teamchat.setMediaIcon(R.mipmap.search_view_close, this);
Teamchat.setChatletIcon(R.mipmap.search_view_right_icon, this);

Getting groups/rooms

You can get list of groups using the rooms API.

static void TeamchatGroups(TeamchatGroupsLoaded handler, Context context);
Parameter Type Description
handler TeamchatGroupsLoaded If success Arraylist of TeamchatGroup Objects will be returned else error will convey if any error occurred
context Context Context

Example:

Teamchat.TeamchatGroups(new Teamchat.TeamchatGroupsLoaded()
{
        @Override
        public void onTeamchatGroupsLoaded(boolean suc, ArrayList<Teamchat.TeamchatGroup> groups, String error)
        {
            if (suc)
            {
               //Success
            }
            else
            {
                //Failure fetching groups
            }
        }, this
);

If no error, groups will be an array list containing TeamchatGroup objects.

The TeamchatGroup object is a light weight object and has the following simple properties:

groupID The identifier of the group as a String
name Name of the room

Creating the chat group using group ID

You can get a specific group using this API.

static void TeamchatGroupWithID(String groupID, TeamchatGroupCompletionHandler handler, Context context)
Parameter Type Description
groupID String Group ID
handler TeamchatGroupCompletionHandler group will the teamchat group on succsess. Error will have the error message in case of failure
context Context Application or Activity context.

Example:

Teamchat.TeamchatGroupWithID("group_id", new Teamchat.TeamchatGroupCompletionHandler()
{
   @Override
   public void onTeamchatGroupCompletion(Teamchat.TeamchatGroup group, String error, String message)
   {

   }
   }, this
);

If no error, a valid group will be returned.

Showing the chat groups list

Use the following API to launch the Chat Groups List Activity:

static void showRoomList(Context context);

Example:

Teamchat.showRoomList(this);

Call this method to launch Chat Groups List Activity wherever it is appropriate in your application.

_images/ChatRooms.png

Showing the chat window for a room

Use this API, to load the chat window for a given Chat Room Id.

static void openRoom(String roomId, Context context);

Example:

Teamchat.openRoom("roomId", this);

Call this method to launch Chat window wherever it is appropriate in your application.

_images/ChatWindow.png

Showing User profile

Use the following API to launch the user profile Activity:

static void showProfile(Context context);

Example:

Teamchat.showProfile(context);

Call this method to launch user profile Activity wherever it is appropriate in your application.

_images/UserProfile.png

Showing Settings Activity

Use the following API to launch the Teamchat settings view:

static boolean showSettings(Context context);

Example:

boolean result = Teamchat.showSettings(this);
if(result)
{
        //Success
}
else
{
        //No active Teamchat session
}

Call this method to launch Settings Activity wherever it is appropriate in your application.

_images/Settings.png

Launching Public groups Activity

Use the following API to launch the Public groups Activity:

static void showPublicGroups(Context context);
Parameter Type Description
context Context Context

Call this method to launch Public groups Activity wherever it is appropriate in your application.

_images/PublicGroups.png

Resetting active Teamchat session

Use this API to reset Teamchat session before creating a new session:

static void resetTeamchatSession(Context context)

Example:

Teamchat.resetTeamchatSession(this);

Setting options to display contacts

The different types of contacts that are supported by Teamchat are:

  1. ShowShowLocalAddressBookContacts - Lists the contacts from phone’s address book.
  2. ShowShowServerAdressBookContacts - List the contacts from Teamchat server in users organisation.
  3. ShowShowCustomAdressBookContacts - List the custom contacts from app contact provider as per AddressBookContactProvider.

The TCCustomAddressBookContact object is a light weight object and has the following simple properties:

profileName Contact display name
email Contact email
phone Contact phone number

AddressBookContactProvider is an interface which provides a method that should return an array list of TCCustomAddressBookContact objects. The interface method is as follows:

ArrayList<TCCustomAddressBookContact> customContacts();

This method should be implemented in the class that conforms to AddressBookContactProvider interface and AddressBookContactProvider can be set using the following API:

static void setCustomAddressBookContactProvider(AddressBookContactProvider customAddressBookContactProvider);

Example:

Teamchat.setCustomAddressBookContactProvider(new Teamchat.AddressBookContactProvider()
{
        @Override
        public ArrayList<Teamchat.TCCustomAddressBookContact> customContacts()
        {
           return ArrayList<Teamchat.TCCustomAddressBookContact>;
        }
});

You can choose the type of contacts that should be listed in contacts list using the following API:

static void setShowContactOptions(EnumSet<ContactType> option)
Parameter Type Description
option EnumSet You can pass an option or a combination of options.

Example:

EnumSet<Teamchat.ContactType> set = = EnumSet.noneOf(Teamchat.ContactType.class);
set.add(Teamchat.ContactType.ShowCustomAdressBookContacts);
Teamchat.setShowContactOptions(set);

Inviting your contacts to Teamchat

You can invite contacts to Teamchat by creating an array of TeamchatInviteContact objects and passing it to the following API:

static void inviteContactsToTeamchat(ArrayList<TeamchatInviteContact> contacts, TeamchatCompletionHandler handler, Context context);
Parameter Type Description
contacts ArrayList An ArrayList of TeamchatInviteContact objects
handler Teamchat Completion Handler If invite is successful, the ‘success’ will be TRUE. Otherwise if it is false error and message will have error description.
context Context Context

Example:

Create TeamchatInviteContact objects as follows:

TeamchatInviteContact invitee1 = new TeamchatInviteContact();
invitee1.name = "John";
invitee1.emailID = "john.bell@gmail.com";

TeamchatInviteContact invitee2 = new TeamchatInviteContact();
invitee2.name = "Kate";
invitee2.emailID = "kate.appleseed@gmail.com";

Create an Arraylist of TeamchatInviteContact objects.

ArrayList<TeamchatInviteContact> inviteContactsArray = new ArrayList<TeamchatInviteContact>;
inviteContactsArray.add(invitee1);
inviteContactsArray.add(invitee2);

Note:

static void initWithCompletionHandler(TeamchatStartCompletionHandler teamchatStartCompletionHandler, Context context) method should be called before calling Invite API.

Teamchat.TeamchatCompletionHandler handler = new Teamchat.TeamchatCompletionHandler()
{
   @Override
   public void onTeamchatCompletion(boolean success, String error, String messaeg)
   {
       // Invite was successful
   }
};
Teamchat.initWithCompletionHandler(new Teamchat.TeamchatStartCompletionHandler()
{
   @Override
   public void onTeamchatStartCompletionHandler(boolean success, String error, String messaeg)
   {
       if (success)
       {
           Teamchat.inviteContactsToTeamchat(inviteContactsArray, handler, this);
       }
   }, this
);

While this asynchronous API is in progress, your app might want to show some progress to indicate Teamchat Invite is in progress.

Getting user info

You can use TeamchatUser class to query about user info like profileName, userEmail, organisation and userID, profileImageURL.

  1. Use the following API to get user’s profile name:

    static String profileName(Context context);
    

This method returns user’s profile name as a String.

Example:

String profileName = TeamChatUser.profileName(this)
  1. Use the following API to get user’s email:

    static String userEmail(Context context);
    

This method returns the user’s emailID as a String.

Example:

String email = TeamChatUser.userEmail(this);
  1. Use the following API to get user’s organisation:

    static String organization(Context context);
    

This method returns the user’s organisation as a String.

Example:

String organization =  TeamChatUser.organization(this)
  1. Use the following API to get user’s ID:

    static String userID(Context context);
    

This method returns the user’s ID as a String.

Example:

String userID = TeamChatUser.userID(this)
  1. Use the following API to get user’s profile image URL:

    static String profileImageURL(Context context);
    

This method returns the user’s profile image URL as a String.

Example:

String profileUrl = TeamChatUser.profileImageURL(this)

Getting the count of unread messages

Use the following API to get the count of unread messages that were received:

static int numberOfUnreadMessages(Context context);

Example:

int unreadMsgCount = Teamchat.numberOfUnreadMessages(this);

Enabling Logs

Use the following API to show the Teamchat logs every time:

static void setLoggingEnabled(boolean loggingEnabled, Context context);

Example:

Teamchat.setLoggingEnabled(true);

Integrating the SDK with your Android app

Method 1:

Place Teamcht.aar file in project’s lib folder and add the following lines to app’s gradle file.:

    android {
   .
   .
   packagingOptions {
      exclude 'META-INF/LICENSE'
      exclude 'META-INF/NOTICE'
      exclude 'META-INF/NOTICE.txt'
      exclude 'META-INF/LICENSE.txt'
   }
   .
   .
}
repositories{
   flatDir{
       dirs 'libs'
   }
}

dependencies {
   .
   .
   compile(name:'Teamchat', ext:'aar')
   .
   .
}
_images/ProjectNavigator.png

Your Gradle file will look something like this

_images/SetUp.png

Method 2:

Follow the below mentioned steps:

Step 1: Right click on project in project structure.

Step 2: Click on New->Module.

Step 3 : Click on Import .Jar or .Aar package.

Step 4 : Click next.

Step 5 : Now browse and select the Teamchat.aar file.

Step 6 : Click Finish. Now the module will be created.

Step 7: Click on project structure and go in dependency section of the module of your app.

Step 8 : Click on plus sign on right side and add teamchat module in the dependencies.

Note:

  1. This SDK uses the following libraries.

    com.android.support:design:23.0.1
    com.android.support:appcompat-v7:23.0.1
    com.google.android.gms:play-services-maps:8.1.0
    com.google.android.gms:play-services-gcm:8.1.0
    aws-android-sdk-2.1.6-autoscaling.jar
    aws-android-sdk-2.1.6-core.jar
    universal-image-loader-1.9.3.jar
    
  2. Make sure to use a theme with no actionbar as your app base theme. Customize this in styles.xml.

    Example: Using Light theme with no actionbar.

    <resources>
           <!-- Base application theme. -->
           <style name="AppTheme" parent="Theme.AppCompat.Light.NoActionBar">
           <!-- Customize your theme here. -->
           </style>
    </resources>
    
  3. To use location services, set up the app to use google maps.

    Refer https://developers.google.com/maps/documentation/android-api/start

  4. To use GCM Push Notification services, set up the app to use GCM.

    Refer https://developers.google.com/cloud-messaging/android/client

  5. SDK uses the following permissions. So no need of including these permissions again in your application Manifest file.

    Network/ internet related

    android.permission.ACCESS_NETWORK_STATE
    android.permission.ACCESS_WIFI_STATE
    android.permission.INTERNET
    android.permission.INTERACT_ACROSS_USERS_FULL
    

    Contacts read and write

    android.permission.READ_CONTACTS
    android.permission.WRITE_CONTACTS
    

    File storage related

    android.permission.WRITE_EXTERNAL_STORAGE
    android.permission.READ_EXTERNAL_STORAGE
    

    Call/ SMS(for verification) related

    android.permission.CALL_PHONE
    android.permission.READ_PHONE_STATE
    android.permission.RECEIVE_SMS
    

    Push notification related

    android.permission.WAKE_LOCK
    com.google.android.c2dm.permission.RECEIVE
    android.permission.VIBRATE
    android.permission.GET_TASKS
    

    Location related

    android.permission.ACCESS_FINE_LOCATION
    android.permission.ACCESS_COARSE_LOCATION
    com.google.android.providers.gsf.permission.READ_GSERVICES
    

    Mic

    android.permission.RECORD_AUDIO
    

    Camera access

    android.permission.CAMERA
    

Set host URL before initializing using the following API. Make sure the url ends with ‘/’ (ex. http://demo.teamchat.com/)

TeamChat.setHostURL("HOST_URL", this);

Now you need to initialize the Teamchat object with appID before making any other API calls.

Teamchat.initializeWithAppID("appID", new Teamchat.TeamchatInitializationWithAppIDCompletionHandler()
{
       @Override
       public void onTeamchatInitializationWithAppIDCompletion(boolean success, String message)
       {
           if (success)
           {
               //Initialized successfully
           }
           else
           {
               //Initialization failed. message is holding the error description.
           }
       }, this
);

Enable remote notifications by setting GCM ID.:

GoogleCloudMessaging gcm = GoogleCloudMessaging.getInstance(MainActivity.this);
regId = gcm.register("your_GCM_SenderId");
Teamchat.setRemoteNotificationsDeviceToken(regId, MainActivity.this);

Refer below link, how to obtain Registration ID.

https://developers.google.com/cloud-messaging/android/client

You can login to Teamchat in two ways:

  1. Set Authentication code, emailID and userID.

    TeamChat.setAuthenticationCode("authenticationCode", this);
    TeamChat.setUserEmailID("userEmailID", this);
    TeamChat.setUserID("userID", this);
    
  2. Launch Teamchat login Activity.

        Teamchat.login(LoginActivity.this, new Teamchat.LoginCompletionHandler()
    {
        @Override
        public void onLoginCompletion(boolean success, String message)
        {
                if (success)
                {
                //Success
            }
            else
            {
                //Failure while logging into Teamchat.
            }
        }
    );
    

If you want to configure UI of the Teamchat screens, you can set them as follows:

Teamchat.setNavigationTitle(this, "My Title");
Teamchat.setChatListItemSelector(R.drawable.bg, this);
Teamchat.setMediaIcon(R.mipmap.search_view_close, this);
Teamchat.setChatletIcon(R.mipmap.search_view_right_icon, this);

To launch the chat groups list Activity, you can use the following API:

    Teamchat.initWithCompletionHandler(new Teamchat.TeamchatStartCompletionHandler()
    {
    @Override
    public void onTeamchatStartCompletionHandler(boolean success, String error, String messaeg)
    {
            if (success)
            {
                    Teamchat.showRoomList(this);
        }
        else
        {
            //error
        }
    }, this
);

Note:

static void initWithCompletionHandler(TeamchatStartCompletionHandler teamchatStartCompletionHandler, Context context) method should be called before launching groups list activity.

To launch the chat window activity, you can use the following API:

Teamchat.initWithCompletionHandler(new Teamchat.TeamchatStartCompletionHandler()
{
    @Override
    public void onTeamchatStartCompletionHandler(boolean success, String error, String messaeg)
    {
            if (success)
            {
            Teamchat.openRoom("group_id", this);
        }
        else
        {
            //error
        }
    }, this
);

Note:

static void initWithCompletionHandler(TeamchatStartCompletionHandler teamchatStartCompletionHandler, Context context) method should be called before launching chat window activity.

To launch the user profile activity, you can use the following API:

Teamchat.initWithCompletionHandler(new Teamchat.TeamchatStartCompletionHandler()
{
    @Override
    public void onTeamchatStartCompletionHandler(boolean success, String error, String messaeg)
    {
            if (success)
        {
            Teamchat.showProfile(this);
        }
        else
        {
            //error
        }
    }, this
);

Note:

static void initWithCompletionHandler(TeamchatStartCompletionHandler teamchatStartCompletionHandler, Context context) method should be called before launching user profile activity.

To launch the public groups activity, you can use the following API:

Teamchat.initWithCompletionHandler(new Teamchat.TeamchatStartCompletionHandler()
{
    @Override
    public void onTeamchatStartCompletionHandler(boolean success, String error, String messaeg)
    {
            if (success)
        {
            Teamchat.showPublicGroups(this);
        }
        else
        {
            //error
        }
    }, this
);

Note:

static void initWithCompletionHandler(TeamchatStartCompletionHandler teamchatStartCompletionHandler, Context context) method should be called before launching public groups activity.

To launch the Teamchat settings activity, you can use the following API:

Teamchat.initWithCompletionHandler(new Teamchat.TeamchatStartCompletionHandler()
    {
            @Override
        public void onTeamchatStartCompletionHandler(boolean success, String error, String messaeg)
        {
            if (success)
            {
                    boolean result = Teamchat.showSettings(this);
                    if(result)
                {
                    //Success
                }
                else
                {
                            //No active Teamchat session
                }
            }
            else
            {
                    //error
            }
        }, this
    );

Note:

static void initWithCompletionHandler(TeamchatStartCompletionHandler teamchatStartCompletionHandler, Context context) method should be called before launching Teamchat settings activity.