Перейти к навигации

How do I organize an account's WeChat article history before choosing what to read?

To export a WeChat Official Account’s article history, call wechat_mp.v2.fetch_account_articles with the account’s verified username and raw=false. Each list page returns titles, summaries, links and publication times; pass each page’s next_offset back as offset for the next page, then turn the saved responses into a CSV with wechat_history.py below. If you only have an article link, the article-detail action data:wechat_mp.v2.fetch_article_detail_h5 returns the account ID in data.content.user_name.

For example, to find the account’s job announcements from last quarter:

  1. Build the article index back to the start of the quarter.
  2. Pick candidates by actual publication dates and titles.
  3. Open the selected articles to verify roles, deadlines and eligibility.
  4. Share the index, the dates you checked and the articles still to review.

Fetch article text, read counts or comments only for the selected articles.

A history backfill and a daily check start at different places. To resume a backfill, continue from the saved next_offset of the last saved page. To check tomorrow for new articles, start on page one and compare the page with your saved article keys. Daily update workflow

In the article index, keep each page’s request ID, and use each article’s original URL to link the index row to saved article details. The daily check uses the same account and the same article identities as the history backfill, and always starts from the first page.

Identify the account

The required username is an account identifier, not the account’s display name. Supported forms are gh_…, mini-program-linked gh_…@app, and custom WeChat IDs.

If you only have an article URL, inspect the article-detail action data:wechat_mp.v2.fetch_article_detail_h5 first. The article-detail output contract returns the account’s data.content.user_name; the article-detail call is an additional paid lookup, not free account resolution. Do not guess the account identifier from a translated display name.

Inspect the article-list action

curl -sS https://api.beatapi.io/v1/capabilities/inspect \
-H 'Content-Type: application/json' \
-d '{"reference":"data:wechat_mp.v2.fetch_account_articles"}'

Inspect is free. Use Inspect to check the inputs, readiness and price of wechat_mp.v2.fetch_account_articles. For the first page, omit offset or pass an empty string. offset is an opaque pagination cursor, not a row number or an article count.

Fetch one list page

Check the current pricing page, then replace <username> and run:

curl -sS https://api.beatapi.io/v1/social-data/call \
-H "Authorization: Bearer $BEATAPI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"action":"wechat_mp.v2.fetch_account_articles","params":{"username":"<username>","raw":false,"item_show_type":0}}' \
-o wechat-articles-page-1.json

Check the HTTP status and execution status first. With explicit raw=false, the response returns data.articles[], data.biz_username, data.is_end (0/1), and data.next_offset. Each simplified article has app_msg_id, idx, title, digest, url, create_time, and update_time. The default raw=true returns nested batch objects instead. The saved-page incremental guide implements the simplified raw=false shape and state transitions; do not substitute another platform’s fields.

Pass back next_offset

Use the previous response’s next_offset as the next request’s offset, unchanged: do not decode or increment next_offset. Each page is another paid execution.

page_size appears in the input, but the public description says WeChat currently ignores page_size. Setting page_size to 100 does not guarantee one hundred articles, so never estimate collection size as calls multiplied by page_size.

Omitting item_show_type selects articles. Videos, audio and image-text posts are separate content tabs; for an article-history task keep the default instead of mixing tabs into one history.

Create a bounded incremental check

For a history backfill:

  1. Keep the raw responses, request IDs, account, content tab and page number.
  2. Use a verified stable article key for each article.
  3. Stop on a repeated cursor, an error or the approved page limit, and report the range you collected.

An unrecognized output field does not mean the history is exhausted.

A daily check is a separate task: request the first page again and compare the first page against the saved keys. The incremental sync guide covers deduplication, recovery and scheduling. The list has no ordering guarantee, so do not stop at the first old article.

Build an article directory for the username I provide. Check the first page’s account identity, then continue within the chosen date range and budget. Save titles, links, publication times, raw responses and request IDs. Retrieve bodies after I select articles, and report the actual scope and request count when finished.

