Skip to main content

Chat Sessions

Before a user can begin sending and receiving real-time messages and use in-app chat features like typing indicators, delivery and read receipts, live reactions, etc, their device needs to start a chat session. You can think of starting a chat session like entering a chat room. After a user starts a chat session, the chat session is active until the user ends the chat session. Ending a chat session corresponds to leaving a chat room.

Chat session event handlers

When starting a chat session, you can define event handlers to respond to chat events that occur while the chat session is active, as such when a new message is received, a user starts/stop typing, a user has entered or left the chat room, a user went offline, etc.


All chat session event handlers are optional, so you only needed to register handlers for chat events your application cares about.

NameParametersTrigger condition (when called)
onMessageReceivedMessageA message is sent to this channel
onKeystrokesReceivedKeystrokesTyping keystrokes are made by users in this channel
onTypingStartedUserA user starts typing in this channel
onTypingStoppedUserA user stops typing in this channel
onParticipantEnteredChatUserA user starts a chat session in this channel
onParticipantLeftChatUserA user ends their active chat session in this channel
onParticipantPresenceChangedUserA member of this channel changes their presence status (goes online or offline)
onMessageUpdatedMessageA message sent in this channel has been updated
onChannelUpdatedChannelThe channel associated with this chat session has been updated
onMessageReadMessage, ReadReceiptA message sent in this channel has been read


channelChannelThe channel this session was started for
endfunctionEnds this chat session when invoked

Starting a chat session

You start a chat session using a channel object and optionally chat session event handler methods to handle chat events.


channelChannelThe channel this session is associated with
onMessageReceivedfunctionChat session event handler function-
onKeystrokesReceivedfunctionChat session event handler function-
onTypingStartedfunctionChat session event handler function-
onTypingStoppedfunctionChat session event handler function-
onParticipantEnteredChatfunctionChat session event handler function-
onParticipantLeftChatfunctionChat session event handler function-
onParticipantPresenceChangedfunctionChat session event handler function-
onMessageUpdatedfunctionChat session event handler function-
onChannelUpdatedfunctionChat session event handler function-
onMessageReadfunctionChat session event handler function-
const result = chatkitty.startChatSession({
channel: channel, // Optional event handlers below...
onMessageReceived: (message) => {
// handle received messages
onTypingStarted: (user) => {
// handle user starts typing
onTypingStopped: (user) => {
// handle user stops typing
}, //... and so on.

if (result.succeeded) {
const session = result.session; // Handle session

if (result.failed) {
const error = result.error; // Handle error

Ending a chat session

If you no longer wish to participate in a channel's live chat and receive its events, you must end your chat session with the channel. After the last active chat session for a user in a channel is closed, certain chat events like new messages trigger notifications.


A user session must be active for the current user before starting a chat session