Backend API Protocol

Back to detailed guide | 简体中文

This document covers every Weixin backend endpoint used by the plugin for QR login, lifecycle notifications, messaging, and media. The two QR login requests always use Tencent's fixed service. A backend selected by the account's post-login baseurl must implement the lifecycle, messaging, and media endpoints.

QR creation and all post-login endpoints use POST; QR status polling uses GET. All requests include:

Header	Description
iLink-App-Id	Plugin application ID
iLink-App-ClientVersion	Plugin version encoded as an unsigned integer
SKRouteTag	Optional configured route tag

POST requests additionally include Content-Type: application/json, AuthorizationType: ilink_bot_token, and a random base64-encoded X-WECHAT-UIN. Authenticated post-login requests also include Authorization: Bearer <bot-token>; QR status GET requests do not include these POST-specific headers.

Authenticated post-login POST bodies include base_info; QR creation does not. The message examples below omit it for readability.

{
  "base_info": {
    "channel_version": "<plugin version>",
    "bot_agent": "OpenClaw"
  }
}

bot_agent is for observability only. Its supported format and configuration are documented in the detailed guide.

Endpoint List

Method	Path	Description
POST	/ilink/bot/get_bot_qrcode?bot_type=3	Create a QR login session
GET	/ilink/bot/get_qrcode_status?qrcode=<opaque-id>	Poll QR login status; accepts optional verify_code
POST	/ilink/bot/msg/notifystart	Notify backend that the channel started
POST	/ilink/bot/msg/notifystop	Notify backend that the channel stopped
POST	/ilink/bot/getupdates	Long-poll for new messages
POST	/ilink/bot/sendmessage	Send a message (text/image/video/file)
POST	/ilink/bot/getuploadurl	Get CDN upload pre-signed parameters
POST	/ilink/bot/getconfig	Get account config (typing ticket, etc.)
POST	/ilink/bot/sendtyping	Send/cancel typing status

The first two rows describe the fixed QR login service. They are not sent to the account's post-login baseurl.

QR Login and Lifecycle

Create a QR session with:

POST /ilink/bot/get_bot_qrcode?bot_type=3
Content-Type: application/json

{
  "local_token_list": []
}

local_token_list contains up to 10 local bot_token values from the most recently registered accounts; it is empty when no local credentials exist. The backend uses the list to recognize bots already bound to this OpenClaw and may respond with binded_redirect. Every token in the list is sensitive; never put a real value in logs or examples.

The response contains an opaque qrcode identifier and qrcode_img_content, the URL rendered as the QR code. Poll GET /ilink/bot/get_qrcode_status?qrcode=<opaque-id> until it reaches a terminal state. The optional verify_code query parameter handles verification challenges.

Field	Type	Description
status	string	wait, scaned, need_verifycode, verify_code_blocked, expired, scaned_but_redirect, binded_redirect, or confirmed
bot_token	string?	Bot credential returned after confirmation
ilink_bot_id	string?	Required account ID after confirmation
baseurl	string?	Account API base URL
ilink_user_id	string?	ID of the user who scanned the QR code
redirect_host	string?	New polling host for scaned_but_redirect

After authentication, call /ilink/bot/msg/notifystart when the channel starts and /ilink/bot/msg/notifystop when it stops. Both receive the standard base_info body and return:

{
  "ret": 0,
  "errmsg": ""
}

QR identifiers, verification codes, bot tokens, account IDs, user IDs, and context tokens are sensitive. Never place real values in logs or examples.

getUpdates

Long-polling endpoint. The server responds when new messages arrive or on timeout.

Request body:

{
  "get_updates_buf": ""
}

Field	Type	Description
get_updates_buf	string	Sync cursor from the previous response; empty string for the first request

Response body:

{
  "ret": 0,
  "msgs": [],
  "get_updates_buf": "<new cursor>",
  "longpolling_timeout_ms": 35000
}

Field	Type	Description
ret	number	Return code, 0 = success
errcode	number?	Error code (e.g., -14 = stale token)
errmsg	string?	Error description
msgs	WeixinMessage[]	Message list (structure below)
get_updates_buf	string	New sync cursor to pass in the next request
longpolling_timeout_ms	number?	Server-suggested long-poll timeout for the next request (ms)

sendMessage

Send a message to a user.

Request body:

{
  "msg": {
    "to_user_id": "<target user ID>",
    "context_token": "<conversation context token>",
    "item_list": [
      {
        "type": 1,
        "text_item": { "text": "Hello" }
      }
    ]
  }
}

Response body:

{
  "ret": 0,
  "errmsg": ""
}

getUploadUrl

Get CDN upload pre-signed parameters. Call this endpoint before uploading a file; clients prefer upload_full_url and otherwise use upload_param. thumb_upload_param may be returned only when a thumbnail is requested. The current plugin always sends no_need_thumb: true, uploads only the original media, and neither requests nor uses thumbnail upload parameters.

Request body:

{
  "filekey": "<file identifier>",
  "media_type": 1,
  "to_user_id": "<target user ID>",
  "rawsize": 12345,
  "rawfilemd5": "<plaintext MD5>",
  "filesize": 12352,
  "no_need_thumb": true,
  "aeskey": "<32-character hex AES key>"
}

