weixin-ts / bot/src / WeixinBot
Class: WeixinBot
Defined in: bot/src/bot.ts:71
High-level WeChat Bot client with automatic long-polling and event-driven message handling.
Example
const bot = new WeixinBot({ token: 'YOUR_TOKEN' })
bot.on('message', (msg) => {
// Handle incoming message
const text = msg.item_list?.find(i => i.type === 1)?.text_item?.text
if (text) {
bot.sendText({ to: msg.from_user_id!, text: `Echo: ${text}` })
}
})
bot.on('error', console.error)
bot.start()Extends
Constructors
Constructor
new WeixinBot(
options?):WeixinBot
Defined in: bot/src/bot.ts:89
Parameters
options?
Returns
WeixinBot
Overrides
Accessors
baseUrl
Get Signature
get baseUrl():
string
Defined in: bot/src/bot.ts:104
The API base URL being used
Returns
string
cdnBaseUrl
Get Signature
get cdnBaseUrl():
string
Defined in: bot/src/bot.ts:109
The CDN base URL being used
Returns
string
isLoggedIn
Get Signature
get isLoggedIn():
boolean
Defined in: bot/src/bot.ts:242
Check if the bot has a valid token (from constructor, login, or session).
Returns
boolean
isPolling
Get Signature
get isPolling():
boolean
Defined in: bot/src/bot.ts:99
Whether the bot is currently polling for messages
Returns
boolean
Methods
emit()
emit<
K>(event, ...args):void
Defined in: bot/src/events.ts:91
Emit an event, calling all registered listeners with the provided arguments.
Type Parameters
K
K extends "message" | "error" | "connected" | "disconnected" | "session:loaded" | "session:expired"
Parameters
event
K
The event name to emit
args
...BotEventMap[K] extends any[] ? any[any] : any[]
Arguments to pass to the listeners
Returns
void
Inherited from
getConfigForUser()
getConfigForUser(
userId,contextToken?):Promise<GetConfigResp>
Defined in: bot/src/bot.ts:474
Fetch bot configuration for a specific user. Useful for getting the typing ticket.
Parameters
userId
string
The iLink user ID
contextToken?
string
Optional context token
Returns
Promise<GetConfigResp>
getContextToken()
getContextToken(
userId):string|undefined
Defined in: bot/src/bot.ts:508
Get the cached context token for a user. Context tokens are automatically cached from incoming messages.
Parameters
userId
string
Returns
string | undefined
getUpdates()
getUpdates(
getUpdatesBuf?):Promise<WeixinMessage[]>
Defined in: bot/src/bot.ts:492
Manually call getUpdates for custom polling logic. Most users should use start() instead for automatic polling.
Parameters
getUpdatesBuf?
string
The context buffer from the previous response
Returns
Promise<WeixinMessage[]>
Array of new messages
login()
login(
callbacks?):Promise<LoginResult>
Defined in: bot/src/bot.ts:180
Login via QR code scanning.
This is the simplest way to authenticate. If session is configured, the token is automatically persisted for next time.
Parameters
callbacks?
Callbacks for QR display and status updates
Returns
Promise<LoginResult>
Login result with token and account info
Example
import { fileSession } from '@weixin-ts/bot/node'
const bot = new WeixinBot({ session: fileSession('.weixin-bot.session.json') })
await bot.login({
onQrCode: (url) => console.log('Scan:', url),
onScanned: () => console.log('Confirm in WeChat...'),
})
bot.start()off()
off<
K>(event,handler):this
Defined in: bot/src/events.ts:59
Remove an event listener.
Type Parameters
K
K extends "message" | "error" | "connected" | "disconnected" | "session:loaded" | "session:expired"
Parameters
event
K
The event name
handler
(...args) => void
The handler to remove
Returns
this
this for chaining
Inherited from
on()
on<
K>(event,handler):this
Defined in: bot/src/events.ts:42
Register an event listener.
Type Parameters
K
K extends "message" | "error" | "connected" | "disconnected" | "session:loaded" | "session:expired"
Parameters
event
K
The event name to listen for
handler
(...args) => void
The callback function
Returns
this
this for chaining
Inherited from
once()
once<
K>(event,handler):this
Defined in: bot/src/events.ts:77
Register a one-time event listener. The handler is automatically removed after the first invocation.
Type Parameters
K
K extends "message" | "error" | "connected" | "disconnected" | "session:loaded" | "session:expired"
Parameters
event
K
The event name
handler
(...args) => void
The callback function (called at most once)
Returns
this
this for chaining
Inherited from
removeAllListeners()
removeAllListeners<
K>(event?):this
Defined in: bot/src/events.ts:105
Remove all listeners for a specific event, or all listeners if no event is specified.
Type Parameters
K
K extends "message" | "error" | "connected" | "disconnected" | "session:loaded" | "session:expired"
Parameters
event?
K
Optional event name. If omitted, removes all listeners.
Returns
this
Inherited from
TypedEventEmitter.removeAllListeners
sendFile()
sendFile(
options):Promise<string>
Defined in: bot/src/bot.ts:324
Send a file attachment. Handles CDN upload and encryption automatically.
Parameters
options
Send media options (file as Uint8Array/ArrayBuffer, fileName recommended)
Returns
Promise<string>
The client-generated message ID
Example
await bot.sendFile({ to: 'user_id', file: pdfBuffer, fileName: 'report.pdf' })sendImage()
sendImage(
options):Promise<string>
Defined in: bot/src/bot.ts:299
Send an image message. Handles CDN upload and encryption automatically.
Parameters
options
Send media options (file as Uint8Array/ArrayBuffer)
Returns
Promise<string>
The client-generated message ID
Example
const imageBuffer = await fetch('https://example.com/photo.jpg').then(r => r.arrayBuffer())
await bot.sendImage({ to: 'user_id', file: new Uint8Array(imageBuffer) })sendText()
sendText(
options):Promise<string>
Defined in: bot/src/bot.ts:257
Send a text message to a user.
Parameters
options
Send text options
Returns
Promise<string>
The client-generated message ID
Example
await bot.sendText({ to: 'user_id', text: 'Hello!' })sendTyping()
sendTyping(
userId,status?):Promise<void>
Defined in: bot/src/bot.ts:439
Send a typing indicator to a user. Requires a valid typing ticket (fetched automatically via getConfig).
Parameters
userId
string
The user to show typing to
status?
2 | 1
Typing status (defaults to TYPING)
Returns
Promise<void>
Example
await bot.sendTyping('user_id')
// ... do work ...
await bot.sendTyping('user_id', TypingStatus.CANCEL)sendVideo()
sendVideo(
options):Promise<string>
Defined in: bot/src/bot.ts:309
Send a video message. Handles CDN upload and encryption automatically.
Parameters
options
Send media options (file as Uint8Array/ArrayBuffer)
Returns
Promise<string>
The client-generated message ID
start()
start():
void
Defined in: bot/src/bot.ts:121
Start long-polling for messages. Returns immediately — polling runs in the background. The bot will emit 'message' events for each incoming message and 'connected' once polling has started.
Returns
void
Throws
Error if already polling
stop()
stop():
void
Defined in: bot/src/bot.ts:152
Stop polling for messages. In-flight requests will be aborted gracefully.
Returns
void