发起安装

发起应用安装，生成签名并跳转到第三方应用。

接口说明

属性	值
请求方式	POST
请求路径	/im-user/api/v1/apps/install/initiate
鉴权方式	User Token

说明

此接口由 IM 系统内部调用，第三方应用无需直接调用。当用户在 IM 中点击"安装应用"时，IM 会自动调用此接口并跳转到第三方应用的 installRedirectUri。

请求头

Authorization: Bearer {userAccessToken}
Content-Type: application/json

请求参数

参数	类型	必填	说明
appId	number	是	应用 ID
workspaceId	number	是	工作空间 ID
state	string	是	状态参数（防 CSRF，随机字符串）

请求示例

{
  "appId": 123,
  "workspaceId": 1001,
  "state": "random_state_string"
}

响应参数

参数	类型	说明
redirectUrl	string	跳转 URL（第三方应用的绑定页面）
appId	number	应用 ID
appName	string	应用名称
workspaceId	number	工作空间 ID
workspaceName	string	工作空间名称
state	string	状态参数
tokenExpiresIn	number	令牌有效期（秒），默认 31536000（1年）
signTimestamp	number	签名时间戳（秒级）
sign	string	签名值，用于第三方应用验证请求合法性

响应示例

{
  "code": 200,
  "data": {
    "redirectUrl": "https://your-app.com/api/im/install/callback?workspace_id=1001&workspace_name=%E6%B5%8B%E8%AF%95%E5%B7%A5%E4%BD%9C%E7%A9%BA%E9%97%B4&app_id=123&initiator_user_id=456&timestamp=1736380800&sign=a1b2c3d4...",
    "appId": 123,
    "appName": "OA办公系统",
    "workspaceId": 1001,
    "workspaceName": "测试工作空间",
    "state": "random_state_string",
    "tokenExpiresIn": 31536000,
    "signTimestamp": 1736380800,
    "sign": "a1b2c3d4e5f6789..."
  }
}

跳转参数

IM 跳转到 installRedirectUri 时，会携带以下 URL 参数：

参数	类型	说明
workspace_id	number	IM 工作空间 ID
workspace_name	string	IM 工作空间名称（URL 编码）
app_id	number	应用 ID
initiator_user_id	number	发起安装的 IM 用户 ID
timestamp	number	签名时间戳（秒级，10位数字）
sign	string	签名值（64位小写十六进制字符串）

跳转 URL 示例

https://your-app.com/api/im/install/callback
  ?workspace_id=1001
  &workspace_name=%E6%B5%8B%E8%AF%95%E5%B7%A5%E4%BD%9C%E7%A9%BA%E9%97%B4
  &app_id=123
  &initiator_user_id=456
  &timestamp=1736380800
  &sign=3f8c2a1b4d5e6f7890abcdef1234567890abcdef1234567890abcdef12345678

建议

建议将 installRedirectUri 配置为后端接口地址，而非前端页面。后端可以安全地保存签名信息到 Session，并根据业务逻辑决定重定向到哪个前端页面。

错误码

错误码	说明	解决方案
400	appId不能为空	确保传递了 appId 参数
400	workspaceId不能为空	确保传递了 workspaceId 参数
400	state不能为空	确保传递了 state 参数
400	应用不存在	检查 appId 是否正确
400	工作空间不存在	检查 workspaceId 是否正确
400	应用未配置回调地址	在开发者中心配置 installRedirectUri
401	Token 无效或已过期	用户需要重新登录 IM

下一步

• 确认安装 - 确认应用安装接口
• 签名机制 - 了解签名算法