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.

note

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

Name	Parameters	Trigger condition (when called)
onMessageReceived	Message	A message is sent to this channel
onKeystrokesReceived	Keystrokes	Typing keystrokes are made by users in this channel
onTypingStarted	User	A user starts typing in this channel
onTypingStopped	User	A user stops typing in this channel
onParticipantEnteredChat	User	A user starts a chat session in this channel
onParticipantLeftChat	User	A user ends their active chat session in this channel
onParticipantPresenceChanged	User	A member of this channel changes their presence status (goes online or offline)
onMessageUpdated	Message	A message sent in this channel has been updated
onChannelUpdated	Channel	The channel associated with this chat session has been updated
onMessageRead	Message, ReadReceipt	A message sent in this channel has been read

Properties

Name	Type	Description	Required
channel	Channel	The channel this session was started for	✔
end	function	Ends 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.

Parameters

Name	Type	Description	Required
channel	Channel	The channel this session is associated with	✔
onMessageReceived	Message	A message is sent to this channel
onKeystrokesReceived	Keystrokes	Typing keystrokes are made by users in this channel
onTypingStarted	User	A user starts typing in this channel
onTypingStopped	User	A user stops typing in this channel
onParticipantEnteredChat	User	A user starts a chat session in this channel
onParticipantLeftChat	User	A user ends their active chat session in this channel
onParticipantPresenceChanged	User	A member of this channel changes their presence status (goes online or offline)
onMessageUpdated	Message	A message sent in this channel has been updated
onChannelUpdated	Channel	The channel associated with this chat session has been updated
onMessageRead	Message, ReadReceipt	A message sent in this channel has been read

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.

session.end();

note

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