# wechat-rust-sdk

**Repository Path**: clawbrain/wechat-rust-sdk

## Basic Information

- **Project Name**: wechat-rust-sdk
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-25
- **Last Updated**: 2026-03-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# wechat-rust-sdk

Rust SDK for Weixin OpenClaw channel API (`@tencent-weixin/openclaw-weixin`).

## Features

- Core API:
  - `getUpdates`
  - `sendMessage`
  - `getUploadUrl`
  - `getConfig`
  - `sendTyping`
- QR login flow:
  - `start_qr_login`
  - `login_with_qr_auto` (auto poll / auto refresh / optional credential persist)
- Typing support:
  - `start_typing_guard`
  - `poll_and_process_with_typing`
- Media support (local file):
  - `send_image_file`
  - `send_video_file`
  - `send_attachment_file`
  - `send_media_file_auto`
- Inbound media fetch (image/file):
  - `download_media_item_to_temp`
  - `download_message_media_to_temp`
- Inbound image fetch as base64:
  - `download_image_item_as_base64`
  - `download_message_image_as_base64`

## Install

```toml
[dependencies]
wechat-rust-sdk = { path = "." }
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
```

## Quick Start

```rust
use wechat_rust_sdk::{Client, GetUpdatesReq};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = Client::builder("https://ilinkai.weixin.qq.com/")
        .token("your-token")
        .build()?;

    let updates = client
        .get_updates(GetUpdatesReq {
            get_updates_buf: Some(String::new()),
            ..Default::default()
        })
        .await?;

    println!("ret={:?}, msgs={:?}", updates.ret, updates.msgs.as_ref().map(|v| v.len()));
    Ok(())
}
```

## Examples

### 1) Basic API example

```bash
WECHAT_TOKEN="your-token" \
cargo run --example basic
```

Optional media send:

```bash
WECHAT_TOKEN="your-token" \
WECHAT_TO_USER_ID="target-user-id" \
WECHAT_MEDIA_FILE="/absolute/path/to/file" \
cargo run --example basic
```

### 2) Echo bot (QR login + typing + media echo)

- Example file: `examples/echobot.rs`
- Behavior:
  - If no `WECHAT_TOKEN`, starts QR login automatically
  - Replies text messages
  - For media messages, replies text `我收到：文件` and forwards the original media item

Run:

```bash
cargo run --example echobot
```

Use existing token:

```bash
WECHAT_TOKEN="your-token" \
cargo run --example echobot
```

## Environment Variables

- `WECHAT_BASE_URL` (optional)
  - default: `https://ilinkai.weixin.qq.com/`
- `WECHAT_TOKEN` (optional for `echobot`, required for most direct API calls)
- `WECHAT_TO_USER_ID` (optional, for `basic` send)
- `WECHAT_TEXT` (optional, for `basic` text send)
- `WECHAT_MEDIA_FILE` (optional, for `basic` media send)

## Endpoint Mapping

- `Client::get_updates` -> `POST ilink/bot/getupdates`
- `Client::send_message` -> `POST ilink/bot/sendmessage`
- `Client::get_upload_url` -> `POST ilink/bot/getuploadurl`
- `Client::get_config` -> `POST ilink/bot/getconfig`
- `Client::send_typing` -> `POST ilink/bot/sendtyping`

## Notes

- `send_message` now checks business-level `ret/errcode` in response body (not only HTTP status).
- `get_updates` keeps JS parity on timeout: returns empty success result for retry.