发送消息

通过 Bot API，您可以向用户发送消息通知。

接口说明

属性	值
请求方式	POST
请求路径	/im-user/api/v1/bot/send-message
鉴权方式	Bot Token

请求参数

参数	类型	必填	说明
workspaceId	number	是	工作空间 ID
userId	number	是	目标用户 ID
text	string	是	消息文本内容
payload	string	否	扩展字段（JSON 格式）

请求头

Authorization: Bearer {botToken}
Content-Type: application/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": "您有一条新的审批待处理"
  }'

Java 示例

import cn.hutool.http.HttpRequest;
import cn.hutool.json.JSONUtil;

public class BotMessageSender {
    
    private final String apiBaseUrl;
    private final String botToken;
    
    public BotMessageSender(String apiBaseUrl, String botToken) {
        this.apiBaseUrl = apiBaseUrl;
        this.botToken = botToken;
    }
    
    /**
     * 发送文本消息
     */
    public BotMessageResponse 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(apiBaseUrl + "/im-user/api/v1/bot/send-message")
            .header("Authorization", "Bearer " + botToken)
            .header("Content-Type", "application/json")
            .body(JSONUtil.toJsonStr(body))
            .execute()
            .body();
        
        JSONObject json = JSONUtil.parseObj(response);
        if (json.getInt("code") != 200) {
            throw new ServiceException(json.getStr("message"));
        }
        
        return json.getBean("data", BotMessageResponse.class);
    }
    
    /**
     * 发送带扩展字段的消息
     */
    public BotMessageResponse sendMessageWithPayload(Long workspaceId, Long userId, 
                                                      String text, Map<String, Object> payload) {
        Map<String, Object> body = new HashMap<>();
        body.put("workspaceId", workspaceId);
        body.put("userId", userId);
        body.put("text", text);
        body.put("payload", JSONUtil.toJsonStr(payload));
        
        String response = 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();
        
        JSONObject json = JSONUtil.parseObj(response);
        if (json.getInt("code") != 200) {
            throw new ServiceException(json.getStr("message"));
        }
        
        return json.getBean("data", BotMessageResponse.class);
    }
}

带扩展字段的请求

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": "您有一条新的请假审批待处理",
    "payload": "{\"type\":\"leave_approval\",\"leaveId\":456,\"action\":\"approve\"}"
  }'

响应参数

参数	类型	说明
messageId	string	消息 ID
channelId	number	频道 ID
roomId	number	房间 ID
status	string	状态：sent/failed
errorMessage	string	错误信息（失败时返回）

响应示例

成功响应

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

失败响应

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

业务场景示例

审批通知

// 发送审批通知
botMessageSender.sendMessage(
    workspaceId,
    userId,
    "您有一条新的请假审批待处理\n" +
    "申请人：张三\n" +
    "请假类型：事假\n" +
    "请假时间：2026-01-06 至 2026-01-08"
);

工单告警

// 发送工单告警
botMessageSender.sendMessage(
    workspaceId,
    userId,
    "⚠️ 生产异常告警\n" +
    "设备：CNC-001\n" +
    "异常类型：温度过高\n" +
    "当前温度：85°C\n" +
    "请及时处理！"
);

任务提醒

// 发送任务提醒
Map<String, Object> payload = new HashMap<>();
payload.put("type", "task_reminder");
payload.put("taskId", 789);
payload.put("action", "view");

botMessageSender.sendMessageWithPayload(
    workspaceId,
    userId,
    "📋 任务提醒\n" +
    "任务：完成季度报告\n" +
    "截止时间：2026-01-10 18:00\n" +
    "剩余时间：2天",
    payload
);

错误码

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

注意事项

提示

• Bot Token 需要在请求头中携带
• workspaceId 必须是应用已安装的工作空间
• userId 必须是该工作空间的成员

下一步

• 消息类型 - 了解支持的消息类型
• 发送频道消息 API - 向频道发送消息的 API 文档