wechat

Documentation

Overview

Package wechat provides a Channel adapter for WeChat Official Accounts (公众号).

Official API Documentation: - URL: https://developers.weixin.qq.com/doc/offiaccount/Getting_Started/Overview.html - API Version: 公众平台 API (服务端 API) - Last Updated: 2024 - Authentication: access_token (AppID + AppSecret)

Supported Features: - Text messages (文本消息) - Image messages (图片消息) - Voice messages (语音消息) - Video messages (视频消息) - File messages (文件消息) - Template messages (模板消息)

Rate Limits: - access_token: Valid for 2 hours, refresh recommended every 1.5 hours - Template messages: Require user interaction within 48 hours - Customer service messages: 48-hour window after user interaction

Security Requirements: - IP whitelist must be configured in WeChat Developer Console - Server URL must use HTTPS - Message signature verification required for webhooks

Index

• Constants
• Variables
• type APIResponse
• type Channel
  • func NewChannel(name string, config Config) (*Channel, error)
  • func (c *Channel) GetCapabilities() channel.ChannelCapabilities
  • func (c *Channel) HandleWebhook(path string, data []byte) (*message.Message, error)
  • func (c *Channel) SendMessage(ctx context.Context, msg *message.Message) error
  • func (c *Channel) Start(ctx context.Context, handler channel.MessageHandler) error
  • func (c *Channel) Stop(ctx context.Context) error
  • func (c *Channel) VerifySignature(signature, timestamp, nonce string) bool
• type Config
  • func (c *Config) Validate() error
• type FileMessage
• type ImageMessage
• type TextMessage
• type TokenResponse
• type VideoMessage
• type VoiceMessage
• type WebhookRequest

Constants

const (
	BaseURL = "https://api.weixin.qq.com/cgi-bin"

	EndpointToken        = "/token"
	EndpointSendMessage  = "/message/custom/send"
	EndpointSendTemplate = "/message/template/send"
	EndpointUploadMedia  = "/media/upload"
	EndpointGetMedia     = "/media/get"
)

API endpoints for WeChat Official Account API.

Variables

var (
	ErrInvalidSignature     = errors.New("invalid signature")
	ErrTokenExpired         = errors.New("access token expired")
	ErrAppIDRequired        = errors.New("app_id is required")
	ErrAppSecretRequired    = errors.New("app_secret is required")
	ErrTokenRequired        = errors.New("token is required for webhook verification")
	ErrUserNotSubscribed    = errors.New("user not subscribed")
	ErrTemplateNotFound     = errors.New("template not found")
	ErrMessageOutsideWindow = errors.New("message outside 48-hour window")
)

Error definitions for WeChat channel.

Types

type APIResponse

type APIResponse struct {
	ErrCode int    `json:"errcode"`
	ErrMsg  string `json:"errmsg"`
}

APIResponse represents a generic API response.

type Channel

type Channel struct {
	*channel.BaseChannel
	// contains filtered or unexported fields
}

Channel implements the channel.Channel interface for WeChat.

func NewChannel

func NewChannel(name string, config Config) (*Channel, error)

NewChannel creates a new WeChat channel.

func (*Channel) GetCapabilities

func (c *Channel) GetCapabilities() channel.ChannelCapabilities

GetCapabilities returns the capabilities of the WeChat channel.

func (*Channel) HandleWebhook

func (c *Channel) HandleWebhook(path string, data []byte) (*message.Message, error)

HandleWebhook processes incoming webhook requests from WeChat. This implements the WebhookHandler interface.

func (*Channel) SendMessage

func (c *Channel) SendMessage(ctx context.Context, msg *message.Message) error

SendMessage sends a message to a WeChat user.

func (*Channel) Start

func (c *Channel) Start(ctx context.Context, handler channel.MessageHandler) error

Start initializes the channel and starts token refresh loop.

func (*Channel) Stop

func (c *Channel) Stop(ctx context.Context) error

Stop gracefully shuts down the channel.

func (*Channel) VerifySignature

func (c *Channel) VerifySignature(signature, timestamp, nonce string) bool

VerifySignature verifies the webhook signature from WeChat.

type Config

type Config struct {
	AppID     string
	AppSecret string
	Token     string
	AESKey    string
}

Config contains the configuration for WeChat channel.

func (*Config) Validate

func (c *Config) Validate() error

Validate validates the configuration.

type FileMessage

type FileMessage struct {
	ToUser  string `json:"touser"`
	MsgType string `json:"msgtype"`
	File    struct {
		MediaID string `json:"media_id"`
	} `json:"file"`
}

FileMessage represents a file message to send.

type ImageMessage

type ImageMessage struct {
	ToUser  string `json:"touser"`
	MsgType string `json:"msgtype"`
	Image   struct {
		MediaID string `json:"media_id"`
	} `json:"image"`
}

ImageMessage represents an image message to send.

type TextMessage

type TextMessage struct {
	ToUser  string `json:"touser"`
	MsgType string `json:"msgtype"`
	Text    struct {
		Content string `json:"content"`
	} `json:"text"`
}

TextMessage represents a text message to send.

type TokenResponse

type TokenResponse struct {
	AccessToken string `json:"access_token"`
	ExpiresIn   int    `json:"expires_in"`
	ErrCode     int    `json:"errcode"`
	ErrMsg      string `json:"errmsg"`
}

TokenResponse represents the response from the token API.

type VideoMessage

type VideoMessage struct {
	ToUser  string `json:"touser"`
	MsgType string `json:"msgtype"`
	Video   struct {
		MediaID      string `json:"media_id"`
		ThumbMediaID string `json:"thumb_media_id"`
		Title        string `json:"title"`
		Description  string `json:"description"`
	} `json:"video"`
}

VideoMessage represents a video message to send.

type VoiceMessage

type VoiceMessage struct {
	ToUser  string `json:"touser"`
	MsgType string `json:"msgtype"`
	Voice   struct {
		MediaID string `json:"media_id"`
	} `json:"voice"`
}

VoiceMessage represents a voice message to send.

type WebhookRequest

type WebhookRequest struct {
	ToUserName   string  `xml:"ToUserName"`
	FromUserName string  `xml:"FromUserName"`
	CreateTime   int64   `xml:"CreateTime"`
	MsgType      string  `xml:"MsgType"`
	Content      string  `xml:"Content"`
	MsgID        string  `xml:"MsgId"`
	PicURL       string  `xml:"PicUrl"`
	MediaID      string  `xml:"MediaId"`
	Format       string  `xml:"Format"`
	ThumbMediaID string  `xml:"ThumbMediaId"`
	Location_X   float64 `xml:"Location_X"`
	Location_Y   float64 `xml:"Location_Y"`
	Scale        int     `xml:"Scale"`
	Label        string  `xml:"Label"`
	Event        string  `xml:"Event"`
	EventKey     string  `xml:"EventKey"`
}

WebhookRequest represents an incoming webhook request from WeChat.