How to Integrate WeChat `draft_add`

If you are building WeChat automation, one concrete question appears sooner or later:

How should the official draft_add endpoint be integrated, and where do teams usually get it wrong?

This is more practical than asking what a draft API is in general, because real integration failures appear immediately once the request hits production data.

Official WeChat reference:

• Draft Add (draft_add)

What draft_add does

The official API name is:

draft_add

The endpoint is:

POST https://api.weixin.qq.com/cgi-bin/draft/add?access_token=ACCESS_TOKEN

Its role is direct:

It adds article or image-message content into the WeChat draft box.

That means it is not a formatting API. It is a draft-management API.

If you need the higher-level separation first, continue with:

• What Is the WeChat Draft API, and How Is It Different from Markdown-to-HTML Conversion?
• How to Integrate the Article Draft API: Minimum Headers, Body, and Order of Operations

Rule one: server-side only

This is the most important constraint.

According to the official docs, draft_add:

must be called from the server, not directly from a frontend such as a webpage, mini-program, or app client.

So the stable structure is:

1. the frontend sends content to your server
2. your server obtains or refreshes access_token
3. your server calls draft_add

If your design depends on browser-side calls to WeChat, the integration model is already off.

Adding a draft does not mean permanent storage

Two official behavior details are easy to overlook:

1. after a draft is mass-sent or published, it is removed from the draft box
2. drafts can be viewed and managed in the public-account platform

So the draft box should be treated as:

• a pre-publish state

not as:

• a permanent content store

If you need reliable records, keep your own business-side state instead of assuming the draft box is long-term storage.

The key request shape

The core structure is:

{
  "articles": [
    {
      "article_type": "news",
      "title": "Title",
      "content": "HTML or body content"
    }
  ]
}

The important detail is that the item shape changes with article_type.

The official docs support at least these types:

• news
• newspic

Treating them as one generic object is a common source of bugs.

Common mistakes in news article drafts

1. Sending Unicode-escaped title or author strings

The official docs explicitly warn against manually sending strings like "\u4f5c\u8005" instead of normal characters.

Pass normal strings. Do not pre-escape them into Unicode literals.

2. Treating content as arbitrary HTML

The content field has real constraints:

• HTML is supported
• content must stay below 20,000 characters
• content must stay under 1MB
• JavaScript is removed
• image URLs inside the body must come from the dedicated article-image upload workflow
• external image URLs can be filtered

That means this assumption is unsafe:

No. For article bodies, image handling has to follow WeChat's rules, or the content will not survive the draft workflow intact.

3. Treating thumb_media_id as optional

For article_type = news, thumb_media_id is required and must be a permanent media id.

So a public cover-image URL is not enough. The cover must first become WeChat-recognized media.

newspic is not the same as news

For newspic, the focus shifts toward fields such as:

• image_info.image_list
• cover_info.crop_percent_list
• product_info.footer_product_info.product_key

Two rules matter immediately:

1. There can be at most 20 images

The official docs cap image-message content at 20 images, and the first image becomes the cover image.

If your system generates image lists dynamically, validate the count before calling WeChat.

2. Product-card fields depend on account capability

The docs list error codes such as:

• 53404
• 53405
• 53406

These indicate that commerce-related fields depend not only on request structure, but also on account-side selling capability and product state.

So a product-card draft should not be treated as the default path.

Why crop fields fail so often

The cover-crop fields in draft creation are not pixel coordinates. They are percentage-based values.

If your integration treats them like raw image editor coordinates, the result can be invalid even if the field names are correct.

That is one reason why cover handling should be separated from article-body handling during debugging.

A safer debugging order

When draft_add fails, a better sequence is:

1. confirm the call is server-side
2. confirm access_token is valid
3. confirm whether the content is news or newspic
4. validate body length and HTML constraints
5. validate body-image handling separately from cover-media handling
6. confirm thumb_media_id or other required media ids exist
7. only then inspect more specialized fields like crop settings or product info

That order finds integration errors faster because it starts with the stable constraints first.

Closing thought

draft_add is not difficult because the JSON is large. It is difficult because draft creation sits at the boundary between content rules, media rules, and account capability.

Once those layers are separated, the endpoint becomes much easier to integrate and much easier to debug.