Inside WeChat's New AI Entry Point: A Field Guide to Every Roadblock in Integrating Xiaowei
Preface | A New AI Entry Point Emerges in WeChat: We Wrote Down Every Pitfall We Hit While Integrating It
Series: "Xiaowei (WeChat Mini Program AI) in Practice" - Part 0 ⚠️ Version note: This article is based on the Xiaowei internal beta (official docs and team testing as of 2026-11-18). WeChat has not released an official version. Capabilities, entry points, and rules described here may change with version iterations. After the official release, please refer to the official documentation.
1. Where This Series Comes From
In the second half of 2026, WeChat started beta-testing an AI capability called "Xiaowei" within its mini-program system. When a user says something to Xiaowei in WeChat, Xiaowei understands the intent, directly calls a capability registered by a mini-program, and returns a result card in the conversation. The user taps the card to go directly to a specific page in the mini-program.
Our team integrated our mini-program (Taro tech stack) with this capability as soon as possible, and we went through the complete path:
Apply for access → Development mode selection → Engineering implementation → Writing skills → Self-testing → Evaluation → Review submission → Release → Gray rollout → Hit troubleshooting and optimization
Every step on this path has its own pitfalls. And these pitfalls share a common characteristic: you can't find them online.
- Some pitfalls are due to official documentation being scattered and frequently updated, requiring cross-referencing to piece together the truth.
- Some pitfalls are because the rules are unclear during the beta phase, so they can only be discovered through actual testing (e.g., the hard requirement for the number of evaluation cases, the troubleshooting path when gray rollout doesn't hit).
- Some pitfalls are even "the documentation says A, but reality is B" - for example, the document quality evaluation has zero tolerance for fixed scripts, and
context.queryis not what you think ("extracted entities").
So we decided to compile these first-hand experiences into a series, both to give team members who weren't involved a complete understanding and to provide other developers on the same integration path with a "pitfall map."
2. What This Series Covers
The series consists of 11 parts (preface + 10 main articles), unfolding along the real integration timeline:
| # | Chapter | What You'll Get |
|---|---|---|
| 1 | Get to Know Xiaowei | What Xiaowei is, where the entry point is, the complete chain behind one invocation, and two major cognitive misunderstandings |
| 2 | Integration Modes and Access Preparation | How to choose between Automatic Mode and AI Development Mode, and the version threshold that will block you if not confirmed in advance |
| 3 | [Hands-on 1] Engineering Implementation | Coexistence of AI subpackages with the main project, how to configure agent, and hard configuration constraints |
| 4 | [Hands-on 2] Writing a Skill from Scratch | Using a real "product search" case to explain the 4 most universally valuable hands-on points |
| 5 | [Hands-on 3] Relay Landing | After the user taps the AI card: WebView hosting, atomic component navigation, login completion |
| 6 | [Hands-on 4] Giving the Agent a Persona | How to write an AGENTS.md: identity positioning, intent distribution table, boundaries and fallback |
| 7 | Evaluation | The passing line for self-testing and WeChat team evaluation, hard case requirements, and pitfalls that only pre-checks reveal |
| 8 | Review and Release | The complete process and checklist between evaluation passing and actual launch |
| 9 | Gray Rollout and Hit Troubleshooting | Gray rollout mechanism, the "why am I not hitting" decision tree, monitoring dashboards |
| 10 | Hit Effect Optimization | Two-layer selection model for hits, all optimization levers on code-side and platform-side |
In one sentence: The full-chain practical guide from "having heard of Xiaowei" to "being launched and hit by users."
3. Who This Is For
- Mini-program developers who haven't touched Xiaowei yet: The target audience of this series. No AI background is required; Chapter 1 starts from "what exactly is Xiaowei."
- Developers currently integrating: Jump directly to Chapters 3-6 for engineering implementation, skill writing, relay reception, and Agent persona. The evaluation, review, and gray rollout pitfalls in Chapters 7-9 can save you a lot of trial-and-error time.
- Technical decision-makers: Chapters 1 and 2 are enough for you to judge "whether to integrate, which mode, and where the costs lie."
4. Reading Prerequisites and Conventions
- Beta disclaimer: Xiaowei is currently in beta. All capabilities, configurations, version numbers, evaluation standards, and gray rollout rules in this series are based on the 2026-11 beta version official docs and team testing. They may change at any time with version iterations. Each chapter includes a version note at the top. After the official release, please refer to the official documentation.
- Desensitization: Company names, internal domains, and API addresses are desensitized or replaced with placeholders. All test conclusions come from the team's real projects, but example code is generalized.
- Tech stack background: Our main project is a Taro + React mini-program, but the AI development mode part of Xiaowei uses native mini-program code (as required by the official docs). The series will explain how the two coexist; you don't need to be familiar with Taro.
- No repetition of official docs: Where official docs clearly describe syntax details, we only provide links without copying. The value of this series lies in what the official docs don't clarify, what's scattered, or what differs from actual behavior.
5. Let's Start
If you have no concept of Xiaowei yet, start from Chapter 1 - it corrects two cognitive misconceptions almost everyone hits, and that's the foundation for everything else.
Next article: 01 - Get to Know Xiaowei: What Is the AI Assistant in WeChat, Really?
This article is a compilation of hands-on experience (based on the beta version). Official capabilities and processes are subject to WeChat's open documentation and public platform backend.