跳到主要内容

发送频道消息

向频道发送消息。

接口说明​

属性值
请求方式POST
请求路径/im-user/api/v1/bot/channels/{channelId}/messages
鉴权方式Bot Token
说明

此接口用于 Bot 向指定频道发送消息。Bot 需要是该频道的成员才能发送消息。

请求头​

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

路径参数​

参数类型必填说明
channelIdnumber是频道 ID

请求参数​

参数类型必填说明
msgTextstring是消息文本内容（Query 参数）
payloadstring否扩展字段（JSON 格式，Query 参数）

请求示例​

基本请求​

curl -X POST 'https://api.im.example.com/im-user/api/v1/bot/channels/5001/messages?msgText=%E9%A1%B9%E7%9B%AE%E5%85%AC%E5%91%8A' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

带扩展字段​

curl -X POST 'https://api.im.example.com/im-user/api/v1/bot/channels/5001/messages?msgText=%E9%A1%B9%E7%9B%AE%E5%85%AC%E5%91%8A&payload=%7B%22type%22%3A%22announcement%22%7D' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

响应参数​

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

响应示例​

成功响应​

{
  "code": 200,
  "data": {
    "messageId": 123456790,
    "channelId": 5001,
    "roomId": 5001,
    "status": "sent"
  }
}

失败响应​

{
  "code": 404,
  "msg": "频道不存在"
}

错误码​

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

Java 调用示例​

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

import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

public class BotApiClient {
    
    private final String apiBaseUrl;
    private final String botToken;
    
    public BotApiClient(String apiBaseUrl, String botToken) {
        this.apiBaseUrl = apiBaseUrl;
        this.botToken = botToken;
    }
    
    /**
     * 发送消息到频道
     * 
     * @param channelId 频道 ID
     * @param msgText 消息文本
     * @return 消息响应
     */
    public BotMessageResponse sendChannelMessage(Long channelId, String msgText) {
        return sendChannelMessage(channelId, msgText, null);
    }
    
    /**
     * 发送消息到频道（带扩展字段）
     * 
     * @param channelId 频道 ID
     * @param msgText 消息文本
     * @param payload 扩展字段（JSON 格式）
     * @return 消息响应
     */
    public BotMessageResponse sendChannelMessage(Long channelId, String msgText, String payload) {
        StringBuilder url = new StringBuilder();
        url.append(apiBaseUrl)
           .append("/im-user/api/v1/bot/channels/")
           .append(channelId)
           .append("/messages?msgText=")
           .append(URLEncoder.encode(msgText, StandardCharsets.UTF_8));
        
        if (payload != null) {
            url.append("&payload=")
               .append(URLEncoder.encode(payload, StandardCharsets.UTF_8));
        }
        
        String response = HttpRequest.post(url.toString())
            .header("Authorization", "Bearer " + botToken)
            .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
from urllib.parse import urlencode

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_channel_message(
        self, 
        channel_id: int, 
        msg_text: str, 
        payload: dict = None
    ) -> dict:
        """发送消息到频道"""
        url = f"{self.api_base_url}/im-user/api/v1/bot/channels/{channel_id}/messages"
        
        headers = {
            "Authorization": f"Bearer {self.bot_token}"
        }
        
        params = {"msgText": msg_text}
        if payload:
            params["payload"] = json.dumps(payload)
        
        response = requests.post(url, params=params, headers=headers)
        result = response.json()
        
        if result.get("code") != 200:
            raise Exception(f"发送频道消息失败: {result.get('msg')}")
        
        return result.get("data")

使用场景​

项目公告​

// 发送项目公告
botApiClient.sendChannelMessage(
    projectChannelId,
    "📢 项目公告\n" +
    "────────────\n" +
    "本周五下午 14:00-16:00 进行系统升级\n" +
    "届时服务将暂停，请提前做好准备\n" +
    "────────────\n" +
    "如有疑问请联系运维团队"
);

每日报告​

// 发送每日数据报告
String payload = JSONUtil.toJsonStr(Map.of(
    "type", "daily_report",
    "date", "2026-01-09",
    "action", "view_dashboard"
));

botApiClient.sendChannelMessage(
    reportChannelId,
    "📊 每日数据报告\n" +
    "日期：2026-01-09\n" +
    "────────────\n" +
    "新增用户：128\n" +
    "活跃用户：1,256\n" +
    "订单数量：89\n" +
    "────────────\n" +
    "详情请查看数据看板",
    payload
);

构建通知​

// 发送构建通知
botApiClient.sendChannelMessage(
    devChannelId,
    "🔧 构建通知\n" +
    "────────────\n" +
    "项目：im-cloud\n" +
    "分支：main\n" +
    "状态：✅ 构建成功\n" +
    "版本：v1.2.3\n" +
    "────────────\n" +
    "提交者：张三"
);

下一步​