Wechaty

Ship.Fail PreAngel

电梯演讲

Wechaty 是一款对话式 RPA SDK，能够简化聊天机器人的开发流程。它就像聊天机器人开发领域的瑞士军刀，为 WhatsApp、WeChat 等多种消息平台提供通用接口。使用 Wechaty，你只需编写一次机器人代码，便可在所有支持的平台上运行。这意味着你可以专注于打造引人入胜的对话体验，而无需担心各平台 API 的复杂性。Wechaty 是开源且易于使用的，并拥有一个充满活力的社区，随时准备帮助你将聊天机器人的创意变为现实。

连接聊天机器人

Wechaty 是面向聊天机器人开发者的 RPA（机器人流程自动化）SDK，可以帮助你用 6 行代码分别使用 JavaScript、Python、Go 和 Java 编写机器人，同时支持跨平台运行，包括 Linux、Windows、MacOS，以及 Docker。

:spider_web: https://wechaty.js.org
:octocat: https://github.com/Wechaty/wechaty
:beetle: https://github.com/Wechaty/wechaty/issues
:book: https://github.com/Wechaty/wechaty-getting-started
:whale: https://hub.docker.com/r/wechaty/wechaty

最新消息

• 重磅：绕过登录限制，wechaty 免费版 web 协议重放荣光, @gengchen528, 2021 年 4 月 13 日

开发者之声

"Wechaty 是一个很棒的解决方案；我相信会有更多用户认识到它的价值。" 链接
— @Gcaufy，腾讯工程师，WePY 的作者

"太好用，好用的想哭"
— @xinbenlv，Google 工程师，HaoShiYou.org 的创始人

”好用到哭“——你们对得起这个评价！ 链接
— @bigbrother666sh，《社长不见了》剧本杀 NPC DM 的创作者

"最好的微信开发库" 链接
— @Jarvis，百度工程师

"Wechaty 让运营人员有更多时间思考如何进行活动策划、留存用户，实现商业变现" 链接
— @lijiarui，Juzi.BOT 的创始人兼 CEO

"如果你懂 js ... 就试试 Wechaty 吧。它非常容易使用。"
— @Urinx Uri Lee，WeixinBot(Python) 的作者

"Wechaty 是一个很好的项目；我希望它能继续发展下去！因此，我成为了开放集体的贡献者。"
— @Simple

更多内容请参见 Wiki:开发者之声

加入我们的 Discord 社区

Wechaty 被成千上万的开发者用于众多聊天机器人项目中。若想与其他开发者交流，请扫描下方二维码，加入我们的 Wechaty 开发者社区。

立即扫描吧，因为其他 Wechaty 开发者也正期待与你交流呢！

资源

过去几年里，Wechaty 举办过许多技术分享会，并撰写了大量博客文章；以下是 Wechaty 的所有相关资源：

• :video_camera: YouTube 播放列表：观看所有与 Wechaty 相关的技术分享视频
• :page_with_curl: 完整文档
• :bulb: 博客：了解开发者如何使用 Wechaty 构建精彩项目！
• :beginner: Wechaty-Getting-Started：开箱即用的 Wechaty 入门项目模板
• :tada: Wechaty 贡献者列表：感谢他们的贡献！
• :gift: Juzibot 支持 Wechaty：全面了解 Wechaty

:rocket: 全世界最短的聊天机器人代码：仅 6 行 JavaScript

import { WechatyBuilder } from 'wechaty'

const wechaty = WechatyBuilder.build() // 获取一个 Wechaty 实例
wechaty
  .on('scan', (qrcode, status) => console.log(`扫描二维码登录：${status}\nhttps://wechaty.js.org/qrcode/${encodeURIComponent(qrcode)}`))
  .on('login',            user => console.log(`用户 ${user} 已登录`))
  .on('message',       message => console.log(`消息：${message}`))
wechaty.start()

注意：Wechaty 需要 Node.js 版本 >= 16

这个机器人在扫码登录后，会将所有消息记录到控制台。

你可以在 examples/ding-dong-bot.ts 找到 Wechaty 的官方示例，更多示例请参阅我们的 示例目录。