Field	Type	Description
filekey	string	Per-upload file identifier
media_type	number	1 = IMAGE, 2 = VIDEO, 3 = FILE, 4 = VOICE
to_user_id	string	Target user ID
rawsize	number	Original file plaintext size
rawfilemd5	string	Original file plaintext MD5
filesize	number	Ciphertext size after AES-128-ECB encryption
no_need_thumb	boolean?	Set true to omit thumbnail upload parameters
aeskey	string?	AES-128 key as 32 hexadecimal characters
thumb_rawsize	number?	Thumbnail plaintext size when a thumbnail is requested
thumb_rawfilemd5	string?	Thumbnail plaintext MD5 when requested
thumb_filesize	number?	Thumbnail ciphertext size when requested

Response body:

{
  "upload_param": "<original image upload encrypted parameters>",
  "upload_full_url": "https://cdn.example.test/upload",
  "thumb_upload_param": "<optional thumbnail upload parameters>"
}

Field	Type	Description
upload_param	string?	Parameters used to construct the CDN upload URL
upload_full_url	string?	Complete CDN upload URL; takes precedence over upload_param
thumb_upload_param	string?	Optional thumbnail upload parameters

getConfig

Get account configuration, including the typing ticket.

Request body:

{
  "ilink_user_id": "<user ID>",
  "context_token": "<optional, conversation context token>"
}

Response body:

{
  "ret": 0,
  "errmsg": "",
  "typing_ticket": "<base64-encoded typing ticket>"
}

sendTyping

Send or cancel the typing status indicator.

Request body:

{
  "ilink_user_id": "<user ID>",
  "typing_ticket": "<obtained from getConfig>",
  "status": 1
}

Field	Type	Description
status	number	1 = typing, 2 = cancel typing

Response body:

{
  "ret": 0,
  "errmsg": ""
}

Message Structure

WeixinMessage

Field	Type	Description
seq	number?	Message sequence number
message_id	string | number?	Unique integer message ID; getUpdates preserves integer tokens as exact strings
from_user_id	string?	Sender ID
to_user_id	string?	Receiver ID
client_id	string?	Client-generated message ID
create_time_ms	number?	Creation timestamp (ms)
update_time_ms	number?	Update timestamp (ms)
delete_time_ms	number?	Deletion timestamp (ms)
session_id	string?	Session ID
group_id	string?	Group ID
message_type	number?	1 = USER, 2 = BOT
message_state	number?	0 = NEW, 1 = GENERATING, 2 = FINISH
item_list	MessageItem[]?	Message content list
context_token	string?	Conversation context token, must be passed back when replying
run_id	string?	OpenClaw run ID for generated replies

getUpdates also preserves integer msg_id tokens as strings, including in referenced items. It leaves message text and other numeric fields unchanged. Replay dedupe and MessageSid accept exact decimal integer strings and legacy safe integer numbers; 42 and "42" keep the same existing key. Unsafe numeric IDs are not reliable identities and use the existing fallback chain instead. The account namespace, 24-hour replay TTL and persisted key format are unchanged.

MessageItem

Field	Type	Description
type	number	1 TEXT, 2 IMAGE, 3 VOICE, 4 FILE, 5 VIDEO, 11 TOOL_CALL_START, 12 TOOL_CALL_RESULT
create_time_ms	number?	Item creation timestamp
update_time_ms	number?	Item update timestamp
is_completed	boolean?	Whether a progress item is complete
msg_id	string?	Item message ID
text_item	{ text: string }?	Text content
image_item	ImageItem?	Image (with CDN reference and AES key)
voice_item	VoiceItem?	Voice (SILK encoded)
file_item	FileItem?	File attachment
video_item	VideoItem?	Video
ref_msg	RefMessage?	Referenced message
tool_call_start_item	{ tool_name?: string; tool_call_id?: string }?	Tool invocation metadata
tool_call_result_item	{ tool_name?: string; tool_call_id?: string; status?: string }?	Tool completion metadata

Nested Item Structures

Structure	Fields
RefMessage	message_item?: MessageItem, title?: string
ImageItem	media?: CDNMedia, thumb_media?: CDNMedia, aeskey?: string, url?: string, mid_size?: number, thumb_size?: number, thumb_height?: number, thumb_width?: number, hd_size?: number
VoiceItem	media?: CDNMedia, encode_type?: number, bits_per_sample?: number, sample_rate?: number, playtime?: number, text?: string
FileItem	media?: CDNMedia, file_name?: string, md5?: string, len?: string
VideoItem	media?: CDNMedia, video_size?: number, play_length?: number, video_md5?: string, thumb_media?: CDNMedia, thumb_size?: number, thumb_height?: number, thumb_width?: number
ToolCallStartItem	tool_name?: string, tool_call_id?: string
ToolCallResultItem	tool_name?: string, tool_call_id?: string, status?: string

CDN Media Reference (CDNMedia)

All media types (image/voice/file/video) are transferred via CDN using AES-128-ECB encryption:

Field	Type	Description
encrypt_query_param	string?	Encrypted parameters for CDN download/upload
aes_key	string?	Base64-encoded AES-128 key
encrypt_type	number?	Encryption metadata mode
full_url	string?	Complete download URL returned by the backend

CDN Upload Flow

1. Calculate the file's plaintext size, MD5, and ciphertext size after AES-128-ECB encryption
2. Call getUploadUrl with no_need_thumb: true
3. Prefer upload_full_url; otherwise construct the CDN URL from upload_param
4. Encrypt the original media with AES-128-ECB and POST it to the CDN URL as application/octet-stream
5. Read x-encrypted-param from the CDN response and use it as encrypt_query_param in the CDNMedia reference
6. Include the reference in the MessageItem and send

The protocol also defines thumb_rawsize, thumb_rawfilemd5, thumb_filesize, and thumb_upload_param for implementations that set no_need_thumb: false and upload a thumbnail. The current plugin does not enter that branch.