wechatbot

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 23, 2026 License: MIT Imports: 19 Imported by: 0

README

wechatbot-go

微信 iLink Bot SDK for Go —— 仅维护 Go 版本。

本项目 fork 自 corespeed-io/wechatbot， 仅保留并维护其中的 Go SDK 版本。原仓库还包含 Node.js、Python、Rust 等实现， 如果你需要其他语言版本，请访问原仓库。

核心协议与原始代码保持一致，后续会针对 Go SDK 持续做特性补全和稳定性改进。

安装

go get github.com/Icatme/wechatbot-go

要求 Go 1.22+，零 CGO 依赖。

快速开始

package main

import (
    "context"
    "fmt"
    "os"
    "os/signal"
    "syscall"

    "github.com/Icatme/wechatbot-go"
)

func main() {
    ctx, cancel := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
    defer cancel()

    bot := wechatbot.New(wechatbot.Options{
        OnQRURL: func(url string) { fmt.Println("请扫码:", url) },
    })

    if _, err := bot.Login(ctx, false); err != nil {
        fmt.Fprintln(os.Stderr, "登录失败:", err)
        os.Exit(1)
    }

    bot.OnMessage(func(msg *wechatbot.IncomingMessage) {
        _ = bot.Reply(ctx, msg, fmt.Sprintf("Echo: %s", msg.Text))
    })

    _ = bot.Run(ctx)
}

更多示例见 examples/。

功能特性

  • 扫码登录 + 凭证持久化
  • 长轮询接收消息
  • 文本 / 图片 / 文件 / 视频 / 语音 收发
  • CDN 上传下载与 AES-128-ECB 解密
  • context_token 自动管理
  • 输入状态指示器
  • 会话过期（-14）自动恢复

文档

与原仓库的关系

  • 原仓库：github.com/corespeed-io/wechatbot（多语言）
  • 本仓库：github.com/Icatme/wechatbot-go（仅 Go）
  • 许可证：MIT（保留原项目版权声明）

贡献

由于这是独立维护的 Go-only fork，Issues 和 PR 请提交到本仓库。

License

MIT

Documentation

Overview

Package wechatbot provides a WeChat iLink Bot SDK for Go.

It handles QR login, long-poll message receiving, text/media sending, typing indicators, context_token management, and AES-128-ECB CDN crypto.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BaseInfo 

type BaseInfo struct {
	ChannelVersion string `json:"channel_version"`
}

BaseInfo is included in every POST request body.

type Bot 

type Bot struct {
	// contains filtered or unexported fields
}

Bot is the main WeChat bot client.

func New 

func New(opts ...Options) *Bot

New creates a new Bot instance.

func (*Bot) Download 

func (b *Bot) Download(ctx context.Context, msg *IncomingMessage) (*DownloadedMedia, error)

Download downloads media from an incoming message. Returns nil if the message has no media. Priority: image > file > video > voice.

func (*Bot) DownloadRaw 

func (b *Bot) DownloadRaw(ctx context.Context, media *CDNMedia, aeskeyOverride string) ([]byte, error)

DownloadRaw downloads and decrypts a raw CDN media reference.

func (*Bot) Login 

func (b *Bot) Login(ctx context.Context, force bool) (*Credentials, error)

Login performs QR code login or loads stored credentials.

func (*Bot) OnMessage 

func (b *Bot) OnMessage(handler MessageHandler)

OnMessage registers a message handler.

func (*Bot) Reply 

func (b *Bot) Reply(ctx context.Context, msg *IncomingMessage, text string) error

Reply sends a text reply to an incoming message.

func (*Bot) ReplyContent 

func (b *Bot) ReplyContent(ctx context.Context, msg *IncomingMessage, content SendContent) error

ReplyContent replies with any content type.

func (*Bot) Run 

func (b *Bot) Run(ctx context.Context) error

Run starts the long-poll loop. Blocks until Stop() is called or context is cancelled.

func (*Bot) Send 

func (b *Bot) Send(ctx context.Context, userID, text string) error

Send sends a text message to a user (requires prior context_token).

func (*Bot) SendMedia 

func (b *Bot) SendMedia(ctx context.Context, userID string, content SendContent) error

SendMedia sends any content type to a user.

func (*Bot) SendTyping 

func (b *Bot) SendTyping(ctx context.Context, userID string) error

SendTyping shows the "typing..." indicator.

func (*Bot) Stop 

func (b *Bot) Stop()

Stop gracefully stops the poll loop.

