Quickstart

This page takes you from nothing to a working integration: initialize, sign in, send the first message, show conversations and messages, and sign out. Before you start:

1. Add the im module as described in Overview and installation.
2. Create an app in the tenant console and review its runtime policies.
3. Have your backend issue IM sign-in tickets after users sign in to your system. The app only receives tickets; never put the Client Secret or an App Token in the app.

Initialize and sign in

After the user agrees to your privacy policy, initialize one client in the main process. The code below runs in one of your coroutines; context is an Android Context and ticket is a ticket your backend just issued:

import com.deeprespond.im.*

val im = DRClient.initialize(context, DRClientOptions(
    appKey = "org#app",
    apiUrl = "https://api.example.com",
))
im.auth.awaitRestored()
if (im.auth.currentUser == null) {
    im.auth.loginWithTicket(ticket)
}
im.connection.waitUntilReady()

initialize returns immediately and the saved sign-in state is restored in the background, so call awaitRestored() before deciding whether to sign in: users who signed in before are reconnected without signing in again. When a ticket stops working you need a new one from your backend; ticketProvider can handle that automatically.

Send a message

The recipient must be an existing IM user in the app, and the app's friend, mute and group policies must allow the message:

val message = im.messages.send(
    SendTarget.User("bob"),
    OutgoingContent.Text("你好"),
    SendOptions(waitUntilSent = true),
)
println(message.messageId)

By default send returns the local message as soon as it's written to the send queue, and the SDK sends it from there. This example uses waitUntilSent = true to wait for the server's confirmation. For all message types and failure handling, see Messages.

Conversation and message screens

val conversation = im.conversations.openSingle("bob")
val list = im.messages.open(conversation.conversationKey)
try {
    list.snapshot.collect { snapshot ->
        println(snapshot.items.size) // 在 UI 中展示快照。
    }
} finally {
    list.close()
}

This runs in the screen's coroutine: when the screen is destroyed and the coroutine is cancelled, finally closes the list. Don't start a collection that never ends from a button click; for tying subscriptions to the UI lifecycle, see UI and lifecycle. For files, group chat and push, see Files, Groups and Offline push.

Sign out

im.auth.logout(clearLocalData = true)

logout signs the user out. Use destroy only when switching AppKey or shutting the client down entirely, not every time a screen closes. See Client lifecycle.

Run the example and check your integration

The source includes sdk/android/example, with a Kotlin chat screen and a screen written against the Java API. Once your build environment is ready, run ./gradlew :example:installDebug and enter your AppKey, service URL and sign-in ticket.

Things to check:

• Plain chat only needs the network permission; request notification, microphone and camera permissions for the features that use them.
• When testing against a local server over HTTP, give the app a debug network security config; use HTTPS in production.
• Whether users can add friends, send messages or create groups is decided by the runtime policies.
• A message in the queued state (waiting to send) hasn't been sent yet: watch the message status, or use waitUntilSent.
• The SDK is currently installed from a local Maven repository and isn't on public Maven yet.

Join a standalone channel

After signing in, you can join channels your backend created by following Channels. The app must have channels enabled and your backend must allow the user to join; joining doesn't turn on the camera or microphone by default.