Skip to content

xwang152-jack/wechat_official_plugin

BranchesTags

Repository files navigation

WeChat Official Account Plugin for Dify

This is a WeChat Official Account plugin developed for the Dify platform, providing complete WeChat Official Account API integration with support for material management, draft operations, and message publishing.

Features

🔐 Access Token Management

  • Get Access Token: Retrieve WeChat Official Account access tokens with automatic refresh support
  • Credential Validation: Automatically validate App ID and App Secret validity
  • Secure Storage: Securely manage and store access credentials

📁 Material Management

  • Upload Permanent Materials: Support for multiple media types including images, audio, video, and thumbnails
  • Get Permanent Materials: Retrieve uploaded permanent material information using media IDs
  • Delete Permanent Materials: Remove unnecessary permanent materials
  • Smart File Processing: Automatic handling of file size limits, format validation, and error processing
  • Multiple Upload Methods: Support for both URL links and local file uploads

📝 Draft Management

  • Create Article Drafts: Create article message drafts with complete information including titles, content, and cover images
  • Publish Drafts: Submit drafts for publication to WeChat Official Account
  • Parameter Validation: Complete parameter validation and error prompts
  • Chinese Character Support: Perfect support for Chinese content encoding and display

Project Structure

wechat_official_plugin/
├── manifest.yaml              # Plugin configuration file
├── main.py                   # Plugin entry file
├── requirements.txt          # Python dependencies
├── README.md                # Project documentation
├── .env.example             # Environment variable example
├── _assets/
│   └── icon.svg             # Plugin icon
├── provider/
│   ├── wechat_official.yaml # Provider configuration
│   └── wechat_official_provider.py # Provider implementation
└── tools/
    ├── __init__.py             # Tool package initialization
    ├── wechat_api_utils.py     # WeChat API utility class
    ├── get_access_token.yaml   # Get access token tool configuration
    ├── get_access_token.py     # Get access token tool implementation
    ├── upload_material.yaml   # Upload material tool configuration
    ├── upload_material.py     # Upload material tool implementation
    ├── get_material.yaml      # Get material tool configuration
    ├── get_material.py        # Get material tool implementation
    ├── delete_material.yaml   # Delete material tool configuration
    ├── delete_material.py     # Delete material tool implementation
    ├── create_draft.yaml      # Create draft tool configuration
    ├── create_draft.py        # Create draft tool implementation
    ├── publish_draft.yaml     # Publish draft tool configuration
    └── publish_draft.py       # Publish draft tool implementation

Technical Specifications

  • Python Version: 3.12+
  • Architecture Support: AMD64, ARM64
  • Memory Requirements: 1MB
  • Dependencies:
    • dify_plugin: Dify plugin development framework
    • python-dotenv>=1.0.0: Environment variable management
    • Pillow>=10.0.0: Image processing support

Quick Start

1. Environment Setup

Ensure your system has Python 3.12 or higher installed.

2. Install Dependencies

cd wechat_official_plugin
pip install -r requirements.txt

3. Configure Environment Variables

Copy the environment variable example file and configure your WeChat Official Account information:

cp .env.example .env

Edit the .env file and fill in your WeChat Official Account configuration:

# WeChat Official Account Configuration
WECHAT_APP_ID=your_app_id_here
WECHAT_APP_SECRET=your_app_secret_here

4. Run Plugin

python main.py

Plugin Installation

Custom Plugin Local Upload

If you encounter an exception message during plugin installation:

plugin verification has been enabled, and the plugin you want to install has a bad signature

Solution (Simple and Direct):

Directly modify Dify's .env file:

FORCE_VERIFYING_SIGNATURE=false

Note: After adding this, you need to restart Docker by executing the following commands in the command line:

cd docker  # First switch to the docker directory under your local Dify installation directory
docker compose down
docker compose up -d

Configuration Guide

WeChat Official Account Configuration

Before using the plugin, you need to obtain the following information from WeChat Official Account Platform:

  1. App ID: WeChat Official Account application ID
  2. App Secret: WeChat Official Account application secret

Steps to Get Configuration Information

  1. Login to WeChat Official Account Platform
  2. Go to "Development" -> "Basic Configuration"
  3. Get "Developer ID (AppID)" and "Developer Password (AppSecret)"
  4. Ensure the official account is verified and has relevant interface permissions enabled

FILES_URL Configuration

Used to display file preview or download links to the frontend, or as multimodal input; links are signed and have expiration times.

File processing plugins must configure FILES_URL:

  • If the address is https://example.com, set FILES_URL=https://example.com
  • If the address is http://example.com, set FILES_URL=http://example.com

Modify Dify's .env file:

FILES_URL=http://<your_IP_address>

Restart Docker service:

docker compose down
docker compose up -d

Tool Usage Guide

Get Access Token

# Get access token
result = get_access_token_tool.invoke({
    # No additional parameters needed, uses configured App ID and App Secret
})

Upload Materials

# Upload image material
result = upload_material_tool.invoke({
    "media_type": "image",
    "file_url": "https://example.com/image.jpg"
})

