API 概述

书谱 IM 开放平台提供 RESTful 风格的 HTTP API，支持第三方应用接入 IM 系统，实现应用安装、用户免登、消息推送等功能。

基础信息

属性	值
基础 URL	https://api.im.example.com
API 前缀	/im-user/api/v1
协议	HTTPS
数据格式	JSON
字符编码	UTF-8

提示

实际部署时，请将 api.im.example.com 替换为您的 IM 服务域名。

API 分类

分类	说明	鉴权方式	调用方
安装 API	应用安装相关接口	签名验证	第三方应用后端
鉴权 API	Login Ticket 相关接口	Bot Token / User Token	IM 系统 / 第三方应用后端
Bot API	消息发送相关接口	Bot Token	第三方应用后端

请求格式

请求头

Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

请求体

所有 POST 请求使用 JSON 格式：

{
  "param1": "value1",
  "param2": "value2"
}

请求示例

curl -X POST 'https://api.im.example.com/im-user/api/v1/bot/send-message' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  -H 'Content-Type: application/json' \
  -d '{
    "workspaceId": 1001,
    "userId": 123,
    "text": "您有一条新的消息"
  }'

响应格式

所有 API 响应遵循统一格式：

成功响应

{
  "code": 200,
  "data": {
    "field1": "value1",
    "field2": "value2"
  }
}

失败响应

{
  "code": 400,
  "msg": "错误描述"
}

字段	类型	说明
code	number	状态码，200 表示成功
msg	string	错误描述（失败时返回）
data	object	业务数据（成功时返回）

通用错误码

错误码	说明	常见原因
200	成功	-
400	请求参数错误	参数缺失、格式错误、签名验证失败
401	Token 无效或已过期	Token 过期、Token 格式错误、未提供 Token
403	权限不足	应用未安装到目标工作空间、无权访问目标资源
404	资源不存在	用户不存在、频道不存在、应用不存在
500	服务器内部错误	服务异常，请联系管理员

业务错误码

错误码	说明	解决方案
400	无效的 Client ID	检查 clientId 是否正确
400	签名已过期	签名有效期为 10 分钟，请重新发起安装
400	签名验证失败	检查签名计算是否正确，确保 clientSecret 正确
400	Login Ticket 无效或已过期	Ticket 已使用或超过 5 分钟，请重新从 IM 打开应用
401	需要使用 Bot Token 调用此接口	确保使用 Bot Token 而非 User Token

API 列表

安装 API

接口	方法	路径	说明
发起安装	POST	/im-user/api/v1/apps/install/initiate	发起应用安装（IM 内部调用）
确认安装	POST	/im-user/api/v1/oauth/install/confirm	确认应用安装，获取 Bot Token

鉴权 API

接口	方法	路径	说明
生成 Ticket	POST	/im-user/api/v1/oauth/ticket	生成 Login Ticket（IM 内部调用）
验证 Ticket	POST	/im-user/api/v1/oauth/ticket/verify	验证 Login Ticket，获取用户信息

Bot API

接口	方法	路径	说明
发送消息	POST	/im-user/api/v1/bot/send-message	向用户发送私聊消息
发送频道消息	POST	/im-user/api/v1/bot/channels/{channelId}/messages	向频道发送消息

鉴权方式

Bot Token

用于调用 Bot API 和验证 Ticket，代表应用身份：

Authorization: Bearer {botToken}

获取方式：应用安装到工作空间时，通过 确认安装接口 返回。

有效期：默认 1 年（31536000 秒），过期后需重新安装应用。

使用场景：

• 调用 Bot API 发送消息
• 验证 Login Ticket 获取用户信息

User Token

用于生成 Login Ticket，代表用户身份：

Authorization: Bearer {userAccessToken}

获取方式：用户登录 IM 客户端后获取（IM 内部使用）。

使用场景：

• 生成 Login Ticket（IM 系统内部调用）

签名验证

用于确认安装接口，验证请求的合法性：

sign = SHA256(clientId + timestamp + clientSecret)

安全特性：

• 不传输 clientSecret，只传输签名
• 时间戳防重放攻击（10 分钟有效期，允许 1 分钟时钟偏差）

详细说明请参考 签名机制。

调用流程

下一步

• 安装 API - 应用安装相关接口
• 鉴权 API - Login Ticket 相关接口
• Bot API - 消息发送相关接口