Users, friends and presence

This page covers everything about people: user profiles (im.users), friends and the blocklist (im.friends), presence (im.presence) and the user's signed-in devices (im.devices). What users are allowed to do is decided by the runtime policies.

You want to	See
Show and edit the user's own profile, show others' nicknames and avatars	Your profile and other users' profiles
Add friends, handle friend requests, set remarks	Friends and requests
Block someone, set the friend add mode	Blocklist and friend add mode
Show online or offline	Presence
See and sign out the user's other devices	Signed-in devices

Your profile and other users' profiles

val me = im.users.refreshMe()
im.users.updateMe(nickname = "小明")
val profiles = im.users.fetch(listOf("bob"), force = true)
println(profiles["bob"]?.nickname)

• users.me is a StateFlow of the user's own profile.
• get(username) reads a cached profile synchronously and returns null if there isn't one.
• fetch returns a Map from username to profile. Unexpired cache entries are used directly; with force = true the server is always queried.
• updateMe can change nickname, avatarUrl and attributes, and also supports clearAttributes and version. Keys in attributes set to null are deleted; clearAttributes removes all attributes.
• To set an avatar, upload it with USER_AVATAR first and then write the returned URL to the profile; see Avatars and group files.
• myMute is the user's mute information, for display only; whether sending is allowed is decided by the server.

Friends and requests

im.friends.requests.send("bob", message = "你好，我是小明")
im.friends.requests.accept("bob", remark = "同事")
im.friends.update("bob", remark = "项目同事")

• friends.list() / listFlow() provide the friend list. get reads one friend locally, check checks relationships with several users, and remove removes a friend. listInfo holds the friend count and limit; see Data types.
• requests.received() / sent() page through received and sent requests. decline declines one, markRead marks received requests as read, and unreadCount is a StateFlow of unread requests.
• What send does depends on the other user's friend add mode: you may become friends right away, or only send a request. Show the result based on the return value and the latest friend list.

Blocklist and friend add mode

im.friends.blacklist.add("bob")
val blocked = im.friends.blacklist.has("bob")
im.friends.blacklist.remove("bob")

• blacklist.list() / listFlow() subscribe to the blocklist.
• friends.settings.get() gets the user's friend add mode and set(mode) changes it; mode null uses the app default.
• How blocking affects messages and calls is decided by the server's policies.

Presence

val subscription = im.presence.subscribe(listOf("bob"))
try {
    val known = im.presence.get("bob")
    val queried = im.presence.query(listOf("bob"))
    println(known)
    println(queried)
} finally {
    subscription.close()
}

• subscribe follows these people's presence; close it when the screen goes away. PresenceChanged is emitted when a status changes.
• get reads the status known in memory; query asks the server once.
• When a status can't be found, a subscription fails or permission is missing, don't just show "Offline": tell "unknown", "not visible" and actually offline apart. Failed subscriptions emit PresenceSubscribeFailed.

Signed-in devices

• devices.online() reads the user's devices online now, sessions() queries all of the user's active sign-ins, and kick(sessionId) signs out a given device.
• DevicesChanged is emitted when the user's online devices change, and DevicesNewLogin when the user signs in on a new device.
• For device limits and same-platform replacement, see Multi-device sign-in in the server docs.

For full parameters, see the users API, friends API and presence API.