User Presence

User presence allows you to show when a user was last active and if they are online right now. This feature can be enabled or disabled per channel type in the channel type settings.

Listening to Presence Changes

To receive presence updates, you need to watch a channel or query channels with presence: true. This allows you to show a user as offline when they leave and update their status in real time.

// You need to be watching some channels/queries to be able to get presence events.
// Here are two different ways of doing that:

// 1. Watch a single channel with presence = true set
val watchRequest = WatchChannelRequest().apply {
  data["members"] = listOf("john", "jack")
  presence = true
}
channelClient.watch(watchRequest).enqueue { result ->
  if (result is Result.Success) {
    val channel: Channel = result.value
  } else {
    // Handle error
  }
}

// 2. Query some channels with presence = true set
val channelsRequest = QueryChannelsRequest(
  filter = Filters.and(
    Filters.eq("type", "messaging"),
    Filters.`in`("members", listOf("john", "jack")),
  ),
  offset = 0,
  limit = 10,
).apply {
  presence = true
}
client.queryChannels(channelsRequest).enqueue { result ->
  if (result is Result.Success) {
    val channels: List<Channel> = result.value
  } else {
    // Handle error
  }
}

// Finally, subscribe to presence to events
client.subscribeFor<UserPresenceChangedEvent> { event ->
  // Handle change
}

// You need to be watching some channels/queries to be able to get presence events.
// Here are two different ways of doing that:

// 1. Watch a single channel with presence = true set
WatchChannelRequest watchRequest = new WatchChannelRequest();
watchRequest.setPresence(true);
watchRequest.getData().put("members", Arrays.asList("john", "jack"));
channelClient.watch(watchRequest).enqueue(result -> {
  if (result.isSuccess()) {
    Channel channel = result.getOrNull();
  } else {
    // Handle error
  }
});

// 2. Query some channels with presence events
int channelsOffset = 0;
int channelsLimit = 10;
FilterObject channelsFilter = Filters.and(
    Filters.eq("type", "messaging"),
    Filters.in("members", Arrays.asList("john", "jack"))
);
QuerySorter<Channel> channelsSort = new QuerySortByField<>();
int messageLimit = 0;
int memberLimit = 0;
QueryChannelsRequest channelsRequest = new QueryChannelsRequest(
    channelsFilter,
    channelsOffset,
    channelsLimit,
    channelsSort,
    messageLimit,
    memberLimit
);
client.queryChannels(channelsRequest).enqueue(result -> {
  if (result.isSuccess()) {
    List<Channel> channels = result.getOrNull();
  } else {
    // Handle error
  }
});

// Finally, Subscribe to events
client.subscribeFor(
    new Class[]{UserPresenceChangedEvent.class},
    event -> {
      // Handle change
    }
);

A users online status change can be handled via event delegation by subscribing to the user.presence.changed event the same you do for any other event.

Presence Data Format

Whenever you read a user the presence data will look like this:

JavaScript

{
  id: 'unique_user_id',
  online: true,
  status: 'Eating a veggie burger...',
  last_active: '2019-01-07T13:17:42.375Z'
}

The online field indicates if the user is online. The status field stores text indicating the current user status.

The last_active field is updated when a user connects and then refreshed every 15 minutes.

To mark your user as invisible, you can update your user to set the invisible property to true. Your user will remain invisible even if you disconnect and reconnect. You must explicitly set invisible to false in order to become visible again.

Node.js

// become invisible
await client.upsertUser({
  id: "unique_user_id",
  invisible: true,
});

// become visible
await client.upsertUser({
  id: "unique_user_id",
  invisible: false,
});

You can also set your user to invisible when connecting by setting the invisible property to true. You can also set a custom status message at the same time:

val user = User(
  id = "user-id",
  invisible = true,
)
client.connectUser(user, "{{ chat_user_token }}").enqueue { result ->
  if (result is Result.Success) {
    val user: ConnectionData = result.value
  } else {
    // Handle error
  }
}

User user = new User.Builder()
    .withId("user-id")
    .withInvisible(true)
    .build();
client.connectUser(user, "{{ chat_user_token }}").enqueue(result -> {
  if (result.isSuccess()) {
    User userRes = result.getOrNull().getUser();
  } else {
    // Handle error
  }
});

When invisible is set to true, the current user will appear as offline to other users.

Typing Indicators

Polls API