SoftchatJS Core

Javascript client for JS based frameworks

Initiating the client

To get started a new connection instance needs to be created by passing in the your projectId and subId. Create a free account at: https://www.softchatjs.com

import ChatClient, { Conversation, Message } from 'softchatjs-core';

const client = ChatClient.getInstance({ subId: '1234', projectId: '1234' });

Create a user session

To get started a new connection instance needs to be created by passing in the your projectId and subId

import ChatClient, { Conversation, Message } from 'softchatjs-core';

// To create a user session, pass in the user's id and username
// if the uid doesn't alread exist, a new user is created

const chatUser = { 
    uid: '14', 
    username: 'oscar',
    firstname: '',  // optional
    profileUrl: '', // optional
    lastname: '', // optional
    custom: {}, // optional
    color: '' // optional
}
client.initializeUser(chatUser);

Notifications

Push notifications are supported through Expo, Firebase Cloud Messaging (FCM), and Apple Push Notification Service (APNS). While Expo push notifications are configured to work seamlessly without additional setup, integrating FCM or APNS requires uploading your credentials to the dashboard. Navigate to Project → Settings to add your FCM or APNS credentials.

How to initiate a session with a user's notification details:

var notificationConfig = {
  type: "expo" // "expo" | "fcm" | "apns",
  token: "Expo[XXXXXX]" // device token
}
client.initializeUser(chatUser, { notificationConfig });

The MessageClient Overview

The MessageClient provides a comprehensive interface for managing conversations, messages, and broadcast lists within your application. It offers a variety of methods to streamline interactions with these components, enabling developers to efficiently integrate messaging functionalities.

import ChatClient, { Conversation, Message } from 'softchatjs-core';

// To create a user session, pass in the user's id and username
// if the id doesn't alread exist, a new user is created

const chatUser = { 
  uid: '14', 
  username: 'oscar',
  firstname: '',  // optional
  profileUrl: '', // optional
  lastname: '', // optional
  custom: {}, // optional
  color: '' // optional
}

client.initializeUser(chatUser);

Get message history:

const messages = await client.messageClient(conversationId).getMessages() as Array<Message>
setMessages(messages);

Sending a message:

const conversationId = "my-conversation-id"; // replace with actual conversation id
const recipientId = '19';
const msClient = client.messageClient(conversationId);
msClinet.sendMessage({
  conversationId,
  to: recipientId, // replace with actual userId
  message: "Hello 😊",
  quotedMessageId: "",
  reactions: [],
  attachedMedia: [],
  quotedMessage: null
})