:checkered_flag: 系统要求

1. Node.js 版本 16 或更高
2. NPM 版本 7 或更高
3. TypeScript 版本 4.4 或更高

快速开始

• Wechaty 入门仓库 - https://github.com/wechaty/wechaty-getting-started

我们为初学者准备了一个设置最简单的 Wechaty 入门仓库。只需 clone、npm install 和 npm start，即可直接运行。

如果你是第一次接触 Wechaty 并希望尝试一下，强烈建议从这个仓库入手，并将其作为你项目的初始模板。

否则，请将上述“全世界最短的聊天机器人代码：6 行 JavaScript”示例保存为名为 bot.js 的文件，然后就可以使用 NPM 或 Docker 来运行它了。

1. NPM

npm init
npm install wechaty

# 创建你的第一个 bot.js 文件，可以复制粘贴上面的“全世界最短的聊天机器人代码：6 行 JavaScript”
# 然后：
node bot.js

2. Docker

• Wechaty Docker 入门仓库 - https://github.com/wechaty/docker-wechaty-getting-started

Wechaty Docker 同时支持 JavaScript 和 TypeScript。如果使用 TypeScript，只需以 .ts 为扩展名保存即可，无需编译，因为我们使用 ts-node 来运行。

2.1. 运行 JavaScript

# 对于 JavaScript
docker run -ti --rm --volume="$(pwd)":/bot wechaty/wechaty bot.js

2.2. 运行 TypeScript

# 对于 TypeScript
docker run -ti --rm --volume="$(pwd)":/bot wechaty/wechaty bot.ts

更多关于 Wechaty Docker 的信息，请参阅 Wiki:Docker。

3. 切换协议（木偶）

Wechaty 功能非常强大，可以在不同的协议上运行。您可以通过将环境变量 WECHATY_PUPPET 设置为不同的木偶提供者来指定协议。

如果您无法使用 Web 协议，可以按照这里的说明使用其他协议：https://github.com/wechaty/wechaty/wiki/Support-Developers 我们提供免费的令牌，以支持开发者构建有价值的微信聊天机器人。

目前我们支持以下 木偶提供者：

协议	木偶提供者	环境变量
Web	PuppetPuppeteer	export WECHATY_PUPPET=wechaty-puppet-puppeteer
Windows	PuppetWorkPro	export WECHATY_PUPPET=wechaty-puppet-service
Mock	PuppetMock	export WECHATY_PUPPET=wechaty-puppet-mock
Web	PuppetWechat4u	export WECHATY_PUPPET=wechaty-puppet-wechat4u
iPad	PuppetRock	export WECHATY_PUPPET=wechaty-puppet-service
iPad	PuppetPadLocal	export WECHATY_PUPPET=wechaty-puppet-service
Windows	PuppetDonut	export WECHATY_PUPPET=wechaty-puppet-service
iPad	PuppetPadpro 已弃用	export WECHATY_PUPPET=wechaty-puppet-padpro
iPad	PuppetPadchat 已弃用	export WECHATY_PUPPET=wechaty-puppet-padchat
iPad	PuppetPadplus 已弃用	export WECHATY_PUPPET=wechaty-puppet-padplus
Mac	PuppetMacpro 已弃用	export WECHATY_PUPPET=wechaty-puppet-macpro
Windows	PuppetWxwork 已弃用	export WECHATY_PUPPET=wechaty-puppet-service

更多关于 Wechaty 木偶的信息，请参阅木偶维基：

1. 木偶目录： https://github.com/Wechaty/wechaty-puppet/wiki/Directory
2. 木偶兼容性： https://github.com/Wechaty/wechaty-puppet/wiki/Compatibility

:guitar: API

完整的文档请参阅 Wechaty 官方 API 参考。

1 类 Wechaty

主机器人类。

一个 Bot 是一个 Wechaty 实例，用于控制特定的 wechaty-puppet。

