Documentation
¶
Overview ¶
Package qbot 提供 QQ 机器人单聊和群聊的 Access Token 管理、文本发送与 Webhook 接收能力。
SDK 不启动 HTTP 服务,不持久化凭证、事件或消息序号。 调用方负责开放平台配置、HTTP 服务生命周期、消息去重及被动回复序号。 频道、WebSocket、媒体上传下载和富媒体消息发送不在当前支持范围内。
Index ¶
- Variables
- type APIError
- type AccessTokenResponse
- type Client
- func (c *Client) GetAccessToken(ctx context.Context) (*AccessTokenResponse, error)
- func (c *Client) SendGroupText(ctx context.Context, request SendGroupTextRequest) (*SendTextResponse, error)
- func (c *Client) SendText(ctx context.Context, request SendTextRequest) (*SendTextResponse, error)
- func (c *Client) WebhookHandler(handler func(context.Context, Message) error) (http.Handler, error)
- type EventType
- type Message
- type MessageAttachment
- type MessageExtInfo
- type Option
- type SendGroupTextRequest
- type SendTextRequest
- type SendTextResponse
- type User
Constants ¶
This section is empty.
Variables ¶
var ( ErrAppIDRequired = errx.New("app id is required") ErrAppSecretRequired = errx.New("app secret is required") ErrUserIDRequired = errx.New("user openid is required") ErrGroupIDRequired = errx.New("group openid is required") ErrInvalidTarget = errx.New("invalid message target") ErrTextRequired = errx.New("text is required") ErrInvalidReply = errx.New("message id and event id are mutually exclusive") ErrMessageHandlerRequired = errx.New("message handler is required") ErrInvalidURL = errx.New("invalid api url") ErrRequest = errx.New("qq request failed") ErrHTTPStatus = errx.New("unexpected http status") ErrProtocol = errx.New("qq protocol error") ErrRateLimited = errx.New("qq rate limit exceeded") ErrInvalidSignature = errx.New("invalid webhook signature") )
Functions ¶
This section is empty.
Types ¶
type AccessTokenResponse ¶
type AccessTokenResponse struct {
AccessToken string `json:"access_token"`
ExpiresIn int64 `json:"expires_in"`
ExpiresAt time.Time `json:"-"`
}
AccessTokenResponse 返回凭证及其有效期;静态 Token 的有效期字段为零。 ExpiresIn 是服务端返回的原始有效秒数,读取缓存时应以 ExpiresAt 判断实际到期时间。
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client 提供 QQ 单聊和群聊的鉴权、文本发送及 Webhook 接收能力,不应在创建后复制。
func (*Client) GetAccessToken ¶
func (c *Client) GetAccessToken(ctx context.Context) (*AccessTokenResponse, error)
GetAccessToken 返回静态 Token 或缓存凭证,临近过期时按需刷新,不启动后台协程。 并发调用共享成功的刷新结果;返回值是副本,调用方不能修改内部缓存。
func (*Client) SendGroupText ¶
func (c *Client) SendGroupText(ctx context.Context, request SendGroupTextRequest) (*SendTextResponse, error)
SendGroupText 向指定群主动发送或被动回复文本;多次回复同一消息时由调用方递增序号。
func (*Client) SendText ¶
func (c *Client) SendText(ctx context.Context, request SendTextRequest) (*SendTextResponse, error)
SendText 向指定用户主动发送或被动回复文本;MessageSequence 为零时使用协议默认值 1。
type Message ¶
type Message struct {
ID string `json:"id"`
Content string `json:"content"`
Timestamp string `json:"timestamp"`
Author User `json:"author"`
GroupID string `json:"group_openid,omitempty"`
Type int `json:"message_type,omitempty"`
Attachments []MessageAttachment `json:"attachments,omitempty"`
EventID string `json:"-"`
EventType EventType `json:"-"`
Sequence uint64 `json:"-"`
}
Message 保留事件内的消息及外层事件标识;ID 与 EventID 分别用于消息回复和事件回复。
type MessageAttachment ¶
type MessageAttachment struct {
URL string `json:"url,omitempty"`
Filename string `json:"filename,omitempty"`
ContentType string `json:"content_type,omitempty"`
Size int64 `json:"size,omitempty"`
Width int `json:"width,omitempty"`
Height int `json:"height,omitempty"`
}
MessageAttachment 只保留附件元数据,SDK 不下载媒体或发送富媒体消息。
type MessageExtInfo ¶
type MessageExtInfo struct {
ReferenceIndex string `json:"ref_idx,omitempty"`
}
MessageExtInfo 保存服务端返回的消息引用索引。
type Option ¶
type Option func(*Client)
func WithAppSecret ¶
WithAppSecret 配置用于获取 Access Token 和 Webhook 验签的机器人密钥。
func WithBaseURL ¶
WithBaseURL 覆盖消息 API 地址;不改变获取 Token 的固定入口。
func WithClient ¶
WithClient 注入自定义 restx 客户端,用于调整传输配置或本地测试。
func WithInsecureHTTP ¶
func WithInsecureHTTP() Option
WithInsecureHTTP 允许明文消息 API 地址,仅用于可信的开发或测试环境。
func WithTimeout ¶
WithTimeout 配置一次公开 API 调用的总超时,包括等待和获取 Token 的时间。
type SendGroupTextRequest ¶
type SendGroupTextRequest struct {
GroupID string
Text string
MessageID string
EventID string
MessageSequence uint32
}
SendGroupTextRequest 配置群聊文本发送;GroupID 使用入站消息的 group_openid。
type SendTextRequest ¶
type SendTextRequest struct {
ToUserID string
Text string
MessageID string
EventID string
MessageSequence uint32
}
SendTextRequest 配置单聊文本发送;ToUserID 使用入站消息的 author.user_openid。
type SendTextResponse ¶
type SendTextResponse struct {
MessageID string `json:"id"`
Timestamp string `json:"timestamp"`
ExtInfo MessageExtInfo `json:"ext_info,omitempty"`
TraceID string `json:"-"`
}
SendTextResponse 返回服务端消息 ID、发送时间、引用信息及 HTTP 追踪 ID。
type User ¶
type User struct {
ID string `json:"id,omitempty"`
Username string `json:"username,omitempty"`
Bot bool `json:"bot,omitempty"`
UserOpenID string `json:"user_openid,omitempty"`
MemberOpenID string `json:"member_openid,omitempty"`
MemberRole string `json:"member_role,omitempty"`
}
User 的不同 OpenID 只适用于对应场景和当前 AppID,不能跨场景或跨机器人互换。