Skip to main content

Send your first message

This quickstart walks you through the core Nexconn SDK flow: import the SDK, initialize it, register handlers, connect to the server, and send a message.

Requirements​

SDK versionAndroidAPI level
1.0+5.0 or later21+

Prerequisites​

  • Register a developer account on the Nexconn Console. A default application is automatically created in the development environment upon registration.

  • On the Key Management page, obtain the App Key for your development environment. You can also view the App Secret and data center assignment (Singapore by default).

  • Optionally, create a new application and obtain the App Key and App Secret for the desired environment.

tip

Each application has two separate App Keys for the development and production environments. Data is isolated between environments. Before going live, switch to the production App Key to complete end-to-end testing.

Step 1: Import the SDK​

info

This quickstart uses a Gradle remote dependency. For all import options, see Import the SDK.

  1. Open your project in Android Studio and switch to the Project view.

  2. In the root build.gradle, declare the Nexconn Maven repository:

    Use the setup that matches your Gradle plugin version:

    Open the root build.gradle file and add:

    Groovy
    allprojects {
        repositories {
            ...
            mavenCentral()
        }
    }

  3. In your app-level build.gradle, add the Nexconn SDK as a dependency. Replace x.y.z with the latest version from the Maven repository.

    Groovy
    dependencies {
        ...
        implementation 'ai.nexconn.chat:chat:x.y.z'
    }

Step 2: Initialize the SDK​

Call NCEngine.initialize() in your Application's onCreate() method. Obtain your App Key from the Nexconn Console before proceeding.

info

This quickstart shows basic initialization. For full options including overseas data centers and private cloud configuration, see Initialize the SDK.

Singapore data center (default)​

If your App Key belongs to the Singapore data center, you do not need extra configuration.

kotlin
val appKey = "Your_AppKey" // e.g., bos9p5rlcm2ba

NCEngine.initialize(InitParams(applicationContext, appKey))

Global data center​

If you use another data center, pass the corresponding AreaCode.

kotlin
val appKey = "Your_AppKey"

val initParams = InitParams(applicationContext, appKey).apply {
    areaCode = AreaCode.SINGAPORE
}

NCEngine.initialize(initParams)

Step 3: Listen for messages​

Add a channel handler to receive real-time and offline messages.

tip

Register the handler before connecting to ensure all offline messages are received.

kotlin
NCEngine.addMessageHandler("MyHandler", object : MessageHandler {
    override fun onMessageReceived(event: MessageReceivedEvent) {
        val message = event.message
        println("Received message: ${message.messageId}")

        when (message.content) {
            is TextMessage -> {
                val text = (message.content as TextMessage).text
                println("Text: $text")
            }
            is ImageMessage -> {
                println("Image message received")
            }
        }
    }
})

Step 4: Connect to the server​

Get an access token​

To simulate messaging, register a user first. In production, your app server calls the Nexconn Server API to register a user and obtain an access token. For this quickstart, use the API debugging tool in the Console to generate a token for user ID 1:

JSON
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "code": 200,
  "userId": "1",
  "token": "gxld6GHx3t1eDxof1qtxxYrQcjkbhl1V@sgyu.cn.example.com;sgyu.cn.example.com"
}

Add a connection handler​

Set up a connection handler to monitor connection status. Use it to update the UI, such as showing "Reconnecting..." or "Connected." Register the handler for your app's lifecycle and remove it when you no longer need it.

kotlin
NCEngine.addConnectionStatusHandler("ConnectionHandler") { status ->
    when (status) {
        ConnectionStatus.CONNECTED -> println("Connected")
        ConnectionStatus.UNCONNECTED -> println("Disconnected")
        ConnectionStatus.TOKEN_INCORRECT -> println("Token error")
        else -> println("Status: $status")
    }
}

Connect​

Call NCEngine.connect() with the access token to establish a connection.

tip

The Nexconn SDK has a built-in reconnection mechanism. Call connect() only once per app lifecycle. For details, see Connection.

kotlin
val token = "gxld6GHx3t1eDxof1qtxxYrQcjkbhl1V@sgyu.cn.example.com;sgyu.cn.example.com"

NCEngine.connect(ConnectParams(token)) { userId, error ->
    if (error == null && userId != null) {
        println("Connected as user: $userId")
    } else {
        println("Connection failed: ${error?.message}")
    }
}

Step 5: Send a message​

Send a text message to user ID 2 through a direct channel. The SDK also supports image, file, voice, and other message types. See Message types for details.

kotlin
val channel = DirectChannel("2")

val textMessage = TextMessage("Hello from user 1!")

val params = SendMessageParams(textMessage).apply {
    pushContent = "You have a new message"
}

channel.sendMessage(params, object : SendMessageHandler {
    override fun onAttached(message: Message) {
        println("Message saved to local DB: ${message.messageId}")
    }

    override fun onResult(message: Message?, error: NCError?) {
        if (error == null) {
            println("Message sent: ${message?.messageId}")
        } else {
            println("Send failed: ${error.message}")
        }
    }
})

What's next​

Last updated on