• new Wechaty(options?: WechatyOptions)
  1. options.name?: string 此机器人的名称（可选）
  2. options.puppet?: string 选择要使用的木偶提供者。必须是以下之一：
     1. wechaty-puppet-wechat - 适用于 Web 微信的 Angular 钩子
     2. wechaty-puppet-wechat4u - 适用于 Web 微信的 HTTP API
     3. wechaty-puppet-padpro - iPad 应用协议
     4. wechaty-puppet-ioscat - iPhone 应用钩子
     5. wechaty-puppet-mock - 用于测试的模拟
  3. options.puppetOptions?: PuppetOptions 木偶提供者的选项。

Wechaty	API	描述
事件	login	机器人成功登录后触发
事件	logout	机器人登出后触发
事件	friendship	当有人向机器人发送好友请求时触发
事件	message	当有新消息时触发
事件	room-join	当有人加入任何聊天室时触发
事件	room-topic	当有人更改聊天室主题时触发
事件	room-leave	当有人离开聊天室时触发
事件	room-invite	当有聊天室邀请时触发
事件	scan	当机器人需要显示二维码供扫描时触发
方法	start(): Promise<void>	启动机器人
方法	stop(): Promise<void>	停止机器人
方法	logonoff(): boolean	返回机器人的登录状态
方法	logout(): Promise<void>	让机器人登出
方法	currentUser(): ContactSelf	获取当前登录的机器人联系人
方法	say(text: string): Promise<void>	让机器人对自己说 text

2 类 Contact

所有微信联系人（好友与非好友）都将被封装为一个 Contact 对象。

Contact	API	描述
静态	find(query: string): Promise<null | Contact>	根据姓名或备注查找联系人，若结果多于一个，则返回第一个。
静态	findAll(query: string): Promise<Contact[]>	根据 name 或 alias 查找联系人。
静态	load(query: string): Contact	根据 ID 获取联系人。
属性	id: readonly string	获取联系人的 ID。
方法	sync(): Promise<void>	强制重新加载联系人数据，从底层 API 再次同步数据。
方法	say(text: string): Promise<void | Message>	向联系人发送文本、联系人名片或文件，返回机器人发送的消息（仅 puppet-padplus 支持）。
方法	self(): boolean	检查联系人是否为自身。
方法	name(): string	获取联系人的姓名。
方法	alias(): Promise<string>	获取联系人的备注名。
方法	alias(newAlias: string): Promise<void>	设置或删除联系人的备注名。
方法	friend(): boolean	检查联系人是否为好友。
方法	type(): ContactType	返回联系人的类型。
方法	province(): string	获取联系人的省份信息。
方法	city(): string	获取联系人的城市信息。
方法	avatar(): Promise<FileBox>	获取联系人的头像图片流。
方法	gender(): ContactGender	获取联系人的性别。

2.1 类 ContactSelf

类 ContactSelf 继承自 Contact。

ContactSelf	API	描述
方法	avatar(file: FileBox): Promise<void>	设置机器人的头像。
方法	qrcode(): Promise<string>	获取机器人的二维码。
方法	signature(text: string): Promise<void>	设置机器人的个性签名。

2.2 类 Friendship

用于处理添加好友、接收好友请求及确认好友关系的事件。

Friendship	API	描述
静态	add(contact: Contact, hello?: string): Promise<void>	向联系人发送好友邀请。
方法	accept(): Promise<void>	接受好友请求。
方法	hello(): string	获取好友邀请中的问候语。
方法	contact(): Contact	获取好友关系中的联系人。
方法	type(): FriendshipType	返回好友关系类型（未知、已确认、已接收、验证中）。

3 类 Message

所有微信消息都将被封装为一个 Message 对象。

