How to Build a WeChat Message Push Service with Cloudflare Workers: A Complete Guide from Zero to Deployment
Hi there. I’m a developer who has spent years working with serverless architectures and the WeChat ecosystem, and I want to share something genuinely useful with you. Let’s talk about a lightweight, practical tool that solves a common problem: how to reliably push business messages directly to WeChat users without managing servers or paying for expensive third-party services.
Have you faced situations like these? Your server crashes at 2 AM, but you don’t notice until morning. A customer places an order, but the system can’t notify you immediately. Or maybe you want to send yourself a daily digest report, but can’t find a simple, free solution. Traditional approaches require renting servers or using paid push platforms—both cumbersome and costly.
The solution we’re exploring today might be exactly what you need. It requires no server rental, no ongoing maintenance, deploys in minutes, and offers a generous free tier that covers individual or small-team usage. Most importantly, you maintain full control over the entire process.
What Exactly Is This Solution?
In simple terms, we’re building a middleware service on Cloudflare Workers that receives your HTTP requests and calls the WeChat Official Account Template Message API to deliver content to users. This service is called WXPush.
What are Cloudflare Workers? Think of them as lightweight code running on over 300 global CDN edge nodes. When a user makes a request, it’s automatically routed to the nearest city, resulting in extremely low latency. The key advantage is usage-based pricing with a generous free tier of 100,000 requests per day—making it essentially free for personal projects.
What are WeChat Template Messages? This is an official WeChat capability that allows verified Official Accounts to send structured notification cards for important updates like “Order Payment Successful” or “Service Exception Alert.” These messages appear quietly in the user’s chat list without the intrusiveness of customer service messages.
Why Invest Time in This Approach?
Before we start, you might ask: “Aren’t there existing push services? Why build my own?” Fair question. This approach offers tangible benefits:
First, the cost is genuinely low. Cloudflare’s free tier includes 100,000 requests/day and 10 million KV operations/day. Unless your business sends messages to tens of thousands of people daily, you’ll never pay a cent. Compare this to the cheapest cloud server at several hundred dollars annually, not to mention environment setup and security maintenance.
Second, it’s secure and controllable. Your WeChat credentials are encrypted and stored as Cloudflare Secrets, not hardcoded. Even if your repository becomes public, sensitive data remains protected. All data transmission uses HTTPS, and Cloudflare provides built-in DDoS protection.
Third, it’s highly flexible. You can configure different message templates for different scenarios and even override default settings temporarily via URL parameters. For example, normally push to the operations team, but in emergencies, change one parameter to push to everyone—no code modification needed.
Fourth, maintenance overhead is virtually zero. After deployment, you never worry about server crashes, system upgrades, or security patches. Cloudflare’s engineers handle everything—you simply call the API.
Of course, there are prerequisites: you need a verified WeChat Official Account (Subscription or Service Account), and users must follow this account. This is WeChat’s security mechanism to prevent spam.
What You’ll Need Before Starting
Let’s gather all required materials before beginning to avoid mid-process stalls:
-
A verified WeChat Official Account: Must be verified; personal subscription accounts don’t support template messages. Log into the Official Account admin panel, navigate to “Development” -> “Basic Configuration” to find your AppID and AppSecret. -
A Cloudflare Account: Register at cloudflare.com if you don’t have one—the process is straightforward. -
A Template Message ID: In the Official Account backend, go to “Ad Management” -> “Template Messages.” Select an existing template or apply for a new one. After configuring keywords, the system generates a template ID that looks like 6n_CMcMWtwWMG7pyt1uFg9K27pX-qHQxO2h6sZdJfh0. -
User OpenIDs: This is the unique identifier for users under your Official Account. If unavailable, request from your developer or see the acquisition methods below.
With these ready, we can begin deployment. Two approaches are available based on your technical background.
Deployment Method 1: Direct Code Pasting (Simplest for Beginners)
If you’re unfamiliar with Git or don’t want to set up a development environment, this method is ideal. Complete everything through browser clicks and code pasting.
Step 1: Log Into Cloudflare and Create a Worker
Open your browser and access the Cloudflare Dashboard. In the left menu, find “Workers & Pages,” click it, then select “Create Application” followed by “Create Worker.”
You’ll need to name your service. This name becomes part of your service address: your-worker-name.your-subdomain.workers.dev. Names can only contain letters, numbers, and hyphens, and must be globally unique. I recommend using wxpush- plus your project name, like wxpush-order-notify.
After entering the name, click “Deploy.” Cloudflare will first generate a default Hello World example.
Step 2: Replace with WXPush Code
After successful deployment, you’ll see “Congratulations! Your Worker has been successfully deployed.” Don’t celebrate yet—this is just sample code. Click the “Edit Code” button to enter the online editor.
You’ll see default code like this:
export default {
async fetch(request, env, ctx) {
return new Response('Hello World!');
},
};
Delete it completely. Then open the project’s src/index.js file (if you downloaded the project) or copy directly from the GitHub page. Paste all contents verbatim into the Cloudflare editor.
After pasting, your editor should contain complete logic for handling WeChat tokens, calling the template message API, and validating parameters. Don’t worry if you don’t understand it—it’s already encapsulated; you don’t need to dive deep for now.
Click the “Save and Deploy” button in the editor’s upper-right corner. Cloudflare will recompile and push your code to global nodes—usually within seconds.
Step 3: Configure Environment Variables (Critical)
The code is deployed but doesn’t know your WeChat Official Account information yet. Configure environment variables now.
Return to the Worker’s main management page, click the “Settings” tab, then select “Variables.” Here you’ll see the “Environment Variables” section.
Add the following variables, checking the “Encrypt” option for each one—this is crucial for credential security:
After completing these, click “Save.” Your service now has identity credentials and communication passwords.
Step 4: Test Service Functionality
Open your browser and construct a test URL (replace address and token with yours):
https://<your-worker-address>/wxsend?title=Test Message&content=Deployment successful!&token=your_secret_token
If everything works, you’ll see “Successfully sent messages to 1 user(s). First response: ok.” The configured WeChat user should receive a template message card.
If not, check:
-
Is the token correct? -
Is the OpenID valid? -
Does the template ID contain spaces? -
Does the Official Account have template message permissions?
Deployment Method 2: Automatic GitHub Repository Deployment (Great for Teams)
If you prefer Git for version control and continuous integration, use this method. Cloudflare automatically redeploys whenever you push code updates.
Step 1: Fork the Project Repository
Open the project’s GitHub page and click “Fork” to copy it to your account. Alternatively, clone it locally and push to your new private repository.
Step 2: Connect GitHub in Cloudflare
In the Cloudflare Dashboard, go to “Workers & Pages,” but this time click “Connect to Git.” The system will guide you through authorizing Cloudflare to access your GitHub account.
After authorization, select your forked repository.
Step 3: Configure Build Settings
This step is crucial. Since WXPush is pure JavaScript without a build process, configure build settings specially:
-
Project name: Anything, like wxpush-production -
Production branch: Usually mainormaster -
Framework preset: Must select None -
Build command: Leave blank -
Output directory: Leave blank -
Root directory: Keep /
Step 4: Add Environment Variables
Like Method 1, in the configuration page’s “Environment Variables” section, add API_TOKEN, WX_APPID, WX_SECRET, etc. Again, always check “Encrypt.”
Step 5: Save and Deploy
Click “Save and Deploy.” Cloudflare will automatically pull code from GitHub and complete deployment. Thereafter, every push to your production branch triggers automatic redeployment within minutes.
You can view deployment records, including who pushed what code and when, making rollbacks easy if issues arise.
How to Call This Push Service?
Once running, WXPush supports two invocation methods: GET and POST requests, covering different scenarios.
Method 1: Simple GET Requests
This is the most direct approach, ideal for browser testing or quick scripting with curl.
Basic Format:
https://<your-worker-address>/wxsend?token=your-key&title=message-title&content=message-body
Parameter Breakdown:
Complete Example:
Assume your Worker address is wxpush-api.yourname.workers.dev and you want to send a server restart notification:
<-URL-> 22:00&token=WxPush_2024_Secure_Key_XyZ9LmPqRsTu
Note: Spaces and special characters in URLs must be encoded (e.g., %20 for space), or use URL encoding functions in your programming language.
Method 2: Professional POST Requests
GET requests expose parameters in URLs, making them unsuitable for sensitive data. POST requests place data in the request body—more secure and RESTful-compliant.
Endpoint:
https://<your-worker-address>/wxsend
Headers:
Authorization: your-token
Content-Type: application/json
Body (JSON format):
{
"title": "Webhook Notification",
"content": "Automated task completed, processed 1234 records",
"userid": "o7Xy_1a2B3c4D5e6F7g8H9i0J1k2L3m",
"template_id": "6n_CMcMWtwWMG7pyt1uFg9K27pX-qHQ..."
}
cURL Example:
curl -X POST <-URL-> \
-H 'Authorization: WxPush_2024_Secure_Key_XyZ9LmPqRsTu' \
-H 'Content-Type: application/json' \
-d '{
"title": "Order Payment Success",
"content": "Order #: <-PHONE->, Amount: ¥299.00"
}'
This approach integrates seamlessly with various systems:
-
GitLab/GitHub Webhooks: Auto-notify teams after code commits -
Monitoring Systems: Direct Prometheus/Zabbix alerts to WeChat -
Business Systems: Real-time notifications for orders, shipments, refunds -
Scheduled Tasks: Push daily reports to yourself
Success Response
If messages are sent to at least one user, the service returns HTTP 200 with text like “Successfully sent messages to 1 user(s). First response: ok”.
Error Response
Errors (incorrect token, missing parameters, WeChat API failures) return appropriate HTTP 4xx or 5xx status codes with error details.
Frequently Asked Questions (FAQ)
Based on community feedback, here are the most common questions and their answers.
Q: Is the Cloudflare Workers free tier really sufficient?
A: For individual projects or small teams, absolutely. The free tier provides 100,000 requests/day. Reaching this limit is difficult under normal business scenarios. If you approach the limit, Cloudflare will email you. At that point, consider optimizing your call logic or upgrading to the paid tier starting at $5/month.
Q: Must the WeChat Official Account be enterprise-verified? Can personal accounts work?
A: Personal subscription accounts cannot use template messages. You need a verified enterprise Official Account or Service Account. The verification fee is ¥300/year, charged by Tencent. This is WeChat’s official barrier to prevent spam.
Q: How do I obtain a user’s OpenID?
A: OpenID is the unique user identifier under your Official Account. You can obtain it through: 1) OAuth2.0 web authorization when users visit your pages; 2) WeChat server push events when users message your account; 3) Exporting follower lists from the Official Account backend’s “User Management” section.
Q: Which environment variables must be encrypted?
A: API_TOKEN, WX_APPID, and WX_SECRET must be encrypted—especially WX_SECRET, which authenticates calls to WeChat. Leakage allows impersonation. WX_USERID should also be encrypted, while WX_TEMPLATE_ID and WX_BASE_URL are less sensitive but can be encrypted for consistency.
Q: URL parameters can override environment variables. Does this mean I can expose my token in URLs?
A: Technically possible, but strongly discouraged. URLs are logged in browser history, server logs, and more. Use POST requests with the Authorization header. If you must use GET, ensure requests originate server-side, not from frontend JavaScript.
Q: Why does the call succeed but no message arrives on WeChat?
A: Check these: 1) Is the OpenID valid and the user truly following your account? 2) Does the template ID match your Official Account? 3) WeChat enforces a frequency limit—typically one message per user per template per 24 hours. Exceeding this causes silent failure. Use multiple templates or optimize sending logic.
Q: Can I push to multiple users simultaneously?
A: Yes. In WX_USERID, separate multiple OpenIDs with |: openid1|openid2|openid3. The userid URL parameter completely overrides this list. For dynamic recipient control, maintain user lists at the caller side and loop through calls rather than hardcoding all OpenIDs in environment variables.
Q: Can clicking the template message redirect to a specific page?
A: Yes, that’s the WX_BASE_URL parameter’s function. Clicking opens this link. Include parameters like `<-URL-> for dynamic detail pages. Note: The redirect domain must be added to your Official Account’s “Web Authorization Domain” list or it will be blocked.
Q: How do I integrate with Prometheus monitoring?
A: Configure Alertmanager’s webhook in alertmanager.yml:
receivers:
- name: 'wechat-push'
webhook_configs:
- url: 'https://<your-worker-address>/wxsend'
http_config:
headers:
Authorization: 'your-token'
send_resolved: true
Then format title and content as JSON in alert rules. You may need a conversion script to transform Prometheus alert formats to WXPush requirements.
Security and Best Practices
While the solution is secure by design, follow these guidelines to avoid pitfalls.
Token Management: API_TOKEN is your API password. Never commit it to Git, logs, or frontend code. Rotate regularly by updating the Cloudflare environment variable first, then gradually migrate callers to the new token to avoid service interruption.
Principle of Least Privilege: If multiple team members exist, don’t use one token everywhere. Create separate Worker instances for different businesses, each with unique tokens and recipient lists. This limits blast radius if a token leaks.
Logging and Monitoring: Cloudflare Workers include built-in logging. The dashboard shows request details: response times, status codes, error messages. Review logs regularly, especially during initial use, to ensure normal operation. Address error emails promptly.
Rate Limiting: WeChat strictly limits template messages. Beyond the per-user 24-hour rule, there’s an overall sending frequency limit (undisclosed by WeChat). Avoid mass sending in short bursts to prevent permission revocation. For high-volume businesses, consider WeChat Work or customer service messages.
Error Handling: Implement robust error handling. A 200 response from WXPush only confirms successful WeChat API invocation. WeChat may still return errors: user not following, template mismatch, etc. These details appear in response text—parse and log them.
Real-World Application Scenarios
Theory is valuable, but real examples spark ideas. Here are four actual use cases.
Scenario 1: Server Monitoring Alerts
Alex manages several cloud servers with Prometheus. Previously, alerts went to email, which he rarely checked. He configured Alertmanager webhooks to push alerts to his WeChat. Title: “Server Alert,” Content: “Host db-01 CPU > 90%, current: 95.3%.” Clicking jumps to Grafana dashboards. A midnight vibration means immediate action.
Scenario 2: E-commerce Order Notifications
Bella’s Shopify store processes several orders daily. Email notifications often landed in spam. She configured Shopify webhooks to call WXPush on new orders. Title: “New Order Alert,” Content: “Order #12345, Amount ¥599, Items: T-shirt x2.” Customer service receives it instantly and processes shipments faster.
Scenario 3: Personal Habit Building
Chris wanted to drink more water daily. He wrote a Python script with cron scheduling to call WXPush twice daily: “Time to drink water.” Zero cost, but highly effective because WeChat is an app he definitely checks.
Scenario 4: Git Commit Notifications
Diana’s development team uses GitLab. Whenever code merges to main, GitLab’s webhook triggers WXPush to notify tech leads. Title: “Code Merge Alert,” Content: “Zhang San merged MR #42, 5 files changed.” Leads quickly review changes to ensure quality.
These share a common pattern: information is important but not urgent, needs guaranteed delivery, but doesn’t require real-time chat. Template messages perfectly fit this need.
Video Tutorial and Advanced Learning
If text feels uncertain, the project author prepared a detailed 20-minute video tutorial demonstrating every click. It’s on YouTube with Chinese narration and visual guidance—beginner-friendly.
Video URL: `<-URL-> I recommend pausing frequently to replicate actions in your browser.
For those already familiar with Cloudflare Workers wanting deeper customization, study the src/index.js implementation. It includes WeChat access token caching (avoiding frequent API calls), parameter validation, and error handling. Modify it to add logging, support more message types, or integrate with WeChat Work.
Cost Analysis and Upgrade Recommendations
Let’s discuss costs. The free tier’s 100,000 requests/day—how is this counted? Each call to /wxsend counts as one request. Cloudflare internal operations (like fetching environment variables) don’t count. If you send messages to 10 people, WXPush loops through WeChat API calls but still counts as only 1 Worker request.
When might you exceed it? Attackers maliciously calling your API, or using it as a public API with massive traffic. Normal business operations with thousands of daily active users rarely hit the limit.
If exceeded, Cloudflare returns HTTP 429. Your options:
-
Upgrade to Workers Paid ($5/month) for 10 million requests/day -
Optimize logic: merge multiple messages, batch sends -
Add simple rate limiting in code to prevent abuse
Paid tiers also offer longer CPU time limits (50ms vs. free’s 10ms), larger KV storage, and detailed analytics—but the free tier is sufficient for push services.
Regarding Official Account costs: besides the ¥300/year verification fee, template messages are free. However, if users unfollow or complain about spam, WeChat may revoke API permissions. Always ensure messages provide value.
Troubleshooting Checklist
When service breaks, don’t panic. Follow this systematic checklist to resolve 90% of issues.
-
Check Cloudflare Status: In the Worker dashboard, review recent request status codes. 4xx errors indicate token issues; 5xx errors show server-side problems. Check logs for details. -
Validate WeChat Credentials: Reset AppSecretin the Official Account backend and update the Cloudflare environment variable. Wait ~5 minutes for propagation. -
Test Minimal Case: Use the simplest GET request with only token,title, andcontentto isolate variables. -
Review WeChat Error Codes: WXPush responses include WeChat’s raw response. errcode: 40003means invalid OpenID;43004means user not following;45047means rate limit exceeded. -
Verify Template Status: Ensure the template is active and not deleted in the Official Account backend. -
Confirm Network Connectivity: While Cloudflare is highly reliable, occasional glitches occur. Use curl -Ito verify your Worker address is reachable. -
Check Code Version: With GitHub deployment, ensure the production branch contains the latest code. Sometimes pushes don’t trigger deployments—manually click “Redeploy” in Cloudflare if needed.
If issues persist after this checklist, open an Issue on GitHub with error logs (sanitize sensitive data). The author and community will help analyze.
Contributing and Open Source License
WXPush is open source under the MIT License. This means you can freely use, modify, distribute, and even use it commercially. The only requirement is retaining the original copyright notice in the code.
If you find bugs or have improvements, submit a Pull Request. Potential contributions:
-
Support for additional message types -
Enhanced error messages -
Multi-language support -
More detailed deployment documentation
The project is on GitHub—search for “WXPush.” Contributing improves the tool and builds your coding skills. Even non-coders can help by translating docs or recording tutorial videos.
Summary and Next Steps
By now, you should have a complete understanding of building a WeChat push service with Cloudflare Workers. Let’s recap core steps:
-
Prepare a verified Official Account and Cloudflare account -
Choose deployment method (code paste or GitHub integration) -
Configure encrypted environment variables -
Call via GET or POST -
Flexibly override defaults using URL parameters
This solution’s value lies in encapsulating complex WeChat API calls into simple HTTP requests, while Cloudflare handles server maintenance. You focus on business logic, not infrastructure.
What can you do next?
-
Deploy a test instance now and send your first message -
Replace email notifications in existing systems with WeChat pushes for better reach -
Explore Cloudflare Workers’ other features: KV storage, Durable Objects -
Share within your team for monitoring and business alerts
Technology is vast, but good tools simplify complexity. I hope WXPush becomes a reliable tool in your arsenal. If you encounter deployment issues or discover unique use cases, share them to benefit others.
Appendix: Structured Data Markup
To help search engines and AI assistants understand this content, we provide structured data.
FAQ Schema
{
"@context": "<-URL->",
"@type": "FAQPage",
"mainEntity": [
{
"@type": "Question",
"name": "Is the Cloudflare Workers free tier really sufficient?",
"acceptedAnswer": {
"@type": "Answer",
"text": "For individual projects or small teams, absolutely. The free tier provides 100,000 requests/day. Reaching this limit is difficult under normal business scenarios. If you approach the limit, Cloudflare will email you. At that point, consider optimizing your call logic or upgrading to the paid tier starting at $5/month."
}
},
{
"@type": "Question",
"name": "Must the WeChat Official Account be enterprise-verified? Can personal accounts work?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Personal subscription accounts cannot use template messages. You need a verified enterprise Official Account or Service Account. The verification fee is ¥300/year, charged by Tencent. This is WeChat's official barrier to prevent spam."
}
},
{
"@type": "Question",
"name": "How do I obtain a user's OpenID?",
"acceptedAnswer": {
"@type": "Answer",
"text": "OpenID is the unique user identifier under your Official Account. You can obtain it through: 1) OAuth2.0 web authorization when users visit your pages; 2) WeChat server push events when users message your account; 3) Exporting follower lists from the Official Account backend's 'User Management' section."
}
}
]
}
HowTo Schema
{
"@context": "<-URL->",
"@type": "HowTo",
"name": "How to Deploy a WeChat Push Service via Cloudflare Workers",
"description": "Use the WXPush project to build a WeChat Official Account template message push service on Cloudflare Workers",
"step": [
{
"@type": "HowToStep",
"name": "Prepare accounts and credentials",
"text": "Register and verify a WeChat Official Account to obtain AppID and AppSecret. Register a Cloudflare account."
},
{
"@type": "HowToStep",
"name": "Create Cloudflare Worker",
"text": "Log into the Cloudflare Dashboard, navigate to Workers & Pages, and create a new Worker service."
},
{
"@type": "HowToStep",
"name": "Deploy WXPush code",
"text": "Delete the Worker default code and paste the complete contents of WXPush's src/index.js into the online editor, then save and deploy."
},
{
"@type": "HowToStep",
"name": "Configure encrypted environment variables",
"text": "In Worker settings, add API_TOKEN, WX_APPID, WX_SECRET, WX_USERID and other required variables, ensuring each is marked as encrypted."
},
{
"@type": "HowToStep",
"name": "Test the service",
"text": "Use a browser or curl to construct a GET request to the /wxsend endpoint, verifying successful message delivery to WeChat."
}
]
}
References:
-
Cloudflare Workers Official Documentation: <-URL-> -
Wikipedia – Serverless Computing: <-URL->
