Bot Token

Bot Token 是应用安装到工作空间后获得的令牌，用于调用 Bot API。

获取方式

Bot Token 在应用安装到工作空间时获取，通过确认安装接口返回。

确认安装接口

接口地址： POST /im-user/api/v1/oauth/install/confirm

请求参数：

{
  "clientId": "550e8400-e29b-41d4-a716-446655440000",
  "workspaceId": 1001,
  "externalTenantId": "1",
  "installerUserId": 456,
  "timestamp": 1704528000,
  "sign": "a1b2c3d4..."
}

响应参数：

{
  "code": 200,
  "data": {
    "botToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "bot",
    "botUserId": 456,
    "botName": "OA办公系统",
    "workspaceId": 1001,
    "workspaceName": "测试工作空间",
    "installationId": 789,
    "expiresIn": 31536000,
    "scope": "bot:message:send,bot:user:read"
  }
}

Token 属性

属性	说明
botToken	Bot Token 值
tokenType	Token 类型，固定为 "bot"
expiresIn	有效期（秒），默认 1 年
scope	权限范围

使用方式

在调用 Bot API 时，需要在请求头中携带 Bot Token：

Authorization: Bearer {botToken}

curl 示例

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": "Hello!"
  }'

Java 示例

import cn.hutool.http.HttpRequest;

public class BotApiClient {
    
    private final String botToken;
    private final String apiBaseUrl;
    
    public BotApiClient(String botToken, String apiBaseUrl) {
        this.botToken = botToken;
        this.apiBaseUrl = apiBaseUrl;
    }
    
    public String sendMessage(Long workspaceId, Long userId, String text) {
        Map<String, Object> body = new HashMap<>();
        body.put("workspaceId", workspaceId);
        body.put("userId", userId);
        body.put("text", text);
        
        return HttpRequest.post(apiBaseUrl + "/im-user/api/v1/bot/send-message")
            .header("Authorization", "Bearer " + botToken)
            .header("Content-Type", "application/json")
            .body(JSONUtil.toJsonStr(body))
            .execute()
            .body();
    }
}

适用 API

Bot Token 可用于以下 API：

API	说明
POST /im-user/api/v1/bot/send-message	发送消息给用户
POST /im-user/api/v1/bot/send-channel-message	发送消息到频道
POST /im-user/api/v1/oauth/ticket/verify	验证 Login Ticket

有效期

• 默认有效期：1 年（31536000 秒）
• 过期处理：Token 过期后需要重新安装应用获取新 Token

检查 Token 是否过期

public boolean isTokenExpired(LocalDateTime expiresAt) {
    return expiresAt.isBefore(LocalDateTime.now());
}

Token 过期处理

public String getBotToken(Long tenantId) {
    WorkspaceBinding binding = bindingMapper.selectByTenantId(tenantId);
    
    if (binding == null) {
        throw new ServiceException("租户未绑定工作空间");
    }
    
    if (binding.getBotTokenExpiresAt().isBefore(LocalDateTime.now())) {
        throw new ServiceException("Bot Token 已过期，请重新安装应用");
    }
    
    return binding.getBotToken();
}

存储建议

Bot Token 应安全存储在数据库中：

CREATE TABLE workspace_bindings (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    oa_tenant_id BIGINT NOT NULL,
    im_workspace_id BIGINT NOT NULL,
    bot_token VARCHAR(1024) COMMENT 'Bot Token',
    bot_token_expires_at DATETIME COMMENT 'Token过期时间',
    -- 其他字段...
);

安全建议

重要

• Bot Token 应存储在服务端，禁止暴露在前端
• 不要将 Bot Token 提交到代码仓库
• 建议使用环境变量或配置中心管理
• 定期检查 Token 是否即将过期

错误处理

错误码	说明	解决方案
401	Token 无效或已过期	检查 Token 是否正确，或重新安装应用
403	权限不足	检查 Token 的 scope 是否包含所需权限

下一步

• SSO 集成 - 使用 Bot Token 验证 Login Ticket
• 发送消息 - 使用 Bot Token 发送消息