Channelize API SDK Integration

Channelize-API SDK

The following documentation is built to help you with integration of our iOS API SDK into your project.

Dependencies

Requirements Before we begin, please do make sure that

Your application is built on iOS 9.0 or above.
Since Channelize SDK as of now only supports Version 9.0 or higher.
You have Xcode 9.4.1 or later as your IDE to install and run Channelize SDK on iOS.
Swift 4 / 4.1 / 4.2

Pod Installation

If you've never used CocoaPods for a Xcode project, open a terminal window, move to your project directory, and then create a Podfile by running the following command.

pod init

Add the following lines to the Podfile.

platform :ios, '9.0'

target 'YourProject' do
  use_frameworks!
  pod 'ChannelizeAPI'
end

And then install the Channelize API framework through CocoaPods.

pod install

If you are already using CocoaPods then add the following pod

pod 'ChannelizeAPI'

Required Files

You need create an .plist file with name as "Channelize-Info.plist" and place following keys

<key>PUBLIC_KEY</key>
<string>xxxx PublicKey xxxx</string>
<key>API_URL</key>
<string>xxxx API URL xxxxx </string>
<key>MQTT_URL</key>
<string>xxxxxxx MQTT URL xxxxxx</string>

App Permission

Make sure following app permissions are in your app info.plist file

<key>NSAppTransportSecurity</key>
  <dict>
  	<key>NSAllowsArbitraryLoads</key>
  	<true/>
  </dict>

Using SDK Method and Properties

**Note: Where ever you want to use Channelize, please import following

import Channelize_API

Configuring and Connecting

Configuring Channelize

To configure Channelize you need to add the following code in didFinishLaunchingWithOptions function of your project's AppDelegate.swift file

Channelize.configure()

Login to Channelize Server

You need to Login into Channelize server before using APIs. To login add following code in your app(most preferred on login button action in your app)

