TalkJS Core

The @talkjs/core package lets you connect to your TalkJS chat as a user and read, subscribe to, and update your chat data.

See our docs for more information.

Prerequisites

To use this package, you will need a TalkJS account. TalkJS provides a ready-to-use chat client for your application. Your account gives you access to TalkJS's free development environment.

Example

This example demonstrates how to create a TalkJS session and then create two users and conversation between them.

Install the @talkjs/core package:

npm install @talkjs/core
# or
yarn add @talkjs/core

Import it into the component where you want to use it:

import { getTalkSession } from "@talkjs/core";

Then add the following code to create the session, users and conversation:

// Replace with your own app ID
const appId = "<APP_ID>";
const userId = "alice";

const session = getTalkSession({ appId, userId });
session.currentUser.createIfNotExists({ name: "Alice" });

const conversation = session.conversation("my_conversation");
conversation.createIfNotExists();

conversation.subscribeMessages((messages) => {
  console.log(messages);
});

For example, if you are using React, add this code inside a useEffect hook.

Node.js compatibility

This package is primarily intended to be used in the browser because it only connects as a single user. However, it also works in Node.js.

The @talkjs/core package uses WebSockets to create a connection to the TalkJS servers. If you use @talkjs/core in the browser or in Node.js version 22, it will use the built-in WebSocket implementation automatically. Node.js version 21 will also use the built-in implementation if the --experimental-websocket flag is enabled.

If you are using an older version of Node.js without built-in support for WebSockets, you will need to add support with a library. We recommend installing the ws package. Then tell @talkjs/core to use WebSocket from the library:

import { getTalkSession, registerPolyfills } from "@talkjs/core";
import { WebSocket } from "ws";

registerPolyfills({ WebSocket: WebSocket });

const session = getTalkSession(...);

Support

If you encounter any problems with @talkjs/core, please open a chat with support. TalkJS support is staffed by engineers.

Changelog

1.6.0

• Added TalkSession.setToken(token: string) which reauthenticates the session with a new token.
• Added TalkSession.onNeedToken: () => void which gets called whenever a new auth token is needed. To use refreshable auth tokens, set a callback that fetches a new auth token and passed it to setToken.
• Deprecated token and tokenFetcher options in getTalkSession in favour of those two properties.
• Removed some duplicate logging on auth-related errors.
• Sessions no longer get garbage collected under any circumstances (to enable persistence of .setToken).
• Initial token fetch is now delayed until you actually use the session to send a request, rather than happening as soon as you call getTalkSession.

1.5.9

• Fixed a bug that would make the library crash under certain conditions.

1.5.8

• Bugfix for React Native.

1.5.7

• Fixed a bug that would cause a crash in React Native.

1.5.6

• Bugfix for on-prem deployments, no impact on the SAAS offering.

1.5.5

• Marked snapshot properties as readonly and applied Object.freeze to snapshots. These were never intended to be editable, as the snapshots are reused and shared between sessions.
• Improved docs for ConversationRef to better explain the reason why ConversationRef.set adds you to the conversation.

1.5.4

• Fixed a bug that prevented the websocket from disconnecting when idle after unsubscribing.

1.5.3

• Fixed a bug where subscribing to a conversation's messages after previously subscribing to that conversation, could cause an error related to sequence numbers being out-of-order.

1.5.2

• Added browser field to package.json.

1.5.1

• When passing markup text to ConversationRef.send, it now ignores formatted links and action buttons/links. Previously it parsed those nodes and tried to send them, which caused an error because users do not have permission to send those nodes.

1.5.0

• Fixed a bug where MessageRef.get() would always set MessageSnapshot.referencedMessage to null
• Added support for getting and setting emoji reactions on messages.
  • Added ReactionRef which is created via MessageRef.reaction.
  • Added ReactionSnapshot which is available in MessageSnapshot.reactions.
• Session.user, Session.conversation, ConversationRef.message, ConversationRef.participant, and MessageRef.reaction now all perform type validation on the argument and will throw an error if you use an invalid type or an empty string.

1.4.2

• Changed GenericFileBlock from subtype?: undefined to subtype?: never so that type narrowing works consistently when you check subtype === "<type>".

1.4.1

• Fixed an error when subscribing to a conversation while already subscribed to all conversations, or vice-versa.

1.4.0

• Added UserRef.subscribeOnline which subscribes to a user's online status.
  • Added UserOnlineSnapshot, UserOnlineSubscription, and UserOnlineActiveState.

1.3.0

• Added TalkSession.subscribeConversations which returns a windowed subscription to your most recently active conversations.
  • Added ConversationListSubscription and ConversationListActiveState.

1.2.0

• Added ConversationRef.subscribeParticipants which returns a windowed subscription to the participants in the conversation.
  • Added ParticipantSubscription and ParticipantActiveState.
• Improved startup time by sending queued requests faster when you first open the connection.

1.1.1

• Added ConversationSnapshot.everyoneReadUntil which is the minimum of all the participants' readUntil values.

1.1.0

• Added ConversationRef.subscribeTyping which lets you subscribe to typing indicators in a conversation.
  • Added TypingSubscription, TypingSnapshot, ManyTypingSnapshot, FewTypingSnapshot

1.0.1

• Fixed a bug with ConversationRef.subscribe where it would emit the same snapshot multiple times in a row, when old messages were edited or deleted.
• Exported types for GenericFileMetadata, AudioFileMetadata, ImageFileMetadata, VideoFileMetadata, and VoiceRecordingFileMetadata.

1.0.0

• Initial Release