Message	API	描述
静态	find(query: string): Promise<null | Message>	在缓存中查找消息并返回第一个。
静态	findAll(query: string): Promise<Message[]>	在缓存中查找消息，返回消息列表。
方法	from(): Contact	获取消息的发送者。
方法	to(): Contact	获取消息的接收者。
方法	room(): null | Room	获取消息所在的群聊。（若消息不在群聊中，则返回 null）
方法	text(): string	获取消息的文本内容。
方法	say(text: string): Promise<void | Message>	向发送者回复文本、媒体文件或联系人消息，返回机器人发送的消息（仅 puppet-padplus 支持）。
方法	type(): MessageType	获取消息的类型。
方法	self(): boolean	判断消息是否由自身发送。
方法	mention(): Contact[]	获取消息中被提及的好友列表。
方法	mentionSelf(): boolean	判断消息是否提及了自身。
方法	forward(to: Contact): Promise<void>	转发接收到的消息。
方法	age(): number	消息创建以来的秒数。
方法	date(): Date	消息的创建时间。
方法	toFileBox(): Promise<FileBox>	从消息中提取媒体文件，并将其放入 FileBox 中。
方法	toContact(): Promise<Contact>	获取消息中的分享卡片。

4 类 Room

所有微信群（群聊）都将被封装为一个 Room 对象。

Room	API	描述
静态	create(contactList: Contact[], topic?: string): Promise<Room>	创建一个新的群聊
静态	find(query: string): Promise<null | Room>	根据条件查找一个群聊。如果找到多个，返回第一个。
静态	findAll(query: string): Promise<Room[]>	查找群聊中的所有成员
静态	load(query: string): Room	根据群聊 ID 加载群聊对象
属性	id: readonly string
事件	join	当有人加入任何群聊时触发
事件	topic	当有人更改群聊主题时触发
事件	leave	当有人离开群聊时触发
事件	invite	当收到群聊邀请时触发
方法	sync(): <Promise<void>	强制重新加载群聊数据，从底层 API 再次同步数据。
方法	say(text: string): Promise<void | Message>	在群聊中发送文本、媒体文件、联系人名片或包含 @提及联系人的消息，返回机器人发送的消息（仅 puppet-padplus 支持）。
方法	add(contact: Contact): Promise<void>	将联系人添加到群聊中
方法	del(contact: Contact): Promise<void>	从群聊中删除联系人
方法	quit(): Promise<void>	机器人自己退出群聊
方法	topic(): Promise<string>	获取群聊的主题
方法	topic(newTopic: string): Promise<void>	设置群聊的主题
方法	announce(text: string): Promise<void>	设置/获取群聊公告
方法	qrcode(): Promise<string>	获取群聊的二维码，可用于扫描加入群聊。
方法	alias(contact: Contact): Promise<string>	返回联系人在群聊中的昵称
方法	roomAlias(contact: Contact): Promise<string | null>	与 alias 方法功能相同
方法	has(contact: Contact): Promise<boolean>	检查群聊中是否包含指定联系人
方法	memberAll(query?: string): Promise<Contact[]>	查找群聊中的所有联系人，或具有特定名称的联系人
方法	member(query: string): Promise<null | Contact>	查找群聊中的联系人，如果找到多个，返回第一个。
方法	memberList():Promise<Contact[]>	获取群聊中的所有成员
方法	owner(): null | Contact	获取群聊的所有者

4.1 类 RoomInvitation

处理群聊邀请

RoomInvitation	API	描述
方法	accept(): Promise<void>	接受群聊邀请
方法	inviter(): Contact	获取群聊邀请的发送者
方法	roomTopic(): Promise<string>	获取群聊邀请中的群聊主题
方法	date(): Promise<Date>	邀请创建的时间
方法	age(): Promise<number>	邀请自创建以来的秒数

测试

Wechaty 通过单元测试和集成测试进行全面自动化测试，并支持持续集成与持续交付 (CI/CD)，由 Travis、Shippable 和 Appveyor 等 CI 工具提供支持。

要测试 Wechaty，请运行：

npm test

更多关于测试的信息，请参阅 Wiki:Tests。

创建 Wechaty 插件

创建并发布 Wechaty 插件非常简单。只需将你的模块暴露为一个接受单个参数 wechaty 的函数即可。当你的插件被 Wechaty 导入时，它会将自身作为参数传递进来，因此你可以自由地添加 Wechaty 支持的任何配置。

import { WechatyPlugin } from 'wechaty'

export default const MyPlugin: WechatyPlugin = (wechaty: Wechaty) => {
  // ...
}

