> For the complete documentation index, see [llms.txt](https://wechaty.gitbook.io/wechaty/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wechaty.gitbook.io/wechaty/zh/api/wechaty.md).

# Wechaty

## 简介 <a href="#intro" id="intro"></a>

根据你选择的[Puppet](/wechaty/zh/puppet.md#intro)的不同，Bot 可能等于下面中的一个客户端，不同的[Puppet](/wechaty/zh/puppet.md#intro) 代表的我们对微信协议的不同实现方式, Puppet的英文意思是`傀儡`, 很形象的描述了我们希望Puppet做的事情：帮助 Wechaty 来控制微信的操作。

* 网页微信客户端, 当你选择: [puppet-puppeteer](https://github.com/chatie/wechaty-puppet-puppeteer)/[puppet-wechat4u](https://github.com/chatie/wechaty-puppet-wechat4u)​
* iPad 微信客户端, 当你选择: [puppet-padchat](https://github.com/lijiarui/wechaty-puppet-padchat)​

了解更多:

* [Wechaty 中的Puppet 是什么意思](/wechaty/zh/puppet.md#intro)

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

{% content-ref url="/pages/-Lv6eNQTxO1pWI0O0WKq" %}
[Message](/wechaty/zh/api/message.md)
{% endcontent-ref %}

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

{% content-ref url="/pages/-Lv6eNQUwx26sPnL7H0g" %}
[Contact](/wechaty/zh/api/contact.md)
{% endcontent-ref %}

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

{% content-ref url="/pages/-Lv6eNQWztp5I2rJ25HW" %}
[Room](/wechaty/zh/api/room.md)
{% endcontent-ref %}

## Wechaty <a href="#wechaty" id="wechaty"></a>

**Kind**: global class

* ​[Wechaty](/wechaty/zh/api/wechaty.md#Wechaty)​
  * ​[new Wechaty(\[options\])](/wechaty/zh/api/wechaty.md#new-wechaty-options)​
  * *instance*
    * ​[.on(event, listener)](/wechaty/zh/api/wechaty.md) ⇒ [`Wechaty`](/wechaty/zh/api/wechaty.md#wechaty-on-event-listener-wechaty)​
    * ​[.start()](/wechaty/zh/api/wechaty.md#wechaty-start-promise) ⇒ `Promise.`
    * ​[.stop()](/wechaty/zh/api/wechaty.md#wechaty-stop-promise) ⇒ `Promise.`
    * ​[.logout()](/wechaty/zh/api/wechaty.md#wechaty-logout-promise) ⇒ `Promise.`
    * ​[.logonoff()](/wechaty/zh/api/wechaty.md#wechaty-logonoff-boolean) ⇒ `boolean`
    * ​[.userSelf()](/wechaty/zh/api/wechaty.md#wechaty-userself-contactself) ⇒ `ContactSelf`
    * ​[.say(textOrContactOrFileOrUrl)](/wechaty/zh/api/wechaty.md#wechaty-say-textorcontactorfileorurl-promise) ⇒ `Promise.`
  * *static*
    * ​[.instance(\[options\])](/wechaty/zh/api/wechaty.md#wechaty-instance-options)​

### new Wechaty(\[options]) <a href="#new-wechaty-options" id="new-wechaty-options"></a>

创建一个 Wechaty 的实例，默认使用Web 的方式，切换到iPad 的方式，参数设置请查看[示例代码](https://github.com/lijiarui/wechaty-puppet-padchat#示例代码)

| Param      | Type                                                            | Default |
| ---------- | --------------------------------------------------------------- | ------- |
| \[options] | ​[`WechatyOptions`](/wechaty/zh/api/wechaty.md#wechatyoptions)​ | `{}`    |

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

```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'})` 的作用是一样的。 [查看详情](/wechaty/zh/faq.md#login-status-persistent).&#x20;

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

#### 使用iPad 版本的场景

* 当不使用web 版本的时候，需要定义你需要用什么样的方式接入，通过定义puppet名字的方式确定接入方式，这里是wechaty-puppet-padchat
* puppetOptions 在这里是用来传递[token](https://github.com/lijiarui/wechaty-puppet-padchat/wiki/购买token)的，按照下面代码示例传入即可。

```typescript
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`](/wechaty/zh/api/wechaty.md#Wechaty)​ <a href="#wechaty-on-event-listener-wechaty" id="wechaty-on-event-listener-wechaty"></a>

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

* **scan**: 当机器人需要扫码登录的时候，会触发这个事件，当手机扫码登录后，机器人就可以登录进去了。
* **login**: 当机器人登陆成功后，会触发这个事件。
* **logout**: 当机器人退出登陆的时候，会触发到这个事件。
* **message**: 当有新消息的时候会触发这个事件。

初次之外，wechaty还有一些群相关的事件，了解更多：[WechatyEventName](/wechaty/zh/api/wechaty.md#wechatyeventname)​

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

**Kind**: instance method of [`Wechaty`](/wechaty/zh/api/wechaty.md#wechaty)

**Returns**: [`Wechaty`](/wechaty/zh/api/wechaty.md#wechaty) - - this for chaining, see advanced [chaining usage](https://github.com/Chatie/wechaty-getting-started/wiki/FAQ-EN#36-why-wechatyonevent-listener-return-wechaty)​

| Param    | Type                                                                        | Description                 |
| -------- | --------------------------------------------------------------------------- | --------------------------- |
| event    | ​[`WechatyEventName`](/wechaty/zh/api/wechaty.md#wechatyeventname)​         | Emit WechatyEvent           |
| listener | ​[`WechatyEventFunction`](/wechaty/zh/api/wechaty.md#wechatyeventfunction)​ | Depends on the WechatyEvent |

**Example** *(Event:scan)*

```typescript
// 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 )*

```typescript
// Login Event will emit when bot login full successful.

​bot.on('login', (user) => {  console.log(`user ${user} login`)})
```

**Example** *(Event:logout )*

```typescript
// Logout Event will emit when bot detected log out.

​bot.on('logout', (user) => {  console.log(`user ${user} logout`)})
```

**Example** *(Event:message )*

```typescript
// Message Event will emit when there's a new message.

​wechaty.on('message', (message) => {  console.log(`message ${message} received`)})
```

**Example** *(Event:friendship )*

```typescript
// 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 )*

```typescript
// 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 )*

```typescript
// 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 )*

```typescript
// 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. )*

```typescript
// 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 )*

```typescript
// error Event will emit when there's an error occurred.

​bot.on('error', (error) => {  console.error(error)})
```

### wechaty.start() ⇒ `Promise.` <a href="#wechaty-start-promise" id="wechaty-start-promise"></a>

启动机器人

{% hint style="info" %}
机器人所有的操作必须在这个函数执行完成之后。
{% endhint %}

**Kind**: instance method of [`Wechaty`](/wechaty/zh/api/wechaty.md#wechaty) **Example**

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

### wechaty.stop() ⇒ `Promise.` <a href="#wechaty-stop-promise" id="wechaty-stop-promise"></a>

停止机器人

**Kind**: instance method of [`Wechaty`](/wechaty/zh/api/wechaty.md#Wechaty) **Example**

```typescript
await bot.stop()
```

### wechaty.logout() ⇒ `Promise.` <a href="#wechaty-logout-promise" id="wechaty-logout-promise"></a>

登出机器人

**Kind**: instance method of [`Wechaty`](/wechaty/zh/api/wechaty.md#wechaty) **Example**

```typescript
await bot.logout()
```

### wechaty.logonoff() ⇒ `boolean` <a href="#wechaty-logonoff-boolean" id="wechaty-logonoff-boolean"></a>

获取机器人logon/logoff 的状态

**Kind**: instance method of [`Wechaty`](/wechaty/zh/api/wechaty.md#wechaty) **Example**

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

### wechaty.userSelf() ⇒ `ContactSelf` <a href="#wechaty-userself-contactself" id="wechaty-userself-contactself"></a>

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

**Kind**: instance method of [`Wechaty`](/wechaty/zh/api/wechaty.md#wechaty) **Example**

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

### wechaty.say(textOrContactOrFileOrUrl) ⇒ `Promise.` <a href="#wechaty-say-textorcontactorfileorurl-promise" id="wechaty-say-textorcontactorfileorurl-promise"></a>

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

{% hint style="info" %}
这个函数是否能成功调用，取决于你使用了哪一种Puppet 的实现，了解更多：[Puppet 兼容性列表](/wechaty/zh/puppet.md#puppet-compatibility)
{% endhint %}

**Kind**: instance method of [`Wechaty`](/wechaty/zh/api/wechaty.md#wechaty)​

| Param | Type | Description |
| ----- | ---- | ----------- |

| textOrContactOrFileOrUrl | `string` \| `Contact` \| `FileBox` \| `UrlLink` | <p>发送文本、联系人名片或者文件给机器人自己。</p><p>你可以使用 <a href="https://www.npmjs.com/package/file-box">FileBox</a> 来发送文件</p> |
| ------------------------ | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |

// 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)

// 5. send Link to bot itself const linkPayload = new UrlLink({ description : 'WeChat Bot SDK for Individual Account, Powered by TypeScript, Docker, and Love', thumbnailUrl: '<https://avatars0.githubusercontent.com/u/25162437?s=200&v=4>', title : 'Welcome to Wechaty', url : '<https://github.com/chatie/wechaty>', }) await bot.say(linkPayload)

````
### 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/zh/api/wechaty.md#puppetmodulename)
* [WechatyOptions](/wechaty/zh/api/wechaty.md#wechatyoptions)&#x20;
* [WechatyEventName](/wechaty/zh/api/wechaty.md#wechatyeventname)
* [WechatyEventFunction](/wechaty/zh/api/wechaty.md#wechatyeventfunction)

### PuppetModuleName <a href="#puppetmodulename" id="puppetmodulename"></a>

**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 <a href="#wechatyoptions" id="wechatyoptions"></a>

创建wechaty 实例的可选参数类型。

**Kind**: global typedef **Properties**

|       名称      |                                      类型                                     | 描述                                                                                                                                                                                                                                                                                             |
| :-----------: | :-------------------------------------------------------------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|      name     |                                   `string`                                  | Wechaty 机器人的名称. 当你按照下面的方式设置的时候： `new Wechaty({name: 'wechatyName'})` 他会自动生成一个叫做`wechatyName.memory-card.json`的文件 。这个文件会存储机器人的登陆信息。如果这个文件有效，启动wechaty 的时候，你不需要扫码登陆就能自动登陆机器人（只对`wechaty-puppet-padchat`有效）。 这个名字在启动机器人的时候，是可以通过环境变量`WECHATY_NAME` 设置的，如：`WECHATY_NAME="wechatyName" node bot.js` |
|     puppet    | [PuppetModuleName](/wechaty/zh/api/wechaty.md#PuppetModuleName) \| `Puppet` | 使用puppet名称指定相关puppet或者直接传入puppet实例作为`Wechaty`底层插件， 了解更多[puppet](https://github.com/Chatie/wechaty/wiki/Puppet)信息                                                                                                                                                                               |
| puppetOptions |                               `PuppetOptions`                               | 指定puppet信息  `endpoint`: 指定puppet的底层服务器地址； `timeout`：指定watchDog的超时时间 `token`: 指定puppet的token                                                                                                                                                                                                    |

### WechatyEventName <a href="#wechatyeventname" id="wechatyeventname"></a>

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

|      名称     |    类型    | 描述                                                                                                     |
| :---------: | :------: | ------------------------------------------------------------------------------------------------------ |
|    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](/wechaty/zh/api/room-invitation.md)                              |
|     scan    | `string` | 当机器人需要扫码登陆的时候会触发这个事件。 建议你安装 `qrcode-terminal`(运行 `npm install qrcode-terminal`) 这个包，这样你可以在命令行中直接看到二维码。 |