几分钟内，为你的应用接入即时通信

快速开始

在控制台创建应用并复制 App Key，然后引入 SDK。SDK 不依赖框架，可直接用于 Vue、React 或原生页面。

复制<script src="/docs/sdk/im-sdk.js"></script>
<script>
IMSDK.init({
  appKey: 'app_xxxxxxxxx',
  apiBase: '/api/v1',
  wsUrl: 'wss://your-domain.example/ws'
});

await IMSDK.login({ userId: 'user_1001', code: 'token_from_your_backend' });
const message = IMSDK.createTextMessage('你好，蓝信 IM！');
await IMSDK.sendMessage('conv_01HXYZ', message);
</script>

身份认证

你的后端用 App Key、App Secret 和业务用户 ID 换取 Token，再把 Token 交给浏览器。浏览器 SDK 的 login 不发起登录请求，只在本地保存这个 Token，并连接实时服务。认证请求使用 X-Token。

开发者后端：换取 Token

复制POST /api/v1/im/auth/token HTTP/1.1
Content-Type: application/json

{"appKey":"app_xxx","appSecret":"仅保存在后端","userId":"user_1001"}

// data
{"token":"eyJ...","tokenType":"X-Token","expiresIn":7200,"userId":"user_1001"}

浏览器：使用已签发 Token

复制const session = await IMSDK.login({
  userId: 'user_1001',
  code: tokenFromYourBackend
});

// SDK 后续 HTTP 请求自动添加：
// X-Token: eyJ...
await IMSDK.logout(); // 仅清理本地 Token 并断开 WebSocket

REST endpoints

API 基地址为 /api/v1，IM 路由均以 /im 开头。分页接口接受 limit（最大 100），响应统一返回 {"code":0,"data":...}。

查看机器可读的完整 endpoint 清单 →

浏览器 SDK

IMSDK 是共享实例；如需在同一页面连接多个应用，可使用 new IMSDK.Client()。所有网络方法均返回 Promise。

复制const conversations = await IMSDK.conversation.list({ limit: 20 });
const friends = await IMSDK.friend.list();
await IMSDK.blacklist.add('spam_user', '广告骚扰');

const group = await IMSDK.group.create({
  name: '产品讨论组',
  memberIds: ['user_1002', 'user_1003']
});

const uploaded = await IMSDK.upload(file);
await IMSDK.sendMessage(group.conversationNo,
  IMSDK.createImageMessage(uploaded.url, { width: 1280, height: 720 })
);
await IMSDK.sendToUser('user_1002', IMSDK.createTextMessage('你好'));

自定义部署路径

后端路由尚未固定或经网关改写时，可只覆盖变化的路径：

复制IMSDK.init({
  appKey: 'app_xxxxxxxxx',
  apiBase: 'https://api.example.com/api/v1',
  routes: {
    messages: '/im/messages',
    messageHistory: '/im/messages/history/:conversationNo'
  }
});

消息

构造器创建 {type, content, clientMessageId} 消息对象，调用 sendMessage 后才会发送。唯一的 clientMessageId 用于服务端幂等去重。

复制IMSDK.createTextMessage('Hello');
IMSDK.createImageMessage(url, { width: 800, height: 600 });
IMSDK.createFileMessage(url, { name: 'brief.pdf', size: 20480 });
IMSDK.createAudioMessage(url, { duration: 12 });
IMSDK.createVideoMessage(url, { duration: 30, poster: coverUrl });
IMSDK.createLocationMessage(31.2304, 121.4737, { name: '上海' });
IMSDK.createCardMessage({ title: '订单', description: '#20260724' });
IMSDK.createCustomMessage('poll.created', { pollId: 'poll_01' });

复制const page = await IMSDK.getMessageHistory('conv_01HXYZ', {
  beforeSequence: 120,
  limit: 30
});
await IMSDK.markConversationRead('conv_01HXYZ', 'msg_01HXYZ');
await IMSDK.markMessageRead('msg_01HXYZ');
await IMSDK.revokeMessage('msg_01HXYZ');
await IMSDK.deleteMessage('msg_01HXYZ');

实时事件

SDK 使用 wsUrl?token=<X-Token> 在 HTTP Upgrade 时认证，不会在连接建立后发送 auth 消息。入站包使用 event 和 payload；SDK 发送 {"type":"ping"} 时服务端回复 {"event":"pong"}。

复制const onMessage = message => renderMessage(message);
IMSDK.on('message.created', onMessage);
IMSDK.on('connection.reconnecting', ({ attempt, delay }) => {
  console.log(`第 ${attempt} 次重连，${delay}ms 后执行`);
});

// 不再需要时
IMSDK.off('message.created', onMessage);

错误处理

失败请求抛出 IMSDK.IMError，包含 code、status、details 和 retryable。网络错误、429 与 5xx 标记为可重试。

复制try {
  await IMSDK.sendMessage(conversationId, message);
} catch (error) {
  if (error.status === 401) {
    requestNewTokenFromYourBackend();
  } else if (error.retryable) {
    queueForRetry(message);
  } else {
    showError(error.message);
  }
}

Webhooks

Webhook worker 将事件 JSON 原样 POST 到应用配置的地址。当前实现不生成签名；接收端应使用难以猜测的 HTTPS URL，并验证事件内容。

复制POST /your/webhook HTTP/1.1
X-IM-Event: message.created
X-IM-Event-Id: evt_01HXYZ
Content-Type: application/json

{"messageNo":"m_01HXYZ","conversationNo":"c_01HXYZ",...}

用量限制

API 按 IP 与路由以分钟窗口限流；超限返回 HTTP 429 和 Retry-After: 60。