Cost and next step

Article-list pages and article details are separate executions. Select relevant entries from the article index first, then fetch full text only for the selected articles. The article index does not guarantee complete history or real-time updates.

Social Data contract · Capabilities contract

Save a resumable history chunk, then hand its state to daily checks

A history backfill uses the same documented raw=false fields as the incremental processor, but each chunk continues the current history cursor instead of starting at page one. The wechat_history.py helper below processes saved responses only. wechat_history.py does not execute a paid request and does not retry an error.

  1. Prepare history-pages.json from 1–20 saved pages in the order you collected them. Each entry records the action, the params (canonical gh_ username, raw=false, item_show_type=0, and offset only when continuing), the HTTP status, the collection time, and the response filename. The manifest format is the same as in the incremental guide. Every next page must use the exact preceding data.next_offset. The 20-page limit is a local chunk cap, not a platform page limit or a fixed article count.
  2. Save the script as wechat_history.py and run the first chunk: python3 wechat_history.py - history-pages.json history-001.
  3. wechat_history.py writes the first request of the next chunk to history-001/next-request.json. Collect the next pages within your approved budget, save their log, then run python3 wechat_history.py history-001 next-pages.json history-002.
  4. Keep all chunk directories: state.json holds the current article table, and the earlier raw evidence stays in the earlier chunk directories.