config 的存在是为了让用户能够向你的插件传递自定义配置。在编写 Wechaty 插件文档时，你应该列出用户可以使用的配置选项。

更多信息请参见：

1. Wechaty 插件支持与 KickOut 示例 #1939
2. Wechaty 插件贡献库

:pencil: 发布说明

• 最新版本（所有版本 这里）
• 变更日志

:saxophone: 自 2019 年 2 月 15 日以来的浏览量

:sparkling_heart: 由 Wechaty 提供支持

:sparkles: Wechaty 徽章

[![Powered by Wechaty](https://img.shields.io/badge/Powered%20By-Wechaty-brightgreen.svg)](https://wechaty.js.org)

更多嵌入式 HTML/Markdown 代码，请参阅 Wiki:Badge。

:star2: Projects Using Wechaty

1. 一个用CNN深度神经网络给图片评分的wechaty项目
2. Relay between Telegram and WeChat
3. A chat bot managing the HaoShiYou wechat groups run by volunteers of haoshiyou.org
4. An interactive chat bot to manage a TODO list
5. Forward WeChat messages to telegram
6. koa与wechaty实现的微信小助手，可定时提醒与发消息设定定时任务
7. Wechaty Pay - 让线上没有难做的生意
8. 开源社的微信机器人项目

Pull Request is welcome to add yours!

Learn more about Projects Using Wechaty at Wiki:Projects Using Wechaty

:innocent: Find a Good Server

The best practice for running Wechaty Docker/NPM is using a VPS(Virtual Private Server) outside of China, which can save you hours of time because npm install and docker pull will run smoothly without any problem.

The following VPS providers are used by the Wechaty team, and they worked perfectly in production. You can use the following link to get one in minutes. Also, doing this can support Wechaty because you are referred by us.

Location	Price	Ram	Payment	Provider
Singapore	$5	512MB	Paypal	DigitalOcean
Japan	$5	1GB	Paypal	Linode
Korea	$10	1GB	Alipay, Paypal	Netdedi
Singapore	$3.5	512MB	Alipay, Wechat	Vultr

:notes: See Also

• RelatedProject

:poop: The Story

In 2017 ...

Huan's daily life/work depends on too much chat on wechat.

• Almost 14,000 wechat friends in May 2014, before wechat restricts a total number of friends to 5,000.
• Almost 400 wechat rooms, and most of them have more than 400 members.

Can you imagine that? He was dying...

So a tireless bot working for me 24x7 on wechat, monitoring/filtering the most important message is badly needed. For example, it highlights discussion which contains the KEYWORDS which he want to follow up(especially in a noisy room). ;-)

At last, It's built for huan's personal study purpose of Automatically Testing.

Stargazers over time

:two_hearts: Contributors

This project exists thanks to all the people who contribute. [Contribute].

---

:sunglasses: Backers

Thank you to all our backers! 🙏 [Become a backer]

:smirk: Sponsors

Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]

Multi-language Wechaty

• Wechaty - RPA SDK for Chatot Makers (TypeScript)
• Python Wechaty - RPA SDK for Chatbot Makers written in Python
• Go Wechaty - RPA SDK for Chatbot Makers written in Go
• Java Wechaty - RPA SDK for Chatbot Makers written in Java(Kotlin)
• Scala Wechaty - RPA SDK for Chatbot Makers written in Scala
• PHP Wechaty - RPA SDK for Chatbot Makers written in PHP
• .Net(C#) Wechaty - RPA SDK for Chatbot Makers written in .NET(C#)

History

main v1.11 (Nov 22, 2021)

Working on reduxify the Wechaty ecosystem for applying the CQRS pattern.

v1.10 (Nov 21, 2021)

Second beta release of Wechaty, with all ecosystem npm modules with version v1.10 (wechaty-puppet, wechaty-puppet-service, etc)

v1.0 (Sep 2021)

• Release v1.0 of Wechaty is the first beta release of Wechaty.

v0.69

1. v0.69: Supports ES Modules (with CJS dual support) (#2232)

v0.68 (Aug 27, 2021)

1. TLS support (#2231)
2. The latest CommonJS version

Creators

1. Huan (LinkedIn), 🐧 Tencent TVP of Chatbot・🤖 Chatie Architect・⭐️ GitHub Star・🚀 YC W19・🌐 Microsoft RD & AI MVP・🦾 Google ML GDE ・🤠 Serial Entrepreneur・🔥 Burner
2. Rui (李佳芮), Microsoft AI MVP & RD, Co-founder & CEO of Juzi.BOT (YC W19 Alumni)

Cite Wechaty

To cite this project in publications:

@misc{Wechaty,
  author = {Huan Li, Rui Li},
  title = {Wechaty: Conversational SDK for Chatbot Makers},
  year = {2016},
  publisher = {GitHub},
  journal = {GitHub Repository},
  howpublished = {\url{https://github.com/wechaty/wechaty}},
}

Copyright & License

• Code & Docs © 2016-now Huan, Rui, and Wechaty Community Contributors
• Code released under the Apache-2.0 License
• Docs released under Creative Commons

Wechaty 快速上手指南

Wechaty 是一个开源的聊天机器人 SDK，支持微信、WhatsApp 等多个平台。它允许开发者使用一套代码构建跨平台的聊天机器人，被誉为“聊天机器人界的瑞士军刀”。

1. 环境准备

在开始之前，请确保您的开发环境满足以下最低要求：

• Node.js: 版本 >= 16
• NPM: 版本 >= 7
• TypeScript: 版本 >= 4.4 (可选，若使用 TS 开发)
• 操作系统: Linux, Windows, MacOS 或 Docker 环境

国内开发者提示：建议配置 npm 镜像源以加速依赖安装。

npm config set registry https://registry.npmmirror.com

2. 安装步骤

您可以选择通过 NPM 直接安装，或使用 Docker 运行（无需本地安装 Node.js 环境）。

方式一：NPM 安装（推荐）

1. 初始化项目并安装 Wechaty：

   npm init -y
   npm install wechaty
   

2. 创建入口文件 bot.js，将下方的“基本使用”代码复制进去。

3. 运行机器人：

   node bot.js
   

方式二：Docker 运行

如果您已安装 Docker，可以直接拉取镜像运行，避免环境配置问题。

1. 创建入口文件 bot.js（内容见下方）。
2. 执行以下命令运行（支持挂载当前目录）：

   # 运行 JavaScript 文件
   docker run -ti --rm --volume="$(pwd)":/bot wechaty/wechaty bot.js
   
   # 若使用 TypeScript (文件名为 bot.ts)，命令如下
   # docker run -ti --rm --volume="$(pwd)":/bot wechaty/wechaty bot.ts
   

3. 基本使用

以下是“世界上最短的聊天机器人代码”，仅需 6 行即可实现扫码登录并监听消息。

新建文件 bot.js，填入以下内容：

import { WechatyBuilder } from 'wechaty'

const wechaty = WechatyBuilder.build() // 获取 Wechaty 实例
wechaty
  .on('scan', (qrcode, status) => console.log(`Scan QR Code to login: ${status}\nhttps://wechaty.js.org/qrcode/${encodeURIComponent(qrcode)}`))
  .on('login',            user => console.log(`User ${user} logged in`))
  .on('message',       message => console.log(`Message: ${message}`))
wechaty.start()

运行流程：

1. 执行启动命令后，控制台会输出一个二维码链接。
2. 访问该链接或直接扫描终端显示的二维码（取决于具体 Puppet 实现）进行微信登录。
3. 登录成功后，所有接收到的消息将会打印在控制台。

4. 切换协议 (Puppet)

Wechaty 支持通过环境变量切换不同的底层协议（Puppet），以适应不同的业务场景（如 Web 协议、Windows 协议等）。

在运行命令前设置 WECHATY_PUPPET 环境变量即可：

# 示例：指定使用 puppeteer (Web 协议)
export WECHATY_PUPPET=wechaty-puppet-puppeteer
node bot.js

注意：部分协议（如 Windows 协议）可能需要申请 Token 或特定环境支持。详细支持的协议列表请参考官方文档或开发者社区。