MessageApi

消息收发模块，支持私聊、群聊、合并转发、历史记录查询等。

方法

私聊

方法	返回类型	说明
sendPrivateMsg(userId: number, message: MessageSegment[])	Result<{ message_id: number }>	发送私聊消息

群聊

方法	返回类型	说明
sendGroupMsg(groupId: number, message: MessageSegment[])	Result<{ message_id: number }>	发送群聊消息
sendGroupForwardMsg(groupId: number, nodes: ForwardNode[])	Result<{ message_id: number }>	发送群合并转发消息

通用

方法	返回类型	说明
sendMsg(params: SendMsgParams)	Result<{ message_id: number }>	发送消息（通用，可指定 message_type）
deleteMsg(messageId: number)	Result<void>	撤回消息
getMsg(messageId: number)	Result<MessageDetail>	获取消息详情
getForwardMsg(id: string)	Result<ForwardMessage>	获取合并转发消息
sendForwardMsg(nodes: ForwardNode[])	Result<{ message_id: number }>	发送合并转发（通用）
sendPrivateForwardMsg(userId: number, nodes: ForwardNode[])	Result<{ message_id: number }>	发送私聊合并转发消息

消息管理

方法	返回类型	说明
markMsgAsRead(messageId: number)	Result<void>	标记消息已读
markGroupMsgAsRead(groupId: number, userId?: number, messageId?: string)	Result<void>	标记群聊消息已读

互动

方法	返回类型	说明
sendPoke(userId: number, groupId?: number, targetId?: number)	Result<void>	发送戳一戳（私聊或群聊）
clickInlineKeyboardButton(params: InlineKeyboardClick)	Result<void>	点击内联键盘按钮

历史消息

方法	返回类型	说明
getGroupMsgHistory(groupId: number, messageSeq?: number, count?: number, reverseOrder?: boolean, disableGetUrl?: boolean, parseMultMsg?: boolean, quickReply?: boolean)	Result<MessageDetail[]>	获取群聊历史消息
getFriendMsgHistory(userId: number, messageSeq?: number, count?: number, reverseOrder?: boolean, disableGetUrl?: boolean, parseMultMsg?: boolean, quickReply?: boolean)	Result<MessageDetail[]>	获取私聊历史消息
getRecentContact(count?: number)	Result<RecentContact[]>	获取最近聊天记录

返回数据结构

SendMsgParams

interface SendMsgParams {
  message_type?: 'private' | 'group'
  user_id?: number
  group_id?: number
  message: MessageSegment[]
  auto_escape?: boolean
}

MessageDetail

interface MessageDetail {
  message_id: number
  real_id?: number
  sender: Sender
  time: number
  message_type: string
  message: MessageSegment[]
  raw_message: string
  group_id?: number
  [key: string]: unknown
}

ForwardMessage

interface ForwardMessage {
  id: string
  content?: unknown[]
  [key: string]: unknown
}

ForwardNode

interface ForwardNode {
  type: 'node'
  data: {
    id?: number
    content?: MessageSegment[]
    user_id?: number
    nickname?: string
  }
}

RecentContact

interface RecentContact {
  user_id: number
  group_id?: number
  last_time: number
  message_type: string
  [key: string]: unknown
}

InlineKeyboardClick

interface InlineKeyboardClick {
  group_id: number
  bot_appid: string
  button_id: string
  callback_data: string
  msg_seq: string
}

Sender

interface Sender {
  user_id?: number | null
  nickname?: string | null
  sex?: string | null
  age?: number | null
  card?: string | null
  role?: string | null
  title?: string | null
  level?: string | null
  area?: string | null
  group_id?: number | null
  [key: string]: unknown
}

示例

import { MessageApi, Seg } from '@aemeath-projects/napcat'

const msg = new MessageApi(client)

// 发送群消息
const result = await msg.sendGroupMsg(123456789, [
  Seg.text('Hello, everyone!'),
])
if (result.ok) {
  console.log('发送成功，message_id:', result.data.message_id)
} else {
  console.error('发送失败:', result.error.code, result.error.message)
}

// 获取消息详情
const detail = await msg.getMsg(12345)
if (detail.ok) {
  console.log('发送者:', detail.data.sender.nickname)
  console.log('内容:', detail.data.raw_message)
}

// 获取群聊历史消息
const history = await msg.getGroupMsgHistory(123456789, undefined, 20)
if (history.ok) {
  history.data.forEach((m) => console.log(m.message_id, m.sender.nickname))
}

// 获取最近聊天记录
const recent = await msg.getRecentContact(10)
if (recent.ok) {
  recent.data.forEach((c) => console.log(c.user_id, c.last_time))
}