import csv, hashlib, json, pathlib, sys
from datetime import datetime
previous_package, manifest_path, target = sys.argv[1:4]
previous = "-" if previous_package == "-" else str(pathlib.Path(previous_package) / "state.json")
restart = len(sys.argv) == 5 and sys.argv[4] == "--restart"
if len(sys.argv) not in (4, 5) or len(sys.argv) == 5 and not restart:
raise ValueError("Optional final argument is --restart")
entries = json.loads(pathlib.Path(manifest_path).read_text(encoding="utf-8"))
if not isinstance(entries, list) or not 1 <= len(entries) <= 20:
raise ValueError("Supply 1–20 saved pages for this history chunk")
tab = entries[0]["params"].get("item_show_type")
if type(tab) is not int or tab not in (0, 5, 7, 8):
raise ValueError("Select one explicit content tab: 0, 5, 7 or 8")
checkpoint = None if previous_package == "-" else json.loads((pathlib.Path(previous_package) / "checkpoint.json").read_text(encoding="utf-8"))
if checkpoint is not None and restart:
checkpoint = {"version": 1, "resume_params": {"username": json.loads(pathlib.Path(previous).read_text(encoding="utf-8"))["username"], "raw": False, "item_show_type": tab, "offset": ""}}
if checkpoint is not None and (checkpoint.get("version") != 1 or not isinstance(checkpoint.get("resume_params"), dict)):
raise ValueError("History checkpoint is terminal or requires investigation; do not issue another page")
manifest_path, target = pathlib.Path(manifest_path), pathlib.Path(target)
ACTION = "wechat_mp.v2.fetch_account_articles"
state = {"version": 1, "username": None, "item_show_type": tab, "articles": []} if previous == "-" else json.loads(pathlib.Path(previous).read_text(encoding="utf-8"))
if state.get("version") != 1 or (type(state.get("item_show_type")) is not int or state["item_show_type"] != tab) or not isinstance(state.get("articles"), list):
raise ValueError("Expected state for this same content tab")
def number(v):
if type(v) is int and v > 9007199254740991:
raise ValueError("Unsafe numeric ID; require an originally string-encoded ID")
if isinstance(v, bool) or not isinstance(v, (int, str)) or not str(v).isdigit() or int(v) < 1:
raise ValueError("Expected positive article ID/position")
return str(int(v))
def stamp(v):
t = datetime.fromisoformat(v.replace("Z", "+00:00"))
if t.tzinfo is None:
raise ValueError("Collection times must include timezone")
return t
def key(row):
return number(row["app_msg_id"]) + ":" + number(row["idx"])
records = {}
for row in state["articles"]:
k = key(row)
if k in records:
raise ValueError("Duplicate article identity in old state")
stamp(row["first_seen_at"]); stamp(row["last_seen_at"])
records[k] = row
initial = set(records)
new, changed, observed, request_ids, cursors = set(), set(), set(), set(), set()
if checkpoint is not None and not restart:
prior_cursors = checkpoint.get("seen_next_offsets", [])
if not isinstance(prior_cursors, list) or any(not isinstance(c, str) or not c for c in prior_cursors):
raise ValueError("Invalid history cursor ledger")
cursors.update(prior_cursors)
resumed_offset = checkpoint["resume_params"].get("offset")
if resumed_offset:
cursors.add(resumed_offset)
pages, raw_pages, observations = [], [], []
expected, username, last_time = None, state["username"], None
stop = "saved_pages_exhausted"
watermark = stamp(state["last_collected_at"]) if state.get("last_collected_at") else None
processed = state.get("processed_requests", {})
if not isinstance(processed, dict):
raise ValueError("Invalid processed-request ledger")
metadata = ("title", "digest", "url", "create_time", "update_time")
for index, entry in enumerate(entries):
if stop != "saved_pages_exhausted":
raise ValueError("Manifest contains pages after terminal response")
params = entry["params"]
if entry.get("action") != ACTION or params.get("raw") is not False or (type(params.get("item_show_type")) is not int or params["item_show_type"] != tab):
raise ValueError("Keep the same explicit content tab and raw=false")
if set(params) - {"username", "raw", "item_show_type", "offset", "page_size"}:
raise ValueError("Unexpected parameters")
account = params["username"]
if not isinstance(account, str) or not account.startswith("gh_"):
raise ValueError("This helper uses the account's verified gh_ username")
if username is None:
username = account
if account != username:
raise ValueError("Mixed account or old state belongs to another account")
if index == 0:
if checkpoint is None and params.get("offset") not in (None, ""):
raise ValueError("The first history chunk starts at the beginning")
if checkpoint is not None:
resume = checkpoint["resume_params"]
if any(params.get(field) != resume.get(field) for field in ("username", "raw", "item_show_type")) or (params.get("offset") or "") != (resume.get("offset") or ""):
raise ValueError("First page does not match the saved history checkpoint")
if index > 0 and params.get("offset") != expected:
raise ValueError("Broken offset chain")
current_time = stamp(entry["collected_at"])
if last_time and current_time < last_time:
raise ValueError("Manifest times must be chronological")
last_time = current_time
http = entry["http_status"]
if type(http) is not int or not 100 <= http <= 599:
raise ValueError("Record the actual integer HTTP status")
path = manifest_path.parent / entry["response_file"]
raw = path.read_bytes(); raw_pages.append(raw)
result = json.loads(raw)
page = {"page": index + 1, "params": params, "collected_at": entry["collected_at"], "http_status": http,
"source": str(path), "sha256": hashlib.sha256(raw).hexdigest()}
pages.append(page)
if http != 200:
error = result.get("error", {})
if not isinstance(error, dict) or not isinstance(error.get("code"), str) or not error["code"]:
raise ValueError("Expected gateway error envelope")
page.update(error_code=error["code"], request_id=error.get("request_id"))
stop = "gateway_failed"
continue
if result.get("action") != ACTION or result.get("status") != "succeeded":
raise ValueError("Wrong action or unsuccessful response")
request = result.get("request_id")
if not isinstance(request, str) or not request.strip() or request in request_ids:
raise ValueError("Missing/repeated request ID")
request_ids.add(request); page["request_id"] = request
replayed = request in processed
signature = {"sha256": page["sha256"], "params": params, "collected_at": entry["collected_at"]}
if replayed and processed[request] != signature:
raise ValueError("Processed request was changed")
if not replayed and watermark and current_time < watermark:
raise ValueError("Do not apply older unseen observations")
page["replayed"] = replayed
data = result.get("data")
if not isinstance(data, dict) or data.get("biz_username") != username or not isinstance(data.get("articles"), list):
raise ValueError("Expected simplified article list for the same account")
for article in data["articles"]:
k = key(article)
if not isinstance(article.get("title"), str) or not isinstance(article.get("url"), str) or not article["url"]:
raise ValueError("Article requires title and URL")
for field in metadata:
if article.get(field) is not None and (isinstance(article[field], bool) or not isinstance(article[field], (str, int))):
raise ValueError("Unexpected article field type")
values = {field: article.get(field) for field in metadata}
observations.append({"article_key": k, "page": index + 1, "request_id": request, "article": article})
observed.add(k)
if replayed:
if k not in records:
raise ValueError("Processed request refers to a missing stored article")
continue
prior = records.get(k)
if prior is None:
new.add(k)
elif k in initial and any(prior.get(field) != values[field] for field in metadata):
changed.add(k)
record = {"app_msg_id": number(article["app_msg_id"]), "idx": number(article["idx"]), **values,
"first_seen_at": prior["first_seen_at"] if prior else entry["collected_at"],
"last_seen_at": entry["collected_at"], "last_request_id": request}
records[k] = record
if not replayed:
processed[request] = signature
state["last_collected_at"] = entry["collected_at"]
watermark = current_time
page["returned_objects"] = len(data["articles"])
end, cursor = data.get("is_end"), data.get("next_offset")
if type(end) not in (bool, int) or end not in (0, 1):
stop = "missing_end_flag"
elif end == 1:
stop = "provider_end"
elif not data["articles"]:
stop = "empty_page_before_end"
elif not isinstance(cursor, str) or not cursor:
stop = "missing_cursor"
elif cursor in cursors:
stop = "repeated_cursor"
else:
cursors.add(cursor); expected = cursor
resume_params = None
if stop == "saved_pages_exhausted":
resume_params = {"username": username, "raw": False, "item_show_type": tab, "offset": expected}
stop = "history_chunk_saved"
elif stop == "gateway_failed":
resume_params = dict(entries[-1]["params"])
next_request = {"action": ACTION, "params": resume_params} if resume_params is not None else None
state.update(username=username, articles=[records[k] for k in sorted(records)], processed_requests=processed)
target.mkdir(exist_ok=False)
def safe(v):
if v is None:
return ""
value = str(v)
return "'" + value if value.startswith(("=", "+", "-", "@", "\t", "\r", "\n")) else value
columns = ["app_msg_id", "idx", *metadata, "first_seen_at", "last_seen_at", "last_request_id"]
for name, keys in [("new-articles.csv", new), ("changed-articles.csv", changed)]:
with (target / name).open("x", encoding="utf-8-sig", newline="") as f:
writer = csv.DictWriter(f, fieldnames=columns); writer.writeheader()
writer.writerows({field: safe(records[k].get(field)) for field in columns} for k in sorted(keys))
(target / "state.json").write_text(json.dumps(state, ensure_ascii=False, indent=2), encoding="utf-8")
with (target / "observations.jsonl").open("x", encoding="utf-8") as f:
for item in observations:
f.write(json.dumps(item, ensure_ascii=False) + "\n")
for index, raw in enumerate(raw_pages):
(target / ("raw-page-%02d.json" % (index + 1))).write_bytes(raw)
report = {"username": username, "requested_tab": tab, "new_articles": len(new), "changed_known_articles": len(changed),
"observed_keys": len(observed), "stored_articles": len(records), "stop_reason": stop,
"complete_history": False, "visible_history_end_observed": stop == "provider_end", "publication_dates_inferred": False, "pages": pages}
(target / "coverage.json").write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
if next_request:
(target / "next-request.json").write_text(json.dumps(next_request, ensure_ascii=False, indent=2), encoding="utf-8")
print(json.dumps({"new": len(new), "changed": len(changed), "stop": stop}))
(target / "checkpoint.json").write_text(json.dumps({"version": 1, "username": username, "requested_tab": tab,
"stop_reason": stop, "resume_params": resume_params, "seen_next_offsets": sorted(cursors), "state_file": "state.json",
"prior_package": previous_package, "warning": "A cursor is not a permanent checkpoint; preserve all chunks and restart from page one if invalid"}, ensure_ascii=False, indent=2), encoding="utf-8")

