跳到主要内容

发送第一条消息

本文介绍如何通过 Bot API 发送第一条消息。

前提条件​

在发送消息之前，您需要：

  1. 已创建应用并获取 clientId 和 clientSecret
  2. 已将应用安装到目标工作空间，获取 botToken
  3. 知道目标用户的 userId
快速测试

如果您只是想快速测试 API，可以先手动完成安装流程获取 Bot Token。详细的安装流程请参考 应用安装。

步骤一：获取 Bot Token​

应用安装到工作空间后，会返回 Bot Token。如果您已经有 Bot Token，可以跳过此步骤。

安装确认接口： POST /im-user/api/v1/oauth/install/confirm

curl -X POST 'https://api.im.example.com/im-user/api/v1/oauth/install/confirm' \
  -H 'Content-Type: application/json' \
  -d '{
    "clientId": "550e8400-e29b-41d4-a716-446655440000",
    "workspaceId": 1001,
    "timestamp": 1704528000,
    "sign": "your_calculated_sign"
  }'

响应示例：

{
  "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"
  }
}

步骤二：发送消息​

使用 Bot Token 调用发送消息接口。

接口地址： POST /im-user/api/v1/bot/send-message

请求头：

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

请求参数：

参数类型必填说明
workspaceIdnumber是工作空间 ID
userIdnumber是目标用户 ID
textstring是消息文本内容
payloadstring否扩展字段（JSON 格式）

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;
import cn.hutool.json.JSONUtil;

public class BotMessageSender {
    
    private static final String API_BASE_URL = "https://api.im.example.com";
    private final String botToken;
    
    public BotMessageSender(String botToken) {
        this.botToken = botToken;
    }
    
    public void 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);
        
        String response = HttpRequest.post(API_BASE_URL + "/im-user/api/v1/bot/send-message")
            .header("Authorization", "Bearer " + botToken)
            .header("Content-Type", "application/json")
            .body(JSONUtil.toJsonStr(body))
            .execute()
            .body();
        
        System.out.println("发送结果: " + response);
    }
    
    public static void main(String[] args) {
        String botToken = "your_bot_token";
        BotMessageSender sender = new BotMessageSender(botToken);
        sender.sendMessage(1001L, 123L, "Hello, 这是来自开放平台的第一条消息！");
    }
}

响应示例​

成功响应：

{
  "code": 200,
  "data": {
    "messageId": "msg_abc123",
    "channelId": 10001,
    "roomId": 20001,
    "status": "sent"
  }
}

失败响应：

{
  "code": 401,
  "message": "Token 无效或已过期"
}

常见错误​

错误码说明解决方案
401Token 无效或已过期检查 Bot Token 是否正确，或重新获取
403权限不足检查应用是否已安装到目标工作空间
404用户不存在检查 userId 是否正确

🎉 恭喜​

您已成功发送第一条消息！接下来可以：