func (*Bot) StopTyping 

func (b *Bot) StopTyping(ctx context.Context, userID string) error

StopTyping cancels the "typing..." indicator.

func (*Bot) Upload 

func (b *Bot) Upload(ctx context.Context, data []byte, userID string, mediaType int) (*UploadResult, error)

Upload uploads data to WeChat CDN without sending a message.

type CDNMedia 

type CDNMedia struct {
	EncryptQueryParam string `json:"encrypt_query_param"`
	AESKey            string `json:"aes_key"`
	EncryptType       int    `json:"encrypt_type,omitempty"`
	// FullURL is the complete download URL returned by server; when set, use directly.
	FullURL string `json:"full_url,omitempty"`
}

CDNMedia references an encrypted file on the WeChat CDN.

type ContentType 

type ContentType string

ContentType is the primary type of an incoming message. 

const (
	ContentText  ContentType = "text"
	ContentImage ContentType = "image"
	ContentVoice ContentType = "voice"
	ContentFile  ContentType = "file"
	ContentVideo ContentType = "video"
)

type Credentials 

type Credentials struct {
	Token     string `json:"token"`
	BaseURL   string `json:"baseUrl"`
	AccountID string `json:"accountId"`
	UserID    string `json:"userId"`
	SavedAt   string `json:"savedAt,omitempty"`
}

Credentials holds login credentials.

type DownloadedMedia 

type DownloadedMedia struct {
	Data     []byte
	Type     string // "image", "file", "video", "voice"
	FileName string
	Format   string // "silk" for voice
}

DownloadedMedia is the result of downloading media from a message.

type FileContent 

type FileContent struct {
	Media    *CDNMedia
	FileName string
	MD5      string
	Size     int64
}

FileContent holds parsed file data.

type FileItem 

type FileItem struct {
	Media    *CDNMedia `json:"media,omitempty"`
	FileName string    `json:"file_name,omitempty"`
	MD5      string    `json:"md5,omitempty"`
	Len      string    `json:"len,omitempty"`
}

FileItem holds file content.

type ImageContent 

type ImageContent struct {
	Media      *CDNMedia
	ThumbMedia *CDNMedia
	AESKey     string
	URL        string
	Width      int
	Height     int
}

ImageContent holds parsed image data from a message.

type ImageItem 

type ImageItem struct {
	Media       *CDNMedia `json:"media,omitempty"`
	ThumbMedia  *CDNMedia `json:"thumb_media,omitempty"`
	AESKey      string    `json:"aeskey,omitempty"`
	URL         string    `json:"url,omitempty"`
	MidSize     int64     `json:"mid_size,omitempty"`
	ThumbSize   int64     `json:"thumb_size,omitempty"`
	ThumbWidth  int       `json:"thumb_width,omitempty"`
	ThumbHeight int       `json:"thumb_height,omitempty"`
	HDSize      int64     `json:"hd_size,omitempty"`
}

ImageItem holds image content and CDN references.

type IncomingMessage 

type IncomingMessage struct {
	UserID        string
	Text          string
	Type          ContentType
	Timestamp     time.Time
	Images        []ImageContent
	Voices        []VoiceContent
	Files         []FileContent
	Videos        []VideoContent
	QuotedMessage *QuotedMessage
	Raw           *WireMessage
	ContextToken  string // internal, managed by SDK
}

IncomingMessage is a parsed, user-friendly representation.

type MediaType 

type MediaType int

MediaType is used in upload requests. 

const (
	MediaImage MediaType = 1
	MediaVideo MediaType = 2
	MediaFile  MediaType = 3
	MediaVoice MediaType = 4
)

type MessageHandler 

type MessageHandler func(msg *IncomingMessage)

MessageHandler is called for each incoming user message.

type MessageItem 

type MessageItem struct {
	Type      MessageItemType `json:"type"`
	TextItem  *TextItem       `json:"text_item,omitempty"`
	ImageItem *ImageItem      `json:"image_item,omitempty"`
	VoiceItem *VoiceItem      `json:"voice_item,omitempty"`
	FileItem  *FileItem       `json:"file_item,omitempty"`
	VideoItem *VideoItem      `json:"video_item,omitempty"`
	RefMsg    *RefMessage     `json:"ref_msg,omitempty"`
}

MessageItem is a single content item within a message.

type MessageItemType 

type MessageItemType int

MessageItemType indicates the content type of a message item. 

