How to Build a Personal WeChat Bot with iLink and the JiLink Java SDK

Background and the new iLink Bot API

Historically, developers connected personal WeChat accounts to programs by reverse‑engineering the iPad protocol (e.g., WeChatPadPro) or by hooking the PC client and injecting DLLs. Those methods work but violate WeChat’s service agreement, carry a high risk of account bans, and break whenever the official client updates.

In March 2026 WeChat released the official ClawBot plugin that uses the iLink (智联) protocol. The endpoint is ilinkai.weixin.qq.com. Personal accounts can now legally access a Bot API that forwards user messages to a program and returns the program’s replies via a standard HTTP/JSON interface.

What is iLink?

iLink is a pure message channel:

It forwards incoming user messages to your service.

It delivers your service’s replies back to the user.

Key differences from the old reverse‑engineering solutions:

Legality : iLink is officially open with usage terms; old methods violate the agreement.

Ban risk : No ban risk under normal use; old methods have a very high risk.

Protocol stability : Server‑side API with version control; old methods break on any client update.

Interface : Simple HTTP/JSON; old methods simulate iPad/PC protocols.

Media support : Full support for text, image, voice (Silk + transcription), file, and video. Images are sent via CDN with AES‑128‑ECB encryption.

iLink does not store content or provide AI capabilities; developers must supply their own AI. Tencent may monitor connection types, content, and request frequency.

How iLink works

The protocol consists of three stages: QR‑code login, long‑polling for messages, and token‑based message replies. The sequence diagram below shows the flow.

Developer Program          iLink Server               WeChat User
    │                         │                         │
    │── GET get_bot_qrcode ─▶ │                         │
    │◀─ { qrcode, url } ────│                         │
    │                         │◀── User scans QR code ───│
    │─ GET qrcode_status ─▶│ (long‑poll)               │
    │◀─ { status: confirmed, bot_token, baseurl } ──│
    │                         │                         │
    │  Persist bot_token, use Bearer auth later │
    │─── POST getupdates ─▶ │                         │
    │   (hold ≤ 35 s)         │◀── User sends "Hello" ──│
    │◀─ { msgs, context_token, get_updates_buf } ──│
    │─── POST sendmessage ▶ │                         │
    │   (with context_token)│─── Push reply ─────────▶│

Three common pitfalls often cause failures:

Long‑poll cursor : The get_updates_buf field returned by getupdates acts like a database cursor. It must be sent back on the next request; otherwise the server will resend the same batch of messages.

Context token : Every incoming message includes a context_token. When replying, the same token must be returned; otherwise the reply is not routed to the correct conversation.

Random X-WECHAT-UIN header : Each request must include a freshly generated header. Generate a random uint32, convert it to a decimal string, then Base64‑encode it. Missing or static values cause the request to be rejected.

JiLink – a Java SDK for iLink

JiLink is a lightweight Java SDK that hides the three pitfalls above. Add the following Maven dependency (Java 17+ required):

<dependency>
    <groupId>io.github.pig-mesh.ai</groupId>
    <artifactId>ilink-wechat-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

The SDK has no third‑party dependencies; it uses only the JDK HttpClient and standard libraries.

Core API Overview

login(force?)

– QR‑code login; reuses existing credentials if available. onMessage(handler) – Register a callback to handle incoming messages. reply(msg, text) – Send a reply; the SDK automatically includes the required context_token. send(userId, text) – Proactively push a message (the user must have interacted with the bot before). sendTyping(userId) – Show “user is typing” indicator. stopTyping(userId) – Cancel the typing indicator. run() – Start the long‑polling main loop. stop() – Stop the bot.

The SDK internally manages context_token, the long‑poll cursor, typing tickets, and automatic re‑login, exposing only three clean verbs to developers: onMessage, reply, and run.

Minimal Echo Bot (≈20 lines)

import io.github.pigmesh.ai.ilink.WeixinBot;

public class EchoBot {
    public static void main(String[] args) {
        WeixinBot bot = new WeixinBot();
        // First run prints a QR‑code URL; scan with WeChat to log in
        bot.login();
        bot.onMessage(msg -> {
            System.out.printf("Received %s: %s%n", msg.getUserId(), msg.getText());
            // Show typing indicator before replying
            bot.sendTyping(msg.getUserId());
            // Reply; context_token is added automatically
            bot.reply(msg, "Echo: " + msg.getText());
        });
        // Start long‑polling loop
        bot.run();
    }
}

On first launch the SDK stores credentials at ~/.weixin-bot/credentials.json. If the session expires (error code -14), the SDK clears the file and triggers a fresh login.

Proactive Message Push

To send outbound notifications (e.g., alerts), use send(userId, text) after the user has sent at least one message so the SDK has cached the context_token:

// The user must have interacted with the bot before
bot.send("[email protected]", "Your K8s cluster has a crashed pod");

If you need to initiate a conversation with a new user, ask them to send a simple "Hi" first to obtain a context_token.

jilink‑tui – Terminal WeChat client

jilink‑tui is a companion terminal application built on top of JiLink. After starting the program, a QR‑code URL is printed; scanning logs you in. The UI shows recent conversations on the left and the message pane on the right. Arrow keys switch chats, and Enter sends text.

The synchronization is bidirectional: a message typed on the phone appears instantly in the terminal, the typing indicator lights up, and the bot’s reply is pushed back to the phone. No reverse‑engineering is involved.

Typical use cases

With iLink and JiLink you can build personal AI assistants, deployment‑alert bots, household group managers, CI/CD triggers, or bridges that forward WeChat messages to platforms such as Feishu or DingTalk—all while staying within the legal personal‑account scope.