@talkjs/core/README.md

Lets you connect to your TalkJS chat as a user and read, subscribe to, and update your chat data.

# TalkJS Core

The `@talkjs/core` package lets you connect to your [TalkJS](https://talkjs.com) chat as a user and read, subscribe to, and update your chat data.

[See our docs](https://talkjs.com/docs/Reference/JavaScript_Data_API/) for more information.

## Prerequisites

To use this package, you will need a [TalkJS account](https://talkjs.com/dashboard/login). 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:

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

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

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

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

```js
// 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 `WebSocket`s 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 `WebSocket`s, you will need to add support with a library. We recommend installing the [ws](https://www.npmjs.com/package/ws) package. Then tell `@talkjs/core` to use `WebSocket` from the library:

```js
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](https://talkjs.com/?chat). TalkJS support is staffed by engineers.

## Changelog

### 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