Quickstart

Install the SDK from public npm and go through "create users → look up a user → send a message" in a dedicated test app. This only needs Node.js, with no source repository or TypeScript compiler.

Prepare the app

1. Install Node.js 22.17.0 or later, and check with node --version.
2. In the console, use the demo app created when you signed up, or create an app, and get the Client ID and Client Secret under "Access credentials" on the Overview.
3. Have the server API address and the AppKey ready. In the AppKey, the part before # is the org name and the part after is the app name.

This example creates two test users and sends a text message. Use a dedicated test app; the script prints the usernames so you can clean them up in the console afterward.

Install

mkdir im-node-quickstart
cd im-node-quickstart
npm init -y
npm install @deeprespond/im-server-sdk@1.0.7

In an existing pnpm project you can run pnpm add @deeprespond/im-server-sdk@1.0.7 instead. Check the version after installing:

node -p "require('@deeprespond/im-server-sdk/package.json').version"

It should print 1.0.7. The npm package page and release notes list what's distributed and what was verified.

Set environment variables

Create .env in the project root and replace the placeholders with your test app's details:

IM_BASE_URL=https://im.example.com
IM_ORG_NAME=your_org
IM_APP_NAME=your_app
IM_CLIENT_ID=replace_with_client_id
IM_CLIENT_SECRET=replace_with_client_secret

IM_BASE_URL is the API root your deployment gives you, without /openapi/v1 or org and app paths; the SDK adds those. The placeholder domain can't be called. The Client ID and Secret are server credentials; the App ID and callback signing secrets can't stand in for them.

Add .env to the project's .gitignore. In production, have your deployment platform inject the same variables, and never put credentials in web pages or apps.

Write main.mjs

Save the following as main.mjs. The .mjs extension means ES modules with top-level await, so you don't need to change type in package.json.

import { randomUUID } from 'node:crypto';
import { DRClient, isDRError } from '@deeprespond/im-server-sdk';

function required(name) {
  const value = process.env[name]?.trim();
  if (!value) throw new Error(`缺少环境变量 ${name}`);
  return value;
}

const im = new DRClient({
  baseUrl: required('IM_BASE_URL'),
  orgName: required('IM_ORG_NAME'),
  appName: required('IM_APP_NAME'),
  clientId: required('IM_CLIENT_ID'),
  clientSecret: required('IM_CLIENT_SECRET'),
});

const suffix = randomUUID().replaceAll('-', '').slice(0, 12);
const alice = `sdk_alice_${suffix}`;
const bob = `sdk_bob_${suffix}`;
console.log('本次测试用户：', alice, bob);

try {
  await im.users.create(alice, { nickname: 'Node 示例 Alice' });
  await im.users.create(bob, { nickname: 'Node 示例 Bob' });
  const user = await im.users.get(alice);
  console.log('查询成功：', user.username);

  const sent = await im.messages.send({
    from: alice,
    to_user: bob,
    client_msg_id: `quickstart_${suffix}`,
    type: 'text',
    body: { text: '你好，这是一条来自 Node.js 服务端 SDK 的消息。' },
  });
  console.log('发送接口返回：', sent.message_id);
} catch (error) {
  if (isDRError(error)) {
    console.error({
      code: error.code,
      reason: error.reason,
      op: error.op,
      requestId: error.requestId,
    });
  } else {
    console.error(error instanceof Error ? error.message : '执行失败');
  }
  process.exitCode = 1;
} finally {
  await im.close();
}

Run and check

Run it in the directory with .env and main.mjs; the same command works in Windows PowerShell:

node --env-file=.env main.mjs

On success it prints the two test usernames, the lookup result and a message_id. That means the create, lookup and send APIs worked; whether the recipient receives it online, syncs it offline and returns read status needs a client SDK signed in as them.

Each run generates new test usernames. If it fails partway, users already created aren't deleted automatically; use the usernames printed at the start to check and clean up. When retrying the same business message, reuse the original client_msg_id; see Retries and idempotency.

Use it in your own service

Long-running back ends create a DRClient in a module, reuse it, and close it when the process stops. After a user signs in to your system successfully, a protected back-end endpoint issues the IM sign-in ticket:

// im 为服务启动时创建的客户端；username 来自已经认证的业务用户。
const result = await im.users.issueLoginTicket(username, { auto_create: true });
// 仅将 result.ticket 返回给该用户，再交给客户端 SDK 登录。

The SDK manages the App Token internally; users' sign-in tickets come from issueLoginTicket(); and the callback secret is only for verifying signatures at the receiver. For what each is for and how to troubleshoot them, see Credentials and identities.

• Calling the API: timeouts, errors, paging, batches, files and standalone channels.
• Receiving callbacks: event subscriptions, sync hooks and framework integrations.
• Examples guide: TypeScript, Fastify, Express, NestJS and Next.js.
• FAQ and troubleshooting: track down install, authentication, retry and callback problems by symptom.