Getting Started

This section help you to start building your integration, so that you can send your first message.

Step 1: Get Your App ID

First of all, you need to create your application (App ID) in dashboard, by accessing Qiscus Chat Dashboard.

You can create more than one App ID within a single account. For further information regarding multiple applications in single account.

Step 2: Install Qiscus Chat SDK

Qiscus Chat SDK requires minimum IOS SDK 10. To integrate your apps with Qiscus, it can be done in 2 steps:

First, you need to add dependency QiscusCore into your Podfile

pod 'QiscusCore', "1.10.1"

To see all chat SDK versions and supported Xcode version you can see following link.

Second, you need to pod install from terminal

pod install

Step 3: Initialization Qiscus Chat SDK

You need to initiate your App ID for your chat App before carry out to Authentication. Can be implemented in the initial startup. Here is how you can do that:

QiscusCore.setup(AppID: AppID)

Step 4: Authentication to Qiscus

To use Qiscus Chat SDK features, a user firstly need to authenticate to Qiscus Server. This authentication is done by calling setUser() function. This function will retrieve or create user credential based on the unique userId, for example:

QiscusCore.setUser(userId: userId, userKey: userKey, username:username, avatarURL: avatarUrl, extras: extras, onSuccess: { (user) in  

  print("success")

}) { (error) in                

  print("error \(String(describing: error?.message))")             

}

Where:

• userId (string, unique): a user identifier that will be used to identify a user and used whenever another user need to chat with this user. It can be anything, whether is is user's email, your user database index, etc. As long as it is unique and a string. This value is case sensitive
• userKey (string): userKey for authentication purpose, so even if a stranger knows your user Id, he/she cannot access the user data
• username (string): username is used as a display name inside chat room
• avatarUrl (string, optional): to display user's avatar, fallback to default avatar if not provided
• extras ([string:any], optional): to give additional information (metadata) to user, which consist key-value, for example key:position, and value: engineer

For further detail you might figure out Authentications section.

Step 5: Create a Chat Room

There are three Chat Room types in Qiscus Chat SDK:

• 1-on-1 Chat Room
• Group Chat Room
• Channel Chat Room

In this section, we will use 1-on-1 Chat Room. We assume that you already know a targeted user you want to chat with. To start a conversation with your targeted user, you can call chatUser() method. Qiscus Chat SDK, then, will serve you a new chat room, asynchronously. When the room is successfully created, Qiscus Chat SDK will return a chat room package through onSuccess listener

QiscusCore.shared.chatUser(userId: userId, extras, onSuccess: { (room, comments) in

    print("success")   

}) { (error) in

    print(error.message)

}

Where:

• userId (string) : a user identifier that will be used to identify a user and used whenever another user needs to chat with this user. It can be anything, whether is user's email, your user database index, etc. as long as it is unique and a string. This value is case sensitive
• extras ([string:any], optional) : metadata that can be as additional information to chat room, which consists key-value, for example, key: background, and value: red

Step 6: Send Message

You can send any type of data through Qiscus Chat SDK, in this section let's send a "Hi" message, with type value is text. You need to pass roomId and the message value, for example

let message = CommentModel()

message.message = "Hi"

message.type    = "text"

message.roomId  = roomId 

​

QiscusCore.shared.sendMessage(message: message, onSuccess: { (comment) in

  print("success")

}) { (error) in

  print(error.message)

}

Where:

• message (object): consist of message , type , and roomId that you send to other participant
• type (string): message type, that you can define freely, there are reserved rich messages type, for example: text, file_attachment, account_linking, buttons, button_postback_response, reply, system_event, card, custom, location, contact_person, carousel. These type have been taken, if you use it and custom your structured data, you may face your structured data will not work, these type for bot API, hence you need define other type name.

Messages can be received by the recipient target through a onRoomMessageReceived event. This event is triggered whenever users send a message. Here is you will get this event:

// re-connect once re-open the apps 

extension AppDelegate {

   // check whether is authenticated or not

   if QiscusCore.hasSetupUser() {

      // connect to realtime 

      QiscusCore.connect(delegate: self)      

   }

}

​

//set your delegate in viewWillAppear

func setRoomDelegate(){

    if let room = self.room {

         room.delegate = self

     }       

}

​

//remove your delegate in viewWillDisappear

func removeRoomDelegate() {

    if let room = self.room {

         room.delegate = nil

    }

}

​

extension YourChatViewController : QiscusCoreRoomDelegate {

    // MARK: Message event in a chat room

​

    /// new message is comming

    ///

    /// - Parameters:

    /// - comment: new comment object

    func onMessageReceived(message: CommentModel){

    }

}

For further details about message, you can find at Message section and Event handler section