Edit a message:

  const conversationId = "my-conversation-id"; // replace with actual converationId
  const msClient = client.messageClient(conversationId);
  msClient.editMessage({
  to: "user-123", // replace with actual userId
  conversationId: "my-conversation-id",
  messageId: "message-id-to-delete",
  textMessage: "Hey there!",
  shouldEdit: true,

Send typing notification:

  const conversationId = "my-conversation-id"; // replace with actual converationId
  const msClient = client.messageClient(conversationId);
  msClient.sendTypingNotification(
    "user-123", // replace with actual userId
  );

Sending stopped typing notification:

  const conversationId = "my-conversation-id"; // replace with actual converationId
  const msClient = client.messageClient(conversationId);
  msClient.sendStoppedTypingNotification(
    "user-123," // replace with actual userId
  );

React to a message

  const conversationId = "my-conversation-id"; // replace with actual converationId
  const msClient = client.messageClient(conversationId);
  msClient.reactToMessage(
    {
      conversationId,
      messageId: "message-id",
      reactions: [{
        emoji: "🤷",
        uid: "me-123", // this needs to be fixed**
      }],
      to: "user-123" // replace with actual userId
    }
  );

Upload an attachment

  const conversationId = "my-conversation-id"; // replace with actual converationId
  const msClient = client.messageClient(conversationId);
  const res = await msClient.uploadFile(
    uri: string | NodeJS.ReadableStream | Buffer | File,
    meta: {
      filename: string;
      mimeType: string;
      ext: string
    }
  )

  // res = { data: { url: 'https://www.uploaded.file.com/123' } }

Delete a message

const msClient = client.messageClient(conversationId);
msClient.deleteMessage(messageId, conversationId);

Get messages

Messages are paginated by default, with 25 per page

const msClient = client.messageClient(conversationId);
const messages = await msClient.getMessages(1); // page

Read messages

const msClient = client.messageClient(conversationId);
msClient.readMessages(conversatioId, { uid: 'my-id', messageIds: ['message-id'] });

Create new conversation

There are two types of conversations private-chat & group-chat (Private conversations and Group conversations). Creating a conversation requires two steps; Adding participant(s) and sending the initial message

Creating a private conversation private-chat

 const conn = client.newConversation({ id: "100", username: 'john-123' });
 const newConversation = conn.create('Hey there');
 console.log(newConversation)

Creating a group conversation group-chat

 var participants = [
    { uid: "101", username: 'john-123' },
    { uid: "102", username: 'mike-234' },
    { uid: "103", username: 'susan-345' }
 ]
 var groupMeta = {
    groupName: 'Cool group',
    groupIcon: 'https://www.link-to-icon.com/png/200',
    groupBanner: 'https://www.link-to-icon.com/png/200'
 }
 const conn = client.newConversation(participants, groupMeta);
 conn.create('Hey there');

Events

Events are used to listen for detect and respond to changes in the user session

1. conversation_list_meta_changed:

client.subscribe("conversation_list_meta_changed", (event: ChatEventGenerics<{ conversationListMeta: ConversationListMeta }>) => {
  const conversationList = Object.values(event.conversationListMeta).flat() as { conversation: Conversation, lastMessage: Message, unread: string[] }[];
  console.log(conversationList)
})

2. connection_changed: Changes in the connection status:

client.subscribe("connection_changed", (event: ChatEventGenerics<ConnectionEvent>) => {
  console.log(event)
});

3. new_message: A new message recieved in a chat:

client.subscribe("new_message", (event) => {
  console.log(event);
});

4. edited_message: An existing message has been edited:

client.subscribe("edited_message", (event) => {
  console.log(event);
});

5. started_typing: Recipient started started typing:

client.subscribe("started_typing", (event) => {
    console.log(event);
});

6. stopped_typing: Recipient stopped typing:

client.subscribe("stopped_typing", (event) => {
    console.log(event);
});

7. deleted_message: Delete message from a conversation:

client.subscribe("deleted_message", (event) => {
console.log(event);
});

7. broadcast_list_meta_changed

client.subscribe("broadcast_list_meta_changed", (event) => {
console.log(event);
});

Unsubscribing from events

It's usually good practise to unsubscribe from from events when they're no longer in need. You can easily unsubscribe from an event by using the unsubscribe method from client Example:

client.unsubscribe("stopped_typing", handleStoppedTypingFunc);

// or to unsubscribe from all events

client.unsubscribeAll("stopped_typing");

Broadcast lists

Use broadacast lists to send a single message to multiple users, each conversation will be sent as a private message to each recipient

import ChatClient, { Conversation, Message, ChatEventGenerics } from 'softchatjs-core';

const client = ChatClient.getInstance({ subId: '1234', projectId: '1234' });

Create a new broadcast list
const newBroadcastList = client.newBroadcastList([
  {
    username: "skyline_ace",
    uid: "a1b2c3d4e5",
    firstname: "Alex",
    lastname: "Smith",
    profileUrl: "https://avatar.iran.liara.run/public",
    custom: { bio: "Lover of heights", hobby: "Climbing" },
    color: "#3498db",
  },
]);
const newList = newBroadcastList.create();
console.log(newList);

Update a broadacast list

client.updateBroadcastList({ broadcastListId: string, participants: string[], name: string });

Delete a broadacast list

client.deleteBroadcastList({ broadcastListId: "12345" })

Get connection status

You can check the connection status of a client, even if event handlers have not been configured yet.

var connStatus = client.getConnectionStatus();
console.log(connStatus);
// {
//   connecting: false,
//   isConnected: true,
//   fetchingConversations: false,
// }

Retrying a connection

If the connection is lost, the system will attempt to reconnect the user automatically. After 5 unsuccessful reconnection attempts, the connection will be terminated. To manually retry the connection, you can call the retryConnection() method at any time.

client.retryConnection();

Disconnecting a user

You may choose to disconnect a user, such as during a logout process or for other specific reasons. The disconnect() method terminates the socket connection and clears all associated user details.

client.disconnect();