const (
	ItemText  MessageItemType = 1
	ItemImage MessageItemType = 2
	ItemVoice MessageItemType = 3
	ItemFile  MessageItemType = 4
	ItemVideo MessageItemType = 5
)

type MessageState 

type MessageState int

MessageState indicates the message delivery state. 

const (
	MessageStateNew        MessageState = 0
	MessageStateGenerating MessageState = 1
	MessageStateFinish     MessageState = 2
)

type MessageType 

type MessageType int

MessageType indicates who sent the message. 

const (
	MessageTypeUser MessageType = 1
	MessageTypeBot  MessageType = 2
)

type Options 

type Options struct {
	BaseURL   string
	CredPath  string
	LogLevel  string // "debug", "info", "warn", "error", "silent"
	OnQRURL   func(url string)
	OnScanned func()
	OnExpired func()
	OnError   func(err error)
}

Options configures a Bot instance.

type QuotedMessage 

type QuotedMessage struct {
	Title string
	Text  string
	Type  ContentType
}

QuotedMessage represents a referenced message.

type RefMessage 

type RefMessage struct {
	Title       string       `json:"title,omitempty"`
	MessageItem *MessageItem `json:"message_item,omitempty"`
}

RefMessage represents a quoted/referenced message.

type SendContent 

type SendContent struct {
	Text     string
	Image    []byte
	Video    []byte
	File     []byte
	FileName string
	Caption  string
}

SendContent describes what to send. Use one of:

  • SendText("Hello!")
  • SendImage(data)
  • SendVideo(data)
  • SendFile(data, "report.pdf")

func SendFile 

func SendFile(data []byte, fileName string) SendContent

SendFile creates a file SendContent.

func SendImage 

func SendImage(data []byte) SendContent

SendImage creates an image SendContent.

func SendText 

func SendText(text string) SendContent

SendText creates a text SendContent.

func SendVideo 

func SendVideo(data []byte) SendContent

SendVideo creates a video SendContent.

type TextItem 

type TextItem struct {
	Text string `json:"text"`
}

TextItem holds text content.

type UploadResult 

type UploadResult struct {
	Media             CDNMedia
	AESKey            []byte
	EncryptedFileSize int
}

UploadResult is the result of uploading media to CDN.

type VideoContent 

type VideoContent struct {
	Media      *CDNMedia
	ThumbMedia *CDNMedia
	DurationMs int
	Width      int
	Height     int
}

VideoContent holds parsed video data.

type VideoItem 

type VideoItem struct {
	Media      *CDNMedia `json:"media,omitempty"`
	VideoSize  int64     `json:"video_size,omitempty"`
	PlayLength int       `json:"play_length,omitempty"`
	ThumbMedia *CDNMedia `json:"thumb_media,omitempty"`
}

VideoItem holds video content.

type VoiceContent 

type VoiceContent struct {
	Media      *CDNMedia
	Text       string
	DurationMs int
	EncodeType int
}

VoiceContent holds parsed voice data.

type VoiceItem 

type VoiceItem struct {
	Media      *CDNMedia `json:"media,omitempty"`
	EncodeType int       `json:"encode_type,omitempty"`
	Text       string    `json:"text,omitempty"`
	Playtime   int       `json:"playtime,omitempty"`
}

VoiceItem holds voice content.

type WireMessage 

type WireMessage struct {
	Seq          int64         `json:"seq,omitempty"`
	MessageID    int64         `json:"message_id,omitempty"`
	FromUserID   string        `json:"from_user_id"`
	ToUserID     string        `json:"to_user_id"`
	ClientID     string        `json:"client_id"`
	CreateTimeMs int64         `json:"create_time_ms"`
	MessageType  MessageType   `json:"message_type"`
	MessageState MessageState  `json:"message_state"`
	ContextToken string        `json:"context_token"`
	ItemList     []MessageItem `json:"item_list"`
}

WireMessage is the raw message from the iLink API.

Source Files

View all Source files

Directories

Path Synopsis
examples
echo-bot command
Echo bot example — receives messages and replies with "Echo: <text>".
 Echo bot example — receives messages and replies with "Echo: <text>".
internal
auth
Package auth handles QR code login and credential persistence.
 Package auth handles QR code login and credential persistence.
crypto
Package crypto provides AES-128-ECB encryption/decryption for WeChat CDN media.
 Package crypto provides AES-128-ECB encryption/decryption for WeChat CDN media.
protocol
Package protocol implements the raw iLink Bot API HTTP calls.
 Package protocol implements the raw iLink Bot API HTTP calls.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.