跳到主要内容

发送消息

向用户发送私聊消息。

接口说明​

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

此接口用于 Bot 向指定用户发送私聊消息。系统会自动创建或复用 Bot 与用户之间的私聊频道。

请求头​

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

请求参数​

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

请求示例​

基本请求​

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": "您有一条新的审批待处理"
  }'

带扩展字段​

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\":\"view\"}"
  }'

响应参数​

参数类型说明
messageIdnumber消息 ID
channelIdnumber频道 ID（Bot 与用户的私聊频道）
roomIdnumber房间 ID（与 channelId 相同）
statusstring状态：sent（发送成功）/ failed（发送失败）
errorMessagestring错误信息（失败时返回）

响应示例​

成功响应​

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

失败响应​

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

错误码​

错误码说明解决方案
400workspaceId不能为空确保传递了 workspaceId 参数
400userId不能为空确保传递了 userId 参数
400text不能为空确保传递了 text 参数
401需要 Bot Token确保在请求头中传递了 Authorization
401Bot Token 无效或已过期检查 Bot Token 是否正确，或重新安装应用
403权限不足检查应用是否已安装到目标工作空间
404用户不存在检查 userId 是否正确
500发送消息失败服务异常，请联系管理员

Java 调用示例​

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

import java.util.HashMap;
import java.util.Map;

public class BotApiClient {
    
    private final String apiBaseUrl;
    private final String botToken;
    
    public BotApiClient(String apiBaseUrl, String botToken) {
        this.apiBaseUrl = apiBaseUrl;
        this.botToken = botToken;
    }
    
    /**
     * 发送消息给用户
     * 
     * @param workspaceId 工作空间 ID
     * @param userId 目标用户 ID
     * @param text 消息文本
     * @return 消息响应
     */
    public BotMessageResponse sendMessage(Long workspaceId, Long userId, String text) {
        return sendMessage(workspaceId, userId, text, null);
    }
    
    /**
     * 发送消息给用户（带扩展字段）
     * 
     * @param workspaceId 工作空间 ID
     * @param userId 目标用户 ID
     * @param text 消息文本
     * @param payload 扩展字段（JSON 格式）
     * @return 消息响应
     */
    public BotMessageResponse sendMessage(Long workspaceId, Long userId, 
                                          String text, String payload) {
        Map<String, Object> body = new HashMap<>();
        body.put("workspaceId", workspaceId);
        body.put("userId", userId);
        body.put("text", text);
        if (payload != null) {
            body.put("payload", 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 RuntimeException("发送消息失败: " + json.getStr("msg"));
        }
        
        return json.getBean("data", BotMessageResponse.class);
    }
}

Python 调用示例​

import requests
import json

class BotApiClient:
    def __init__(self, api_base_url: str, bot_token: str):
        self.api_base_url = api_base_url
        self.bot_token = bot_token
    
    def send_message(
        self, 
        workspace_id: int, 
        user_id: int, 
        text: str, 
        payload: dict = None
    ) -> dict:
        """发送消息给用户"""
        url = f"{self.api_base_url}/im-user/api/v1/bot/send-message"
        
        headers = {
            "Authorization": f"Bearer {self.bot_token}",
            "Content-Type": "application/json"
        }
        
        data = {
            "workspaceId": workspace_id,
            "userId": user_id,
            "text": text
        }
        
        if payload:
            data["payload"] = json.dumps(payload)
        
        response = requests.post(url, json=data, headers=headers)
        result = response.json()
        
        if result.get("code") != 200:
            raise Exception(f"发送消息失败: {result.get('msg')}")
        
        return result.get("data")

使用场景​

审批通知​

// 发送审批通知
String payload = JSONUtil.toJsonStr(Map.of(
    "type", "approval",
    "approvalId", 12345,
    "action", "view"
));

botApiClient.sendMessage(
    workspaceId,
    userId,
    "📋 审批通知\n" +
    "────────────\n" +
    "您有一条新的请假审批待处理\n" +
    "申请人：张三\n" +
    "请假类型：年假\n" +
    "请假时间：2026-01-10 ~ 2026-01-12\n" +
    "────────────\n" +
    "点击查看详情",
    payload
);

任务提醒​

// 发送任务提醒
botApiClient.sendMessage(
    workspaceId,
    userId,
    "⏰ 任务提醒\n" +
    "────────────\n" +
    "任务「完成项目文档」即将到期\n" +
    "截止时间：2026-01-10 18:00\n" +
    "────────────\n" +
    "请及时处理"
);

下一步​