Introduction

Integrate real-time chat into your React Native or Web application with the ChatKitty JavaScript SDK.

Installation

ChatKitty is available as an npm package.

Install the ChatKitty npm package with yarn...

yarn add chatkitty

...or with npm

npm install chatkitty

Authentication

Initialize the Chat SDK with your API key

Get a ChatKitty instance with your API key

import ChatKitty from 'chatkitty';

export const kitty = ChatKitty.getInstance(CHATKITTY_API_KEY);

Create a ChatKitty instance by passing your application's API key to the ChatKitty.getInstance(string) method as a parameter.

Starting a user session

To make calls to ChatKitty through the Chat SDK, a user session must be started. A user session creates an open connection to ChatKitty belonging a user throughout the duration of their usage of your application, until the user session is ended. A user session is active from when it was started until it's ended by the user, or the session connection is lost.

You can start a user session using the unique username of a user and optional authentication parameters to secure the user session.

Starting a user session with a username and authentication parameters

Starting a user session

const result = await kitty.startSession({
  username: email,
  authParams: { // parameters to pass to authentication chat function
    password: password, 
  },
});

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

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

If you're using ChatKitty Chat Functions, you can provide custom authentication logic or proxy user authentication through your backend using a User Attempted Start Session chat function. The chat function will be passed the username and authentication parameters from a ChatKitty.startSession(StartSessionRequest) call. Your logic will determine if the user is allowed to start a session with their credentials.

Starting a user session with just a username (guest user session)

Starting a guest user session

const result = await kitty.startSession({
  username: email,
});

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

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

If your application has the guest user feature enabled, you can start a user session by calling the ChatKitty.startSession(StartSessionRequest) method with only your user's unique name.

Ending a user session

Ending a user session

kitty.endSession();

To end a user ChatKitty session, call the ChatKitty.endSession() method.

Current User

Get the current user

const result = await kitty.getCurrentUser();

const user = result.user; // Handle user

After starting a ChatKitty user session, you can request the current user anytime by calling the ChatKitty.getCurrentUser() method.

Observing the current user

Observing the current user changes

const unsubscribe = kitty.onCurrentUserChanged((user) => {
  // handle new current user or current user changes
});

unsubscribe(); // call unsubscribe function when you're no longer interested in current user changes

Get updates when the current user changes by using the ChatKitty.onCurrentUserChanged((user: CurrentUser | null) => void) method.

Updating the current user

Updating the current user

await kitty.updateCurrentUser((user) => {
  user.properties = {
    ...user.properties,
    "new-property": newPropertyValue,
  };

  return user;
});

Update the current user by using the ChatKitty.updateCurrentUser((user: CurrentUser) => CurrentUser) method, taking the current user and returning a user with the changes to be applied.

Channels

Channels are the backbone of the ChatKitty chat experience. Users can join channels and receive or send messages. After a user joins a channel, the user becomes a channel member. ChatKitty broadcasts messages created in channels to channel members with active chat sessions and sends push notifications to offline members.

Channel types

There are four types of channels;

Public Channel

Users can join public channels by themselves or via invites from an existing channel member. ChatKitty persists messages sent in public channels by default but this behaviour can be configured.

Private Channel

Users can only join private channels via invites from an existing channel member. ChatKitty persists messages sent in private channels by default but this behaviour can be configured.

Direct Channel

Direct channels let users have private conversations between up to 9 other users. New users cannot be added to a direct channel and there can only exist one direct channel between a set of users.

Open Channel

Open channels provide Twitch-style chats where many users can join the chat without invites and send messages.

Creating a channel

Creating a new public channel

const result = await kitty.createChannel({
  type: "PUBLIC",
  name: channelName,
});

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

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

Creating a new direct channel

const result = await kitty.createChannel({
  type: "DIRECT",
  name: channelName,
  members: [{ id: userId }, { id: anotherUserId }],
});

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

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

Create a new channel by using the ChatKitty.createChannel(CreateChannelRequest) method. A user is automatically a member of a group channel they created.

Get channels

Get channels the current user can begin chat sessions in

const result = await kitty.getChannels();

if (result.succeeded) {
  const channels = result.paginator.items; // Handle channels
}

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

You can get channels the current user can chat in by calling the ChatKitty.getChannels() method.

Get joinable channels

Get group channels the current user can become a member of

const result = await kitty.getChannels({ joinable: true });

if (result.succeeded) {
  const channels = result.paginator.items; // Handle channels
}

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

Get channels the current user can join, becoming a member, by calling the ChatKitty.getChannels({ joinable: true }) method.

Getting a channel

Getting a channel by id

const result = await kitty.getChannel(channelId);

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

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

Get a channel by searchable properties like channel ID by using the ChatKitty.getChannel(property) method.

Joining a channel

Joining a group channel

const result = await kitty.joinChannel({ channel: channel });

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

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

The current user can join a group channel, becoming a member, by using the ChatKitty.joinChannel(JoinChannelRequest) method.

Listening for joined channels

Listening for joined channels

const unsubscribe = kitty.onJoinedChannel((channel) => {
  // handle channel
});

