use-chat

Wrap your application (or chat component tree) with ChatProvider. You must pass the serviceFactory, a storage instance, and an optional config object.

Config Options:

• typingThrottleTime: Time in ms to throttle received typing indicators.
• typingDebounceTime: Time in ms to debounce sent typing indicators.
• debounceTyping: Boolean to enable/disable debouncing of sent typing indicators.
• autoDraft: Configuration for message drafts (e.g., AutoDraft.Save | AutoDraft.Restore).

import {
  BasicStorage,
  ChatProvider,
  AutoDraft
} from "@chatscope/use-chat";

const chatStorage = new BasicStorage({
  groupIdGenerator: () => "some-id",
  messageIdGenerator: () => "some-id"
});

const serviceFactory = (storage, updateState) => {
  return new MyChatService(storage, updateState);
};

<ChatProvider 
  serviceFactory={serviceFactory} 
  storage={chatStorage} 
  config={{
    typingThrottleTime: 250,
    typingDebounceTime: 900,
    debounceTyping: true,
    autoDraft: AutoDraft.Save | AutoDraft.Restore
  }}
>
  <App />
</ChatProvider>

The useChat hook provides access to the current state of the chat and methods to interact with it. Common properties and methods include:

• currentMessages: An array of grouped messages for the active conversation.
• conversations: A list of all available conversations.
• activeConversation: The currently selected conversation object.
• setActiveConversation(id): Method to switch the active chat.
• sendMessage({ message, conversationId, senderId }): Method to send a message.
• getUser(id): Method to retrieve user data by ID.

Example usage:

import { useChat, ChatMessage, MessageContentType, MessageDirection, MessageStatus } from "@chatscope/use-chat";

export const Chat = () => {
  const { 
    currentMessages, 
    conversations, 
    activeConversation, 
    setActiveConversation, 
    sendMessage, 
    getUser 
  } = useChat();

  const handleSend = text => {
    const message = new ChatMessage({
      id: "",
      content: text,
      contentType: MessageContentType.TextHtml,
      senderId: "my-user-id",
      direction: MessageDirection.Outgoing,
      status: MessageStatus.Sent
    });

    sendMessage({
      message,
      conversationId: activeConversation.id,
      senderId: "my-user-id",
    });
  };

  // ... render logic
};

Use the following methods to manage conversations within BasicStorage:

• addConversation(conversation: Conversation<ConversationData>): boolean: Adds a new conversation. Returns true if added.
• getConversation(conversationId: ConversationId): [Conversation<ConversationData>, number] | [undefined, undefined]: Retrieves a conversation and its index.
• updateConversation(conversation: Conversation<ConversationData>): void: Replaces an existing conversation with updated data.
• removeConversation(conversationId: ConversationId, removeMessages?: boolean): boolean: Removes a conversation. If removeMessages is true (default), all messages associated with this conversation are also deleted.
• conversationExists(conversationId: ConversationId): boolean: Checks if a conversation ID exists.
• setUnread(conversationId: ConversationId, count: number): void: Updates the unread message counter for a conversation.
• setActiveConversation(conversationId?: ConversationId, resetUnreadCounter?: boolean): void: Sets the active conversation. If resetUnreadCounter is true (default), the unread counter for the new active conversation is set to 0.

The TypingUsersList class is used to maintain a collection of users who are currently typing. It provides methods to add, remove, and locate users within the list based on their UserId.

Key Methods

• addUser(typingUser: TypingUser): Adds a user to the list. If a user with the same userId already exists, the existing entry is replaced with the new typingUser object.
• removeUser(userId: UserId): Removes the user with the specified ID from the collection.
• findIndex(userId: UserId): Returns the index of the user in the list, or -1 if the user is not found.
• length: A getter that returns the current number of typing users in the list.

import { TypingUsersList } from './TypingUsersList';
import { TypingUser } from './TypingUser';

// Initialize the list
const typingList = new TypingUsersList({ items: [] });

// Add a user
typingList.addUser({ userId: 'user-123', name: 'John Doe' } as TypingUser);

// Check length
console.log(typingList.length); // 1

// Remove a user
typingList.removeUser('user-123');

// Find index
const index = typingList.findIndex('user-123'); // -1

The MessageContent interface and its specialized implementations define the structure of data carried by a message. Depending on the MessageContentType, the content field (or specific fields like url and data) will hold different data types such as strings, arrays of items, or binary data.

Common content types include:

• Text-based: TextContent (plain text), MarkdownContent (markdown), HtmlContent (HTML), and KmlContent (KML strings).
• Media: ImageContent, VideoContent, and GalleryContent (an array of GalleryItem).
• Files: AttachmentContent and AttachmentListContent.
• Other: VCardContent and OtherContent (using unknown for flexible payloads).

Note on Binary vs URL: For ImageContent, AttachmentContent, and VideoContent, if the url is an empty string, the content is treated as binary data provided in the data field (ArrayBuffer).

// Example of an ImageContent object
const imageMessage: ImageContent = {
  url: "https://example.com/image.png",
  data: new ArrayBuffer(0) // or actual buffer if url is empty
};

// Example of a GalleryContent object
const galleryMessage: GalleryContent = {
  content: [
    { description: "First image", src: "https://example.com/1.png" },
    { description: "Second image", src: "https://example.com/2.png" }
  ]
};