checkpoint.json records the next parameters, the previous chunk, the ledger of seen cursors and the stop reason. The cursor ledger catches a cursor that returns itself and a cursor cycle across different chunks; the explicit --restart flag begins a new cursor sequence. Read the stop reasons as follows:

Stop reasonMeaningNext request
history_chunk_savedMore history remains to inspect; the backfill is not complete.Written to next-request.json
provider_endThe visible sequence ended. provider_end does not prove access to removed or private history.None
missing_cursor, repeated_cursor, missing_end_flagThe cursor is missing or repeated, or is_end is malformed. Investigate instead of jumping forward.None

The exported coverage.json never labels the archive “complete history.”

On a gateway failure, wechat_history.py keeps the successfully parsed preceding pages, and checkpoint.json keeps the failed request’s exact params. The saved params are a recovery proposal, not an automatic retry and not a guarantee of no charge. Check the error and usage, and approve any additional spending before running the request again. Handle a network timeout that has no saved error body outside the parser; never invent a successful or empty page.

If the platform rejects an old cursor:

  1. Send a fresh page-one request with raw=false and save the actual response and log.
  2. Run python3 wechat_history.py history-002 restart-pages.json history-003 --restart.

The restart keeps existing article identities and first-seen times and resets only the pagination position; the restart does not erase old history or reuse the rejected cursor. Replays of already processed requests are still hash-checked. A changed title for an existing article key is tracked as a changed article, separately from a new article.

