chat bots: you can implement any logic of connecting with and communicating with SimpleX Chat users. Using chat groups a chat bot can connect SimpleX Chat users with each other.
control of the equipment: e.g. servers or home automation. SimpleX Chat provides secure and authorised connections, so this is more secure than using rest APIs.
any scenarios of scripted message sending.
chat and chat-based interfaces.
Please share your use cases and implementations.
Quick start: a simple bot
npm i simplex-chat@6.5.1
Simple 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:
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
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.
Native library
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 only
Set 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.
PostgreSQL backend
DbConfig.type selects the backend; one backend per process.
libpq5 must be installed on the host system (apt install libpq5 on Debian/Ubuntu)
PostgreSQL backend is only available for Linux x86_64
A PostgreSQL server accessible via connection string
bot: a simple declarative API to run a chat-bot with a single function call. It automates creating and updating of the bot profile, address and bot commands shown in the app UI.
api: an API to send chat commands and receive chat events to/from chat core. You need to use it in bot event handlers, and for any other use cases.
core: a low level API to the core library - the same that is used in desktop clients. You are unlikely to ever need to use this module directly, except for image resizing.
create and change user profile (although, in most cases you can do it manually, via SimpleX Chat terminal app).
create and accept invitations or connect with the contacts.
create and manage long-term user address, accepting connection requests automatically.
send, receive, delete and update messages, and add message reactions.
send live messages, e.g. streamed replies.
create, join and manage group.
send and receive files.
etc.
Tests
npm installnpm run buildnpm test
To 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: