SDK configuration (Android)

Dependency Management

The Android SDK has several dependencies, which you can check directly in Maven. Note that the latest release might appear in Maven with some delay.

Installation Steps for Chat2Desk Library

1. Edit the build.gradle file in the root of your project to add mavenCentral() to the list of repositories:

allprojects {
    repositories {
        jcenter()
        mavenCentral() //add this line
    }
}

2. Add Chat2Desk to the dependencies section of build.gladle. Paste the current version from the changelog:

dependencies {
    ...
    // Paste the actual version from the changelog
    implementation 'com.chat2desk:chat2desk_sdk:${Version}'
}

3. Add Java 8 support to your project in the build.gradle file:

android {
    ... //other configs
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

If targeting devices with Android API below 26, you need to use Android Gradle Plugin version 4.0 or newer and enable core library desugaring.

SDK initialization

The Android app requires the following permissions:

<uses-permission android:name="android.permission.INTERNET"/>

If you need to interact with MediaStore or media files in shared storage, you should use one or more of the storage permissions:

 <uses-permission android:name="android.permission.READ_MEDIA_IMAGES"/> <uses-permission android:name="android.permission.READ_MEDIA_VIDEO"/> <uses-permission android:name="android.permission.READ_MEDIA_AUDIO"/> 

Then create an instance of the Chat2Desk client, of type IChat2Desk, and initialize it:

val settings = Settings(
    authToken = WIDGET_TOKEN,
    baseHost = BASE_HOST,
    wsHost = WS_HOST,
    storageHost = STORAGE_HOST
)
val chat2desk: IChat2Desk = Chat2Desk.create(settings, context)

Replace WIDGET_TOKEN, BASE_HOST, WS_HOST, STORAGE_HOST with the values from the Settings > Widget + Online Chat page for the specific connected channel.

Removing the SDK

Before removing an instance of IChat2Desk, use the IChat2Desk.close method to prevent memory leaks.

Connecting and Disconnecting

Use IChat2Desk.start to connect to the service and IChat2Desk.stop to disconnect from it.

You can monitor the connection status through the connectionStatus property: Flow<ConnectionState>.

Here's a code example to understand how it works:

class SomeClass(private val chat2desk: IChat2Desk) {
    private val coroutineScope = CoroutineScope(Dispatchers.Main)
    
    init {
        coroutineScope.launch {
            chat2desk.connectionStatus.collect {
                println(it)
            }
        }
    }
    public suspend fun start() {
        chat2desk.start()
    }

    public suspend fun stop() {
        chat2desk.stop()
    }
}

Receiving Messages

To work with messages, the library must be connected to the Chat2Desk service. All incoming and outgoing messages are cached within the library by default and can be accessed offline.

To get the list of messages, use the messages property: Flow<List<Message>>.

chat2desk.messages.collect { messages ->
    println(messages)
}

Fetching Messages from the Server

To work with messages, the library must be connected to the Chat2Desk service. Note that the SDK fetches a maximum of 100 messages at a time from the server.

• chat2desk.fetchMessages(): Fetches the latest 100 messages.
• chat2desk.fetchNewMessages(): Fetches new messages that are newer than the last message on the device.
• chat2desk.fetchMessage(loadMore = true): Fetches older messages that are older than the first message on the device, but no more than 100 at a time.

Searching Messages

The SDK provides two ways to search messages: full-text search and operator-based search. Both methods search messages by the Message.text property and return a list of messages List<Message>.

Full-Text Search

chat2desk.fullTextSearch(query: String): List<Message>

Query tokens follow these rules:

• Tokens can only consist of ASCII and Latin-1 characters. All other characters are treated as spaces.
• Hyphenated words (e.g., full-text) are split into two tokens (full and text).
• Tokens are not case-sensitive or sensitive to diacritical marks.

You can search for a whole word or phrase and limit results with these symbols:

• Exclude results for a word by prefixing it with -. For example, fiction -science includes all results for fiction and excludes those containing science.
• Specify prefixes with * at the end of a word. For example, fict* will include results for fiction and fictitious. (The SDK does not currently support suffix searches).

Operator-Based Search

chat2desk.searchByQuery(query: String, options: SearchOptions?): List<Message>

data class SearchOptions(
    /**
     * Search operator
     */
    val operator: QueryStringOperator = QueryStringOperator.CONTAINS,
    /**
     * Case sensitivity
     * ASCII and Latin-1 characters only
     */
    val caseSensitivity: Boolean = false,
)

enum class QueryStringOperator {
    BEGINSWITH,
    CONTAINS,
    ENDSWITH,
    LIKE,
    EQUAL,
    NOTEQUAL
}

Search options allow you to specify an operator for searching messages:

• BEGINSWITH: Matches if the left string expression begins with the right string expression.
• CONTAINS: Matches if the right string expression appears anywhere in the left string expression.
• ENDSWITH: Matches if the left string expression ends with the right string expression.
• LIKE: Matches if the left string expression matches the right wildcard string expression.
• EQUAL: Matches if the left string is lexicographically equal to the right string.
• NOTEQUAL: Matches if the left string is not lexicographically equal to the right string.

Sending Messages

To send messages, the library must be connected to the Chat2Desk service.

• Send a message: sendMessage(txt: String)

chat2desk.sendMessage(txt)

• Send message with attachment: sendMessage(msg: String, attachedFile: AttachedFile) To send an attachment, you need to create an instance of the class AttachedFile and pass it to the method.

val attachedFile = AttachedFile.fromUri(
    context,
    uri,
    originalName,
    mimeType,
    fileSize
)
chat2desk.sendMessage(txt, attachedFile)

• Resend message: resendMessage(msg: Message)

chat2desk.resendMessage(message)

Sending Client Information

The service allows sending client information. By default, two fields name and phone are available:

chat2desk.sendClientParams(name, phone)

The service also sends a list of custom fields defined in the company customFields: Flow<List<CustomField>>.

val fields: List<CustomField>
chat2desk.customFields.collect {
  fields = it
}
chat2desk.sendClientParams(name, phone, mapOf(fields[0].id to "value"))

Additional Settings

• Operator information: operator: Flow<Operator?>

chat2desk.operator.collect {operator ->
  println(operator)
}

• ​​​​​​​Error handling: Flow<Throwable?>​​​​​​​

​​​​​​​​​​​​​​chat2desk.error.collect {error ->
  println(error.message)
}

Demo

Kotlin SDK Demo demonstrates the basic functionality of the SDK.​​​​​​​