JavaScript/TypeScript Client SDK for OpenIM 👨‍💻💬

Use this SDK to add instant messaging capabilities to your application. By connecting to a self-hosted OpenIM server, you can quickly integrate instant messaging capabilities into your app with just a few lines of code.

The underlying SDK core is implemented in OpenIM SDK Core. Using the WebAssembly support provided by Go language, it can be compiled into wasm for web integration. The web interacts with the OpenIM SDK Core through JSON, and the SDK exposes a re-encapsulated API for easy usage. In terms of data storage, JavaScript handles the logic of the SQL layer by virtualizing SQLite and storing it in IndexedDB using sql.js.

Documentation 📚

Visit https://doc.rentsoft.cn/ for detailed documentation and guides.

For the SDK reference, see https://doc.rentsoft.cn/sdks/quickstart/browser.

Installation 💻

Adding Dependencies

npm install open-im-sdk-wasm --save

Obtaining Required Static Resources for WASM

Follow these steps to obtain the static resources required for WebAssembly (WASM):

Locate the open-im-sdk-wasm subdirectory in the node_modules directory of your project. Copy all the files in the assets folder to your project's public resource directory.

The files to be copied are:
- openIM.wasm
- sql-wasm.wasm
- wasm_exec.js
After copying the files, import the wasm_exec.js file in your index.html file using a <script> tag.

Possible Issues ❗

For Webpack 5+

Add the following configuration to your Webpack configuration:

resolve: {
  fallback: {
    fs: false,
    path: false,
    crypto: false,
  },
},

For Webpack 4 or Vite

Note: If you are using Webpack 4, you will also need to install the worker loader.

npm install worker-loader worker-plugin -D

Add the following configuration to your Webpack configuration:

const WorkerPlugin = require("worker-plugin");

// ...

plugins: [new WorkerPlugin()],

// ...

Follow these steps:

Copy the lib directory from the npm package to your project (e.g., src/utils/lib).

Modify the import method of the web worker in the lib/api/index.js file.

// For Webpack 4:
+ import IMWorker from 'worker-loader!./worker.js';
// For Vite:
+ import IMWorker from './worker?worker';

- worker = new Worker(new URL('./worker.js', import.meta.url));
+ worker = new IMWorker();

Usage 🚀

The following examples demonstrate how to use the SDK. TypeScript is used, providing complete type hints.

Importing the SDK

import { getSDK } from 'open-im-sdk-wasm';
// or your own path after copying
// import { getSDK } from '@/utils/lib';

const OpenIM = getSDK();

Logging In and Listening for Connection Status

Note: You need to deploy OpenIM Server first, the default port of OpenIM Server is 10001, 10002.

import { CbEvents } from 'open-im-sdk-wasm';
import type { WSEvent } from 'open-im-sdk-wasm';

OpenIM.on(CbEvents.OnConnecting, handleConnecting);
OpenIM.on(CbEvents.OnConnectFailed, handleConnectFailed);
OpenIM.on(CbEvents.OnConnectSuccess, handleConnectSuccess);

OpenIM.login({
  userID: 'IM user ID',
  token: 'IM user token',
  platformID: 5,
  apiAddr: 'http://your-server-ip:10002',
  wsAddr: 'ws://your-server-ip:10001',
});

function handleConnecting() {
  // Connecting...
}

function handleConnectFailed({ errCode, errMsg }: WSEvent) {
  // Connection failed ❌
  console.log(errCode, errMsg);
}

function handleConnectSuccess() {
  // Connection successful ✅
}

To log into the IM server, you need to create an account and obtain a user ID and token. Refer to the access token documentation for details.

Receiving and Sending Messages 💬

OpenIM makes it easy to send and receive messages. By default, there is no restriction on having a friend relationship to send messages (although you can configure other policies on the server). If you know the user ID of the recipient, you can conveniently send a message to them.

import { CbEvents } from 'open-im-sdk-wasm';
import type { WSEvent, MessageItem } from 'open-im-sdk-wasm';

// Listenfor new messages 📩
OpenIM.on(CbEvents.OnRecvNewMessages, handleNewMessages);

const message = (await OpenIM.createTextMessage('hello openim')).data;

OpenIM.sendMessage({
  recvID: 'recipient user ID',
  groupID: '',
  message,
})
  .then(() => {
    // Message sent successfully ✉️
  })
  .catch(err => {
    // Failed to send message ❌
    console.log(err);
  });

function handleNewMessages({ data }: WSEvent<MessageItem[]>) {
  // New message list 📨
  console.log(data);
}

Examples 🌟

You can find a demo web app that uses the SDK in the openim-pc-web-demo repository.

Browser Support 🌐

Browser	Desktop OS	Mobile OS
Chrome (61+)	Windows, macOS, Linux	Android
Firefox (58+)	Windows, macOS, Linux	Android
Safari (15+)	macOS	iOS
Edge (Chromium 16+)	Windows, macOS

Community 👥

Community Meetings 📆

We want anyone to get involved in our community and contributing code, we offer gifts and rewards, and we welcome you to join us every Thursday night.

Our conference is in the OpenIM Slack 🎯, then you can search the Open-IM-Server pipeline to join

We take notes of each biweekly meeting in GitHub discussions, Our historical meeting notes, as well as replays of the meetings are available at Google Docs 📑.

Who are using OpenIM 👀

Check out our user case studies page for a list of the project users. Don't hesitate to leave a 📝comment and share your use case.

License 📄

OpenIM is licensed under the Apache 2.0 license. See LICENSE for the full license text.

hefangxuan / open-im-sdk-web-wasm