package
SimpleX Chat Node.js library for chat bots
npm install simplex-chatGitHub-flavored package documentation.
Across all versions, last 30 days.
2,238 in 30 days
Runtime metadata.
Tagged topics.
Latest published Nov 12, 2026
latest
beta
This library replaced now deprecated SimpleX Chat WebRTC TypeScript client.
Please share your use cases and implementations.
npm i simplex-chat@6.5.1Simple bot that replies with squares of numbers you send to it:
(async () => {
const {bot} = await import("simplex-chat")
// if you are running from this GitHub repo:
// const {bot} = await import("../dist/index.js")
await bot.run({
profile: {displayName: "Squaring bot example", fullName: ""},
dbOpts: {type: "sqlite", filePrefix: "./squaring_bot"},
options: {
addressSettings: {welcomeMessage: "Send a number, I will square it.",
},
onMessage: async (ci, content, chat) => {
const n = +content.text
const reply = typeof n === "number" &&
If you installed this package as dependency, you can run this example with:
node ./node_modules/simplex-chat/examples/squaring-bot-readme.jsIf you run it on Mac, the first time it will take 20-30 seconds for MacOS to verify the library.
If you cloned this repository, you can:
cd ./packages/simplex-chat-nodejs
npm install
npm run build
SIMPLEX_ADDON_PATH=build/Release/simplex.node node ./examples/squaring-bot-readme.jsBuilding the Node.js add-on from source needs node-gyp build tools.
There is an example with more options in ./examples/squaring-bot.ts.
You can run it with: npx ts-node ./examples/squaring-bot.ts
A larger example, with a business address and commands as keys: SimpleX Calculator.
Live messages are shown to recipients while they are written, e.g. a streamed reply of a language model.
onMessage handler for bot.run that streams a reply:
const {api, util} = require("simplex-chat")
async function onMessage(ci, content, chat) {
const {chatType, chatId} = util.chatInfoRef(ci.chatInfo)
const live = new api.LiveMessage(chat, chatType, chatId)
let text = ""
for await (const delta of streamReply(content.text)) {
text += delta
live.update(text)
}
await live.end()
}streamReply stands for your function that returns text fragments as an async iterable.
update sends the first text at once, and then updates the message at most once per 3 seconds (interval parameter). end finalizes the message; a message without text is deleted.
The underlying commands: apiSendMessages with liveMessage = true sends a live message, apiUpdateChatItem with liveMessage = true updates it, and with liveMessage = false finalizes it.
libsimplex and the prebuilt Node.js add-on are downloaded on first use into the user cache ($XDG_CACHE_HOME/simplex-chat or ~/.cache/simplex-chat on Linux, ~/Library/Caches/simplex-chat on macOS, %LOCALAPPDATA%\simplex-chat on Windows), shared with the Python library. To download them ahead of time, for example in a Dockerfile, run as the user that runs the app:
npx simplex-chat install # sqlite (default)
npx simplex-chat install --backend postgres # Linux x86_64 onlySet SIMPLEX_LIBS_DIR to a directory with a local build of libsimplex and its dependencies to use it instead; it must be built for the backend in use. Set SIMPLEX_ADDON_PATH to a locally built add-on (build/Release/simplex.node) to use it instead of the downloaded one.
ChatApi.init loads the library for DbConfig.type; the low-level core functions require core.loadLibrary(backend) first.
DbConfig.type selects the backend; one backend per process.
libpq5 must be installed on the host system (apt install libpq5 on Debian/Ubuntu)// SQLite (default)
dbOpts: {type: "sqlite", filePrefix: "./data/bot"}
// optional: encryptionKey: "<sqlcipher-key>"
// PostgreSQL
dbOpts: {
type: "postgres",
connectionString: "postgres://user:pass@host/db",
// schemaPrefix: "bot", // optional — defaults to "simplex_v1"
}The library docs are here.
Library provides these modules:
This library uses @simplex-chat/types package with auto-generated bot API types.
Library provides types and functions to:
npm install
npm run build
npm testTo run one test file: npm test -- tests/core.test.ts.
A local SMP server is started for the API and bot tests. On Linux x86-64 and arm64, smp-server is downloaded from simplexmq releases to node_modules/.cache/smp-server. To use another build, or on other systems, set SMP_SERVER to the path of smp-server:
SMP_SERVER=/path/to/smp-server npm testshhhum
sh@simplex.chat
Estimated unpacked size across 5 packages.
787.6 kB
Includes dependencies.
3 direct dependencies.