Main bot class.
All wechat rooms(groups) will be encapsulated as a Room.
Room is Sayable,
Example/Room-Bot
All wechat contacts(friend) will be encapsulated as a Contact.
Contact is Sayable,
Example/Contact-Bot
Send, receive friend request, and friend confirmation events.
All wechat messages will be encapsulated as a Message.
Message is Sayable,
Example/Ding-Dong-Bot
Meidia Type Message
Wechaty Class Event Type
Wechaty Class Event Function
Room Class Event Type
Room Class Event Function
The way to search member by Room.member()
The way to search Contact
Promise.<void>
* [.on(event, listener)](#Wechaty+on) ⇒ [Wechaty](#Wechaty)
* [.quit()](#Wechaty+quit) ⇒ Promise.<void>
* [.logout()](#Wechaty+logout) ⇒ Promise.<void>
* [.self()](#Wechaty+self) ⇒ [Contact](#Contact)
* [.say(content)](#Wechaty+say) ⇒ Promise.<boolean>
* _static_
* [.instance()](#Wechaty.instance)
* [.version([forceNpm])](#Wechaty.version) ⇒ string
### wechaty.init() ⇒ Promise.<void>
Initialize the bot, return Promise.
**Kind**: instance method of [Wechaty](#Wechaty)
**Example**
```js
await bot.init()
// do other stuff with bot here
```
### wechaty.on(event, listener) ⇒ [Wechaty](#Wechaty)
**Kind**: instance method of [Wechaty](#Wechaty)
**Returns**: [Wechaty](#Wechaty) - - this for chain
More Example Gist: [Example/Friend-Bot](https://github.com/wechaty/wechaty/blob/master/example/friend-bot.ts)
| Param | Type | Description |
| --- | --- | --- |
| event | [WechatyEventName](#WechatyEventName) | Emit WechatyEvent |
| listener | [WechatyEventFunction](#WechatyEventFunction) | Depends on the WechatyEvent |
**Example** *(Event:scan )*
```js
wechaty.on('scan', (url: string, code: number) => {
console.log(`[${code}] Scan ${url} to login.` )
})
```
**Example** *(Event:login )*
```js
bot.on('login', (user: Contact) => {
console.log(`user ${user} login`)
})
```
**Example** *(Event:logout )*
```js
bot.on('logout', (user: Contact) => {
console.log(`user ${user} logout`)
})
```
**Example** *(Event:message )*
```js
wechaty.on('message', (message: Message) => {
console.log(`message ${message} received`)
})
```
**Example** *(Event:friend )*
```js
bot.on('friend', (contact: Contact, request: FriendRequest) => {
if(request){ // 1. request to be friend from new contact
let result = await request.accept()
if(result){
console.log(`Request from ${contact.name()} is accept succesfully!`)
} else{
console.log(`Request from ${contact.name()} failed to accept!`)
}
} else { // 2. confirm friend ship
console.log(`new friendship confirmed with ${contact.name()}`)
}
})
```
**Example** *(Event:room-join )*
```js
bot.on('room-join', (room: Room, inviteeList: Contact[], inviter: Contact) => {
const nameList = inviteeList.map(c => c.name()).join(',')
console.log(`Room ${room.topic()} got new member ${nameList}, invited by ${inviter}`)
})
```
**Example** *(Event:room-leave )*
```js
bot.on('room-leave', (room: Room, leaverList: Contact[]) => {
const nameList = leaverList.map(c => c.name()).join(',')
console.log(`Room ${room.topic()} lost member ${nameList}`)
})
```
**Example** *(Event:room-topic )*
```js
bot.on('room-topic', (room: Room, topic: string, oldTopic: string, changer: Contact) => {
console.log(`Room ${room.topic()} topic changed from ${oldTopic} to ${topic} by ${changer.name()}`)
})
```
### wechaty.quit() ⇒ Promise.<void>
Quit the bot
**Kind**: instance method of [Wechaty](#Wechaty)
**Example**
```js
await bot.quit()
```
### wechaty.logout() ⇒ Promise.<void>
Logout the bot
**Kind**: instance method of [Wechaty](#Wechaty)
**Example**
```js
await bot.logout()
```
### wechaty.self() ⇒ [Contact](#Contact)
Get current user
**Kind**: instance method of [Wechaty](#Wechaty)
**Example**
```js
const contact = bot.self()
console.log(`Bot is ${contact.name()}`)
```
### wechaty.say(content) ⇒ Promise.<boolean>
Send message to filehelper
**Kind**: instance method of [Wechaty](#Wechaty)
| Param | Type |
| --- | --- |
| content | string |
### Wechaty.instance()
get the singleton instance of Wechaty
**Kind**: static method of [Wechaty](#Wechaty)
**Example** *(The World's Shortest ChatBot Code: 6 lines of JavaScript)*
```js
const { Wechaty } = require('wechaty')
Wechaty.instance() // Singleton
.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}`))
.init()
```
### Wechaty.version([forceNpm]) ⇒ string
Return version of Wechaty
**Kind**: static method of [Wechaty](#Wechaty)
**Returns**: string - - the version number
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| [forceNpm] | boolean | false | if set to true, will only return the version in package.json. otherwise will return git commit hash if .git exists. |
**Example**
```js
console.log(Wechaty.instance().version()) // return '#git[af39df]'
console.log(Wechaty.instance().version(true)) // return '0.7.9'
```
## Room
All wechat rooms(groups) will be encapsulated as a Room.
`Room` is `Sayable`,
[Example/Room-Bot](https://github.com/Chatie/wechaty/blob/master/example/room-bot.ts)
**Kind**: global class
* [Room](#Room)
* _instance_
* [.say(textOrMedia, [replyTo])](#Room+say) ⇒ Promise.<boolean>
* [.on(event, listener)](#Room+on) ⇒ this
* [.add(contact)](#Room+add) ⇒ Promise.<number>
* [.del(contact)](#Room+del) ⇒ Promise.<number>
* [.topic([newTopic])](#Room+topic) ⇒ string \| void
* [.alias(contact)](#Room+alias) ⇒ string \| null
* [.roomAlias(contact)](#Room+roomAlias) ⇒ string \| null
* [.has(contact)](#Room+has) ⇒ boolean
* [.memberAll(queryArg)](#Room+memberAll) ⇒ [Array.<Contact>](#Contact)
* [.member(queryArg)](#Room+member) ⇒ [Contact](#Contact) \| null
* [.memberList()](#Room+memberList) ⇒ [Array.<Contact>](#Contact)
* [.refresh()](#Room+refresh) ⇒ Promise.<void>
* _static_
* [.create(contactList, [topic])](#Room.create) ⇒ [Promise.<Room>](#Room)
* [.findAll([query])](#Room.findAll) ⇒ Promise.<Array.<Room>>
* [.find(query)](#Room.find) ⇒ Promise.<(Room\|null)>
### room.say(textOrMedia, [replyTo]) ⇒ Promise.<boolean>
Send message inside Room, if set [replyTo], wechaty will mention the contact as well.
**Kind**: instance method of [Room](#Room)
**Returns**: Promise.<boolean> - If bot send message successfully, it will return true. If the bot failed to send for blocking or any other reason, it will return false
| Param | Type | Description |
| --- | --- | --- |
| textOrMedia | string \| [MediaMessage](#MediaMessage) | Send `text` or `media file` inside Room. |
| [replyTo] | [Contact](#Contact) \| [Array.<Contact>](#Contact) | Optional parameter, send content inside Room, and mention @replyTo contact or contactList. |
**Example** *(Send text inside Room)*
```js
const room = await Room.find({name: 'wechaty'}) // change 'wechaty' to any of your room in wechat
await room.say('Hello world!')
```
**Example** *(Send media file inside Room)*
```js
const room = await Room.find({name: 'wechaty'}) // change 'wechaty' to any of your room in wechat
await room.say(new MediaMessage('/test.jpg')) // put the filePath you want to send here
```
**Example** *(Send text inside Room, and mention @replyTo contact)*
```js
const contact = await Contact.find({name: 'lijiarui'}) // change 'lijiarui' to any of the room member
const room = await Room.find({name: 'wechaty'}) // change 'wechaty' to any of your room in wechat
await room.say('Hello world!', contact)
```
### room.on(event, listener) ⇒ this
**Kind**: instance method of [Room](#Room)
**Returns**: this - - this for chain
| Param | Type | Description |
| --- | --- | --- |
| event | [RoomEventName](#RoomEventName) | Emit WechatyEvent |
| listener | [RoomEventFunction](#RoomEventFunction) | Depends on the WechatyEvent |
**Example** *(Event:join )*
```js
const room = await Room.find({topic: 'event-room'}) // change `event-room` to any room topic in your wechat
if (room) {
room.on('join', (room: Room, inviteeList: Contact[], inviter: Contact) => {
const nameList = inviteeList.map(c => c.name()).join(',')
console.log(`Room ${room.topic()} got new member ${nameList}, invited by ${inviter}`)
})
}
```
**Example** *(Event:leave )*
```js
const room = await Room.find({topic: 'event-room'}) // change `event-room` to any room topic in your wechat
if (room) {
room.on('leave', (room: Room, leaverList: Contact[]) => {
const nameList = leaverList.map(c => c.name()).join(',')
console.log(`Room ${room.topic()} lost member ${nameList}`)
})
}
```
**Example** *(Event:topic )*
```js
const room = await Room.find({topic: 'event-room'}) // change `event-room` to any room topic in your wechat
if (room) {
room.on('topic', (room: Room, topic: string, oldTopic: string, changer: Contact) => {
console.log(`Room ${room.topic()} topic changed from ${oldTopic} to ${topic} by ${changer.name()}`)
})
}
```
### room.add(contact) ⇒ Promise.<number>
Add contact in a room
**Kind**: instance method of [Room](#Room)
| Param | Type |
| --- | --- |
| contact | [Contact](#Contact) |
**Example**
```js
const contact = await Contact.find({name: 'lijiarui'}) // change 'lijiarui' to any contact in your wechat
const room = await Room.find({topic: 'wechat'}) // change 'wechat' to any room topic in your wechat
if (room) {
const result = await room.add(contact)
if (result) {
console.log(`add ${contact.name()} to ${room.topic()} successfully! `)
} else{
console.log(`failed to add ${contact.name()} to ${room.topic()}! `)
}
}
```
### room.del(contact) ⇒ Promise.<number>
Delete a contact from the room
It works only when the bot is the owner of the room
**Kind**: instance method of [Room](#Room)
| Param | Type |
| --- | --- |
| contact | [Contact](#Contact) |
**Example**
```js
const room = await Room.find({topic: 'wechat'}) // change 'wechat' to any room topic in your wechat
const contact = await Contact.find({name: 'lijiarui'}) // change 'lijiarui' to any room member in the room you just set
if (room) {
const result = await room.del(contact)
if (result) {
console.log(`remove ${contact.name()} from ${room.topic()} successfully! `)
} else{
console.log(`failed to remove ${contact.name()} from ${room.topic()}! `)
}
}
```
### room.topic([newTopic]) ⇒ string \| void
SET/GET topic from the room
**Kind**: instance method of [Room](#Room)
| Param | Type | Description |
| --- | --- | --- |
| [newTopic] | string | If set this para, it will change room topic. |
**Example** *(When you say anything in a room, it will get room topic. )*
```js
const bot = Wechaty.instance()
bot
.on('message', async m => {
const room = m.room()
if (room) {
const topic = room.topic()
console.log(`room topic is : ${topic}`)
}
})
```
**Example** *(When you say anything in a room, it will change room topic. )*
```js
const bot = Wechaty.instance()
bot
.on('message', async m => {
const room = m.room()
if (room) {
const oldTopic = room.topic()
room.topic('change topic to wechaty!')
console.log(`room topic change from ${oldTopic} to ${room.topic()}`)
}
})
```
### room.alias(contact) ⇒ string \| null
Return contact's roomAlias in the room, the same as roomAlias
**Kind**: instance method of [Room](#Room)
**Returns**: string \| null - - If a contact has an alias in room, return string, otherwise return null
| Param | Type |
| --- | --- |
| contact | [Contact](#Contact) |
**Example**
```js
const bot = Wechaty.instance()
bot
.on('message', async m => {
const room = m.room()
const contact = m.from()
if (room) {
const alias = room.alias(contact)
console.log(`${contact.name()} alias is ${alias}`)
}
})
```
### room.roomAlias(contact) ⇒ string \| null
Same as function alias
**Kind**: instance method of [Room](#Room)
| Param | Type |
| --- | --- |
| contact | [Contact](#Contact) |
### room.has(contact) ⇒ boolean
Check if the room has member `contact`.
**Kind**: instance method of [Room](#Room)
**Returns**: boolean - Return `true` if has contact, else return `false`.
| Param | Type |
| --- | --- |
| contact | [Contact](#Contact) |
**Example** *(Check whether 'lijiarui' is in the room 'wechaty')*
```js
const contact = await Contact.find({name: 'lijiarui'}) // change 'lijiarui' to any of contact in your wechat
const room = await Room.find({topic: 'wechaty'}) // change 'wechaty' to any of the room in your wechat
if (contact && room) {
if (room.has(contact)) {
console.log(`${contact.name()} is in the room ${room.topic()}!`)
} else {
console.log(`${contact.name()} is not in the room ${room.topic()} !`)
}
}
```
### room.memberAll(queryArg) ⇒ [Array.<Contact>](#Contact)
Find all contacts in a room
#### definition
- `name` the name-string set by user-self, should be called name, equal to `Contact.name()`
- `roomAlias` | `alias` the name-string set by user-self in the room, should be called roomAlias
- `contactAlias` the name-string set by bot for others, should be called alias, equal to `Contact.alias()`
**Kind**: instance method of [Room](#Room)
| Param | Type | Description |
| --- | --- | --- |
| queryArg | [MemberQueryFilter](#MemberQueryFilter) \| string | When use memberAll(name:string), return all matched members, including name, roomAlias, contactAlias |
### room.member(queryArg) ⇒ [Contact](#Contact) \| null
Find all contacts in a room, if get many, return the first one.
**Kind**: instance method of [Room](#Room)
| Param | Type | Description |
| --- | --- | --- |
| queryArg | [MemberQueryFilter](#MemberQueryFilter) \| string | When use member(name:string), return all matched members, including name, roomAlias, contactAlias |
**Example** *(Find member by name)*
```js
const room = await Room.find({topic: 'wechaty'}) // change 'wechaty' to any room name in your wechat
if (room) {
const member = room.member('lijiarui') // change 'lijiarui' to any room member in your wechat
if (member) {
console.log(`${room.topic()} got the member: ${member.name()}`)
} else {
console.log(`cannot get member in room: ${room.topic()}`)
}
}
```
**Example** *(Find member by MemberQueryFilter)*
```js
const room = await Room.find({topic: 'wechaty'}) // change 'wechaty' to any room name in your wechat
if (room) {
const member = room.member({name: 'lijiarui'}) // change 'lijiarui' to any room member in your wechat
if (member) {
console.log(`${room.topic()} got the member: ${member.name()}`)
} else {
console.log(`cannot get member in room: ${room.topic()}`)
}
}
```
### room.memberList() ⇒ [Array.<Contact>](#Contact)
Get all room member from the room
**Kind**: instance method of [Room](#Room)
### room.refresh() ⇒ Promise.<void>
Force reload data for Room
**Kind**: instance method of [Room](#Room)
### Room.create(contactList, [topic]) ⇒ [Promise.<Room>](#Room)
Create a new room.
**Kind**: static method of [Room](#Room)
| Param | Type |
| --- | --- |
| contactList | [Array.<Contact>](#Contact) |
| [topic] | string |
**Example** *(Creat a room with 'lijiarui' and 'juxiaomi', the room topic is 'ding - created')*
```js
const helperContactA = await Contact.find({ name: 'lijiarui' }) // change 'lijiarui' to any contact in your wechat
const helperContactB = await Contact.find({ name: 'juxiaomi' }) // change 'juxiaomi' to any contact in your wechat
const contactList = [helperContactA, helperContactB]
console.log('Bot', 'contactList: %s', contactList.join(','))
const room = await Room.create(contactList, 'ding')
console.log('Bot', 'createDingRoom() new ding room created: %s', room)
await room.topic('ding - created')
await room.say('ding - created')
```
### Room.findAll([query]) ⇒ Promise.<Array.<Room>>
Find room by topic, return all the matched room
**Kind**: static method of [Room](#Room)
| Param | Type |
| --- | --- |
| [query] | RoomQueryFilter |
**Example**
```js
const roomList = await Room.findAll() // get the room list of the bot
const roomList = await Room.findAll({name: 'wechaty'}) // find all of the rooms with name 'wechaty'
```
### Room.find(query) ⇒ Promise.<(Room\|null)>
Try to find a room by filter: {topic: string | RegExp}. If get many, return the first one.
**Kind**: static method of [Room](#Room)
**Returns**: Promise.<(Room\|null)> - If can find the room, return Room, or return null
| Param | Type |
| --- | --- |
| query | RoomQueryFilter |
## Contact
All wechat contacts(friend) will be encapsulated as a Contact.
`Contact` is `Sayable`,
[Example/Contact-Bot](https://github.com/Chatie/wechaty/blob/master/example/contact-bot.ts)
**Kind**: global class
* [Contact](#Contact)
* _instance_
* [.say(textOrMedia)](#Contact+say) ⇒ Promise.<boolean>
* [.name()](#Contact+name) ⇒ string
* [.alias(newAlias)](#Contact+alias) ⇒ string \| null \| Promise.<boolean>
* [.stranger()](#Contact+stranger) ⇒ boolean \| null
* [.official()](#Contact+official) ⇒ boolean \| null
* [.special()](#Contact+special) ⇒ boolean \| null
* [.personal()](#Contact+personal) ⇒ boolean \| null
* [.star()](#Contact+star) ⇒ boolean
* [.gender()](#Contact+gender) ⇒ Gender.Male(2) \| Gender.Female(1) \| Gender.Unknown(0)
* [.province()](#Contact+province) ⇒ string \| undefined
* [.city()](#Contact+city) ⇒ string \| undefined
* [.avatar()](#Contact+avatar) ⇒ Promise.<NodeJS.ReadableStream>
* [.refresh()](#Contact+refresh) ⇒ Promise.<this>
* [.self()](#Contact+self) ⇒ boolean
* _static_
* [.find(query)](#Contact.find) ⇒ Promise.<(Contact\|null)>
* [.findAll([queryArg])](#Contact.findAll) ⇒ Promise.<Array.<Contact>>
### contact.say(textOrMedia) ⇒ Promise.<boolean>
Send Text or Media File to Contact.
**Kind**: instance method of [Contact](#Contact)
| Param | Type |
| --- | --- |
| textOrMedia | string \| [MediaMessage](#MediaMessage) |
**Example**
```js
const contact = await Contact.find({name: 'lijiarui'}) // change 'lijiarui' to any of your contact name in wechat
await contact.say('welcome to wechaty!')
await contact.say(new MediaMessage(__dirname + '/wechaty.png') // put the filePath you want to send here
```
### contact.name() ⇒ string
Get the name from a contact
**Kind**: instance method of [Contact](#Contact)
**Example**
```js
const name = contact.name()
```
### contact.alias(newAlias) ⇒ string \| null \| Promise.<boolean>
GET / SET / DELETE the alias for a contact
Tests show it will failed if set alias too frequently(60 times in one minute).
**Kind**: instance method of [Contact](#Contact)
| Param | Type |
| --- | --- |
| newAlias | none \| string \| null |
**Example** *( GET the alias for a contact, return {(string | null)})*
```js
const alias = contact.alias()
if (alias === null) {
console.log('You have not yet set any alias for contact ' + contact.name())
} else {
console.log('You have already set an alias for contact ' + contact.name() + ':' + alias)
}
```
**Example** *(SET the alias for a contact)*
```js
const ret = await contact.alias('lijiarui')
if (ret) {
console.log(`change ${contact.name()}'s alias successfully!`)
} else {
console.log(`failed to change ${contact.name()} alias!`)
}
```
**Example** *(DELETE the alias for a contact)*
```js
const ret = await contact.alias(null)
if (ret) {
console.log(`delete ${contact.name()}'s alias successfully!`)
} else {
console.log(`failed to delete ${contact.name()}'s alias!`)
}
```
### contact.stranger() ⇒ boolean \| null
Check if contact is stranger
**Kind**: instance method of [Contact](#Contact)
**Returns**: boolean \| null - - True for not friend of the bot, False for friend of the bot, null for unknown.
**Example**
```js
const isStranger = contact.stranger()
```
### contact.official() ⇒ boolean \| null
Check if it's a offical account
**Kind**: instance method of [Contact](#Contact)
**Returns**: boolean \| null - - True for official account, Flase for contact is not a official account, null for unknown
**See**
- [webwxApp.js#L324](https://github.com/Chatie/webwx-app-tracker/blob/7c59d35c6ea0cff38426a4c5c912a086c4c512b2/formatted/webwxApp.js#L3243)
- [Urinx/WeixinBot/README](https://github.com/Urinx/WeixinBot/blob/master/README.md)
**Example**
```js
const isOfficial = contact.official()
```
### contact.special() ⇒ boolean \| null
Check if it's a special contact
The contact who's id in following list will be identify as a special contact
`weibo`, `qqmail`, `fmessage`, `tmessage`, `qmessage`, `qqsync`, `floatbottle`,
`lbsapp`, `shakeapp`, `medianote`, `qqfriend`, `readerapp`, `blogapp`, `facebookapp`,
`masssendapp`, `meishiapp`, `feedsapp`, `voip`, `blogappweixin`, `weixin`, `brandsessionholder`,
`weixinreminder`, `wxid_novlwrv3lqwv11`, `gh_22b87fa7cb3c`, `officialaccounts`, `notification_messages`,
**Kind**: instance method of [Contact](#Contact)
**Returns**: boolean \| null - True for brand, Flase for contact is not a brand
**See**
- [webwxApp.js#L3848](https://github.com/Chatie/webwx-app-tracker/blob/7c59d35c6ea0cff38426a4c5c912a086c4c512b2/formatted/webwxApp.js#L3848)
- [webwxApp.js#L3246](https://github.com/Chatie/webwx-app-tracker/blob/7c59d35c6ea0cff38426a4c5c912a086c4c512b2/formatted/webwxApp.js#L3246)
**Example**
```js
const isSpecial = contact.special()
```
### contact.personal() ⇒ boolean \| null
Check if it's a personal account
**Kind**: instance method of [Contact](#Contact)
**Returns**: boolean \| null - - True for personal account, Flase for contact is not a personal account
**Example**
```js
const isPersonal = contact.personal()
```
### contact.star() ⇒ boolean
Check if the contact is star contact.
**Kind**: instance method of [Contact](#Contact)
**Returns**: boolean - - True for star friend, False for no star friend.
**Example**
```js
const isStar = contact.star()
```
### contact.gender() ⇒ Gender.Male(2) \| Gender.Female(1) \| Gender.Unknown(0)
Contact gender
**Kind**: instance method of [Contact](#Contact)
**Example**
```js
const gender = contact.gender()
```
### contact.province() ⇒ string \| undefined
Get the region 'province' from a contact
**Kind**: instance method of [Contact](#Contact)
**Example**
```js
const province = contact.province()
```
### contact.city() ⇒ string \| undefined
Get the region 'city' from a contact
**Kind**: instance method of [Contact](#Contact)
**Example**
```js
const city = contact.city()
```
### contact.avatar() ⇒ Promise.<NodeJS.ReadableStream>
Get avatar picture file stream
**Kind**: instance method of [Contact](#Contact)
**Example**
```js
const avatarFileName = contact.name() + `.jpg`
const avatarReadStream = await contact.avatar()
const avatarWriteStream = createWriteStream(avatarFileName)
avatarReadStream.pipe(avatarWriteStream)
log.info('Bot', 'Contact: %s: %s with avatar file: %s', contact.weixin(), contact.name(), avatarFileName)
```
### contact.refresh() ⇒ Promise.<this>
Force reload data for Contact
**Kind**: instance method of [Contact](#Contact)
**Example**
```js
await contact.refresh()
```
### contact.self() ⇒ boolean
Check if contact is self
**Kind**: instance method of [Contact](#Contact)
**Returns**: boolean - True for contact is self, False for contact is others
**Example**
```js
const isSelf = contact.self()
```
### Contact.find(query) ⇒ Promise.<(Contact\|null)>
Try to find a contact by filter: {name: string | RegExp} / {alias: string | RegExp}
Find contact by name or alias, if the result more than one, return the first one.
**Kind**: static method of [Contact](#Contact)
**Returns**: Promise.<(Contact\|null)> - If can find the contact, return Contact, or return null
| Param | Type |
| --- | --- |
| query | [ContactQueryFilter](#ContactQueryFilter) |
**Example**
```js
const contactFindByName = await Contact.find({ name:"ruirui"} )
const contactFindByAlias = await Contact.find({ alias:"lijiarui"} )
```
### Contact.findAll([queryArg]) ⇒ Promise.<Array.<Contact>>
Find contact by `name` or `alias`
If use Contact.findAll() get the contact list of the bot.
#### definition
- `name` the name-string set by user-self, should be called name
- `alias` the name-string set by bot for others, should be called alias
**Kind**: static method of [Contact](#Contact)
| Param | Type |
| --- | --- |
| [queryArg] | [ContactQueryFilter](#ContactQueryFilter) |
**Example**
```js
const contactList = await Contact.findAll() // get the contact list of the bot
const contactList = await Contact.findAll({name: 'ruirui'}) // find allof the contacts whose name is 'ruirui'
const contactList = await Contact.findAll({alias: 'lijiarui'}) // find all of the contacts whose alias is 'lijiarui'
```
## FriendRequest
Send, receive friend request, and friend confirmation events.
1. send request
2. receive request(in friend event)
3. confirmation friendship(friend event)
[Example/Friend-Bot](https://github.com/Chatie/wechaty/blob/master/example/friend-bot.ts)
**Kind**: global class
* [FriendRequest](#FriendRequest)
* [.send(contact, [hello])](#FriendRequest+send) ⇒ Promise.<boolean>
* [.accept()](#FriendRequest+accept) ⇒ Promise.<boolean>
### friendRequest.send(contact, [hello]) ⇒ Promise.<boolean>
Send a new friend request
**Kind**: instance method of [FriendRequest](#FriendRequest)
**Returns**: Promise.<boolean> - Return a Promise, true for accept successful, false for failure.
| Param | Type | Default |
| --- | --- | --- |
| contact | [Contact](#Contact) | |
| [hello] | string | "'Hi'" |
**Example**
```js
const from = message.from()
const request = new FriendRequest()
request.send(from, 'hello~')
```
### friendRequest.accept() ⇒ Promise.<boolean>
Accept a friend request
**Kind**: instance method of [FriendRequest](#FriendRequest)
**Returns**: Promise.<boolean> - Return a Promise, true for accept successful, false for failure.
## Message
All wechat messages will be encapsulated as a Message.
`Message` is `Sayable`,
[Example/Ding-Dong-Bot](https://github.com/Chatie/wechaty/blob/master/example/ding-dong-bot.ts)
**Kind**: global class
* [Message](#Message)
* _instance_
* [.say(textOrMedia, [replyTo])](#Message+say) ⇒ Promise.<any>
* [.from()](#Message+from) ⇒ [Contact](#Contact)
* [.room()](#Message+room) ⇒ [Room](#Room) \| null
* [.content()](#Message+content) ⇒ string
* [.type()](#Message+type) ⇒ [MsgType](#MsgType)
* [.typeSub()](#Message+typeSub) ⇒ [MsgType](#MsgType)
* [.typeApp()](#Message+typeApp) ⇒ [AppMsgType](#AppMsgType)
* [.typeEx()](#Message+typeEx) ⇒ [MsgType](#MsgType)
* [.self()](#Message+self) ⇒ boolean
* [.mentioned()](#Message+mentioned) ⇒ [Array.<Contact>](#Contact)
* [.to()](#Message+to) ⇒ [Contact](#Contact) \| null
* [.readyStream()](#Message+readyStream) ⇒ Promise.<Readable>
* _static_
* [.find()](#Message.find)
* [.findAll()](#Message.findAll)
### message.say(textOrMedia, [replyTo]) ⇒ Promise.<any>
Reply a Text or Media File message to the sender.
**Kind**: instance method of [Message](#Message)
**See**: [Example/ding-dong-bot](https://github.com/Chatie/wechaty/blob/master/example/ding-dong-bot.ts)
| Param | Type |
| --- | --- |
| textOrMedia | string \| [MediaMessage](#MediaMessage) |
| [replyTo] | [Contact](#Contact) \| [Array.<Contact>](#Contact) |
**Example**
```js
const bot = Wechaty.instance()
bot
.on('message', async m => {
if (/^ding$/i.test(m.content())) {
await m.say('hello world')
console.log('Bot REPLY: hello world')
await m.say(new MediaMessage(__dirname + '/wechaty.png'))
console.log('Bot REPLY: Image')
}
})
```
### message.from() ⇒ [Contact](#Contact)
Get the sender from a message.
**Kind**: instance method of [Message](#Message)
### message.room() ⇒ [Room](#Room) \| null
Get the room from the message.
If the message is not in a room, then will return `null`
**Kind**: instance method of [Message](#Message)
### message.content() ⇒ string
Get the content of the message
**Kind**: instance method of [Message](#Message)
### message.type() ⇒ [MsgType](#MsgType)
Get the type from the message.
If type is equal to `MsgType.RECALLED`, [Message#id](Message#id) is the msgId of the recalled message.
**Kind**: instance method of [Message](#Message)
**See**: [MsgType](#MsgType)
### message.typeSub() ⇒ [MsgType](#MsgType)
Get the typeSub from the message.
If message is a location message: `m.type() === MsgType.TEXT && m.typeSub() === MsgType.LOCATION`
**Kind**: instance method of [Message](#Message)
**See**: [MsgType](#MsgType)
### message.typeApp() ⇒ [AppMsgType](#AppMsgType)
Get the typeApp from the message.
**Kind**: instance method of [Message](#Message)
**See**: [AppMsgType](#AppMsgType)
### message.typeEx() ⇒ [MsgType](#MsgType)
Get the typeEx from the message.
**Kind**: instance method of [Message](#Message)
### message.self() ⇒ boolean
Check if a message is sent by self.
**Kind**: instance method of [Message](#Message)
**Returns**: boolean - - Return `true` for send from self, `false` for send from others.
**Example**
```js
if (message.self()) {
console.log('this message is sent by myself!')
}
```
### message.mentioned() ⇒ [Array.<Contact>](#Contact)
Get message mentioned contactList.
Message event table as follows
| | Web | Mac PC Client | iOS Mobile | android Mobile |
| :--- | :--: | :----: | :---: | :---: |
| [You were mentioned] tip ([有人@我]的提示) | ✘ | √ | √ | √ |
| Identify magic code (8197) by copy & paste in mobile | ✘ | √ | √ | ✘ |
| Identify magic code (8197) by programming | ✘ | ✘ | ✘ | ✘ |
| Identify two contacts with the same roomAlias by [You were mentioned] tip | ✘ | ✘ | √ | √ |
**Kind**: instance method of [Message](#Message)
**Returns**: [Array.<Contact>](#Contact) - - Return message mentioned contactList
**Example**
```js
const contactList = message.mentioned()
console.log(contactList)
```
### message.to() ⇒ [Contact](#Contact) \| null
Get the destination of the message
Message.to() will return null if a message is in a room, use Message.room() to get the room.
**Kind**: instance method of [Message](#Message)
### message.readyStream() ⇒ Promise.<Readable>
Please notice that when we are running Wechaty,
if you use the browser that controlled by Wechaty to send attachment files,
you will get a zero sized file, because it is not an attachment from the network,
but a local data, which is not supported by Wechaty yet.
**Kind**: instance method of [Message](#Message)
### Message.find()
**Kind**: static method of [Message](#Message)
**Todo**
- [ ] add function
### Message.findAll()
**Kind**: static method of [Message](#Message)
**Todo**
- [ ] add function
## MediaMessage
Meidia Type Message
**Kind**: global class
* [MediaMessage](#MediaMessage)
* [.ext()](#MediaMessage+ext) ⇒ string
* [.filename()](#MediaMessage+filename) ⇒ string
* [.readyStream()](#MediaMessage+readyStream)
* [.forward(sendTo)](#MediaMessage+forward) ⇒ Promise.<boolean>
### mediaMessage.ext() ⇒ string
Get the MediaMessage file extension, etc: `jpg`, `gif`, `pdf`, `word` ..
**Kind**: instance method of [MediaMessage](#MediaMessage)
**Example**
```js
bot.on('message', async function (m) {
if (m instanceof MediaMessage) {
console.log('media message file name extention is: ' + m.ext())
}
})
```
### mediaMessage.filename() ⇒ string
Get the MediaMessage filename, etc: `how to build a chatbot.pdf`..
**Kind**: instance method of [MediaMessage](#MediaMessage)
**Example**
```js
bot.on('message', async function (m) {
if (m instanceof MediaMessage) {
console.log('media message file name is: ' + m.filename())
}
})
```
### mediaMessage.readyStream()
Get the read stream for attachment file
**Kind**: instance method of [MediaMessage](#MediaMessage)
### mediaMessage.forward(sendTo) ⇒ Promise.<boolean>
Forward the received message.
The types of messages that can be forwarded are as follows:
The return value of [type](#Message+type) matches one of the following types:
```json
MsgType {
TEXT = 1,
IMAGE = 3,
VIDEO = 43,
EMOTICON = 47,
LOCATION = 48,
APP = 49,
MICROVIDEO = 62,
}
```
When the return value of [type](#Message+type) is `MsgType.APP`, the return value of [typeApp](#Message+typeApp) matches one of the following types:
```json
AppMsgType {
TEXT = 1,
IMG = 2,
VIDEO = 4,
ATTACH = 6,
EMOJI = 8,
}
```
But, it should be noted that when forwarding ATTACH type message, if the file size is greater than 25Mb, the forwarding will fail.
The reason is that the server limits the forwarding of files above 25Mb. You need to download the file and use `new MediaMessage (file)` to send the file.
**Kind**: instance method of [MediaMessage](#MediaMessage)
| Param | Type | Description |
| --- | --- | --- |
| sendTo | [Room](#Room) \| [Contact](#Contact) | The recipient of the message, the room, or the contact |
## FriendRequest
**Kind**: global class
* [FriendRequest](#FriendRequest)
* [.send(contact, [hello])](#FriendRequest+send) ⇒ Promise.<boolean>
* [.accept()](#FriendRequest+accept) ⇒ Promise.<boolean>
### friendRequest.send(contact, [hello]) ⇒ Promise.<boolean>
Send a new friend request
**Kind**: instance method of [FriendRequest](#FriendRequest)
**Returns**: Promise.<boolean> - Return a Promise, true for accept successful, false for failure.
| Param | Type | Default |
| --- | --- | --- |
| contact | [Contact](#Contact) | |
| [hello] | string | "'Hi'" |
**Example**
```js
const from = message.from()
const request = new FriendRequest()
request.send(from, 'hello~')
```
### friendRequest.accept() ⇒ Promise.<boolean>
Accept a friend request
**Kind**: instance method of [FriendRequest](#FriendRequest)
**Returns**: Promise.<boolean> - Return a Promise, true for accept successful, false for failure.
## Gender : enum
Enum for Gender values.
**Kind**: global enum
**Properties**
| Name | Type | Description |
| --- | --- | --- |
| Unknown | number | 0 for Unknown |
| Male | number | 1 for Male |
| Female | number | 2 for Female |
## AppMsgType : enum
Enum for AppMsgType values.
**Kind**: global enum
**Properties**
| Name | Type | Description |
| --- | --- | --- |
| TEXT | number | AppMsgType.TEXT (1) for TEXT |
| IMG | number | AppMsgType.IMG (2) for IMG |
| AUDIO | number | AppMsgType.AUDIO (3) for AUDIO |
| VIDEO | number | AppMsgType.VIDEO (4) for VIDEO |
| URL | number | AppMsgType.URL (5) for URL |
| ATTACH | number | AppMsgType.ATTACH (6) for ATTACH |
| OPEN | number | AppMsgType.OPEN (7) for OPEN |
| EMOJI | number | AppMsgType.EMOJI (8) for EMOJI |
| VOICE_REMIND | number | AppMsgType.VOICE_REMIND (9) for VOICE_REMIND |
| SCAN_GOOD | number | AppMsgType.SCAN_GOOD (10) for SCAN_GOOD |
| GOOD | number | AppMsgType.GOOD (13) for GOOD |
| EMOTION | number | AppMsgType.EMOTION (15) for EMOTION |
| CARD_TICKET | number | AppMsgType.CARD_TICKET (16) for CARD_TICKET |
| REALTIME_SHARE_LOCATION | number | AppMsgType.REALTIME_SHARE_LOCATION (17) for REALTIME_SHARE_LOCATION |
| TRANSFERS | number | AppMsgType.TRANSFERS (2e3) for TRANSFERS |
| RED_ENVELOPES | number | AppMsgType.RED_ENVELOPES (2001) for RED_ENVELOPES |
| READER_TYPE | number | AppMsgType.READER_TYPE (100001) for READER_TYPE |
## MsgType : enum
Enum for MsgType values.
**Kind**: global enum
**Properties**
| Name | Type | Description |
| --- | --- | --- |
| TEXT | number | MsgType.TEXT (1) for TEXT |
| IMAGE | number | MsgType.IMAGE (3) for IMAGE |
| VOICE | number | MsgType.VOICE (34) for VOICE |
| VERIFYMSG | number | MsgType.VERIFYMSG (37) for VERIFYMSG |
| POSSIBLEFRIEND_MSG | number | MsgType.POSSIBLEFRIEND_MSG (40) for POSSIBLEFRIEND_MSG |
| SHARECARD | number | MsgType.SHARECARD (42) for SHARECARD |
| VIDEO | number | MsgType.VIDEO (43) for VIDEO |
| EMOTICON | number | MsgType.EMOTICON (47) for EMOTICON |
| LOCATION | number | MsgType.LOCATION (48) for LOCATION |
| APP | number | MsgType.APP (49) for APP |
| VOIPMSG | number | MsgType.VOIPMSG (50) for VOIPMSG |
| STATUSNOTIFY | number | MsgType.STATUSNOTIFY (51) for STATUSNOTIFY |
| VOIPNOTIFY | number | MsgType.VOIPNOTIFY (52) for VOIPNOTIFY |
| VOIPINVITE | number | MsgType.VOIPINVITE (53) for VOIPINVITE |
| MICROVIDEO | number | MsgType.MICROVIDEO (62) for MICROVIDEO |
| SYSNOTICE | number | MsgType.SYSNOTICE (9999) for SYSNOTICE |
| SYS | number | MsgType.SYS (10000) for SYS |
| RECALLED | number | MsgType.RECALLED (10002) for RECALLED |
## WechatyEventName
Wechaty Class Event Type
**Kind**: global typedef
**Properties**
| Name | Type | Description |
| --- | --- | --- |
| error | string | When the bot get error, there will be a Wechaty error event fired. |
| login | string | After the bot login full successful, the event login will be emitted, with a Contact of current logined user. |
| logout | string | Logout will be emitted when bot detected log out, with a Contact of the current login user. |
| scan | string | A scan event will be emitted when the bot needs to show you a QR Code for scanning. |
| heartbeat | string | Get bot's heartbeat. |
| friend | string | When someone sends you a friend request, there will be a Wechaty friend event fired. |
| message | string | Emit when there's a new message. |
| room-join | string | Emit when anyone join any room. |
| room-topic | string | Get topic event, emitted when someone change room topic. |
| room-leave | string | Emit when anyone leave the room.function | (this: Wechaty, error: Error) => void callback function |
| login | function | (this: Wechaty, user: Contact)=> void |
| logout | function | (this: Wechaty, user: Contact) => void |
| scan | function | (this: Wechaty, url: string, code: number) => void function | (this: Wechaty, data: any) => void |
| friend | function | (this: Wechaty, friend: Contact, request?: FriendRequest) => void |
| message | function | (this: Wechaty, message: Message) => void |
| room-join | function | (this: Wechaty, room: Room, inviteeList: Contact[], inviter: Contact) => void |
| room-topic | function | (this: Wechaty, room: Room, topic: string, oldTopic: string, changer: Contact) => void |
| room-leave | function | (this: Wechaty, room: Room, leaverList: Contact[]) => void |
## RoomEventName
Room Class Event Type
**Kind**: global typedef
**Properties**
| Name | Type | Description |
| --- | --- | --- |
| join | string | Emit when anyone join any room. |
| topic | string | Get topic event, emitted when someone change room topic. |
| leave | string | Emit when anyone leave the room.function | (this: Room, inviteeList: Contact[] , inviter: Contact) => void |
| room-topic | function | (this: Room, topic: string, oldTopic: string, changer: Contact) => void |
| room-leave | function | (this: Room, leaver: Contact) => void |
## MemberQueryFilter
The way to search member by Room.member()
**Kind**: global typedef
**Properties**
| Name | Type | Description |
| --- | --- | --- |
| name | string | Find the contact by wechat name in a room, equal to `Contact.name()`. |
| alias | string | Find the contact by alias set by the bot for others in a room, equal to `roomAlias`. |
| roomAlias | string | Find the contact by alias set by the bot for others in a room. |
| contactAlias | string | Find the contact by alias set by the contact out of a room, equal to `Contact.alias()`. [More Detail](https://github.com/Chatie/wechaty/issues/365) |
## ContactQueryFilter
The way to search Contact
**Kind**: global typedef
**Properties**
| Name | Type | Description |
| --- | --- | --- |
| name | string | The name-string set by user-self, should be called name |
| alias | string | The name-string set by bot for others, should be called alias [More Detail](https://github.com/Chatie/wechaty/issues/365) |