Channelize.main.login(username: email, password: password){(user,error) in 
   guard error == nil else {
       return }
  //Use User details here

Connecting User to Channelize Server

Connect user to get various event delegate calls(Please connect only logged users)

Channelize.connect()

Disconnecting User from Channelize Server

Disconnect a user from Channelize server to stop receiving further notifications, messages and event notifications

Channelize.disconnect()

Logout From Channelize Server

To logout from Channelize server, please add following code, where you want user to logout

Channelize.main.logout()

API References

APIs for Conversations

Getting Number of Recent Chat Count

/*
Params Required
1. QUERY_FILTER :- (QueryBuilder.ConversationCountFilters,Required)
*/

CHService.main.getRecentChatCount(queryFilter: QUERY_FILTER, completion: {(count,error) in
    guard error == nil else{
        return debugPrint(error.debugDescription)
    }
    // DO_YOUR_STUFF_HERE
})

Getting Recent Conversations

Params Required
1. QUERY_FILTER :- (QueryBuilder.ConversationFilters,Required)
*/
CHService.main.getChats(queryFilter: QUERY_FILTER, completion: {(conversations,error) in
    guard error == nil else{
        return debugPrint(error.debugDescription)
    }
    // DO_YOUR_STUFF_HERE
})

Get Conversation With a particular user

To get conversation with a particular User, make following API request

CHService.main.getChat(with: USER_ID, completion: {(conversation,error) in
    if let error = error {
        return print(error.localizedDescription)
    }
    // Do your stuff here
})

Get Conversation of conversation id

To get conversation with a particular id, make following API request

CHService.main.getChat(of: CONVERSATION_ID, completion: {(conversation,error) in
    if let error = error {
        return print(error.localizedDescription)
    }
    // Do your stuff here
})

Clearing a Conversation

To clear a conversation, make following API request using a conversation object.

conversation.clear(){(status, error) in
    if let error = error {
        return print(error.localizedDescription)
    }
    // Do your stuff here
}

Conversation Actions

You can perform various actions related to a Conversation like deleting,clearing,adding members, removing members, making a member admin of a group etc. All these action will be performed using a conversation object.

List of Actions you can perform are

Deleting a Conversation

conversation.delete(completion: {(status,error) in 
    if let error = error{
       return print(error.localizedDescription)
    }
    // DO_YOUR_STUFF_HERE
})

Marking All Messages Read

conversation.markAllMessagesAsRead()

Getting A conversation Messages

Clearing A Conversation

conversation.clear(completion: {(status,error) in
                        
})

Deleting A Conversation

conversation.delete(completion: {(status,error) in
                        
})

Leaving A Conversation

conversation.leave(completion: {(status,error) in
    guard error == nil else {
        return
    }  
})

Changing A Conversation Title

conversation.changeTitle(title: title!, completion: {(chat,error) in
    guard error == nil else {
        return print(error?.localizedDescription)
    }
    // DO_YOUR_STUFF_HERE
})

Removing Members from A Group Conversation

conversation.removeMembers(userIds: [user.id], completion: {(status,error) in
    if(status){
        // Member Removed
    }else{
        // Operation Failed
    }
})

Making A Member admin of a group Conversation

conversation.makeAdmin(userIds: USER_ID_OF_MEMBER, completion: {(status,error) in
    if(status){
        // Operation Successful
    }else{
        // Operation Failed
    }
})

Adding Members to a group Conversation

conversation.addMembers(userIds: [USER_IDS_OF_MEMBER], completion: {(status,error) in
    if(status){
        // Members Added
    }else{
        // Operation Failed
    }
})

Getting Message Count of A Conversation

Through conversation Object

conversation.getMessageCount(completion: {(count,error) in
    guard error == nil else {
        return debugPrint(error.debugDescription)
    }
    // DO_YOUR_STUFF_HERE
    
})

Through Direct API Call

/* Params Required :- 
1.CHAT_ID(String,Required)
2.QUERY_FILTER_OBJECT(QueryBuilder.ConversationMessageCountFilters,required)*/

CHService.main.getMessageCount(queryFilter: QUERY_FILTER_OBJECT, chatId: CHAT_ID, completion: {[weak self]
    (count,error) in
    // DO_YOUR_STUFF_HERE 
})

Getting Messages of A Conversation

Using conversation Object

/*Params Required
1. QUERY_FILTER_OBJECT :- (QueryBuilder.ConversationMessagesFilter,Required)
*/
conversation.getMessages(queryFilter: QUERY_FILTER, completion: {(messages,error) in
    if let error = error {
        return print(error.localizedDescription)
    }
    // DO_YOUR_STUFF_HERE    
})

Using Direct API Call

/*
Params Required
1. QUERY_FILTER_OBJECT :- (QueryBuilder.ConversationMessagesFilter,Required)
2. CHAT_ID :- (String,Required)
*/
CHService.main.getMessages(queryFilter: QUERY_FILTER_OBJECT, chatId: CHAT_ID, completion: {(messages,error) in
    if let error = error {
        return print(error.localizedDescription)
    }
    // DO_YOUR_STUFF_HERE
})

Groups APIs

Get total Number of groups Count

To get total number of groups, make following API request

CHService.main.getGroupsCount(params:[String:Any],completion: {(groupsCount) in
    if let error = error {
        return print(error.localizedDescription)
    }
    // Do your stuff here
})

Get List of Groups

To get list of groups, make following API request

//limit: Numbers of groups list in one call
//offset: Starting index for groups list call
CHService.main.getGroups(params:[String:Any], completion: {(conversations,error) in
    if let error = error {
        return print(error.localizedDescription)
    }
    // Do your stuff here
})

Creating Groups

CHConversation objects are created by calling createGroup(title:memberIds:imageData:completion) using CHService class.
To create a groups, create following API request Fields are:
title:(String,Required) -> Title of the group
memberIds:(Array,Required) -> Groups Members Ids
imageData: (Data,Optional) -> Image Data for Group Profile Image
completion:(Required, ChatData): Completion handler which return the created object of CHConversation & error if the request failed.

CHService.main.createGroup(title: GROUP_TITLE, memberIds: [MEMBERS_IDS], imageData: IMAGE_DATA, completion: {(conversation,error) in
    if let error = error {
        return print(error.localizedDescription)
    }
    // Do your stuff here
})

Leave a group

To leave a group, make following API request using conversation object of that group.

conversation.leave(){(status, error) in
    guard error == nil else {    // Error.
        return
    }
}

Add Member to a group

To add a member to the Group make following API request using conversation object of that group.

conversation.addMembers(userIds: [USER_IDS]){(conversation, error) in
    if let error = error {
        return print(error.localizedDescription)
    }
    // Do your stuff here
}

Remove Member from the Group

To remove members from the group, make following API request using conversation object of that group.

conversation.removeMembers(userIds: [USER_IDS]){(conversation, error) in
    if let error = error {
        return print(error.localizedDescription)
    }
    // Do your stuff here
}

Make a member Admin of the Group

To make members admin of the group, make following API request using conversation object of that group.

conversation.makeAdmin(userId: USER_ID){(status, error) in
    if let error = error {
        return print(error.localizedDescription)
    }
    // Do your stuff here
}

Updating a group Title

To update title of the group, make following API request using conversation object of that group.

conversation.changeTitle(title: TITLE_NAME){(conversation, error) in
    if let error = error {
        return print(error.localizedDescription)
    }
    // Do your stuff here
}

Updating Group Profile Photo

To update a group profile photo, make following API request using conversation object of that group.

conversation.updateProfileImage(data: IMAGE_DATA){(conversation, error) in
    if let error = error {
        return print(error.localizedDescription)
    }
    // Do your stuff here
}

Messages

Get the list of messages for a conversation

For getting the total number of messages -

 conversation.getMessageCount() {(count, error) in   
     if let error = error {
         return print(error.localizedDescription)
     }
     //Do your stuff here  
  }

Using the getMessages(limit:Int?, offset:Int?, completion:completion) call you can retrieve the list of messages which provide an array of CHMessage type objects.

  conversation.getMessages(limit: DEFAULT_LIMIT, offset: OFFSET) {(messages, error) in  
      if let error = error {
          return print(error.localizedDescription)
      }    
      //Do your stuff here
   }

Remove messages

Using the deleteMessages(messageIds:[String], completion: completion) call you can delete messages using their ID's.

  conversation.deleteMessages(messageIds:[MESSAGE_ID'S]){(status, error) in   
      if let error = error {
          return print(error.localizedDescription)
      }
      //Do your stuff here    
   }

Mark messages as read

Using the markAllMessagesAsRead() call you can delete messages using their ID's.

  conversation.markAllMessagesAsRead()

Mark a message as read

Using the markAsRead() call you can mark a message read

  message.markAsRead()

Sending Messages

For Normal Messages CHMessage objects are created by calling sendMessage(text:data:fileUrl:type:completion) using conversation object. The fields are as follows:
- text (Optional, String?): text message as String. Add this if you are sending a text message.
- data (Optional, Data?): file as Data if you sending audio,image or video file as Data.
- fileUrl (Optional, URL?): url of the file you are trying to send.
- type (Required, CHMessageType): attachment type of the message. Choose from the enum.
- completion (Required, MessageResult): Completion handler which return the created object of CHMessage & error if the request failed.

  conversation.sendMessage(text: MESSAGE_TEXT, data: FILE_DATA, fileUrl: FILE_URL, type:ATTACHMENT_TYPE){
     (message, error) in
     guard error == nil else {    // Error.
        return
     }
  }

For Quoted Message CHMessage objects are created by calling sendQuotedMessage(text:quotedMessage:completion) using conversation object. The fields are as follows:
- text (Required, String): text message as String.
- quotedMessage (Required, [String]): An instance of the message that is being quoted.
- completion (Required, MessageResult): Completion handler which return the created object of CHMessage & error if the request failed.

  conversation.sendQuotedMessage(text: MESSAGE_TEXT, quotedMessage: QUOTED_MESSAGE){(message, error) in
     guard error == nil else {    // Error.
        return
     }
  }

Forwarding a message To forward a message, following parameters are required

messageIds -> Array of string containing message ids to be forwarded
chatIds -> Array of string containing conversations ids
userIds -> Array of string containing ids of users to whom message to be forwared
ownerId -> Current user id

let params:[String:Any] = [
    "messageIds" : messageIds,
    "chatIds"    : selectedChatIds,
    "userIds"    : selectedUserIds,
    "ownerId"    : Channelize.main.currentUserId()!
]
CHService.main.forwardMessage(params: params, completion: {[weak self] (status) in
    if(status){
    } else {
    }
})

Users

Getting Total Users Count

/*
Parameters Required:
1. QUERY_FILTER_OBJECT :- (QueryBuilder.GetUserCountFilters,Required)
*/
CHService.main.getUserCounts(queryFilter: QUERY_FILTER_OBJECT, completion: {(count,error) in
    // DO_YOUR_STUFF_HERE
})

Getting Friends Count

/*
Parameters Required:
1. QUERY_FILTER_OBJECT :- (QueryBuilder.GetFriendsCountFilters,Required)
*/
CHService.main.getFriendsCounts(queryFilter: QUERY_FILTER_OBJECT, completion: {(count,error) in
    // DO_YOUR_STUFF_HERE
})

Getting All Users

/*
Parameters Required:
1. QUERY_FILTER_OBJECT :- (QueryBuilder.GetUserFilters,Required)
*/
CHService.main.getUsers(queryFilter: QUERY_FILTER_OBJECT, completion: {(users,error) in
    // DO_YOUR_STUFF_HERE
})

Getting All Friends List

/*
Parameters Required:
1. QUERY_FILTER_OBJECT :- (QueryBuilder.GetFriendsFilters,Required)
*/
CHService.main.getFriends(queryFilter: QUERY_FILTER_OBJECT, completion: {(friends,error) in
    // DO_YOUR_STUFF_HERE
})

Getting Blocked User Count

/*
Parameters Required:
1. QUERY_FILTER_OBJECT :- (QueryBuilder.GetBlockedUserCountFilters,Required)
*/
CHService.main.getBlockedUsersCount(queryFilter: query, completion: {(count,error) in
// DO_YOUR_STUFF_HERE
})

Getting Blocked User

/*
Parameters Required:
1. QUERY_FILTER_OBJECT :- (QueryBuilder.GetBlockedUserFilters,Required)
*/
CHService.main.getBlockedUsers(queryFilter: query, completion: {(users,error) in
// DO_YOUR_STUFF_HERE
})

Blocking A User User’s have the ability to block/unblcok other users, allowing them to have a sense of privacy and security around the kinds of people that they interact with. If User A blocks User B: - User B can not create a conversation with User A & vice versa. - User B can not send messages to User A & vice versa, if a conversation already exists between the two. - Note that these rules do not apply to Group Conversations

/*
Parameters Requires:
1. USER_ID :- (String,Required) User Id of the user to block
*/
CHService.main.blockUser(userId: USER_ID, completion: {(status,error) in
    
})

UnBlocking A User

/*
Parameters Requires:
1. USER_ID :- (String,Required) User Id of the user to block
*/
CHService.main.unblockUser(userId: USER_ID, completion: {(status,error) in
    
})

Retrieve a user using user id

You can also retrieve a user using it's user_id in Channelize application by requesting the following call.

  CHService.main.getUser(with: USER_ID) {(user, error) in
      if let error = error {
          return print(error.localizedDescription)
      }    
      //Do your stuff here
   }

Blocking/Unblocking

User’s have the ability to block/unblcok other users, allowing them to have a sense of privacy and security around the kinds of people that they interact with. If User A blocks User B:
- User B can not create a conversation with User A & vice versa.
- User B can not send messages to User A & vice versa, if a conversation already exists between the two.
- Note that these rules do not apply to Group Conversations

  CHService.main.blockUser(userId: USER_ID){ (status, error) in
     guard error == nil else {    // Error.
        return
     }
     if status {
          // Successfully Blocked 
     }
  }

To unblock a user using the following code -

  CHService.main.unblockUser(userId: USER_ID){ (status, error) in
     guard error == nil else {    // Error.
        return
     }
     if status {
          // Successfully UnBlocked 
     }
  }

Update User Settings You can set following settings for a user

visibility(Bool) -> To show or hide user online offline status
isOnline(Bool) -> To set user online or offline
notification(Bool) -> To send or stop notification to a user

To update user settings, make following api request. Send settings which you want to update in params(dictionary of type [String:Any])

Channelize.updateUserSettings(params: [String : Any], completion: {(user,error) in
            if let error = error {
                return print(error.localizedDescription)
            }
            //Do your stuff
        })

Real Time Updates

To handle real time Updates using MQTT, please refer to this page https://github.com/ChannelizeIO/Channelize-iOS/wiki/MQTT-Subscriber-Setup-with-Channelize-API-SDK

Provide feedback

Saved searches

Use saved searches to filter your results more quickly