WeChat appmsgpublish vs profile_ext/getmsg APIs: Key Differences and Use Cases

The appmsgpublish API returns an HTML publish page intended for browser rendering, while the profile_ext/getmsg API returns structured JSON containing message metadata used for data extraction and bulk export operations.

When building export tools for WeChat Official Accounts using the wechat-article/wechat-article-exporter repository, developers must choose between two distinct backend endpoints. While both APIs retrieve article listings from the WeChat MP backend, they serve fundamentally different architectural purposes—one delivers human-readable HTML, while the other provides machine-readable JSON for programmatic processing.

Core Architectural Differences

The appmsgpublish Endpoint

The appmsgpublish endpoint (https://mp.weixin.qq.com/cgi-bin/appmsgpublish) retrieves the publish page of a public account. According to the implementation in server/api/web/mp/appmsgpublish.get.ts, the handler constructs a query string using parameters like sub, fakeid, begin, count, and token. The response type defined in types/types.d.ts as AppMsgPublishResponse contains a publish_page field with raw HTML that can be directly rendered in a browser or parsed with Cheerio.

The profile_ext/getmsg Endpoint

In contrast, the profile_ext/getmsg endpoint (https://mp.weixin.qq.com/mp/profile_ext) provides a paginated list of messages in JSON format. As implemented in server/api/web/mp/profile_ext_getmsg.get.ts, this API uses query parameters including action=getmsg, __biz, offset, count, uin, key, and pass_ticket. The TypeScript definition in types/profile_getmsg.d.ts reveals that the response includes a general_msg_list string containing JSON-encoded message data with titles, URLs, publish dates, and media types.

Authentication and Request Flow

Both APIs are proxied through the exporter's Nitro server using the proxyMpRequest() function in server/utils/proxy-request.ts, but they handle authentication differently.

For appmsgpublish, the system extracts a login token from the cookie store via getTokenFromStore and passes it as a token query parameter. The profile_ext/getmsg API embeds authentication credentials directly in the query string through uin, key, and pass_ticket parameters, requiring no explicit cookie injection beyond the standard proxy headers.

Response Formats and Data Processing

The response handling diverges significantly between the two endpoints.

The appmsgpublish API returns HTML content suitable for display or DOM parsing. Client-side code in apis/index.ts wraps this with request<AppMsgPublishResponse>('/api/web/mp/appmsgpublish', …) to retrieve the publish page directly.

The profile_ext/getmsg API returns parsed JSON (via parseJson: true in the proxy) that feeds the exporter pipeline. As shown in apis/index.ts at line 143, the frontend calls request<ProfileGetMsgResponse>('/api/web/mp/profile_ext_getmsg', …) and parses the general_msg_list JSON string into ParsedProfileGetMsg objects to populate the download queue.

Code Examples: Fetching Data from Both APIs

When fetching the publish page for display purposes:

import { request } from '@/utils/request'

async function getPublishPage(fakeId: string, token: string) {
  const resp = await request<AppMsgPublishResponse>('/api/web/mp/appmsgpublish', {
    query: { id: fakeId, token, begin: 0, size: 10, keyword: '' },
  })
  // resp.publish_page contains the raw HTML of the publish list
  return resp.publish_page
}

When extracting structured data for export operations:

import { request } from '@/utils/request'

async function getProfileMessages(params: {
  id: string; uin: string; key: string; pass_ticket: string; begin?: number; size?: number
}) {
  const resp = await request<ProfileGetMsgResponse>('/api/web/mp/profile_ext_getmsg', {
    query: { ...params, begin: params.begin ?? 0, size: params.size ?? 10 },
  })
  // resp.general_msg_list is a JSON string → parse it
  const messageList = JSON.parse(resp.general_msg_list) as ParsedProfileGetMsg[]
  return messageList
}

When to Use Each API

Use appmsgpublish when you only need a quick preview of the public account's article list in HTML format, such as for displaying the official "publish page" as-is in a browser interface.

Use profile_ext/getmsg when you need structured data for each article—including titles, URLs, publish dates, and media types—to drive export functions like the Downloader or Exporter components in the wechat-article-exporter pipeline.

Summary

• appmsgpublish returns HTML (publish_page) from https://mp.weixin.qq.com/cgi-bin/appmsgpublish, requiring a token parameter stored in cookies.
• profile_ext/getmsg returns JSON (general_msg_list) from https://mp.weixin.qq.com/mp/profile_ext, using uin, key, and pass_ticket for authentication.
• Both APIs are proxied through server/utils/proxy-request.ts but handle different content types—HTML versus machine-readable JSON.
• The exporter uses appmsgpublish for display purposes and profile_ext/getmsg for data extraction that feeds the download queue.

Frequently Asked Questions

What is the main difference between appmsgpublish and profile_ext/getmsg?

The appmsgpublish API provides an HTML publish page designed for browser rendering, while profile_ext/getmsg returns structured JSON data containing article metadata. The former is implemented in server/api/web/mp/appmsgpublish.get.ts and returns AppMsgPublishResponse, whereas the latter is implemented in server/api/web/mp/profile_ext_getmsg.get.ts and returns ProfileGetMsgResponse with a parseable general_msg_list field.

Which API should I use for exporting WeChat articles to PDF or HTML?

You should use the profile_ext/getmsg API. According to the wechat-article-exporter source code, this endpoint provides the general_msg_list JSON that contains structured article data—including titles, URLs, and dates—required by the Downloader and Exporter classes to perform bulk exports. The appmsgpublish API only provides display-oriented HTML without the structured metadata needed for automated export pipelines.

How does authentication differ between these two WeChat APIs?

Authentication differs in parameter passing: appmsgpublish requires a token query parameter extracted from cookie storage via getTokenFromStore, while profile_ext/getmsg embeds credentials directly in the query string using uin, key, and pass_ticket parameters. Both APIs route through proxyMpRequest() in server/utils/proxy-request.ts, but appmsgpublish explicitly handles session tokens whereas profile_ext/getmsg relies on ticket-based authentication.

Where are these API proxies implemented in the codebase?

The appmsgpublish proxy handler is located at server/api/web/mp/appmsgpublish.get.ts, and the profile_ext_getmsg handler is at server/api/web/mp/profile_ext_getmsg.get.ts. Both utilize the shared proxyMpRequest() utility in server/utils/proxy-request.ts to forward requests to WeChat's official endpoints, with type definitions residing in types/types.d.ts and types/profile_getmsg.d.ts respectively.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}