Skip to main content

JavaScript quick start

Installing the ChatKitty JS Core SDK​

To use the ChatKitty JavaScript Chat SDK, you'll need to add the ChatKitty JavaScript SDK NPM package to your JavaScript front-end project:

npm install @chatkitty/core

Initializing the ChatKitty SDK with your API key​

With your API key from the ChatKitty dashboard, you can initialize a new instance of the ChatKitty client:

import ChatKitty from '@chatkitty/core';

export const chatkitty = ChatKitty.getInstance('YOUR CHATKITTY API KEY HERE');

With that, you can now use the ChatKitty SDK to begin building real-time chat features into your application.

Starting a guest user session​

You must create a user session before a user can begin chatting with other users using ChatKitty. A user session represents a secure bidirectional connection with ChatKitty servers allowing users to send and receive messages in real-time.

Before you learn about authenticating users with ChatKitty, you can create a guest user session. You can start a user session by passing a unique username to your ChatKitty client's startSession() method. A username is a string that uniquely identifies a user within your application.

const result = await chatkitty.startSession({
  username: 'jane@chatkitty.com'
});

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

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

We recommend you use uniquely hashed email addresses or phone numbers as usernames.

Creating a public channel​

With a ChatKitty connection established, you can create a public channel that any user can view and join.

const result = await chatkitty.createChannel({
  type: 'PUBLIC',
  name: 'my-first-public-channel',
});

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

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

Creating a direct channel​

With a ChatKitty connection established, you can create a direct channel to direct message (DM) another user.

const result = await chatkitty.createChannel({
  type: 'DIRECT',
  members: [{ username: 'john@chatkitty.com' }],
});

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

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

Starting a chat session​

Next, start a chat session using startChatSession() to listen to channel events.

const result = chatkitty.startChatSession({
  channel: channel,
  onMessageReceived: (message) => {
    // handle received messages
  },
  onKeystrokesReceived: (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 disturb, invisible
  },
  onMessageRead: (message, receipt) => {
    // handle read receipt for message
  },
  onMessageUpdated: (message) => {
    // handle message changes
  },
  onChannelUpdated: (channel) => {
    // handle channel changes
  },
});

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

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

Receiving channel messages​

ChatKitty lets you register a number of handler methods when starting a chat session. Perhaps most important is the onMessageReceived() handler method. This method is called in real-time whenever a new message is sent by a channel member. Typically, this is where you included code to update your UI with the new message.

note

All handler methods are optional. You only needed to register handlers for chat events your application cares about.

Sending messages​

To send a message to a channel with an active chat session, use sendMessage().

Sending a text message​

To send a text message pass a string body to sendMessage().

const result = await chatkitty.sendMessage({
  channel: channel,
  body: 'Hello, world!',
});

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

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

Sending a file message​

To send a file message pass a JavaScript file or CreateChatKittyFileProperties as file to sendMessage(). Optionally, you can pass a ChatKittyUploadProgressListener to track file upload progress.

const result = await chatkitty.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
}

Getting channel message history​

To fetch previous messages sent in a channel, use the getMessages() method.

const result = await chatkitty.listMessages({
  channel: channel,
});

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

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