# Upload video material
result = upload_material_tool.invoke({
    "media_type": "video",
    "file_url": "https://example.com/video.mp4",
    "title": "Video Title",
    "introduction": "Video Description"
})

# Upload audio material
result = upload_material_tool.invoke({
    "media_type": "voice",
    "file_url": "https://example.com/audio.mp3"
})

Get and Delete Materials

# Get material information
result = get_material_tool.invoke({
    "media_id": "your_media_id"
})

# Delete material
result = delete_material_tool.invoke({
    "media_id": "your_media_id"
})

Create and Publish Drafts

# Create article draft
result = create_draft_tool.invoke({
    "title": "Article Title",
    "content": "<p>Article Content HTML</p>",
    "author": "Author Name",
    "digest": "Article Summary",
    "thumb_media_id": "cover_image_media_id",
    "content_source_url": "https://example.com",
    "need_open_comment": "1",
    "only_fans_can_comment": "0"
})

# Publish draft
result = publish_draft_tool.invoke({
    "media_id": "draft_media_id"
})

Error Handling

The plugin includes comprehensive error handling mechanisms, including:

  • Network Errors: Automatic retry and timeout handling (30-second timeout)
  • API Errors: Detailed error code explanations and handling suggestions
  • Parameter Validation: Input parameter format and validity checks
  • File Processing: File size, format, and permission checks
  • Encoding Processing: Perfect support for Chinese character encoding and display
  • Credential Management: Automatic validation and refresh of access tokens

Featured Capabilities

🌟 Perfect Chinese Character Support

The plugin has completely resolved Chinese character encoding issues:

  • ✅ Perfect support for Chinese in draft titles, content, authors, and other fields
  • ✅ Correct handling of Unicode characters during JSON data transmission
  • ✅ Proper display of Chinese content in WeChat API responses
  • ✅ No manual handling of Unicode escape sequences required

🛡️ Smart Parameter Validation

  • Title length limit (≤64 characters)
  • Author name length limit (≤8 characters)
  • Summary length limit (≤120 characters)
  • Cover image media_id format validation
  • HTML content security checks

Important Notes

  1. Interface Permissions: Ensure your WeChat Official Account has the relevant interface permissions enabled
  2. Call Frequency: Comply with WeChat API call frequency limits
  3. File Size: Different material types have different file size limits
  4. Content Review: Published content needs to pass WeChat platform review
  5. Original Protection: If there are original declarations, they need to pass original review
  6. Character Encoding: The plugin automatically handles Chinese character encoding, no additional configuration needed

Troubleshooting

"Invalid credentials" Error 🔥 Most Common Issue

If you encounter an "Invalid credentials" error when configuring the plugin, please follow these troubleshooting steps:

Quick Diagnosis

# Use built-in diagnostic tool
python diagnostic.py --app-id YOUR_APP_ID --app-secret YOUR_APP_SECRET

Manual Check Steps

  1. Verify Credential Format

    • App ID: Must start with wx, total length 18 characters
    • App Secret: Must be a 32-character hexadecimal string
    • Ensure no extra spaces or line breaks

  2. Confirm Credential Source

    • Login to WeChat Official Account Platform
    • Go to "Development" -> "Basic Configuration"
    • Copy the correct "Developer ID (AppID)" and "Developer Password (AppSecret)"

  3. Check Official Account Status

    • ✅ Official account is verified
    • ✅ Material management interface permissions are enabled
    • ✅ Draft box/publishing interface permissions are enabled

  4. Network Connection Test

    # Test if WeChat API is accessible
curl -I https://api.weixin.qq.com

Common Error Code Explanations

Error Code Description Solution
40013 Invalid AppID Check App ID format and validity
41004 Missing secret parameter Confirm App Secret is correctly filled
42001 access_token timeout Re-obtain access token
48001 API function not authorized Confirm official account has relevant interface permissions enabled

Detailed Troubleshooting Guide: Please refer to TROUBLESHOOTING.md

Technical Support

If you encounter problems during use, please check:

  1. WeChat Official Account configuration is correct
  2. Network connection is normal
  3. API permissions are enabled
  4. Call parameters meet requirements

Getting Help

  1. Run Diagnostic Tool: python diagnostic.py --app-id YOUR_APP_ID --app-secret YOUR_APP_SECRET
  2. Check Detailed Logs: Check error information in Dify system logs
  3. Reference Documentation: See TROUBLESHOOTING.md for detailed solutions

Changelog

v0.0.1 (2025-09-05)

  • 🎉 Initial version release
  • ✅ Support for access token acquisition and management
  • ✅ Support for permanent material upload, retrieval, and deletion
  • ✅ Support for article draft creation and publishing
  • ✅ Complete error handling and parameter validation mechanisms
  • ✅ Fixed Chinese character encoding issues, perfect Unicode support
  • ✅ Smart file processing and format validation
  • ✅ 30-second timeout setting adapted to WeChat API response times
  • ✅ Detailed error diagnosis and user-friendly error prompts

License

This project is licensed under the MIT License. See the LICENSE file for details.

About

his is a WeChat Official Account plugin developed for the Dify platform, providing complete WeChat Official Account API integration with support for material management, draft operations, and message publishing.

Resources

Readme
Activity

Stars

4 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages