From 91cc7575136e5a5e3eeb3c27a25fd26dddac5bda Mon Sep 17 00:00:00 2001
From: ludis <service@ldsun.com>
Date: Tue, 30 Jun 2026 06:23:24 -0400
Subject: [PATCH] docs: clarify weixin media voice behavior

---
 README.md       | 22 ++++++++++++++++++++++
 README.zh_CN.md | 18 ++++++++++++++++++
 2 files changed, 40 insertions(+)

diff --git a/README.md b/README.md
index 05ad188..5f1bf86 100644
--- a/README.md
+++ b/README.md
@@ -134,6 +134,28 @@ All endpoints use `POST` with JSON request and response bodies. Common request h
 | getConfig | `getconfig` | Get account config (typing ticket, etc.) |
 | sendTyping | `sendtyping` | Send/cancel typing status indicator |
 
+### Outbound media notes
+
+The current outbound media helper routes local files by MIME type:
+
+- `video/*` -> video message
+- `image/*` -> image message
+- all other MIME types, including `audio/*`, -> file attachment
+
+Although the wire protocol includes `UploadMediaType.VOICE` and
+`MessageItemType.VOICE`, this package does not currently expose a public
+`sendVoice` helper for native WeChat voice bubbles. If you need voice-bubble
+delivery, verify the required account permissions, media upload type, codec,
+message item shape, and real client rendering with Tencent/iLink first.
+
+For media sends, callers should check both:
+
+1. the business response (`ret` / `errmsg`), and
+2. the actual WeChat client rendering.
+
+An HTTP 200 or `sendmessage` acceptance does not always guarantee that a media
+item is visible as the intended client-side message type.
+
 ### getUpdates
 
 Long-polling endpoint. The server responds when new messages arrive or on timeout.
diff --git a/README.zh_CN.md b/README.zh_CN.md
index 9322541..c5aa7b6 100644
--- a/README.zh_CN.md
+++ b/README.zh_CN.md
@@ -130,6 +130,24 @@ openclaw config set session.dmScope per-account-channel-peer
 | getConfig | `getconfig` | 获取账号配置（typing ticket 等） |
 | sendTyping | `sendtyping` | 发送/取消输入状态指示 |
 
+### 出站媒体说明
+
+当前出站媒体 helper 按本地文件 MIME 类型路由：
+
+- `video/*` -> 视频消息
+- `image/*` -> 图片消息
+- 其他所有 MIME 类型，包括 `audio/*` -> 文件附件
+
+虽然底层协议包含 `UploadMediaType.VOICE` 和 `MessageItemType.VOICE`，但本包当前没有公开的
+`sendVoice` helper 用于发送微信原生语音气泡。如果需要语音气泡投递，请先向腾讯/iLink 确认所需账号权限、媒体上传类型、编码格式、消息 item 结构和真实客户端展示效果。
+
+发送媒体消息时，调用方应同时检查：
+
+1. 业务响应（`ret` / `errmsg`）
+2. 微信客户端的实际展示效果
+
+HTTP 200 或 `sendmessage` 被接受，并不一定保证媒体消息会按预期客户端形态展示。
+
 ### getUpdates
 
 长轮询接口。服务端在有新消息或超时后返回。