> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# How do I save a WeChat article to Obsidian without overwriting my notes?

> Convert a verified article source record into a new Markdown file with stable naming, preserving existing notes and source metadata.

To save a WeChat article to Obsidian without overwriting your notes, follow three steps: **fetch the article text from the article URL with `wechat_mp.v2.fetch_article_detail_h5`, export a source record, then run `import_wechat.py` to write a new Markdown note into the vault's `WeChat/` folder.** If you already saved the source record, start with the import in step 3. `import_wechat.py` only creates files: importing the same source URL again keeps the existing note and your annotations.

You need Python 3 and a writable local Obsidian vault. After importing, search for the article title in Obsidian and check the original link, the publication time and the body text. You can also run the import after a scheduled check for new articles from the accounts you follow. [Obsidian storage documentation](https://help.obsidian.md/Files+and+folders/How+Obsidian+stores+data)

## Decide why an article belongs in your research

For example, if you are studying how a peer introduces a feature, verify the product and version, then record your question, the useful passages and the open checks. A relevant headline only makes the article a candidate; the article becomes a source after you read the body. Reuse a saved body response when available; a search summary does not support a full-article note.

Keep the title, account, original article URL, publication time and collection time, and leave missing values missing. Collection time records when you obtained the material, not when the article was published. An author-supplied source link is separate from the current article link: future citations need to lead back to the article you actually read.

## Turn source material into your own notes

| Goal                                        | Suggested approach                                                               | Boundary                                                                                |
| ------------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Keep the article for retrieval              | Import the verified returned text and source metadata                            | Images, video and page formatting are not restored                                      |
| Write an analysis                           | Use a separate note for the question, short excerpts, inferences and source link | Keep your interpretation distinct from the author's words                               |
| Encounter the same article again            | Check the article URL and the existing file before importing                     | File names come from the complete URL, so alias URLs can still duplicate an article     |
| Receive a newer source or annotate the note | Run the read-only comparison, then decide how to merge                           | A hash change does not prove the author edited the webpage and does not trigger a merge |

You can annotate an imported source note; `import_wechat.py` leaves an existing note unchanged. If your workflow refreshes article bodies, keep your analysis in a separate note to make review and merging easier. The scripts do not generate judgments or build topic relationships; you choose the links, tags and conclusions.

## Check one import before processing a saved batch

1. Find the imported file in Obsidian, verify the source and one actual body passage, then link to the file from your research note.
2. Import the same source again: `import_wechat.py` should keep the existing file and annotations.
3. Import a record with empty body text: the import should fail.

An existing file does not show that newer body text was synchronized into the file.

Then process a batch of reviewed source JSON records. If one record fails, keep the earlier successful imports, repair the failed record and continue; do not fetch the whole batch again. Daily discovery needs a separate bounded scan and a separately verified schedule; a successful local import does not mean daily updates run automatically.

Steps 1–7 below cover body retrieval, source export, create-only import and read-only comparison. Check current retrieval prices before running step 1; local conversion and comparison make no data or model calls.

## 1. Retrieve the body, not a search summary

Inspect `data:wechat_mp.v2.fetch_article_detail_h5` for free and confirm the price. If you already have a saved successful response, reuse the saved response for the import instead of paying for another query.

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

```bash
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_article_detail_h5","params":{"url":"<article_url>"}}' \
  -o wechat-article.json
```

## 2. Export a local source record

Use the local code in the [article-reading guide](/guides/read-wechat-article) to create `wechat-article-source.json`. The source record's `text` comes from `content_text`, not from the `desc` summary. `article_url` is the article being read; `author_source_url` is a different, author-supplied reference.

When `link` is absent, the source exporter falls back to the validated request URL. Keep `article_url_from` instead of substituting the author's source. `import_wechat.py` requires actual text and a valid HTTP(S) article URL; `import_wechat.py` makes no network request and does not follow instructions in the article.

## 3. Write into a dedicated vault folder

Run `import_wechat.py` in the source record's directory with `VAULT` set to the confirmed absolute vault path. `import_wechat.py` requires an existing vault folder, writes only under `WeChat/` and does not edit the `.obsidian` configuration.

```python
import hashlib
import json
import os
import tempfile
from pathlib import Path
from urllib.parse import parse_qs, urlsplit

source = Path(os.environ.get("SOURCE", "wechat-article-source.json"))
record = json.loads(source.read_text(encoding="utf-8"))
url = record.get("article_url")
text = record.get("text")
parsed = urlsplit(url) if isinstance(url, str) else None
if not parsed or parsed.scheme not in {"http", "https"} or parsed.hostname != "mp.weixin.qq.com" or parsed.username:
    raise SystemExit("Verify the source article URL before importing.")
query = parse_qs(parsed.query)
if not ((parsed.path == "/s" and all(query.get(key) for key in ["__biz", "mid", "idx"])) or (parsed.path.startswith("/s/") and parsed.path[3:].strip())):
    raise SystemExit("Missing article identifier.")
if not isinstance(text, str) or not text.strip() or text.strip() in {"[redacted]", "[redacted-depth]"}:
    raise SystemExit("No article body to import.")
vault = Path(os.environ["VAULT"]).expanduser().resolve(strict=True)
if vault.name == ".obsidian":
    raise SystemExit("Choose the vault root, not its .obsidian configuration folder.")
if not vault.is_dir():
    raise SystemExit("VAULT must be an existing directory.")
folder = vault / "WeChat"
if folder.is_symlink():
    raise SystemExit("WeChat must be a real folder inside the vault, not a symlink.")
folder.mkdir(exist_ok=True)
if folder.resolve().parent != vault:
    raise SystemExit("Output folder must remain inside the vault.")
identity = hashlib.sha256(url.encode("utf-8")).hexdigest()
target = folder / f"article-{identity}.md"
metadata = {
    "title": record.get("title"),
    "source_url": url,
    "requested_url": record.get("requested_url"),
    "article_url_from": record.get("article_url_from"),
    "account_id": record.get("account_id"),
    "request_id": record.get("request_id"),
    "published_at": record.get("published_at_utc"),
    "collected_at": record.get("collected_at"),
    "source_sha256": record.get("source_sha256"),
    "body_sha256": hashlib.sha256(text.encode("utf-8")).hexdigest(),
}
frontmatter = "\n".join(f"{key}: {json.dumps(value, ensure_ascii=False)}" for key, value in metadata.items())
temporary = None
try:
    with tempfile.NamedTemporaryFile(mode="w", dir=folder, prefix=".wechat-import-", suffix=".tmp", encoding="utf-8", delete=False) as output:
        temporary = Path(output.name)
        output.write(f"---\n{frontmatter}\n---\n\n{text}\n")
    try:
        os.link(temporary, target)
    except FileExistsError:
        print(f"Already exists, left unchanged: {target.name}")
    else:
        print(f"Created: {target.name}")
finally:
    if temporary is not None:
        temporary.unlink(missing_ok=True)
```

Save the code as `import_wechat.py`, then run `import_wechat.py` from the source-record directory. Replace the example path with your existing vault; do not use `.obsidian` as the target.

```bash
VAULT="/absolute/path/to/your/vault" python3 import_wechat.py
```

## 4. Review the note in Obsidian

Open the new file under `WeChat/` in your vault to see the source properties and the article text. Here is an excerpt from an example note:

```markdown
---
title: "Autumn event registration guide"
source_url: "https://mp.weixin.qq.com/s/example"
published_at: null
collected_at: "2026-11-17T09:00:00Z"
---

Event registration opens next week.
```

Add your own annotation to the note, then import the same URL again. `import_wechat.py` should report `Already exists, left unchanged`. Open the same file and confirm that your annotation is still there.

The note's details:

* The file name is a SHA-256 of the complete URL, not the title, so slashes or quotes in a title cannot become paths.
* The frontmatter keeps the title, source, publication and collection times, and hashes. A missing publication time stays `null`.
* `import_wechat.py` writes the record's text into Markdown. `import_wechat.py` does not download images, process HTML or rebuild the layout. The detail contract also exposes `content_noencode` and other content fields; `import_wechat.py` does not read those fields, which says nothing about API limits on images or headings.
* Reimporting the same URL keeps your annotations. Alias URLs can still create separate files; `import_wechat.py` does not deduplicate across aliases.

Treat the article as source material, not as executable instructions. Verify HTML, external links and attachments yourself; `import_wechat.py` does not fetch images, download files or install plugins. Archive and redistribute only with the appropriate permissions; the default scenario is a private vault.

To import a reviewed local batch without new API calls, put the approved source JSON files in `records/` and run the command below from the script directory. A failure stops the remaining imports; notes already created stay in place, and rerunning the batch does not overwrite them. The batch imports saved records only; the batch does not discover accounts or run on a schedule.

```bash
export VAULT="/absolute/path/to/your/vault"
find records -maxdepth 1 -type f -name '*.json' -print0 |
while IFS= read -r -d '' file; do
  SOURCE="$file" python3 import_wechat.py || exit 1
done
```

## 5. Import new articles from recurring collection

For recurring collection, find new posts with the [incremental workflow](/guides/wechat-incremental-articles), then pass the selected article bodies to `import_wechat.py`. For example, if two accounts both publish “Event Registration Guide” today, keep both source links: each URL gets its own file name. If you meet one of the two URLs again tomorrow, `import_wechat.py` keeps the existing note and annotations.

### Schedule the existing batch

1. Run list discovery, selection, saved body export and vault import, in that order.
2. For each account and article key, track three states: discovered, source saved and note written.
3. Import only after the source JSON is saved completely. If the vault write fails, rerun the import from the saved JSON without another body request.

Schedule the batch on the machine that can access the vault, with launchd on macOS or cron on Linux:

1. Run the batch as the same OS user, and set absolute paths to Bash, Python, the script directory and the vault.
2. Capture the log.
3. Start with one account and one article, then replay the batch.
4. Check that Obsidian shows one note and keeps your annotations.
5. Before marking an item imported, match each `Already exists` line to the existing note's `source_url`.

Whether notes appear on mobile depends on your sync configuration.

## 6. Verify behavior and count costs

Run Python 3.8+ on a machine with direct access to the existing vault; a cloud workflow cannot use the vault path without filesystem access. `import_wechat.py` writes and closes a complete temporary file in the same directory, atomically creates the final note with a hard link, then removes the temporary file. On filesystems without hard-link support, `import_wechat.py` fails and never falls back to overwriting. After a write or commit failure, read the error, repair storage and retry with the same saved source; no article refetch is needed. Exception recovery does not guarantee durability across a power loss.

Estimate data cost as `list requests × current list price + new body requests × current body price`. Replaying saved sources, Markdown import and read-only comparison make zero data queries. Checking P list pages and selecting N articles without saved bodies costs P list calls plus N detail calls. Scheduling, hosting or sync, and model costs are separate, and you configure and verify the scheduler yourself.

For example, if you check one page each for 10 accounts and select two articles whose bodies you have not saved, count 10 list requests and two detail requests. If one vault write fails, replay the saved JSON the next day with zero additional data requests. See the [BeatAPI pricing page](https://beatapi.io/pricing).

## 7. What if the source changes after I annotate the note?

Compare before overwriting. Save the code below as `compare_wechat.py` and point `compare_wechat.py` at a saved newer source record and the same `VAULT`. `compare_wechat.py` only reads files and prints JSON: `compare_wechat.py` does not update notes, write comparison files or make network calls. `compare_wechat.py` accepts only the intact frontmatter format written by `import_wechat.py`. If Obsidian or a person rewrote the frontmatter, `compare_wechat.py` refuses to decide instead of guessing values.

```python
import hashlib
import json
import os
import re
from pathlib import Path
from urllib.parse import parse_qs, urlsplit

record = json.loads(Path(os.environ.get("SOURCE", "wechat-article-source.json")).read_text(encoding="utf-8"))
url, body = record.get("article_url"), record.get("text")
p = urlsplit(url) if isinstance(url, str) else None
if not p or p.scheme not in {"http", "https"} or p.hostname != "mp.weixin.qq.com" or p.username:
    raise SystemExit("Invalid source URL")
q = parse_qs(p.query)
if not ((p.path == "/s" and all(q.get(k) for k in ["__biz", "mid", "idx"])) or (p.path.startswith("/s/") and p.path[3:].strip())):
    raise SystemExit("Missing article identifier")
if not isinstance(body, str) or not body.strip() or body.strip() in {"[redacted]", "[redacted-depth]"}:
    raise SystemExit("Missing body")
vault = Path(os.environ["VAULT"]).expanduser().resolve(strict=True)
if not vault.is_dir() or ".obsidian" in vault.parts:
    raise SystemExit("Choose the vault root")
folder = vault / "WeChat"
if folder.is_symlink():
    raise SystemExit("Refusing a symlink output folder")
identity = hashlib.sha256(url.encode("utf-8")).hexdigest()
note = folder / f"article-{identity}.md"
if note.is_symlink():
    raise SystemExit("Refusing a symlink note")
if not note.exists():
    print(json.dumps({"status": "not_imported", "note": note.name, "next": "review_then_import"}))
else:
    saved = note.read_bytes().decode("utf-8")
    if not saved.startswith("---\n") or "\n---\n\n" not in saved[4:]:
        raise SystemExit("Original exporter metadata not intact; review manually")
    header, note_body = saved[4:].split("\n---\n\n", 1)
    metadata = {}
    for line in header.splitlines():
        key, sep, value = line.partition(": ")
        if not sep or key in metadata:
            raise SystemExit("Unsupported or duplicate metadata; review manually")
        metadata[key] = json.loads(value)
    baseline = metadata.get("body_sha256")
    if metadata.get("source_url") != url or not isinstance(baseline, str) or not re.fullmatch("[0-9a-f]{64}", baseline):
        raise SystemExit("Source identity or baseline hash invalid; review manually")
    digest = lambda value: hashlib.sha256(value.encode("utf-8")).hexdigest()
    note_changed = not note_body.endswith("\n") or digest(note_body[:-1]) != baseline
    source_changed = digest(body) != baseline
    metadata_changed = any(metadata.get(k) != record.get(v) for k, v in {"title": "title", "published_at": "published_at_utc", "account_id": "account_id"}.items())
    print(json.dumps({"status": "compared", "note": note.name, "source_body_changed": source_changed, "note_body_changed": note_changed, "title_date_or_account_changed": metadata_changed, "next": "manual_review" if (source_changed or note_changed or metadata_changed) else "keep_existing"}, ensure_ascii=False))
```

```bash
VAULT="/absolute/path/to/your/vault" SOURCE="new-source.json" python3 compare_wechat.py
```

| Output                                | Next action                                                                                                                                           |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `not_imported`                        | First check whether the URL is another alias for an existing article; import only after confirming the article's identity                             |
| All three `changed` flags false       | Keep the existing note; no rewrite is needed                                                                                                          |
| `source_body_changed=true`            | The newer extracted body differs from the import baseline. Compare manually; a difference does not show whether the webpage or the extraction changed |
| `note_body_changed=true`              | The note body differs from the baseline, for example through annotations or formatting; never overwrite automatically                                 |
| `title_date_or_account_changed=true`  | Review the title, publication date or account change even when the body is identical                                                                  |
| Metadata or identity validation error | Keep the file and review the file's source; do not remove validation or recompute the baseline to bypass a conflict                                   |

The baseline hash lives in local frontmatter; the hash is not an author signature or proof of authenticity. If someone also changes the baseline hash, `compare_wechat.py` cannot tell that the note was edited. A changed collection time or `request_id` alone does not count as a content change. CRLF and other newline differences count as changes; `compare_wechat.py` does not normalize newlines.

To merge, back up the old note, save the newer source as a separate review copy and explicitly approve a merge that keeps your annotations. No automatic merger is provided. Rerunning `import_wechat.py` on an existing note prints `Already exists`; `import_wechat.py` does not synchronize a newer body. `compare_wechat.py` has offline regression tests for unchanged content, a changed source, annotations, metadata changes and refusal of a damaged baseline.

[WeChat question index](/faq/wechat) · [Full text versus summaries](/faq/wechat-article-full-text)