GoQQBot

切换主题

单聊富媒体上传 ​

在单聊里回复图片，可以先用 ctx.UploadMedia 上传，再把上传结果交给 ctx.Reply。SDK 会从收到的事件里找到用户和会话。下面的例子由业务传入图片 URL。

go
package guide

import (
	"context"
	"time"

	"github.com/ProgramCX/GoQQBot/pkg/message"
	"github.com/ProgramCX/GoQQBot/shared/types"
)

func replyImageURL(ctx *types.Context, imageURL string) error {
	op, cancel := context.WithTimeout(ctx.RequestContext(), 30*time.Second)
	defer cancel()
	uploaded, err := ctx.UploadMedia(op, message.RichMediaRequest{
		FileType: message.FileTypeImage,
		URL:      imageURL,
	})
	if err != nil {
		return err
	}
	return ctx.ReplyContext(op, message.Media(uploaded.FileInfo))
}

在 C2C_MESSAGE_CREATE 的处理函数里调用示例。URL 可来自业务配置或自有存储。同一个函数也适用于群聊。上传与发送都使用当前会话。

参数与协议 ​

单聊上传使用 POST /v2/users/{user_openid}/files。

字段说明
FileType图片、视频、语音或文件，使用对应 FileType 常量
URL平台下载的 HTTP(S) 地址。从 URL、UploadID、FileData 中三选一。
SrvSendMsg默认为 false。设为 true 请求直接发送主动消息（proactive message）。
FileName用 UploadID 或 FileData 时填写。URL 模式无需自行推断远端文件名。

本地图片使用分片上传。

脱离消息处理器调用 ​

在后台服务里，也可以用 API 客户端上传。指定会话目标就行，无需把路由器或 SDK 的 Context 传给服务。何时发送由业务决定。

go
package guide

import (
	"context"

	"github.com/ProgramCX/GoQQBot/pkg/api"
	"github.com/ProgramCX/GoQQBot/pkg/message"
)

func uploadUserVideo(op context.Context, client *api.Client, userOpenID, videoURL string) (*message.RichMediaResponse, error) {
	return client.UploadMedia(op, message.Target{
		Scene: message.SceneC2C,
		ID:    userOpenID,
	}, message.RichMediaRequest{
		FileType: message.FileTypeVideo,
		URL:      videoURL,
	})
}

示例函数只上传文件。回复时，发送方要另外提供实际收到的事件作为回复来源。发送单聊消息时，可用 Client.SendReply 配合真实事件来源。具备平台资格时也可用 Client.SendMessage。

错误与重试 ​

用 errors.Is(err, api.ErrInvalidMedia) 判断输入是否合法。平台错误保留为 *api.APIError。用 errors.As 读取 HTTP 状态、错误码和 trace。DiagnosticMessage() 可读取平台提供的说明。

注意事项 ​

  • 将未经验证的地址交给平台，会触发对用户指定地址的下载。
  • SDK 只检查 URL 格式。QQ 需要能访问并下载这个地址。如果下载超时，或文件格式、审核不符合要求，平台可能拒绝请求。
  • 本机路径无法作为公网 URL 上传。URL 上传失败后，SDK 不会自动下载文件或改走本地上传。
  • 如果上传返回了结果但 err 也有值，HTTP 请求可能已经成功，只是 SDK 没能读出响应。再次提交前先核对平台是否已创建任务或发送主动消息。直接重发可能产生重复。SDK 不自动重试 POST。

另请参阅 ​

富媒体概述 · 本地分片上传 · QQ 官方：单聊富媒体上传