Wechaty

Last updated 3 months ago

一个Wechaty 代表着一个微信的客户端,他取决于你具体使用哪一个Puppet

简介

根据你选择的Puppet的不同,Bot 可能等于下面中的一个客户端,不同的Puppet 代表的我们对微信协议的不同实现方式, Puppet的英文意思是傀儡, 很形象的描述了我们希望Puppet做的事情:帮助 Wechaty 来控制微信的操作。

了解更多:

如果你希望先了解如何发送消息,点击下面

如果你希望先了解如何操作微信联系人,点击下面

如果你希望先了解如何操作微信群,点击下面

Wechaty

Kind: global class

new Wechaty([options])

创建一个 Wechaty 的实例,默认使用Web 的方式,切换到iPad 的方式,参数设置请查看示例代码

Param

Type

Default

[options]

WechatyOptions

{}

Example (The World's Shortest ChatBot Code: 6 lines of JavaScript)

const { Wechaty } = require('wechaty')
const bot = new Wechaty()
bot.on('scan', (qrcode, status) => console.log(['https://api.qrserver.com/v1/create-qr-code/?data=',encodeURIComponent(qrcode),'&size=220x220&margin=20',].join('')))
bot.on('login', user => console.log(`User ${user} logined`))
bot.on('message', message => console.log(`Message: ${message}`))
bot.start()

注意,`new Wechaty()` 是可以传参数的

使用网页版本的场景

  • 这里name 是用来存储登录信息的,和`Wechaty.instance({name: 'XX'})` 的作用是一样的。 查看详情.

const bot = new Wechaty({ name: 'your-bot-name' })

使用iPad 版本的场景

  • 当不使用web 版本的时候,需要定义你需要用什么样的方式接入,通过定义puppet名字的方式确定接入方式,这里是wechaty-puppet-padchat

  • puppetOptions 在这里是用来传递token的,按照下面代码示例传入即可。

const WECHATY_PUPPET_PADCHAT_TOKEN = 'your-token-here'
const puppet = 'wechaty-puppet-padchat' // 使用ipad 的方式接入。
const puppetOptions = {
token: WECHATY_PUPPET_PADCHAT_TOKEN,
}
const bot = new Wechaty({
name: 'your-bot-name'
puppet,
puppetOptions,
})
  • 上述的puppet 和 token 也可以不写进代码里面,通过环境变量来传递,如在命令行中运行:

WECHATY_PUPPET_PADCHAT_TOKEN=你的token WECHATY_PUPPET=padchat node bot.js

wechaty.on(event, listener) ⇒ Wechaty

当机器人收到消息,会触发一个事件,一些简单的事件介绍如下:

  • scan: 当机器人需要扫码登录的时候,会触发这个事件,当手机扫码登录后,机器人就可以登录进去了。

  • login: 当机器人登陆成功后,会触发这个事件。

  • logout: 当机器人退出登陆的时候,会触发到这个事件。

  • message: 当有新消息的时候会触发这个事件。

初次之外,wechaty还有一些群相关的事件,了解更多:WechatyEventName

你可以在这些时间的方法中自定义你希望的所有逻辑。​

Kind: instance method of Wechaty

Returns: Wechaty - - this for chaining, see advanced chaining usage

Param

Type

Description

event

WechatyEventName

Emit WechatyEvent

listener

WechatyEventFunction

Depends on the WechatyEvent

Example (Event:scan)

// Scan Event will emit when the bot needs to show you a QR Code for scanning​
bot.on('scan', (url, code) => { console.log(`[${code}] Scan ${url} to login.` )})

Example (Event:login )

// Login Event will emit when bot login full successful.
​bot.on('login', (user) => { console.log(`user ${user} login`)})

Example (Event:logout )

// Logout Event will emit when bot detected log out.
​bot.on('logout', (user) => { console.log(`user ${user} logout`)})

Example (Event:message )

// Message Event will emit when there's a new message.
​wechaty.on('message', (message) => { console.log(`message ${message} received`)})

Example (Event:friendship )

// Friendship Event will emit when got a new friend request, or friendship is confirmed.
​bot.on('friendship', (friendship) => {
if(friendship.type() === Friendship.Type.Receive){
// 1. receive new friendship request from new contact
const contact = friendship.contact()
let result = await friendship.accept()
if(result){
console.log(`Request from ${contact.name()} is accept succesfully!`)
} else {
console.log(`Request from ${contact.name()} failed to accept!`)
}
} else if (friendship.type() === Friendship.Type.Confirm) {
// 2. confirm friendship
console.log(`new friendship confirmed with ${contact.name()}`)
}
})

Example (Event:room-join )

// room-join Event will emit when someone join the room.
bot.on('room-join', (room, inviteeList, inviter) => {
const nameList = inviteeList.map(c => c.name()).join(',')
console.log(`Room ${room.topic()} got new member ${nameList}, invited by ${inviter}`)
})

Example (Event:room-leave )

// room-leave Event will emit when someone leave the room.​
bot.on('room-leave', (room, leaverList) => {
const nameList = leaverList.map(c => c.name()).join(',')
console.log(`Room ${room.topic()} lost member ${nameList}`)
})

Example (Event:room-topic )

// room-topic Event will emit when someone change the room's topic.
bot.on('room-topic', (room, topic, oldTopic, changer) => {
console.log(`Room ${room.topic()} topic changed from ${oldTopic} to ${topic} by ${changer.name()}`)
})

Example (Event:room-invite, RoomInvitation has been encapsulated as a RoomInvitation Class. )

// room-invite Event will emit when there's an room invitation.
​bot.on('room-invite', async roomInvitation => {
try {
console.log(`received room-invite event.`)
await roomInvitation.accept()
} catch (e) {
console.error(e)
}
}

Example (Event:error )

// error Event will emit when there's an error occurred.
​bot.on('error', (error) => { console.error(error)})

wechaty.start() ⇒ Promise.

启动机器人

机器人所有的操作必须在这个函数执行完成之后。

Kind: instance method of Wechaty Example

await bot.start() // do other stuff with bot here

wechaty.stop() ⇒ Promise.

停止机器人

Kind: instance method of Wechaty Example

await bot.stop()

wechaty.logout() ⇒ Promise.

登出机器人

Kind: instance method of Wechaty Example

await bot.logout()

wechaty.logonoff() ⇒ boolean

获取机器人logon/logoff 的状态

Kind: instance method of Wechaty Example

if (bot.logonoff()) {
console.log('Bot logined')
} else {
console.log('Bot not logined')
}

wechaty.userSelf() ⇒ ContactSelf

获取当前机器人的所有信息

Kind: instance method of Wechaty Example

const contact = bot.userSelf()
console.log(`Bot is ${contact.name()}`)

wechaty.say(textOrContactOrFileOrUrl) ⇒ Promise.

机器人自己给自己发消息。

这个函数是否能成功调用,取决于你使用了哪一种Puppet 的实现,了解更多:Puppet 兼容性列表

Kind: instance method of Wechaty

Param

Type

Description

textOrContactOrFileOrUrl

string | Contact | FileBox

发送文本、联系人名片或者文件给机器人自己。

你可以使用 FileBox 来发送文件

\`\`\`typescript // 1. send text to bot itself await bot.say\('hello!'\)​ // 2. send Contact to bot itself const contact = bot.Contact.load\('contactId'\) await bot.say\(contact\)​ // 3. send Image to bot itself from remote url import { FileBox } from 'file-box' const fileBox = FileBox.fromUrl\('https://chatie.io/wechaty/images/bot-qr-code.png'\) await bot.say\(fileBox\)​ // 4. send Image to bot itself from local file import { FileBox } from 'file-box' const fileBox = FileBox.fromFile\('/tmp/text.jpg'\) await bot.say\(fileBox\) \`\`\` \#\#\# Wechaty.instance\\(\\[options\\]\\) 获取全局的Wechaty 实例。 \*\*Kind\*\*: static method of \[\`Wechaty\`\]\(wechaty.md\#wechaty\)​ \| Param \| Type \| Default \| \| :--- \| :--- \| :--- \| \| \\[options\\] \| ​\[\`WechatyOptions\`\]\(wechaty.md\#wechatyoptions\)​ \| \`{}\` \| \*\*Example\*\* \_\\(The World's Shortest ChatBot Code: 6 lines of JavaScript\\)\_ \`\`\`typescript const { Wechaty } = require\('wechaty'\) ​Wechaty.instance\(\) // Global instance .on\('scan', \(url, code\) => console.log\(\`Scan QR Code to login: ${code}\n${url}\`\)\) .on\('login', user => console.log\(\`User ${user} logined\`\)\) .on\('message', message => console.log\(\`Message: ${message}\`\)\) .start\(\) \`\`\` \#\# 类型定义 \* \[PuppetModuleName\]\(wechaty.md\#puppetmodulename\) \* \[WechatyOptions\]\(wechaty.md\#wechatyoptions\) \* \[WechatyEventName\]\(wechaty.md\#wechatyeventname\) \* \[WechatyEventFunction\]\(wechaty.md\#wechatyeventfunction\) \#\#\# PuppetModuleName \*\*Kind\*\*: global typedef \*\*Properties\*\* PuppetModuleName 参数在这里代表着Puppet 的名称,类型是 string, 可能的取值为: \| Name \| Type \| Description \| \| :--- \| :--- \| :--- \| \| PUPPET\\_DEFAULT \| \`string\` \| 默认的puppet, 默认会使用 wechaty-puppet-puppeteer \| \| wechaty-puppet-wechat4u \| \`string\` \| 默认的puppet,使用 \[wechat4u\]\(https://github.com/nodeWechat/wechat4u\) 来控制 \[网页微信 API\]\(https://wx.qq.com/\) \| \| wechaty-puppet-padchat \| \`string\` \| 使用WebSocket 协议链接一个协议服务器,来控制iPad 微信。 \| \| wechaty-puppet-puppeteer \| \`string\` \| 通过chrome\\(谷歌\\)浏览器使用 \[google puppeteer\]\(https://github.com/GoogleChrome/puppeteer\) 来控制 \[网页微信 API\]\(https://wx.qq.com/\) \| \| wechaty-puppet-mock \| \`string\` \| 为单元测试提供模拟调用的Puppet \| \#\#\# WechatyOptions 创建wechaty 实例的可选参数类型。 \`\`\`typescript export interface WechatyOptions { memory? : MemoryCard, name? : string, // Wechaty Name profile? : null \| string, // DEPRECATED: use name instead puppet? : PuppetModuleName \| Puppet, // Puppet name or instance puppetOptions? : PuppetOptions, // Puppet TOKEN ioToken? : string, // Io TOKEN } \`\`\` \*\*Kind\*\*: global typedef \*\*Properties\*\*

Name

Type

Description

name

string

Wechaty 机器人的名称.

当你按照下面的方式设置的时候: new Wechaty({name: 'wechatyName'})

他会自动生成一个叫做wechatyName.memory-card.json的文件 。这个文件会存储机器人的登陆信息。如果这个文件有效,启动wechaty 的时候,你不需要扫码登陆就能自动登陆机器人。

这个名字在启动机器人的时候,是可以通过环境变量WECHATY_NAME 设置的,如:WECHATY_NAME="wechatyName" node bot.js

ioToken

string

Io TOKEN

Wechaty 事件的类型 \*\*Kind\*\*: global typedef \*\*Properties\*\*

Name

Type

Description

error

string

当机器人内部出错的时候会触发error 事件。

login

string

当机器人成功登陆后,会触发login 事件,并会在事件中传递当前登陆机器人的信息。

logout

string

当机器人检测到登出的时候,会触发logout 事件,并会在事件中传递机器人的信息。

heartbeat

string

获取机器人的心跳。

friendship

string

当有人给机器人发好友请求的时候会触发这个事件。

message

string

当机器人收到消息的时候会触发这个事件。

ready

string

当所有数据加载完成后,会触发这个事件。在wechaty-puppet-padchat 中,它意味着已经加载完成Contact 和Room 的信息。

room-join

string

当有人进入微信群的时候会触发这个事件。机器人主动进入某个微信群,t那个样会触发这个事件。

room-topic

string

当有人修改群名称的时候会触发这个事件。

room-leave

string

当机器人把群里某个用户移出群聊的时候会触发这个时间。用户主动退群是无法检测到的。

room-invite

string

当收到群邀请的时候,会触发这个事件。具体请看 RoomInvitation

scan

string

当机器人需要扫码登陆的时候会触发这个事件。

建议你安装 qrcode-terminal(运行 npm install qrcode-terminal) 这个包,这样你可以在命令行中直接看到二维码。