Expand description
Connect to WeChat, authenticate, synchronize and submit messages with NativeClient.
Most server operations are methods on NativeClient, rather than free
functions in this crate’s Functions list. AccountState holds accepted
credentials; transfer it once into NativeClient::from_account. Account
operations then share that owner. It is secret data, not an API access token.
| Task | Start here |
|---|---|
| QR login | NativeClient::start_qr_login, NativeClient::poll_login, NativeClient::complete_login |
| Receive a sync page | NativeClient::sync, wire::decode_add_message |
| Send text | NativeClient::send_text, TextSendResult |
| Contacts and rooms | NativeClient::lookup_contacts, NativeClient::lookup_room |
| Attachments | media, media_send, NativeClient::send_file |
| Logout and shutdown | NativeClient::logout, NativeClient::shutdown, and _blocking forms of both |
| Classify a failure | ServiceRejected, is_session_rejected, AccountInterrupted, NativeRequestNotSubmitted |
| Low-level encoding | wire, protobuf |
§Send one text message
After an approved login, call the client method with the recipient’s exact WeChat username. Persist the task ID, timestamp and intended operation in your application’s recovery record before submission. A client ID is not a server guarantee against duplicate sends.
use wechat_protocol::{wire, NativeClient, TextSendOptions, TextSendResult};
async fn send_once(
client: &NativeClient,
recipient: &str,
text: &str,
task_id: &str,
created_at: u32,
) -> anyhow::Result<TextSendResult> {
let client_id = wire::client_message_id(task_id.as_bytes());
anyhow::ensure!(client_id != 0, "Choose another task ID");
client.send_text(recipient, text, TextSendOptions {
created_at,
client_message_id: client_id,
source: None,
}).await
}The source package includes runnable qr_login, send_text and sync_once
examples. They keep credentials in memory and perform no profile writes.
§Application responsibilities
The crate implements supported wire operations, transport authentication and response decoding. The embedding application owns credential storage, send intents, uncertainty handling, sync recovery and official-profile writeback. An accepted receipt establishes server acceptance, not recipient playback or completed local history. An error after submission must not cause a blind resend.
This library does not launch or load the official client. Peer responses pass pinned MMTLS signature and record authentication before business decode. Account-owned requests run blocking transport work on Tokio’s blocking pool. Login bootstrap and remaining low-level operations are blocking and require a blocking worker in async applications.
§Errors
Functions return anyhow::Error. Branch on the types it carries rather than
on message text:
ServiceRejectedholds theServiceand the non-zero code of a verified response.is_session_rejectedis true when the account needs a new login or renewal.AccountInterruptedsays why the account owner ended a request or a notification wait: stopped, transferred, or superseded by a renewal.NativeRequestNotSubmittedsays nothing was handed to transport. An interruption without it has an unknown outcome.
§Blocking embedders
Applications that run their own blocking workers need no Tokio runtime:
use NativeClient::request_blocking,
NativeClient::open_push_connection_blocking,
NativeClient::renew_session_blocking, NativeClient::logout_blocking,
PendingLogout::submit_blocking and NativeClient::shutdown_blocking.
Re-exports§
pub use openim::OpenImContact;pub use openim::OpenImServiceError;pub use crate::wire::AddMessage;pub use crate::wire::AvatarBytes;pub use crate::wire::ContactLookup;pub use crate::wire::ContactRecord;pub use crate::wire::Heartbeat;pub use crate::wire::InitContactPage;pub use crate::wire::RoomMember;pub use crate::wire::RoomRoster;pub use crate::wire::SyncBatch;pub use crate::wire::SyncCommand;pub use crate::wire::TextSendResult;pub use crate::wire::VoiceChunk;
Modules§
- business
- Business encryption is separate from authenticated MMTLS records.
- calls
- Call signaling codecs, authenticated host routes and media packet transforms.
- contact_
sync - Linux 4.1.13.26 contact stream (CGI8674). This stream has its own
rs_config/sync_11cursor; the message SyncKey is only request context. - crypto
- file_
upload - File-upload message reservation. This authenticated request can affect the account’s message state; callers must persist its receipt and never retry an uncertain response automatically.
- media
- Bounded native CDN transport. This uses the observed HTTP carrier on port 443, not HTTPS. Media encryption and advertised size/digests are checked separately.
- media_
send - Final media-message metadata. CDN upload and message submission are separate steps; persist source bytes, generated keys and intent before either step.
- mmtls
- Fresh pinned MMTLS handshake and authenticated shortlink exchange.
- openim
- Read one exact OpenIM contact through the supported native contact operation.
- protobuf
- Bounded numbered protobuf primitives. Unknown fields and full u64 values survive.
- push
- Persistent authenticated incoming notifications. The outer longlink command is distinct from the encrypted business CGI: heartbeat 238/518, sync 121/138.
- quote_
send - Quoted app-message metadata. Callers resolve the selected message and persist this reference and the final XML before submitting a send attempt.
- silk
- Bounded independent SILK SDK wrapper. Public source/license pins are under vendor/silk; no WeChat codec library is linked or loaded.
- wire
- Typed numbered business messages for the supported native profile.
Structs§
- Account
Identity - Account
Lease - Cheap authority check for account workers. It carries no credentials and becomes invalid on shutdown or any accepted credential renewal. It cannot replace the final submission guard on an authenticated signaling request.
- Account
Persistence Failed - A verified response could not commit its account update. The response may still be retained independently; this error never authorizes resubmission.
- Account
Push Connection - Persistent account connection for callers that already own blocking workers. Requests and notification waits use the same account admission and handoff barriers as ordinary operations. Reconnect after a credential generation changes; an old authenticated socket cannot adopt newer credentials.
- Account
Request - A single logical operation borrowing this client’s temporary request state. It is not an account owner and cannot outlive request_blocking. No operation accepts an independently mutable AccountState. Use ordinary async client methods unless the embedding application already owns a blocking worker.
- Account
State - Accepted credentials. Serialize only into the service’s encrypted state vault.
- Account
Status - Non-secret account lifecycle information. Credentials require an explicit export; status/debug output must never contain an AccountState.
- Auth
Snapshot - Raw accepted auth sections, retained only inside the encrypted account state. The update mask describes native application gates; presence alone does not mean an optional section changed active account credentials.
- Device
Profile - Group
Detail - Group
Member Result - Group
Metadata Page - Group
Mutation Reply - Group
Rpc - Login
Attempt - Logout
Reply - Message
Recall - Message
Recall Reply - Metadata
Reply - Native
Client - Native account client and login bootstrap for supported WeChat operations.
- Native
Options - Native
Request NotSubmitted - The operation stopped before business bytes were handed to transport. This marker is never attached to a timeout, rejected reply or post-handoff fence.
- Pending
Logout - One reserved terminal operation. Reservation stops account admission without sending anything. An embedding daemon can commit local logout inhibition before consuming this token to submit its optional remote logout. Dropping the token leaves the account stopped and sends no request.
- Service
Rejected - A verified response carried a non-zero service code. The request reached the service, so this error never shows that an operation was not submitted.
- Session
Read Notification - Session
Read Reply - Text
Send Options - Correlation values must be recorded with the application’s send intent before submission. Neither a task ID nor a transport error authorizes a blind retry.
Enums§
- Account
Interrupted - Why the account owner ended a request or a notification wait. This says
nothing about whether bytes were sent; check
NativeRequestNotSubmittedfor that. - Account
Lifecycle - Group
Mutation - Login
Status - Service
- The response boundary that reported a non-zero service code.
Constants§
Traits§
- Account
Persistence - Persist an accepted account update before it becomes visible to other client operations. Implementations store data only: they must not call back into the client, perform network operations, or implement authentication/retry policy. A failed write leaves in-memory state unchanged and never retries a request.
Functions§
- contact_
notification_ request - Direct contact writes use the official full-contact oplog shape. Fetch a current record first; change only the mute bit and preserve all other bytes.
- contact_
pinning_ requests - Ordinary Linux pin/unpin copies the complete contact, changes primary bit 0x800, and sends ModContact through oplog2. The secondary mask is a uint64. A folded group is removed from its message box in a preceding oplog74 step.
- controlled_
contact_ fields - Extract only the proved field-control IDs. Version ordering is deliberately not guessed: callers preserve these fields and retain the unresolved update.
- decode_
group_ detail - decode_
group_ inventory - decode_
group_ mutation - group_
detail_ request - group_
inventory_ request - group_
mutation_ requests - Steps are separate requests. An uncertain step must stop the entire flow. A known cleanup rejection can be retained while a later quit is attempted.
- is_
retryable_ login_ poll_ error - Polling an issued login challenge is repeatable. This does not authorize retrying QR creation, credential exchange, sends or rejected authentication.
- is_
session_ rejected - True when the error shows that the service no longer accepts the account’s
session: a
ServiceRejectedfor whichServiceRejected::is_session_rejectedholds, or anOpenImServiceErrorwith the same code. - login_
lan_ error_ reason - observed_
created_ group - Recover a valid create identity even when another success field is malformed. This is evidence for review, never permission to repeat the creation.
- ordinary_
identity