unsubscribe(); // call unsubscribe function when you're no longer interested in recieving updates

When user joins a channel or is added to a channel by another user or through the Platform API, registered on joined channel listeners are notified. Register a listener using the ChatKitty.onJoinedChannel((channel: Channel) => void) method.

Getting channel members

Getting channel members

const result = await kitty.getChannelMembers({
 channel: channel,
});

if (result.succeeded) {
 const members = result.paginator.items; // Handle members
}

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

You can get a channel's members by calling the ChatKitty.getChannelMembers(GetChannelMembersRequest) method.

Checking if channel is unread

Checking if a channel has unread messages

const result = await kitty.getChannelUnread({
 channel: channel,
});

if (result.succeeded) {
 const unread = result.unread; // Handle unread boolean
}

A channel is unread if it has any unread messages by the current user. You can check if a channel is unread by calling the ChatKitty.getChannelUnread(GetChannelUnreadRequest) method.

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, emoji and like reactions, etc, their device needs to start a chat session.

Starting a chat session

Starting a chat session

const result = kitty.startChatSession({
      channel: channel,
      onReceivedMessage: (message) => {},
    });

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

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

Start a chat session by calling the ChatKitty.startChatSession(StartChatSessionRequest) method. This method returns a StartChatSessionResult object with a ChatSession, which can be used to later end the chat session, if the session was successfully started.

Listening to chat session events

Registering chat session event handler methods when starting a chat session

kitty.startChatSession({
 channel: channel,
 onReceivedMessage: (message) => {
  // handle received messages
 },
 onReceivedKeystrokes: (keystrokes) => {
  // handle received typing keystrokes
 },
 onTypingStarted: (user) => {
  // handle user starts typing
 },
 onTypingStopped: (user) => {
  // handle user stops typing
 },
 onParticipantEnteredChat: (user) => {
  // handle user who just entered the chat
 },
 onParticipantLeftChat: (user) => {
  // handle user who just left the chat
 },
 onParticipantPresenceChanged: (user) => {
  // handle user who became online, offline, do not distrub, invisible
 },
});

When an event involving a chat session channel happens, like a message sent in the channel or another user joined the channel, a corresponding chat session event handler method registered when starting the session is called.

Chat session event handler methods

Ending a chat session

Ending a chat session using its chat session object

session.end(); // Ends the session

Ending a chat session using the ChatKitty client

ChatKitty.endChatSession(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.

End a chat session by calling either the ChatSession's end() or ChatKitty.endChatSession(ChatSession) method.

Messages

Users send messages through your application and administrators can send messages through the Platform API.

Messages types

There are four types of messages;

Text Message

Users can send text messages containing a unicode text body. These messages can contain emojis and other unicode characters but have no file attachments.

File Message

Users can send files messages with one, or many file attachments.

System Text Message

Administrators can send text messages containing a unicode text body. These messages can contain emojis and other unicode characters but have no file attachments.

System File Message

Administrators can send files messages with one, or many file attachments.

Send a message

Sending a text message to a channel

const result = await kitty.sendMessage({
  channel: channel,
  body: messageText,
});

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

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

Sending a file message to a channel

const result = await kitty.sendMessage({
 channel: channel,
 file: file,
 progressListener: {
  onStarted: () => {
   // Handle file upload started
  },

  onProgress: (progress) => {
   // Handle file upload process
  },

  onCompleted: (result) => {
   // Handle file upload completed
  },
 },
});

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

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

You can send a message by calling the ChatKitty.sendMessage(SendMessageRequest) method.

Receiving messages in real-time

Receiving chat session messages in real-time

kitty.startChatSession({
 channel: channel,
 onReceivedMessage: (message) => {
  // Handle recevied message
 },
});

You can receive messages in real-time by starting a chat session and registering a onReceivedMessage handler.

Get messages

Get messages inside a channel

const result = await kitty.getMessages({
  channel: channel,
});

if (result.succeeded) {
  const messages = result.paginator.items; // Handle messages
}

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

You can get messages in a channel by calling the ChatKitty.getChannelMessages(GetMessagesRequest) method.

Notifications

Notifications inform a user of relevant actions related to another screen in your application from their current screen. ChatKitty sends notifications to your app through the ChatKitty JavaScript SDK when an action outside of an active chat session occurs. You can listen for these notifications and use them to build in-app notification views.

Listening to in-app notifications

Listening for new in-app notifications

const unsubscribe = kitty.onNotificationReceived((notification) => {
  // handle notification
});

unsubscribe(); // call unsubscribe function when you're no longer interested in recieving notifications

When an event outside of an active chat session happens, like a message sent, a notification is sent to registered notification listeners. Register a notification listener using the ChatKitty.onNotificationReceived((notification: Notification) => void) method.

Notification types

Handling notification types

kitty.onNotificationReceived((notification) => {
  switch (notification.data.type) {
    case "USER:SENT:MESSAGE":
      // handle notification data
      break;
    case "SYSTEM:SENT:MESSAGE":
      // handle notification data
      break;
  }
});