For daily checks, switch to python3 wechat_sync.py history-003/state.json today-pages.json daily-001 from the incremental guide. The first daily request omits offset; the daily check does not continue checkpoint.json. Keep the history coverage status next to the daily report, especially if you stopped the initial backfill at a budget cap. Select only specific new URLs for separately billed body reads. Raw time values stay raw; first-seen time is not publication time.

Estimate list cost as planned pages multiplied by the current list price on the pricing page. wechat_history.py processes up to 20 saved pages per chunk and makes no retrieval requests; continue with another chunk for a larger history. Record each chunk’s actual scope and stop reason for the next continuation.

Identifier precision prerequisite

Unquoted JSON numbers decoded through float64 can lose precision above 9007199254740991 before wechat_history.py reads the file. wechat_history.py rejects any unquoted numeric ID above 9007199254740991. IDs encoded as strings in the response stay exact. Do not “fix” a rejected numeric ID by wrapping the rounded value in quotes: stop the export and keep request_id for investigation. Python’s large integers and spreadsheet text formatting cannot restore digits already rounded during JSON decoding.

Apply the same checkpoint rules to one other content tab

wechat_history.py accepts an explicit item_show_type of 0 (articles), 5 (videos), 7 (audio), or 8 (image-text). wechat_history.py reads the tab from the first recorded request and locks that tab for the manifest, stored state, continuation, and restart. Keep a separate chunk chain per account and tab. Existing article-tab state stays compatible, but article-tab state cannot seed a video run. The daily-sync helper wechat_sync.py still accepts article tab 0 only.

The output files keep the historical names new-articles.csv, changed-articles.csv, and state.articles for compatibility. For a nonzero tab, those rows hold the tab’s returned post metadata rather than classic article bodies. The original item objects, including item_show_type, msg_type, and cover, stay in observations.jsonl and the raw page files. Do not infer a downloadable video or audio asset from a post URL, and do not count cover images as all images in a post. Nonzero content tabs follow the same manifest tab-locking and continuation rules in wechat_history.py; verify the returned item structure against your first saved media-tab response.

For an editorial subset, filter by within-batch headline position, not by page order or app_msg_id alone.